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.

Overview¶

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

Bitmap Operations
`GeClipMap.Blit()`	Blits from s_dp to this clip map.
`GeClipMap.GetBh()`	Retrieves the pixel height of the clip map.
`GeClipMap.GetBitmap()`	Returns the internal bitmap object.
`GeClipMap.GetBw()`	Retrieves the pixel width of the clip map.
`GeClipMap.GetDim()`	Retrieves the pixel dimensions of the clip map.
Clipping Checks
`GeClipMap.ClipArea()`	Checks if a rectangle is inside the clip region.
`GeClipMap.ClipPoint()`	Checks if a point is inside the clip region.
Color And Pixels
`GeClipMap.GetPixelRGBA()`	Retrieves the color of the pixel at (x,y).
`GeClipMap.SetColor()`	Sets the draw color.
`GeClipMap.SetPixel()`	Sets the pixel at (x,y) to the draw color.
`GeClipMap.SetPixelRGBA()`	Sets the pixel at (x,y) to the specified color.
Drawing Configuration
`GeClipMap.SetDrawMode()`	Sets the draw mode for the following drawing operations.
`GeClipMap.SetOffset()`	Offsets all the following draw commands by this amount.
Drawing Sessions
`GeClipMap.BeginDraw()`	Must be called before any drawing commands.
`GeClipMap.EndDraw()`	Must be called after any drawing commands.
Font Management
`GeClipMap.GetFont()`	Returns the current font description.
`GeClipMap.SetFont()`	Sets the current font.
Initialization And Cleanup
`GeClipMap.Destroy()`	Resets the clip map to its initial state and frees allocated memory.
`GeClipMap.Init()`	Initializes the clip map bitmap to the given dimensions and depth.
`GeClipMap.InitWith()`	Loads the clip map bitmap from the file specified by name.
`GeClipMap.InitWithBitmap()`	Loads the clip map bitmap from bm.
Magic Methods
`GeClipMap.__init__()`	Creates a new instance of `GeClipMap`.
Shape Drawing
`GeClipMap.Arc()`	Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.
`GeClipMap.Ellipse()`	Draws an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.
`GeClipMap.FillArc()`	Draws an arc within the rectangle from (x1,y1) to (x2,y2) with the draw color.
`GeClipMap.FillEllipse()`	Fills an ellipse within the rectangle from (x1,y1) to (x2,y2) with the draw color.
`GeClipMap.FillPolygon()`	Fills the polygon line specified by the p with the draw color.
`GeClipMap.FillRect()`	Fills a rectangle from (x1,y1) to (x2,y2) with the draw color.
`GeClipMap.Line()`	Draws a line from (x1,y1) to (x2,y2) with the draw color.
`GeClipMap.PolyLine()`	Draws the polygon line specified by the p with the draw color.
`GeClipMap.Rect()`	Draws the outline of a rectangle from (x1,y1) to (x2,y2) with the draw color.
Text Rendering
`GeClipMap.TextAscent()`	Calculates the ascent in the current font.
`GeClipMap.TextAt()`	Prints the string txt with the top left corner at (x,y) in the current draw color.
`GeClipMap.TextHeight()`	Calculates the maximum height of a string in the current font.
`GeClipMap.TextWidth()`	Calculates the width of the string txt in the current font.

Members¶

Font Management¶

static 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	One `BaseContainer` per font, no order guaranteed.
GE_CM_FONTSORT_HIERARCHICAL	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.

Return type

c4d.BaseContainer

Returns

The font list.

static 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 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 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 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 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.

Bitmap Operations¶

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.GetBh(self)¶

Retrieves the pixel height of the clip map.

Return type: int
Returns: The height.

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.GetBw(self)¶

Retrieves the pixel width of the clip map.

Return type: int
Returns: The width.

GeClipMap.GetDim(self)¶

Retrieves the pixel dimensions of the clip map.

w, h = clmap.GetDim()

Return type: Tuple[int, int]
Returns: The width and height dimensions of the clip map.

Clipping Checks¶

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.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.

Color And Pixels¶

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.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.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.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.)

Drawing Configuration¶

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.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.

Drawing Sessions¶

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().

Font Management¶

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.

GeClipMap.SetFont(self, font_description, font_size)¶

Sets the current font.

Parameters

font_description (Optional[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.

Initialization And Cleanup¶

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.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

name (Union[str, c4d.storage.MemoryFileStruct]) – The path to the image.
frame (int) – The frame number to load in a movie.

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

bm (c4d.bitmaps.BaseBitmap) – The bitmap to initialize the clip map with.
alpha_channel (Optional[c4d.bitmaps.BaseBitmap]) – The alpha channel to use in bm.

Return type

bool

Returns

True if the clip map was initialized, otherwise False.

Magic Methods¶

GeClipMap.__init__(self)¶: Creates a new instance of GeClipMap.

Shape Drawing¶

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.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.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.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.FillPolygon(self, p)¶

Fills the polygon line specified by the p with the draw color.

New in version 24.

Warning

This function must be enclosed between GeClipMap.BeginDraw() and GeClipMap.EndDraw().

Parameters: p (Tuple[int, int]) – The points in the polygon, a list of list made of 2 int representing the X and 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.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.PolyLine(self, p)¶

Draws the polygon line specified by the p with the draw color.

New in version 24.

Warning

This function must be enclosed between GeClipMap.BeginDraw() and GeClipMap.EndDraw().

Parameters: p (Tuple[int, int]) – The points in the polygon line, a list of list made of 2 int representing the X and 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.

Text Rendering¶

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.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.TextHeight(self)¶: Calculates the maximum height of a string in the current font.

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.

Category	Option	Description
Query	Words and phrases	Search is case-insensitive. Put a phrase in quotes for an exact match. Quoted phrases require every word and disable fuzzy matching.
Terms	OR / AND	Choose whether to match any term or require all terms.
Fuzzy	On / Off	Toggle approximate and prefix matches. Quoted phrases always use strict matching.
Results	Sparse / Dense	Sparse groups multiple hits for one entity and hides its owned API members when the class or module itself matches. Dense lists each match separately.
Sort by	Type / Relevance	Group results by entity type then rank within each group, or rank all results by relevance.
Content	All / API / Manuals / Examples / Resources	Search all documentation, API documentation, manuals, the examples index, or the resources index. Code examples embedded in other sections retain their own content area.
Entity	All / Page / Module / Class / Function / Attribute / Description / Node / Symbol / Icon	Page covers results without a specific entity type. Resource entity types are available with All or Resources; API entity types are available with All or API.
Location	All / Text / Code / Name / Signature	Text covers everything outside code, names, and signatures. Name and Signature are available with All or API.

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)