tinyspline.h File Reference

#include <stddef.h>

Include dependency graph for tinyspline.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	tsDeBoorNet
struct	tsBSpline

Typedefs
typedef float	tsRational

Enumerations
enum	tsError {   TS_SUCCESS = 0, TS_MALLOC = -1, TS_DIM_ZERO = -2, TS_DEG_GE_NCTRLP = -3,   TS_U_UNDEFINED = -4, TS_MULTIPLICITY = -5, TS_KNOTS_DECR = -6, TS_NUM_KNOTS = -7,   TS_UNDERIVABLE = -8 }
enum	tsBSplineType { TS_OPENED = 0, TS_CLAMPED = 1, TS_BEZIERS = 2, TS_NONE = 3 }

Functions
void	ts_deboornet_default (tsDeBoorNet *deBoorNet)
void	ts_deboornet_free (tsDeBoorNet *deBoorNet)
void	ts_bspline_default (tsBSpline *bspline)
void	ts_bspline_free (tsBSpline *bspline)
void	ts_bspline_move (tsBSpline *from, tsBSpline *to)
tsError	ts_bspline_new (const size_t deg, const size_t dim, const size_t n_ctrlp, const tsBSplineType type, tsBSpline *bspline)
tsError	ts_bspline_interpolate (const tsRational *points, const size_t n, const size_t dim, tsBSpline *bspline)
tsError	ts_bspline_derive (const tsBSpline *original, tsBSpline *derivative)
tsError	ts_deboornet_copy (const tsDeBoorNet *original, tsDeBoorNet *copy)
tsError	ts_bspline_copy (const tsBSpline *original, tsBSpline *copy)
tsError	ts_bspline_set_ctrlp (const tsBSpline *bspline, const tsRational *ctrlp, tsBSpline *result)
tsError	ts_bspline_set_knots (const tsBSpline *bspline, const tsRational *knots, tsBSpline *result)
tsError	ts_bspline_setup_knots (const tsBSpline *original, const tsBSplineType type, const tsRational min, const tsRational max, tsBSpline *result)
tsError	ts_bspline_evaluate (const tsBSpline *bspline, const tsRational u, tsDeBoorNet *deBoorNet)
tsError	ts_bspline_insert_knot (const tsBSpline *bspline, const tsRational u, const size_t n, tsBSpline *result, size_t *k)
tsError	ts_bspline_resize (const tsBSpline *bspline, const int n, const int back, tsBSpline *resized)
tsError	ts_bspline_split (const tsBSpline *bspline, const tsRational u, tsBSpline *split, size_t *k)
tsError	ts_bspline_buckle (const tsBSpline *original, const tsRational b, tsBSpline *buckled)
tsError	ts_bspline_to_beziers (const tsBSpline *bspline, tsBSpline *beziers)
int	ts_fequals (const tsRational x, const tsRational y)
char *	ts_enum_str (const tsError err)
tsError	ts_str_enum (const char *str)
void	ts_ffill (tsRational *arr, const size_t num, const tsRational val)

Typedef Documentation

typedef float tsRational

Definition at line 19 of file tinyspline.h.

Enumeration Type Documentation

enum tsBSplineType

This enum describes how to fill the knot vector of a spline.

If you don't know what an opened or clamped spline is, take a look at: www.cs.mtu.edu/~shene/COURSES/cs3621/NOTES/spline/B-spline/bspline-curve.html

Enumerator
TS_OPENED
TS_CLAMPED
TS_BEZIERS
TS_NONE

Definition at line 61 of file tinyspline.h.

{
/* setup knots as... */
    TS_OPENED = 0,  /* [uniformly spaced] */
    TS_CLAMPED = 1, /* [u_1 = u_2 = ..., uniformly spaced, ... = u_n-1 = u_n] */
    TS_BEZIERS = 2, /* uniformly spaced with s(u) = order for all u in knots */
    TS_NONE = 3     /* do not setup the knots; they may have any values */
} tsBSplineType;

enum tsError

This enum contains all error codes used by TinySpline.

