c4d.utils.SplineHelp

Helper class for SplineObject. Designed to allow you to get positions along splines form real world units as well as get non flipping/non gimbal locked matrices and vectors from the spline. Must be inited before use. All values returned are in global space. The slow part is SplineHelp.InitSpline(); other access is pretty fast.

Definition

class c4d.utils.SplineHelp

• SplineHelp.__init__()

• SplineHelp.InitSpline()
• SplineHelp.FreeSpline()

• SplineHelp.Exists()
• SplineHelp.GetSegmentCount()
• SplineHelp.GetVertexMatrix()
• SplineHelp.GetPointValue()
• SplineHelp.GetPointIndex()
• SplineHelp.GetPosition()
• SplineHelp.GetTangent()
• SplineHelp.GetNormal()
• SplineHelp.GetCrossNormal()
• SplineHelp.GetSegmentLength()
• SplineHelp.GetSplineLength()
• SplineHelp.GetOffsetFromUnit()
• SplineHelp.GetOffsetFromReal()
• SplineHelp.SplineToLineIndex()
• SplineHelp.GetSize()
• SplineHelp.GetMatrix()

• SplineHelp.GetVertexCount()
• SplineHelp.GetVertexSize()

Inheritance

• c4d.utils.SplineHelp

Members

SplineHelp.__init__()

Return type: SplineHelp Returns: A new spline help object.

SplineHelp.InitSpline(op, [up=c4d.Vector(0.0)][, rail=None][, target_rail=True][, use_deformed_points=False][, force_update=False][, use_global_space=True])

Call before using the spline help class. (Must be called before any other command.)

Parameters:

• op (SplineObject) – The spline object to use.
• up (Vector) – Optional upvector for the spline normals generation. This is only used at the start of splines/segments; this way it avoids gimbal lock if at all possible.
• rail (BaseObject) – Optional rail spline object for the spline normals generation.
• target_rail (bool) – The optional rail spline is not only used as up-vector but also as target. This is used for instance in MoGraph’s Rail options (Cloner, Spline effector, Spline Wrap etc.).
• use_deformed_points (bool) – Use deformed point positions of the spline.
• force_update (bool) – The spline help class internally caches its own content. Thus it will be much faster if the same splines are used for initialization. However, a full initialization can be forced by setting this parameter to True.
• use_global_space (bool) – If True the resulting matrices are in global space rather than in the spline objects’ local space.

Return type:

bool

Returns:

True if successful, otherwise False.

SplineHelp.FreeSpline()

Called to free the spline data. Recalling InitSpline() or calling SplineHelp.__free__ will automatically call this.

SplineHelp.GetSegmentCount()

Gets the number of segments in the spline.

Note

Unlike the way CINEMA 4D handles segments where a segmenet count of 0 means there’s either no segments or 1 segment, this returns 1 segment if there is 1 and 0 if there are 0.

Return type: int Returns: Segment count.

SplineHelp.Exists()

Useful check to see if the spline helper contains data and has been inited.

Return type: bool Returns: True if the spline helper is ready to use.

SplineHelp.GetSegmentCount()

Get the segment count of the spline.

Return type: int Returns: The count.

SplineHelp.GetVertexMatrix(segment, index)

Retrieves a full matrix for a specific point of the line.

Note

This is not the spline vertex, but instead the line object’s vertex. (Calculated with LOD=1.0.)

Parameters: index (int) – Line object vertex. Raises IndexError:   index must be 0<=index< GetPointCount() Return type: Matrix Returns: Coordinate system matrix at index.

SplineHelp.GetPointValue(offset, segment)

Converts a natural offset value to a real percentage offset value.

Note

This percentage uses the realworld units for its offset, so regardless of how the spline’s points and interpolation is set, a gap of 2% on a 100m long spline will always be 2m whereas normally in spline natural space, a gap of 2% can vary a great deal depending on the spline’s interpolation etc.

Parameters:

• offset (float) – The offset given in spline space.
• segment (int) – The segment index.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

float

Returns:

The realworld percentage offset.

SplineHelp.GetPointIndex(offset, segment)

Retrieves the nearest line point index to the given real offset.

Parameters:

• offset (float) – The offset given in spline space.
• segment (int) – The segment index.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

int

Returns:

The nearest line object point index, rounded down.

SplineHelp.GetPosition(offset[, segment=0][, smooth=True][, realoffset=False])

