Trait CurveEvaluator

pub trait CurveEvaluator: Backend {
    // Required methods
    fn point_at(&self, curve: &Curve3, at: CurveMeasure) -> GeomResult<Point3>;
    fn tangent_at(&self, curve: &Curve3, at: CurveMeasure) -> GeomResult<Vec3>;
    fn frame_at(&self, curve: &Curve3, at: CurveMeasure) -> GeomResult<Frame3>;

    // Provided methods
    fn distance_convention(&self, curve: &Curve3) -> DistanceConvention { ... }
    fn determinism(&self) -> Determinism { ... }
}

Curve evaluation provider.

Implementing this trait is the capability declaration: it lets a consumer name “evaluate a curve at a distance” without depending on a particular engine. A provider that cannot evaluate curves must not implement it.

Why a frame and not just a tangent

A tangent fixes direction but not roll, so placing an object needs a full oriented frame. The convention has to be decided ONCE, here, because a wrong one tilts the placed object rather than failing loudly – and every consumer re-deriving it would fragment slightly.

Why the frame is not Frenet

The Frenet normal is the wrong tool for placement even though it is the classical one. On an alignment with a crest followed by a sag it points DOWN on the crest and UP in the sag, flipping at the inflection, and on any straight run the curvature is zero and the normal is undefined entirely. An object placed by it would be upright, then inverted, then unplaceable.

frame_at therefore uses a REFERENCE-UP frame: right = normalise(tangent x up) and up' = right x tangent, which is continuous through inflections and defined on straights. It is undefined only when the tangent is parallel to the reference direction – a truly vertical curve – where a provider must refuse rather than return an arbitrary roll.

Required Methods

fn point_at(&self, curve: &Curve3, at: CurveMeasure) -> GeomResult<Point3>

Position at at along curve.

CurveMeasure carries WHICH method of measurement the caller means, so a native parameter cannot be mistaken for a length. A Distance is interpreted in this provider’s distance_convention for this curve; a Parameter is the curve’s own parameter and is independent of that convention.

Refuses a non-finite value, a distance on a curve whose convention is Unsupported, and a value outside the curve.

fn tangent_at(&self, curve: &Curve3, at: CurveMeasure) -> GeomResult<Vec3>

Unit tangent at at along curve.

Unit length is part of the contract: a caller composing a rotation from this must not have to renormalise, and a non-unit result would silently scale whatever it is applied to.

fn frame_at(&self, curve: &Curve3, at: CurveMeasure) -> GeomResult<Frame3>

Oriented frame at at along curve.

x is the unit tangent, z is the reference-up direction, and y = z x x completes a right-handed orthonormal triad. See the trait docs for why this is not the Frenet frame.

Refuses when the tangent is parallel to up, where roll is genuinely undetermined.

Provided Methods

fn distance_convention(&self, curve: &Curve3) -> DistanceConvention

Which distance this provider measures for curve.

Callers MUST consult this before trusting a distance. Defaults to DistanceConvention::Unsupported so a provider that has not declared a convention is treated as unable rather than assumed to mean 3D arc length.

fn determinism(&self) -> Determinism

Reproducibility this provider guarantees.

Defaults to Determinism::BestEffort, the weakest level, so an unaudited provider cannot silently satisfy a stronger request.

Implementors