English | 한국어

cumulus3d-align

Coordinate alignment and point cloud post-processing: GPS (WGS84) ↔ ENU conversion, robust Sim3 alignment of a reconstruction to GPS ENU, alignment of two reconstructions via shared 3D points, zone coordinate-frame chaining (re-anchoring), and point cloud masking, decimation, and snapshot composition. Every Sim3 follows the core convention new_from_old (X' = sRX + t).

Pipeline stage: after SfM. Aligns each zone's refined model to the GPS-referenced ENU frame (the refined map) (align_to_gps), moves the preview into the refined model's frame (align_reconstructions), chains the frames of successive zones (AnchorChain), and builds the step-by-step snapshot point clouds (compose_snapshot).

Main entry points

Public items

Items marked ✓ in the "Root" column are also re-exported at the crate root (cumulus3d_align::).

cloud — point cloud post-processing (core PointCloud)

error

geodesy — WGS84 LLA ↔ ECEF ↔ ENU

kdtree

model_aligner — GPS ENU alignment

reanchor

shared — shared 3D points of two reconstructions

umeyama — Sim3 estimation

Examples

Same code as the crate-level doc-test (synthetic data).

use cumulus3d_align::{compose_snapshot, umeyama, EnuFrame, SnapshotOptions};
use cumulus3d_core::io::PointCloud;
use cumulus3d_core::{Quat, Sim3, Vec3};

// GPS (WGS84) ↔ ENU: east/north/up coordinates in meters from the origin.
let enu = EnuFrame::new(37.5, 127.0, 10.0);
let p = enu.lla_to_enu(37.5001, 127.0001, 10.0);
let (lat, lon, _alt) = enu.enu_to_lla(&p);
assert!((lat - 37.5001).abs() < 1e-9 && (lon - 127.0001).abs() < 1e-9);

// Estimate the Sim3 (src → dst) between two sets of corresponding points.
let truth = Sim3::new(2.0, Quat::from_axis_angle(&Vec3::z(), 0.3), Vec3::new(1.0, 2.0, 3.0));
let src: Vec<Vec3> = (0..10).map(|i| Vec3::new(i as f64, (i * i) as f64 * 0.1, (i as f64).sin())).collect();
let dst: Vec<Vec3> = src.iter().map(|x| truth.transform_point(x)).collect();
let est = umeyama(&src, &dst, true).unwrap();
assert!((est.scale - 2.0).abs() < 1e-9);

// Snapshot: drop preview points within 1.5 m of refined points, merge, then take 1/stride.
let fine = PointCloud { positions: vec![[0.0, 0.0, 0.0]], ..Default::default() };
let coarse = PointCloud { positions: vec![[0.5, 0.0, 0.0], [10.0, 0.0, 0.0]], ..Default::default() };
let snap = compose_snapshot(&[&fine], &[&coarse], &SnapshotOptions { mask_radius: 1.5, stride: 1 });
assert_eq!(snap.len(), 2);

Aligning a reconstruction to the GPS-referenced ENU frame:

use cumulus3d_align::{align_to_gps_file, ModelAlignerOptions};
let mut rec = cumulus3d_core::interop::read_model("model/0").unwrap();
let a = align_to_gps_file(&mut rec, "gps_ref.txt", &ModelAlignerOptions::default()).unwrap();
println!("inliers {}/{}, median error {:.2} m", a.num_inliers, a.common.len(), a.median_error);

Feature flags and hardware

• No feature flags. CPU only (point cloud processing and KD-tree queries run in parallel with rayon).
• The GPS file format (lines of name latitude longitude altitude) is read by cumulus3d_core::io::read_gps_file.