Smoothness and derivatives for (cubic) curves

[mweatherley]

This is another prototype as part of the Curve project. Once again, I have ignored NURBS for the time being.

Objective

Provide a general framework for expressing smoothness for curves (up to C2) and integrate it with bevy_math's existing cubic spline constructions.

Solution

Continuous/differentiable curves

There are a few layers here. At the most basic level, we have a trait-enshrined way of expressing tangent spaces at the level of types:

pub trait HasTangent {
    type Tangent;
}

The point of this is that it is used to define types WithDerivative<T> and WithTwoDerivatives<T> that pair a point with derivatives at that point (elements of the tangent space). For example:

/// A point with a tangent.
pub struct WithDerivative<T>
where
    T: HasTangent,
{
    /// The underlying point.
    pub point: T,
    /// The derivative at `point`.
    pub derivative: T::Tangent,
}

Now, the central idea connecting this to curves is that a differentiable curve is a curve that returns WithDerivative<T> when sampled, so that the point component provides the position and derivative provides the velocity. We have introduced some new traits that work this way: they are just marker traits on top of Curve<...>:

pub trait ContinuousCurve<T>: Curve<T> {}

pub trait DifferentiableCurve<T>: Curve<WithDerivative<T>>
where
    T: HasTangent,
{
}

//...

Of course, with these traits, it's worth keeping in mind that they will not be preserved by the abstract Curve interface methods. For example, applying Curve::map to a differentiable curve, the result need not generally be differentiable. The same is true for many operations, including simple ones like compose (which joins two curves end-to-end).

On the other hand, the result of calling such functions may actually be continuous, differentiable, and so on. To bridge this gap in expressivity, we have also introduced a wrapper struct Blessed and a method bless that produces it so that the user can explicitly elevate to the level of these marker traits when necessary:

/// Bless this curve, allowing it to be treated as continuous, differentiable, and so on.
fn bless(self) -> Blessed<Self> {
    Blessed(self)
}

Cubic segments and curves

The interoperation of cubic curves with this new technology comes in a few parts. Firstly, CubicCurve has an additional marker type parameter S: Smoothness which indicates the global guarantees of smoothness that issue from the curve's construction. This parameter has four levels: Nothing, C0, C1, and C2. CubicCurve<P, S> is itself a Curve<P>, sampling from its position. If its Smoothness parameter is at least C0, then it is a ContinuousCurve. CubicSegment<P> is similar, but it is always a ContinuousCurve (it has no Smoothness parameter).

To access higher derivative information through the Curve interface, there are a pair of new methods on both CubicSegment and CubicCurve:

/// Returns a [curve] whose samples include both the position and velocity from this curve. If
/// this curve is at least C1, then the output is a [`DifferentiableCurve`].
///
/// [curve]: Curve
#[inline]
pub fn with_velocity(&self) -> SegmentDerivative<&Self> {
    SegmentDerivative(&self)
}

/// Returns a [curve] whose samples include the position, velocity, and acceleration from this
/// curve. If this curve is at least C2, then the output is a [`TwiceDifferentiableCurve`].
///
/// [curve]: Curve
#[inline]
pub fn with_velocity_accel(&self) -> SegmentTwoDerivatives<&Self> {
    SegmentTwoDerivatives(&self)
}

CubicCurve is similar. The wrapper types SegmentDerivative and SegmentTwoDerivatives (truly inspired nomenclature) implement DifferentiableCurve and TwiceDifferentiableCurve respectively. Similarly, the wrapper types for CubicCurve — CurveDerivative and CurveTwoDerivatives — implement DifferentiableCurve and TwiceDifferentiableCurve if the underlying Smoothness parameter is at least C1 or C2 respectively.

Putting it together

For starters, we can use the Curve interface pretty seamlessly in conjunction with cubic splines:

// This is a `Curve<P>` where `P` is determined by the control data:
let my_curve = CubicBSpline::new(control_data).to_curve();
// so we can do all the usual curve operations on it:
let new_curve = my_curve.reparametrize(|t| f32::cbrt(t));

For something more complex, let's imagine we have some geometric operation which wants a differentiable curve as input and produces some output:

pub fn do_geometry(curve: impl DifferentiableCurve<Vec3>) -> Output { //... }

For a cubic curve, we could do something like this:

let my_curve = CubicHermite::new(points, tangents).to_curve().with_velocity();
let output = do_geometry(my_curve);

On the other hand, if I specified my inputs with CubicBezier but I made sure it's differentiable using the folds of my brain (or am willing to accept the consequences of doing something weird), I can use the bless interface to work with it:

let my_curve = CubicBezier::new(control_data).to_curve().with_velocity();
let output = do_geometry(my_curve.bless());

Migration Guide

Some existing uses of the CubicCurve type will need to be annotated with a Smoothness parameter in order for the program to compile. This is because CubicCurve now tracks its global continuity and differentiability guarantees. For similar reasons, existing uses of CubicCurve::push_segment or Extend::extend will require first calling CubicCurve::without_smoothness in order to destroy the smoothness guarantees from the curve's construction, since arbitrary concatenations of curve segments cannot be known by the compiler to maintain these guarantees.

[mweatherley]

Closing in favor of #16503 for now, which makes much less sweeping changes.