Copp_path

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

Data Structures
struct	CoppJet3
	C-compatible third-order automatic-differentiation scalar. More...
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(*	CoppPathParametricFn) (void *user_data, size_t dim, struct CoppJet3 s, struct CoppJet3 *q)
	C callback for evaluating a scalar-parametric path with automatic derivatives.
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_parametric (size_t dim, double s_min, double s_max, CoppPathParametricFn evaluate, void *user_data, struct CoppPath **out_path)
	Build a path from a scalar-parametric C callback.
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_parametric, 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 36 of file path.h.

CoppPathParametricFn

typedef enum CoppStatus(* CoppPathParametricFn) (void *user_data, size_t dim, struct CoppJet3 s, struct CoppJet3 *q)

C callback for evaluating a scalar-parametric path with automatic derivatives.

The callback receives one seeded CoppJet3 path parameter and must write dim CoppJet3 values into q. COPP extracts each returned value and its first three derivatives to serve the existing path evaluation and robot sampling APIs.

Definition at line 36 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 36 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 36 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 67 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 81 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.

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

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_parametric()

enum CoppStatus copp_path_from_parametric	(	size_t	dim,
		double	s_min,
		double	s_max,
		CoppPathParametricFn	evaluate,
		void *	user_data,
		struct CoppPath **	out_path )

Build a path from a scalar-parametric C callback.

COPP calls evaluate once per path sample with a seeded CoppJet3 value for s. The callback writes dim output entries describing only q(s); the returned CoppJet3 derivative fields provide dq, ddq, and dddq. Use the inline helpers in copp/path.h such as copp_add, copp_mul, and copp_sin to write formulas without hand-differentiating them.

The resulting path supports position, second-order, and third-order evaluation and can be sampled by copp_robot_sample_path_2nd or copp_robot_sample_path_3rd.

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 builds a one-dimensional q(s) = sin(2*pi*s) path.

static enum CoppStatus eval_path_parametric(
    void *user_data,
    size_t dim,
    struct CoppJet3 s,
    struct CoppJet3 *q)
{
    (void)user_data;
    if (dim != 1 || q == NULL) {
        return COPP_STATUS_INVALID_ARGUMENT;
    }
    q[0] = copp_sin(copp_mul_f64(s, 6.28318530717958647692));
    return COPP_STATUS_OK;
}
 
struct CoppPath *path = NULL;
check(copp_path_from_parametric(1, 0.0, 1.0, eval_path_parametric, NULL, &path));

Safety

evaluate 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_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));

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

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.

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.

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

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

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.

Safety

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