- Added trait ToPointCloud to make ICP easy to use with point clouds

loaded from various sources. - Added modelz integration -
`estimate_transform` has slightly changed to allow `ToPointCloud` in
parameters

Author: maccesch

.github/workflows/cd.yml

@@ -35,7 +35,7 @@ jobs:
           cargo rdme --check
 
       - name: Run tests
-        run: cargo test
+        run: cargo test --features modelz
 
       - name: Publish crate modern-icp
         uses: katyo/publish-crates@v2

.zed/settings.json

@@ -10,7 +10,7 @@
           "allTargets": true
         },
         "cargo": {
-          "features": ["rerun"],
+          "features": ["rerun", "modelz"],
           "target": "wasm32-unknown-unknown"
         }
       }

CHANGELOG.md

@@ -3,6 +3,12 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2025-07-05
+
+- Added trait `ToPointCloud` to make ICP easy to use with point clouds loaded from various sources.
+- Added modelz integration
+- `estimate_transform` has slightly changed to allow `ToPointCloud` in parameters
+
 ## [0.3.0] - 2025-07-02
 
 - Renamed `is_small_squared_distance_error` to `same_squared_distance_error`

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "modern-icp"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2024"
 authors = ["Marc-Stefan Cassola"]
 categories = ["graphics", "algorithms", "mathematics"]
@@ -15,6 +15,7 @@ repository = "https://github.com/Synphonyte/modern-icp"
 cfg-if = "1"
 kdtree = "0.7.0"
 lazy_static = { version = "1.5.0", optional = true }
+modelz = { version = "0.1.5", optional = true }
 nalgebra = "0.33.2"
 num-traits = "0.2.19"
 rerun = { version = "0.23", optional = true }
@@ -28,3 +29,4 @@ rand = "0.8.5"
 default = []
 rerun = ["dep:rerun", "dep:lazy_static", "nalgebra/convert-glam029"]
 serde = ["dep:serde", "nalgebra/serde-serialize"]
+modelz = ["dep:modelz"]

Cargo.toml

@@ -13,7 +13,7 @@ A modern modular pure Rust implementation of the Iterative Closest Point algorit
 
 ```rust
 let (alignee_transform, error_sum) = estimate_transform(
-    &alignee_cloud,
+    alignee_cloud,
     &target_cloud,
     20, // max iterations
     BidirectionalDistance::new(&target_cloud),
@@ -24,4 +24,25 @@ let (alignee_transform, error_sum) = estimate_transform(
 );
 ```
 
+### Integrations
+
+An integrations with the modelz crate is provided so you can use `Model3D` with the `estimate_transform` function.
+
+```rust
+use modelz::Model3D;
+
+if let (Ok(alignee), Ok(target)) = (Model3D::load("alignee.gltf"), Model3D::load("target.stl")) {
+    let (transform, error_sum) = estimate_transform(
+        alignee,
+        &target,
+        20, // max iterations
+        BidirectionalDistance::new(&target),
+        accept_all,
+        reject_3_sigma_dist,
+        point_to_plane_lls::estimate_isometry,
+        same_squared_distance_error(1.0),
+    );
+}
+```
+
 <!-- cargo-rdme end -->

README.md

@@ -1,7 +1,7 @@
 use crate::correspondence::{
     CorrespondenceEstimator, Correspondences, get_ordered_correspondences_and_distances_nn,
 };
-use crate::{PointCloud, PointCloudPoint, kd_tree_of_point_cloud};
+use crate::{PointCloud, PointCloudPoint, ToPointCloud, kd_tree_of_point_cloud};
 use kdtree::KdTree;
 use nalgebra::{RealField, Scalar};
 use num_traits::{Float, One, Zero};
@@ -10,44 +10,50 @@ use num_traits::{Float, One, Zero};
 /// Bidirectional Distance algorithm.
 ///
 /// See this [paper from Dong et al.](https://doi.org/10.1049/iet-cvi.2016.0058)
-pub struct BidirectionalDistance<'a, T>
+pub struct BidirectionalDistance<T>
 where
     T: Scalar + RealField + Float + One + Zero,
 {
-    target_tree: KdTree<T, usize, &'a [T]>,
+    target_tree: KdTree<T, usize, Vec<T>>,
+    target_cloud: PointCloud<T, 3>,
 }
 
-impl<'a, T> CorrespondenceEstimator<'a, T, PointCloud<T, 3>, 3> for BidirectionalDistance<'a, T>
+impl<'a, T, PC> CorrespondenceEstimator<'a, T, PC, 3> for BidirectionalDistance<T>
 where
     T: Scalar + RealField + Float + One + Zero,
