{"id":21630086,"url":"https://github.com/virtualritz/uniform-cubic-splines","last_synced_at":"2025-09-04T07:16:29.830Z","repository":{"id":57671111,"uuid":"308203414","full_name":"virtualritz/uniform-cubic-splines","owner":"virtualritz","description":"Uniform cubic spline evaluation and inversion in Rust","archived":false,"fork":false,"pushed_at":"2024-10-04T14:45:22.000Z","size":139,"stargazers_count":18,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-08T20:55:38.593Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/virtualritz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-10-29T03:07:21.000Z","updated_at":"2024-11-20T12:04:34.000Z","dependencies_parsed_at":"2024-08-19T20:42:13.389Z","dependency_job_id":null,"html_url":"https://github.com/virtualritz/uniform-cubic-splines","commit_stats":{"total_commits":30,"total_committers":2,"mean_commits":15.0,"dds":0.06666666666666665,"last_synced_commit":"604448e186d4eb6583c11a0ded5dca91afbda39a"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualritz%2Funiform-cubic-splines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualritz%2Funiform-cubic-splines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualritz%2Funiform-cubic-splines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/virtualritz%2Funiform-cubic-splines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/virtualritz","download_url":"https://codeload.github.com/virtualritz/uniform-cubic-splines/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230501172,"owners_count":18236061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-25T02:09:43.891Z","updated_at":"2025-08-21T08:30:57.059Z","avatar_url":"https://github.com/virtualritz.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `uniform-cubic-splines`\n\nUniform cubic spline interpolation \u0026 inversion.\n\n[![Documentation](https://docs.rs/uniform-cubic-splines/badge.svg)](https://docs.rs/uniform-cubic-splines/)\n[![Crate](https://img.shields.io/crates/v/uniform-cubic-splines.svg)](https://crates.io/crates/uniform-cubic-splines)\n\nThis crate supports the following types of splines:\n\n- [B-spline](https://en.wikipedia.org/wiki/B-spline)\n- [Bezier](https://en.wikipedia.org/wiki/Composite_B%C3%A9zier_curve)\n- [Catmull-Rom](https://en.wikipedia.org/wiki/Cubic_Hermite_spline#Catmull%E2%80%93Rom_spline)\n- [Hermite](https://en.wikipedia.org/wiki/Cubic_Hermite_spline)\n- Linear\n- Power\n\n![Curve widget with 1D Catmull-Rom spline](spline_ui.png)\n\n_Curve widget with a 1D Catmull-Rom spline with non-uniform knot\nspacing and knot multiplicity using this crate for interpolation\n(drawn using `tiny-skia`)._\n\nThe crate uses generics to allow interpolation of any type for which\ncertain traits are defined.\n\nI.e. you can use this crate to interpolate splines in 1D, 2D, 3D, etc.\n\n```toml\n[dependencies]\nuniform-cubic-splines = { version = \"0.4\" }\n```\n\n## Example\n\nUsing a combination of `spline_inverse()` and `spline()` it is\npossible to compute a full spline-with-nonuniform-abscissæ:\n\n```rust\nuse uniform_cubic_splines::prelude::*;\n\n// We want to evaluate the spline at knot value 0.3.\nlet x = 0.3;\n\n// The first and last points are never interpolated.\nlet knot_spacing = [0.0, 0.0, 0.1, 0.3, 1.0, 1.0];\nlet knots        = [0.0, 0.0, 1.3, 4.2, 3.2, 3.2];\n\nlet v = spline_inverse::\u003cCatmullRom, _\u003e(x, \u0026knot_spacing).unwrap();\nlet y = spline::\u003cCatmullRom, _, _\u003e(v, \u0026knots).unwrap();\n\nassert!((y - 4.2).abs() \u003c 1e-6);\n```\n\n## Features\n\n- `monotonic_check` -- The\n  [`spline_inverse()`](https://docs.rs/uniform-cubic-splines/latest/uniform_cubic_splines/fn.spline_inverse.html)/[`spline_inverse_with()`](https://docs.rs/uniform-cubic-splines/latest/uniform_cubic_splines/fn.spline_inverse_with.html)\n  code will check if the knot vector is monotonic (_enabled_ by default). **Performance impact**: Disabling this feature can improve `spline_inverse` performance by ~5-10% by eliminating monotonicity validation overhead. Only disable if you can guarantee monotonic input, as non-monotonic knots will produce undefined results.\n\n## Using with Math Libraries\n\nThe `Spline` trait can be implemented for vector types from external math libraries. See the `tests/nalgebra_integration.rs` file for a complete example of implementing the trait for `nalgebra::Vector3\u003cf32\u003e` and `nalgebra::Point3\u003cf32\u003e`.\n\n```rust\nuse nalgebra::Vector3;\nuse uniform_cubic_splines::{spline, CatmullRom};\n\n// After implementing the Spline trait for Vector3\u003cf32\u003e\nlet knots = vec![\n    Vector3::new(0.0, 0.0, 0.0),\n    Vector3::new(1.0, 1.0, 1.0),\n    Vector3::new(2.0, 0.0, 2.0),\n    Vector3::new(3.0, -1.0, 3.0),\n];\n\nlet result = spline::\u003cCatmullRom, _, _\u003e(0.5, \u0026knots).unwrap();\n```\n\nNote that vector types from math libraries need custom `Spline` implementations because:\n- The interpolation parameter `x` must be a scalar (f32/f64)\n- Vectors don't implement the `Float` trait\n- Component-wise interpolation requires custom logic\n\nSee `tests/nalgebra_integration.rs` for an example of implementing the `Spline` trait for vector types using wrapper structs.\n\n## `f16` \u0026 `f128` Support\n\nThis crate supports `f16` and `f128` types on a `nightly` toolchain if you use this repository as an overlay in your `Cargo.toml`.\n\n```toml\n[patch.crates-io]\nuniform-cubic-splines = {\n    git = \"https://github.com/virtualritz/uniform-cubic-splines.git\"\n}\n```\n\n\u003e This will be supported without an overlay once [this PR on `num-traits`](https://github.com/rust-num/num-traits/pull/333) is merged and published.\n\n## Background\n\nThe code was originally a Rust port of the implementation found in the [Open\nShading Language](https://github.com/imageworks/OpenShadingLanguage)\nC++ source. However, it has since diverged significantly with numerous\noptimizations and improvements:\n\n- **Optimized `spline_inverse`**: Uses binary search for segment location\n  (O(log n) instead of O(n)) for splines with \u003e12 segments.\n- **Improved segment range detection**: Evaluates actual spline values at\n  segment boundaries instead of just checking control points.\n\nIf you come from a background of computer graphics/shading languages used in offline rendering this crate should feel like home.\n\n## Performance\n\nThe implementation has been heavily optimized beyond the original OSL C++ source.\n\n### Key Optimizations\n\n- **Binary search in `spline_inverse`**: For splines with \u003e12 segments, uses\n  binary search (O(log n)) instead of linear search (O(n)), providing up to\n  7x speedup for 1,000+ segments.\n- **Adaptive root-finding**: Illinois modification of Regula Falsi with\n  automatic fallback to bisection for robust convergence.\n- **Optimized polynomial evaluation**: Uses Horner's method for efficient\n  cubic polynomial evaluation.\n\n### Architecture Changes in v0.5\n\n- **Trait-based design**: The new [`Spline`](https://docs.rs/uniform-cubic-splines/latest/uniform_cubic_splines/trait.Spline.html) trait allows specialized implementations for different types.\n- **Error handling**: Functions now return `Result\u003cT, SplineError\u003e` instead of panicking on invalid inputs.\n\n### Benchmarks\n\nPerformance for scalar types (`f32` and `f64`):\n\n| **Points** | `f32 spline()` | `f32 spline_inverse()` | `f64 spline()` | `f64 spline_inverse()` |\n| ---------- | -------------- | ---------------------- | -------------- | ---------------------- |\n| 10         | 2.4 ns         | 19 ns                  | 2.3 ns         | 18 ns                  |\n| 50         | 2.4 ns         | 39 ns                  | 2.4 ns         | 39 ns                  |\n| 100        | 2.4 ns         | 62 ns                  | 2.4 ns         | 72 ns                  |\n| 500        | 2.4 ns         | 265 ns                 | 2.6 ns         | 263 ns                 |\n\n_Benchmarks taken on Ubuntu with `rustc 1.83.0-nightly` on an AMD Ryzen 7 6800H laptop._\n\nThe trait-based architecture allows external math libraries to provide their own optimized implementations for vector types.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtualritz%2Funiform-cubic-splines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvirtualritz%2Funiform-cubic-splines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvirtualritz%2Funiform-cubic-splines/lists"}