Copp_path

Files
file	bindings/c/include/copp/path.h
	Path construction, metadata, evaluation, and callback path APIs.

Data Structures
struct	CoppPathOptions
	Options for waypoint spline path construction. More...

Typedefs
typedef struct CoppPath	CoppPath
	Opaque C handle for a library-owned Path.
typedef enum CoppStatus(*	CoppPathEvaluate2ndFn) (void *user_data, size_t dim, size_t n, const double *s, double *q, double *dq, double *ddq)
	C callback for evaluating q, dq, and ddq.
typedef enum CoppStatus(*	CoppPathEvaluate3rdFn) (void *user_data, size_t dim, size_t n, const double *s, double *q, double *dq, double *ddq, double *dddq)
	C callback for evaluating q, dq, ddq, and dddq.

Enumerations
enum	CoppPathOutOfRangeMode { COPP_PATH_OUT_OF_RANGE_MODE_ERROR = 0 , COPP_PATH_OUT_OF_RANGE_MODE_CLAMP = 1 }
	C ABI path out-of-range behavior. More...
enum	CoppPathParametrization { COPP_PATH_PARAMETRIZATION_UNIFORM = 0 }
	C ABI waypoint-spline parametrization. More...

Functions
enum CoppStatus	copp_path_default_options (double s_min, double s_max, struct CoppPathOptions *out_options)
	Write default waypoint spline options into out_options.
enum CoppStatus	copp_path_from_waypoints (struct CoppMatrixViewF64 waypoints, struct CoppPathOptions options, struct CoppPath **out_path)
	Build a waypoint spline path.
enum CoppStatus	copp_path_from_evaluator_2nd (size_t dim, double s_min, double s_max, CoppPathEvaluate2ndFn evaluate_2nd, void *user_data, struct CoppPath **out_path)
	Build a path from a C callback that provides derivatives up to 2nd order.
enum CoppStatus	copp_path_from_evaluator_3rd (size_t dim, double s_min, double s_max, CoppPathEvaluate2ndFn evaluate_2nd, CoppPathEvaluate3rdFn evaluate_3rd, void *user_data, struct CoppPath **out_path)
	Build a path from C callbacks that provide derivatives up to 3rd order.
enum CoppStatus	copp_path_dim (const struct CoppPath *path, size_t *out_dim)
	Return the path dimension.
enum CoppStatus	copp_path_s_range (const struct CoppPath *path, double *out_s_min, double *out_s_max)
	Return the valid path parameter range.
enum CoppStatus	copp_path_evaluate_up_to_2nd (const struct CoppPath *path, struct CoppSliceF64 s, struct CoppMatrixF64 *out_q, struct CoppMatrixF64 *out_dq, struct CoppMatrixF64 *out_ddq)
	Evaluate q, dq, and ddq at the supplied path parameters.
enum CoppStatus	copp_path_evaluate_up_to_3rd (const struct CoppPath *path, struct CoppSliceF64 s, struct CoppMatrixF64 *out_q, struct CoppMatrixF64 *out_dq, struct CoppMatrixF64 *out_ddq, struct CoppMatrixF64 *out_dddq)
	Evaluate q, dq, ddq, and dddq at the supplied path parameters.
void	copp_path_free (struct CoppPath *path)
	Release a path handle created by this module.

Detailed Description

Typedef Documentation

CoppPath

typedef struct CoppPath CoppPath

Opaque C handle for a library-owned Path.

Create with copp_path_from_waypoints, copp_path_from_evaluator_2nd, or copp_path_from_evaluator_3rd and release exactly once with copp_path_free. C callers must not inspect or allocate this type directly.

Definition at line 34 of file path.h.

CoppPathEvaluate2ndFn

typedef enum CoppStatus(* CoppPathEvaluate2ndFn) (void *user_data, size_t dim, size_t n, const double *s, double *q, double *dq, double *ddq)

C callback for evaluating q, dq, and ddq.

The callback receives n path samples in s and must write column-major dim x n matrices into q, dq, and ddq.

Definition at line 34 of file path.h.

CoppPathEvaluate3rdFn

typedef enum CoppStatus(* CoppPathEvaluate3rdFn) (void *user_data, size_t dim, size_t n, const double *s, double *q, double *dq, double *ddq, double *dddq)

C callback for evaluating q, dq, ddq, and dddq.

The callback receives n path samples in s and must write column-major dim x n matrices into q, dq, ddq, and dddq.

Definition at line 34 of file path.h.

Enumeration Type Documentation

CoppPathOutOfRangeMode

enum CoppPathOutOfRangeMode

C ABI path out-of-range behavior.

