c4d.bitmaps.GeClipMap

class c4d.bitmaps.GeClipMap
This class stores and manipulates a bitmap, providing more advanced drawing tools than BaseBitmap.
Just like for bitmaps x = y = 0 is the top left corner.
Be sure to call GeClipMap.Init(), GeClipMap.InitWith() or GeClipMap.InitWithBitmap() before you attempt to use a newly allocated clip map.

Note

Though clip maps support other bit depths than 32, the functionality is severely limited.
It is recommended that the clip map class is only used for 32 bit bitmaps.
Please note that the default bit depth for BaseBitmap is 24. You need to manually set it to 32 if you use Init to initialize the clip map.

Methods Signatures

GeClipMap.__init__(self,) Creates a new instance of GeClipMap.
GeClipMap.Init(self, w, h[, bits]) Initializes the clip map bitmap to the given dimensions and depth. Any previous data is lost.
GeClipMap.InitWith(self, name, frame) Loads the clip map bitmap from the file specified by name.
GeClipMap.InitWithBitmap(self, bm[, alpha_channel])
Loads the clip map bitmap from bm.
GeClipMap.Destroy(self,) Resets the clip map to its initial state and frees allocated memory.
GeClipMap.GetBitmap(self,) Returns the internal bitmap object.
GeClipMap.BeginDraw(self,) Must be called before any drawing commands.
GeClipMap.EndDraw(self,) Must be called after any drawing commands.
GeClipMap.GetDim(self,) Retrieves the pixel dimensions of the clip map.
GeClipMap.GetBw(self,) Retrieves the pixel width of the clip map.
GeClipMap.GetBh(self,) Retrieves the pixel height of the clip map.
GeClipMap.Blit(self, dx, dy, s_dp, ...) Blits from s_dp to this clip map. The region (sx1, sy1) to (sx2, sy2) from the source will be copied into the region with the top left corner at (dx, dy) in the destination.
GeClipMap.SetColor(self, r, g, b[, alpha]) Sets the draw color.
GeClipMap.SetOffset(self, off_x, off_y) Offsets all the following draw commands by this amount.
GeClipMap.SetDrawMode(self, mode, par) Sets the draw mode for the following drawing operations.
GeClipMap.SetPixel(self, x, y) Sets the pixel at (x,y) to the draw color.
GeClipMap.Line(self, x1, y1, x2, y2) Draws a line from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.Rect(self, x1, y1, x2, y2) Draws the outline of a rectangle from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.FillRect(self, x1, y1, x2, y2) Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.Arc(self, x1, y1, x2, y2, seg) Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.FillArc(self, x1, y1, x2, y2, seg) Draws an arc within the rectangle from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.Ellipse(self, x1, y1, x2, y2) Draws an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.FillEllipse(self, x1, y1, x2, y2) Fills an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.
GeClipMap.SetPixelRGBA(self, x, y, r, g, b[, a]) Sets the pixel at (x,y) to the specified color.
GeClipMap.GetPixelRGBA(self, x, y) Retrieves the color of the pixel at (x,y).
GeClipMap.TextAt(self, x, y, txt) Prints the string txt with the top left corner at (x,y) in the current draw color.
GeClipMap.TextWidth(self, txt) Calculates the width of the string txt in the current font.
GeClipMap.TextHeight(self,) Calculates the maximum height of a string in the current font.
GeClipMap.TextAscent(self,) Calculates the ascent in the current font. This is the distance from the baseline to the ascended line and usually represents the height of capital letters.
GeClipMap.ClipPoint(self, x, y) Checks if a point is inside the clip region.
GeClipMap.ClipArea(self, x1, y1, x2, y2) Checks if a rectangle is inside the clip region.
GeClipMap.SetFont(self, font_description, ...) Sets the current font.
GeClipMap.GetFont(self, font_description) Returns the current font description.

Static Methods Signatures

c4d.bitmaps.GeClipMap.GetFontName(font_description, type) Retrieves the font name from a font description.
c4d.bitmaps.GeClipMap.GetFontDescription(name, type) Retrieves a font description.
c4d.bitmaps.GeClipMap.EnumerateFonts(sort_mode)
Enumerates all fonts and returns them in a container.
c4d.bitmaps.GeClipMap.GetDefaultFont(type) Retrieves Cinema 4D’s default font.
c4d.bitmaps.GeClipMap.GetFontSize(font_description, type) Retrieves the font size for a given font.
c4d.bitmaps.GeClipMap.SetFontSize(font_description, type, ...) Sets the font size for a given font.

