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.

Methods Signatures

`SculptObject.GetSubdivisionCount()`	Get the number of subdivisions that this sculpt object currently has; i.e. how many times it has been subdivided by the user.
`SculptObject.GetPolygonCopy()`	Get a copy of the sculpt object at a specific subdivision level.
`SculptObject.GetOriginalObject()`	Get the original `PolygonObject` that the `SculptTag` is applied to.
`SculptObject.GetPolygonCount()`	Get the number of polygons at the current subdivision level.
`SculptObject.GetPointCount()`	Get the number of points at the current subdivision level.
`SculptObject.GetCurrentLevel()`	Gets the current subdivision level that the sculpt object is currently at.
`SculptObject.GetMemoryUsage()`	Get the amount of memory currently used for this sculpt object. This does not include any memory used by the Viewport.
`SculptObject.GetCurrentLayer()`	Get the currently layer, or folder, selected for this sculpt object.
`SculptObject.AddLayer()`	Create a new layer on the sculpt object at the current subdivision level.
`SculptObject.AddFolder()`	Create a new folder for the sculpt object.
`SculptObject.DeleteSelectedLayer()`	Deletes the currently selected layer (or folder) on the sculpt object (as specified in the Sculpting Layer Manager UI).
`SculptObject.Update()`	Recomposites all the layers and updates the sculpt object.
`SculptObject.GetVertexNormal()`	Get the vertex normal for the polygon object at index and at the current subdivision level.
`SculptObject.GetFaceNormal()`	Gets the face normal for the polygon object at index and at the current subdivision level.
`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.Subdivide()`	Subdivide the sculpt object to the next level.
`SculptObject.IncreaseSubdivisionLevel()`	Increase the subdivision level to the next highest level.
`SculptObject.DecreaseSubdivisionLevel()`	Decrease the subdivision level to the down one level.
`SculptObject.GetFirstLayer()`	Get the first layer. This is usually the Base Object layer.
`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.IsFrozen()`	Check if the sculpt object is frozen.
`SculptObject.SetFrozen()`	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.
`SculptObject.GetAllowDeformations()`	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.
`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.UpdateCollision()`	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.
`SculptObject.NeedCollisionUpdate()`	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.
`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.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.StartUndo()`	Call before any calls to `AddOffset()`, `SetOffset()`, `AddToMask()` or `SetMask()` if you wish it to be undone.
`SculptObject.EndUndo()`	Must be called after `StartUndo()` once all the points and masks have been changed on the layers.
`SculptObject.Smooth()`	Smooth the sculpt object and apply the offsets to the currently selected layer.
`SculptObject.GetMaskCachePoint()`	Gets the mask value from the mask cache.
`SculptObject.UpdateMask()`	Updates the mask on the sculpt object.
`SculptObject.InitOpenGL()`	Initializes the sculpt object for the given viewport for OpenGL use. Private.
`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.GetPolygon()`	Gets the Polygon at the given index.
`SculptObject.GetDisplayPolygonObject()`	Retrieves the Polygon Object that is currently being displayed in the viewport.

Inheritance

Parent Class:

c4d.BaseObject

Methods Documentation

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

Get the original PolygonObject that the SculptTag is applied to.

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

SculptObject.GetPolygonCount(self)¶

Get the number of polygons at the current subdivision level.

Return type: int
Returns: The number of polygons.

SculptObject.GetPointCount(self)¶

Get the number of points at the current subdivision level.

Return type: int
Returns: The number of points.

SculptObject.GetCurrentLevel(self)¶

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

Return type: int
Returns: The current subdivision level.

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

Create a new folder for the sculpt object.

Return type: c4d.modules.sculpting.SculptFolder
Returns: The sculpt folder 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.Update(self)¶: Recomposites all the layers and updates the sculpt object.

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.

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

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

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

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

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

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

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

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

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

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

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