diff --git a/CHANGELOG.md b/CHANGELOG.md index 5332a6c..c0e9068 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,9 @@ +* [4.0](#40) + * [Major changes](#major-changes) + * [Patch changes](#patch-changes) * [3.5.4](#354) * [3.5.3](#353) * [3.5.2](#352) @@ -14,19 +17,19 @@ * [3.2](#32) * [3.1](#31) * [3.0](#30) - * [Major changes](#major-changes) - * [Patch changes](#patch-changes) + * [Major changes](#major-changes-1) + * [Patch changes](#patch-changes-1) * [2.2](#22) * [2.1.1](#211) * [2.1](#21) * [2.0.1](#201) * [2.0](#20) - * [Major changes](#major-changes-1) + * [Major changes](#major-changes-2) * [Minor changes](#minor-changes) * [1.0](#10) - * [Major changes](#major-changes-2) + * [Major changes](#major-changes-3) * [Minor changes](#minor-changes-1) - * [Patch changes](#patch-changes-1) + * [Patch changes](#patch-changes-2) * [0.2.3](#023) * [0.2.2](#022) * [0.2.1](#021) @@ -36,6 +39,26 @@ +# 4.0 + +> Mar 05, 2021 + +## Major changes + +- Switch the `Interpolation` enum to `#[non_exhaustive]` to allow adding more interpolation modes (if any) in the + future. +- Introduce `SampledWithKey`, which is a more elegant / typed way to access a sample along with its associated key + index. +- Refactor the `Interpolate` trait and add the `Interpolator` trait. + +## Patch changes + +- Highly simplify the various implementors (`cgmath`, `nalgebra` and `glam`) so that maintenance is easy. +- Expose the `impl_Interpolate` macro, allowing to implement the API all at once if a type implements the various + `std::ops:*` traits. Since most of the crates do, this macro makes it really easy to add support for a crate. +- Drop `simba` as a direct dependency. +- Drop `num-traits` as a direct dependency. + # 3.5.4 > Feb 27, 2021 diff --git a/Cargo.toml b/Cargo.toml index cfd42a1..432e06d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "splines" -version = "3.5.4" +version = "4.0.0" license = "BSD-3-Clause" authors = ["Dimitri Sabadie "] description = "Spline interpolation made easy" @@ -23,7 +23,7 @@ maintenance = { status = "actively-developed" } default = ["std"] impl-cgmath = ["cgmath"] impl-glam = ["glam"] -impl-nalgebra = ["nalgebra", "num-traits", "simba"] +impl-nalgebra = ["nalgebra"] serialization = ["serde", "serde_derive"] std = [] @@ -31,10 +31,8 @@ std = [] cgmath = { version = ">=0.17, <0.19", optional = true } glam = { version = ">=0.10, <0.13", optional = true } nalgebra = { version = ">=0.21, <0.25", optional = true } -num-traits = { version = "0.2", optional = true } serde = { version = "1", optional = true } serde_derive = { version = "1", optional = true } -simba = { version = ">=0.1.2, <0.5", optional = true } [dev-dependencies] float-cmp = ">=0.6, < 0.9" diff --git a/src/cgmath.rs b/src/cgmath.rs index 958c512..7f3f17e 100644 --- a/src/cgmath.rs +++ b/src/cgmath.rs @@ -1,92 +1,15 @@ -use cgmath::{ - BaseFloat, BaseNum, InnerSpace, Quaternion, Vector1, Vector2, Vector3, Vector4, VectorSpace, -}; +use crate::impl_Interpolate; -use crate::interpolate::{ - cubic_bezier_def, cubic_hermite_def, quadratic_bezier_def, Additive, Interpolate, Linear, One, -}; +use cgmath::{Quaternion, Vector1, Vector2, Vector3, Vector4}; -macro_rules! impl_interpolate_vec { - ($($t:tt)*) => { - impl Linear for $($t)* where T: BaseNum { - #[inline(always)] - fn outer_mul(self, t: T) -> Self { - self * t - } +impl_Interpolate!(f32, Vector1, std::f32::consts::PI); +impl_Interpolate!(f32, Vector2, std::f32::consts::PI); +impl_Interpolate!(f32, Vector3, std::f32::consts::PI); +impl_Interpolate!(f32, Vector4, std::f32::consts::PI); +impl_Interpolate!(f32, Quaternion, std::f32::consts::PI); - #[inline(always)] - fn outer_div(self, t: T) -> Self { - self / t - } - } - - impl Interpolate for $($t)* - where Self: InnerSpace, T: Additive + BaseFloat + One { - #[inline(always)] - fn lerp(a: Self, b: Self, t: T) -> Self { - a.lerp(b, t) - } - - #[inline(always)] - 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) - } - - #[inline(always)] - fn quadratic_bezier(a: Self, u: Self, b: Self, t: T) -> Self { - quadratic_bezier_def(a, u, b, t) - } - - #[inline(always)] - fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: T) -> Self { - cubic_bezier_def(a, u, v, b, t) - } - } - } -} - -impl_interpolate_vec!(Vector1); -impl_interpolate_vec!(Vector2); -impl_interpolate_vec!(Vector3); -impl_interpolate_vec!(Vector4); - -impl Linear for Quaternion -where - T: BaseFloat, -{ - #[inline(always)] - fn outer_mul(self, t: T) -> Self { - self * t - } - - #[inline(always)] - fn outer_div(self, t: T) -> Self { - self / t - } -} - -impl Interpolate for Quaternion -where - Self: InnerSpace, - T: Additive + BaseFloat + One, -{ - #[inline(always)] - fn lerp(a: Self, b: Self, t: T) -> Self { - a.nlerp(b, t) - } - - #[inline(always)] - 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) - } - - #[inline(always)] - fn quadratic_bezier(a: Self, u: Self, b: Self, t: T) -> Self { - quadratic_bezier_def(a, u, b, t) - } - - #[inline(always)] - fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: T) -> Self { - cubic_bezier_def(a, u, v, b, t) - } -} +impl_Interpolate!(f64, Vector1, std::f64::consts::PI); +impl_Interpolate!(f64, Vector2, std::f64::consts::PI); +impl_Interpolate!(f64, Vector3, std::f64::consts::PI); +impl_Interpolate!(f64, Vector4, std::f64::consts::PI); +impl_Interpolate!(f64, Quaternion, std::f64::consts::PI); diff --git a/src/glam.rs b/src/glam.rs index c9e510b..4333c14 100644 --- a/src/glam.rs +++ b/src/glam.rs @@ -1,88 +1,8 @@ +use crate::impl_Interpolate; use glam::{Quat, Vec2, Vec3, Vec3A, Vec4}; -use crate::interpolate::{ - cubic_bezier_def, cubic_hermite_def, quadratic_bezier_def, Interpolate, Linear, -}; - -macro_rules! impl_interpolate_vec { - ($($t:tt)*) => { - impl Linear for $($t)* { - #[inline(always)] - fn outer_mul(self, t: f32) -> Self { - self * t - } - - #[inline(always)] - fn outer_div(self, t: f32) -> Self { - self / t - } - } - - impl Interpolate for $($t)* { - #[inline(always)] - fn lerp(a: Self, b: Self, t: f32) -> Self { - a.lerp(b, t) - } - - #[inline(always)] - fn cubic_hermite( - x: (Self, f32), - a: (Self, f32), - b: (Self, f32), - y: (Self, f32), - t: f32, - ) -> Self { - cubic_hermite_def(x, a, b, y, t) - } - - #[inline(always)] - fn quadratic_bezier(a: Self, u: Self, b: Self, t: f32) -> Self { - quadratic_bezier_def(a, u, b, t) - } - - #[inline(always)] - fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: f32) -> Self { - cubic_bezier_def(a, u, v, b, t) - } - } - } -} - -impl_interpolate_vec!(Vec2); -impl_interpolate_vec!(Vec3); -impl_interpolate_vec!(Vec3A); -impl_interpolate_vec!(Vec4); - -impl Linear for Quat { - #[inline(always)] - fn outer_mul(self, t: f32) -> Self { - self * t - } - - #[inline(always)] - fn outer_div(self, t: f32) -> Self { - self / t - } -} - -impl Interpolate for Quat { - #[inline(always)] - fn lerp(a: Self, b: Self, t: f32) -> Self { - a.lerp(b, t) - } - - #[inline(always)] - fn cubic_hermite(x: (Self, f32), a: (Self, f32), b: (Self, f32), y: (Self, f32), t: f32) -> Self { - cubic_hermite_def(x, a, b, y, t) - } - - #[inline(always)] - fn quadratic_bezier(a: Self, u: Self, b: Self, t: f32) -> Self { - quadratic_bezier_def(a, u, b, t) - } - - #[inline(always)] - fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: f32) -> Self { - cubic_bezier_def(a, u, v, b, t) - } -} +impl_Interpolate!(f32, Vec2, std::f32::consts::PI); +impl_Interpolate!(f32, Vec3, std::f32::consts::PI); +impl_Interpolate!(f32, Vec3A, std::f32::consts::PI); +impl_Interpolate!(f32, Vec4, std::f32::consts::PI); +impl_Interpolate!(f32, Quat, std::f32::consts::PI); diff --git a/src/interpolate.rs b/src/interpolate.rs index 2ef09ba..6234258 100644 --- a/src/interpolate.rs +++ b/src/interpolate.rs @@ -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: Sized + Copy + Linear { +/// `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: 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 + Sub {} - -impl Additive for T where T: Copy + Add + Sub {} - -/// Set of additive types that support outer multiplication and division, making them linear. -pub trait Linear: 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; + >::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(x: (V, T), a: (V, T), b: (V, T), y: (V, T), t: T) -> V -where - V: Linear, - T: Additive + Mul + 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(a: V, u: V, b: V, t: T) -> V -where - V: Linear, - T: Additive + Mul + 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(a: V, u: V, v: V, b: V, t: T) -> V -where - V: Linear, - T: Additive + Mul + 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 { + >::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); diff --git a/src/interpolation.rs b/src/interpolation.rs index 031e99b..15e7e42 100644 --- a/src/interpolation.rs +++ b/src/interpolation.rs @@ -6,9 +6,13 @@ use serde_derive::{Deserialize, Serialize}; /// Available kind of interpolations. /// /// Feel free to visit each variant for more documentation. +#[non_exhaustive] #[derive(Copy, Clone, Debug, Eq, PartialEq)] -#[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))] -#[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))] +#[cfg_attr( + feature = "serialization", + derive(Deserialize, Serialize), + serde(rename_all = "snake_case") +)] pub enum Interpolation { /// Hold a [`Key`] until the sampling value passes the normalized step threshold, in which /// case the next key is used. @@ -20,12 +24,16 @@ pub enum Interpolation { /// /// [`Key`]: crate::key::Key Step(T), + /// Linear interpolation between a key and the next one. Linear, + /// Cosine interpolation between a key and the next one. Cosine, + /// Catmull-Rom interpolation, performing a cubic Hermite interpolation using four keys. CatmullRom, + /// Bézier interpolation. /// /// A control point that uses such an interpolation is associated with an extra point. The segmant @@ -41,6 +49,7 @@ pub enum Interpolation { /// point and the current control point’s associated point. This is called _quadratic Bézer /// interpolation_ and it kicks ass too, but a bit less than cubic. Bezier(V), + /// A special Bézier interpolation using an _input tangent_ and an _output tangent_. /// /// With this kind of interpolation, a control point has an input tangent, which has the same role @@ -53,8 +62,6 @@ pub enum Interpolation { /// /// Stroke Bézier interpolation is always a cubic Bézier interpolation by default. StrokeBezier(V, V), - #[doc(hidden)] - __NonExhaustive, } impl Default for Interpolation { diff --git a/src/key.rs b/src/key.rs index aca16dc..e366199 100644 --- a/src/key.rs +++ b/src/key.rs @@ -1,16 +1,15 @@ //! Spline control points. //! -//! A control point associates to a “sampling value” (a.k.a. time) a carriede value that can be +//! A control point associates to a “sampling value” (a.k.a. time) a carried value that can be //! interpolated along the curve made by the control points. //! //! Splines constructed with this crate have the property that it’s possible to change the //! interpolation mode on a key-based way, allowing you to implement and encode complex curves. +use crate::interpolation::Interpolation; #[cfg(feature = "serialization")] use serde_derive::{Deserialize, Serialize}; -use crate::interpolation::Interpolation; - /// A spline control point. /// /// This type associates a value at a given interpolation parameter value. It also contains an @@ -19,8 +18,11 @@ use crate::interpolation::Interpolation; /// /// [`Interpolation`]: crate::interpolation::Interpolation #[derive(Copy, Clone, Debug, Eq, PartialEq)] -#[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))] -#[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))] +#[cfg_attr( + feature = "serialization", + derive(Deserialize, Serialize), + serde(rename_all = "snake_case") +)] pub struct Key { /// Interpolation parameter at which the [`Key`] should be reached. pub t: T, diff --git a/src/nalgebra.rs b/src/nalgebra.rs index feb5f13..37da59a 100644 --- a/src/nalgebra.rs +++ b/src/nalgebra.rs @@ -1,70 +1,18 @@ -use nalgebra::{Scalar, Vector, Vector1, Vector2, Vector3, Vector4, Vector5, Vector6}; -use num_traits as nt; -use simba::scalar::{ClosedAdd, ClosedDiv, ClosedMul, ClosedSub}; -use std::ops::Mul; +use crate::impl_Interpolate; +use nalgebra::{Quaternion, Vector1, Vector2, Vector3, Vector4, Vector5, Vector6}; -use crate::interpolate::{ - cubic_bezier_def, cubic_hermite_def, quadratic_bezier_def, Additive, Interpolate, Linear, One, -}; +impl_Interpolate!(f32, Vector1, std::f32::consts::PI); +impl_Interpolate!(f32, Vector2, std::f32::consts::PI); +impl_Interpolate!(f32, Vector3, std::f32::consts::PI); +impl_Interpolate!(f32, Vector4, std::f32::consts::PI); +impl_Interpolate!(f32, Vector5, std::f32::consts::PI); +impl_Interpolate!(f32, Vector6, std::f32::consts::PI); +impl_Interpolate!(f32, Quaternion, std::f32::consts::PI); -macro_rules! impl_interpolate_vector { - ($($t:tt)*) => { - // implement Linear - impl Linear for $($t)* - where T: Scalar + - Copy + - ClosedAdd + - ClosedSub + - ClosedMul + - ClosedDiv { - #[inline(always)] - fn outer_mul(self, t: T) -> Self { - self * t - } - - #[inline(always)] - fn outer_div(self, t: T) -> Self { - self / t - } - } - - impl Interpolate for $($t)* - where Self: Linear, - T: Additive + One + Mul, - V: nt::One + - nt::Zero + - Additive + - Scalar + - ClosedAdd + - ClosedMul + - ClosedSub + - Interpolate { - #[inline(always)] - fn lerp(a: Self, b: Self, t: T) -> Self { - Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t)) - } - - #[inline(always)] - 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) - } - - #[inline(always)] - fn quadratic_bezier(a: Self, u: Self, b: Self, t: T) -> Self { - quadratic_bezier_def(a, u, b, t) - } - - #[inline(always)] - fn cubic_bezier(a: Self, u: Self, v: Self, b: Self, t: T) -> Self { - cubic_bezier_def(a, u, v, b, t) - } - } - } -} - -impl_interpolate_vector!(Vector1); -impl_interpolate_vector!(Vector2); -impl_interpolate_vector!(Vector3); -impl_interpolate_vector!(Vector4); -impl_interpolate_vector!(Vector5); -impl_interpolate_vector!(Vector6); +impl_Interpolate!(f64, Vector1, std::f64::consts::PI); +impl_Interpolate!(f64, Vector2, std::f64::consts::PI); +impl_Interpolate!(f64, Vector3, std::f64::consts::PI); +impl_Interpolate!(f64, Vector4, std::f64::consts::PI); +impl_Interpolate!(f64, Vector5, std::f64::consts::PI); +impl_Interpolate!(f64, Vector6, std::f64::consts::PI); +impl_Interpolate!(f64, Quaternion, std::f64::consts::PI); diff --git a/src/spline.rs b/src/spline.rs index dd685b0..8090008 100644 --- a/src/spline.rs +++ b/src/spline.rs @@ -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). /// @@ -102,40 +100,38 @@ impl Spline { /// sampling impossible. For instance, [`Interpolation::CatmullRom`] requires *four* keys. If /// you’re near the beginning of the spline or its end, ensure you have enough keys around to make /// the sampling. - pub fn sample_with_key(&self, t: T) -> Option<(V, &Key, Option<&Key>)> + pub fn sample_with_key(&self, t: T) -> Option> where - T: Additive + One + Trigo + Mul + Div + PartialOrd, - V: Additive + Interpolate, + T: Interpolator, + V: Interpolate, { let keys = &self.0; let i = search_lower_cp(keys, t)?; let cp0 = &keys[i]; - match cp0.interpolation { + 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, cp0, Some(cp1))) + 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, cp0, Some(cp1))) + 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, cp0, Some(cp1))) + Some(value) } Interpolation::CatmullRom => { @@ -147,51 +143,47 @@ impl Spline { 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, cp0, Some(cp1))) + Some(value) } } 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, cp0, Some(cp1))) + Some(value) } + }; - Interpolation::__NonExhaustive => unreachable!(), - } + value.map(|value| SampledWithKey { value, key: i }) } /// Sample a spline at a given time. /// pub fn sample(&self, t: T) -> Option where - T: Additive + One + Trigo + Mul + Div + PartialOrd, - V: Additive + Interpolate, + T: Interpolator, + V: Interpolate, { - self.sample_with_key(t).map(|(v, _, _)| v) + self.sample_with_key(t).map(|sampled| sampled.value) } /// Sample a spline at a given time with clamping, returning the interpolated value along with its @@ -205,10 +197,10 @@ impl Spline { /// # Error /// /// This function returns [`None`] if you have no key. - pub fn clamped_sample_with_key(&self, t: T) -> Option<(V, &Key, Option<&Key>)> + pub fn clamped_sample_with_key(&self, t: T) -> Option> where - T: Additive + One + Trigo + Mul + Div + PartialOrd, - V: Additive + Interpolate, + T: Interpolator, + V: Interpolate, { if self.0.is_empty() { return None; @@ -216,18 +208,22 @@ impl Spline { self.sample_with_key(t).or_else(move || { let first = self.0.first().unwrap(); + if t <= first.t { - let second = if self.0.len() >= 2 { - Some(&self.0[1]) - } else { - None + let sampled = SampledWithKey { + value: first.value, + key: 0, }; - Some((first.value, &first, second)) + Some(sampled) } else { let last = self.0.last().unwrap(); if t >= last.t { - Some((last.value, &last, None)) + let sampled = SampledWithKey { + value: last.value, + key: self.0.len() - 1, + }; + Some(sampled) } else { None } @@ -238,10 +234,10 @@ impl Spline { /// Sample a spline at a given time with clamping. pub fn clamped_sample(&self, t: T) -> Option where - T: Additive + One + Trigo + Mul + Div + PartialOrd, - V: Additive + Interpolate, + T: Interpolator, + V: Interpolate, { - self.clamped_sample_with_key(t).map(|(v, _, _)| v) + self.clamped_sample_with_key(t).map(|sampled| sampled.value) } /// Add a key into the spline. @@ -295,11 +291,22 @@ impl Spline { } } +/// A sampled value along with its key index. +#[derive(Clone, Debug, Eq, Hash, PartialEq)] +pub struct SampledWithKey { + /// Sampled value. + pub value: V, + + /// Key index. + pub key: usize, +} + /// A mutable [`Key`]. /// /// Mutable keys allow to edit the carried values and the interpolation mode but not the actual /// interpolator value as it would invalidate the internal structure of the [`Spline`]. If you /// want to achieve this, you’re advised to use [`Spline::replace`]. +#[derive(Debug)] pub struct KeyMut<'a, T, V> { /// Carried value. pub value: &'a mut V, @@ -307,16 +314,6 @@ pub struct KeyMut<'a, T, V> { pub interpolation: &'a mut Interpolation, } -// Normalize a time ([0;1]) given two control points. -#[inline(always)] -pub(crate) fn normalize_time(t: T, cp: &Key, cp1: &Key) -> T -where - T: Additive + Div + 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(cps: &[Key], t: T) -> Option where diff --git a/tests/cgmath.rs b/tests/cgmath.rs new file mode 100644 index 0000000..6d334f6 --- /dev/null +++ b/tests/cgmath.rs @@ -0,0 +1,43 @@ +#![cfg(feature = "cgmath")] + +use cgmath as cg; +use splines::{Interpolation, Key, Spline}; + +#[test] +fn cgmath_vector_interpolation() { + use splines::Interpolate; + + let start = cg::Vector2::new(0.0, 0.0); + let mid = cg::Vector2::new(0.5, 0.5); + let end = cg::Vector2::new(1.0, 1.0); + + assert_eq!(Interpolate::lerp(0., start, end), start); + assert_eq!(Interpolate::lerp(1., start, end), end); + assert_eq!(Interpolate::lerp(0.5, start, end), mid); +} + +#[test] +fn stroke_bezier_straight() { + use float_cmp::approx_eq; + + let keys = vec![ + Key::new( + 0.0, + cg::Vector2::new(0., 1.), + Interpolation::StrokeBezier(cg::Vector2::new(0., 1.), cg::Vector2::new(0., 1.)), + ), + Key::new( + 5.0, + cg::Vector2::new(5., 1.), + Interpolation::StrokeBezier(cg::Vector2::new(5., 1.), cg::Vector2::new(5., 1.)), + ), + ]; + let spline = Spline::from_vec(keys); + + assert!(approx_eq!(f32, spline.clamped_sample(0.0).unwrap().y, 1.)); + assert!(approx_eq!(f32, spline.clamped_sample(1.0).unwrap().y, 1.)); + assert!(approx_eq!(f32, spline.clamped_sample(2.0).unwrap().y, 1.)); + assert!(approx_eq!(f32, spline.clamped_sample(3.0).unwrap().y, 1.)); + assert!(approx_eq!(f32, spline.clamped_sample(4.0).unwrap().y, 1.)); + assert!(approx_eq!(f32, spline.clamped_sample(5.0).unwrap().y, 1.)); +} diff --git a/tests/mod.rs b/tests/integ.rs similarity index 76% rename from tests/mod.rs rename to tests/integ.rs index 4ff6aae..7ef2fd6 100644 --- a/tests/mod.rs +++ b/tests/integ.rs @@ -1,9 +1,4 @@ -use splines::{Interpolation, Key, Spline}; - -#[cfg(feature = "cgmath")] -use cgmath as cg; -#[cfg(feature = "nalgebra")] -use nalgebra as na; +use splines::{spline::SampledWithKey, Interpolation, Key, Spline}; #[test] fn step_interpolation_f32() { @@ -18,8 +13,14 @@ fn step_interpolation_f32() { assert_eq!(spline.sample(0.9), Some(10.)); assert_eq!(spline.sample(1.), None); assert_eq!(spline.clamped_sample(1.), Some(10.)); - assert_eq!(spline.sample_with_key(0.2), Some((10., &start, Some(&end)))); - assert_eq!(spline.clamped_sample_with_key(1.), Some((10., &end, None))); + assert_eq!( + spline.sample_with_key(0.2), + Some(SampledWithKey { value: 10., key: 0 }) + ); + assert_eq!( + spline.clamped_sample_with_key(1.), + Some(SampledWithKey { value: 10., key: 1 }) + ); } #[test] @@ -35,8 +36,14 @@ fn step_interpolation_f64() { assert_eq!(spline.sample(0.9), Some(10.)); assert_eq!(spline.sample(1.), None); assert_eq!(spline.clamped_sample(1.), Some(10.)); - assert_eq!(spline.sample_with_key(0.2), Some((10., &start, Some(&end)))); - assert_eq!(spline.clamped_sample_with_key(1.), Some((10., &end, None))); + assert_eq!( + spline.sample_with_key(0.2), + Some(SampledWithKey { value: 10., key: 0 }) + ); + assert_eq!( + spline.clamped_sample_with_key(1.), + Some(SampledWithKey { value: 10., key: 1 }) + ); } #[test] @@ -151,61 +158,6 @@ fn several_interpolations_several_keys() { assert_eq!(spline.clamped_sample(11.), Some(4.)); } -#[cfg(feature = "cgmath")] -#[test] -fn stroke_bezier_straight() { - use float_cmp::approx_eq; - - let keys = vec![ - Key::new( - 0.0, - cg::Vector2::new(0., 1.), - Interpolation::StrokeBezier(cg::Vector2::new(0., 1.), cg::Vector2::new(0., 1.)), - ), - Key::new( - 5.0, - cg::Vector2::new(5., 1.), - Interpolation::StrokeBezier(cg::Vector2::new(5., 1.), cg::Vector2::new(5., 1.)), - ), - ]; - let spline = Spline::from_vec(keys); - - assert!(approx_eq!(f32, spline.clamped_sample(0.0).unwrap().y, 1.)); - assert!(approx_eq!(f32, spline.clamped_sample(1.0).unwrap().y, 1.)); - assert!(approx_eq!(f32, spline.clamped_sample(2.0).unwrap().y, 1.)); - assert!(approx_eq!(f32, spline.clamped_sample(3.0).unwrap().y, 1.)); - assert!(approx_eq!(f32, spline.clamped_sample(4.0).unwrap().y, 1.)); - assert!(approx_eq!(f32, spline.clamped_sample(5.0).unwrap().y, 1.)); -} - -#[cfg(feature = "cgmath")] -#[test] -fn cgmath_vector_interpolation() { - use splines::Interpolate; - - let start = cg::Vector2::new(0.0, 0.0); - let mid = cg::Vector2::new(0.5, 0.5); - let end = cg::Vector2::new(1.0, 1.0); - - assert_eq!(Interpolate::lerp(start, end, 0.0), start); - assert_eq!(Interpolate::lerp(start, end, 1.0), end); - assert_eq!(Interpolate::lerp(start, end, 0.5), mid); -} - -#[cfg(feature = "nalgebra")] -#[test] -fn nalgebra_vector_interpolation() { - use splines::Interpolate; - - let start = na::Vector2::new(0.0, 0.0); - let mid = na::Vector2::new(0.5, 0.5); - let end = na::Vector2::new(1.0, 1.0); - - assert_eq!(Interpolate::lerp(start, end, 0.0), start); - assert_eq!(Interpolate::lerp(start, end, 1.0), end); - assert_eq!(Interpolate::lerp(start, end, 0.5), mid); -} - #[test] fn add_key_empty() { let mut spline: Spline = Spline::from_vec(vec![]); diff --git a/tests/nalgebra.rs b/tests/nalgebra.rs new file mode 100644 index 0000000..f89e7df --- /dev/null +++ b/tests/nalgebra.rs @@ -0,0 +1,16 @@ +#![cfg(feature = "nalgebra")] + +use nalgebra as na; + +#[test] +fn nalgebra_vector_interpolation() { + use splines::Interpolate; + + let start = na::Vector2::new(0.0, 0.0); + let mid = na::Vector2::new(0.5, 0.5); + let end = na::Vector2::new(1.0, 1.0); + + assert_eq!(Interpolate::lerp(0., start, end), start); + assert_eq!(Interpolate::lerp(1., start, end), end); + assert_eq!(Interpolate::lerp(0.5, start, end), mid); +}