c4d.bitmaps.BaseBitmap

The bitmap class can be used to load, read, draw and save bitmap pictures of various formats. Be sure to call BaseBitmap.Init() before you attempt to use a newly allocated bitmap.

Note

Bitmaps are organized so that x = y = 0 is the top left corner.

Note

Though the bitmap class can work with other bit depths than 24 and 32, please note that only these function support other bit depths: BaseBitmap.GetBw(), BaseBitmap.GetBh(), BaseBitmap.GetBt(), BaseBitmap.GetBpz(), BaseBitmap.Init(), BaseBitmap.GetPixelCnt(), BaseBitmap.SetPixelCnt(), BaseBitmap.SetCMAP(), BaseBitmap.AddChannel(), BaseBitmap.RemoveChannel(), BaseBitmap.GetAlphaPixel(), BaseBitmap.SetAlphaPixel(), BaseBitmap.GetChannelCount(), BaseBitmap.GetChannelNum() (to use higher bit depths or multiple channels, see MultipassBitmap).

See also

Copy32BitImage.py for an example showing how to copy the internal data of an image to a new one.

Inheritance

Members

BaseBitmap.__init__()
Return type: BaseBitmap
Returns: The new bitmap.
BaseBitmap.__getitem__(key)

This is similar to GetPixel(). An example:

x, y, z = bmp[5, 5] #returns the color of a pixel at position x(5), y(5)
Raises IndexError:
  If the pixel position is out of the bitmap boundaries. See GetSize(), GetBw() and GetBh().
Parameters: key (int) – The pixel position.
Return type: list of int
Returns: The color of a pixel. Range between 0-255.
BaseBitmap.__setitem__(key, value)

This is similar to GetPixel(). An example:

bmp[5, 5] = (50, 255, 50) #returns the color of a pixel at position x(5), y(5)
Raises IndexError:
 

If the pixel position is out of the bitmap boundaries. See GetSize(), GetBw() and GetBh().

Parameters:
  • key (int) – The pixel position.
  • value (list of int) – The color of the pixel. Range between 0-255.
BaseBitmap.__eq__(self, other)
BaseBitmap.__ne__(self, other)

Check if two different objects point to the same bitmap.

Note

Does not compare if two different objects are equal.

BaseBitmap.SetPixel(x, y, r, g, b)