The following snippet shows how to handle errors: TsError err = ... // any function call here if (err < 0) { // or use err != TS_SUCCESS printf("we got an error!");

// you may want to reuse error codes // over several functions return err; }

Enumerator
TS_SUCCESS
TS_MALLOC
TS_DIM_ZERO
TS_DEG_GE_NCTRLP
TS_U_UNDEFINED
TS_MULTIPLICITY
TS_KNOTS_DECR
TS_NUM_KNOTS
TS_UNDERIVABLE

Definition at line 41 of file tinyspline.h.

{
    TS_SUCCESS = 0,         /* no error */
    TS_MALLOC = -1,         /* malloc/realloc returned null */
    TS_DIM_ZERO = -2,       /* the dimension of the control points are 0 */
    TS_DEG_GE_NCTRLP = -3,  /* degree of spline >= number of control points */
    TS_U_UNDEFINED = -4,    /* spline is not defined at u */
    TS_MULTIPLICITY = -5,   /* the multiplicity of a knot is greater than
                             * the order of the spline */
    TS_KNOTS_DECR = -6,     /* decreasing knot vector */
    TS_NUM_KNOTS = -7,      /* unexpected number of knots */
    TS_UNDERIVABLE = -8     /* spline is not derivable */
} tsError;

Function Documentation

tsError ts_bspline_buckle	(	const tsBSpline *	original,
		const tsRational	b,
		tsBSpline *	buckled
	)

Buckles by and stores the result in .

This function is based on: Holten, Danny. "Hierarchical edge bundles: Visualization of adjacency relations in hierarchical data." Visualization and Computer Graphics, IEEE Transactions on 12.5 (2006): 741-748. Holten calls it "straightening" (page 744, equation 1).

Usually the range of is: 0 <= <= 1, where 0 results in a line between the first and the last control point (no buckle) and 1 keeps the original shape (maximum buckle). If < 0 or > 1 the behaviour is undefined, though it will not result in an error.

This function creates a deep copy of , if != and will never fail if == (always returns TS_SUCCESS).

On error all values of are 0/NULL.

Returns

TS_SUCCESS on success.

TS_MALLOC if != and allocating memory failed.

tsError ts_bspline_copy	(	const tsBSpline *	original,
		tsBSpline *	copy
	)

The copy constructor of tsBSpline.

Creates a deep copy of and stores the result in . This function does not free already allocated memory in . If you want to reuse an instance of tsBSpline by using it in multiple calls of this function, make sure to call ts_bspline_free beforehand.

On error all values of are 0/NULL. The function does nothing if ==

Returns

TS_SUCCESS on success.

TS_MALLOC if allocating memory failed.

void ts_bspline_default

(

tsBSpline *

bspline

)

The default constructor of tsBSpline.

All values of are set to 0/NULL.

tsError ts_bspline_derive	(	const tsBSpline *	original,
		tsBSpline *	derivative
	)

Computes the derivative of . http://www.cs.mtu.edu/~shene/COURSES/cs3621/NOTES/spline/B-spline/bspline-derv.html

The derivative of a spline of degree ->deg with ->n_ctrlp control points and ->n_knots knots is another spline of degree ->deg-1 with ->n_ctrl-1 control points and ->n_knots-2 knots, defined over as C'(u) = Sum_{i=0}^{n-1} N_{i+1,p-1}(u) * (P_{i+1} - P_{i}) * p / (u_{i+p+1}-u_{i+1}) = Sum_{i=1}^{n} N_{i,p-1}(u) * (P_{i} - P_{i-1}) * p / (u_{i+p}-u_{i}) If is clamped, it can be shown that C'(u) = Sum_{i=0}^{n-1} N_{i,p-1}(u) * (P_{i+1} - P_{i}) * p / (u_{i+p+1}-u_{i+1}) where the multiplicity of the first and the last u is p rather than p+1.

This function does not free already allocated memory in . If you want to reuse an instance of tsBSpline by using it in multiple calls of this function, make sure to call ts_deboornet_free beforehand.

On error (and if != ) all values of are 0/NULL.

Returns

