c4d.modules.sculpting.SculptObject¶

class c4d.modules.sculpting.SculptObject¶: A SculptObject is what you use to interact with the data referenced by a SculptTag (SculptTag.GetSculptObject()).

The SculptTag on a PolygonObject references a SculptObject that is stored in a scene hook within the document.

When the SculptTag is deleted this SculptObject is also deleted.

New in version R15.037.

Parent Class:

c4d.BaseObject

Overview¶

Collision And Raycasting
`SculptObject.HitObject()`	Given a ray in object space do a hit intersection against the sculpt object and return any data if the ray hits the object.
`SculptObject.HitScreen()`	From a viewport cast a ray, in screen space, onto the sculpt object and return any data if the ray hits the object.
`SculptObject.NeedCollisionUpdate()`	Tells the sculpt object that it requires a collision update before the user tries to use any of the sculpt tools.
`SculptObject.UpdateCollision()`	Updates any collision data after any changes to the sculpt layer offsets have been made.
Geometry Access
`SculptObject.GetDisplayPolygonObject()`	Retrieves the Polygon Object that is currently being displayed in the viewport.
`SculptObject.GetFaceNormal()`	Gets the face normal for the polygon object at index and at the current subdivision level.
`SculptObject.GetOriginalObject()`	Get the original `PolygonObject` that the `SculptTag` is applied to.
`SculptObject.GetPoint()`	Get read-only access to the point at index that will be used for the polygon object at the current subdivision level.
`SculptObject.GetPolygon()`	Gets the Polygon at the given index.
`SculptObject.GetVertexNormal()`	Get the vertex normal for the polygon object at index and at the current subdivision level.
Layer Management
`SculptObject.AddFolder()`	Create a new folder for the sculpt object.
`SculptObject.AddLayer()`	Create a new layer on the sculpt object at the current subdivision level.
`SculptObject.DeleteSelectedLayer()`	Deletes the currently selected layer (or folder) on the sculpt object (as specified in the Sculpting Layer Manager UI).
`SculptObject.GetBaseLayer()`	Get the Base Object layer, which is the special layer that has multiple `SculptLayerData` children, one for each subdivison level, that allows the user to sculpt on while at any subdivision level.
`SculptObject.GetCurrentLayer()`	Get the currently layer, or folder, selected for this sculpt object.
`SculptObject.GetFirstLayer()`	Get the first layer.
Masks And Selection
`SculptObject.GetMaskCachePoint()`	Gets the mask value from the mask cache.
`SculptObject.IsPointSelected()`	For use in the `SculptBrushToolData.FloodSelectedLayer()` method to determine if a point should be moved or not.
`SculptObject.IsPolygonSelected()`	For use in the `SculptBrushToolData.FloodSelectedLayer()` method to determine if a point should be moved or not.
`SculptObject.UpdateMask()`	Updates the mask on the sculpt object.
Processing And Resources
`SculptObject.GetMemoryUsage()`	Get the amount of memory currently used for this sculpt object.
`SculptObject.InitOpenGL()`	Initializes the sculpt object for the given viewport for OpenGL use.
`SculptObject.Smooth()`	Smooth the sculpt object and apply the offsets to the currently selected layer.
`SculptObject.Update()`	Recomposites all the layers and updates the sculpt object.
State Controls
`SculptObject.GetAllowDeformations()`	Check if the object allows to be deformed by any deformers.
`SculptObject.IsFrozen()`	Check if the sculpt object is frozen.
`SculptObject.SetAllowDeformations()`	Set the Allow Deformations checkbox thereby allowing any deformers to have an effect on the display of the sculpt object, as long as it is also frozen.
`SculptObject.SetFrozen()`	Sets the frozen state of the sculpt object.
Subdivision Management
`SculptObject.DecreaseSubdivisionLevel()`	Decrease the subdivision level to the down one level.
`SculptObject.GetCurrentLevel()`	Gets the current subdivision level that the sculpt object is currently at.
`SculptObject.GetPointCount()`	Get the number of points at the current subdivision level.
`SculptObject.GetPolygonCopy()`	Get a copy of the sculpt object at a specific subdivision level.
`SculptObject.GetPolygonCount()`	Get the number of polygons at the current subdivision level.
`SculptObject.GetSubdivisionCount()`	Get the number of subdivisions that this sculpt object currently has; i.e.
`SculptObject.IncreaseSubdivisionLevel()`	Increase the subdivision level to the next highest level.
`SculptObject.Subdivide()`	Subdivide the sculpt object to the next level.
Undo Management
`SculptObject.EndUndo()`	Must be called after `StartUndo()` once all the points and masks have been changed on the layers.
`SculptObject.StartUndo()`	Call before any calls to `AddOffset()`, `SetOffset()`, `AddToMask()` or `SetMask()` if you wish it to be undone.