Methods Documentation

GeClipMap.__init__(self)

Creates a new instance of GeClipMap.

Return type:c4d.bitmaps.GeClipMap
Returns:The new clipmap.
GeClipMap.Init(self, w, h, bits=32)

Initializes the clip map bitmap to the given dimensions and depth. Any previous data is lost.

Parameters:
  • w (int) – Width
  • h (int) – height
  • bits (int) – 32
Return type:

bool

Returns:

True if the initialization was successful.

GeClipMap.InitWith(self, name, frame)

Loads the clip map bitmap from the file specified by name.

Note

The file can be either a movie or a picture.
The file format is automatically detected.
Any previous data is lost.
result, isMovie = clmap.InitWith(path)
if result == c4d.IMAGERESULT_OK: #int check
    # picture loaded
    if isMovie: #bool check
        pass # file is a movie
    else:
        pass # file is no movie
Parameters:
Return type:

tuple(int, bool)

Returns:

The image result and a boolean value if the file is a movie.

GeClipMap.InitWithBitmap(self, bm, alpha_channel=None)
Loads the clip map bitmap from bm.
Any previous data is lost.
Parameters:
Return type:

bool

Returns:

True if the clip map was initialized, otherwise False.

GeClipMap.Destroy(self)

Resets the clip map to its initial state and frees allocated memory.

Warning

Requires a new call to Init() before the clip map can be used again.

GeClipMap.GetBitmap(self)

Returns the internal bitmap object.

Warning

The clip map alpha channel won’t be encoded in this bitmap. This is a limitation.

Return type:c4d.bitmaps.BaseBitmap
Returns:The bitmap.
GeClipMap.BeginDraw(self)

Must be called before any drawing commands.

Note

After you call a sequence of drawing commands you should call GeClipMap.EndDraw().

GeClipMap.EndDraw(self)

Must be called after any drawing commands.

Note

Before you call a sequence of drawing commands you should call GeClipMap.BeginDraw().

GeClipMap.GetDim(self)

Retrieves the pixel dimensions of the clip map.

w, h = clmap.GetDim()
Return type:tuple of int
Returns:The width and height dimensions of the clip map.
GeClipMap.GetBw(self)

Retrieves the pixel width of the clip map.

Return type:int
Returns:The width.
GeClipMap.GetBh(self)

Retrieves the pixel height of the clip map.

Return type:int
Returns:The height.
GeClipMap.Blit(self, dx, dy, s_dp, sx1, sy1, sx2, sy2, rop)

Blits from s_dp to this clip map. The region (sx1, sy1) to (sx2, sy2) from the source will be copied into the region with the top left corner at (dx, dy) in the destination.

Additionally you can specify a raster operation with rop.

Parameters:
  • dx (int) – Top left destination X coordinate.
  • dy (int) – Top left destination Y coordinate.
  • s_dp (c4d.bitmaps.GeClipMap) – Source.
  • sx1 (int) – Top left source X coordinate.
  • sy1 (int) – Top left source Y coordinate.
  • sx2 (int) – Bottom right source X coordinate.
  • sy2 (int) – Bottom right source Y coordinate.
  • rop (int) –

    Raster operation:

    GE_CM_BLIT_COPY Source overwrites destination.
    GE_CM_BLIT_COL Source overwrites destination everywhere where source doe not equal the background color.
    GE_CM_BLIT_FG Sets pixels to the foreground color if the color is not the background color.
GeClipMap.SetColor(self, r, g, b, alpha=255)

Sets the draw color.

Parameters:
  • r (int) – Red. (Between 0 and 255.).
  • g (int) – Green. (Between 0 and 255.)
  • b (int) – Blue. (Between 0 and 255.)
  • alpha (int) – Alpha value. (Between 0 and 255.)
GeClipMap.SetOffset(self, off_x, off_y)

Offsets all the following draw commands by this amount.

Note

The clip region is not offset.

