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.

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.

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.

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

CoppPathParametrization

enum CoppPathParametrization

C ABI waypoint-spline parametrization.

Enumerator
COPP_PATH_PARAMETRIZATION_UNIFORM	Uniform parameter spacing between waypoints.

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.

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.

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.

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.

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.

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.