Crate uniform_cubic_splines

Source

Expand description

Uniform cubic spline interpolation & inversion.

This crate supports the following types of splines:

The crate uses generics to allow interpolation of any type for which certain traits are defined.

I.e. you can use this crate to interpolate splines in 1D, 2D, 3D, etc.

§Version 0.4 Changes

Trait-based architecture: New Spline trait enables specialized implementations.
Error handling: Functions return Result<T, SplineError> instead of panicking.
Clone-based design: Uses Clone instead of Copy to support more types like nalgebra::Vector3.
Extensibility: External crates can implement Spline for their own types.

§Example

Using a combination of spline_inverse() and spline() it is possible to compute a full spline-with-non-uniform-abscissæ:

use uniform_cubic_splines::prelude::*;

// We want to evaluate the spline at knot value 0.3.
let x = 0.3;

// The first and last points are never interpolated.
let knot_spacing = [0.0, 0.0, 0.1, 0.3, 1.0, 1.0];
let knots = [0.0, 0.0, 1.3, 4.2, 3.2, 3.2];

let v = spline_inverse::<CatmullRom, _>(x, &knot_spacing).unwrap();
let y = spline::<CatmullRom, _, _>(v, &knots).unwrap();

assert!(y - 4.2 < 1e-6);

§Background

The code was originally a Rust port of the resp. implementations found in the Open Shading Language C++ source. However, it has since diverged significantly with extensive optimizations:

Binary search optimization: spline_inverse uses binary search for splines with >12 segments, achieving O(log n) complexity instead of O(n)
Improved range detection: Evaluates actual spline values at segment boundaries rather than just checking control points
Adaptive root-finding: Illinois-modified Regula Falsi with automatic bisection fallback

If you come from a background of computer graphics/shading languages used in offline rendering this crate should feel familiar while providing better performance.

§`no-std`

The crate does not depend on the standard library (i.e. is marked no_std).

§Cargo Features

monotonic_check (enabled by default) — The spline_inverse()/spline_inverse_with() code will check if the knot vector is monotonic. Disabling improves performance by ~5-10% but requires monotonic input.
nightly_f16 — Enable f16 support on nightly Rust. Requires patched num-traits with nightly_f16 feature.
nightly_f128 — Enable f128 support on nightly Rust. Requires patched num-traits with nightly_f128 feature.

Re-exports§

pub use basis::*;

Modules§

basis: Spline basis types.
prelude: Convenience re-exports.

Structs§

SplineInverseOptions: Options for spline_inverse_with() function.

Enums§

SplineError: Errors that can occur during spline operations.

Traits§

Spline: Trait for types that can be interpolated using splines.

Functions§

is_len_okDeprecated: Returns true if a knots slice you want to feed into spline() has the correct length for the choosen Basis.
spline: As x varies from 0 to 1, this function returns the value of a cubic interpolation of uniformly spaced knots.
spline_inverse: Computes the inverse of the spline() function.
spline_inverse_segment: Computes the inverse of a single spline segment.
spline_inverse_segment_with: Computes the inverse of a single spline segment with custom options.
spline_inverse_with: Computes the inverse of the spline() function with control over iterations & precision via resp. SplineInverseOptions.
spline_segment: Evaluates a spline for a single segment defined by 4 control points. This is the performance-critical inner loop of the spline function.

Type Aliases§

SplineResult: Result type for spline operations.