Enumerator
COPP_PATH_OUT_OF_RANGE_MODE_ERROR	Return an error when a query parameter is outside [s_min, s_max].
COPP_PATH_OUT_OF_RANGE_MODE_CLAMP	Clamp query parameters into [s_min, s_max].

Definition at line 39 of file path.h.

CoppPathParametrization

enum CoppPathParametrization

C ABI waypoint-spline parametrization.

Enumerator
COPP_PATH_PARAMETRIZATION_UNIFORM	Uniform parameter spacing between waypoints.

Definition at line 53 of file path.h.

Function Documentation

copp_path_default_options()

enum CoppStatus copp_path_default_options	(	double	s_min,
		double	s_max,
		struct CoppPathOptions *	out_options )

Write default waypoint spline options into out_options.

Defaults are quintic order 5, uniform parametrization, zero boundary derivatives, and out-of-range errors.

Warning

Safety out_options must be valid for one CoppPathOptions write.

copp_path_from_waypoints()

enum CoppStatus copp_path_from_waypoints	(	struct CoppMatrixViewF64	waypoints,
		struct CoppPathOptions	options,
		struct CoppPath **	out_path )

Build a waypoint spline path.

waypoints must be a matrix view of shape dim x n_points, where each column is one waypoint. options.start_state and options.end_state may be empty to use zero boundary derivatives.

Column-major input with leading_dim >= rows avoids a temporary layout copy while building the spline coefficients. Row-major input is accepted and copied once into column-major temporary storage. Spline construction still allocates library-owned polynomial coefficients for the returned path.

On success, *out_path receives a non-null handle that must be released with copp_path_free.

Example

The example below builds a two-dimensional spline path from column-major waypoint coordinates.

enum { DIM = 2, NUM_WAYPOINTS = 4 };
double waypoints[DIM * NUM_WAYPOINTS] = {
    0.0, 0.0,
    0.3, 0.2,
    0.7, 0.8,
    1.0, 1.0,
};
 
struct CoppPathOptions options;
struct CoppPath *path = NULL;
check(copp_path_default_options(0.0, 1.0, &options));
check(copp_path_from_waypoints(
    COPP_MATRIX_VIEW_F64_COLUMN_MAJOR(waypoints, DIM, NUM_WAYPOINTS),
    options,
    &path));
 
copp_path_free(path);

Warning

Safety Non-empty matrix views in waypoints and options must point to valid double arrays for their declared layouts for the duration of this call. out_path must be valid for one CoppPath* write.

copp_path_from_evaluator_2nd()

enum CoppStatus copp_path_from_evaluator_2nd	(	size_t	dim,
		double	s_min,
		double	s_max,
		CoppPathEvaluate2ndFn	evaluate_2nd,
		void *	user_data,
		struct CoppPath **	out_path )

Build a path from a C callback that provides derivatives up to 2nd order.

The callback operates on a batch of n path samples and must write column-major dim x n output matrices (data[row + col * dim]) for q, dq, and ddq. The resulting path can be evaluated or sampled up to 2nd order. Third-order evaluation returns COPP_STATUS_PATH_UNSUPPORTED_DERIVATIVE_ORDER.

The callback pointer and user_data are borrowed by the created path and must remain valid until copp_path_free is called. Calls into the callback are serialized per path handle.

On success, *out_path receives a non-null handle that must be released with copp_path_free.

Example

The example below wraps a one-dimensional external evaluator that provides q, dq, and ddq.

static enum CoppStatus eval_path_2nd(
    void *user_data,
    size_t dim,
    size_t n,
    const double *s,
    double *q,
    double *dq,
    double *ddq)
{
    for (size_t j = 0; j < n; ++j) {
        q[0 + j * dim] = s[j];
        dq[0 + j * dim] = 1.0;
        ddq[0 + j * dim] = 0.0;
    }
    return COPP_STATUS_OK;
}
 
struct CoppPath *path = NULL;
check(copp_path_from_evaluator_2nd(1, 0.0, 1.0, eval_path_2nd, NULL, &path));

Warning

Safety evaluate_2nd must be non-null and valid until copp_path_free. user_data must remain valid for all callback calls. out_path must be valid for one CoppPath* write.

copp_path_from_evaluator_3rd()

enum CoppStatus copp_path_from_evaluator_3rd	(	size_t	dim,
		double	s_min,
		double	s_max,
		CoppPathEvaluate2ndFn	evaluate_2nd,
		CoppPathEvaluate3rdFn	evaluate_3rd,
		void *	user_data,
		struct CoppPath **	out_path )

Build a path from C callbacks that provide derivatives up to 3rd order.