Parameters:
  • off_x (int) – X distance in pixels.
  • off_y (int) – Y distance in pixels.
GeClipMap.SetDrawMode(self, mode, par)

Sets the draw mode for the following drawing operations.

Parameters:
  • mode (int) –

    Mode:

    GE_CM_DRAWMODE_COPY New pixels overwrite old ones.
    GE_CM_DRAWMODE_BLEND New pixels blend with old ones, taking the alpha value of the new pixels in account as well as the blend factor specified by the parameter. The value specified by the parameter is the opacity of the source (bitmap). It ranges from 0 to 256, where 256 equals 1.0 and means opaque.
    GE_CM_DRAWMODE_MASK New pixels overwrite the old ones at the bits where the mask specified by the parameter equals 1.
  • par (int) – Parameter (Depends on mode)
GeClipMap.SetPixel(self, x, y)

Sets the pixel at (x,y) to the draw color.

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) – X coordinate.
  • y (int) – Y coordinate.
GeClipMap.Line(self, x1, y1, x2, y2)

Draws a line from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – First X coordinate.
  • y1 (int) – First Y coordinate.
  • x2 (int) – Second X coordinate.
  • y2 (int) – Second Y coordinate.
GeClipMap.Rect(self, x1, y1, x2, y2)

Draws the outline of a rectangle from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
GeClipMap.FillRect(self, x1, y1, x2, y2)

Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
GeClipMap.Arc(self, x1, y1, x2, y2, seg)

Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
  • seg

    The arc is drawn in the direction given by:

    0 (x1,y1) -> (x2,y1) -> (x2,y2)
    1 (x2,y1) -> (x2,y2) -> (x1,y2)
    2 (x2,y2) -> (x1,y2) -> (x1,y1)
    3 (x1,y2) -> (x1,y1) -> (x2,y1)
GeClipMap.FillArc(self, x1, y1, x2, y2, seg)

Draws an arc within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
  • seg

    The arc is drawn in the direction given by:

    0 (x1,y1) -> (x2,y1) -> (x2,y2)
    1 (x2,y1) -> (x2,y2) -> (x1,y2)
    2 (x2,y2) -> (x1,y2) -> (x1,y1)
    3 (x1,y2) -> (x1,y1) -> (x2,y1)
GeClipMap.Ellipse(self, x1, y1, x2, y2)

Draws an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
GeClipMap.FillEllipse(self, x1, y1, x2, y2)

Fills an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
GeClipMap.SetPixelRGBA(self, x, y, r, g, b, a=255)

Sets the pixel at (x,y) to the specified color.

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) – X coordinate.
  • y (int) – Y coordinate.
  • r (int) – Red. (Between 0 and 255.)
  • g (int) – Green. (Between 0 and 255.)
  • b (int) – Blue. (Between 0 and 255.)
  • a (int) – Alpha value. (Between 0 and 255.)
GeClipMap.GetPixelRGBA(self, x, y)

Retrieves the color of the pixel at (x,y).

r, g, b, a = clmap.GetPixelRGBA(5, 5)

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) – X coordinate.
  • y (int) – Y coordinate.
Return type:

List[int]

Returns:

The color of the pixel.

GeClipMap.TextAt(self, x, y, txt)

Prints the string txt with the top left corner at (x,y) in the current draw color.

Parameters:
  • x (int) – Top left X coordinate.
  • y (int) – Top left Y coordinate.
  • txt (str) – Text to print.
GeClipMap.TextWidth(self, txt)

Calculates the width of the string txt in the current font.

Parameters:txt (str) – The string.
Return type:int
Returns:Calculates the maximum height of a string in the current font.
GeClipMap.TextHeight(self)

Calculates the maximum height of a string in the current font.

GeClipMap.TextAscent(self)

Calculates the ascent in the current font. This is the distance from the baseline to the ascended line and usually represents the height of capital letters.

GeClipMap.ClipPoint(self, x, y)

Checks if a point is inside the clip region.

Parameters:
  • x (int) – X coordinate.
  • y (int) – Y coordinate.
Return type:

bool

Returns:

True if the point is inside the region, otherwise False.

GeClipMap.ClipArea(self, x1, y1, x2, y2)

