add mint feature for Point trait impl for mint::Point2 and mint::Poin…

…t3 (#134)

rstar/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Unreleased
 
+## Added
+- Add optional support for the [mint](https://docs.rs/mint/0.5.9/mint/index.html) crate
+
 ## Changed
 - Fixed a stack overflow error in `DrainIterator::next`
 

rstar/Cargo.toml

@@ -20,6 +20,7 @@ heapless = "0.7.10"
 num-traits = { version = "0.2", default-features = false, features = ["libm"] }
 serde = { version = "1.0", optional = true, default-features = false, features = ["alloc", "derive"] }
 smallvec = "1.6"
+mint = { version = "0.5.9", optional = true }
 
 [features]
 default = []
@@ -30,3 +31,4 @@ rand = "0.7"
 rand_hc = "0.2"
 approx = "0.3"
 serde_json = "1.0"
+nalgebra = { version = "0.32.3", features = ["mint"] }

rstar/src/lib.rs

@@ -17,8 +17,14 @@
 //! the [primitives module](crate::primitives) may be of interest for a quick start.
 //!
 //! # (De)Serialization
-//! Enable the `serde` feature for [Serde](https://crates.io/crates/serde) support.
+//! Enable the `serde` feature for [serde](https://crates.io/crates/serde) support.
 //!
+//! # Mint compatibility with other crates
+//! Enable the `mint` feature for
+//! [`mint`](https://crates.io/crates/mint) support. See the
+//! documentation on the [mint] module for an expample of an
+//! integration with the
+//! [`nalgebra`](https://crates.io/crates/nalgebra) crate.
 #![deny(missing_docs)]
 #![forbid(unsafe_code)]
 #![cfg_attr(not(test), no_std)]
@@ -35,6 +41,9 @@ mod point;
 pub mod primitives;
 mod rtree;
 
+#[cfg(feature = "mint")]
+pub mod mint;
+
 #[cfg(test)]
 mod test_utilities;
 

rstar/src/mint.rs

@@ -0,0 +1,94 @@
+//! [`mint`](https://crates.io/crates/mint) is a library for
+//! interoperability between maths crates, for example, you may want
+//! to use [nalgebra](https://crates.io/crates/nalgebra) types for
+//! representing your points and _also_ use the same points with the
+//! `rstar` library.
+//!
+//! Here is an example of how you might do that using `mint` types for
+//! compatibility between the two libraries. Make sure to enable the
+//! `mint` features on both the `nalgebra` and the `rstar` crates for
+//! this to work. You will also need to depend on the
+//! [`mint`](https://crates.io/crates/mint) crate.
+//!
+//! ```
+//! use rstar::RTree;
+//!
+//! let point1 = nalgebra::Point2::new(0.0, 0.0);
+//! let point2 = nalgebra::Point2::new(1.0, 1.0);
+//!
+//! // First we have to convert the foreign points into the mint
+//! // compatibility types before we can store them in the rtree
+//!
+//! let mint_point1: mint::Point2<f64> = point1.into();
+//! let mint_point2: mint::Point2<f64> = point2.into();
+//!
+//! // Now we can use them with rtree structs and methods
+//! let mut rtree = RTree::new();
+//!
+//! rtree.insert(mint_point2);
+//!
+//! assert_eq!(rtree.nearest_neighbor(&mint_point1), Some(&mint_point2));
+//! ```
+
+use crate::{Point, RTreeNum};
+
+impl<T: RTreeNum> Point for mint::Point2<T> {
+    type Scalar = T;
+
+    const DIMENSIONS: usize = 2;
+
+    fn generate(mut generator: impl FnMut(usize) -> Self::Scalar) -> Self {
+        mint::Point2 {
+            x: generator(0),
+            y: generator(1),
+        }
+    }
+
+    fn nth(&self, index: usize) -> Self::Scalar {
+        match index {
+            0 => self.x,
+            1 => self.y,
+            _ => unreachable!(),
+        }
+    }
+
+    fn nth_mut(&mut self, index: usize) -> &mut Self::Scalar {
+        match index {
+            0 => &mut self.x,
+            1 => &mut self.y,
+            _ => unreachable!(),
+        }
+    }
+}
+
+impl<T: RTreeNum> Point for mint::Point3<T> {
+    type Scalar = T;
+
+    const DIMENSIONS: usize = 3;
+
+    fn generate(mut generator: impl FnMut(usize) -> Self::Scalar) -> Self {
+        mint::Point3 {
+            x: generator(0),
+            y: generator(1),
+            z: generator(2),
+        }
+    }
+
+    fn nth(&self, index: usize) -> Self::Scalar {
+        match index {
+            0 => self.x,
+            1 => self.y,
+            2 => self.z,
+            _ => unreachable!(),
+        }
+    }
+
+    fn nth_mut(&mut self, index: usize) -> &mut Self::Scalar {
+        match index {
+            0 => &mut self.x,
+            1 => &mut self.y,
+            2 => &mut self.z,
+            _ => unreachable!(),
+        }
+    }
+}

rstar/src/rtree.rs

@@ -689,8 +689,15 @@ where
     ///   [0.0, 1.0],
     ///   [1.0, 0.0],
     /// ]);
-    /// assert_eq!(tree.nearest_neighbors(&[1.0, 1.0]), &[&[0.0, 1.0], &[1.0, 0.0]]);
+    ///
+    /// // A single nearest neighbor
     /// assert_eq!(tree.nearest_neighbors(&[0.01, 0.01]), &[&[0.0, 0.0]]);
+    ///
+    /// // Two nearest neighbors
+    /// let nearest_two = tree.nearest_neighbors(&[1.0, 1.0]);
+    /// assert_eq!(nearest_two.len(), 2);
+    /// assert!(nearest_two.contains(&&[0.0, 1.0]));
+    /// assert!(nearest_two.contains(&&[1.0, 0.0]));
     /// ```
     pub fn nearest_neighbors(&self, query_point: &<T::Envelope as Envelope>::Point) -> Vec<&T> {
         nearest_neighbor::nearest_neighbors(&self.root, query_point.clone())