copp::Path Class Reference

Geometric path wrapper backed by Rust Path. More...

#include <path.hpp>

Public Member Functions
	Path (Path &&) noexcept
Path &	operator= (Path &&) noexcept
	~Path ()
	Path (const Path &)=delete
Path &	operator= (const Path &)=delete
std::size_t	dim () const
	Return the path dimension.
std::pair< double, double >	s_range () const
	Return the valid path-parameter interval (s_min, s_max).
PathDerivatives	evaluate_q (Span< const double > s) const
	Evaluate position samples only.
Expected< PathDerivatives >	evaluate_q (Span< const double > s, NoThrowTag) const
PathDerivatives	evaluate_up_to_2nd (Span< const double > s) const
	Evaluate position, first derivative, and second derivative.
Expected< PathDerivatives >	evaluate_up_to_2nd (Span< const double > s, NoThrowTag) const
PathDerivatives	evaluate_up_to_3rd (Span< const double > s) const
	Evaluate position, first derivative, second derivative, and third derivative.
Expected< PathDerivatives >	evaluate_up_to_3rd (Span< const double > s, NoThrowTag) const
std::optional< SmoothingReport >	smoothing_report () const
	Return fitting diagnostics of a path built by from_waypoints_fitting.

Static Public Member Functions
static Path	from_waypoints (MatrixView waypoints, SplineConfig config={})
	Build a spline path from waypoint positions.
static Expected< Path >	from_waypoints (MatrixView waypoints, SplineConfig config, NoThrowTag)
static Expected< Path >	from_waypoints (MatrixView waypoints, NoThrowTag)
static Path	from_waypoints (std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config={})
	Build a spline path from waypoint-list notation.
static Expected< Path >	from_waypoints (std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config, NoThrowTag)
static Expected< Path >	from_waypoints (std::initializer_list< std::initializer_list< double > > waypoints, NoThrowTag)
static Path	from_waypoints_interpolating (MatrixView waypoints, SplineConfig config={})
	Build a spline path that interpolates every waypoint.
static Expected< Path >	from_waypoints_interpolating (MatrixView waypoints, SplineConfig config, NoThrowTag)
static Expected< Path >	from_waypoints_interpolating (MatrixView waypoints, NoThrowTag)
static Path	from_waypoints_interpolating (std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config={})
	Build an interpolating spline path from waypoint-list notation.
static Expected< Path >	from_waypoints_interpolating (std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config, NoThrowTag)
static Expected< Path >	from_waypoints_interpolating (std::initializer_list< std::initializer_list< double > > waypoints, NoThrowTag)
static Path	from_waypoints_fitting (MatrixView waypoints, SmoothingConfig config={})
	Build a tolerance-bounded fitted path from waypoint positions.
static Expected< Path >	from_waypoints_fitting (MatrixView waypoints, SmoothingConfig config, NoThrowTag)
static Expected< Path >	from_waypoints_fitting (MatrixView waypoints, NoThrowTag)
static Path	from_waypoints_fitting (std::initializer_list< std::initializer_list< double > > waypoints, SmoothingConfig config={})
	Build a tolerance-bounded fitted path from waypoint-list notation.
static Expected< Path >	from_waypoints_fitting (std::initializer_list< std::initializer_list< double > > waypoints, SmoothingConfig config, NoThrowTag)
static Expected< Path >	from_waypoints_fitting (std::initializer_list< std::initializer_list< double > > waypoints, NoThrowTag)
static Path	from_parametric (PathParametric parametric, double s_min, double s_max)
	Build a path from a scalar-parametric formula.
static Expected< Path >	from_parametric (PathParametric parametric, double s_min, double s_max, NoThrowTag)
static Path	from_parametric (std::size_t dim, double s_min, double s_max, PathParametricWriter parametric)
	Build a path from a scalar-parametric formula that writes into a buffer.
static Expected< Path >	from_parametric (std::size_t dim, double s_min, double s_max, PathParametricWriter parametric, NoThrowTag)
static Path	from_evaluator_2nd (std::size_t dim, double s_min, double s_max, PathEvaluator2nd evaluator)
	Build a path from a batch evaluator with explicit derivatives up to second order.
static Expected< Path >	from_evaluator_2nd (std::size_t dim, double s_min, double s_max, PathEvaluator2nd evaluator, NoThrowTag)
static Path	from_evaluator_3rd (std::size_t dim, double s_min, double s_max, PathEvaluator3rd evaluator)
	Build a path from a batch evaluator with explicit derivatives up to third order.
static Expected< Path >	from_evaluator_3rd (std::size_t dim, double s_min, double s_max, PathEvaluator3rd evaluator, NoThrowTag)

Friends
const void *	detail::path_handle (const Path &path) noexcept

Detailed Description

Geometric path wrapper backed by Rust Path.

Path owns a Rust-side path handle through the cxx bridge. It is movable but not copyable. The C++ public API exposes RAII ownership and throws copp::Error on construction or evaluation failure.

Definition at line 425 of file path.hpp.

Constructor & Destructor Documentation

Path() [1/2]

copp::Path::Path ( Path && )

noexcept

~Path()

copp::Path::~Path

(

)

Path() [2/2]

copp::Path::Path ( const Path & )

delete

Member Function Documentation

from_waypoints() [1/6]

Path copp::Path::from_waypoints ( MatrixView waypoints, SplineConfig config = {} )

static

Build a spline path from waypoint positions.

Equivalent alias of from_waypoints_interpolating: the spline passes through every waypoint. Both names are supported.

waypoints is a (dim x n_points) matrix where each column is one waypoint. At least one dimension and two waypoint columns are required.

Column-major views can cross the bridge directly. Row-major views are accepted for convenience and copied once into column-major storage before calling Rust.

The input view only needs to remain valid during this call; the returned Path owns the constructed Rust path.

Parameters

waypoints	Borrowed waypoint matrix.
config	Spline order, parameter range, and out-of-range policy.

Returns

Movable owning Path.

Exceptions

copp::Error

on invalid shape, invalid config, or Rust spline construction failure.

auto waypoints = copp::Matrix::from_columns({
    {0.0, 0.0},
    {0.5, 0.25},
    {1.0, 1.0},
});
auto path = copp::Path::from_waypoints(waypoints.view());

from_waypoints() [2/6]

Expected< Path > copp::Path::from_waypoints ( MatrixView waypoints, SplineConfig config, NoThrowTag  )

inlinestatic

Definition at line 758 of file path.hpp.

from_waypoints() [3/6]

Expected< Path > copp::Path::from_waypoints ( MatrixView waypoints, NoThrowTag tag )

inlinestatic

Definition at line 766 of file path.hpp.

from_waypoints() [4/6]

Path copp::Path::from_waypoints ( std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config = {} )

static

Build a spline path from waypoint-list notation.

Each inner list is one waypoint vector. The example below creates a two-dimensional path through three waypoints:

Parameters

waypoints	Outer list of waypoint vectors, not matrix rows.
config	Spline construction options.

Returns

Movable owning Path.

Exceptions

copp::Error

if the waypoint list is empty, ragged, or invalid.

auto path = copp::Path::from_waypoints({
    {0.0, 0.0},
    {0.5, 0.25},
    {1.0, 1.0},
});

from_waypoints() [5/6]

Expected< Path > copp::Path::from_waypoints ( std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config, NoThrowTag  )

inlinestatic

Definition at line 771 of file path.hpp.

from_waypoints() [6/6]

Expected< Path > copp::Path::from_waypoints ( std::initializer_list< std::initializer_list< double > > waypoints, NoThrowTag tag )

inlinestatic

Definition at line 779 of file path.hpp.

from_waypoints_interpolating() [1/6]

Path copp::Path::from_waypoints_interpolating ( MatrixView waypoints, SplineConfig config = {} )

static

Build a spline path that interpolates every waypoint.

The path passes through every waypoint column at its assigned parameter, up to floating-point roundoff. Choose it when each waypoint is a position or event that must be retained; use from_waypoints_fitting when the waypoints form a reference polyline that may be approximated within tolerances.

waypoints is a (dim x n_points) matrix where each column is one waypoint. At least one dimension and two waypoint columns are required. Row-major views are copied once into column-major storage; the view only needs to remain valid during this call.

Warning

Unstable API: the waypoint interpolation and fitting constructor families (all from_waypoints* overloads) may change names, signatures, configuration types, and method-selection interfaces in future releases as more algorithms are added.

Parameters

waypoints	Borrowed waypoint matrix.
config	Spline order, parameter range, boundary states, and out-of-range policy.

Returns

Movable owning Path.

Exceptions

copp::Error

on invalid shape, invalid config, or Rust spline construction failure.

auto waypoints = copp::Matrix::from_columns({
    {0.0, 0.0},
    {0.5, 0.25},
    {1.0, 1.0},
});
auto path = copp::Path::from_waypoints_interpolating(waypoints.view());

from_waypoints_interpolating() [2/6]

Expected< Path > copp::Path::from_waypoints_interpolating ( MatrixView waypoints, SplineConfig config, NoThrowTag  )

inlinestatic

Definition at line 786 of file path.hpp.

from_waypoints_interpolating() [3/6]

Expected< Path > copp::Path::from_waypoints_interpolating ( MatrixView waypoints, NoThrowTag tag )

inlinestatic

Definition at line 794 of file path.hpp.

from_waypoints_interpolating() [4/6]

Path copp::Path::from_waypoints_interpolating ( std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config = {} )

static

Build an interpolating spline path from waypoint-list notation.

Each inner list is one waypoint vector, not a matrix row.

Warning

Unstable API; see the MatrixView overload.

auto path = copp::Path::from_waypoints_interpolating({
    {0.0, 0.0},
    {0.5, 0.25},
    {1.0, 1.0},
});

from_waypoints_interpolating() [5/6]

Expected< Path > copp::Path::from_waypoints_interpolating ( std::initializer_list< std::initializer_list< double > > waypoints, SplineConfig config, NoThrowTag  )

inlinestatic

Definition at line 799 of file path.hpp.

from_waypoints_interpolating() [6/6]

Expected< Path > copp::Path::from_waypoints_interpolating ( std::initializer_list< std::initializer_list< double > > waypoints, NoThrowTag tag )

inlinestatic

Definition at line 807 of file path.hpp.

from_waypoints_fitting() [1/6]

Path copp::Path::from_waypoints_fitting ( MatrixView waypoints, SmoothingConfig config = {} )

static

Build a tolerance-bounded fitted path from waypoint positions.

Adjacent waypoint columns form a reference polyline under one common parameter. The result uses adaptive nonuniform C4 quintic B-splines and does not pass through interior waypoints: selected axes may deviate from the polyline within their tolerances, while endpoint positions are retained. The absolute error at the same parameter is numerically audited over every complete reference interval. Unselected axes keep C4 quintic interpolation through all columns. Inspect the achieved bounds with smoothing_report().

Fitting is geometric preprocessing, not time parameterization; path derivatives remain derivatives with respect to s.

Warning

Unstable API: the waypoint interpolation and fitting constructor families (all from_waypoints* overloads) may change names, signatures, configuration types, and method-selection interfaces in future releases as more algorithms are added.

Parameters

waypoints	Borrowed (dim x n_points) waypoint matrix.
config	Tolerances, axis selection, parameters, and budgets.

Returns

Movable owning Path with a populated smoothing_report().

Exceptions

copp::Error

on invalid shape or configuration, or when the tolerances cannot be met within the configured budgets.