Checks if a rectangle is inside the clip region.

Parameters:
  • x1 (int) – Top left X coordinate.
  • y1 (int) – Top left Y coordinate.
  • x2 (int) – Bottom right X coordinate.
  • y2 (int) – Bottom right Y coordinate.
Return type:

int

Returns:

The result.

GeClipMap.SetFont(self, font_description, font_size)

Sets the current font.

Parameters:
  • font_description (c4d.BaseContainer) – The font description. Can be None for the default font.
  • font_size (float) – Font size, or 0.0 for the default height.
Return type:

bool

Returns:

True if successful, otherwise False.

GeClipMap.GetFont(self, font_description)

Returns the current font description.

Parameters:font_description (c4d.BaseContainer) – Assigned the current font description.
Return type:float
Returns:The font size.

Static Methods Documentation

static c4d.bitmaps.GeClipMap.GetFontName(font_description, type)

Retrieves the font name from a font description.

New in version R17.032.

Parameters:
  • font_description (c4d.BaseContainer) – The font description.
  • type (int) –

    The type of font name:

    GE_FONT_NAME_DISPLAY Human readable font name (e.g. “Helvetica Bold”).
    GE_FONT_NAME_FAMILY Font family name (e.g. “Helvetica”).
    GE_FONT_NAME_STYLE Font style name (e.g. “Bold”).
    GE_FONT_NAME_POSTSCRIPT Font postscript name (e.g. “Helvetica-Bold”).
Return type:

str

Returns:

The font name.

static c4d.bitmaps.GeClipMap.GetFontDescription(name, type)

Retrieves a font description.

New in version R17.032.

Parameters:
  • name (str) – The font name.
  • type (int) –

    The type of font name:

    GE_FONT_NAME_DISPLAY Human readable font name (e.g. “Helvetica Bold”).
    GE_FONT_NAME_FAMILY Font family name (e.g. “Helvetica”).
    GE_FONT_NAME_STYLE Font style name (e.g. “Bold”).
    GE_FONT_NAME_POSTSCRIPT Font postscript name (e.g. “Helvetica-Bold”).
Return type:

c4d.BaseContainer

Returns:

The font description.

static c4d.bitmaps.GeClipMap.EnumerateFonts(sort_mode)
Enumerates all fonts and returns them in a container.
For each font a container (font description) will be inserted. They can be used for SetFont() and GetFontName().

New in version R17.032.

Parameters:sort_mode (str) –

The sort mode:

GE_CM_FONTSORT_FLAT For each font family a BaseContainer is stored and will hold a description for each font of the family (one container per font). The font families are sorted alphabetically.
GE_CM_FONTSORT_HIERARCHICAL One BaseContainer per font, no order guaranteed.
Return type:c4d.BaseContainer
Returns:The font list.
static c4d.bitmaps.GeClipMap.GetDefaultFont(type)

Retrieves Cinema 4D’s default font.

New in version R17.032.

Parameters:type (int) –

The default font type:

GE_FONT_DEFAULT_SYSTEM The Cinema 4D system font.
GE_FONT_DEFAULT_MONOSPACED The Cinema 4D monospaced font.
Return type:c4d.BaseContainer
Returns:The default font description.
static c4d.bitmaps.GeClipMap.GetFontSize(font_description, type)

Retrieves the font size for a given font.

New in version R17.032.

Parameters:
  • font_description (c4d.BaseContainer) – The font description.
  • type (int) –

    The type of font size:

    GE_FONT_SIZE_INTERNAL The unit of the font size is not specified (OS or context dependent). It is not guaranteed to be pixels or points or whatever. Use it only to compare the size of two font descriptions.
Return type:

float

Returns:

The font size.

static c4d.bitmaps.GeClipMap.SetFontSize(font_description, type, size)

Sets the font size for a given font.

New in version R17.032.

Parameters:
  • font_description (c4d.BaseContainer) – The font description.
  • type (int) –

    The type of font size:

    GE_FONT_SIZE_INTERNAL The unit of the font size is not specified (OS or context dependent). It is not guaranteed to be pixels or points or whatever. Use it only to compare the size of two font descriptions.
  • size (float) – The font size to set.
Return type:

bool

Returns:

True if successful, otherwise False.