English | 한국어

cumulus3d-core

The common foundation crate of cumulus3d: camera models, geometry (quaternions, rigid and similarity transforms), feature and match types, an in-memory feature store, a correspondence graph, sparse reconstruction data structures, generic RANSAC, and file I/O.

API doc comments are currently in Korean; English translation is planned.

Role in the pipeline: it does not run a stage of its own; it defines the types and stores exchanged by every stage (features → matching → SfM → alignment → densification). The feature stage writes to a FeatureStore, the matching stage writes two-view geometries into the same store, and SfM reads correspondences through a MatchGraph to build a Reconstruction.

Conventions

• Numbers are f64 (keypoints only are f32). Vectors and matrices use the nalgebra aliases Vec2, Vec3, Mat3, Mat3x4.
• IDs: CameraId/RigId/FrameId/ImageId/Point2DIdx = u32, Point3DId/PairId = u64. Invalid value = the maximum value (INVALID_*). Image IDs must be < 2^31−1 (because of the pair ID computation).
• Poses: Rigid3 = A_to_B, X_B = R X_A + t. Image poses are world_to_cam, center C = −Rᵀt. a * b = a ∘ b (A_to_C = B_to_C * A_to_B).
• Quaternion Quat {w,x,y,z}: Hamilton convention, file order w,x,y,z.
• Camera coordinates: x right, y down, z forward. The pixel origin is the top-left corner; the center of the top-left pixel = (0.5, 0.5).
• Sim3 is new_from_old: X' = s R X + t. Use Sim3::transform_pose for poses.
• RANSAC residuals are squared errors; inlier = residual ≤ max_error².
• Pair data is stored internally in the "smaller id → larger id" direction; lookups in the opposite direction return the inverted data.

Main entry points

Public items

"root" marks items that are also re-exported from the crate root (cumulus3d_core::…).

analyzer

camera

error

features

geometry

graph

ids (all root)

interop

Handles the model file format (cameras/images/points3D, optionally rigs/frames; .bin and .txt) and the dense-reconstruction workspace layout.

io

linalg

ransac

reconstruction

store

Example

Build a reconstruction from two images and one 3D point, compute the reprojection error, then save and load it as model files (same as the doc-test in src/lib.rs).

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};

fn main() -> cumulus3d_core::Result<()> {
    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 two cameras (1 m baseline) to create 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));
    Ok(())
}

Feature flags and hardware

None. This is a pure-CPU crate with no feature flags. Dependencies: nalgebra, rayon (parallel observation filtering), rand/rand_pcg, thiserror.