c4d.modules.sculpting.BrushDabData¶

class c4d.modules.sculpting.BrushDabData¶: The brush data for an individual dab.

New in version R16.021.

Methods Signatures

`BrushDabData.GetData()`	Gets the settings data for the tool.
`BrushDabData.GetObject()`	Gets the Sculpt Object that the dab is for.
`BrushDabData.GetPointData()`	Gets the point at index affected by the brush.
`BrushDabData.GetPolyData()`	Gets the polygon at index affected by the brush.
`BrushDabData.GetPolygonObject()`	Gets the Polygon Object for the Sculpt Object that is currently being displayed in the viewport.
`BrushDabData.GetBaseObject()`	Gets the original object that the Sculpt Tag is applied to.
`BrushDabData.GetPointCount()`	Gets the number of points that are touched by the dab.
`BrushDabData.GetPolyCount()`	Gets the number of polygons that are touched by the dab.
`BrushDabData.GetNeighbor()`	Gets the neighbor information for the Sculpt Object if it is currently at level 0.
`BrushDabData.GetLayer()`	Retrieves the currently selected Layer for a subdivided `SculptObject`.
`BrushDabData.GetPoint()`	Retrieves the live point at index that is modified on the surface during a brush stroke.
`BrushDabData.GetOriginalPoint()`	Retrieves a copy of the point at index in its state before the brush stroke started.
`BrushDabData.GetNormal()`	Gets the normal at the current hitpoint for the dab.
`BrushDabData.GetDrawDirectionNormal()`	If the brush supports the Draw Direction, i.e. the user has set `SculptBrushParams.EnableDrawDirection()` to True, then this returns the direction selected by the user.
`BrushDabData.GetBrushStrength()`	Gets the brush strength for the dab.
`BrushDabData.GetBrushRadius()`	Gets the brush radius for the dab. The size of the radius is in the Sculpt Object local space.
`BrushDabData.GetMousePos3D()`	If the brush mode is SCULPTBRUSHMODE_GRAB then this method can be used to get the location of the mouse pointer in world space in the scene.
`BrushDabData.GetHitPoint()`	Gets the point on the surface of the SculptObject where the dab is going to be placed. This is the center of the dab.
`BrushDabData.GetLastHitPoint()`	Gets the hit point for the previous dab during the stroke.
`BrushDabData.GetHitPolygon()`	Gets the index of the polygon on the surface of the SculptObject where the dab is going to be placed.
`BrushDabData.GetEyePoint()`	Gets the location of the mouse in local space above the model.
`BrushDabData.IsMirroredDab()`	Checks if this dab is for a mirrored brush stroke.
`BrushDabData.GetBrushOverride()`	Gets the override flags. This could be any combination of the OVERRIDE flags.
`BrushDabData.GetBaseDraw()`	Gets the `BaseDraw` that the user is currently drawing in.
`BrushDabData.GetAveragePointAndNormal()`	Gets the average point and normal.
`BrushDabData.GetMirrorPoint()`	Mirror the point (or Normal) from the objects space to the correct location for the current dab.
`BrushDabData.ApplySmooth()`	Applies an effect of the smooth brush to the current dab.
`BrushDabData.GetVertexNormal()`	Gets the vertex normal at index for the Sculpt Object.
`BrushDabData.GetOriginalVertexNormal()`	Gets the state of a vertex normal before the user started a brush stroke.
`BrushDabData.GetFaceNormal()`	Gets the face normal at index for the SculptObject.
`BrushDabData.GetAutoScaleValue()`	Returns a value which represents the scale of the Sculpt Object.
`BrushDabData.GetBrushFalloff()`	Returns the brush falloff for the point specified by the index value.
`BrushDabData.GetBrushFalloffFromPos()`	Returns the falloff value, defined by the falloff curve, based on the distance from pos to the hitpoint for the dab.
`BrushDabData.OffsetPoint()`	Offsets the point on the layer by the given offset amount.
`BrushDabData.IsPreviewDab()`	Checks if this is a preview dab. Currently only DragDab and DragRect draw modes support preview brushes.
`BrushDabData.OffsetPreviewPoint()`	If `IsPreviewDab()` returns True then you should apply your offset using this method.
`BrushDabData.DirtyAllPoints()`	Dirty all the points for this dab according to the flags.
`BrushDabData.IsPointModified()`	When using symmetry another mirrored brush may change the point.
`BrushDabData.GetStencilColor()`	Retrieves the grey value, color and coordinates of the stencil for a point in the Sculpt Object local space.
`BrushDabData.GetStampColor()`	Retrieves the grey value, color and coordinates of the stamp for a point in the Sculpt Object local space.
`BrushDabData.GetStencil()`	Retrieves the stencil bitmap used for this dab.
`BrushDabData.GetStamp()`	Retreves the stamp bitmap used for this dab.
`BrushDabData.GetStrokeInstanceID()`	Gets the ID of the stroke instance that this dab is being drawn for.
`BrushDabData.IsSculptObject()`	Checks if the object being touched is a `SculptObject` (i.e. has a `SculptTag`).
`BrushDabData.IsFillTool()`	Checks if the current draw mode is fill.
`BrushDabData.IsBackface()`	Returns True if the dab is being applied backfacing polygons.

