English | 한국어

cumulus3d-cli

The cumulus3d executable, which progressively builds 3D point clouds from drone-formation video (three cameras, GPS), and the library (cumulus3d_cli) that holds its assembly.

Pipeline stage: the whole assembly. It chains the other crates (feature extraction → matching → SfM → BA → GPS alignment → densification) inside a single process and handles progressive streaming: while video arrives position by position, it emits per-zone previews (no BA) and refined models (with BA) as events. Data passes between stages as in-memory structures (no intermediate database or model folders).

Build: cargo build --release -p cumulus3d-cli → target/release/cumulus3d.

Executable usage

cumulus3d stream

cumulus3d stream --src <input dir> --out <output dir> [--span 12 --overlap 2 --stride 3] [options]

Input folder: images/camF|camR|camL/<cam>_NNNN.jpg, gps_ref.txt (lines: camF/camF_0000.jpg latitude longitude altitude). Only frames camF_NNNN.jpg with NNNN % stride == 0 are used, and position = index in the list of selected frames. The output folder is deleted and recreated.

Output: timeline.txt, run.log, full/{preview,refined}/*.ply (per-zone dense point clouds), aligned/, snapshots/ (per-event snapshots, manifest.json), final_frame/ (zone point clouds brought into the last refined frame), work/models/ (--save-models), DONE. The table of outputs per hook is in the sinks module documentation.

cumulus3d stream --src <input-dir> --out <output-dir> --stride 1
cumulus3d stream --src <input-dir> --out <output-dir-quick> --stride 1 --max-positions 15 --dense-max-image-size 320

cumulus3d run / cumulus3d plan (declarative plan)

cumulus3d run <plan.toml> [--check]        # check the plan (every problem at once), then run
cumulus3d plan --print-default             # default plan (aerial-formation preset) as TOML
cumulus3d plan --check <plan.toml>         # check only

A plan file holds the same settings as the stream options ([input], [zones], [align], [features], [matching], [sparse], [dense] with [dense.fusion]/[dense.filter], [sinks], and top-level seed, threads, gps, pairing). Missing keys take their defaults; unknown keys are errors. Example: examples/plans/aerial-formation.toml at the repository root. With the same settings, run produces the same outputs as stream.

Stage subcommands

feature_extractor, matches_importer, global_mapper, image_registrator, point_triangulator, bundle_adjuster, model_aligner, model_analyzer, model_converter, image_deleter, image_undistorter, densify. They accept the command names and option strings used by existing scripts (--database_path, --ImageReader.camera_model, etc.). State between stages is carried by --database_path (a cumulus3d feature-store binary file in C3DFS format; files with the old marker from before 0.3.0 are also read) and model folders (cumulus3d_core::interop format). Boolean options accept 1/0/true/false; GPU-related options (--FeatureExtraction.use_gpu, etc.) are accepted but ignored.

cumulus3d feature_extractor --database_path db.c3dfs --image_path images --ImageReader.single_camera_per_folder 1 --ImageReader.camera_model OPENCV
cumulus3d matches_importer --database_path db.c3dfs --match_list_path pairs.txt --match_type pairs
cumulus3d global_mapper --database_path db.c3dfs --image_path images --output_path sg0   # model goes to sg0/0
cumulus3d model_aligner --input_path in --output_path out --ref_images_path gps.txt --ref_is_gps 1 --alignment_type enu --alignment_max_error 3
cumulus3d model_converter --input_path model --output_path out --output_type BIN|TXT|PLY
cumulus3d image_undistorter --image_path images --input_path in --output_path dense --max_image_size 960
cumulus3d densify -i dense -o dense.ply [--mvs-profile fast|quality --number-views 10 --fusion-mode consistency|traversal|score --stats]
cumulus3d densify -i model --image_path images -o dense.ply      # undistortion done in memory too
cumulus3d densify -i dense -o out/x.ply --fusion-variants variants.txt   # depth maps once, several fusion settings

model_aligner supports only --ref_is_gps 1 --alignment_type enu. The feature store is cumulus3d's own binary format, not SQLite.

Main entry points

Public items

session — state value and reducer

pipeline — hook pipeline

events — events and commands

live — in-memory display deltas

sinks — default output hooks

stream — cumulus3d stream assembly

declare — declarative builder (plan → build → run)

Full reference: docs/DECLARATIVE.md.

densewrap — shared densification path

post — post-processing (alignment, snapshots, re-anchoring)

fusion_variants — batch run of fusion variants

interop — stage subcommands

util — logging, timing, and serialization helpers

Examples

Feed an image folder position by position for progressive reconstruction, producing the same files as cumulus3d stream (requires real images).

use cumulus3d_cli::events::{Event, EventKind};
use cumulus3d_cli::pipeline::Pipeline;
use cumulus3d_cli::session::{Input, Session, SessionConfig};
use cumulus3d_cli::sinks::{self, SinkOptions};
use cumulus3d_cli::stream::{frame_set, Layout};
use cumulus3d_core::io::read_gps_file;
use std::path::Path;

fn main() -> Result<(), String> {
    let src = Path::new("data");
    let layout = Layout::discover(src, 3)?;
    let mut cfg = SessionConfig::new(src.join("images"));
    cfg.gps = read_gps_file(src.join("gps_ref.txt")).map_err(|e| e.to_string())?;
    cfg.total_positions = Some(layout.frames.len());

    let pipeline = Pipeline::new(Session::new(cfg)).on(EventKind::ZonePreview, |e: &Event| {
        if let Event::ZonePreview { range, cloud, .. } = e {
            println!("preview zone {}: {} points", range.zone, cloud.len());
        }
    });
    let mut pipeline = sinks::attach(pipeline, Path::new("out"), &SinkOptions::default()).map_err(|e| e.to_string())?;
    for p in 0..layout.frames.len() {
        pipeline.push(Input::Frames(frame_set(&layout, p)));
    }
    let (_session, summary) = pipeline.finish();
    println!("{} events", summary.events);
    Ok(())
}

Functional use, passing only state values without hooks:

use cumulus3d_cli::session::{finish, step, FrameSet, Session, SessionConfig};

let s0 = Session::new(SessionConfig::new("data/images"));
let frames = FrameSet::new([("camF", "camF/camF_0000.jpg"), ("camR", "camR/camR_0000.jpg")]);
let (s1, events) = step(&s0, frames);
for e in &events {
    if let Some(t) = e.timeline_text() {
        println!("{t}");
    }
}
let (_done, _summary_events) = finish(&s1);

Both examples are also included as doc-tests in src/lib.rs. For an example that runs end to end on a synthetic scene: cargo run --release -p cumulus3d-cli --example hooks.

Feature flags and hardware

• There are no cargo feature flags. cumulus3d-cuda is always linked, but it loads the CUDA libraries dynamically, so it builds and runs on machines without CUDA.
• Densification (stream by default, the densify subcommand) requires the GPU PatchMatch backend (CUDA 12.x driver). Without a device, stream logs an error at the densification stage; use --no-dense to run without densification. The SessionConfig::new default is no densification.
• --gpu or --sift-backend cuda / --match-backend cuda require a CUDA 12.x driver. Results are identical to the CPU backends.
• Tests: cargo test --release -p cumulus3d-cli (stream end to end on a synthetic scene, subcommand chains, equivalence of default hook output).