Kanzi  3.9.7
Kanzi Engine API
kanzi::Spline Class Reference

Spline is a piecewise polynomial curve that defines a path in a 3-dimensional space. More...

#include <kanzi/core/math/spline.hpp>

Public Types

enum  { SplineDimension }
 

Public Member Functions

SplinePtr clone () const
 Clone this spline and return the cloned spline. More...
 
const vector< float > & getCoefficientComponents () const
 Get the polynomial coefficients components for a spline. More...
 
unsigned int getDegree () const
 Get degree of the spline polynomial. More...
 
Vector3 getPoint (float timePoint) const
 Evaluates the value of the spline in the given time point. More...
 
unsigned int getSegmentCount () const
 Get the spline segment count. More...
 
bool isLooping () const
 Indicates whether the spline is looping. More...
 

Static Public Member Functions

static SplinePtr create (unsigned int degree, const vector< Vector3 > &coefficients, bool looping)
 Creates a spline from polynomial coefficients. More...
 
static SplinePtr create (unsigned int degree, vector< float > coefficientComponents, bool looping)
 Creates a spline from polynomial coefficients. More...
 
static SplinePtr createCatmullRom (vector< Vector3 > controlPoints, bool looping)
 Creates a Catmull-Rom spline with given control points. More...
 
static SplinePtr createCatmullRom (const vector< float > &controlPointComponents, bool looping)
 Creates a Catmull-Rom spline with given control points. More...
 
static SplinePtr createEmpty ()
 Creates an empty spline with all members set to zero. More...
 
static SplinePtr createLinear (const vector< Vector3 > &controlPoints, bool looping)
 Creates a piecewise linear spline with given control points. More...
 

Protected Member Functions

 Spline ()
 Construct spline with member values set to 0. More...
 
 Spline (unsigned int degree, vector< float > coefficientComponents, bool looping)
 Construct spline with passed in parameters as member values. More...
 

Detailed Description

Spline is a piecewise polynomial curve that defines a path in a 3-dimensional space.

The spline consists of any number of piecewise segments. Each piecewise segment of the spline is a polynomial of the form: y = a + b*x + c*x^2 + d*x^3 + ..., where coefficients a,b,c,d... are Vector3 values that define the spline, x is the time point value from range (0,1) that is used to index the spline, and y is the resulting value of the path.

The degree of a polynomial corresponds with the highest coefficient that is nonzero. For example if c is non-zero but coefficients d and higher are all zero, the polynomial is of degree 2.

The shapes that polynomials can make are as follows: degree 0: Constant, only a is non-zero. Example: y = 3, a constant, uniquely defined by one point. degree 1: Linear, b is highest non-zero coefficient. Example: y = 1 + 2*x. A line, uniquely defined by two points. degree 2: Quadratic, c is highest non-zero coefficient. Example: y = 1 - 2*x + x^2. A parabola, uniquely defined by three points. degree 3: Cubic, d is highest non-zero coefficient. Example: y = -1 - 7/(2*x) + 3/(2*x^3). A cubic curve (which can have an inflection, at x = 0 in this example), uniquely defined by four points.

The degree three polynomial - known as a cubic polynomial - is the one that is most typically chosen for constructing smooth curves in computer graphics. It is used because it is the lowest degree polynomial that can support an inflection - so we can make interesting curves, and it is very well behaved numerically - that means that the curves will usually be smooth.

The spline can be defined to be either looping or open. In a looping spline, the last piecewise segment is connected to the first segment, and the time point can be used in a modular fashion. In an open spline, the time point is clamped between the first and last piecewise segment.

Examples

Create a spline from given control points.

// Declare control points for a spline.
vector<Vector3> splinePoints;
splinePoints.push_back(Vector3(0.0f, 0.0f, 0.0f));
splinePoints.push_back(Vector3(1.0f, 0.0f, 0.0f));
splinePoints.push_back(Vector3(3.0f, 1.0f, 0.0f));
splinePoints.push_back(Vector3(5.0f, 1.0f, 1.0f));
splinePoints.push_back(Vector3(4.0f, -1.0f, 0.0f));
splinePoints.push_back(Vector3(2.0f, 0.0f, -1.0f));
splinePoints.push_back(Vector3(6.0f, 0.0f, 0.0f));
splinePoints.push_back(Vector3(3.0f, 0.0f, 0.0f));
// Create a first degree linear non-looping spline.
// The spline control points are moved to the spline to prevent unnecessary copies.
const bool looping = false;
SplinePtr linearSpline = Spline::createLinear(kanzi::move(splinePoints), looping);

Evaluate a spline at a given time point.

// Evaluate the spline at given time point. Use this to get the interpolated Vector3 value at any given time point on the spline.
// This evaluates the spline value at 20% at the 4th piecewise segment. The resulting value will be (4.8f, 0.6f, 0.8f).
const float time = 3.2f;
Vector3 point = linearSpline->getPoint(time);

Member Enumeration Documentation

anonymous enum
Enumerator
SplineDimension 

This spline implementation is fixed to three dimensions.

Constructor & Destructor Documentation

kanzi::Spline::Spline ( )
explicitprotected

Construct spline with member values set to 0.

kanzi::Spline::Spline ( unsigned int  degree,
vector< float >  coefficientComponents,
bool  looping 
)
explicitprotected

