fast_gicp/
lib.rs

1//! High-level Rust API for the fast_gicp point cloud registration library.
2//!
3//! This crate provides safe, idiomatic Rust bindings for the fast_gicp C++ library,
4//! which implements efficient variants of the Generalized Iterative Closest Point (GICP) algorithm.
5//!
6//! # Features
7//!
8//! - **openmp**: Enables OpenMP parallelization (default)
9//! - **cuda**: Enables CUDA GPU acceleration
10//!
11//! # Examples
12//!
13//! ## Using the Builder Pattern
14//!
15//! The builder pattern provides a fluent API for configuring registration algorithms:
16//!
17//! ```no_run
18//! use fast_gicp::{types::RegularizationMethod, FastGICP, PointCloudXYZ};
19//!
20//! let source = PointCloudXYZ::from_points(&[[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]]);
21//! let target = PointCloudXYZ::from_points(&[[0.1, 0.0, 0.0], [1.1, 0.0, 0.0]]);
22//!
23//! // Create and configure FastGICP using the builder pattern
24//! let gicp = FastGICP::builder()
25//!     .max_iterations(50)
26//!     .transformation_epsilon(1e-6)
27//!     .regularization_method(RegularizationMethod::Frobenius)
28//!     .build()?;
29//!
30//! let result = gicp.align(&source, &target)?;
31//! println!("Final transformation: {:?}", result.final_transformation);
32//! # Ok::<(), fast_gicp::Error>(())
33//! ```
34//!
35//! ## VGICP with Voxelization
36//!
37//! ```no_run
38//! use fast_gicp::{types::VoxelAccumulationMode, FastVGICP, PointCloudXYZ};
39//!
40//! let source = PointCloudXYZ::from_points(&[[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]]);
41//! let target = PointCloudXYZ::from_points(&[[0.1, 0.0, 0.0], [1.1, 0.0, 0.0]]);
42//!
43//! let vgicp = FastVGICP::builder()
44//!     .resolution(0.5)
45//!     .voxel_accumulation_mode(VoxelAccumulationMode::Additive)
46//!     .build()?;
47//!
48//! let result = vgicp.align(&source, &target)?;
49//! # Ok::<(), fast_gicp::Error>(())
50//! ```
51//!
52//! ## CUDA Acceleration (requires "cuda" feature)
53//!
54//! ```no_run
55//! # #[cfg(feature = "cuda")]
56//! # {
57//! use fast_gicp::{types::NeighborSearchMethod, FastVGICPCuda, PointCloudXYZ};
58//!
59//! let source = PointCloudXYZ::from_points(&[[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]]);
60//! let target = PointCloudXYZ::from_points(&[[0.1, 0.0, 0.0], [1.1, 0.0, 0.0]]);
61//!
62//! let cuda_vgicp = FastVGICPCuda::builder()
63//!     .resolution(1.0)
64//!     .neighbor_search_method(NeighborSearchMethod::Direct27)
65//!     .build()?;
66//!
67//! let result = cuda_vgicp.align(&source, &target)?;
68//! # }
69//! # Ok::<(), fast_gicp::Error>(())
70//! ```
71//!
72//! ## Direct API
73//!
74//! You can also use the algorithms directly:
75//!
76//! ```no_run
77//! use fast_gicp::{FastGICP, PointCloudXYZ, Transform3f};
78//!
79//! let source = PointCloudXYZ::from_points(&[[0.0, 0.0, 0.0], [1.0, 0.0, 0.0]]);
80//! let target = PointCloudXYZ::from_points(&[[0.1, 0.0, 0.0], [1.1, 0.0, 0.0]]);
81//!
82//! let gicp = FastGICP::new();
83//! let result = gicp.align(&source, &target)?;
84//! println!("Final transformation: {:?}", result.final_transformation);
85//! # Ok::<(), fast_gicp::Error>(())
86//! ```
87
88/// Point cloud and registration modules
89pub mod error;
90
91pub mod point_cloud;
92pub mod registration;
93pub mod transform;
94
95pub mod types;
96
97#[cfg(feature = "cuda")]
98pub mod fast_vgicp_cuda;
99
100#[cfg(feature = "cuda")]
101pub mod ndt_cuda;
102
103// Re-exports for convenience
104pub use error::{Error, Result};
105
106pub use point_cloud::{PointCloudXYZ, PointCloudXYZI};
107pub use registration::{FastGICP, FastVGICP, RegistrationResult};
108pub use transform::Transform3f;
109
110pub use types::{NeighborSearchMethod, RegularizationMethod, VoxelAccumulationMode};
111
112#[cfg(feature = "cuda")]
113pub use types::{NdtDistanceMode, NearestNeighborMethod};
114
115#[cfg(feature = "cuda")]
116pub use fast_vgicp_cuda::FastVGICPCuda;
117
118#[cfg(feature = "cuda")]
119pub use ndt_cuda::NDTCuda;
120
121#[cfg(all(test, not(feature = "cuda")))]
122mod tests {
123    use super::*;
124
125    #[test]
126    fn test_point_cloud_creation() {
127        let cloud = PointCloudXYZ::new();
128        assert_eq!(cloud.size(), 0);
129        assert!(cloud.is_empty());
130    }
131
132    #[test]
133    fn test_point_cloud_from_iterator() {
134        let points = vec![[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]];
135        let cloud: PointCloudXYZ = points.into_iter().collect();
136        assert_eq!(cloud.size(), 2);
137    }
138}
139
140#[cfg(feature = "docs-only")]
141#[cfg(test)]
142mod docs_only_tests {
143    use super::types::*;
144
145    #[test]
146    fn test_types_exist() {
147        // Test that basic types can be created
148        let _method = RegularizationMethod::Frobenius;
149        let _mode = VoxelAccumulationMode::Additive;
150        let _neighbor = NeighborSearchMethod::Direct1;
151    }
152}
fast_gicp/lib.rs

fast_gicp/
lib.rs