copp::SmoothingConfig config;
config.tolerance = 1.0e-3;
auto path = copp::Path::from_waypoints_fitting(waypoints.view(), config);
auto report = path.smoothing_report(); // report->max_errors[i] <= 1e-3

from_waypoints_fitting() [2/6]

Expected< Path > copp::Path::from_waypoints_fitting ( MatrixView waypoints, SmoothingConfig config, NoThrowTag  )

inlinestatic

Definition at line 814 of file path.hpp.

from_waypoints_fitting() [3/6]

Expected< Path > copp::Path::from_waypoints_fitting ( MatrixView waypoints, NoThrowTag tag )

inlinestatic

Definition at line 822 of file path.hpp.

from_waypoints_fitting() [4/6]

Path copp::Path::from_waypoints_fitting ( std::initializer_list< std::initializer_list< double > > waypoints, SmoothingConfig config = {} )

static

Build a tolerance-bounded fitted path from waypoint-list notation.

Each inner list is one waypoint vector, not a matrix row.

Warning

Unstable API; see the MatrixView overload.

from_waypoints_fitting() [5/6]

Expected< Path > copp::Path::from_waypoints_fitting ( std::initializer_list< std::initializer_list< double > > waypoints, SmoothingConfig config, NoThrowTag  )

inlinestatic

Definition at line 827 of file path.hpp.

from_waypoints_fitting() [6/6]

Expected< Path > copp::Path::from_waypoints_fitting ( std::initializer_list< std::initializer_list< double > > waypoints, NoThrowTag tag )

inlinestatic

Definition at line 835 of file path.hpp.

from_parametric() [1/4]

Path copp::Path::from_parametric ( PathParametric parametric, double s_min, double s_max )

static

Build a path from a scalar-parametric formula.

The callback receives a seeded Jet3 value and returns one Jet3 per path dimension. The dimension is inferred by probing the callback once at the midpoint of [s_min, s_max]. Derivatives up to third order are propagated by Jet3 arithmetic.

Parameters

parametric	Function from scalar s to a vector-valued path.
s_min	Lower bound of the valid path range.
s_max	Upper bound of the valid path range.

Returns

Movable owning Path.

Exceptions

copp::Error

if the callback is empty, returns zero or inconsistent dimension, throws during probing/evaluation, or the range is invalid.

from_parametric() [2/4]

Expected< Path > copp::Path::from_parametric ( PathParametric parametric, double s_min, double s_max, NoThrowTag  )

inlinestatic

Definition at line 842 of file path.hpp.

from_parametric() [3/4]

Path copp::Path::from_parametric ( std::size_t dim, double s_min, double s_max, PathParametricWriter parametric )

static

Build a path from a scalar-parametric formula that writes into a buffer.

This overload avoids allocating a std::vector<Jet3> on each path sample. The callback must write exactly dim entries into q.

Parameters

dim	Path dimension / number of entries written by the callback.
s_min	Lower bound of the valid path range.
s_max	Upper bound of the valid path range.
parametric	Allocation-free writer callback.

from_parametric() [4/4]

Expected< Path > copp::Path::from_parametric ( std::size_t dim, double s_min, double s_max, PathParametricWriter parametric, NoThrowTag  )

inlinestatic

Definition at line 852 of file path.hpp.

from_evaluator_2nd() [1/2]

Path copp::Path::from_evaluator_2nd ( std::size_t dim, double s_min, double s_max, PathEvaluator2nd evaluator )

static

Build a path from a batch evaluator with explicit derivatives up to second order.

The returned Path owns the callback. dim must be positive and remain consistent with the callback's output writes. The path range must satisfy finite s_min < s_max.

Parameters

dim	Path dimension.
s_min	Lower range endpoint.
s_max	Upper range endpoint.
evaluator	Batch callback that fills q, dq, and ddq.

Returns