Members¶

Collision And Raycasting¶

SculptObject.HitObject(self, rayp, rayv, backfaces)¶

Given a ray in object space do a hit intersection against the sculpt object and return any data if the ray hits the object.

Note

This will return the closest hit point if multiple intersections are found.

Note

To use the Hit functions the mesh must be unfrozen and both NeedCollisionUpdate(True) and UpdateCollision() should be called to initialize the collision data.

Parameters

rayp (c4d.Vector) – The starting position of the ray in object space.
rayv (c4d.Vector) – The direction the ray is pointing.
backfaces (bool) – Allow back facing polygons to be hit tested.

Return type

dict{distance: float, normal: Vector, point: Vector, polygon: int}

Returns

The intersection data will be returned if the object was hit:

distance: The distance from the ray point. normal: The normal of the hitpoint on the surface of the object in its local coordinate system. point: Location of the hit point on the surface of the object in its local coordinate system. polygon: The polygon that was hit.

SculptObject.HitScreen(self, bd, mx, my, backfaces)¶

From a viewport cast a ray, in screen space, onto the sculpt object and return any data if the ray hits the object.

Note

This will return the closest hit point if multiple intersections are found.

Note

To use the Hit functions the mesh must be unfrozen and both NeedCollisionUpdate(True) and UpdateCollision() should be called to initialize the collision data.

Parameters

bd (c4d.BaseDraw) – The BaseDraw that the user is casting the ray from.
mx (float) – The X coordinate (i.e. mouse coordinate) in screen space.
my (float) – The Y coordinate (i.e mouse coordinate) in screen space.
backfaces (bool) – Allow back facing polygons to be hit tested.

Return type

dict{distance: float, normal: Vector, point: Vector, polygon: int}

Returns

The intersection data will be returned if the object was hit:

SculptObject.NeedCollisionUpdate(self, fullUpdate)¶

Tells the sculpt object that it requires a collision update before the user tries to use any of the sculpt tools. Then next time a user tries to use a tool it will first call UpdateCollision() to ensure that the HitScreen()/HitObject() calls will be correct.

Parameters: fullUpdate (bool) – Set to True to update the full mesh. This is not always required.

SculptObject.UpdateCollision(self)¶: Updates any collision data after any changes to the sculpt layer offsets have been made. This is required before you call the HitScreen()/HitObject() methods.

Geometry Access¶

SculptObject.GetDisplayPolygonObject(self)¶

Retrieves the Polygon Object that is currently being displayed in the viewport.

This is the internal Polygon Object and should never be changed.

New in version R16.021.

Note

In SculptBrushToolData.FloodSelectedLayer() calls it returns the same as GetOriginalObject() when sculpting on a Polygon Object that have no SculptTag.

Return type: c4d.PolygonObject
Returns: The Polygon Object displayed in the viewport.

SculptObject.GetFaceNormal(self, index)¶

Gets the face normal for the polygon object at index and at the current subdivision level.

New in version R17.032.

Parameters: index (int) – The index of the face.
Raises: IndexError – If the face index is out of range : 0<=index<GetPolygonCount().
Return type: c4d.Vector
Returns: The face normal.

SculptObject.GetOriginalObject(self)¶

Get the original PolygonObject that the SculptTag is applied to.

Return type: c4d.PolygonObject
Returns: The original PolygonObject.

SculptObject.GetPoint(self, index)¶

Get read-only access to the point at index that will be used for the polygon object at the current subdivision level.

Parameters: index (int) – The index of the point.
Raises: IndexError – If the point index is out of range : 0<=index<GetPointCount().
Return type: c4d.Vector
Returns: The point.

SculptObject.GetPolygon(self, index)¶

Gets the Polygon at the given index.

New in version R16.021.

