feat!: arbitrary dimensional points (#23)

* feat: arbitrary dimensions, first draft

* refactor: math macros, loosen trait

* docs: update for new point format

* feat: tested, proper 2d point deserialization

.gitignore

@@ -1,2 +1,3 @@
 /target
 /Cargo.lock
+.vscode

README.md

@@ -10,29 +10,30 @@ A Rust port of the Javascript [simplify-js](https://github.com/mourner/simplify-
 use simplify_polyline::*;
 
 fn main() {
-    let points = &[
-        Point { x: 0.0, y: 0.0 }, Point { x: 1.0, y: 1.0 },
-        Point { x: 2.0, y: 2.0 }, Point { x: 3.0, y: 3.0 },
-        Point { x: 4.0, y: 4.0 }
+    let points = [
+        Point { vec: [0.0, 0.0] }, Point { vec: [1.0, 1.0] },
+        Point { vec: [2.0, 2.0] }, Point { vec: [3.0, 3.0] },
+        Point { vec: [4.0, 4.0] }
     ];
     // alternatively, use the point! macro
-    let points = &[
+    let points = [
         point!(0.0, 0.0), point!(1.0, 1.0), point!(2.0, 2.0),
         point!(3.0, 3.0), point!(4.0, 4.0)
     ];
     // alternatively, use the points! macro
     let points = points![(0.0, 0.0), (1.0, 1.0), (2.0, 2.0), (3.0, 3.0), (4.0, 4.0)];
 
     // low-quality simplification (fast)
-    let new_points = simplify(points, 1.0, false);
+    let new_points = simplify(&points, 1.0, false);
     // low-quality simplification (slower)
-    let new_points = simplify(points, 1.0, true);
+    let new_points = simplify(&points, 1.0, true);
 }
 ```
 
 ## Features
 
 - `serde`, optional, defaults to off. Allows serializing/deserializing points.
+  - Note, this only works for some dimensions, and some formats. Read the docs for more info.
 
 ## Performance
 
@@ -41,13 +42,13 @@ Measurements taken with an AMD Ryzen 7 5800x, in Pop!\_OS 22.04.
 | Test Case                               | simplify-polyline | simplify-js |
 | --------------------------------------- | ----------------: | ----------: |
 | 1118 Points, Low Quality, Tolerance 1   |         16.584 μs |   52.907 μs |
-| 1118 Points, High Quality, Tolerance 1  |         30.910 μs |   85.653 μs |
+| 1118 Points, High Quality, Tolerance 1  |         26.989 μs |   85.653 μs |
 | 1118 Points, Low Quality, Tolerance 5   |          3.987 μs |   12.840 μs |
-| 1118 Points, High Quality, Tolerance 5  |         23.215 μs |   57.901 μs |
+| 1118 Points, High Quality, Tolerance 5  |         19.497 μs |   57.901 μs |
 | 73752 Points, Low Quality, Tolerance 1  |         82.251 μs |  273.075 μs |
-| 73752 Points, High Quality, Tolerance 1 |       1974.004 μs | 5376.344 μs |
+| 73752 Points, High Quality, Tolerance 1 |       1933.700 μs | 5376.344 μs |
 | 73752 Points, Low Quality, Tolerance 5  |         54.150 μs |  181.554 μs |
-| 73752 Points, High Quality, Tolerance 5 |       1460.742 μs | 3921.569 μs |
+| 73752 Points, High Quality, Tolerance 5 |       1458.900 μs | 3921.569 μs |
 
 ## Contributing
 

benches/bench.rs

@@ -5,57 +5,65 @@ use simplify_polyline::{simplify, Point};
 pub const BENCH_FIXTURE_1118: &str = include_str!("../fixtures/bench-1118.json");
 pub const BENCH_FIXTURE_73752: &str = include_str!("../fixtures/bench-73752.json");
 
+fn fixture_1118() -> Vec<Point<2, f64>> {
+    serde_json::from_str::<Vec<Point<2, f64>>>(BENCH_FIXTURE_1118).unwrap()
+}
+
+fn fixture_73752() -> Vec<Point<2, f64>> {
+    serde_json::from_str::<Vec<Point<2, f64>>>(BENCH_FIXTURE_73752).unwrap()
+}
+
 fn simplify_hq_1118_pts(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_1118).unwrap();
+    let points = fixture_1118();
     c.bench_function("simplify_hq_1118_pts", |b| {
         b.iter(|| simplify(&points, 1.0, true))
     });
 }
 
 fn simplify_lq_1118_pts(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_1118).unwrap();
+    let points = fixture_1118();
     c.bench_function("simplify_lq_1118_pts", |b| {
         b.iter(|| simplify(&points, 1.0, false))
     });
 }
 
 fn simplify_hq_1118_pts_tol5(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_1118).unwrap();
+    let points = fixture_1118();
     c.bench_function("simplify_hq_1118_pts_tol5", |b| {
         b.iter(|| simplify(&points, 5.0, true))
     });
 }
 
 fn simplify_lq_1118_pts_tol5(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_1118).unwrap();
+    let points = fixture_1118();
     c.bench_function("simplify_lq_1118_pts_tol5", |b| {
         b.iter(|| simplify(&points, 5.0, false))
     });
 }
 
 fn simplify_hq_73752_pts(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_73752).unwrap();
+    let points = fixture_73752();
     c.bench_function("simplify_hq_73752_pts", |b| {
         b.iter(|| simplify(&points, 1.0, true))
     });
 }
 
 fn simplify_lq_73752_pts(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_73752).unwrap();
+    let points = fixture_73752();
     c.bench_function("simplify_lq_73752_pts", |b| {
         b.iter(|| simplify(&points, 1.0, false))
     });
 }
 
 fn simplify_hq_73752_pts_tol5(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_73752).unwrap();
+    let points = fixture_73752();
     c.bench_function("simplify_hq_73752_pts_tol5", |b| {
         b.iter(|| simplify(&points, 5.0, true))
     });
 }
 
 fn simplify_lq_73752_pts_tol5(c: &mut Criterion) {
-    let points = serde_json::from_str::<Vec<Point<f64>>>(BENCH_FIXTURE_73752).unwrap();
+    let points = fixture_73752();
     c.bench_function("simplify_lq_73752_pts_tol5", |b| {
         b.iter(|| simplify(&points, 5.0, false))
     });

src/lib.rs

@@ -3,98 +3,46 @@
 
 pub use traits::ExtendedNumOps;
 
+/// stub
 #[cfg(feature = "serde")]
-use serde::{Deserialize, Serialize};
+pub mod serde;
 
+mod point;
 mod traits;
 
-/// A two-diemensional point, where the value of each coordinate must implement the
-/// [ExtendedNumOps] trait.
-///
-/// Example:
-/// ```
-/// use simplify_polyline::*;
-///
-/// let point = Point { x: 1.0, y: 1.0 };
-/// ```
-#[derive(Clone, Copy, PartialEq, Eq, Debug)]
-#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
-pub struct Point<T: ExtendedNumOps> {
-    /// The x coordinate value.
-    pub x: T,
-    /// The y coordinate value.
-    pub y: T,
-}
+pub use point::Point;
 
-/// Creates a [Point] struct, used for input and output for [simplify]. A type should be specified
-/// as the first argument that implements the [ExtendedNumOps] trait.
-///
-/// Example
-/// ```
-/// use simplify_polyline::*;
-///
-/// let point = point!(1.0, 1.0);
-/// ```
-#[macro_export]
-macro_rules! point {
-    ($x:expr,$y:expr) => {
-        Point { x: $x, y: $y }
-    };
-}
+fn get_sq_seg_dist<const D: usize, T: ExtendedNumOps>(
+    pt: &Point<D, T>,
+    start: &Point<D, T>,
+    end: &Point<D, T>,
+) -> T {
+    let mut intersection = *start;
+    let difference = end - start;
 
-/// Creates a &[[Point]] array, used for  used for input and output for [simplify]. A type should
-/// be specified as the first argument that implements the [ExtendedNumOps] trait. Point values
-/// should be specified as length-2 tuples, where each value matches the input type, in (x, y)
-/// order.
-///
-/// Example
-/// ```
-/// use simplify_polyline::*;
-///
-/// let points = points![(1.0, 1.0), (2.0, 2.0), (3.0, 3.0)];
-/// ```
-#[macro_export]
-macro_rules! points {
-    ($(($x:expr,$y:expr)),*) => {
-        &[$(Point { x: $x, y: $y }),*]
-    };
-}
-
-fn get_sq_dist<T: ExtendedNumOps>(p1: &Point<T>, p2: &Point<T>) -> T {
-    let dx = p2.x - p1.x;
-    let dy = p2.y - p1.y;
-
-    dx * dx + dy * dy
-}
-
-fn get_sq_seg_dist<T: ExtendedNumOps>(pt: &Point<T>, start: &Point<T>, end: &Point<T>) -> T {
-    let (mut x, mut y, mut dx, mut dy) = (start.x, start.y, end.x - start.x, end.y - start.y);
-
-    if !dx.is_zero() || !dy.is_zero() {
-        let t = ((pt.x - x) * dx + (pt.y - y) * dy) / (dx * dx + dy * dy);
+    if !difference.is_origin() {
+        let t = ((pt - start) * difference).value_sum() / difference.sq_dist_origin();
         if t > T::one() {
-            x = end.x;
-            y = end.y;
+            intersection = *end;
         } else if t > T::zero() {
-            x = x + (dx * t);
-            y = y + (dy * t);
+            intersection = intersection + (difference * t)
         }
     }
 
-    dx = pt.x - x;
-    dy = pt.y - y;
-
-    dx * dx + dy * dy
+    (pt - intersection).sq_dist_origin()
 }
 
-fn simplify_radial_dist<T: ExtendedNumOps>(points: &[Point<T>], tolerance: T) -> Vec<Point<T>> {
+fn simplify_radial_dist<const D: usize, T: ExtendedNumOps>(
+    points: &[Point<D, T>],
+    tolerance: T,
+) -> Vec<Point<D, T>> {
     let mut prev_point = points[0];
     let mut new_points = vec![prev_point];
     let mut point = prev_point;
 
     for pt in points.iter().skip(1) {
         point = *pt;
-        if get_sq_dist(pt, &prev_point) > tolerance {
+        if pt.sq_dist(&prev_point) > tolerance {
             new_points.push(*pt);
             prev_point = *pt;
         }
@@ -107,12 +55,12 @@ fn simplify_radial_dist<T: ExtendedNumOps>(points: &[Point<T>], tolerance: T) ->
     new_points
 }
 
-fn simplify_dp_step<T: ExtendedNumOps>(
-    points: &[Point<T>],
+fn simplify_dp_step<const D: usize, T: ExtendedNumOps>(
+    points: &[Point<D, T>],
     first: usize,
     last: usize,
     tolerance: T,
-    simplified: &mut Vec<Point<T>>,
+    simplified: &mut Vec<Point<D, T>>,
 ) {
     let mut max_sq_dist = tolerance;
     let mut max_index = 0;
@@ -136,7 +84,10 @@ fn simplify_dp_step<T: ExtendedNumOps>(
     }
 }
 
-fn simplify_douglas_peucker<T: ExtendedNumOps>(points: &[Point<T>], tolerance: T) -> Vec<Point<T>> {
+fn simplify_douglas_peucker<const D: usize, T: ExtendedNumOps>(
+    points: &[Point<D, T>],
+    tolerance: T,
+) -> Vec<Point<D, T>> {
     let mut simplified = vec![points[0]];
     simplify_dp_step(points, 0, points.len() - 1, tolerance, &mut simplified);
     simplified.push(points[points.len() - 1]);
@@ -156,18 +107,16 @@ fn simplify_douglas_peucker<T: ExtendedNumOps>(points: &[Point<T>], tolerance: T
 ///     algorithm.
 ///   - `false`: the list of points are first filtered using a simple radial distance algorithm,
 ///     and then passed to the the Douglas-Peucker algorithm for final simplification.
-pub fn simplify<T: ExtendedNumOps>(
-    points: &[Point<T>],
-    tolerance: f64,
+pub fn simplify<const D: usize, T: ExtendedNumOps>(
+    points: &[Point<D, T>],
+    tolerance: T,
     high_quality: bool,
-) -> Vec<Point<T>> {
+) -> Vec<Point<D, T>> {
     if points.len() <= 2 {
         return points.to_vec();
     }
 
-    let tolerance_t = T::from_f64(tolerance).unwrap_or_else(T::one);
-
-    let tolerance_sq = tolerance_t * tolerance_t;
+    let tolerance_sq = tolerance * tolerance;
     let intermediate = if high_quality {
         points.to_vec()
     } else {