Methods Documentation

BrushDabData.GetData(self)¶

Gets the settings data for the tool.

Return type: c4d.BaseContainer
Returns: The data.

BrushDabData.GetObject(self)¶

Gets the Sculpt Object that the dab is for.

Return type: c4d.modules.sculpting.SculptObject
Returns: The sculpt object.

BrushDabData.GetPointData(self, index)¶

Gets the point at index affected by the brush.

Parameters: index (int) – The index of the point.
Raises: IndexError – If the point index is out of range : 0<=index<GetPointCount().
Return type: dict{pointIndex: int, distance: float}
Returns: The point data index and distance.

BrushDabData.GetPolyData(self, index)¶

Gets the polygon at index affected by the brush.

Parameters: index (int) – The index of the polygon.
Raises: IndexError – If the point index is out of range : 0<=index<GetPolyCount().
Return type: dict{polyIndex: int, distance: float}
Returns: The polygon data index.

BrushDabData.GetPolygonObject(self)¶

Gets the Polygon Object for the Sculpt Object that is currently being displayed in the viewport.

Return type: c4d.PolygonObject
Returns: The Polygon Object.

BrushDabData.GetBaseObject(self)¶

Gets the original object that the Sculpt Tag is applied to.

Note

In the case where this there is no Sculpt Tag on then this will return the same as the call to GetPolygonObject().

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

BrushDabData.GetPointCount(self)¶

Gets the number of points that are touched by the dab.

Return type: int
Returns: The number of points.

BrushDabData.GetPolyCount(self)¶

Gets the number of polygons that are touched by the dab.

Return type: int
Returns: The number of polygons.

BrushDabData.GetNeighbor(self)¶

Gets the neighbor information for the Sculpt Object if it is currently at level 0.

Note

If the user is sculpting a regular unsubdivided Polygon Object then this will also return a neighbor information.

Return type: Optional[c4d.utils.Neighbor]
Returns: The Neighbor information if Sculpt Object is at level 0 (or if the user is sculpting on a regular PolygonObject), otherwise None.

BrushDabData.GetLayer(self)¶

Retrieves the currently selected Layer for a subdivided SculptObject.

Note

If the user is sculpting a regular PolygonObject) then this will return None.

Return type: Optional[c4d.modules.sculpting.SculptLayer]
Returns: The currently selected layer in the LayerManager if it is a subdivided SculptObject, otherwise None.

BrushDabData.GetPoint(self, index)¶

Retrieves the live point at index that is modified on the surface during a brush stroke.

This point may already have been modified by previous brush dabs during the current brush stroke.

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 at index on the PolygonObject that is currently displayed in the viewport.

BrushDabData.GetOriginalPoint(self, index)¶

Retrieves a copy of the point at index in its state before the brush stroke started.

Note