Parameters: index (int) – The index of the polygon.
Raises: IndexError – If the polygon index is out of range : 0<=index<GetPolygonCount().
Return type: Optional[c4d.CPolygon]
Returns: The Polygon if it was found, otherwise None.

SculptObject.GetVertexNormal(self, index)¶

Get the vertex normal for the polygon object at index and at the current subdivision level.

Parameters: index (int) – The index of the vertex.
Raises: IndexError – If the vertex index is out of range : 0<=index<GetPointCount().
Return type: c4d.Vector
Returns: The vertex normal.

Layer Management¶

SculptObject.AddFolder(self)¶

Create a new folder for the sculpt object.

Return type: c4d.modules.sculpting.SculptFolder
Returns: The sculpt folder added.

SculptObject.AddLayer(self)¶

Create a new layer on the sculpt object at the current subdivision level.

Return type: c4d.modules.sculpting.SculptLayer
Returns: The sculpt layer added.

SculptObject.DeleteSelectedLayer(self)¶

Deletes the currently selected layer (or folder) on the sculpt object (as specified in the Sculpting Layer Manager UI).

Note

If the currently selected layer is a folder then it will only delete the folder if all the layers that are contained in that folder are at the same subdivision level as the current subdivion level.

Return type: bool
Returns: True if the layer was deleted, otherwise False.

SculptObject.GetBaseLayer(self)¶

Get the Base Object layer, which is the special layer that has multiple SculptLayerData children, one for each subdivison level, that allows the user to sculpt on while at any subdivision level.

Return type: c4d.modules.sculpting.SculptLayerBase
Returns: The Base Object layer.

SculptObject.GetCurrentLayer(self)¶

Get the currently layer, or folder, selected for this sculpt object.

Return type: c4d.modules.sculpting.SculptLayerBase
Returns: The current sculpt layer or folder.

SculptObject.GetFirstLayer(self)¶

Get the first layer. This is usually the Base Object layer.

Return type: c4d.modules.sculpting.SculptLayerBase
Returns: The first layer.

Masks And Selection¶

SculptObject.GetMaskCachePoint(self, id)¶

Gets the mask value from the mask cache.

New in version R16.021.

Parameters: id (int) – The index of the point.
Raises: IndexError – If the point index is out of range : 0<=index<GetPointCount().
Return type: float
Returns: The mask cache value.

SculptObject.IsPointSelected(self, index)¶

For use in the SculptBrushToolData.FloodSelectedLayer() method to determine if a point should be moved or not.
When in Point Mode, and there is a selection, it returns True if a point is selected or False if the point is not selected. If there are no points selected it returns True.
When in Polygon Mode, and there is a selection, it returns True if a point on any of the selected polygons is selected or False if there is no point selected. If there are no polygons selected it returns True.
It returns False in all other cases.

New in version R16.021.

Note

This method only works when the selected object being sculpted on is by a tool and is a Polygon Object without a SculptTag.

Parameters: index (int) – The index of the point.
Raises: IndexError – If the point index is out of range : 0<=index<GetPointCount().
Return type: bool
Returns: True if the point was selected, False if not.

SculptObject.IsPolygonSelected(self, index)¶

For use in the SculptBrushToolData.FloodSelectedLayer() method to determine if a point should be moved or not.
When in Polygon Mode, and there is a selection, it returns True if a point on any of the selected polygons is selected or False if there is no point selected.
If there are no polygons selected it returns True. It returns False in all other cases.

New in version R16.021.

Note

This method only works when the selected object being sculpted on is by a tool and is a Polygon Object without a SculptTag.

Parameters: index (int) – The index of the polygon.
Raises: IndexError – If the polygon index is out of range : 0<=index<GetPolygonCount().
Return type: bool
Returns: True if the polygon was selected, False if not.

SculptObject.UpdateMask(self, fullUpdate)¶

Updates the mask on the sculpt object.

New in version R16.021.

Parameters: fullUpdate (bool) – Pass True to force a full update of the mask.

Processing And Resources¶

SculptObject.GetMemoryUsage(self)¶

Get the amount of memory currently used for this sculpt object. This does not include any memory used by the Viewport.

Return type: int
Returns: The memory used in bytes.

SculptObject.InitOpenGL(self, bd)¶

Initializes the sculpt object for the given viewport for OpenGL use. Private.

New in version R16.021.