+    PC: ToPointCloud<T, 3>,
 {
-    fn new(target: &'a PointCloud<T, 3>) -> Self {
+    fn new(target: &'a PC) -> Self {
+        let target_cloud = target.to_point_cloud();
+
         BidirectionalDistance {
-            target_tree: kd_tree_of_point_cloud(target),
+            target_tree: kd_tree_of_point_cloud(&target_cloud),
+            target_cloud,
         }
     }
 
-    fn find_correspondences<'b, FP>(
-        &self,
+    fn find_correspondences<'b, 't, FP>(
+        &'t self,
         alignee: &'b PointCloud<T, 3>,
-        target: &'b PointCloud<T, 3>,
+        _target: &'b PC,
         filter_points: &mut FP,
-    ) -> Correspondences<'b, T, 3>
+    ) -> Correspondences<'b, 't, T, 3>
     where
         FP: FnMut(&PointCloudPoint<T, 3>) -> bool,
+        'b: 't,
     {
         let (alignee_point_cloud, corresponding_target_point_cloud, alignee_to_target_distances) =
             get_ordered_correspondences_and_distances_nn(
                 &self.target_tree,
                 alignee,
-                target,
+                &self.target_cloud,
                 filter_points,
             );
 
         let (target_point_cloud, corresponding_alignee_point_cloud, target_to_alignee_distances) =
             get_ordered_correspondences_and_distances_nn(
                 &kd_tree_of_point_cloud(alignee),
-                target,
+                &self.target_cloud,
                 alignee,
                 filter_points,
             );

src/align/correspondence/bidirectional_distance.rs

@@ -71,14 +71,15 @@ where
         }
     }
 
-    fn find_correspondences<'b, FP>(
-        &self,
+    fn find_correspondences<'b, 't, FP>(
+        &'t self,
         alignee: &'b PointCloud<T, 3>,
         _target: &'b T,
         filter_points: &mut FP,
-    ) -> Correspondences<'b, T, 3>
+    ) -> Correspondences<'b, 't, T, 3>
     where
         FP: FnMut(&PointCloudPoint<T, 3>) -> bool,