TS_SUCCESS on success.

TS_MALLOC if allocating memory failed.

TS_UNDERIVABLE if ->deg < 1 or if ->n_ctrlp < 2 or if the multiplicity of an internal knot of is greater than the degree of . NOTE: This will be fixed in the future.

tsError ts_bspline_evaluate	(	const tsBSpline *	bspline,
		const tsRational	u,
		tsDeBoorNet *	deBoorNet
	)

Evaluates at knot value and stores result in .

This function does not free already allocated memory in . If you want to reuse an instance of tsDeBoorNet by using it in multiple calls of this function, make sure to call ts_deboornet_free beforehand.

On error all values of are 0/NULL.

Returns

TS_SUCCESS on success.

TS_MALLOC if allocating memory failed.

TS_MULTIPLICITY if multiplicity of > order of .

TS_U_UNDEFINED if is not defined at .

void ts_bspline_free

(

tsBSpline *

bspline

)

The destructor of tsBSpline.

Frees all dynamically allocated memory and calls ts_deboornet_free afterwards.

tsError ts_bspline_insert_knot	(	const tsBSpline *	bspline,
		const tsRational	u,
		const size_t	n,
		tsBSpline *	result,
		size_t *	k
	)

tsError ts_bspline_interpolate	(	const tsRational *	points,
		const size_t	n,
		const size_t	dim,
		tsBSpline *	bspline
	)

Performs a cubic spline interpolation using thomas algorithm. https://en.wikipedia.org/wiki/Tridiagonal_matrix_algorithm http://www.math.ucla.edu/~baker/149.1.02w/handouts/dd_splines.pdf http://www.bakoma-tex.com/doc/generic/pst-bspline/pst-bspline-doc.pdf

The resulting spline is a sequence of bezier curves connecting each point in . Each bezier curve is of degree 3 with dimension . The total number of control points is (n-1)*4.

This function does not free already allocated memory in . If you want to reuse an instance of tsBSpline by using it in multiple calls of this function, make sure to call ts_deboornet_free beforehand.

On error all values of are 0/NULL.

Note:
is the number of points in and not the length of .

Returns

TS_SUCCESS on success.

TS_DIM_ZERO if == 0.

TS_DEG_GE_NCTRLP if
< 2.

TS_MALLOC if allocating memory failed.

void ts_bspline_move	(	tsBSpline *	from,
		tsBSpline *	to
	)

The move constructor of tsBSpline.

Moves all values from to and calls ts_bspline_default on afterwards.

tsError ts_bspline_new	(	const size_t	deg,
		const size_t	dim,
		const size_t	n_ctrlp,
		const tsBSplineType	type,
		tsBSpline *	bspline
	)

A convenient constructor for tsBSpline.

Create a new spline of degree with dimension and many control points. This function automatically calculates the necessary number of knots and fills the knot vector according to .

On error all values of are 0/NULL.

Returns

TS_SUCCESS on success.

TS_DIM_ZERO if == 0.

TS_DEG_GE_NCTRLP if >= .

TS_NUM_KNOTS if == TS_BEZIERS and % +1 != 0

TS_MALLOC if allocating memory failed.

tsError ts_bspline_resize	(	const tsBSpline *	bspline,
		const int	n,
		const int	back,
		tsBSpline *	resized
	)

Resizes by
(number of control points) and stores the result in . If != 0 the resulting splines is resized at the end. If == 0 the resulting spline is resized at the front.

Resizing a spline at the end is usually faster, because the current values don't need to be copied.

This function creates a deep copy of , if != .

On error (and if != ) all values of are 0/NULL.

Returns

TS_SUCCESS on success.

TS_DEG_GE_NCTRLP if the degree of would be >= the number of the control points of .

TS_OVER_UNDERFLOW if adding
to the current length of the control point/knot array would cause a over/underflow.

TS_MALLOC if (re)allocating memory failed.

if != :

Returns

TS_DIM_ZERO if the degree of == 0.

TS_DEG_GE_NCTRLP if the degree of >= the number of the control points of .

TS_MALLOC if allocating memory failed.

tsError ts_bspline_set_ctrlp	(	const tsBSpline *	bspline,
		const tsRational *	ctrlp,
		tsBSpline *	result
	)

Creates a deep copy of (only if !=

Returns

) and copies the first bspline->n_ctrlp * bspline->dim control points from to

using memmove. The behaviour of this function is undefined if the length of is less than bspline->n_ctrlp * bspline->dim.

On error (and if !=

Returns

) all values of

are 0/NULL.

TS_SUCCESS on success.

TS_MALLOC if !=

and allocating memory failed.

tsError ts_bspline_set_knots	(	const tsBSpline *	bspline,
		const tsRational *	knots,
		tsBSpline *	result
	)

Creates a deep copy of (only if !=

Returns

) and copies the the first bspline->n_knots from to

using memmove. The behaviour of this function is undefined if the length of is less than bspline->n_knots.

On error (and if !=

Returns

) all values of

are 0/NULL.

TS_SUCCESS on success.

TS_MALLOC if !=

and allocating memory failed.

tsError ts_bspline_setup_knots	(	const tsBSpline *	original,
		const tsBSplineType	type,
		const tsRational	min,
		const tsRational	max,
		tsBSpline *	result
	)

Fills the knot vector of according to with minimum knot value to maximum knot value and stores the result in

Returns

.

This function creates a deep copy of , if !=

Returns

.

On error all values of

Returns

are 0/NULL.

TS_SUCCESS on success.

TS_MALLOC if !=

and allocating memory failed.

TS_DEG_GE_NCTRLP if ->n_knots < 2*(->deg+1). (We can reuse the error code TS_DEG_GE_NCTRLP because n_knots < 2*(deg+1) implies deg >= n_ctrlp. Furthermore, using TS_DEG_GE_NCTRLP instead of TS_NUM_KNOTS ensures that TS_NUM_KNOTS is not used twice for this function. To be more fail-safe, ->deg+1 instead of ->order is used, to make sure that ->deg+1 >= 1)

TS_NUM_KNOTS if == TS_BEZIERS and n_knots % order != 0

TS_KNOTS_DECR if >= . (The function uses ts_fequals in order to determine if == )

tsError ts_bspline_split	(	const tsBSpline *	bspline,
		const tsRational	u,
		tsBSpline *	split,
		size_t *	k
	)

tsError ts_bspline_to_beziers	(	const tsBSpline *	bspline,
		tsBSpline *	beziers
	)

tsError ts_deboornet_copy	(	const tsDeBoorNet *	original,
		tsDeBoorNet *	copy
	)

The copy constructor of tsDeBoorNet.

Creates a deep copy of and stores the result in . This function does not free already allocated memory in . If you want to reuse an instance of tsDeBoorNet by using it in multiple calls of this function, make sure to call ts_deboornet_free beforehand.

On error all values of are 0/NULL. The function does nothing if ==

Returns

TS_SUCCESS on success.

TS_MALLOC if allocating memory failed.

void ts_deboornet_default

(

tsDeBoorNet *

deBoorNet

)

The default constructor of tsDeBoorNet.

All values of are set to 0/NULL.

void ts_deboornet_free

(

tsDeBoorNet *

deBoorNet

)

The destructor of tsDeBoorNet.

Frees all dynamically allocated memory and calls ts_deboornet_default afterwards.

char* ts_enum_str

(

const tsError

err

)

Returns the error message associated to . Returns "unknown error" if is not associated (indicating a bug) or is TS_SUCCESS (which is not an actual error).

int ts_fequals	(	const tsRational	x,
		const tsRational	y
	)

Compares the tsRational values and by using absolute and relative epsilon.

Returns

1 if is equals to .

0 otherwise.

void ts_ffill	(	tsRational *	arr,
		const size_t	num,
		const tsRational	val
	)

Fills the given array with from +0 to + (exclusive).

tsError ts_str_enum

(

const char *

str

)

Returns the error code associated to or TS_SUCCESS if is not associated. Keep in mind that by concept "unknown error" is not associated, though, TS_SUCCESS is returned.