Images Manual

Table of Contents

• About
• ImageBaseInterface
• ImageTextureInterface
• ImageInterface
• ImageLayerInterface
• Utility
• Further Reading

About

The MAXON API provides several interfaces to handle image data. All these interfaces are based on maxon::ImageBaseInterface:

• maxon::ImageBaseInterface: Base interface of all image interfaces that handles basic image properties.
• maxon::ImageTextureInterface: A texture object with layers. Used to load and save image files.
• maxon::ImageInterface: Represents a single image within a maxon::ImageTextureInterface.
• maxon::ImageLayerInterface: Represents a single layer within a maxon::ImageInterface.

Note

Typically these image classes represent uncompressed image data. But it is also possible that an image could store compressed or non-RGB data.

A maxon::ImageRef can be obtained from a BaseBitmap using BaseBitmap::GetImageRef(). See BaseBitmap Manual.

  // This example creates a new image and fills it with random RBG data.
  // The image is then stored in a PNG file.
 
  // create ImageRef implementation of ImageInterface
  const maxon::ImageRef image = maxon::ImageClasses::IMAGE().Create() iferr_return;
 
  // init image
  const maxon::PixelFormat rgbFormat = maxon::PixelFormats::RGB::U8();
  const auto storageType = maxon::ImagePixelStorageClasses::Normal();
  image.Init(width, height, storageType, rgbFormat) iferr_return;
 
  // get handler to fill image
  const maxon::ChannelOffsets&       offset = rgbFormat.GetChannelOffsets();
  const maxon::SETPIXELHANDLERFLAGS  flags  = maxon::SETPIXELHANDLERFLAGS::NONE;
  const maxon::SetPixelHandlerStruct destHandler = image.SetPixelHandler(rgbFormat, offset, maxon::ColorProfile(), flags) iferr_return;
 
  // random number generator for random colors
  maxon::LinearCongruentialRandom<maxon::Float32> random;
  random.Init(0);
 
  // array to store RGB data of a single pixel
  maxon::BaseArray<maxon::UChar> pixelArray;
  pixelArray.Resize(3) iferr_return;
 
  const maxon::BITS bitsPerPixel = rgbFormat.GetBitsPerPixel(); // size per pixel
 
  // for each pixel generate a random color and store it in the image
  for (maxon::Int y = 0; y < height; ++y)
  {
    for (maxon::Int x = 0; x < width; ++x)
    {
      auto GetRandomValue = [&random]() -> maxon::UChar
                            {
                              // get random value from 0 to 255
                              // use 255.9 to make sure all values have equal probability
                              const maxon::Float randomValue = random.Get01() * 255.9;
                              return maxon::SafeConvert<maxon::UChar>(randomValue);
                            };
 
      // create random RGB data
      pixelArray[0] = GetRandomValue();
      pixelArray[1] = GetRandomValue();
      pixelArray[2] = GetRandomValue();
 
      // prepare data
      maxon::UChar* data = pixelArray.GetFirst();
      const maxon::PixelMutableBuffer buffer(data, bitsPerPixel); // pixel data
 
      // set pixel data
      const maxon::ImagePos pos { x, y, 1 };  // pixel position and count
      destHandler.SetPixel(pos, buffer, maxon::SETPIXELFLAGS::NONE) iferr_return;
    }
  }
 
  // save image data to file
 
  // create MediaOutputUrlRef from maxon::ImageSaverClasses::Png published object.
  const maxon::MediaOutputUrlRef png = maxon::ImageSaverClasses::Png().Create() iferr_return;
  // prepare MediaSession
  maxon::MediaSessionRef session;
 
  // prepare ImageTextureRef
  const maxon::ImageTextureRef textureRef = maxon::ImageTextureClasses::TEXTURE().Create() iferr_return;
  // add the prepared ImageRef as a child
  textureRef.AddChildren(maxon::IMAGEHIERARCHY::IMAGE, image, maxon::ImageBaseRef()) iferr_return;
  // save to target URL as PNG using the given MediaSession
  textureRef.Save(target, png, maxon::MEDIASESSIONFLAGS::NONE, &session) iferr_return;
 
  // use MediaSession save the image to a file
  session.Convert(maxon::TimeValue(), maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
  session.Close() iferr_return;

ImageBaseInterface

maxon::ImageBaseInterface is the base interface of all image interfaces.

• maxon::ImageBaseInterface::InitBase(): Initializes the bitmap with a given size/height. See maxon::PixelFormats.
• maxon::ImageBaseInterface::AddChildren(): Adds a child image.

An image typically stores bitmap data. This data is accessed with:

• maxon::ImageBaseInterface::GetWidth(): Returns the bitmap width.
• maxon::ImageBaseInterface::GetHeight(): Returns the bitmap height.
• maxon::ImageBaseInterface::GetPixelFormat(): Returns the pixel format. See maxon::PixelFormat.
• maxon::ImageBaseInterface::GetPixelHandler(): Returns a handler to read bitmap data from the image. See maxon::GetPixelHandlerStruct.
• maxon::ImageBaseInterface::SetPixelHandler(): Returns a handler to write bitmap data into the image. See maxon::SetPixelHandlerStruct.
• maxon::ImageBaseInterface::CreateSubImagePart(): Creates a new image referencing a part of the bitmap.

An image can have multiple channels / components:

• maxon::ImageBaseInterface::GetChannelCount(): Returns the number of channels.
• maxon::ImageBaseInterface::GetComponent(): Reads bitmap data from the given component.
• maxon::ImageBaseInterface::SetComponent(): Writes bitmap data into the given component.

Changes to the image can be detected with this observable:

• ObservableRegionChanged: Is fired as soon as anybody modifies the pixel data.

maxon::ImageBaseInterface is based on

• maxon::HierarchyObjectInterface: Allows to add child images e.g. layers.
• maxon::DataDictionaryInterface: Allows to store arbitrary data.

  // This example loads an image file, inverts the RGB data and saves it to a new image file.
 
  // load image
  const maxon::ImageTextureRef sourceImage = maxon::ImageTextureClasses::TEXTURE().Create() iferr_return;
  sourceImage.Load(sourceUrl, maxon::TimeValue(), maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
 
  // read data
  const maxon::PixelFormat format = maxon::PixelFormats::RGB::U8();
  const auto offset = format.GetChannelOffsets();
  const maxon::GetPixelHandlerStruct read = sourceImage.GetPixelHandler(format, offset, maxon::ColorProfile(), maxon::GETPIXELHANDLERFLAGS::NONE, nullptr) iferr_return;
 
  const maxon::Int width  = sourceImage.GetWidth();
  const maxon::Int height = sourceImage.GetHeight();
 
  // prepare buffer
  const maxon::Int size = width * format.GetChannelCount();
  maxon::BaseArray<maxon::UChar> data;
  data.Resize(size) iferr_return;
 
  // load data into buffer
  const maxon::BITS bitsPerPixel = format.GetBitsPerPixel();              // size per pixel
  const maxon::PixelMutableBuffer buffer(data.GetFirst(), bitsPerPixel);  // pixel data
 
  // store in Image
  // create ImageRef implementation of ImageInterface
  const maxon::ImageRef invertedImage = maxon::ImageClasses::IMAGE().Create() iferr_return;
 
  // init image
  const auto storageType = maxon::ImagePixelStorageClasses::Normal();
  invertedImage.Init(width, height, storageType, format) iferr_return;
 
  // get handler to fill image
  const maxon::ColorProfile          colorProfile { };
  const maxon::SETPIXELHANDLERFLAGS  handlerFlags = maxon::SETPIXELHANDLERFLAGS::NONE;
  const maxon::SetPixelHandlerStruct destHandler  = invertedImage.SetPixelHandler(format, offset, colorProfile, handlerFlags) iferr_return;
 
  // loop through each line
  // invert each component
  for (maxon::Int y = 0; y < height; ++y)
  {
    const maxon::ImagePos pos { 0, y, width };
    read.GetPixel(pos, buffer, maxon::GETPIXELFLAGS::NONE) iferr_return;
 
    maxon::ParallelFor::Dynamic(0, size,
      [&data](maxon::Int i)
      {
        data[i] = 255 - data[i];
      });
 
    destHandler.SetPixel(pos, buffer, maxon::SETPIXELFLAGS::NONE) iferr_return;
  }
 
  // save to file
  const maxon::ImageTextureRef targetImage = maxon::ImageTextureClasses::TEXTURE().Create() iferr_return;
  targetImage.AddChildren(maxon::IMAGEHIERARCHY::IMAGE, invertedImage, maxon::ImageBaseRef()) iferr_return;
 
  const maxon::MediaOutputUrlRef png = maxon::ImageSaverClasses::Png().Create() iferr_return;
  targetImage.Save(targetUrl, png, maxon::MEDIASESSIONFLAGS::NONE) iferr_return;

ImageTextureInterface

maxon::ImageTextureInterface represents a texture object with one or multiple images and layers.

• maxon::ImageTextureInterface::Load(): Loads the image data from the given URL.
• maxon::ImageTextureInterface::Save(): Saves the image data to the given MediaOutputRef or maxon::Url. See Media Outputs.
• maxon::ImageTextureInterface::LoadTexture(): Creates a new image from the given URL.

The namespace maxon::ImageTextureClasses contains published objects with implementations of maxon::ImageTextureInterface. The default implementation is maxon::ImageTextureClasses::TEXTURE in gfx_image.h.

  // This example loads an image file into a ImageTextureRef
  // and saves the image data to a new JPG file.
 
  // load image file
  const maxon::ImageTextureRef image = maxon::ImageTextureClasses::TEXTURE().Create() iferr_return;
  image.Load(sourceUrl, maxon::TimeValue(), maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
 
  // convert to JPG
  const maxon::MediaOutputUrlRef jpg = maxon::ImageSaverClasses::Jpg().Create() iferr_return;
 
  // define JPG settings
  maxon::DataDictionary exportSettings;
  exportSettings.Set(maxon::MEDIASESSION::EXPORT::QUALITY, 0.8_f) iferr_return;
  image.Set(maxon::IMAGEPROPERTIES::IMAGE::EXPORTSETTINGS, exportSettings) iferr_return;
 
  // save
  image.Save(targetUrl, jpg, maxon::MEDIASESSIONFLAGS::NONE) iferr_return;

ImageInterface

maxon::ImageInterface represents a single image of a maxon::ImageTextureInterface.

• maxon::ImageInterface::Init(): Initializes the pixel storage.

The namespace maxon::ImageClasses contains published objects with implementations of maxon::ImageInterface. The default implementation is maxon::ImageClasses::IMAGE in gfx_image.h.

ImageLayerInterface

maxon::ImageLayerInterface represents a single layer within a maxon::ImageInterface. The namespace maxon::ImageLayerClasses contains published objects with implementations of maxon::ImageLayerInterface. The default implementation is maxon::ImageLayerClasses::RASTER in gfx_image.h.

Utility

Utility functions to handle images:

• maxon::GetImageOf(): Returns the first image of the given texture.
• maxon::GetFirstAlphaOf(): Returns the alpha channel of the given texture.

Further Reading

• Files & Media
• MAXON API Files & Media
• Media Sessions Manual
• Url Manual