+        'b: 't,
     {
         let mut point_cloud = self.point_cloud.borrow_mut();
         point_cloud.clear();

src/align/correspondence/cylinder.rs

@@ -13,7 +13,7 @@ use num_traits::{Float, One, Zero};
 use std::fmt::Debug;
 
 /// Contains all the correspondences found by the correspondence estimator.
-pub struct Correspondences<'a, T, const D: usize>
+pub struct Correspondences<'a, 't, T, const D: usize>
 where
     T: Copy + PartialEq + Debug + 'static,
 {
@@ -22,12 +22,12 @@ where
     pub alignee_point_cloud: MaskedPointCloud<'a, T, D>,
 
     /// Every point in this iterator corresponds to the point in the `alignee_point_cloud` with the same index.
-    pub corresponding_target_point_cloud: MaskedPointCloud<'a, T, D>,
+    pub corresponding_target_point_cloud: MaskedPointCloud<'t, T, D>,
 
     /// Iterator over the points of the target that have a corresponcence point in the alignee.
     /// (found in the `corresponding_alignee_point_cloud`).
     /// This is only used by bidrectional distance correspondence estimators.
-    pub target_point_cloud: MaskedPointCloud<'a, T, D>,
+    pub target_point_cloud: MaskedPointCloud<'t, T, D>,
 
     /// Every point in this iterator corresponds to the point in the `target_point_cloud` with the same index.
     /// This is only used by bidrectional distance correspondence estimators.
@@ -43,15 +43,16 @@ where
     pub target_to_alignee_distances: Vec<T>,
 }
 
-impl<'a, T, const D: usize> Correspondences<'a, T, D>
+impl<'a, 't, T, const D: usize> Correspondences<'a, 't, T, D>
 where
     T: Copy + PartialEq + Debug + 'static,
+    'a: 't,
 {
     /// Use this for simple one-way correspondence estimators.
     pub fn from_simple_one_way_correspondences(
         alignee_point_cloud: MaskedPointCloud<'a, T, D>,
         alignee: &'a PointCloud<T, D>,
-        corresponding_target_point_cloud: MaskedPointCloud<'a, T, D>,
+        corresponding_target_point_cloud: MaskedPointCloud<'t, T, D>,
         alignee_to_target_distances: Vec<T>,
     ) -> Self {
         let mut empty_alignee_cloud = MaskedPointCloud::new(alignee);
@@ -90,29 +91,30 @@ where
     /// It takes a reference to a `PointCloudPoint` and returns a boolean which is `true` if the point should be included.
     ///
     /// See the [`Correspondences`] return type documentation for more information.
-    fn find_correspondences<'b, FP>(
-        &self,
+    fn find_correspondences<'b, 't, FP>(
+        &'t self,
         alignee: &'b PointCloud<T, D>,
         target: &'b TG,
         filter_points: &mut FP,
-    ) -> Correspondences<'b, T, D>
+    ) -> Correspondences<'b, 't, T, D>
     where
-        FP: FnMut(&PointCloudPoint<T, 3>) -> bool;
+        FP: FnMut(&PointCloudPoint<T, 3>) -> bool,
+        'b: 't;
 }
 
 /// For every point in `data_set_x` finds the nearest point in `data_set_y` using the KD-Tree `tree`.
 /// Returns a masked point_cloud referencing `data_set_x` that contains all points allowed by `filter_points`
 /// and another masked point_cloud referencing `data_set_y` that correspond to the points in the first
 /// returned masked point_cloud.
 /// Finally it returns a list of the distances between the points of the two returned point_clouds.
-pub fn get_ordered_correspondences_and_distances_nn<'a, T, FP>(
-    tree: &KdTree<T, usize, &[T]>,
+pub fn get_ordered_correspondences_and_distances_nn<'a, 't, T, FP>(
+    tree: &KdTree<T, usize, Vec<T>>,
     data_set_x: &'a PointCloud<T, 3>,
-    data_set_y: &'a PointCloud<T, 3>,
+    data_set_y: &'t PointCloud<T, 3>,
     filter_points: &mut FP,
 ) -> (
     MaskedPointCloud<'a, T, 3>,
-    MaskedPointCloud<'a, T, 3>,
+    MaskedPointCloud<'t, T, 3>,
     Vec<T>,
 )
 where

src/align/correspondence/mod.rs

@@ -1,42 +1,48 @@
 use crate::correspondence::{
     CorrespondenceEstimator, Correspondences, get_ordered_correspondences_and_distances_nn,
 };
-use crate::{PointCloud, PointCloudPoint, kd_tree_of_point_cloud};
+use crate::{PointCloud, PointCloudPoint, ToPointCloud, kd_tree_of_point_cloud};
 use kdtree::KdTree;
 use nalgebra::{RealField, Scalar};
 use num_traits::{Float, One, Zero};
 
-pub struct NearestNeighbor<'a, T>
+pub struct NearestNeighbor<T>
 where
     T: Scalar + RealField + Float + One + Zero,
 {
-    tree: KdTree<T, usize, &'a [T]>,
+    tree: KdTree<T, usize, Vec<T>>,
+    target_cloud: PointCloud<T, 3>,
 }
 
-impl<'a, T> CorrespondenceEstimator<'a, T, PointCloud<T, 3>, 3> for NearestNeighbor<'a, T>
+impl<'a, T, PC> CorrespondenceEstimator<'a, T, PC, 3> for NearestNeighbor<T>
 where
     T: Scalar + RealField + Float + One + Zero,
+    PC: ToPointCloud<T, 3>,
 {
-    fn new(target: &'a PointCloud<T, 3>) -> Self {
+    fn new(target: &'a PC) -> Self {
+        let target_cloud = target.to_point_cloud();
+
         NearestNeighbor {
-            tree: kd_tree_of_point_cloud(target),
+            tree: kd_tree_of_point_cloud(&target_cloud),
+            target_cloud,
         }
     }
 
-    fn find_correspondences<'b, FP>(
-        &self,
+    fn find_correspondences<'b, 't, FP>(
+        &'t self,
         alignee: &'b PointCloud<T, 3>,
-        target: &'b PointCloud<T, 3>,
+        _target: &'b PC,
         filter_points: &mut FP,
-    ) -> Correspondences<'b, T, 3>
+    ) -> Correspondences<'b, 't, T, 3>
     where
         FP: FnMut(&PointCloudPoint<T, 3>) -> bool,
+        'b: 't,
     {
         let (alignee_point_cloud, corresponding_points_iter, distances) =
             get_ordered_correspondences_and_distances_nn(
                 &self.tree,
                 alignee,
-                target,
+                &self.target_cloud,
                 filter_points,
             );