feat: make FrechetDistance generic over Metric Spaces

geo/CHANGES.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+- BREAKING: `FrechetDistance` is now defined on the metric space, rather than a method on a Linestring.
+  - <https://github.com/georust/geo/pull/1274>
+  ```rust
+  // before (implicitly Euclidean)
+  line_string_1.frechet_distance(&line_string_2);
+
+  // after
+  Euclidean.frechet_distance(&line_string_1, &line_string_2);
+  Haversine.frechet_distance(&line_string_1, &line_string_2);
+  ```
 - BREAKING: `Densify` and `Length` are now defined on the metric space, rather than a generic method on the geometry.
   - <https://github.com/georust/geo/pull/1298>
   ```rust

geo/benches/frechet_distance.rs

@@ -1,5 +1,5 @@
 use criterion::{criterion_group, criterion_main};
-use geo::frechet_distance::FrechetDistance;
+use geo::{line_measures::FrechetDistance, Euclidean};
 
 fn criterion_benchmark(c: &mut criterion::Criterion) {
     c.bench_function("frechet distance f32", |bencher| {
@@ -8,7 +8,8 @@ fn criterion_benchmark(c: &mut criterion::Criterion) {
 
         bencher.iter(|| {
             criterion::black_box(
-                criterion::black_box(&ls_a).frechet_distance(criterion::black_box(&ls_b)),
+                Euclidean
+                    .frechet_distance(criterion::black_box(&ls_a), criterion::black_box(&ls_b)),
             );
         });
     });
@@ -19,7 +20,8 @@ fn criterion_benchmark(c: &mut criterion::Criterion) {
 
         bencher.iter(|| {
             criterion::black_box(
-                criterion::black_box(&ls_a).frechet_distance(criterion::black_box(&ls_b)),
+                Euclidean
+                    .frechet_distance(criterion::black_box(&ls_a), criterion::black_box(&ls_b)),
             );
         });
     });

geo/src/algorithm/frechet_distance.rs

@@ -1,8 +1,11 @@
-use crate::coords_iter::CoordsIter;
-use crate::line_measures::{Distance, Euclidean};
+use crate::line_measures::Euclidean;
 use crate::{GeoFloat, LineString};
 use num_traits::FromPrimitive;
 
+#[deprecated(
+    since = "0.30.0",
+    note = "Please use the `Euclidean.frechet_distance` method from the `geo::line_measures::FrechetDistance` trait instead"
+)]
 /// Determine the similarity between two `LineStrings` using the [Frechet distance].
 ///
 /// Based on [Computing Discrete Frechet Distance] by T. Eiter and H. Mannila.
@@ -41,117 +44,12 @@ pub trait FrechetDistance<T, Rhs = Self> {
     fn frechet_distance(&self, rhs: &Rhs) -> T;
 }
 
+#[allow(deprecated)]
 impl<T> FrechetDistance<T, LineString<T>> for LineString<T>
 where
     T: GeoFloat + FromPrimitive,
 {
     fn frechet_distance(&self, ls: &LineString<T>) -> T {
-        if self.coords_count() != 0 && ls.coords_count() != 0 {
-            Data {
-                cache: vec![T::zero(); self.coords_count() * ls.coords_count()],
-                ls_a: self,
-                ls_b: ls,
-            }
-            .compute_linear()
-        } else {
-            T::zero()
-        }
-    }
-}
-
-struct Data<'a, T>
-where
-    T: GeoFloat + FromPrimitive,
-{
-    cache: Vec<T>,
-    ls_a: &'a LineString<T>,
-    ls_b: &'a LineString<T>,
-}
-
-impl<T> Data<'_, T>
-where
-    T: GeoFloat + FromPrimitive,
-{
-    /// [Reference implementation]: https://github.com/joaofig/discrete-frechet/tree/master
-    fn compute_linear(&mut self) -> T {
-        let columns_count = self.ls_b.coords_count();
-
-        for (i, &a) in self.ls_a.coords().enumerate() {
-            for (j, &b) in self.ls_b.coords().enumerate() {
-                let dist = Euclidean.distance(a, b);
-
-                self.cache[i * columns_count + j] = match (i, j) {
-                    (0, 0) => dist,
-                    (_, 0) => self.cache[(i - 1) * columns_count].max(dist),
-                    (0, _) => self.cache[j - 1].max(dist),
-                    (_, _) => self.cache[(i - 1) * columns_count + j]
-                        .min(self.cache[(i - 1) * columns_count + j - 1])
-                        .min(self.cache[i * columns_count + j - 1])
-                        .max(dist),
-                };
-            }
-        }
-
-        self.cache[self.cache.len() - 1]
-    }
-}
-
-#[cfg(test)]
-mod test {
-    use super::*;
-
-    #[test]
-    fn test_single_point_in_linestring() {
-        let ls_a = LineString::from(vec![(1., 1.)]);
-        let ls_b = LineString::from(vec![(0., 2.)]);
-        assert_relative_eq!(
-            Euclidean.distance(ls_a.0[0], ls_b.0[0]),
-            ls_a.frechet_distance(&ls_b)
-        );
-    }
-
-    #[test]
-    fn test_identical_linestrings() {
-        let ls_a = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
-        let ls_b = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
-        assert_relative_eq!(0., ls_a.frechet_distance(&ls_b));
-    }
-
-    #[test]
-    fn different_dimensions_linestrings() {
-        let ls_a = LineString::from(vec![(1., 1.)]);
-        let ls_b = LineString::from(vec![(2., 2.), (0., 1.)]);
-        assert_relative_eq!(2f64.sqrt(), ls_a.frechet_distance(&ls_b));
-    }
-
-    #[test]
-    fn test_frechet_1() {
-        let ls_a = LineString::from(vec![(1., 1.), (2., 1.)]);
-        let ls_b = LineString::from(vec![(2., 2.), (2., 3.)]);
-        assert_relative_eq!(2., ls_a.frechet_distance(&ls_b));
-    }
-
-    #[test]
-    fn test_frechet_2() {
-        let ls_a = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
-        let ls_b = LineString::from(vec![(2., 2.), (0., 1.), (2., 4.)]);
-        assert_relative_eq!(2., ls_a.frechet_distance(&ls_b));
-    }
-
-    #[test] // comparing long linestrings should not panic or abort due to stack overflow
-    fn test_frechet_long_linestrings() {
-        let ls: LineString = {
-            let delta = 0.01;
-
-            let mut ls = vec![(0.0, 0.0); 10_000];
-            for i in 1..ls.len() {
-                let (lat, lon) = ls[i - 1];
-                ls[i] = (lat - delta, lon + delta);
-            }
-
-            ls.into()
-        };
-
-        assert_relative_eq!(ls.frechet_distance(&ls.clone()), 0.0);
+        super::line_measures::FrechetDistance::frechet_distance(&Euclidean, self, ls)
     }
 }

geo/src/algorithm/line_measures/frechet_distance.rs

@@ -0,0 +1,208 @@
+use geo_types::{CoordFloat, LineString, Point};
+
+use crate::CoordsIter;
+
+use super::Distance;
+
+/// Determine the similarity between two `LineStrings` using the [Frechet distance].
+///
+/// Based on [Computing Discrete Frechet Distance] by T. Eiter and H. Mannila.
+///
+/// [Frechet distance]: https://en.wikipedia.org/wiki/Fr%C3%A9chet_distance
+/// [Computing Discrete Frechet Distance]: http://www.kr.tuwien.ac.at/staff/eiter/et-archive/cdtr9464.pdf
+pub trait FrechetDistance<F: CoordFloat>: Distance<F, Point<F>, Point<F>> {
+    /// Returns the Fréchet distance between two LineStrings.
+    ///
+    /// See [specific implementations](#implementors) for details.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use geo::line_measures::FrechetDistance;
+    /// use geo::{Haversine, Euclidean, LineString, HaversineMeasure};
+    /// use geo::line_string;
+    ///
+    /// let line_1 = line_string![
+    ///     (x: 0., y: 0.),
+    ///     (x: 1., y: 1.)
+    /// ];
+    /// let line_2 = line_string![
+    ///     (x: 0., y: 1.),
+    ///     (x: 1., y: 2.)
+    /// ];
+    ///
+    /// // Using Euclidean distance
+    /// let euclidean_distance = Euclidean.frechet_distance(&line_1, &line_2);
+    ///
+    /// // Using Haversine distance for geographic coordinates
+    /// let haversine_distance = Haversine.frechet_distance(&line_1, &line_2);
+    ///
+    /// // Using parameterized Haversine for different planetary bodies
+    /// let mars_measure = HaversineMeasure::new(3389.5); // Mars radius in km
+    /// let mars_distance = mars_measure.frechet_distance(&line_1, &line_2);
+    /// ```
+    ///
+    /// [Frechet distance]: https://en.wikipedia.org/wiki/Fr%C3%A9chet_distance
+    fn frechet_distance(&self, ls_1: &LineString<F>, ls_2: &LineString<F>) -> F;
+}
+
+impl<F, MetricSpace> FrechetDistance<F> for MetricSpace
+where
+    F: CoordFloat,
+    MetricSpace: Distance<F, Point<F>, Point<F>>,
+{
+    fn frechet_distance(&self, ls_1: &LineString<F>, ls_2: &LineString<F>) -> F {
+        if ls_1.coords_count() != 0 && ls_2.coords_count() != 0 {
+            Data {
+                cache: vec![F::zero(); ls_1.coords_count() * ls_2.coords_count()],
+                ls_a: ls_1,
+                ls_b: ls_2,
+            }
+            .compute_linear(self)
+        } else {
+            F::zero()
+        }
+    }
+}
+
+struct Data<'a, F: CoordFloat> {
+    cache: Vec<F>,
+    ls_a: &'a LineString<F>,
+    ls_b: &'a LineString<F>,
+}
+
+impl<F: CoordFloat> Data<'_, F> {
+    /// [Reference implementation]: https://github.com/joaofig/discrete-frechet/tree/master
+    fn compute_linear(&mut self, metric_space: &impl Distance<F, Point<F>, Point<F>>) -> F {
+        let columns_count = self.ls_b.coords_count();
+
+        for (i, a) in self.ls_a.points().enumerate() {
+            for (j, b) in self.ls_b.points().enumerate() {
+                let dist = metric_space.distance(a, b);
+
+                self.cache[i * columns_count + j] = match (i, j) {
+                    (0, 0) => dist,
+                    (_, 0) => self.cache[(i - 1) * columns_count].max(dist),
+                    (0, _) => self.cache[j - 1].max(dist),
+                    (_, _) => self.cache[(i - 1) * columns_count + j]
+                        .min(self.cache[(i - 1) * columns_count + j - 1])
+                        .min(self.cache[i * columns_count + j - 1])
+                        .max(dist),
+                };
+            }
+        }
+
+        self.cache[self.cache.len() - 1]
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use crate::{Euclidean, HaversineMeasure};
+
+    use super::*;
+
+    #[test]
+    fn test_single_point_in_linestring_euclidean() {
+        let ls_a = LineString::from(vec![(1., 1.)]);
+        let ls_b = LineString::from(vec![(0., 2.)]);
+        assert_relative_eq!(
+            Euclidean.distance(Point::from(ls_a.0[0]), Point::from(ls_b.0[0])),
+            Euclidean.frechet_distance(&ls_a, &ls_b)
+        );
+    }
+
+    #[test]
+    fn test_identical_linestrings_euclidean() {
+        let ls_a = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
+        let ls_b = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
+        assert_relative_eq!(0., Euclidean.frechet_distance(&ls_a, &ls_b));
+    }
+
+    #[test]
+    fn different_dimensions_linestrings_euclidean() {
+        let ls_a = LineString::from(vec![(1., 1.)]);
+        let ls_b = LineString::from(vec![(2., 2.), (0., 1.)]);
+        assert_relative_eq!(2f64.sqrt(), Euclidean.frechet_distance(&ls_a, &ls_b));
+    }
+
+    #[test]
+    fn test_frechet_1_euclidean() {
+        let ls_a = LineString::from(vec![(1., 1.), (2., 1.)]);
+        let ls_b = LineString::from(vec![(2., 2.), (2., 3.)]);
+        assert_relative_eq!(2., Euclidean.frechet_distance(&ls_a, &ls_b));
+    }
+
+    #[test]
+    fn test_frechet_2_euclidean() {
+        let ls_a = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
+        let ls_b = LineString::from(vec![(2., 2.), (0., 1.), (2., 4.)]);
+        assert_relative_eq!(2., Euclidean.frechet_distance(&ls_a, &ls_b));
+    }
+
+    #[test] // comparing long linestrings should not panic or abort due to stack overflow
+    fn test_frechet_long_linestrings_euclidean() {
+        let ls: LineString = {
+            let delta = 0.01;
+
+            let mut ls = vec![(0.0, 0.0); 10_000];
+            for i in 1..ls.len() {
+                let (lat, lon) = ls[i - 1];
+                ls[i] = (lat - delta, lon + delta);
+            }
+
+            ls.into()
+        };
+
+        assert_relative_eq!(Euclidean.frechet_distance(&ls, &ls), 0.0);
+    }
+
+    #[test]
+    fn test_single_point_in_linestring_haversine_custom() {
+        let mars_measure = HaversineMeasure::new(3389.5); // Mars radius in km
+        let ls_a = LineString::from(vec![(1., 1.)]);
+        let ls_b = LineString::from(vec![(0., 2.)]);
+        assert_relative_eq!(
+            mars_measure.distance(Point::from(ls_a.0[0]), Point::from(ls_b.0[0])),
+            mars_measure.frechet_distance(&ls_a, &ls_b)
+        );
+    }
+
+    #[test]
+    fn test_identical_linestrings_haversine_custom() {
+        let mars_measure = HaversineMeasure::new(3389.5);
+        let ls_a = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
+        let ls_b = LineString::from(vec![(1., 1.), (2., 1.), (2., 2.)]);
+        assert_relative_eq!(0., mars_measure.frechet_distance(&ls_a, &ls_b));
+    }
+
+    #[test]
+    fn different_dimensions_linestrings_haversine_custom() {
+        let mars_measure = HaversineMeasure::new(3389.5);
+        let ls_a = LineString::from(vec![(1., 1.)]);
+        let ls_b = LineString::from(vec![(2., 2.), (0., 1.)]);
+        let expected_distance = mars_measure.distance(Point::new(1., 1.), Point::new(2., 2.));
+        assert_relative_eq!(
+            expected_distance,
+            mars_measure.frechet_distance(&ls_a, &ls_b)
+        );
+    }
+
+    #[test]
+    fn test_frechet_long_linestrings_haversine_custom() {
+        let mars_measure = HaversineMeasure::new(3389.5);
+        let ls: LineString = {
+            let delta = 0.01;
+
+            let mut ls = vec![(0.0, 0.0); 10_000];
+            for i in 1..ls.len() {
+                let (lat, lon) = ls[i - 1];
+                ls[i] = (lat - delta, lon + delta);
+            }
+
+            ls.into()
+        };
+
+        assert_relative_eq!(mars_measure.frechet_distance(&ls, &ls), 0.0);
+    }
+}

geo/src/algorithm/line_measures/mod.rs

@@ -37,5 +37,8 @@ pub use length::{Length, LengthMeasurable};
 mod densify;
 pub use densify::{Densifiable, Densify};
 
+mod frechet_distance;
+pub use frechet_distance::FrechetDistance;
+
 pub mod metric_spaces;
 pub use metric_spaces::{Euclidean, Geodesic, GeodesicMeasure, Haversine, HaversineMeasure, Rhumb};