Sets the pixel at (x, y) to the color specified by (r,g,b) (0 . Similar to the __setitem__().

Note

Currently this method does no range check of x and y. This might be added in the future. Please do the check on your own.

Parameters:
  • x (int) – The X coordinate.
  • y (int) – The Y coordinate.
  • r (int) – The red component.
  • g (int) – The green component.
  • b (int) – The blue component.
Return type:

bool

Returns:

True if successful, otherwise False.

BaseBitmap.GetPixel(x, y)

Retrieves the color at (x,y) and assigns it to the passed pointers (r,g,b) (0 ). Similar to the __getitem__().

Note

Currently this method does no range check of x and y. This might be added in the future. Please do the check on your own.

Parameters:
  • x (int) – The X coordinate.
  • y (int) – The Y coordinate.
  • r (int) – The red component.
  • g (int) – The green component.
  • b (int) – The blue component.
Return type:

list of int

Returns:

The color of the pixel. Range between 0-255.

BaseBitmap.GetPixelCnt(x, y, cnt, buffer, inc, dstmode, flags)

Reads cnt pixels from x/y in the bitmap to the buffer with mode dstmode, incrementing inc bytes for each pixel.

Parameters:
  • x (int) – X coordinate of the first pixel to set.
  • y (int) – Y coordinate of the first pixel to set.
  • cnt (int) – Number of pixels to set.
  • buffer – Should point to a large enough memory buffer containing the pixels to set.
  • inc (int) – The byte increment per pixel in the buffer.
  • dstmode (int) –

    The destination mode:

    COLORMODE_ALPHA Only 8-bit alpha channel.
    COLORMODE_GRAY8 8-bit greyscale channel.
    COLORMODE_AGRAY 8-bit greyscale channel with 8-bit alpha.
    COLORMODE_RGB 8-bit RGB channels.
    COLORMODE_ARGB 8-bit RGB channels with 8-bit alpha.
    COLORMODE_CMYK 8-bit CMYK channel.
    COLORMODE_ACMYK 8-bit CMYK channel with 8-bit alpha.
    COLORMODE_MASK 8-bit greymap as mask.
    COLORMODE_AMASK 8-bit greymap as mask with 8-bit alpha.
    COLORMODE_ILLEGAL Private.
    COLORMODE_GRAYw 8-bit greymap as mask with 8-bit alpha.
    COLORMODE_AGRAYw 16-bit greyscale channel with 16-bit alpha.
    COLORMODE_RGBw 16-bit RGB channels.
    COLORMODE_ARGBw 16-bit RGB channels with 16-bit alpha.
    COLORMODE_MASKw 16-bit greymap as mask with 16-bit alpha.
    COLORMODE_ILLEGALf Private.
    COLORMODE_GRAYf Floating point greyscale channel.
    COLORMODE_AGRAYf Floating point greyscale channel with floating point alpha.
    COLORMODE_RGBf Floating point RGB channels.
    COLORMODE_ARGBf Floating point RGB channels with floating point alpha.
    COLORMODE_MASKf Floating point greymap with floating point alpha.
  • flags (int) –

    Flags:

    PIXELCNT_0 None.
    PIXELCNT_APPLYALPHA Apply alpha channel.
    PIXELCNT_B3DLAYERS Merge B3D layers (MultipassBitmap)
    PIXELCNT_DITHERING Allow dithering.
    PIXELCNT_INTERNAL_ALPHAVALUE Private.
    PIXELCNT_INTERNAL_SETLINE Private.
Return type:

bool

Returns:

True if successful, otherwise False.

BaseBitmap.SetPixelCnt(x, y, cnt, buffer, inc, srcmode, flags)

Sets cnt pixels at x/y in the bitmap from buffer with mode srcmode, incrementing inc bytes for each pixel. The following example shows you how to read/write from/into an image:

"""
Test Example:
BaseBitmap.SetPixelCnt()/BaseBitmap.GetPixelCnt()

This example shows how to copy the internal data of a 32 bit per-channel image to a new one.
"""

import c4d
from c4d import bitmaps, gui, storage

def main():
    path = storage.LoadDialog(type=c4d.FILESELECTTYPE_IMAGES, title="Please Choose a 32 Bit Image:")
    if not path: return

    # Create and initialize selected image
    orig = bitmaps.BaseBitmap()
    if orig.InitWith(path)[0] != c4d.IMAGERESULT_OK:
        gui.MessageDialog("Cannot load image \"" + path + "\".")
        return

    # Check if channel depth is really 32 bit
    if orig.GetBt()/3 != 32:
        gui.MessageDialog("The image \"" + path + "\" is not a 32 bit per-channel image.")
        return

    # Get selected image infos
    width, height = orig.GetSize()
    bits = orig.GetBt()

    # Create the copy and initialize it
    copy = bitmaps.BaseBitmap()
    copy.Init(width, height, bits)

    # Calculate the number of bytes per pixel
    inc = orig.GetBt()/8 # Each pixel has RGB bits, so we need an offset of 'inc' bytes per pixel
                         # the image has 32 bits per-channel : (32*3)/8 = 12 bytes per pixel (1 byte = 8 bits)
                         # the image has 3 channels per pixel (RGB) : 12/3 = 4 bytes per component = 1 float

    # Create a byte sequence buffer large enough to store the copied image pixels
    sq = storage.ByteSeq(None, width*height*inc)

    for row in xrange(height):
        offset = sq.GetOffset(row*(width*inc)) # Offset on bitmap row + offset bytes per pixel
        orig.GetPixelCnt(0, row, width, offset, inc, c4d.COLORMODE_RGBf, c4d.PIXELCNT_0) # Read pixels from the original bitmap to the buffer

    #Example: RGB value of first pixel (only for 32 bits)
    #import struct
    #r, g, b = struct.unpack("fff", sq[0:12])
    #print r, g, b

    for row in xrange(height):
        offset = sq.GetOffset(row*(width*inc)) # Offset on bitmap row + offset bytes per pixel
        copy.SetPixelCnt(0, row, width, offset, inc, c4d.COLORMODE_RGBf, c4d.PIXELCNT_0) # Set pixels in bitmap copy

    bitmaps.ShowBitmap(orig) # Show original
    bitmaps.ShowBitmap(copy) # Show copied image


if __name__=='__main__':
    main()
Parameters:
  • x (int) – X coordinate of the first pixel to set.
  • y (int) – Y coordinate of the first pixel to set.
  • cnt (int) – Number of pixels to set.
  • buffer – Should point to a large enough memory buffer containing the pixels to set.
  • inc (int) – The byte increment per pixel in the buffer.
  • srcmode (The source mode.) –

    The source mode.

    Note

    None of the alpha modes are supported.

    COLORMODE_ALPHA Only 8-bit alpha channel.
    COLORMODE_GRAY8 8-bit greyscale channel.
    COLORMODE_AGRAY 8-bit greyscale channel with 8-bit alpha.
    COLORMODE_RGB 8-bit RGB channels.
    COLORMODE_ARGB 8-bit RGB channels with 8-bit alpha.
    COLORMODE_CMYK 8-bit CMYK channel.
    COLORMODE_ACMYK 8-bit CMYK channel with 8-bit alpha.
    COLORMODE_MASK 8-bit greymap as mask.
    COLORMODE_AMASK 8-bit greymap as mask with 8-bit alpha.
    COLORMODE_ILLEGAL Private.
    COLORMODE_GRAYw 8-bit greymap as mask with 8-bit alpha.
    COLORMODE_AGRAYw 16-bit greyscale channel with 16-bit alpha.
    COLORMODE_RGBw 16-bit RGB channels.
    COLORMODE_ARGBw 16-bit RGB channels with 16-bit alpha.
    COLORMODE_MASKw 16-bit greymap as mask with 16-bit alpha.
    COLORMODE_ILLEGALf Private.
    COLORMODE_GRAYf Floating point greyscale channel.
    COLORMODE_AGRAYf Floating point greyscale channel with floating point alpha.
    COLORMODE_RGBf Floating point RGB channels.
    COLORMODE_ARGBf Floating point RGB channels with floating point alpha.
    COLORMODE_MASKf Floating point greymap with floating point alpha.
  • flags (int) –

    Flags:

    PIXELCNT_0 None.
    PIXELCNT_APPLYALPHA Apply alpha channel.
    PIXELCNT_B3DLAYERS Merge B3D layers (MultipassBitmap)
    PIXELCNT_DITHERING Allow dithering.
    PIXELCNT_INTERNAL_ALPHAVALUE Private.
    PIXELCNT_INTERNAL_SETLINE Private.
Return type:

bool

Returns:

True if successful, otherwise False.

BaseBitmap.GetInternalChannel()

Get the internal read-only alpha channel. The internal alpha channel is the one that’s saved together with the picture, with those formats that support this. If no internal alpha is available, None is returned.

Return type: BaseBitmap
Returns: The internal alpha channel.
BaseBitmap.GetAlphaPixel(channel, x, y)

Get the alpha value at (x,y) to val. The valid range of val is 0 to 255.

Note

Currently this method does no range check of x and y. This might be added in the future. Please do the check on your own.

Parameters:
  • bmp (BaseBitmap) – The alpha channels to use. Has to be an alpha bitmap.
  • x (int) – X coordinate.
  • y (int) – Y coordinate.
Return type:

int

Returns:

The alpha value.

BaseBitmap.SetAlphaPixel(channel, x, y, val)

Sets the alpha value at (x,y) to val. The valid range of val is 0 to 255.

Note

Currently this method does no range check of x and y. This might be added in the future. Please do the check on your own.

Parameters:
  • bmp (BaseBitmap) – The alpha channels to use. Has to be an alpha bitmap.
  • x (int) – X coordinate.
  • y (int) – Y coordinate.
  • val (int) – The alpha value.
BaseBitmap.Init(x, y, depth)

Note

The bitmap class only supports up to 4 channels. Also, most image loaders will only load one alpha channel.

Initializes the bitmap to the given dimensions and depth. Any previous data in the bitmap object is lost.

Parameters:
  • x (int) – The requested width in pixels. (Max 16000 pixels.).
  • y (int) – The requested width in pixels. (Max 16000 pixels.).
  • depth (int) – The requested bit depth. The possible values are {1,4,8,16,24,32}. On some platforms 32 bits will be used even if 24 is requested, to allow for padding.
Return type:

int

Returns:

The result:

IMAGERESULT_OK

Image loaded/created

IMAGERESULT_NOTEXISTING

Image doesn`t exist

IMAGERESULT_WRONGTYPE

Image has the wrong type

IMAGERESULT_OUTOFMEMORY

Not enough memory

IMAGERESULT_FILEERROR

File error

IMAGERESULT_FILESTRUCTURE

Invalid file structure

IMAGERESULT_FILESTRUCTURE

Miscellaneous structure error

IMAGERESULT_PARAM_ERROR

Parameter error

BaseBitmap.InitWith(name[, frame=-1])

Note

The bitmap class only supports up to 4 channels. Also, most image loaders will only load one alpha channel.

Loads a file into the bitmap. The file can be either a movie or a picture. The file format is automatically detected:

result, ismovie = bmp.InitWith(path)
if result==c4d.IMAGERESULT_OK: #int check
    # picture loaded
    if ismovie==True: #bool check
        pass # file is a movie
    else:
        pass # file is no movie
Parameters:
  • name (str or MemoryFileStruct) –

    The file.

    Changed in version R13.051: It is now possible to pass a memory file.

  • frame (int) – The frame number to load in a movie.
Return type:

tuple(int, bool)

Returns:

The result for first element:

IMAGERESULT_OK

Image loaded/created

IMAGERESULT_NOTEXISTING

Image doesn`t exist

IMAGERESULT_WRONGTYPE

Image has the wrong type

IMAGERESULT_OUTOFMEMORY

Not enough memory

IMAGERESULT_FILEERROR

File error

IMAGERESULT_FILESTRUCTURE

Invalid file structure

IMAGERESULT_FILESTRUCTURE

Miscellaneous structure error

IMAGERESULT_PARAM_ERROR

Parameter error

The second element is True if the loaded picture was a movie.

BaseBitmap.FlushAll()

Resets the bitmap to its initial state and frees allocated memory. Requires a call to Init() before the bitmap can be used again.

BaseBitmap.SetColorProfile(profile)

Copy the color profile to the bitmap.

Parameters: profile (ColorProfile) – The profile.
Return type: bool
Returns: True on success, otherwise False.
BaseBitmap.GetColorProfile()

Get a new color profile instance of the bitmap.

Return type: ColorProfile
Returns: The profile.
BaseBitmap.GetClone()

Clones the Bitmap and returns a new instance.

Return type: BaseBitmap
Returns: The clone.
BaseBitmap.GetClonePart(x, y, w, h)

Copies a part of the bitmap, specified by the rectangle (x,y) to (x+w,y+h).

Parameters:
  • x (int) – Upper left x coordinate of the rectangle.
  • y (int) – int
  • w (int.) – The width of the rectangle.
  • h (int) – The height of the rectangle.
Return type:

BaseBitmap or None

Returns:

The cloned bitmap, or None if an error occured.

BaseBitmap.Save(name, format[, savebits=0][, data])

Saves the bitmap to a file. Valid formats are:

FILTER_TIF TIF
FILTER_TGA TGA
FILTER_BMP BMP
FILTER_IFF IFF
FILTER_JPG JPG
FILTER_PICT PICT
FILTER_PSD PSD
FILTER_RLA RLA
FILTER_RPF RPF
FILTER_B3D Bodypaint
Parameters:
  • name (str or MemoryFileStruct) –

    A file.

    Changed in version R13.029: It is now possible to pass a memory file.

  • format (int) – The image format.
  • savebits (int) –

    Can be a combination of the following flags:

    SAVEBIT_0 No flags
    SAVEBIT_ALPHA Save the alpha channel(s) in the file. (For filter plugins, don’t save an alpha channel if this isn’t set.)
    SAVEBIT_MULTILAYER Save multiple layers
    SAVEBIT_USESELECTEDLAYERS Use selected layers
    SAVEBIT_16BITCHANNELS Use 16 bit channels
    SAVEBIT_GREYSCALE Save in grayscale mode
    SAVEBIT_INTERNALNET Private
    SAVEBIT_DONTMERGE Avoid merging of layers in B3D files
    SAVEBIT_32BITCHANNELS Use 32 bit channels
    SAVEBIT_SAVERENDERRESULT Private
    SAVEBIT_FIRSTALPHA_ONLY Private
  • data (BaseContainer) – The data.
Return type:

int

Returns:

True if BaseBitmap is not empty, otherwise False.

IMAGERESULT_OK

Image loaded/created

IMAGERESULT_NOTEXISTING

Image doesn`t exist

IMAGERESULT_WRONGTYPE

Image has the wrong type

IMAGERESULT_OUTOFMEMORY

Not enough memory

IMAGERESULT_FILEERROR

File error

IMAGERESULT_FILESTRUCTURE

Invalid file structure

IMAGERESULT_FILESTRUCTURE

Miscellaneous structure error

IMAGERESULT_PARAM_ERROR

Parameter error

BaseBitmap.GetChannelCount()

Returns the number of alpha channels in the bitmap, including the internal channel.

Return type: int
Returns: Number of alpha channels.
BaseBitmap.Within(x, y)

Checks if a position is in the bitmap.

Parameters:
  • x (int) – The X Coordinate
  • y (int) – The Y Coordinate
Return type:

bool

Returns:

True if the coordinate is in the bitmap.

BaseBitmap.GetSize()

Returns the size of the bitmap in pixels. If the bitmap hasn’t been initialized the return values are 0. (This is the only way to see if a bitmap has been initialized.):

#bmp is a BaseBitmap instance
x, y = bmp.GetSize()
Return type: list of int
Returns: Bitmap width and height in pixels, or 0 if the bitmap isn’t initialized.
BaseBitmap.GetBw()

Returns the width of the bitmap in pixels. If the bitmap hasn’t been initialized the return value is 0. (This is the only way to see if a bitmap has been initialized.)

Return type: int
Returns: Bitmap width in pixels, or 0 if the bitmap isn’t initialized.
BaseBitmap.GetBh()

Returns the height of the bitmap in pixels.

Return type: int
Returns: Bitmap height in pixels.
BaseBitmap.GetBt()

Returns the number of bits per pixel.

Return type: int
Returns: The number of bits.
BaseBitmap.SetCMAP(i, r, g, b)

If the image in the bitmap has 8 bit indexed color, this function can be used to set the palette entries. All four parameters must be between 0 and 255.

Parameters:
  • i (int) – The index.
  • r (int) – The red component.
  • g (int) – The green component.
  • b (int) – The blue component.
BaseBitmap.GetBpz()

Returns the number of bytes per line.

Return type: int
Returns: Number of bytes per line.
BaseBitmap.SetData(id, data)

Sets bitmap data.

Parameters:
  • id (int) –

    The data to set:

    BASEBITMAP_DATA_GAMMA Gamma
    BASEBITMAP_DATA_EXPOSURE Exposure
    BASEBITMAP_DATA_TARGETGAMMA Target gamma
  • data (float) – The data
Return type:

bool

Returns:

True if the data could be set, otherwise False.

BaseBitmap.GetData(id, default)

Gets bitmap data.

Parameters:
  • id (int) –

    The data to get:

    BASEBITMAP_DATA_GAMMA Gamma
    BASEBITMAP_DATA_EXPOSURE Exposure
    BASEBITMAP_DATA_TARGETGAMMA Target gamma
  • default (any) – Returns default if value is not set.
Return type:

float or type(default)

Returns:

the retrieved data, or default.

BaseBitmap.ScaleBicubic(dst, src_xmin, src_ymin, src_xmax, src_ymax, dst_xmin, dst_ymin, dst_xmax, dst_ymax)

Scales the bitmap rectangle (src_xmin, src_ymin, src_xmax, src_ymax) to fit in the destination bitmap rectangle (dst_xmin, dst_ymin, dst_xmax, dst_ymax) and copies it there. The scaling, if necessary, is done using bicubic interpolation. The destination needs to be initialized before calling this function:

bmp.ScaleBicubic(dst, 0, 0, bmp.GetBw()-1, bmp.GetBh()-1, 0, 0, dst.GetBw()-1, dst.GetBh()-1)

Note

This function can currently only scale down, i.e. the destination needs to be smaller or equal to the source in size.

Parameters:
  • dst (BaseBitmap) – The destination bitmap.
  • src_xmin (int) – Source top left X coordinate.
  • src_ymin (int) – Source top left Y coordinate.
  • src_xmax (int) – Source bottom right X coordinate.
  • src_ymax (int) – Source bottom right Y coordinate.
  • dst_xmin (int) – Destination top left X coordinate.
  • dst_ymin (int) – Destination top left Y coordinate.
  • dst_xmax (int) – Destination bottom right X coordinate.
  • dst_ymax (int) – Destination bottom right Y coordinate.
BaseBitmap.ScaleIt(dst, intens, sample, inprop)

Scales the bitmap to fit in the destination bitmap and copies it there. The destination needs to be initialized with the destination size before calling this function.

Parameters:
  • dst (BaseBitmap) – The destination image. Must be initiated already with the destination size.
  • intens (int) – Lets you change brightness of the image (128 = 50% brightness, 256 = unchanged).
  • sample (bool) – If True a better scaling algorithm is used, which results in a better quality but is a bit slower.
  • inprop (bool) – Must be True if non-proportional scaling is wanted.
Return type:

BaseBitmap

Returns:

The scaled bitmap.

BaseBitmap.AddChannel(internal, straight)

Adds a new alpha channel to the image.

Parameters:
  • internal (bool) – Should only be True for the first alpha. The internal alpha will be stored within an image if the image format supports alphas.
  • straight (bool) – Should be True if the image has to be interpreted as straight. For information about straight alphas please take a look at the corresponding option in the render settings of CINEMA 4D and the CINEMA 4D manual.
Return type:

int

Returns:

The new channel.

BaseBitmap.RemoveChannel(channel)

Removes the specified channel from the bitmap.

Parameters: channel (BaseBitmap) – The alpha channels to use.
BaseBitmap.GetChannelNum(num)

Returns the channel ID from the channel index.

Parameters: num (int) – A number between 0 and GetChannelCount().
Return type: BaseBitmap
Returns: The requested channel.
BaseBitmap.GetDirty()

Private.

Return type: int
Returns: Dirty count, incremented when the bitmap changes.
BaseBitmap.SetDirty()

Makes the bitmap dirty.

BaseBitmap.IsMultipassBitmap()

Checks if the image is a MultipassBitmap.

Return type: bool
Returns: True if the image is a MultipassBitmap, otherwise False
BaseBitmap.GetColorMode()

Returns the color mode of the bitmap.

Return type: int
Returns: Color mode
COLORMODE_ALPHA Only 8-bit alpha channel.
COLORMODE_GRAY8 8-bit greyscale channel.
COLORMODE_AGRAY 8-bit greyscale channel with 8-bit alpha.
COLORMODE_RGB 8-bit RGB channels.
COLORMODE_ARGB 8-bit RGB channels with 8-bit alpha.
COLORMODE_CMYK 8-bit CMYK channel.
COLORMODE_ACMYK 8-bit CMYK channel with 8-bit alpha.
COLORMODE_MASK 8-bit greymap as mask.
COLORMODE_AMASK 8-bit greymap as mask with 8-bit alpha.
COLORMODE_ILLEGAL Private.
COLORMODE_GRAYw 8-bit greymap as mask with 8-bit alpha.
COLORMODE_AGRAYw 16-bit greyscale channel with 16-bit alpha.
COLORMODE_RGBw 16-bit RGB channels.
COLORMODE_ARGBw 16-bit RGB channels with 16-bit alpha.
COLORMODE_MASKw 16-bit greymap as mask with 16-bit alpha.
COLORMODE_ILLEGALf Private.
COLORMODE_GRAYf Floating point greyscale channel.
COLORMODE_AGRAYf Floating point greyscale channel with floating point alpha.
COLORMODE_RGBf Floating point RGB channels.
COLORMODE_ARGBf Floating point RGB channels with floating point alpha.
COLORMODE_MASKf Floating point greymap with floating point alpha.
BaseBitmap.GetMemoryInfo()

Get the size of the memory used by the bitmap.

Return type: long
Returns: Memory size of the bitmap.
BaseBitmap.GetUpdateRegionBitmap()

Get the updated region of a bitmap.

Return type: BaseBitmap
Returns: The updated region.

Table Of Contents