Parameters: bd (Optional[c4d.BaseDraw]) – The viewport that is being updated. If None then the currently active view will be used.

SculptObject.Smooth(self, count, respectMask)¶

Smooth the sculpt object and apply the offsets to the currently selected layer.

Parameters

count (int) – The number of times to run the smooth algorithm.
respectMask (bool) – True to not smooth any masked out points, False to apply it to every point.

SculptObject.Update(self)¶: Recomposites all the layers and updates the sculpt object.

State Controls¶

SculptObject.GetAllowDeformations(self)¶

Check if the object allows to be deformed by any deformers. This is also able to be set on the SculptTag in Cinema 4D’s UI.

Note

This option only works if the object is also frozen.

When both these options are enabled, any deformers that are children of the polygon object that the sculpt tag is applied to, will be able to deform the object in the viewport.

Return type: bool
Returns: True if the sculpt object allows deformations, otherwise False.

SculptObject.IsFrozen(self)¶

Check if the sculpt object is frozen.

This is also able to be set on the SculptTag in Cinema 4D’s UI.

Return type: bool
Returns: True if the object is frozen, otherwise False.

SculptObject.SetAllowDeformations(self, allowDef)¶

Set the Allow Deformations checkbox thereby allowing any deformers to have an effect on the display of the sculpt object, as long as it is also frozen.

This option can also be found in the SculptTag’s UI.

Parameters: allowDef (bool) – True to allow deformations, otherwise False.

SculptObject.SetFrozen(self, frozen)¶

Sets the frozen state of the sculpt object. In Cinema 4D UI this is shown in the SculptTag. When the object is frozen no changes to the sculpt object or any of its layers are allowed.

Note

If the polygon object has a Phong tag it will also become active when the sculpt object is frozen.

When not Frozen then the sculpt object uses its own internal vertex normals and disables the Phong tag on the polygonobject.

Parameters: frozen (bool) – The frozen state.

Subdivision Management¶

SculptObject.DecreaseSubdivisionLevel(self)¶

Decrease the subdivision level to the down one level.

If it is already at level 0 then it will do nothing.

Return type: bool
Returns: True if it was able go down a level, otherwise False.

SculptObject.GetCurrentLevel(self)¶

Gets the current subdivision level that the sculpt object is currently at.

Return type: int
Returns: The current subdivision level.

SculptObject.GetPointCount(self)¶

Get the number of points at the current subdivision level.

Return type: int
Returns: The number of points.

SculptObject.GetPolygonCopy(self, level, includeTopLevels)¶

Get a copy of the sculpt object at a specific subdivision level.

Parameters

level (int) – The subdivision level to copy the PolygonObject at.
includeTopLevels (bool) –

If True includes all the detail from any layers that are above subdivisionLevel.

If false includes only the sculpting data for all layers up to and including the subdivisionLevel specified.

Return type

c4d.PolygonObject

Returns

The PolygonObject for the subdivision level.

SculptObject.GetPolygonCount(self)¶

Get the number of polygons at the current subdivision level.

Return type: int
Returns: The number of polygons.

SculptObject.GetSubdivisionCount(self)¶

Get the number of subdivisions that this sculpt object currently has; i.e. how many times it has been subdivided by the user.

Return type: int
Returns: The number of subdivision levels.

SculptObject.IncreaseSubdivisionLevel(self)¶

Increase the subdivision level to the next highest level.

If it is already at the top subdivision level then it will do nothing.

Return type: bool
Returns: True if it was able go up a level, otherwise False.

SculptObject.Subdivide(self)¶

Subdivide the sculpt object to the next level.

Note

This method will only work if the sculpt object is already at the top most level and the memory limit (as specified in the preferences) has not been exceeded and also only if there is enough memory on the user’s computer to successfully do the subdivision.

Return type: bool
Returns: True if the object was successfully subdivided, otherwise False.

Undo Management¶

SculptObject.EndUndo(self)¶: Must be called after StartUndo() once all the points and masks have been changed on the layers.

SculptObject.StartUndo(self)¶: Call before any calls to AddOffset(), SetOffset(), AddToMask() or SetMask() if you wish it to be undone.

Warning

This will only work if you are only making changes to a single layer.

Changes to multiple layers or layers at different levels is not allowed.

Note

The method EndUndo() must be called after all calls to the above functions have been done.

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.