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...
struct	CoppSmoothingOptions
	Options for tolerance-bounded waypoint fitting. More...
struct	CoppSmoothingReport
	Diagnostics recorded while constructing a tolerance-fitted waypoint path. 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_interpolating (struct CoppMatrixViewF64 waypoints, struct CoppPathOptions options, struct CoppPath **out_path)
	Build an interpolating waypoint spline path.
enum CoppStatus	copp_path_from_waypoints (struct CoppMatrixViewF64 waypoints, struct CoppPathOptions options, struct CoppPath **out_path)
	Build an interpolating waypoint spline path.
enum CoppStatus	copp_smoothing_default_options (struct CoppSmoothingOptions *out_options)
	Write default tolerance-bounded fitting options into out_options.
enum CoppStatus	copp_path_from_waypoints_fitting (struct CoppMatrixViewF64 waypoints, struct CoppSmoothingOptions options, struct CoppPath **out_path)
	Build a tolerance-bounded waypoint-fitting path.
enum CoppStatus	copp_path_smoothing_report (const struct CoppPath *path, bool *out_has_report, struct CoppSmoothingReport *out_report)
	Return the construction report of a tolerance-fitted waypoint path.
void	copp_smoothing_report_free (struct CoppSmoothingReport report)
	Release memory owned by a CoppSmoothingReport.
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_interpolating, copp_path_from_waypoints_fitting, 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 37 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 37 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 37 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 37 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 68 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 82 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_interpolating()

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

Build an interpolating waypoint spline path.

waypoints must be a matrix view of shape dim x n_points, where each column is one waypoint. The spline interpolates every waypoint column. 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.

API stability

The waypoint path constructors are currently unstable: their names, signatures, and option types may change as additional waypoint path-construction algorithms are introduced. copp_path_from_waypoints is an equivalent alias of this function.

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_interpolating(
    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_waypoints()

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

Build an interpolating waypoint spline path.

This is an equivalent alias of copp_path_from_waypoints_interpolating with identical arguments, behavior, and status codes. Both names remain supported and share the unstable status of the waypoint path constructors.

Safety

Same requirements as copp_path_from_waypoints_interpolating.

copp_smoothing_default_options()

enum CoppStatus copp_smoothing_default_options

(

struct CoppSmoothingOptions *

out_options

)

Write default tolerance-bounded fitting options into out_options.

Defaults fit every row with absolute tolerance 0.001, assign waypoint parameters uniformly on [0, 1], allow 20 refinement passes and 20000 selected-axis spans, and reject out-of-range queries. All borrowed slices are empty.

Safety

out_options must be valid for one CoppSmoothingOptions write.

copp_path_from_waypoints_fitting()

enum CoppStatus copp_path_from_waypoints_fitting	(	struct CoppMatrixViewF64	waypoints,
		struct CoppSmoothingOptions	options,
		struct CoppPath **	out_path )

Build a tolerance-bounded waypoint-fitting path.

waypoints must be a finite matrix view of shape dim x n_points with dim > 0 and n_points >= 2, where each column is one waypoint. Each column receives a common path parameter (options.parameters, or uniform on [0, 1] when empty), and adjacent columns are joined linearly into a reference polyline. The selected axes (options.axes, or every row when empty) are approximated by one adaptive nonuniform quintic B-spline with C4 continuity whose same-parameter absolute deviation from the reference polyline stays within each axis tolerance. The error is audited over every complete reference interval, not only at the waypoints.

Unlike copp_path_from_waypoints_interpolating, the fitted path does not pass through interior waypoints: selected axes may deviate within their tolerances, while the first and last waypoints are retained. Unselected rows keep quintic C4 interpolation through every column. Derivatives returned by path evaluation are with respect to the path parameter s, not time. Use copp_path_smoothing_report to inspect the selected axes, the final per-axis error bounds, and the refinement work.

Column-major input with leading_dim >= rows is read without a temporary layout copy. Row-major input is accepted and copied once into column-major temporary storage. The returned path owns its fitted representation and does not borrow waypoints or the slices in options after the call.

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

API stability

The waypoint path constructors and CoppSmoothingOptions / CoppSmoothingReport are currently unstable: their names, signatures, and option types may change as additional waypoint path-construction algorithms are introduced.

Errors

Returns COPP_STATUS_PATH_SMOOTHING when the waypoint values, dimensions, axes, tolerances, or parameters violate their contracts, when the selected-axis span count exceeds options.max_segments, when refinement exhausts options.max_refinements or the parameter resolution, when the banded fit encounters an unusable numerical system, or when the final whole-interval audit fails. An unchecked or relaxed approximation is never returned.

Example

The example below fits a two-dimensional waypoint path within 1e-3 input units and reads the final error bound of each axis.

enum { DIM = 2, NUM_WAYPOINTS = 5 };
double waypoints[DIM * NUM_WAYPOINTS] = {
    0.0, 0.0,
    0.25, 0.4,
    0.5, 0.5,
    0.75, 0.4,
    1.0, 0.0,
};
 
struct CoppSmoothingOptions options;
struct CoppPath *path = NULL;
check(copp_smoothing_default_options(&options));
options.tolerance = 1e-3;
check(copp_path_from_waypoints_fitting(
    COPP_MATRIX_VIEW_F64_COLUMN_MAJOR(waypoints, DIM, NUM_WAYPOINTS),
    options,
    &path));
 
bool has_report = false;
struct CoppSmoothingReport report = {0};
check(copp_path_smoothing_report(path, &has_report, &report));
for (size_t i = 0; i < report.axes.len; ++i) {
    printf("axis %zu: %.3e\n", report.axes.data[i], report.max_errors.data[i]);
}
copp_smoothing_report_free(report);
copp_path_free(path);

Safety

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

copp_path_smoothing_report()

enum CoppStatus copp_path_smoothing_report	(	const struct CoppPath *	path,
		bool *	out_has_report,
		struct CoppSmoothingReport *	out_report )

Return the construction report of a tolerance-fitted waypoint path.

For a path built by copp_path_from_waypoints_fitting, *out_has_report receives true and *out_report receives a library-owned report that must be released with copp_smoothing_report_free. For any other path, *out_has_report receives false and *out_report receives an empty report with null vectors and zero counters; releasing it is allowed.

Safety

path must be a non-null handle created by this module. out_has_report must be valid for one bool write and out_report for one CoppSmoothingReport write.

copp_smoothing_report_free()

void copp_smoothing_report_free

(

struct CoppSmoothingReport

report

)

Release memory owned by a CoppSmoothingReport.

Passing an empty report is allowed and has no effect. Passing an already-freed report is invalid.

Safety

report must either be empty/null or have been returned by copp_path_smoothing_report. Passing arbitrary pointers or modified capacity fields is invalid.

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.