Crate cumulus3d_core 

Common foundation: camera models, geometry, reconstruction data structures, correspondence graph, feature store, RANSAC, I/O.

Convention summary (public items per module are in the crate README.md):

• Poses are world_to_cam (world -> camera); quaternions are Hamilton, stored in w,x,y,z order.
• Camera frame: x right, y down, z forward. Pixel coordinates: top-left pixel center = (0.5, 0.5).
• ids: camera/rig/frame/image = u32, 3D point = u64, pair = u64. The invalid value is the maximum of each type.

Usage example

Builds a reconstruction from two images and one 3D point, computes the reprojection error, then saves and loads it as a model file.

use cumulus3d_core::analyzer::ModelStats;
use cumulus3d_core::interop::{read_model, write_model_binary, ImageOrder};
use cumulus3d_core::{Camera, CameraModelKind, Image, Quat, Reconstruction, Rigid3, TrackEntry, Vec3};

let mut cam = Camera::from_focal(CameraModelKind::Pinhole, 1000.0, 1920, 1080);
cam.camera_id = 1;
let mut rec = Reconstruction::new();
rec.add_camera_own_rig(cam.clone())?;

// Project one world point into the two cameras (1 m baseline) to produce 2D observations.
let x = Vec3::new(0.2, -0.1, 5.0);
for (id, tx) in [(1u32, 0.0), (2, -1.0)] {
    let world_to_cam = Rigid3::new(Quat::IDENTITY, Vec3::new(tx, 0.0, 0.0));
    let xy = cam.cam_to_img(&world_to_cam.transform_point(&x)).unwrap();
    rec.add_image_own_frame(Image::new(id, format!("img{id}.jpg"), 1, [xy]), Some(world_to_cam))?;
    rec.register_image(id)?;
}
let pid = rec.add_point3d(x, vec![TrackEntry::new(1, 0), TrackEntry::new(2, 0)], [255, 0, 0])?;
rec.update_point3d_errors();
assert!(rec.point3d(pid).unwrap().error < 1e-9);
rec.check_invariants()?;

let dir = std::env::temp_dir().join("cumulus3d_core_doc_example");
std::fs::create_dir_all(&dir)?;
write_model_binary(&rec, &dir, ImageOrder::default())?;
let back = read_model(&dir)?;
let stats = ModelStats::compute(&back);
assert_eq!((stats.registered_image_count, stats.num_points3d), (2, 1));

Re-exports

pub use camera::Camera;

pub use camera::CameraModelKind;

pub use error::Error;

pub use error::Result;

pub use features::Descriptors;

pub use features::FeatureMatch;

pub use features::Keypoint;

pub use features::TwoViewGeometry;

pub use features::TwoViewGeometryConfig;

pub use features::DESCRIPTOR_DIM;

pub use geometry::Mat3;

pub use geometry::Mat3x4;

pub use geometry::Quat;

pub use geometry::Rigid3;

pub use geometry::Sim3;

pub use geometry::Vec2;

pub use geometry::Vec3;

pub use graph::MatchGraph;

pub use graph::MatchGraphOptions;

pub use reconstruction::Frame;

pub use reconstruction::Image;

pub use reconstruction::Point2D;

pub use reconstruction::Point3D;

pub use reconstruction::Reconstruction;

pub use reconstruction::Rig;

pub use reconstruction::TrackEntry;

pub use store::FeatureStore;

pub use ids::*;

Modules

analyzer

Model statistics (output of the model_analyzer subcommand).

camera

Camera models.

error

Error type.

features

Feature and matching data types.

geometry

Geometry: quaternions, rigid transforms (Rigid3), similarity transforms (Sim3), angle utilities.

graph

Correspondence graph.

ids

Identifier types and pair ids.

interop

File formats exchanged with external tools (interoperability).

io

I/O: PLY, GPS reference files, number formatting and binary helpers. The model file format is in crate::interop.

linalg

Small fixed-size linear algebra. The 3×3 SVD in nalgebra 0.35 gives wrong values when singular values coincide, so a one-sided Jacobi implementation lives here (shared by matching, sfm and align).

ransac

General-purpose RANSAC / LO-RANSAC.

reconstruction

Sparse reconstruction data structures.

store

In-memory feature store (images, cameras, keypoints, descriptors, matches, two-view geometry). Can be saved to and loaded from a binary file.