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

Merge pull request #63 from phaazon/refactor

Browse Source 
Refactor
This commit is contained in:
Dimitri Sabadie 2021-03-05 02:50:14 +01:00 committed by GitHub
commit b92c28cfbb
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
12 changed files with 314 additions and 636 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
CHANGELOG.md
View File

@ -2,6 +2,9 @@
<!-- vim-markdown-toc GFM -->
* [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 @@
<!-- vim-markdown-toc -->
# 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

6
Cargo.toml
View File

@ -1,6 +1,6 @@
[package]
name = "splines"
version = "3.5.4"
version = "4.0.0"
license = "BSD-3-Clause"
authors = ["Dimitri Sabadie <dimitri.sabadie@gmail.com>"]
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"

101
src/cgmath.rs
View File

@ -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<T> Linear<T> for $($t)*<T> where T: BaseNum {
#[inline(always)]
fn outer_mul(self, t: T) -> Self {
self * t
}
impl_Interpolate!(f32, Vector1<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector2<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector3<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector4<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Quaternion<f32>, std::f32::consts::PI);
#[inline(always)]
fn outer_div(self, t: T) -> Self {
self / t
}
}
impl<T> Interpolate<T> for $($t)*<T>
where Self: InnerSpace<Scalar = T>, 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<T> Linear<T> for Quaternion<T>
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<T> Interpolate<T> for Quaternion<T>
where
Self: InnerSpace<Scalar = T>,
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<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector2<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector3<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector4<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Quaternion<f64>, std::f64::consts::PI);

92
src/glam.rs
View File

@ -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<f32> 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<f32> 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<f32> 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<f32> 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);

321
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
}
/// Apply an outer division law.
fn outer_div(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
}
}
};
}
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
fn lerp(t: $t, a: Self, b: Self) -> Self {
a * (1. - t) + b * t
}
#[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
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.0 - x.0).outer_div(b.1 - x.1);
let m1 = (y.0 - a.0).outer_div(y.1 - a.1);
let m0 = (b.1 - x.1) / (b.0 - x.0);
let m1 = (y.1 - a.1) / (y.0 - a.0);
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 {
a * (1. - t) + b * t
a.1 * (two_t3 - three_t2 + 1.)
+ m0 * (t3 - t2 * two_t + t)
+ b.1 * (three_t2 - two_t3)
+ m1 * (t3 - t2)
}
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 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 quadratic_bezier(a: Self, u: Self, b: Self, t: $t) -> Self {
quadratic_bezier_def(a, u, 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(a: Self, u: Self, v: Self, b: Self, t: $t) -> Self {
cubic_bezier_def(a, u, v, b, 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);

15
src/interpolation.rs
View File

@ -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<T, V> {
/// 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<T, V> {
///
/// [`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<T, V> {
/// 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<T, V> {
///
/// Stroke Bézier interpolation is always a cubic Bézier interpolation by default.
StrokeBezier(V, V),
#[doc(hidden)]
__NonExhaustive,
}
impl<T, V> Default for Interpolation<T, V> {

12
src/key.rs
View File

@ -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<T, V> {
/// Interpolation parameter at which the [`Key`] should be reached.
pub t: T,

84
src/nalgebra.rs
View File

@ -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<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector2<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector3<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector4<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector5<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Vector6<f32>, std::f32::consts::PI);
impl_Interpolate!(f32, Quaternion<f32>, std::f32::consts::PI);
macro_rules! impl_interpolate_vector {
($($t:tt)*) => {
// implement Linear
impl<T> Linear<T> for $($t)*<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<T, V> Interpolate<T> for $($t)*<V>
where Self: Linear<T>,
T: Additive + One + Mul<T, Output = T>,
V: nt::One +
nt::Zero +
Additive +
Scalar +
ClosedAdd +
ClosedMul +
ClosedSub +
Interpolate<T> {
#[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<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector2<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector3<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector4<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector5<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Vector6<f64>, std::f64::consts::PI);
impl_Interpolate!(f64, Quaternion<f64>, std::f64::consts::PI);

125
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).
///
@ -102,40 +100,38 @@ impl<T, V> Spline<T, V> {
/// 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<T, V>, Option<&Key<T, V>>)>
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)?;
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<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, 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<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(|(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<T, V> Spline<T, V> {
/// # Error
///
/// This function returns [`None`] if you have no key.
pub fn clamped_sample_with_key(&self, t: T) -> Option<(V, &Key<T, V>, Option<&Key<T, V>>)>
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;
@ -216,18 +208,22 @@ impl<T, V> Spline<T, V> {
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<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(|(v, _, _)| v)
self.clamped_sample_with_key(t).map(|sampled| sampled.value)
}
/// Add a key into the spline.
@ -295,11 +291,22 @@ impl<T, V> Spline<T, V> {
}
}
/// A sampled value along with its key index.
#[derive(Clone, Debug, Eq, Hash, PartialEq)]
pub struct SampledWithKey<V> {
/// 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<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

43
tests/cgmath.rs Normal file
View File

@ -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.));
}

82
tests/mod.rs → tests/integ.rs
View File

@ -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<f32, f32> = Spline::from_vec(vec![]);

16
tests/nalgebra.rs Normal file
View File

@ -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);
}