0.2.3.

Feature-gated with impl-nalgebra.

.gitignore

@@ -1,3 +1,3 @@
-/target
+**/target
 **/*.rs.bk
 Cargo.lock

.travis.yml

@@ -12,6 +12,13 @@ os:
 script:
   - rustc --version
   - cargo --version
+  - echo "Testing default crate configuration"
   - cargo build --verbose
-  - cargo test --lib --verbose
+  - cargo test --verbose
   - cd examples && cargo check --verbose
+  - echo "Testing feature serialization"
+  - cargo build --verbose --features serialization
+  - cargo test --verbose --features serialization
+  - echo "Testing without std"
+  - cargo build --verbose --no-default-features
+  - cargo test --verbose --no-default-features

CHANGELOG.md

@@ -0,0 +1,43 @@
+## 0.2.3
+
+> Sat 13th October 2018
+
+  - Add the `"impl-nalgebra"` feature gate. It gives access to some implementors for the `nalgebra`
+    crate.
+  - Enhance the documentation.
+
+## 0.2.2
+
+> Sun 30th September 2018
+
+  - Bump version numbers (`splines-0.2`) in examples.
+  - Fix several typos in the documentation.
+
+## 0.2.1
+
+> Thu 20th September 2018
+
+  - Enhance the features documentation.
+
+# 0.2
+
+> Thu 6th September 2018
+
+  - Add the `"std"` feature gate, that can be used to compile with the standard library.
+  - Add the `"impl-cgmath"` feature gate in order to make optional, if wanted, the `cgmath`
+    dependency.
+  - Enhance the documentation.
+
+## 0.1.1
+
+> Wed 8th August 2018
+
+  - Add a feature gate, `"serialization"`, that can be used to automatically derive `Serialize` and
+    `Deserialize` from the [serde](https://crates.io/crates/serde) crate.
+  - Enhance the documentation.
+
+# 0.1
+
+> Sunday 5th August 2018
+
+  - Initial revision.

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "splines"
-version = "0.1.0"
+version = "0.2.3"
 license = "BSD-3-Clause"
 authors = ["Dimitri Sabadie <dimitri.sabadie@gmail.com>"]
 description = "Spline interpolation made easy"
@@ -17,5 +17,25 @@ is-it-maintained-issue-resolution = { repository = "phaazon/splines" }
 is-it-maintained-open-issues = { repository = "phaazon/splines" }
 maintenance = { status = "actively-developed" }
 
-[dependencies]
-cgmath = "0.16"
+[features]
+default = ["std", "impl-cgmath"]
+serialization = ["serde", "serde_derive"]
+std = []
+impl-cgmath = ["cgmath"]
+impl-nalgebra = ["nalgebra"]
+
+[dependencies.nalgebra]
+version = ">=0.14, <0.17"
+optional = true
+
+[dependencies.cgmath]
+version = "0.16"
+optional = true
+
+[dependencies.serde]
+version = "1"
+optional = true
+
+[dependencies.serde_derive]
+version = "1"
+optional = true

README.md

@@ -1,4 +1,26 @@
+# splines
+
 This crate provides [splines](https://en.wikipedia.org/wiki/Spline_(mathematics)), mathematic curves
 defined piecewise through control keys a.k.a. knots.
 
 Feel free to dig in the [online documentation](https://docs.rs/splines) for further information.
+
+## A note on features
+
+This crate has features! Here’s a comprehensive list of what you can enable:
+
+  - **Serialization / deserialization.**
+    + This feature implements both the `Serialize` and `Deserialize` traits from `serde` for all
+      types exported by this crate.
+    + Enable with the `"serialization"` feature.
+  - **[cgmath](https://crates.io/crates/cgmath) implementors.**
+    + Adds some useful implementations of `Interpolate` for some cgmath types.
+    + Enable with the `"impl-cgmath"` feature.
+  - **[nalgebra](https://crates.io/crates/nalgebra) implementors.**
+    + Adds some useful implementations of `Interpolate` for some nalgebra types.
+    + Enable with the `"impl-nalgebra"` feature.
+  - **Standard library / no standard library.**
+    + It’s possible to compile against the standard library or go on your own without it.
+    + Compiling with the standard library is enabled by default.
+    + Use `default-features = []` in your `Cargo.toml` to disable.
+    + Enable explicitly with the `"std"` feature.

examples/01-hello-world/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "hello-world"
+version = "0.2.0"
+authors = ["Dimitri Sabadie <dimitri.sabadie@gmail.com>"]
+
+[dependencies]
+splines = "0.2"

examples/01-hello-world/src/main.rs

@@ -0,0 +1,11 @@
+extern crate splines;
+
+use splines::{Interpolation, Key, Spline};
+
+fn main() {
+  let keys = vec![Key::new(0., 0., Interpolation::default()), Key::new(5., 1., Interpolation::default())];
+  let spline = Spline::from_vec(keys);
+
+  println!("value at 0: {}", spline.clamped_sample(0.));
+  println!("value at 3: {}", spline.clamped_sample(3.));
+}

examples/02-serialization/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "serialization"
+version = "0.2.0"
+authors = ["Dimitri Sabadie <dimitri.sabadie@gmail.com>"]
+
+[dependencies]
+serde_json = "1"
+
+[dependencies.splines]
+version = "0.2"
+features = ["serialization"]

examples/02-serialization/src/main.rs

@@ -0,0 +1,30 @@
+#[macro_use] extern crate serde_json;
+extern crate splines;
+
+use serde_json::{Value, from_value};
+use splines::Spline;
+
+fn main() {
+  let value = json!{
+    [
+      {
+        "t": 0,
+        "interpolation": "linear",
+        "value": 0
+      },
+      {
+        "t": 1,
+        "interpolation": { "step": 0.5 },
+        "value": 1
+      },
+      {
+        "t": 5,
+        "interpolation": "cosine",
+        "value": 10
+      },
+    ]
+  };
+
+  let spline = from_value::<Spline<f32>>(value);
+  println!("{:?}", spline);
+}

examples/Cargo.toml

@@ -0,0 +1,9 @@
+[workspace]
+
+members = [
+  "01-hello-world",
+  "02-serialization"
+]
+
+[patch.crates-io]
+splines = { path = ".." }

src/lib.rs

@@ -61,15 +61,65 @@
 //! assert_eq!(spline.clamped_sample(-0.9), 0.); // clamped to the first key
 //! assert_eq!(spline.clamped_sample(1.1), 10.); // clamped to the last key
 //! ```
+//! # Features and customization
 //!
-//! Feel free to have a look at the rest of the documentation for advanced usage.
+//! This crate was written with features baked in and hidden behind feature-gates. The idea is that
+//! the default configuration (i.e. you just add `"spline = …"` to your `Cargo.toml`) will always
+//! give you the minimal, core and raw concepts of what splines, keys / knots and interpolation
+//! modes are. However, you might want more. Instead of letting other people do the extra work to
+//! add implementations for very famous and useful traits – and do it in less efficient way, because
+//! they wouldn’t have access to the internals of this crate, it’s possible to enable features in an
+//! ad hoc way.
+//!
+//! This mechanism is not final and this is currently an experiment to see how people like it or
+//! not. It’s especially important to see how it copes with the documentation.
+//!
+//! So here’s a list of currently supported features and how to enable them:
+//!
+//!   - **Serialization / deserialization.**
+//!     + This feature implements both the `Serialize` and `Deserialize` traits from `serde` for all
+//!       types exported by this crate.
+//!     + Enable with the `"serialization"` feature.
+//!   - **[cgmath](https://crates.io/crates/cgmath) implementors.**
+//!     + Adds some useful implementations of `Interpolate` for some cgmath types.
+//!     + Enable with the `"impl-cgmath"` feature.
+//!   - **[nalgebra](https://crates.io/crates/nalgebra) implementors.**
+//!     + Adds some useful implementations of `Interpolate` for some nalgebra types.
+//!     + Enable with the `"impl-nalgebra"` feature.
+//!   - **Standard library / no standard library.**
+//!     + It’s possible to compile against the standard library or go on your own without it.
+//!     + Compiling with the standard library is enabled by default.
+//!     + Use `default-features = []` in your `Cargo.toml` to disable.
+//!     + Enable explicitly with the `"std"` feature.
 
-extern crate cgmath;
+#![cfg_attr(not(feature = "std"), no_std)]
+#![cfg_attr(not(feature = "std"), feature(alloc))]
+#![cfg_attr(not(feature = "std"), feature(core_intrinsics))]
 
-use cgmath::{InnerSpace, Quaternion, Vector2, Vector3, Vector4};
-use std::cmp::Ordering;
-use std::f32::consts;
-use std::ops::{Add, Div, Mul, Sub};
+// on no_std, we also need the alloc crate for Vec
+#[cfg(not(feature = "std"))] extern crate alloc;
+
+#[cfg(feature = "impl-cgmath")] extern crate cgmath;
+
+#[cfg(feature = "impl-nalgebra")] extern crate nalgebra;
+
+#[cfg(feature = "serialization")] extern crate serde;
+#[cfg(feature = "serialization")] #[macro_use] extern crate serde_derive;
+
+#[cfg(feature = "impl-cgmath")] use cgmath::{InnerSpace, Quaternion, Vector2, Vector3, Vector4};
+
+#[cfg(feature = "impl-nalgebra")] use nalgebra as na;
+#[cfg(feature = "impl-nalgebra")] use nalgebra::core::{DimName, DefaultAllocator, Scalar};
+#[cfg(feature = "impl-nalgebra")] use nalgebra::core::allocator::Allocator;
+
+#[cfg(feature = "std")] use std::cmp::Ordering;
+#[cfg(feature = "std")] use std::f32::consts;
+#[cfg(feature = "std")] use std::ops::{Add, Div, Mul, Sub};
+
+#[cfg(not(feature = "std"))] use alloc::vec::Vec;
+#[cfg(not(feature = "std"))] use core::cmp::Ordering;
+#[cfg(not(feature = "std"))] use core::f32::consts;
+#[cfg(not(feature = "std"))] use core::ops::{Add, Div, Mul, Sub};
 
 /// A spline control point.
 ///
@@ -77,6 +127,8 @@ use std::ops::{Add, Div, Mul, Sub};
 /// interpolation hint used to determine how to interpolate values on the segment defined by this
 /// key and the next one – if existing.
 #[derive(Copy, Clone, Debug)]
+#[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
+#[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))]
 pub struct Key<T> {
   /// Interpolation parameter at which the [`Key`] should be reached.
   pub t: f32,
@@ -99,6 +151,8 @@ impl<T> Key<T> {
 
 /// Interpolation mode.
 #[derive(Copy, Clone, Debug)]
+#[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
+#[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))]
 pub enum Interpolation {
   /// Hold a [`Key`] until the time passes the normalized step threshold, in which case the next
   /// key is used.
@@ -125,6 +179,7 @@ impl Default for Interpolation {
 
 /// Spline curve used to provide interpolation between control points (keys).
 #[derive(Debug, Clone)]
+#[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
 pub struct Spline<T>(Vec<Key<T>>);
 
 impl<T> Spline<T> {
@@ -186,7 +241,18 @@ impl<T> Spline<T> {
       Interpolation::Cosine => {
         let cp1 = &keys[i+1];
         let nt = normalize_time(t, cp0, cp1);
-        let cos_nt = (1. - f32::cos(nt * consts::PI)) * 0.5;
+        let cos_nt = {
+          #[cfg(feature = "std")]
+          {
+            (1. - f32::cos(nt * consts::PI)) * 0.5
+          }
+
+          #[cfg(not(feature = "std"))]
+          {
+            use core::intrinsics::cosf32;
+            unsafe { (1. - cosf32(nt * consts::PI)) * 0.5 }
+          }
+        };
 
         Some(Interpolate::lerp(cp0.value, cp1.value, cos_nt))
       },
@@ -288,6 +354,7 @@ impl Interpolate for f32 {
   }
 }
 
+#[cfg(feature = "impl-cgmath")]
 impl Interpolate for Vector2<f32> {
   fn lerp(a: Self, b: Self, t: f32) -> Self {
     a.lerp(b, t)
@@ -298,6 +365,7 @@ impl Interpolate for Vector2<f32> {
   }
 }
 
+#[cfg(feature = "impl-cgmath")]
 impl Interpolate for Vector3<f32> {
   fn lerp(a: Self, b: Self, t: f32) -> Self {
     a.lerp(b, t)
@@ -308,6 +376,7 @@ impl Interpolate for Vector3<f32> {
   }
 }
 
+#[cfg(feature = "impl-cgmath")]
 impl Interpolate for Vector4<f32> {
   fn lerp(a: Self, b: Self, t: f32) -> Self {
     a.lerp(b, t)
@@ -318,12 +387,69 @@ impl Interpolate for Vector4<f32> {
   }
 }
 
+#[cfg(feature = "impl-cgmath")]
 impl Interpolate for Quaternion<f32> {
   fn lerp(a: Self, b: Self, t: f32) -> Self {
     a.nlerp(b, t)
   }
 }
 
+#[cfg(feature = "impl-nalgebra")]
+impl<N, D> Interpolate for na::Point<N, D>
+where D: DimName,
+      DefaultAllocator: Allocator<N, D>,
+      <DefaultAllocator as Allocator<N, D>>::Buffer: Copy,
+      N: Scalar + Interpolate {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    // The 'coords' of a point is just a vector, so we can interpolate component-wise
+    // over these vectors.
+    let coords = na::Vector::zip_map(&a.coords, &b.coords, |c1, c2| Interpolate::lerp(c1, c2, t));
+    na::Point::from_coordinates(coords)
+  }
+}
+
+#[cfg(feature = "impl-nalgebra")]
+impl Interpolate for na::Vector1<f32> {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    na::Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t))
+  }
+}
+
+#[cfg(feature = "impl-nalgebra")]
+impl Interpolate for na::Vector2<f32> {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    na::Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t))
+  }
+}
+
+#[cfg(feature = "impl-nalgebra")]
+impl Interpolate for na::Vector3<f32> {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    na::Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t))
+  }
+}
+
+#[cfg(feature = "impl-nalgebra")]
+impl Interpolate for na::Vector4<f32> {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    na::Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t))
+  }
+}
+
+#[cfg(feature = "impl-nalgebra")]
+impl Interpolate for na::Vector5<f32> {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    na::Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t))
+  }
+}
+
+#[cfg(feature = "impl-nalgebra")]
+impl Interpolate for na::Vector6<f32> {
+  fn lerp(a: Self, b: Self, t: f32) -> Self {
+    na::Vector::zip_map(&a, &b, |c1, c2| Interpolate::lerp(c1, c2, t))
+  }
+}
+
 // Default implementation of Interpolate::cubic_hermit.
 pub(crate) fn cubic_hermite<T>(x: (T, f32), a: (T, f32), b: (T, f32), y: (T, f32), t: f32) -> T
     where T: Copy + Add<Output = T> + Sub<Output = T> + Mul<f32, Output = T> + Div<f32, Output = T> {

tests/mod.rs

@@ -1,11 +1,15 @@
 extern crate splines;
+#[cfg(feature = "impl-nalgebra")] extern crate nalgebra;
+
+#[cfg(feature = "impl-nalgebra")] use nalgebra as na;
+#[cfg(feature = "impl-nalgebra")] use splines::Interpolate;
 
 use splines::{Interpolation, Key, Spline};
 
 #[test]
 fn step_interpolation_0() {
-  let start  = Key::new(0., 0., Interpolation::Step(0.));
-  let end    = Key::new(1., 10., Interpolation::default());
+  let start = Key::new(0., 0., Interpolation::Step(0.));
+  let end = Key::new(1., 10., Interpolation::default());
   let spline = Spline::from_vec(vec![start, end]);
 
   assert_eq!(spline.sample(0.), Some(10.));
@@ -19,8 +23,8 @@ fn step_interpolation_0() {
 
 #[test]
 fn step_interpolation_0_5() {
-  let start  = Key::new(0., 0., Interpolation::Step(0.5));
-  let end    = Key::new(1., 10., Interpolation::default());
+  let start = Key::new(0., 0., Interpolation::Step(0.5));
+  let end = Key::new(1., 10., Interpolation::default());
   let spline = Spline::from_vec(vec![start, end]);
 
   assert_eq!(spline.sample(0.), Some(0.));
@@ -34,8 +38,8 @@ fn step_interpolation_0_5() {
 
 #[test]
 fn step_interpolation_0_75() {
-  let start  = Key::new(0., 0., Interpolation::Step(0.75));
-  let end    = Key::new(1., 10., Interpolation::default());
+  let start = Key::new(0., 0., Interpolation::Step(0.75));
+  let end = Key::new(1., 10., Interpolation::default());
   let spline = Spline::from_vec(vec![start, end]);
 
   assert_eq!(spline.sample(0.), Some(0.));
@@ -49,8 +53,8 @@ fn step_interpolation_0_75() {
 
 #[test]
 fn step_interpolation_1() {
-  let start  = Key::new(0., 0., Interpolation::Step(1.));
-  let end    = Key::new(1., 10., Interpolation::default());
+  let start = Key::new(0., 0., Interpolation::Step(1.));
+  let end = Key::new(1., 10., Interpolation::default());
   let spline = Spline::from_vec(vec![start, end]);
 
   assert_eq!(spline.sample(0.), Some(0.));
@@ -64,8 +68,8 @@ fn step_interpolation_1() {
 
 #[test]
 fn linear_interpolation() {
-  let start  = Key::new(0., 0., Interpolation::Linear);
-  let end    = Key::new(1., 10., Interpolation::default());
+  let start = Key::new(0., 0., Interpolation::Linear);
+  let end = Key::new(1., 10., Interpolation::default());
   let spline = Spline::from_vec(vec![start, end]);
 
   assert_eq!(spline.sample(0.), Some(0.));
@@ -80,11 +84,11 @@ fn linear_interpolation() {
 #[test]
 fn linear_interpolation_several_keys() {
   let start = Key::new(0., 0., Interpolation::Linear);
-  let k1    = Key::new(1., 5., Interpolation::Linear);
-  let k2    = Key::new(2., 0., Interpolation::Linear);
-  let k3    = Key::new(3., 1., Interpolation::Linear);
-  let k4    = Key::new(10., 2., Interpolation::Linear);
-  let end   = Key::new(11., 4., Interpolation::default());
+  let k1 = Key::new(1., 5., Interpolation::Linear);
+  let k2 = Key::new(2., 0., Interpolation::Linear);
+  let k3 = Key::new(3., 1., Interpolation::Linear);
+  let k4 = Key::new(10., 2., Interpolation::Linear);
+  let end = Key::new(11., 4., Interpolation::default());
   let spline = Spline::from_vec(vec![start, k1, k2, k3, k4, end]);
 
   assert_eq!(spline.sample(0.), Some(0.));
@@ -105,11 +109,11 @@ fn linear_interpolation_several_keys() {
 #[test]
 fn several_interpolations_several_keys() {
   let start = Key::new(0., 0., Interpolation::Step(0.5));
-  let k1    = Key::new(1., 5., Interpolation::Linear);
-  let k2    = Key::new(2., 0., Interpolation::Step(0.1));
-  let k3    = Key::new(3., 1., Interpolation::Linear);
-  let k4    = Key::new(10., 2., Interpolation::Linear);
-  let end   = Key::new(11., 4., Interpolation::default());
+  let k1 = Key::new(1., 5., Interpolation::Linear);
+  let k2 = Key::new(2., 0., Interpolation::Step(0.1));
+  let k3 = Key::new(3., 1., Interpolation::Linear);
+  let k4 = Key::new(10., 2., Interpolation::Linear);
+  let end = Key::new(11., 4., Interpolation::default());
   let spline = Spline::from_vec(vec![start, k1, k2, k3, k4, end]);
 
   assert_eq!(spline.sample(0.), Some(0.));
@@ -128,3 +132,28 @@ fn several_interpolations_several_keys() {
   assert_eq!(spline.sample(10.), Some(2.));
   assert_eq!(spline.clamped_sample(11.), 4.);
 }
+
+#[cfg(feature = "impl-nalgebra")]
+#[test]
+fn nalgebra_point_interpolation() {
+  let start = na::Point2::new(0.0, 0.0);
+  let mid = na::Point2::new(0.5, 0.5);
+  let end = na::Point2::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 = "impl-nalgebra")]
+#[test]
+fn nalgebra_vector_interpolation() {
+  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);
+}
+