evaluate_3rd is required. evaluate_2nd may be null; when it is null, second-order evaluation calls evaluate_3rd internally and discards dddq. Both callbacks operate on a batch of n path samples and must write column-major dim x n output matrices (data[row + col * dim]).

The callback pointers and user_data are borrowed by the created path and must remain valid until copp_path_free is called. Calls into the callbacks are serialized per path handle.

On success, *out_path receives a non-null handle that must be released with copp_path_free.

Example

The example below wraps a one-dimensional external evaluator that also provides third derivatives.

static enum CoppStatus eval_path_3rd(
    void *user_data,
    size_t dim,
    size_t n,
    const double *s,
    double *q,
    double *dq,
    double *ddq,
    double *dddq)
{
    for (size_t j = 0; j < n; ++j) {
        q[0 + j * dim] = s[j] * s[j];
        dq[0 + j * dim] = 2.0 * s[j];
        ddq[0 + j * dim] = 2.0;
        dddq[0 + j * dim] = 0.0;
    }
    return COPP_STATUS_OK;
}
 
struct CoppPath *path = NULL;
check(copp_path_from_evaluator_3rd(1, 0.0, 1.0, NULL, eval_path_3rd, NULL, &path));

Warning

Safety evaluate_3rd must be non-null and valid until copp_path_free. evaluate_2nd, when non-null, must follow the same lifetime rule. user_data must remain valid for all callback calls. out_path must be valid for one CoppPath* write.

copp_path_dim()

enum CoppStatus copp_path_dim	(	const struct CoppPath *	path,
		size_t *	out_dim )

Return the path dimension.

Warning

Safety path must be a non-null handle created by this module. out_dim must be valid for one size_t write.

copp_path_s_range()

enum CoppStatus copp_path_s_range	(	const struct CoppPath *	path,
		double *	out_s_min,
		double *	out_s_max )

Return the valid path parameter range.

Warning

Safety path must be a non-null handle created by this module. out_s_min and out_s_max must be valid for one double write each.

copp_path_evaluate_up_to_2nd()

enum CoppStatus copp_path_evaluate_up_to_2nd	(	const struct CoppPath *	path,
		struct CoppSliceF64	s,
		struct CoppMatrixF64 *	out_q,
		struct CoppMatrixF64 *	out_dq,
		struct CoppMatrixF64 *	out_ddq )

Evaluate q, dq, and ddq at the supplied path parameters.

Output matrices are column-major with shape dim x s.len and must be released with copp_matrix_f64_free.

Example

The example below evaluates second-order path derivatives and reads one column-major output entry.

double s_eval[] = {0.0, 0.5, 1.0};
struct CoppMatrixF64 q = {0};
struct CoppMatrixF64 dq = {0};
struct CoppMatrixF64 ddq = {0};
 
check(copp_path_evaluate_up_to_2nd(
    path,
    (struct CoppSliceF64){s_eval, 3},
    &q,
    &dq,
    &ddq));
 
double q_axis0_at_sample1 = q.data[0 + 1 * q.rows];
copp_matrix_f64_free(ddq);
copp_matrix_f64_free(dq);
copp_matrix_f64_free(q);

Warning

Safety path must be a non-null handle created by this module. s.data must be valid for s.len reads when non-empty. Output pointers must be valid for one CoppMatrixF64 write each.

copp_path_evaluate_up_to_3rd()

enum CoppStatus copp_path_evaluate_up_to_3rd	(	const struct CoppPath *	path,
		struct CoppSliceF64	s,
		struct CoppMatrixF64 *	out_q,
		struct CoppMatrixF64 *	out_dq,
		struct CoppMatrixF64 *	out_ddq,
		struct CoppMatrixF64 *	out_dddq )

Evaluate q, dq, ddq, and dddq at the supplied path parameters.

Output matrices are column-major with shape dim x s.len and must be released with copp_matrix_f64_free.

Example

The example below evaluates a third-order path and releases all returned matrices.

struct CoppMatrixF64 q = {0}, dq = {0}, ddq = {0}, dddq = {0};
check(copp_path_evaluate_up_to_3rd(path, s_slice, &q, &dq, &ddq, &dddq));
copp_matrix_f64_free(dddq);
copp_matrix_f64_free(ddq);
copp_matrix_f64_free(dq);
copp_matrix_f64_free(q);

Warning

Safety path must be a non-null handle created by this module. s.data must be valid for s.len reads when non-empty. Output pointers must be valid for one CoppMatrixF64 write each.

copp_path_free()

void copp_path_free

(

struct CoppPath *

path

)

Release a path handle created by this module.

Passing null is allowed and has no effect.

Warning

Safety path must either be null or a live path handle that has not already been freed.