Construct spline with passed in parameters as member values.

Parameters
degreeDegree of the polynomial.
coefficientComponentsPiecewise polynomial coefficients, where the highest order coefficient is the first element.
loopingControls whether the spline is looping.

Member Function Documentation

static SplinePtr kanzi::Spline::createEmpty ( )
static

Creates an empty spline with all members set to zero.

Returns
Unique pointer to the created spline.
static SplinePtr kanzi::Spline::create ( unsigned int  degree,
const vector< Vector3 > &  coefficients,
bool  looping 
)
static

Creates a spline from polynomial coefficients.

Compared to the createLinear and createCatmullRom methods, this function is suitable only when you have already precalculated the coefficients.

Parameters
degreeDegree of the polynomial.
coefficientsPolynomial coefficients for each piecewise segment, where the highest order coefficient of the first segment is the first element. This is an vector of polynomials, where each polynomial is an array of coefficients, where each coefficient is a Vector3-value. The number of items in the vector should be a multiple of (degree+1).
loopingControls whether the spline is looping.
Returns
Unique pointer to the created spline.
static SplinePtr kanzi::Spline::create ( unsigned int  degree,
vector< float >  coefficientComponents,
bool  looping 
)
static

Creates a spline from polynomial coefficients.

Compared to the createLinear and createCatmullRom methods, this function is suitable only when you have already precalculated the coefficients.

Parameters
degreeDegree of the polynomial.
coefficientComponentsPolynomial coefficients for each piecewise segment, where the highest order coefficient of the first segment is the first element. This is an vector of polynomials, where each polynomial is an array of coefficients, where each coefficient is a (x,y,z)-value. This 3-dimensional array is given as flattened to 1-dimension: coefficients[segment][degree][dimension] -> coefficientComponents[segment * degree * dimension]. The number of items in the vector should be a multiple of (degree+1)*dimension.
loopingControls whether the spline is looping.
Returns
Unique pointer to the created spline.
static SplinePtr kanzi::Spline::createLinear ( const vector< Vector3 > &  controlPoints,
bool  looping 
)
static

Creates a piecewise linear spline with given control points.

Use this to create a spline that goes linearly through all the given control points.

Parameters
controlPointsControl points as Vector3s.
loopingControls whether the spline is looping.
Returns
Unique pointer to the created spline.
static SplinePtr kanzi::Spline::createCatmullRom ( vector< Vector3 controlPoints,
bool  looping 
)
static

Creates a Catmull-Rom spline with given control points.

The Catmull-Rom spline is a cubic spline that goes through all the given control points. It is a Hermite spline where tangents are calculated automatically as t_n = (p_(n+1) - p_(n-1)) / 2. If looping is disabled, first and last tangents are calculated simply t_0 = p_1 - p_0 and t_N = p_N - p_N-1.

Parameters
controlPointsControl points as Vector3s.
loopingControls whether the spline is looping.
Returns
Unique pointer to the created spline.
static SplinePtr kanzi::Spline::createCatmullRom ( const vector< float > &  controlPointComponents,
bool  looping 
)
static

Creates a Catmull-Rom spline with given control points.

The Catmull-Rom spline is a cubic spline that goes through all the given control points. It is a Hermite spline where tangents are calculated automatically as t_n = (p_(n+1) - p_(n-1)) / 2. If looping is disabled, first and last tangents are calculated simply t_0 = p_1 - p_0 and t_N = p_N - p_N-1.

Parameters
controlPointComponentsControl points as a 2-dimensional array that is flattened to 1-dimension: controlPoints[point][dimension] -> controlPointComponents[point * dimension]. The number of items in the vector should be a multiple of dimension.
loopingControls whether the spline is looping.
Returns
Unique pointer to the created spline.
SplinePtr kanzi::Spline::clone ( ) const

Clone this spline and return the cloned spline.

Returns
Unique pointer to the cloned spline.
unsigned int kanzi::Spline::getSegmentCount ( ) const

Get the spline segment count.

Use this to find out how many distinct segments a spline has. The spline consists of segments between the points: A looping spline has as many segments as control points, and a non-looping spline has one segment less.

Returns
Segment count of the spline.
Vector3 kanzi::Spline::getPoint ( float  timePoint) const

Evaluates the value of the spline in the given time point.

Integer part of time point defines the segment index and decimal part of time point defines the location in that segment. Use getSegmentCount to get the number of segments. In a non-looping spline, the segment index is clamped to valid values. In a looping spline, the valid segment indices are extended with modular arithmetic.

Parameters
timePointSegment index and position inside the segment.
Returns
Value of the spline at the given segment and position.
const vector<float>& kanzi::Spline::getCoefficientComponents ( ) const

Get the polynomial coefficients components for a spline.

Returns
One-dimensional array of control point components ordered by: segment, degree, and dimension.
unsigned int kanzi::Spline::getDegree ( ) const

Get degree of the spline polynomial.

Use this to get what degree of polynomial equation a spline uses.

Returns
Degree of the spline.
bool kanzi::Spline::isLooping ( ) const

Indicates whether the spline is looping.

Returns
True if the spline loops itself in the end and forms a closed path, false if not.

The documentation for this class was generated from the following file: