TinySpline
Spline Library for a Multitude of Programming Languages
v0.3.0
Classes | Macros | Typedefs | Enumerations | Functions
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  tsStatus
 
struct  tsBSpline
 
struct  tsDeBoorNet
 

Macros

#define TS_MAX_NUM_KNOTS   10000
 
#define TS_DOMAIN_DEFAULT_MIN   0.0f
 
#define TS_DOMAIN_DEFAULT_MAX   1.0f
 
#define TS_KNOT_EPSILON   1e-4f
 
#define TS_CONTROL_POINT_EPSILON   1e-6f
 
#define TS_TRY(label, error, status)
 
#define TS_CALL(label, error, call)
 
#define TS_CATCH(error)   } if ((error)) {
 
#define TS_FINALLY   } {
 
#define TS_END_TRY
 
#define TS_END_TRY_RETURN(error)   TS_END_TRY return (error);
 
#define TS_END_TRY_ROE(error)   TS_END_TRY if ((error)) return error;
 
#define TS_CALL_ROE(error, call)
 
#define TS_RETURN_SUCCESS(status)
 
#define TS_RETURN_0(status, error, msg)
 
#define TS_RETURN_1(status, error, msg, arg1)
 
#define TS_RETURN_2(status, error, msg, arg1, arg2)
 
#define TS_RETURN_3(status, error, msg, arg1, arg2, arg3)
 
#define TS_THROW_0(label, error, status, val, msg)
 
#define TS_THROW_1(label, error, status, val, msg, arg1)
 
#define TS_THROW_2(label, error, status, val, msg, arg1, arg2)
 
#define TS_THROW_3(label, error, status, val, msg, arg1, arg2, arg3)
 

Typedefs

typedef double tsReal
 

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, TS_LCTRLP_DIM_MISMATCH = -10, TS_IO_ERROR = -11, TS_PARSE_ERROR = -12,
  TS_INDEX_ERROR = -13, TS_NO_RESULT = -14, TS_NUM_POINTS = -15
}
 
enum  tsBSplineType { TS_OPENED = 0, TS_CLAMPED = 1, TS_BEZIERS = 2 }
 

Functions

size_t ts_bspline_degree (const tsBSpline *spline)
 
tsError ts_bspline_set_degree (tsBSpline *spline, size_t deg, tsStatus *status)
 
size_t ts_bspline_order (const tsBSpline *spline)
 
tsError ts_bspline_set_order (tsBSpline *spline, size_t order, tsStatus *status)
 
size_t ts_bspline_dimension (const tsBSpline *spline)
 
tsError ts_bspline_set_dimension (tsBSpline *spline, size_t dim, tsStatus *status)
 
size_t ts_bspline_len_control_points (const tsBSpline *spline)
 
size_t ts_bspline_num_control_points (const tsBSpline *spline)
 
size_t ts_bspline_sof_control_points (const tsBSpline *spline)
 
tsError ts_bspline_control_points (const tsBSpline *spline, tsReal **ctrlp, tsStatus *status)
 
tsError ts_bspline_control_point_at (const tsBSpline *spline, size_t index, tsReal **ctrlp, tsStatus *status)
 
tsError ts_bspline_set_control_points (tsBSpline *spline, const tsReal *ctrlp, tsStatus *status)
 
tsError ts_bspline_set_control_point_at (tsBSpline *spline, size_t index, const tsReal *ctrlp, tsStatus *status)
 
size_t ts_bspline_num_knots (const tsBSpline *spline)
 
size_t ts_bspline_sof_knots (const tsBSpline *spline)
 
tsError ts_bspline_knots (const tsBSpline *spline, tsReal **knots, tsStatus *status)
 
tsError ts_bspline_knot_at (const tsBSpline *spline, size_t index, tsReal *knot, tsStatus *status)
 
tsError ts_bspline_set_knots (tsBSpline *spline, const tsReal *knots, tsStatus *status)
 
tsError ts_bspline_set_knot_at (tsBSpline *spline, size_t index, tsReal knot, tsStatus *status)
 
tsReal ts_deboornet_knot (const tsDeBoorNet *net)
 
size_t ts_deboornet_index (const tsDeBoorNet *net)
 
size_t ts_deboornet_multiplicity (const tsDeBoorNet *net)
 
size_t ts_deboornet_num_insertions (const tsDeBoorNet *net)
 
size_t ts_deboornet_dimension (const tsDeBoorNet *net)
 
size_t ts_deboornet_len_points (const tsDeBoorNet *net)
 
size_t ts_deboornet_num_points (const tsDeBoorNet *net)
 
size_t ts_deboornet_sof_points (const tsDeBoorNet *net)
 
tsError ts_deboornet_points (const tsDeBoorNet *net, tsReal **points, tsStatus *status)
 
size_t ts_deboornet_len_result (const tsDeBoorNet *net)
 
size_t ts_deboornet_num_result (const tsDeBoorNet *net)
 
size_t ts_deboornet_sof_result (const tsDeBoorNet *net)
 
tsError ts_deboornet_result (const tsDeBoorNet *net, tsReal **result, tsStatus *status)
 
tsBSpline ts_bspline_init ()
 
tsError ts_bspline_new (size_t num_control_points, size_t dimension, size_t degree, tsBSplineType type, tsBSpline *spline, tsStatus *status)
 
tsError ts_bspline_copy (const tsBSpline *src, tsBSpline *dest, tsStatus *status)
 
void ts_bspline_move (tsBSpline *src, tsBSpline *dest)
 
void ts_bspline_free (tsBSpline *spline)
 
tsDeBoorNet ts_deboornet_init ()
 
tsError ts_deboornet_copy (const tsDeBoorNet *src, tsDeBoorNet *dest, tsStatus *status)
 
void ts_deboornet_move (tsDeBoorNet *src, tsDeBoorNet *dest)
 
void ts_deboornet_free (tsDeBoorNet *net)
 
tsError ts_bspline_interpolate_cubic_natural (const tsReal *points, size_t num_points, size_t dimension, tsBSpline *spline, tsStatus *status)
 
tsError ts_bspline_interpolate_catmull_rom (const tsReal *points, size_t num_points, size_t dimension, tsReal alpha, const tsReal *first, const tsReal *last, tsReal epsilon, tsBSpline *spline, tsStatus *status)
 
tsError ts_bspline_eval (const tsBSpline *spline, tsReal u, tsDeBoorNet *net, tsStatus *status)
 
tsError ts_bspline_eval_all (const tsBSpline *spline, const tsReal *us, size_t num, tsReal **points, tsStatus *status)
 
tsError ts_bspline_sample (const tsBSpline *spline, size_t num, tsReal **points, size_t *actual_num, tsStatus *status)
 
tsError ts_bspline_bisect (const tsBSpline *spline, tsReal value, tsReal epsilon, int persnickety, size_t index, int ascending, size_t max_iter, tsDeBoorNet *net, tsStatus *status)
 
void ts_bspline_domain (const tsBSpline *spline, tsReal *min, tsReal *max)
 
tsError ts_bspline_is_closed (const tsBSpline *spline, tsReal epsilon, int *closed, tsStatus *status)
 
tsError ts_bspline_derive (const tsBSpline *spline, size_t n, tsReal epsilon, tsBSpline *derivative, tsStatus *status)
 
tsError ts_bspline_insert_knot (const tsBSpline *spline, tsReal u, size_t num, tsBSpline *result, size_t *k, tsStatus *status)
 
tsError ts_bspline_split (const tsBSpline *spline, tsReal u, tsBSpline *split, size_t *k, tsStatus *status)
 
tsError ts_bspline_tension (const tsBSpline *spline, tsReal tension, tsBSpline *out, tsStatus *status)
 
tsError ts_bspline_to_beziers (const tsBSpline *spline, tsBSpline *beziers, tsStatus *status)
 
tsError ts_bspline_to_json (const tsBSpline *spline, char **_json_, tsStatus *status)
 
tsError ts_bspline_from_json (const char *json, tsBSpline *spline, tsStatus *status)
 
tsError ts_bspline_save (const tsBSpline *spline, const char *path, tsStatus *status)
 
tsError ts_bspline_load (const char *path, tsBSpline *spline, tsStatus *status)
 
int ts_knots_equal (tsReal x, tsReal y)
 
void ts_arr_fill (tsReal *arr, size_t num, tsReal val)
 
tsReal ts_distance (const tsReal *x, const tsReal *y, size_t dimension)
 

Macro Definition Documentation

◆ TS_CALL

#define TS_CALL (   label,
  error,
  call 
)
Value:
(error) = (call); \
if ((error)) goto __ ## label ## __;

◆ TS_CALL_ROE

#define TS_CALL_ROE (   error,
  call 
)
Value:
{ \
(error) = (call); \
if ((error)) return error; \
}

◆ TS_CONTROL_POINT_EPSILON

#define TS_CONTROL_POINT_EPSILON   1e-6f

If the distance between two control points is less than or equal to this threshold, they are considered equal. This constant is not used directly by any function of the C interface but is intended to provide a reasonable default value for functions requiring an epsilon environment for comparing control points (the C++ interface, for example, uses this as default value for its optional parameters).

◆ TS_DOMAIN_DEFAULT_MAX

#define TS_DOMAIN_DEFAULT_MAX   1.0f

Default maximum of a spline's domain. This constant is used when setting up new splines. Must be greater than TS_DOMAIN_DEFAULT_MIN

◆ TS_DOMAIN_DEFAULT_MIN

#define TS_DOMAIN_DEFAULT_MIN   0.0f

Default minimum of a spline's domain. This constant is used when setting up new splines. Must be less than TS_DOMAIN_DEFAULT_MAX.

◆ TS_END_TRY

#define TS_END_TRY
Value:
} \
}

◆ TS_KNOT_EPSILON

#define TS_KNOT_EPSILON   1e-4f

If the distance between two knots falls below this threshold, they are considered equal. Must be positive ( > 0 ).

◆ TS_MAX_NUM_KNOTS

#define TS_MAX_NUM_KNOTS   10000

Maximum number of knots of a spline.

◆ TS_RETURN_0

#define TS_RETURN_0 (   status,
  error,
  msg 
)
Value:
{ \
if ((status) != NULL) { \
(status)->code = error; \
sprintf((status)->message, msg); \
} \
return error; \
}

◆ TS_RETURN_1

#define TS_RETURN_1 (   status,
  error,
  msg,
  arg1 
)
Value:
{ \
if ((status) != NULL) { \
(status)->code = error; \
sprintf((status)->message, msg, arg1); \
} \
return error; \
}

◆ TS_RETURN_2

#define TS_RETURN_2 (   status,
  error,
  msg,
  arg1,
  arg2 
)
Value:
{ \
if ((status) != NULL) { \
(status)->code = error; \
sprintf((status)->message, msg, arg1, arg2); \
} \
return error; \
}

◆ TS_RETURN_3

#define TS_RETURN_3 (   status,
  error,
  msg,
  arg1,
  arg2,
  arg3 
)
Value:
{ \
if ((status) != NULL) { \
(status)->code = error; \
sprintf((status)->message, msg, arg1, arg2, arg3); \
} \
return error; \
}

◆ TS_RETURN_SUCCESS

#define TS_RETURN_SUCCESS (   status)
Value:
{ \
if ((status) != NULL) { \
(status)->code = TS_SUCCESS; \
(status)->message[0] = '\0'; \
} \
return TS_SUCCESS; \
}
Definition: tinyspline.h:108

◆ TS_THROW_0

#define TS_THROW_0 (   label,
  error,
  status,
  val,
  msg 
)
Value:
{ \
(error) = val; \
if ((status) != NULL) { \
(status)->code = val; \
sprintf((status)->message, msg); \
} \
goto __ ## label ## __; \
}

◆ TS_THROW_1

#define TS_THROW_1 (   label,
  error,
  status,
  val,
  msg,
  arg1 
)
Value:
{ \
(error) = val; \
if ((status) != NULL) { \
(status)->code = val; \
sprintf((status)->message, msg, arg1); \
} \
goto __ ## label ## __; \
}

◆ TS_THROW_2

#define TS_THROW_2 (   label,
  error,
  status,
  val,
  msg,
  arg1,
  arg2 
)
Value:
{ \
(error) = val; \
if ((status) != NULL) { \
(status)->code = val; \
sprintf((status)->message, msg, arg1, arg2); \
} \
goto __ ## label ## __; \
}

◆ TS_THROW_3

#define TS_THROW_3 (   label,
  error,
  status,
  val,
  msg,
  arg1,
  arg2,
  arg3 
)
Value:
{ \
(error) = val; \
if ((status) != NULL) { \
(status)->code = val; \
sprintf((status)->message, msg, arg1, arg2, arg3); \
} \
goto __ ## label ## __; \
}

◆ TS_TRY

#define TS_TRY (   label,
  error,
  status 
)
Value:
{ \
(error) = TS_SUCCESS; \
if ((status) != NULL) { \
(status)->code = TS_SUCCESS; \
(status)->message[0] = '\0'; \
} \
__ ## label ## __: \
if (!(error)) {
Definition: tinyspline.h:108

Enumeration Type Documentation

◆ tsBSplineType

Describes the structure of the knot vector of a NURBS/B-Spline. For more details, see:

www.cs.mtu.edu/~shene/COURSES/cs3621/NOTES/spline/B-spline/bspline-curve.html

◆ tsError

enum tsError

Defines different error codes.

Enumerator
TS_SUCCESS 

No error.

TS_MALLOC 

Unable to allocate memory.

TS_DIM_ZERO 

Points with dimensionality 0.

TS_DEG_GE_NCTRLP 

degree >= num_control_points.

TS_U_UNDEFINED 

Undefined knot value.

TS_MULTIPLICITY 

multiplicity(u) > order

TS_KNOTS_DECR 

Decreasing knot vector.

TS_NUM_KNOTS 

Unexpected number of knots.

TS_UNDERIVABLE 

Spline is not derivable.

TS_LCTRLP_DIM_MISMATCH 

len_control_points % dim != 0.

TS_IO_ERROR 

Error while reading/writing a file.

TS_PARSE_ERROR 

Error while parsing a serialized entity.

TS_INDEX_ERROR 

Index does not exist.

TS_NO_RESULT 

Function returns without result.

TS_NUM_POINTS 

Unexpected number of points.

Function Documentation

◆ ts_arr_fill()

void ts_arr_fill ( tsReal *  arr,
size_t  num,
tsReal  val 
)

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

Parameters
[in]arrThe array to fill.
[in]numThe fill length.
[in]valThe value to fill into arr.

◆ ts_bspline_bisect()

tsError ts_bspline_bisect ( const tsBSpline spline,
tsReal  value,
tsReal  epsilon,
int  persnickety,
size_t  index,
int  ascending,
size_t  max_iter,
tsDeBoorNet net,
tsStatus status 
)

Tries to find a point P on spline such that:

ts_distance(P[index], value, 1) <= fabs(epsilon)

This function is using the bisection method to determine P. Accordingly, it is expected that the control points of spline are sorted at component index either in ascending order (if ascending != 0) or in descending order (if ascending == 0). If the control points of spline are not sorted at component index, the behaviour of this function is undefined. For the sake of fail-safeness, the distance of P[index] and value is compared with the absolute value of epsilon (using fabs).

The bisection method is an iterative approach which minimizes the error (epsilon) with each iteration step until an "optimum" was found. However, there may be no point P satisfying the distance condition. Thus, the number of iterations must be limited (max_iter). Depending on the domain of the control points of spline at component index and epsilon, max_iter ranges from 7 to 50. In most cases max_iter == 30 should be fine though. The parameter persnickety allows to define the behaviour of this function is case no point was found after max_iter iterations. If enabled (!= 0), TS_NO_RESULT is returned. If disabled (== 0), the best fitting point is returned.

Parameters
[in]splineThe spline to evaluate
[in]valueThe value (point at component index) to find.
[in]epsilonThe maximum distance (inclusive).
[in]persnicketyIndicates whether TS_NO_RESULT should be returned if there is no point P satisfying the distance condition (!= 0 to enable, == 0 to disable). If disabled, the best fitting point is returned.
[in]indexThe point's component.
[in]ascendingIndicates whether the control points of spline are sorted in ascending (!= 0) or in descending (== 0) order at component index.
[in]max_iterThe maximum number of iterations (30 is a sane default value).
[out]netThe output parameter.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_INDEX_ERROR If the dimension of the control points of spline <= index.
TS_NO_RESULT If persnickety is enabled (!= 0) and there is no point P satisfying the distance condition.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_control_point_at()

tsError ts_bspline_control_point_at ( const tsBSpline spline,
size_t  index,
tsReal **  ctrlp,
tsStatus status 
)

Returns a deep copy of the control point of spline at index.

Parameters
[in]splineThe spline whose control point is read at index.
[in]indexThe zero-based index of the control point to return.
[out]ctrlpThe output array.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_INDEX_ERROR If index is out of range.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_control_points()

tsError ts_bspline_control_points ( const tsBSpline spline,
tsReal **  ctrlp,
tsStatus status 
)

Returns a deep copy of the control points of spline.

Parameters
[in]splineThe spline whose control points are read.
[out]ctrlpThe output array.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_copy()

tsError ts_bspline_copy ( const tsBSpline src,
tsBSpline dest,
tsStatus status 
)

Creates a deep copy of src and stores the copied values in dest. Does nothing, if src == dest.

Parameters
[in]srcThe spline to deep copy.
[out]destThe output spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_degree()

size_t ts_bspline_degree ( const tsBSpline spline)

Returns the degree of spline.

Parameters
[in]splineThe spline whose degree is read.
Returns
The degree of spline.

◆ ts_bspline_derive()

tsError ts_bspline_derive ( const tsBSpline spline,
size_t  n,
tsReal  epsilon,
tsBSpline derivative,
tsStatus status 
)

Returns the n'th derivative of spline and stores the result in derivative. Creates a deep copy of spline if spline != derivative. For more details, see:

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

The derivative of a spline s of degree d (d > 0) with m control points and n knots is another spline s' of degree d-1 with m-1 control points and n-2 knots, defined over s as:

\begin{eqnarray*} s'(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}) \end{eqnarray*}

If s has a clamped knot vector, it can be shown that:

\begin{eqnarray*} s'(u) &=& \sum_{i=0}^{n-1} N_{i,p-1}(u) * (P_{i+1} - P_{i}) * p / (u_{i+p+1}-u_{i+1}) \end{eqnarray*}

where the multiplicity of the first and the last knot value u is p rather than p+1. The derivative of a point (degree == 0) is another point with coordinate 0.

Parameters
[in]splineThe spline to derive.
[in]nThe number of derivations.
[in]epsilonThe maximum distance of discontinuous points. If negative, discontinuity is ignored and the derivative is computed based on the first result of the corresponding DeBoorNet.
[out]derivativeThe derivative of spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_UNDERIVABLE If spline is discontinuous at an internal knot and the distance between the corresponding points is greater than epsilon.
TS_MALLOC If allocating memory failed.

< Stores the intermediate result.

< Pointer to the control points of worker.

< Pointer to the knots of worker.

< Used in for loops.

< Pointer to first and second control point.

< Distance between fst and snd.

< Knots at i+deg+1 and i+1.

< Distance between kid1 and ki1.

< Used to swap worker and derivative.

◆ ts_bspline_dimension()

size_t ts_bspline_dimension ( const tsBSpline spline)

Returns the dimension of spline. The dimension of a spline describes the number of components for each point in ts_bspline_get_control_points(spline). One-dimensional splines are possible, albeit their benefit might be questionable.

Parameters
[in]splineThe spline whose dimension is read.
Returns
The dimension of spline.

◆ ts_bspline_domain()

void ts_bspline_domain ( const tsBSpline spline,
tsReal *  min,
tsReal *  max 
)

Returns the domain of spline.

Parameters
[in]splineThe spline to query.
[out]minThe lower bound of the domain of spline.
[out]maxThe upper bound of the domain of spline.

◆ ts_bspline_eval()

tsError ts_bspline_eval ( const tsBSpline spline,
tsReal  u,
tsDeBoorNet net,
tsStatus status 
)

Evaluates spline at knot u and stores the result (cf. tsDeBoorNet) in net.

Parameters
[in]splineThe spline to evaluate.
[in]uThe knot to evaluate spline at.
[out]netThe output parameter
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_U_UNDEFINED If spline is not defined at knot value u.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_eval_all()

tsError ts_bspline_eval_all ( const tsBSpline spline,
const tsReal *  us,
size_t  num,
tsReal **  points,
tsStatus status 
)

Evaluates spline at knots us and stores the resultant points in points. If us contains one or more knots where spline is discontinuous at, only the first point of the corresponding evaluation result is taken. After calling this function points contains exactly num * ts_bspline_dimension(spline) values.

This function is in particular useful in cases where a multitude of knots need to be evaluated, because only a single instance of tsDeBoorNet is created and reused for all evaluation tasks (therefore the memory footprint is reduced to a minimum).

Parameters
[in]splineThe spline to evaluate.
[in]usThe knot values to evaluate.
[in]numThe number of knots in us.
[out]pointsThe output parameter.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_U_UNDEFINED If spline is not defined at one of the knot values in us.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_free()

void ts_bspline_free ( tsBSpline spline)

Frees the data of spline. After calling this function, the data of spline points to NULL.

Parameters
[out]splineThe spline to free.

◆ ts_bspline_from_json()

tsError ts_bspline_from_json ( const char *  json,
tsBSpline spline,
tsStatus status 
)

Parses json and stores the result in spline.

Parameters
[in]jsonThe JSON string to parse.
[out]splineThe deserialized spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_PARSE_ERROR If an error occurred while parsing json.
TS_DIM_ZERO If the dimension is 0.
TS_LCTRLP_DIM_MISMATCH If the length of the control point vector modulo dimension is not 0.
TS_DEG_GE_NCTRLP If the degree is greater or equals to the number of control points.
TS_NUM_KNOTS If the number of knots stored in json does not match to the number of control points and the degree of the spline.
TS_KNOTS_DECR If the knot vector is decreasing.
TS_MULTIPLICITY If there is a knot with multiplicity greater than order.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_init()

tsBSpline ts_bspline_init ( )

Creates a new spline whose data points to NULL.

Returns
A new spline whose data points to NULL.

◆ ts_bspline_insert_knot()

tsError ts_bspline_insert_knot ( const tsBSpline spline,
tsReal  u,
size_t  num,
tsBSpline result,
size_t *  k,
tsStatus status 
)

Inserts the knot u up to num times into the knot vector of spline and stores the result in result. Creates a deep copy of spline if spline != result.

Parameters
[in]splineThe spline with its knot vector into which u is inserted up to num times.
[in]uThe knot to insert.
[in]numHow many times u should be inserted.
[out]resultThe output spline.
[out]kStores the last index of u in result.
statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_interpolate_catmull_rom()

tsError ts_bspline_interpolate_catmull_rom ( const tsReal *  points,
size_t  num_points,
size_t  dimension,
tsReal  alpha,
const tsReal *  first,
const tsReal *  last,
tsReal  epsilon,
tsBSpline spline,
tsStatus status 
)

Interpolates a piecewise cubic spline by translating the given catmull-rom control points into a sequence of bezier curves. In order to avoid division by zero, successive control points with distance less than or equal to epsilon are filtered out. If the resultant sequence contains only a single point, a spline of degree 0 (a point) is created. Optionally, the first and last control point can be specified (first and last).

Parameters
[in]pointsThe points to interpolate.
[in]num_pointsThe number of points in points.
[in]dimensionThe dimensionality of the points.
[in]alphaThe knot parameterization: 0 => uniform, 0.5 => centripetal, 1 => chordal. The input value is automatically trimmed to the [0, 1] interval.
[in]firstThe first control point of the catmull-rom sequence. If NULL, an appropriate point is generated based on the first two points in points. If the distance between first and the first control point in points is less than or equals to epsilon, first is treated as NULL. This is necessary to avoid division by zero.
[in]lastThe last control point of the catmull-rom sequence. If NULL, an appropriate point is generated based on the last two points in points. If the distance between last and the last control point in points is less than or equals to epsilon, last is treated as NULL. This is necessary to avoid division by zero.
[in]epsilonThe maximum distance between points with "same" coordinates. That is, if the distance between neighboring points is less than or equal to epsilon, they are considered equal. For the sake of fail-safeness, the sign is removed with fabs. It is advisable to pass a value greater than zero, however, it is not necessary.
[out]splineThe interpolated spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_DIM_ZERO If dimension is 0.
TS_NUM_POINTS If num_points is 0.
TS_MALLOC If allocating memory failed.

< The points to interpolate based on points.

< Used in for loops.

< Local error handling.

< Catmull-Rom knots.

< Used to calculate derivatives.

< Processed Catmull-Rom points.

◆ ts_bspline_interpolate_cubic_natural()

tsError ts_bspline_interpolate_cubic_natural ( const tsReal *  points,
size_t  num_points,
size_t  dimension,
tsBSpline spline,
tsStatus status 
)

Interpolates a cubic spline with natural end conditions. For more details see:

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 resultant spline is a sequence of bezier curves connecting each point in points. Each bezier curve is of degree 3 with dimensionality dimension. The total number of control points is:

min(1, \p num_points - 1) * 4

Note: num_points is the number of points in points and not the length of points. For instance, the following point vector has num_points = 4 and dimension = 2:

[x0, y0, x1, y1, x2, y2, x3, y3]
Parameters
[in]pointsThe points to interpolate.
[in]num_pointsThe number of points in points.
[in]dimensionThe dimension of each control point in spline.
[out]splineThe output spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_DIM_ZERO If dimension is 0.
TS_NUM_POINTS If num_points is 0.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_is_closed()

tsError ts_bspline_is_closed ( const tsBSpline spline,
tsReal  epsilon,
int *  closed,
tsStatus status 
)

Checks whether the distance of the endpoints of spline is less than or equal to epsilon for the first 'ts_bspline_degree - 1' derivatives (starting with the zeroth derivative).

Parameters
[in]splineThe spline to query.
[in]epsilonThe maximum distance.
[out]closedThe output parameter. 1 if true, 0 otherwise.
statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_knot_at()

tsError ts_bspline_knot_at ( const tsBSpline spline,
size_t  index,
tsReal *  knot,
tsStatus status 
)

Returns the knot of spline at index.

Parameters
[in]splineThe spline whose knot is read at index.
[in]indexThe zero-based index of the knot to return.
[out]knotThe output value.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_INDEX_ERROR If index is out of range.

◆ ts_bspline_knots()

tsError ts_bspline_knots ( const tsBSpline spline,
tsReal **  knots,
tsStatus status 
)

Returns a deep copy of the knots of spline.

Parameters
[in]splineThe spline whose knots are read.
[out]knotsThe output array.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_len_control_points()

size_t ts_bspline_len_control_points ( const tsBSpline spline)

Returns the length of the control point array of spline.

Parameters
[in]splineThe spline with its control point array whose length is read.
Returns
The length of the control point array of spline.

◆ ts_bspline_load()

tsError ts_bspline_load ( const char *  path,
tsBSpline spline,
tsStatus status 
)

Loads spline from a JSON ASCII file.

Parameters
[in]pathPath of the JSON file.
[out]splineThe output spline.

◆ ts_bspline_move()

void ts_bspline_move ( tsBSpline src,
tsBSpline dest 
)

Moves the ownership of the data of src to dest. After calling this function, the data of src points to NULL. Does not free the data of dest. Does nothing, if src == dest.

Parameters
[out]srcThe spline whose values are moved to dest.
[out]destThe spline that receives the values of src.

◆ ts_bspline_new()

tsError ts_bspline_new ( size_t  num_control_points,
size_t  dimension,
size_t  degree,
tsBSplineType  type,
tsBSpline spline,
tsStatus status 
)

Creates a new spline and stores the result in spline.

Parameters
[in]num_control_pointsThe number of control points of spline.
[in]dimensionThe dimension of each control point of spline.
[in]degreeThe degree of spline.
[in]typeHow to setup the knot vector of spline.
[out]splineThe output spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_DIM_ZERO If dimension == 0.
TS_DEG_GE_NCTRLP If degree >= num_control_points.
TS_NUM_KNOTS If type == ::TS_BEZIERS and (num_control_points % degree + 1) != 0.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_num_control_points()

size_t ts_bspline_num_control_points ( const tsBSpline spline)

Returns the number of control points of spline.

Parameters
[in]splineThe spline whose number of control points is read.
Returns
The number of control points of spline.

◆ ts_bspline_num_knots()

size_t ts_bspline_num_knots ( const tsBSpline spline)

Returns the number of knots of spline.

Parameters
[in]splineThe spline whose number of knots is read.
Returns
The number of knots of spline.

◆ ts_bspline_order()

size_t ts_bspline_order ( const tsBSpline spline)

Returns the order (degree + 1) of spline.

Parameters
[in]splineThe spline whose order is read.
Returns
The order of spline.

◆ ts_bspline_sample()

tsError ts_bspline_sample ( const tsBSpline spline,
size_t  num,
tsReal **  points,
size_t *  actual_num,
tsStatus status 
)

Generates a sequence of num different knots (The knots are equally distributed between the minimum and the maximum of the domain of spline), passes this sequence to ts_bspline_eval_all, and stores the resultant points in points. If num is 0, the following default is taken as fallback:

num = (ts_bspline_num_control_points(spline) -
    ts_bspline_degree(spline)) * 30;

That is, the fallback generates 30 knots per Bezier segment. For the sake of stability regarding future changes, the actual number of generated knots (which only differs from num if num is 0) is stored in actual_num. If num is 1, the point located at the minimum of the domain of spline is evaluated.

Parameters
[in]splineThe spline to evaluate.
[in]numThe number of knots to generate.
[out]pointsThe output parameter.
[out]actual_numThe actual number of generated knots. Differs from num only if num is 0. Must not be NULL.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_save()

tsError ts_bspline_save ( const tsBSpline spline,
const char *  path,
tsStatus status 
)

Saves spline as JSON ASCII file.

Parameters
[in]splineThe spline to save.
[in]pathPath of the JSON file.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_IO_ERROR If an error occurred while saving spline.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_set_control_point_at()

tsError ts_bspline_set_control_point_at ( tsBSpline spline,
size_t  index,
const tsReal *  ctrlp,
tsStatus status 
)

Sets the control point of spline at index. Creates a deep copy of ctrlp.

Parameters
[out]splineThe spline whose control point is set at index.
[in]indexThe zero-based index of the control point to set.
[in]ctrlpThe control point to be set at index.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_INDEX_ERROR If index is out of range.

◆ ts_bspline_set_control_points()

tsError ts_bspline_set_control_points ( tsBSpline spline,
const tsReal *  ctrlp,
tsStatus status 
)

Sets the control points of spline. Creates a deep copy of ctrlp.

Parameters
[out]splineThe spline whose control points are set.
[in]ctrlpThe values to deep copy.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.

◆ ts_bspline_set_degree()

tsError ts_bspline_set_degree ( tsBSpline spline,
size_t  deg,
tsStatus status 
)

Sets the degree of spline.

Parameters
[out]splineThe spline whose degree is set.
[in]degThe degree to be set.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_DEG_GE_NCTRLP If degree >= ts_bspline_get_control_points(spline).

◆ ts_bspline_set_dimension()

tsError ts_bspline_set_dimension ( tsBSpline spline,
size_t  dim,
tsStatus status 
)

Sets the dimension of spline. The following conditions must be satisfied:

(1) dim >= 1
(2) len_control_points(spline) % dim == 0

with len_control_points being the length of the control point array of spline. The dimension of a spline describes the number of components for each point in ts_bspline_get_control_points(spline). One-dimensional splines are possible, albeit their benefit might be questionable.

Parameters
[out]splineThe spline whose dimension is set.
[in]dimThe dimension to be set.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_DIM_ZERO If dimension == 0.
TS_LCTRLP_DIM_MISMATCH If len_control_points(spline) % dim != 0

◆ ts_bspline_set_knot_at()

tsError ts_bspline_set_knot_at ( tsBSpline spline,
size_t  index,
tsReal  knot,
tsStatus status 
)

Sets the knot of spline at index.

Parameters
[in]splineThe spline whose knot is set at index.
[in]indexThe zero-based index of the knot to set.
[in]knotThe knot to be set at index.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_INDEX_ERROR If index is out of range.
TS_KNOTS_DECR If setting the knot at index results in a decreasing knot vector.
TS_MULTIPLICITY If setting the knot at index results in a knot vector containing knot with multiplicity greater than the order of spline.

◆ ts_bspline_set_knots()

tsError ts_bspline_set_knots ( tsBSpline spline,
const tsReal *  knots,
tsStatus status 
)

Sets the knots of spline. Creates a deep copy of knots.

Parameters
[out]splineThe spline whose knots are set.
[in]knotsThe values to deep copy and scale.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_KNOTS_DECR If the knot vector is decreasing.
TS_MULTIPLICITY If there is a knot with multiplicity > order

◆ ts_bspline_set_order()

tsError ts_bspline_set_order ( tsBSpline spline,
size_t  order,
tsStatus status 
)

Sets the order (degree + 1) of spline.

Parameters
[out]splineThe spline whose order is set.
[in]orderThe order to be set.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_DEG_GE_NCTRLP If order > ts_bspline_get_control_points(spline) or if order == 0 ( due to the underflow resulting from: order - 1 => 0 - 1 => INT_MAX which always is >= ts_bspline_get_control_points(spline) ).

◆ ts_bspline_sof_control_points()

size_t ts_bspline_sof_control_points ( const tsBSpline spline)

Returns the size of the control point array of spline. This function may be useful when copying control points using memcpy or memmove.

Parameters
[in]splineThe spline with its control point array whose size is read.
Returns
The size of the control point array of spline.

◆ ts_bspline_sof_knots()

size_t ts_bspline_sof_knots ( const tsBSpline spline)

Returns the size of the knot array of spline. This function may be useful when copying knots using memcpy or memmove.

Parameters
[in]splineThe spline with its knot array whose size is read.
Returns
TS_SUCCESS The size of the knot array of spline.

◆ ts_bspline_split()

tsError ts_bspline_split ( const tsBSpline spline,
tsReal  u,
tsBSpline split,
size_t *  k,
tsStatus status 
)

Splits spline at knot value u and stores the result in split. That is, u is inserted n times such that the multiplicity of u is equal to the spline's order. Creates a deep copy of spline if spline != split.

Parameters
[in]splineThe spline to split.
[in]uThe split point (knot).
[out]splitThe split spline.
[out]kStores the last index of u in split.
[out]statusStores the last index of u in result.
Returns
TS_SUCCESS On success.
TS_U_UNDEFINED If spline is not defined at knot value u.
TS_MALLOC If allocating memory failed.

◆ ts_bspline_tension()

tsError ts_bspline_tension ( const tsBSpline spline,
tsReal  tension,
tsBSpline out,
tsStatus status 
)

Sets the control points of spline so that their tension corresponds the given tension factor (0 => yields to a line connecting the first and the last control point; 1 => keeps the original shape). If tension < 0 or if tension > 1, the behaviour of this function is undefined, though, it will not result in an error. Creates a deep copy of spline if spline != out.

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).

Parameters
[in]splineThe input spline.
[in]tensionThe tension factor (0 <= tension <= 1).
[out]outThe output spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

< The straightening factor.

< Pointer to the control points of out.

< Used in for loops.

◆ ts_bspline_to_beziers()

tsError ts_bspline_to_beziers ( const tsBSpline spline,
tsBSpline beziers,
tsStatus status 
)

Decomposes spline into a sequence of Bezier curves by splitting it at each internal knot value. Creates a deep copy of spline if spline != beziers.

Parameters
[in]splineThe spline to decompose.
[out]beziersThe bezier decomposition of spline.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

< Number of control points to add/remove.

< Index of the split knot value.

< Minimum of the knot values.

< Maximum of the knot values.

< Temporarily stores the result.

< Pointer to the knots of tmp.

< Number of knots in tmp.

◆ ts_bspline_to_json()

tsError ts_bspline_to_json ( const tsBSpline spline,
char **  _json_,
tsStatus status 
)

Serializes spline to a null-terminated JSON string and stores the result in json.

Parameters
[in]splineThe spline to serialize.
[out]jsonThe serialized JSON string.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_deboornet_copy()

tsError ts_deboornet_copy ( const tsDeBoorNet src,
tsDeBoorNet dest,
tsStatus status 
)

Creates a deep copy of src and stores the copied values in dest. Does nothing, if src == dest.

Parameters
[in]srcThe net to deep copy.
[out]destThe output net.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_deboornet_dimension()

size_t ts_deboornet_dimension ( const tsDeBoorNet net)

Returns the dimension of net. The dimension of a net describes the number of components for each point in ts_bspline_get_points(spline). One-dimensional nets are possible, albeit their benefit might be questionable.

Parameters
[in]netThe net whose dimension is read.
Returns
The dimension of net.

◆ ts_deboornet_free()

void ts_deboornet_free ( tsDeBoorNet net)

Frees the data of net. After calling this function, the data of net points to NULL.

Parameters
[out]netThe net to free.

◆ ts_deboornet_index()

size_t ts_deboornet_index ( const tsDeBoorNet net)

Returns the index [u_k, u_k+1) with u being the knot of net.

Parameters
[in]netThe net whose index is read.
Returns
The index [u_k, u_k+1) with u being the knot of net.

◆ ts_deboornet_init()

tsDeBoorNet ts_deboornet_init ( )

Creates a new net whose data points to NULL.

Returns
A new net whose data points to NULL.

◆ ts_deboornet_knot()

tsReal ts_deboornet_knot ( const tsDeBoorNet net)

Returns the knot (sometimes referred to as 'u' or 't') of net.

Parameters
[in]netThe net whose knot is read.
Returns
The knot of net.

◆ ts_deboornet_len_points()

size_t ts_deboornet_len_points ( const tsDeBoorNet net)

Returns the length of the point array of net.

Parameters
[in]netThe net with its point array whose length is read.
Returns
The length of the point array of net.

◆ ts_deboornet_len_result()

size_t ts_deboornet_len_result ( const tsDeBoorNet net)

Returns the length of the result array of net.

Parameters
[in]netThe net with its result array whose length is read.
Returns
The length of the result array of net.

◆ ts_deboornet_move()

void ts_deboornet_move ( tsDeBoorNet src,
tsDeBoorNet dest 
)

Moves the ownership of the data of src to dest. After calling this function, the data of src points to NULL. Does not free the data of dest. Does nothing, if src == dest.

Parameters
[out]srcThe net whose values are moved to dest.
[out]destThe net that receives the values of src.

◆ ts_deboornet_multiplicity()

size_t ts_deboornet_multiplicity ( const tsDeBoorNet net)

Returns the multiplicity of the knot of net.

Parameters
[in]netThe net whose multiplicity is read.
Returns
The multiplicity of the knot of net.

◆ ts_deboornet_num_insertions()

size_t ts_deboornet_num_insertions ( const tsDeBoorNet net)

Returns the number of insertion that were necessary to evaluate the knot of net.

Parameters
[in]netThe net with its knot whose number of insertions is read.
Returns
The number of insertions that were necessary to evaluate the knot of net.

◆ ts_deboornet_num_points()

size_t ts_deboornet_num_points ( const tsDeBoorNet net)

Returns the number of points of net.

Parameters
[in]netThe net whose number of points is read.
Returns
The number of points of net.

◆ ts_deboornet_num_result()

size_t ts_deboornet_num_result ( const tsDeBoorNet net)

Returns the number of points in the result array of net (1 <= num_result <= 2).

Parameters
[in]netThe net with its result array whose number of points is read.
Returns
The number of points in the result array of net.

◆ ts_deboornet_points()

tsError ts_deboornet_points ( const tsDeBoorNet net,
tsReal **  points,
tsStatus status 
)

Returns a deep copy of the points of net.

Parameters
[in]netThe net whose points is read.
[out]pointsThe output array.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_deboornet_result()

tsError ts_deboornet_result ( const tsDeBoorNet net,
tsReal **  result,
tsStatus status 
)

Returns a deep copy of the result of net.

Parameters
[in]netThe net whose result is read.
[out]resultThe output array.
[out]statusThe status of this function. May be NULL.
Returns
TS_SUCCESS On success.
TS_MALLOC If allocating memory failed.

◆ ts_deboornet_sof_points()

size_t ts_deboornet_sof_points ( const tsDeBoorNet net)

Returns the size of the point array of net. This function may be useful when copying points using memcpy or memmove.

Parameters
[in]netThe net with its point array whose size is read.
Returns
The size of the point array of net.

◆ ts_deboornet_sof_result()

size_t ts_deboornet_sof_result ( const tsDeBoorNet net)

Returns the size of the result array of net. This function may be useful when copying results using memcpy or memmove.

Parameters
[in]netThe net with its result array whose size is read.
Returns
TS_SUCCESS The size of the result array of net.

◆ ts_distance()

tsReal ts_distance ( const tsReal *  x,
const tsReal *  y,
size_t  dimension 
)

Returns the euclidean distance of the points x and y.

Parameters
[in]xThe x value.
[in]yThe y value.
[in]dimensionThe dimension of x and y.
Returns
The euclidean distance of x and y.

◆ ts_knots_equal()

int ts_knots_equal ( tsReal  x,
tsReal  y 
)

Checks whether x and y are equal with respect to the epsilon environment TS_KNOT_EPSILON, i.e. their distance is less than TS_KNOT_EPSILON.

Parameters
[in]xA knot.
[in]yA knot.
Returns
1 If x and y are equal.
0 If x and y are not equal.