copp.Path

Builds a quintic spline over s in [0, 1] that passes through every waypoint. WAYPOINTS must be a real finite \(\mathrm{dim} \times N\) matrix with each column storing one waypoint q(:, k). At least enough waypoints for the selected native spline order must be provided.

Name-value options: s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1]. order: Odd spline order accepted by the native path module. Defaults to 5, matching Rust/Python defaults. out_of_range_mode: "error" to reject out-of-range evaluation, or "clamp" to clamp query values into s_range. start_state, end_state: Optional dim-by-K boundary derivative matrices. Column j stores the j-th boundary derivative. Empty arrays request zero boundary derivatives from the native default path options.

Use Path.from_waypoints_fitting instead when the path only needs to stay within a tolerance of the waypoints. Path.from_waypoints is an equivalent alias of this constructor.

API stability: The waypoint path constructors are currently unstable: their names, signatures, and options may change as additional waypoint path-construction algorithms are added.

The returned object owns the native path handle. release() may be called explicitly, but ordinary MATLAB object cleanup is also sufficient.

Builds a quintic spline over s in [0, 1]. WAYPOINTS must be a real finite \(\mathrm{dim} \times N\) matrix with each column storing one waypoint q(:, k). At least enough waypoints for the selected native spline order must be provided.

Path.from_waypoints is an equivalent alias of Path.from_waypoints_interpolating with identical arguments, behavior, and errors. Both names remain supported and share the unstable status of the waypoint path constructors.

Name-value options: s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1]. order: Odd spline order accepted by the native path module. Defaults to 5, matching Rust/Python defaults. out_of_range_mode: "error" to reject out-of-range evaluation, or "clamp" to clamp query values into s_range. start_state, end_state: Optional dim-by-K boundary derivative matrices. Column j stores the j-th boundary derivative. Empty arrays request zero boundary derivatives from the native default path options.

The returned object owns the native path handle. release() may be called explicitly, but ordinary MATLAB object cleanup is also sufficient.

assigns each column of the real finite \(\mathrm{dim} \times N\) matrix WAYPOINTS (N >= 2) a common path parameter and joins adjacent columns linearly into a reference polyline. The selected axes 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 whole reference interval, not only at the waypoints.

Unlike 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 s, not time. Use smoothing_report() to inspect the selected axes, final per-axis error bounds, and refinement work.

Name-value options: tolerance: Absolute tolerance in each selected row's input units. A scalar applies to every selected axis. A vector gives one tolerance per selected axis, in the order of axes (not row order). Entries must be finite and positive. Defaults to 1e-3. axes: 1-based rows of WAYPOINTS allowed to deviate from the reference polyline. Entries must be distinct and in range; their order also defines the order of a vector tolerance and of the report's axes and max_errors. Empty (default) selects every row. parameters: Optional path parameter of each waypoint column: finite, strictly increasing, one entry per column. The first and last entries become s_range, and relative spacing affects the fitted geometry. Empty (default) assigns the columns uniformly on [0, 1]. max_refinements: Maximum number of adaptive knot-refinement passes. Defaults to 20. max_segments: Maximum number of polynomial spans used by the selected axes; spans of the unselected-axis interpolant do not count. Defaults to 20000. out_of_range_mode: "error" (default) or "clamp" for later out-of-range evaluation. It does not affect fitting or auditing.

Errors: Native contract violations (for example repeated or out-of-range axes, a tolerance vector of the wrong length, or non-increasing parameters), exceeding max_segments or max_refinements, numerical failure, or a failed final audit raise copp:PathError. An unchecked or relaxed approximation is never returned.

API stability: The waypoint path constructors, their options, and the smoothing report are currently unstable: names, signatures, and options may change as additional waypoint path-construction algorithms are added.

The callback input s is always a \(1 \times N\) row vector. The three outputs must be real finite D-by-N matrices. The native path borrows the callback, so this Path object keeps the MATLAB function handle alive until release()/delete().

also accepts an object or handle object E that implements:

Function handles are handy for scripts and quick demos. Objects are better when the evaluator owns parameters, caches, or helper methods that should be tested independently.

Name-value options: dim: Positive integer path dimension D. s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1].

The resulting native path supports evaluate_q() and evaluate_up_to_2nd(). Third-order evaluation raises a path unsupported-derivative error.

The callback input s is always a \(1 \times N\) row vector. All outputs must be real finite D-by-N matrices. If the native library only needs second-order derivatives, it may still call F and discard dddq.

also accepts an object or handle object E that implements:

If E also implements evaluate_up_to_2nd(s), native second-order evaluation uses that lighter callback. Otherwise it falls back to evaluate_up_to_3rd(s) and discards dddq, matching the C/Python binding semantics.

Name-value options: dim: Positive integer path dimension D. s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1].

differentiates a Symbolic Math Toolbox vector expression Q_EXPR with respect to its only symbolic variable, then wraps the generated batch evaluator with Path.from_evaluator_3rd().

uses the scalar symbolic variable S explicitly. Passing symbol= is required when Q_EXPR contains zero variables or more than one variable.

Name-value options: symbol: Scalar sym variable used as the path parameter. If omitted, it is inferred only when symvar(Q_EXPR) has exactly one variable. s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1].

must be a symbolic row or column vector. Matrix-valued expressions are rejected so the path dimension is unambiguous. The callback created by this constructor receives s as a \(1 \times N\) row vector and returns q/dq/ddq/dddq as \(\mathrm{dim} \times N\) double matrices.

This constructor requires MATLAB Symbolic Math Toolbox. It throws copp:MissingDependency when the toolbox is unavailable.

differentiates a scalar-parameter CasADi SX/MX vector expression Q_EXPR up to third order with respect to scalar symbol S, then wraps the generated batch evaluator with Path.from_evaluator_3rd().

Name-value options: symbol: Required scalar CasADi SX or MX symbol used as the path parameter. s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1].

must be a CasADi row or column vector. Matrix-valued expressions are rejected so the path dimension is unambiguous. The evaluator first tries CasADi Function.map(N) for batch evaluation and falls back to a scalar loop if map evaluation is not supported by the installed CasADi version.

This constructor requires the CasADi MATLAB package on the MATLAB path. It throws copp:MissingDependency when CasADi is unavailable.

calls F with a scalar copp.Jet3 path parameter. F must return a numeric vector or a Jet3 vector. The returned value defines \(q(s)\), and Jet3 automatically supplies dq/ds, d2q/ds2, and d3q/ds3.

Name-value options: s_range: \(1 \times 2\) finite vector [s_min, s_max]. Defaults to [0, 1]. dim: Optional positive integer path dimension. If omitted, the dimension is inferred by probing F at mean(s_range).

The generated evaluator is batch-compatible with the native MEX callback path. Internally it receives s as a \(1 \times N\) row vector, evaluates the scalar Jet3 formula once per sample, and returns \(\mathrm{dim} \times N\) q/dq/ddq/dddq matrices.

Returns a \(\mathrm{dim} \times N\) matrix containing the path position at each sample in S, where N = numel(S). S may be a row or column vector, but must be real and finite. The output orientation is always \(\mathrm{dim} \times N\), matching evaluate_up_to_2nd().

Returns a struct with fields: q: \(\mathrm{dim} \times N\) path position matrix. dq: \(\mathrm{dim} \times N\) first derivative matrix. ddq: \(\mathrm{dim} \times N\) second derivative matrix.

Returns the same matrices as separate outputs. S may be a \(1 \times N\) or \(N \times 1\) vector, and all outputs are always \(\mathrm{dim} \times N\).

Returns a struct with fields: q: \(\mathrm{dim} \times N\) path position matrix. dq: \(\mathrm{dim} \times N\) first derivative matrix. ddq: \(\mathrm{dim} \times N\) second derivative matrix. dddq: \(\mathrm{dim} \times N\) third derivative matrix.

Returns the same \(\mathrm{dim} \times N\) matrices as separate outputs, where N = numel(S). Second-order-only evaluator paths raise copp:PathError for this method.

Returns [] unless OBJ was built by Path.from_waypoints_fitting. For fitted paths REPORT is a struct with fields: axes: Column vector of 1-based selected rows, in tolerance and report order. segments: Number of final polynomial spans shared by the selected axes. interpolated_segments: Number of spans in the separate unselected-axis interpolant. Zero when every row is selected; not included in segments or the max_segments budget. refinements: Number of completed local knot-refinement passes. fitting_rows: Number of fitting rows assembled, counting rows assembled again during local refits. checked_intervals: Number of reference intervals visited by numerical audits, including revisits and the final full audit. max_errors: Column vector of final whole-domain absolute-error bounds, one per selected axis in axes order and in input units. These are Bernstein-derived numerical bounds computed with ordinary floating-point arithmetic, not sampled maxima or formal certificates.

axes, segments, and interpolated_segments describe the final representation; the other counters are cumulative work counters and not optimality or run-time guarantees. Like the waypoint constructors, this report is currently unstable.

is idempotent through release(); it is safe for MATLAB to call it after the user has already called release().

A false result means either release() has been called or the MEX registry no longer contains this handle id.