Retrieves the nearest line point index to the given real offset.

Parameters:

• offset (float) – The offset given in spline space.
• segment (int) – The segment index.
• smooth (bool) – Smoothed position.
• realoffset (bool) – True to use uniform spline distribution.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

Vector

Returns:

The position given by offset in global space.

SplineHelp.GetTangent(offset[, segment=0][, smooth=True][, realoffset=False])

Gets a tangent vector for any point along the spline.

Parameters:

• offset (float) – The offset given in spline space.
• segment (int) – The segment index.
• smooth (bool) – Smoothed tangent.
• realoffset (bool) – True to use uniform spline distribution.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

Vector

Returns:

The tangent given by offset in global space.

SplineHelp.GetNormal(offset[, segment=0][, smooth=True][, realoffset=False])

Gets a normal vector for any point along the spline.

Parameters:

• offset (float) – The offset given in spline space.
• segment (int) – The segment index.
• smooth (bool) – Smoothed normal.
• realoffset (bool) – True to use uniform spline distribution.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

Vector

Returns:

The normal given by offset in global space.

SplineHelp.GetCrossNormal(offset[, segment=0][, smooth=True])

Gets a cross normal vector (i.e. perpendicular to the normal and the tangent) for any point along the spline.

Parameters:

• offset (float) – The offset given in spline space.
• segment (int) – The segment index.
• smooth (bool) – Smoothed cross normal.
• realoffset (bool) – True to use uniform spline distribution.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

Vector

Returns:

The cross normal given by offset in global space.

SplineHelp.GetSegmentLength(segment)

Returns a specific segment’s realworld unit length.

Parameters: segment (int) – Segment index. Raises IndexError:   segment must be 0<=segment< GetSegmentCount() Return type: float Returns: The length of the specified segment.

SplineHelp.GetSplineLength()

Returns the spline’s realworld unit length uncluding all segments.

Return type: float Returns: Spline length.

SplineHelp.GetOffsetFromUnit(unitoffset[, segment=0])

Convert a percentage offset into a natural offset. Percentage offsets ignore spline interpolation etc. and are always x% along the spline.

Parameters:

• unitoffset (float) – A percentage offset, 0<=unitoffset<=1.0.
• segment (int) – The segment index.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

float

Returns:

The natural offset.

SplineHelp.GetOffsetFromReal(offset[, segment=0])

Retrieve an offset from a realworld unit. For example, if a spline is 50 units long, 25 would be 50% of the length, i.e. 0.5

Parameters:

• offset (float) – The real unit offset to convert
• segment (int) – The segment index.

Raises IndexError:  

index must be 0<=index< GetSegmentCount()

Return type:

float

Returns:

The offset in spline space.

SplineHelp.SplineToLineIndex(index)

Converts a spline vertex index to its corresponding line object vertex index.

Parameters: index (int) – The spline vertex index. Return type: int Returns: The line object vertex index.

SplineHelp.GetSize(offset[, segment=0][, smooth=True][, realoffset=False])

Get the distance to an existing rail spline for any point along the spline.

Parameters:

• offset (float) – The spline offset.
• segment (int) – Segment index, 0<=index< GetSegmentCount()
• smooth (bool) – Smoothed position
• realoffset (bool) – True to use uniform spline distribution

Return type:

float

Returns:

The distance given by offset.

SplineHelp.GetMatrix(offset[, segment=0][, smooth=True][, realoffset=False])

Retrieve a full matrix for any point along the spline, constructed as a local coordinate system at that point. Optionally use realworld percentage rather than spline natural space for the offset.

Parameters:

• offset (float) – The spline offset.
• segment (int) – Segment index, 0<=index< GetSegmentCount()
• smooth (bool) – Smoothed position
• realoffset (bool) – True to use uniform spline distribution

Return type:

Matrix

Returns:

Coordinate system matrix at offset.

SplineHelp.GetVertexCount(segment)

Get the number of vertices for a spline segment.

Parameters: segment (int) – The segment index. Raises IndexError:   index must be 0<=index< GetSegmentCount() Return type: int Returns: The number of vertices.

SplineHelp.GetVertexSize(index)

Get the distance to an existing rail spline for a spline vertex specified by index.

Parameters: segment (int) – The segment index. Raises IndexError:   index must be 0<=index< GetVertexCount() Return type: int Returns: The distance given by index.