c4d.utils.SplineHelp

class c4d.utils.SplineHelp

Overview

Magic Methods

SplineHelp.__init__

Deprecated

SplineHelp.GetPos	Deprecated since version R15: Use SplineHelp.GetPosition().
SplineHelp.InitSpline	Initializes the SplineHelp. Must be called before any other function.

Uncategorized

SplineHelp.InitSplineWith	Initializes the SplineHelp with the passed spline op.
SplineHelp.InitSplineWithUpVector	Initializes the SplineHelp with the passed spline op and upvector.
SplineHelp.InitSplineWithRail	Initializes the SplineHelp with the passed spline op and rail.
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.
SplineHelp.GetSegmentCount	Gets the number of segments in the spline.
SplineHelp.GetVertexMatrix	Retrieves a full matrix for a specific point of the line.
SplineHelp.GetPointValue	Converts a natural offset value to a real percentage offset value.
SplineHelp.GetPointIndex	Retrieves the nearest line point index to the given real offset.
SplineHelp.GetPosition	Retrieves the nearest line point index to the given real offset.
SplineHelp.GetTangent	Gets a tangent vector for any point along the spline.
SplineHelp.GetNormal	Gets a normal vector for any point along the spline.
SplineHelp.GetCrossNormal	Gets a cross normal vector (i.e. perpendicular to the normal and the tangent) for any point along the spline.
SplineHelp.GetSegmentLength	Returns a specific segment’s realworld unit length.
SplineHelp.GetSplineLength	Returns the spline’s realworld unit length including all segments.
SplineHelp.GetOffsetFromUnit	Retrieve an offset from a realworld unit.
SplineHelp.GetOffsetFromReal	Convert a percentage offset into a natural offset.
SplineHelp.SplineToLineIndex	Converts a spline vertex index to its corresponding line object vertex index.
SplineHelp.GetSize	Get the distance to an existing rail spline for any point along the spline.
SplineHelp.GetMatrix	Retrieve a full matrix for any point along the spline, constructed as a local coordinate system at that point.
SplineHelp.GetVertexCount	Get the number of vertices for a spline segment.
SplineHelp.GetVertexSize	Get the distance to an existing rail spline for a spline vertex specified by index.
SplineHelp.GetDirty	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.
SplineHelp.GetPointMatrix	Gets the matrix for a spline vertex.
SplineHelp.GetLineObject	Gets a LineObject from SplineHelp functions.
SplineHelp.GetCacheObject	Gets the cache SplineObject.

Members

SplineHelp.__init__(self)

SplineHelp.GetPos(self, offset, segment=0, smooth=True, realoffset=False)

Deprecated since version R15: Use SplineHelp.GetPosition().

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.InitSpline(self, op, upvector=Vector(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.

• upvector (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 (Optional[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(self, op, flags=SPLINEHELPFLAGS_GLOBALSPACE | SPLINEHELPFLAGS_CONTINUECURVE)

Initializes the SplineHelp with the passed spline op.

New in version R17.048.

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_NONE	None.
  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 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(self, op, upvector, flags=SPLINEHELPFLAGS_GLOBALSPACE | SPLINEHELPFLAGS_CONTINUECURVE)

Initializes the SplineHelp with the passed spline op and upvector.

New in version R17.048.

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_NONE	None.
  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 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(self, op, rail, flags=SPLINEHELPFLAGS_GLOBALSPACE | SPLINEHELPFLAGS_CONTINUECURVE)

Initializes the SplineHelp with the passed spline op and rail.

New in version R17.048.

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_NONE	None.
  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 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(self)

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

SplineHelp.Exists(self)

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(self)

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(self, 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(self, offset, segment)

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

Note

This percentage uses the real world 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(self, 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(self, 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(self, 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(self, 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(self, offset, segment=0, smooth=True, realoffset=False)

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(self, 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(self)

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

Return type

float

Returns

Spline length.

SplineHelp.GetOffsetFromUnit(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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(self, 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(self)

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.

New in version R17.048.

Return type

int

Returns

The dirty checksum.

SplineHelp.GetPointMatrix(self, splineVertexIndex)

Gets the matrix for a spline vertex.

New in version R17.048.

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(self)

Gets a LineObject from SplineHelp functions.

New in version R17.048.

Note

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

Return type

Optional[c4d.LineObject]

Returns

The line object. None if it fails or if the SplineHelp was not initialized with SPLINEHELPFLAGS_RETAINLINEOBJECT

SplineHelp.GetCacheObject(self)

Gets the cache SplineObject.

Useful if you need to access the point array from outside the helper while avoiding duplicating the cache and deform fetch code duplication.

New in version S22.

Note

Initializes the SplineHelp with SplineHelp.InitSpline().

Returns

The cache object or None if it fails or if the SplineHelp was not initialized.

Return type

Optional[c4d.BaseList2D]