max/splines
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Refactor the Interpolate trait and add the Interpolator trait.

Browse Source 
This commit represents 99% of the rework. From now on, implementing the
API requires to provide the various interpolation implementations. This
is actually a good thing, because people will now be able to either use
the `impl_Interpolate!` macro, which implements the interpolation in a
very “math” way (using std::ops::* traits and float literals), or by
providing their own.
This commit is contained in:
Dimitri Sabadie
2021-03-05 02:03:46 +01:00
parent 3d43e4c644
commit 0ccc3c0956
2 changed files with 123 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

341
src/interpolate.rs
View File

@@ -42,277 +42,126 @@ use core::ops::{Add, Mul, Sub};
use std::f32;
#[cfg(feature = "std")]
use std::f64;
#[cfg(feature = "std")]
use std::ops::{Add, Mul, Sub};
/// Keys that can be interpolated in between. Implementing this trait is required to perform
/// sampling on splines.
/// Types that can be used as interpolator in splines.
///
/// `T` is the variable used to sample with. Typical implementations use [`f32`] or [`f64`], but
/// you’re free to use the ones you like. Feel free to have a look at [`Spline::sample`] for
/// instance to know which trait your type must implement to be usable.
/// An interpolator value is like the fabric on which control keys (and sampled values) live on.
pub trait Interpolator: Sized + Copy + PartialOrd {
/// Normalize the interpolator.
fn normalize(self, start: Self, end: Self) -> Self;
}
macro_rules! impl_Interpolator {
($t:ty) => {
impl Interpolator for $t {
fn normalize(self, start: Self, end: Self) -> Self {
(self - start) / (end - start)
}
}
};
}
impl_Interpolator!(f32);
impl_Interpolator!(f64);
/// Values that can be interpolated. Implementing this trait is required to perform sampling on splines.
///
/// [`Spline::sample`]: crate::spline::Spline::sample
pub trait Interpolate<T>: Sized + Copy + Linear<T> {
/// `T` is the interpolator used to sample with. Typical implementations use [`f32`] or [`f64`], but
/// you’re free to use the ones you like.
pub trait Interpolate<T>: Sized + Copy {
/// Step interpolation.
fn step(t: T, threshold: T, a: Self, b: Self) -> Self;
/// Linear interpolation.
fn lerp(a: Self, b: Self, t: T) -> Self;
fn lerp(t: T, a: Self, b: Self) -> Self;
/// Cosine interpolation.
fn cosine(t: T, a: Self, b: Self) -> Self;
/// Cubic hermite interpolation.
///
/// Default to [`lerp`].
///
/// [`lerp`]: Interpolate::lerp
fn cubic_hermite(_: (Self, T), a: (Self, T), b: (Self, T), _: (Self, T), t: T) -> Self {
Self::lerp(a.0, b.0, t)
}
fn cubic_hermite(t: T, x: (T, Self), a: (T, Self), b: (T, Self), y: (T, Self)) -> Self;
/// Quadratic Bézier interpolation.
fn quadratic_bezier(a: Self, u: Self, b: Self, t: T) -> Self;
///
/// `a` is the first point; `b` is the second point and `u` is the tangent of `a` to the curve.
fn quadratic_bezier(t: T, a: Self, u: Self, b: Self) -> Self;
/// Cubic Bézier interpolation.
fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: T) -> Self;
///
/// `a` is the first point; `b` is the second point; `u` is the output tangent of `a` to the curve and `v` is the
/// input tangent of `b` to the curve.
fn cubic_bezier(t: T, a: Self, u: Self, v: Self, b: Self) -> Self;
/// Cubic Bézier interpolation – special case for non-explicit second tangent.
///
/// This version does the same computation as [`Interpolate::cubic_bezier`] but computes the second tangent by
/// inversing it (typical when the next point uses a Bézier interpolation, where input and output tangents are
/// mirrored for the same key).
fn cubic_bezier_mirrored(t: T, a: Self, u: Self, v: Self, b: Self) -> Self;
}
/// Set of types that support additions and subtraction.
///
/// The [`Copy`] trait is also a supertrait as it’s likely to be used everywhere.
pub trait Additive: Copy + Add<Self, Output = Self> + Sub<Self, Output = Self> {}
impl<T> Additive for T where T: Copy + Add<Self, Output = Self> + Sub<Self, Output = Self> {}
/// Set of additive types that support outer multiplication and division, making them linear.
pub trait Linear<T>: Additive {
/// Apply an outer multiplication law.
fn outer_mul(self, t: T) -> Self;
/// Apply an outer division law.
fn outer_div(self, t: T) -> Self;
}
macro_rules! impl_linear_simple {
($t:ty) => {
impl Linear<$t> for $t {
fn outer_mul(self, t: $t) -> Self {
self * t
#[macro_export]
macro_rules! impl_Interpolate {
($t:ty, $v:ty, $pi:expr) => {
impl $crate::interpolate::Interpolate<$t> for $v {
fn step(t: $t, threshold: $t, a: Self, b: Self) -> Self {
if t < threshold {
a
} else {
b
}
}
/// Apply an outer division law.
fn outer_div(self, t: $t) -> Self {
self / t
}
}
};
}
impl_linear_simple!(f32);
impl_linear_simple!(f64);
macro_rules! impl_linear_cast {
($t:ty, $q:ty) => {
impl Linear<$t> for $q {
fn outer_mul(self, t: $t) -> Self {
self * t as $q
fn cosine(t: $t, a: Self, b: Self) -> Self {
let cos_nt = (1. - (t * $pi).cos()) * 0.5;
<Self as $crate::interpolate::Interpolate<$t>>::lerp(cos_nt, a, b)
}
/// Apply an outer division law.
fn outer_div(self, t: $t) -> Self {
self / t as $q
}
}
};
}
impl_linear_cast!(f32, f64);
impl_linear_cast!(f64, f32);
/// Types with a neutral element for multiplication.
pub trait One {
/// The neutral element for the multiplicative monoid — typically called `1`.
fn one() -> Self;
}
macro_rules! impl_one_float {
($t:ty) => {
impl One for $t {
#[inline(always)]
fn one() -> Self {
1.
}
}
};
}
impl_one_float!(f32);
impl_one_float!(f64);
/// Types with a sane definition of π and cosine.
pub trait Trigo {
/// π.
fn pi() -> Self;
/// Cosine of the argument.
fn cos(self) -> Self;
}
impl Trigo for f32 {
#[inline(always)]
fn pi() -> Self {
f32::consts::PI
}
#[inline(always)]
fn cos(self) -> Self {
#[cfg(feature = "std")]
{
self.cos()
}
#[cfg(not(feature = "std"))]
{
unsafe { cosf32(self) }
}
}
}
impl Trigo for f64 {
#[inline(always)]
fn pi() -> Self {
f64::consts::PI
}
#[inline(always)]
fn cos(self) -> Self {
#[cfg(feature = "std")]
{
self.cos()
}
#[cfg(not(feature = "std"))]
{
unsafe { cosf64(self) }
}
}
}
/// Default implementation of [`Interpolate::cubic_hermite`].
///
/// `V` is the value being interpolated. `T` is the sampling value (also sometimes called time).
pub fn cubic_hermite_def<V, T>(x: (V, T), a: (V, T), b: (V, T), y: (V, T), t: T) -> V
where
V: Linear<T>,
T: Additive + Mul<T, Output = T> + One,
{
// some stupid generic constants, because Rust doesn’t have polymorphic literals…
let one_t = T::one();
let two_t = one_t + one_t; // lolololol
let three_t = two_t + one_t; // megalol
// sampler stuff
let t2 = t * t;
let t3 = t2 * t;
let two_t3 = t3 * two_t;
let three_t2 = t2 * three_t;
// tangents
let m0 = (b.0 - x.0).outer_div(b.1 - x.1);
let m1 = (y.0 - a.0).outer_div(y.1 - a.1);
a.0.outer_mul(two_t3 - three_t2 + one_t)
+ m0.outer_mul(t3 - t2 * two_t + t)
+ b.0.outer_mul(three_t2 - two_t3)
+ m1.outer_mul(t3 - t2)
}
/// Default implementation of [`Interpolate::quadratic_bezier`].
///
/// `V` is the value being interpolated. `T` is the sampling value (also sometimes called time).
pub fn quadratic_bezier_def<V, T>(a: V, u: V, b: V, t: T) -> V
where
V: Linear<T>,
T: Additive + Mul<T, Output = T> + One,
{
let one_t = T::one() - t;
let one_t_2 = one_t * one_t;
u + (a - u).outer_mul(one_t_2) + (b - u).outer_mul(t * t)
}
/// Default implementation of [`Interpolate::cubic_bezier`].
///
/// `V` is the value being interpolated. `T` is the sampling value (also sometimes called time).
pub fn cubic_bezier_def<V, T>(a: V, u: V, v: V, b: V, t: T) -> V
where
V: Linear<T>,
T: Additive + Mul<T, Output = T> + One,
{
let one_t = T::one() - t;
let one_t_2 = one_t * one_t;
let one_t_3 = one_t_2 * one_t;
let three = T::one() + T::one() + T::one();
a.outer_mul(one_t_3)
+ u.outer_mul(three * one_t_2 * t)
+ v.outer_mul(three * one_t * t * t)
+ b.outer_mul(t * t * t)
}
macro_rules! impl_interpolate_simple {
($t:ty) => {
impl Interpolate<$t> for $t {
fn lerp(a: Self, b: Self, t: $t) -> Self {
fn lerp(t: $t, a: Self, b: Self) -> Self {
a * (1. - t) + b * t
}
fn cubic_hermite(x: (Self, $t), a: (Self, $t), b: (Self, $t), y: (Self, $t), t: $t) -> Self {
cubic_hermite_def(x, a, b, y, t)
fn cubic_hermite(t: $t, x: ($t, Self), a: ($t, Self), b: ($t, Self), y: ($t, Self)) -> Self {
// sampler stuff
let two_t = t * 2.;
let three_t = t * 3.;
let t2 = t * t;
let t3 = t2 * t;
let two_t3 = t3 * two_t;
let three_t2 = t2 * three_t;
// tangents
let m0 = (b.1 - x.1) / (b.0 - x.0);
let m1 = (y.1 - a.1) / (y.0 - a.0);
a.1 * (two_t3 - three_t2 + 1.)
+ m0 * (t3 - t2 * two_t + t)
+ b.1 * (three_t2 - two_t3)
+ m1 * (t3 - t2)
}
fn quadratic_bezier(a: Self, u: Self, b: Self, t: $t) -> Self {
quadratic_bezier_def(a, u, b, t)
fn quadratic_bezier(t: $t, a: Self, u: Self, b: Self) -> Self {
let one_t = 1. - t;
let one_t2 = one_t * one_t;
u + (a - u) * one_t2 + (b - u) * t * t
}
fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: $t) -> Self {
cubic_bezier_def(a, u, v, b, t)
fn cubic_bezier(t: $t, a: Self, u: Self, v: Self, b: Self) -> Self {
let one_t = 1. - t;
let one_t2 = one_t * one_t;
let one_t3 = one_t2 * one_t;
let t2 = t * t;
a * one_t3 + (u * one_t2 * t + v * one_t * t2) * 3. + b * t2 * t
}
fn cubic_bezier_mirrored(t: $t, a: Self, u: Self, v: Self, b: Self) -> Self {
<Self as $crate::interpolate::Interpolate<$t>>::cubic_bezier(t, a, u, b + b - v, b)
}
}
};
}
impl_interpolate_simple!(f32);
impl_interpolate_simple!(f64);
macro_rules! impl_interpolate_via {
($t:ty, $v:ty) => {
impl Interpolate<$t> for $v {
fn lerp(a: Self, b: Self, t: $t) -> Self {
a * (1. - t as $v) + b * t as $v
}
fn cubic_hermite(
(x, xt): (Self, $t),
(a, at): (Self, $t),
(b, bt): (Self, $t),
(y, yt): (Self, $t),
t: $t,
) -> Self {
cubic_hermite_def(
(x, xt as $v),
(a, at as $v),
(b, bt as $v),
(y, yt as $v),
t as $v,
)
}
fn quadratic_bezier(a: Self, u: Self, b: Self, t: $t) -> Self {
quadratic_bezier_def(a, u, b, t as $v)
}
fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: $t) -> Self {
cubic_bezier_def(a, u, v, b, t as $v)
}
}
};
}
impl_interpolate_via!(f32, f64);
impl_interpolate_via!(f64, f32);
impl_Interpolate!(f32, f32, std::f32::consts::PI);
impl_Interpolate!(f64, f64, std::f64::consts::PI);

74
src/spline.rs
View File

@@ -1,5 +1,9 @@
//! Spline curves and operations.
#[cfg(feature = "std")]
use crate::interpolate::{Interpolate, Interpolator};
use crate::interpolation::Interpolation;
use crate::key::Key;
#[cfg(not(feature = "std"))]
use alloc::vec::Vec;
#[cfg(not(feature = "std"))]
@@ -10,12 +14,6 @@ use core::ops::{Div, Mul};
use serde_derive::{Deserialize, Serialize};
#[cfg(feature = "std")]
use std::cmp::Ordering;
#[cfg(feature = "std")]
use std::ops::{Div, Mul};
use crate::interpolate::{Additive, Interpolate, One, Trigo};
use crate::interpolation::Interpolation;
use crate::key::Key;
/// Spline curve used to provide interpolation between control points (keys).
///
@@ -104,8 +102,8 @@ impl<T, V> Spline<T, V> {
/// the sampling.
pub fn sample_with_key(&self, t: T) -> Option<SampledWithKey<V>>
where
T: Additive + One + Trigo + Mul<T, Output = T> + Div<T, Output = T> + PartialOrd,
V: Additive + Interpolate<T>,
T: Interpolator,
V: Interpolate<T>,
{
let keys = &self.0;
let i = search_lower_cp(keys, t)?;
@@ -114,26 +112,24 @@ impl<T, V> Spline<T, V> {
let value = match cp0.interpolation {
Interpolation::Step(threshold) => {
let cp1 = &keys[i + 1];
let nt = normalize_time(t, cp0, cp1);
let value = if nt < threshold { cp0.value } else { cp1.value };
let nt = t.normalize(cp0.t, cp1.t);
let value = V::step(nt, threshold, cp0.value, cp1.value);
Some(value)
}
Interpolation::Linear => {
let cp1 = &keys[i + 1];
let nt = normalize_time(t, cp0, cp1);
let value = Interpolate::lerp(cp0.value, cp1.value, nt);
let nt = t.normalize(cp0.t, cp1.t);
let value = V::lerp(nt, cp0.value, cp1.value);
Some(value)
}
Interpolation::Cosine => {
let two_t = T::one() + T::one();
let cp1 = &keys[i + 1];
let nt = normalize_time(t, cp0, cp1);
let cos_nt = (T::one() - (nt * T::pi()).cos()) / two_t;
let value = Interpolate::lerp(cp0.value, cp1.value, cos_nt);
let nt = t.normalize(cp0.t, cp1.t);
let value = V::cosine(nt, cp0.value, cp1.value);
Some(value)
}
@@ -147,13 +143,13 @@ impl<T, V> Spline<T, V> {
let cp1 = &keys[i + 1];
let cpm0 = &keys[i - 1];
let cpm1 = &keys[i + 2];
let nt = normalize_time(t, cp0, cp1);
let value = Interpolate::cubic_hermite(
(cpm0.value, cpm0.t),
(cp0.value, cp0.t),
(cp1.value, cp1.t),
(cpm1.value, cpm1.t),
let nt = t.normalize(cp0.t, cp1.t);
let value = V::cubic_hermite(
nt,
(cpm0.t, cpm0.value),
(cp0.t, cp0.value),
(cp1.t, cp1.value),
(cpm1.t, cpm1.value),
);
Some(value)
@@ -163,18 +159,14 @@ impl<T, V> Spline<T, V> {
Interpolation::Bezier(u) | Interpolation::StrokeBezier(_, u) => {
// We need to check the next control point to see whether we want quadratic or cubic Bezier.
let cp1 = &keys[i + 1];
let nt = normalize_time(t, cp0, cp1);
let nt = t.normalize(cp0.t, cp1.t);
let value = match cp1.interpolation {
Interpolation::Bezier(v) => {
Interpolate::cubic_bezier(cp0.value, u, cp1.value + cp1.value - v, cp1.value, nt)
}
Interpolation::Bezier(v) => V::cubic_bezier_mirrored(nt, cp0.value, u, v, cp1.value),
Interpolation::StrokeBezier(v, _) => {
Interpolate::cubic_bezier(cp0.value, u, v, cp1.value, nt)
}
Interpolation::StrokeBezier(v, _) => V::cubic_bezier(nt, cp0.value, u, v, cp1.value),
_ => Interpolate::quadratic_bezier(cp0.value, u, cp1.value, nt),
_ => V::quadratic_bezier(nt, cp0.value, u, cp1.value),
};
Some(value)
@@ -188,8 +180,8 @@ impl<T, V> Spline<T, V> {
///
pub fn sample(&self, t: T) -> Option<V>
where
T: Additive + One + Trigo + Mul<T, Output = T> + Div<T, Output = T> + PartialOrd,
V: Additive + Interpolate<T>,
T: Interpolator,
V: Interpolate<T>,
{
self.sample_with_key(t).map(|sampled| sampled.value)
}
@@ -207,8 +199,8 @@ impl<T, V> Spline<T, V> {
/// This function returns [`None`] if you have no key.
pub fn clamped_sample_with_key(&self, t: T) -> Option<SampledWithKey<V>>
where
T: Additive + One + Trigo + Mul<T, Output = T> + Div<T, Output = T> + PartialOrd,
V: Additive + Interpolate<T>,
T: Interpolator,
V: Interpolate<T>,
{
if self.0.is_empty() {
return None;
@@ -242,8 +234,8 @@ impl<T, V> Spline<T, V> {
/// Sample a spline at a given time with clamping.
pub fn clamped_sample(&self, t: T) -> Option<V>
where
T: Additive + One + Trigo + Mul<T, Output = T> + Div<T, Output = T> + PartialOrd,
V: Additive + Interpolate<T>,
T: Interpolator,
V: Interpolate<T>,
{
self.clamped_sample_with_key(t).map(|sampled| sampled.value)
}
@@ -322,16 +314,6 @@ pub struct KeyMut<'a, T, V> {
pub interpolation: &'a mut Interpolation<T, V>,
}
// Normalize a time ([0;1]) given two control points.
#[inline(always)]
pub(crate) fn normalize_time<T, V>(t: T, cp: &Key<T, V>, cp1: &Key<T, V>) -> T
where
T: Additive + Div<T, Output = T> + PartialEq,
{
assert!(cp1.t != cp.t, "overlapping keys");
(t - cp.t) / (cp1.t - cp.t)
}
// Find the lower control point corresponding to a given time.
fn search_lower_cp<T, V>(cps: &[Key<T, V>], t: T) -> Option<usize>
where