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.InitSplineWith()
• SplineHelp.InitSplineWithUpVector()
• SplineHelp.InitSplineWithRail()
• 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()
• SplineHelp.GetDirty()
• SplineHelp.GetPointMatrix()
• SplineHelp.GetLineObject()

Members ¶

SplineHelp. __init__ ( ) ¶

Return type:	c4d.utils.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] ) ¶

Initializes the SplineHelp . Must be called before any other function.

Deprecated since version R17.048.

Instead use the specialized Init() methods: InitSplineWith() , InitSplineWithUpVector() , InitSplineWithRail()

Parameters:	op ( c4d.BaseObject ) – The spline object to use. up ( c4d.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 ( c4d.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. InitSplineWith ( op [ , flags=c4d.SPLINEHELPFLAGS_GLOBALSPACE|c4d.SPLINEHELPFLAGS_CONTINUECURVE ] ) ¶

New in version R17.048.

Initializes the SplineHelp with the passed spline op .

Warning

Must be called before any other function.

Parameters:	op ( c4d.BaseObject ) – The spline object to use. flags ( int ) – The optional flags used to control how the SplineHelp is setup: SPLINEHELPFLAGS_0 No settings. SPLINEHELPFLAGS_USERDEFORMERS Use deformed splines. SPLINEHELPFLAGS_GLOBALSPACE Generate results in global rather than spline local space. SPLINEHELPFLAGS_TARGETRAIL Target the rail spline (if passed). SPLINEHELPFLAGS_CONTINUECURVE Continue the curvature of an existing spline at the end points. SPLINEHELPFLAGS_FORCEUPDATE Force the SplineHelp to recalculate regardless of spline dirtiness. SPLINEHELPFLAGS_RETAINLINEOBJECT Retain a copy of the line object for user usage via SplineHelp.GetLineObject() .
Return type:	bool
Returns:	True if successful, otherwise False .

SplineHelp. InitSplineWithUpVector ( op , upvector [ , flags=c4d.SPLINEHELPFLAGS_GLOBALSPACE|c4d.SPLINEHELPFLAGS_CONTINUECURVE ] ) ¶

New in version R17.048.

Initializes the SplineHelp with the passed spline op and upvector .

Warning

Must be called before any other function.

Parameters:	op ( c4d.BaseObject ) – The spline object to use. upvector ( c4d.Vector ) – The initial up-vector for the spline. flags ( int ) – The optional flags used to control how the SplineHelp is setup: SPLINEHELPFLAGS_0 No settings. SPLINEHELPFLAGS_USERDEFORMERS Use deformed splines. SPLINEHELPFLAGS_GLOBALSPACE Generate results in global rather than spline local space. SPLINEHELPFLAGS_TARGETRAIL Target the rail spline (if passed). SPLINEHELPFLAGS_CONTINUECURVE Continue the curvature of an existing spline at the end points. SPLINEHELPFLAGS_FORCEUPDATE Force the SplineHelp to recalculate regardless of spline dirtiness. SPLINEHELPFLAGS_RETAINLINEOBJECT Retain a copy of the line object for user usage via SplineHelp.GetLineObject() .
Return type:	bool
Returns:	True if successful, otherwise False .

SplineHelp. InitSplineWithRail ( op , rail [ , flags=c4d.SPLINEHELPFLAGS_GLOBALSPACE|c4d.SPLINEHELPFLAGS_CONTINUECURVE ] ) ¶

New in version R17.048.

Initializes the SplineHelp with the passed spline op and rail .

Warning

Must be called before any other function.

Parameters:	op ( c4d.BaseObject ) – The spline object to use. rail ( c4d.BaseObject ) – The rail spline. flags ( int ) – The optional flags used to control how the SplineHelp is setup: SPLINEHELPFLAGS_0 No settings. SPLINEHELPFLAGS_USERDEFORMERS Use deformed splines. SPLINEHELPFLAGS_GLOBALSPACE Generate results in global rather than spline local space. SPLINEHELPFLAGS_TARGETRAIL Target the rail spline (if passed). SPLINEHELPFLAGS_CONTINUECURVE Continue the curvature of an existing spline at the end points. SPLINEHELPFLAGS_FORCEUPDATE Force the SplineHelp to recalculate regardless of spline dirtiness. SPLINEHELPFLAGS_RETAINLINEOBJECT Retain a copy of the line object for user usage via SplineHelp.GetLineObject() .
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. 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 ( ) ¶

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. GetVertexMatrix ( 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’s vertex.
Raises:	IndexError – If the point index is out of range : 0<=segment< PointObject.GetPointCount() .
Return type:	c4d.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 – If segment index is out of range : 0<=segment< 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 – If segment index is out of range : 0<=segment< 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 – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	c4d.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 – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	c4d.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 – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	c4d.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 – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	c4d.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 ) – The segment index.
Raises:	IndexError – If segment index is out of range : 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 ] ) ¶

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:	unitoffset ( float ) – The real unit offset to convert. segment ( int ) – The segment index.
Raises:	IndexError – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	float
Returns:	The offset in spline space.

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

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

Parameters:	offset ( float ) – A percentage offset, 0<=offset<=1.0 . segment ( int ) – The segment index.
Raises:	IndexError – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	float
Returns:	The natural offset.

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 ) – The segment index. smooth ( bool ) – Smoothed position realoffset ( bool ) – True to use uniform spline distribution
Raises:	IndexError – If segment index is out of range : 0<=segment< GetSegmentCount() .
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. smooth ( bool ) – Smoothed position realoffset ( bool ) – True to use uniform spline distribution
Raises:	IndexError – If segment index is out of range : 0<=segment< GetSegmentCount() .
Return type:	c4d.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 – If the segment index is out of range : must be 0<=segment< 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:	index ( int ) – The vertex index.
Raises:	IndexError – If the vertex index is out of range : must be 0<=segment< GetVertexCount() .
Return type:	int
Returns:	The distance given by index .

SplineHelp. GetDirty ( ) ¶

New in version R17.048.

Gets the dirty value for the SplineHelp which indicates how often the help has been updated with new values. i.e. how often the source spline has changed, and or the spline has been cleared.

Return type:	int
Returns:	The dirty checksum.

SplineHelp. GetPointMatrix ( ) ¶

New in version R17.048.

Gets the matrix for a spline vertex.

Parameters:	splineVertexIndex ( int ) – The zero-based index of the spline vertex.
Return type:	c4d.Matrix
Returns:	The resulting matrix for the point along the spline.

SplineHelp. GetLineObject ( ) ¶

New in version R17.048.

Gets a LineObject from SplineHelp functions.

Note

Initializes the SplineHelp with SPLINEHELPFLAGS_RETAINLINEOBJECT for this method to return a line object.

Return type:	c4d.LineObject
Returns:	The line object. None if it fails or if the SplineHelp was not initialized with SPLINEHELPFLAGS_RETAINLINEOBJECT .

Table Of Contents

• c4d.utils.SplineHelp
  • Definition
  • Members