Images Manual


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

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::SetPixelHandlerStruct destHandler = image.SetPixelHandler(rgbFormat, offset, maxon::ColorProfile(), flags) iferr_return;
// random number generator for random colors
// array to store RGB data of a single pixel
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
// 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.Close() iferr_return;
const char ** buffer
Definition: abstract.h:327
PyCompilerFlags * flags
Definition: ast.h:14
This class represents the number of bits in a pixel format.
Definition: gfx_image_bits.h:15
Definition: basearray.h:412
Definition: basearray.h:1326
Definition: basearray.h:1369
Definition: lib_math.h:19
FLOAT Get01()
Returns the next random value in the range of [0..1].
The TimeValue class encapsulates a timer value.
Definition: timevalue.h:33
PyObject * x
Definition: bytesobject.h:38
void Py_ssize_t * pos
Definition: dictobject.h:50
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:188
Float64 Float
Definition: apibase.h:197
unsigned char UChar
unsigned 8 bit character
Definition: apibase.h:185
Flags to control the SetPixelHandler functions.
Definition: gfx_image_pixelformat.h:66
Adds a subImage to a texture. Images are only allowed under Textures.
No options set.
unsigned long Py_ssize_t width
Definition: pycore_traceback.h:88
#define iferr_return
Definition: resultbase.h:1465
Several functions use this helper structure to pass the position within an image and number of pixels...
Definition: gfx_image_pixelhandler.h:18
Several functions use this helper structure to pass the image data to functions.
Definition: gfx_image_pixelformat.h:136
Definition: gfx_image_pixelhandler.h:134
MAXON_ATTRIBUTE_FORCE_INLINE Result< void > SetPixel(const ImagePos &pos, const PixelConstBuffer &buffer, SETPIXELFLAGS flags) const
Definition: gfx_image_pixelhandler.h:191


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

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

An image can have multiple channels / components:

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

// 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;
// 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();
// 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::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 };
[&data](maxon::Int i)
data[i] = 255 - data[i];
// 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;
Py_ssize_t i
Definition: abstract.h:645
const char * format
Definition: abstract.h:183
static auto Dynamic(FROMTYPE from, INDEXTYPE to, const LOOP &obj, Int threadCnt=PARALLELFOR_USEMAXIMUMTHREADS, const Int granularity=PARALLELFOR_DEFAULTGRANULARITY, JobQueueInterface *queue=JOBQUEUE_CURRENT) -> decltype(obj(to))
Definition: parallelfor.h:234
Py_ssize_t size
Definition: bytesobject.h:86
no options set.
Definition: gfx_image_pixelhandler.h:32
MAXON_ATTRIBUTE_FORCE_INLINE Result< void > GetPixel(const ImagePos &pos, const PixelMutableBuffer &buffer, GETPIXELFLAGS flags) const
Definition: gfx_image_pixelhandler.h:96


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

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;
// convert to JPG
const maxon::MediaOutputUrlRef jpg = maxon::ImageSaverClasses::Jpg().Create() iferr_return;
// define JPG settings
maxon::DataDictionary exportSettings;
image.Set(maxon::IMAGEPROPERTIES::IMAGE::EXPORTSETTINGS, exportSettings) iferr_return;
// save
image.Save(targetUrl, jpg, maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
Various qualities.
Definition: macros.h:23


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

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


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 functions to handle images:

Further Reading