c4d.utils.SplineHelp

class c4d.utils.SplineHelp

Methods Signatures

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

Methods Documentation

SplineHelp.__init__(self)
Return type:c4d.utils.SplineHelp
Returns:A new spline help object.
SplineHelp.InitSpline(self, op, up=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.
  • 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(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:c4d.LineObject
Returns:The line object. None if it fails or if the SplineHelp was not initialized with SPLINEHELPFLAGS_RETAINLINEOBJECT