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.
const vector< float > &	getCoefficientComponents () const
	Get the polynomial coefficients components for a spline.
unsigned int	getDegree () const
	Get degree of the spline polynomial.
Vector3	getPoint (float timePoint) const
	Evaluates the value of the spline in the given time point.
unsigned int	getSegmentCount () const
	Get the spline segment count.
bool	isLooping () const
	Indicates whether the spline is looping.

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

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

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

anonymous enum

Enumerator
SplineDimension	This spline implementation is fixed to three dimensions.

Constructor & Destructor Documentation

Spline() [1/2]

kanzi::Spline::Spline ( )

explicitprotected

Construct spline with member values set to 0.

Spline() [2/2]

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

explicitprotected

Construct spline with passed in parameters as member values.

Parameters

degree	Degree of the polynomial.
coefficientComponents	Piecewise polynomial coefficients, where the highest order coefficient is the first element.
looping	Controls whether the spline is looping.

Member Function Documentation

createEmpty()

static SplinePtr kanzi::Spline::createEmpty ( )

static

Creates an empty spline with all members set to zero.

Returns

Unique pointer to the created spline.

create() [1/2]

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

degree	Degree of the polynomial.
coefficients	Polynomial 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).
looping	Controls whether the spline is looping.

Returns

Unique pointer to the created spline.

create() [2/2]

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

degree	Degree of the polynomial.
coefficientComponents	Polynomial 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.
looping	Controls whether the spline is looping.

Returns

Unique pointer to the created spline.

createLinear()

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

controlPoints	Control points as Vector3s.
looping	Controls whether the spline is looping.

Returns

Unique pointer to the created spline.

createCatmullRom() [1/2]

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

controlPoints	Control points as Vector3s.
looping	Controls whether the spline is looping.

Returns

Unique pointer to the created spline.

createCatmullRom() [2/2]

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

controlPointComponents	Control 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.
looping	Controls whether the spline is looping.

Returns

Unique pointer to the created spline.

clone()

SplinePtr kanzi::Spline::clone

(

)

const

Clone this spline and return the cloned spline.

Returns

Unique pointer to the cloned spline.

getSegmentCount()

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.

getPoint()

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

timePoint

Segment index and position inside the segment.

Returns

Value of the spline at the given segment and position.

getCoefficientComponents()

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.

getDegree()

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.

isLooping()

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:

• kanzi/core/math/spline.hpp