You can use this point to compare where the surface was before the user started sculpting.

As an example this data is used by the grab tool to correctly offset the points based on their original location on the surface at the first mouse click.

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 at index of the PolygonObject at the state it was in when the user first pressed the left mouse button down.

BrushDabData.GetNormal(self)¶

Gets the normal at the current hitpoint for the dab.

This is the average vertex normal of all the points that are affected by the dab.

Return type: c4d.Vector
Returns: The normal at the current hitpoint.

BrushDabData.GetDrawDirectionNormal(self)¶

If the brush supports the Draw Direction, i.e. the user has set SculptBrushParams.EnableDrawDirection() to True, then this returns the direction selected by the user.

Otherwise it just returns the same vector as GetNormal().

Return type: c4d.Vector
Returns: The Draw Direction normal.

BrushDabData.GetBrushStrength(self)¶

Gets the brush strength for the dab.

Warning

This strength is not the same as the strength in the BaseContainer data.

This also takes into account many other variables including tablet pressure to create the value.

Return type: float
Returns: The strength of the brush.

BrushDabData.GetBrushRadius(self)¶

Gets the brush radius for the dab. The size of the radius is in the Sculpt Object local space.

Warning

This is not the same as the brush size in the BaseContainer data.

This also takes into account other factors such as the distance from the camera and scale of the object and tablet values to determine the correct brush radius.

Return type: float
Returns: The radius of the brush.

BrushDabData.GetMousePos3D(self)¶

If the brush mode is SCULPTBRUSHMODE_GRAB then this method can be used to get the location of the mouse pointer in world space in the scene.

Return type: c4d.Vector
Returns: The position of the mouse in world space if the brush mode is SCULPTBRUSHMODE_GRAB, otherwise it returns c4d.Vector(0,0,0).

BrushDabData.GetHitPoint(self)¶

Gets the point on the surface of the SculptObject where the dab is going to be placed. This is the center of the dab.

Note

If the mode is set to SCULPTBRUSHMODE_GRAB then this always returns the initial hit point that occurred when the user first pressed the left mouse button down.

Return type: c4d.Vector
Returns: The hitpoint on the surface.

BrushDabData.GetLastHitPoint(self)¶

Gets the hit point for the previous dab during the stroke.

Return type: c4d.Vector
Returns: The last hitpoint on the surface.

BrushDabData.GetHitPolygon(self)¶

Gets the index of the polygon on the surface of the SculptObject where the dab is going to be placed.

This is the center of the dab.

New in version R17.032.

Return type: int
Returns: The index of the polygon on hit the surface.

BrushDabData.GetEyePoint(self)¶

Gets the location of the mouse in local space above the model.
This point is created by interpolating between previous and next real mouse hitpoint on the surface of the Sculpt Object.
It is then projected down onto the surface of the model to get the real hitpoint for this interpolated value.

Return type: c4d.Vector
Returns: The virtual mouse location in local space above the surface of the SculptObject.

BrushDabData.IsMirroredDab(self)¶

Checks if this dab is for a mirrored brush stroke.

Return type: bool
Returns: True if it’s a mirrored dab or False if it’s the main brush stroke.

BrushDabData.GetBrushOverride(self)¶

Gets the override flags. This could be any combination of the OVERRIDE flags.

Return type: int
Returns: The overrides if there are any or 0 if there are none.

BrushDabData.GetBaseDraw(self)¶

Gets the BaseDraw that the user is currently drawing in.

Return type: int
Returns: The BaseDraw.

BrushDabData.GetAveragePointAndNormal(self)¶

Gets the average point and normal.

Depending on what the Fixed Plane (MDATA_SCULPTBRUSH_SETTINGS_FIXEDPLANE) setting is for the brush this will return one of 3 things:

MDATA_SCULPTBRUSH_SETTINGS_FIXEDPLANE_OFF
- averagePoint = The average location of all the points that are touched by the dab.
- normal = The normal at the hitpoint on the surface of the Sculpt Object.
MDATA_SCULPTBRUSH_SETTINGS_FIXEDPLANE_MOUSEDOWN
- averagePoint = The average location of all the points under the dab area when the mouse was mouse button was first pressed.
- normal = The average normal of all the points under the dab area when the mouse was mouse button was first pressed.
MDATA_SCULPTBRUSH_SETTINGS_FIXEDPLANE_WORKPLANE
- averagePoint = The point on the workplane that is above the hitpoint on the surface of the Sculpt Object.
- normal = The normal of the workplane.

Return type: dict{averagePoint: Vector, normal: Vector}
Returns: The average point and normal based on the Fixed Plane setting.

BrushDabData.GetMirrorPoint(self, point, isNormal)¶

Mirror the point (or Normal) from the objects space to the correct location for the current dab.
This should only be used if you need to get the symmetrically mirrored point for a point that you specifically need.
In most cases this method would never be used because the brush system automatically handles symmetrical points for you.

Parameters

point (c4d.Vector) – The input point, or normal to mirror.
isNormal (bool) – Set to True if point is a normal, so that it will then only be rotated and will not be offset.

Return type

c4d.Vector

Returns

The mirrored point.

BrushDabData.ApplySmooth(self)¶: Applies an effect of the smooth brush to the current dab.

Note

Call this after you have modified the dab to smooth it out if needed.

BrushDabData.GetVertexNormal(self, index)¶

Gets the vertex normal at index for the Sculpt Object.

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.

BrushDabData.GetOriginalVertexNormal(self, index)¶

Gets the state of a vertex normal before the user started a brush stroke.

New in version R17.048.

Parameters: index (int) – The index of the vertex.
Return type: c4d.Vector
Returns: The original vertex normal.

BrushDabData.GetFaceNormal(self, index)¶

Gets the face normal at index for the SculptObject.

New in version R17.032.

Parameters: index (int) – The index of the face.
Return type: c4d.Vector
Returns: The face normal.

BrushDabData.GetAutoScaleValue(self, noRadius)¶

Returns a value which represents the scale of the Sculpt Object.

Note

This can be used to convert a distance in object space with the value returned from GetBrushRadius() to help adjust

the algorithm for your brush since the value returned from GetBrushRadius() is also already adjusted using the same value.

Parameters: noRadius (bool) – True means it will not take into account the radius of the object in its calculation and will only use the scale.
Return type: float
Returns: The scale value with which to adjust your local space vector or distance value.

BrushDabData.GetBrushFalloff(self, index, customDistance=- 1.0)¶

Returns the brush falloff for the point specified by the index value.
The falloff is already adjusted by using the values from the stamp and stencil so it can be used directly to adjust the strength of an offset that you wish to add to the layer.
Internally this method will use the distance that this point is from the hitpoint in its calculation. Pass in a value to customDistance to use a different distance.

Parameters

index (int) – The point data index returned from GetPointData().
customDistance (float) – The custom distance to use instead of the points actual distance from the hitpoint.

Return type

float

Returns

The final falloff value that can be used to adjust the offset value.

BrushDabData.GetBrushFalloffFromPos(self, pos)¶

Returns the falloff value, defined by the falloff curve, based on the distance from pos to the hitpoint for the dab.

Parameters: pos (c4d.Vector) – A point in 3D space to get the falloff for.
Return type: float
Returns: The falloff value.

BrushDabData.OffsetPoint(self, index, offset, respectStrength=0)¶

Offsets the point on the layer by the given offset amount.

Note

This method should be used if IsPreviewDab() returns False, otherwise use OffsetPreviewPoint() instead.

Parameters

index (int) – The index of the point.
offset (c4d.Vector) – The vector to offset the point by.
respectStrength (int) –

Let you use or ignore settings such as the layers mask or strength when offsetting the point. See SCULPTOFFSETFLAGS.

By setting the SCULPTOFFSETFLAGS_IGNOREMASK flag it will ignore whatever the mask checkbox state is for the layer.

Otherwise it uses this state to determine if it should use the mask.

Raises

IndexError – If the point index is out of range : 0<=index<GetPointCount().

BrushDabData.IsPreviewDab(self)¶

Checks if this is a preview dab. Currently only DragDab and DragRect draw modes support preview brushes.

Return type: bool
Returns: True if it is a preview dab, otherwise False.

BrushDabData.OffsetPreviewPoint(self, index, offset)¶

If IsPreviewDab() returns True then you should apply your offset using this method.
If it returns False then you should use OffsetPreviewPoint() instead.
This adds the offset to a temporary preview layer that is created when using the DragDab and DragRect draw modes.

Parameters

index (int) – The index of the point.
offset (c4d.Vector) – The vector to offset the point by.

Raises

IndexError – If the point index is out of range : 0<=index<GetPointCount().

BrushDabData.DirtyAllPoints(self, flags)¶

Dirty all the points for this dab according to the flags.

Parameters: flags (int) – See SCULPTBRUSHDATATYPE.

BrushDabData.IsPointModified(self, index)¶

When using symmetry another mirrored brush may change the point.

You can use this to check if another brush stroke has changed a point and if so then you can do something different for this current stroke.

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 modified, otherwise False.

BrushDabData.GetStencilColor(self, point, mode=0)¶

Retrieves the grey value, color and coordinates of the stencil for a point in the Sculpt Object local space.

Parameters

point (int) – The index of the point.
mode (Optional[int]) – The mode used to sample the stencil texture. See SAMPLEMODE.

Raises

IndexError – If the point index is out of range : 0<=index<GetPointCount().

Return type

dict{grey: Vector, color: Vector, coords: Vector}

Returns

The grey value, color and coords of the stencil.

BrushDabData.GetStampColor(self, point, distance, mode)¶

Retrieves the grey value, color and coordinates of the stamp for a point in the Sculpt Object local space.

Parameters

point (int) – The index of the point.
distance (float) –

Can be either the point data distance value (returned by :GetPointData()), the length of the vector (hitpoint - point) or a custom distance value.

This is used to get the correct falloff for the point.
mode (int) – The mode used to sample the stamp texture. See SAMPLEMODE.

Raises

IndexError – If the point index is out of range : 0<=index<GetPointCount().

Return type

dict{grey: Vector, color: Vector, coords: Vector}

Returns

The grey value (adjusted by the stamps Gray Value), color and coordinates of the stamp.

BrushDabData.GetStencil(self)¶

Retrieves the stencil bitmap used for this dab.

Return type: c4d.bitmaps.BaseBitmap
Returns: The bitmap for the stencil.

BrushDabData.GetStamp(self)¶

Retreves the stamp bitmap used for this dab.

Return type: c4d.bitmaps.BaseBitmap
Returns: The bitmap for the stamp.

BrushDabData.GetStrokeInstanceID(self)¶

Gets the ID of the stroke instance that this dab is being drawn for.

Return type: int
Returns: The stroke instance ID.

BrushDabData.IsSculptObject(self)¶

Checks if the object being touched is a SculptObject (i.e. has a SculptTag).

Return type: bool
Returns: True if the object being touched is a SculptObject, otherwise False.

BrushDabData.IsFillTool(self)¶

Checks if the current draw mode is fill.
Basically checks if the dab MDATA_SCULPTBRUSH_SETTINGS_DRAWMODE setting is:
MDATA_SCULPTBRUSH_SETTINGS_DRAWMODE_LASSO_FILL or
MDATA_SCULPTBRUSH_SETTINGS_DRAWMODE_POLY_FILL or
MDATA_SCULPTBRUSH_SETTINGS_DRAWMODE_RECTANGLE_FILL

Return type: bool
Returns: True if the current draw mode is fill, otherwise False.

BrushDabData.IsBackface(self)¶

Returns True if the dab is being applied backfacing polygons.

New in version R17.032.

Note

Backface polygons will only be sculpted on if the brush has its BackFaceSculpting option enabled and the Backface option is also checked by the user.

Return type: bool
Returns: True if the dab is on backfacing polygons, otherwise False.