Movable owning Path.

Exceptions

copp::Error

on invalid dimensions/range or callback failure.

from_evaluator_2nd() [2/2]

Expected< Path > copp::Path::from_evaluator_2nd ( std::size_t dim, double s_min, double s_max, PathEvaluator2nd evaluator, NoThrowTag  )

inlinestatic

Definition at line 863 of file path.hpp.

from_evaluator_3rd() [1/2]

Path copp::Path::from_evaluator_3rd ( std::size_t dim, double s_min, double s_max, PathEvaluator3rd evaluator )

static

Build a path from a batch evaluator with explicit derivatives up to third order.

The returned Path owns the callback. dim must be positive and remain consistent with the callback's output writes. The path range must satisfy finite s_min < s_max.

A third-order evaluator can also be used by TOPP2/COPP2 workflows; the facade requests only the derivatives that each solver needs.

from_evaluator_3rd() [2/2]

Expected< Path > copp::Path::from_evaluator_3rd ( std::size_t dim, double s_min, double s_max, PathEvaluator3rd evaluator, NoThrowTag  )

inlinestatic

Definition at line 874 of file path.hpp.

operator=() [1/2]

Path & copp::Path::operator= ( Path && )

noexcept

operator=() [2/2]

Path & copp::Path::operator= ( const Path & )

delete

dim()

std::size_t copp::Path::dim

(

)

const

Return the path dimension.

Returns

Number of generalized coordinates in q(s).

s_range()

std::pair< double, double > copp::Path::s_range

(

)

const

Return the valid path-parameter interval (s_min, s_max).

Returns

Pair {s_min, s_max}.

evaluate_q() [1/2]

PathDerivatives copp::Path::evaluate_q

(

Span< const double >

s

)

const

Evaluate position samples only.

Returns PathDerivatives with q populated and derivative fields empty.

Parameters

s	Query samples.

Returns

Column-major matrix q with shape (dim(), s.size()).

Exceptions

copp::Error

if samples are invalid or the underlying evaluator fails.

evaluate_q() [2/2]

Expected< PathDerivatives > copp::Path::evaluate_q ( Span< const double > s, NoThrowTag  ) const

inline

Definition at line 885 of file path.hpp.

evaluate_up_to_2nd() [1/2]

PathDerivatives copp::Path::evaluate_up_to_2nd

(

Span< const double >

s

)

const

Evaluate position, first derivative, and second derivative.

Returns q, dq, and ddq, each with shape (dim, s.size()).

Parameters

s	Query samples.

Returns

PathDerivatives with q, dq, and ddq populated.

evaluate_up_to_2nd() [2/2]

Expected< PathDerivatives > copp::Path::evaluate_up_to_2nd ( Span< const double > s, NoThrowTag  ) const

inline

Definition at line 890 of file path.hpp.

evaluate_up_to_3rd() [1/2]

PathDerivatives copp::Path::evaluate_up_to_3rd

(

Span< const double >

s

)

const

Evaluate position, first derivative, second derivative, and third derivative.

Returns q, dq, ddq, and dddq, each with shape (dim, s.size()).

Parameters

s	Query samples.

Returns

PathDerivatives with all derivative matrices populated.

evaluate_up_to_3rd() [2/2]

Expected< PathDerivatives > copp::Path::evaluate_up_to_3rd ( Span< const double > s, NoThrowTag  ) const

inline

Definition at line 895 of file path.hpp.

smoothing_report()

std::optional< SmoothingReport > copp::Path::smoothing_report

(

)

const

Return fitting diagnostics of a path built by from_waypoints_fitting.

Returns

A copied SmoothingReport, or std::nullopt for interpolated, parametric, and evaluator paths.

Friends And Related Symbol Documentation

detail::path_handle

const void * detail::path_handle ( const Path & path )

friend

---

The documentation for this class was generated from the following file:

• bindings/cpp/include/copp/path.hpp