English | 한국어

cumulus3d-features

Image reading (decoding, EXIF, grayscale conversion, downscaling, orientation rotation), initial camera parameter selection, and deterministic SIFT feature extraction.

Pipeline stage: the first stage (feature extraction). Takes a batch of images, assigns cameras, and incrementally writes keypoints and descriptors to cumulus3d_core::FeatureStore. cumulus3d-matching reads this store. SIFT computation sits behind the SiftEngine trait, so it can be swapped for a GPU backend (CudaSift in cumulus3d-cuda).

Main entry points

Public items

"Root" in the tables marks items re-exported at the crate root as cumulus3d_features::name.

extract

gray

exif_info

camera_init

sift

sift::pyramid (low level)

sift::detect (low level)

sift::orient (low level)

Example

Run SIFT on a synthetic image and write it to the store (same code as the crate-level doc-test).

use cumulus3d_core::FeatureStore;
use cumulus3d_features::{
    CpuSift, ExifInfo, ExtractionOptions, FeatureExtractor, GrayImage, ImageSource, ImageStatus, SiftEngine,
    SiftOptions,
};

// Synthetic image: three bright blobs.
let blob = |x: usize, y: usize, cx: f32, cy: f32, s: f32| {
    let (dx, dy) = (x as f32 - cx, y as f32 - cy);
    (-(dx * dx + dy * dy) / (2.0 * s * s)).exp()
};
let img = GrayImage::from_f32(320, 240, |x, y| {
    0.2 + 0.6 * (blob(x, y, 80.0, 60.0, 6.0) + blob(x, y, 200.0, 150.0, 9.0) + blob(x, y, 260.0, 70.0, 5.0))
});

// 1) Call the SIFT backend directly: feature i ↔ descriptor row i.
let out = CpuSift::new().extract(&img, &SiftOptions::default())?;
assert!(!out.is_empty());
assert_eq!(out.features.len(), out.descriptors.len());

// 2) Write to the store (camera assignment + keypoints and descriptors).
let store = FeatureStore::new();
let src = ImageSource { name: "camF/0001.jpg".into(), gray: img, exif: ExifInfo::default() };
let reports = FeatureExtractor::new().extract_inputs(&store, vec![src], &ExtractionOptions::default())?;
assert!(matches!(reports[0].status, ImageStatus::Extracted { .. }));
assert_eq!(store.num_images(), 1);

To read from files, use FeatureExtractor::extract_files(&store, root, &names, &opts). Benchmark: cargo run --release -p cumulus3d-features --example bench_sift -- <image|synthetic> 2048 1152.

Feature flags and hardware

• No feature flags. Pure CPU (rayon) implementation; no special hardware required.
• To run SIFT on the GPU, pass CudaSift from cumulus3d-cuda to FeatureExtractor::with_backend (requires a CUDA 12.x driver).

Behavior notes

• Output is fully deterministic: ascending octave → ascending level → row-major detection order, with a second orientation immediately following its first.
• All improvement options that change results are off by default: truncate_width_to_4 = false, refinement_iterations = 5, reject_singular_refinement, orientation_bin_interpolation, FeatureSelection::TopK/SpatialGrid, num_octaves = Some(n).
• If the name already exists with both keypoints and descriptors, it is skipped (AlreadyExists). If only the row exists, only the features are filled in.
• When read_pose_priors is on and EXIF GPS is present, a position prior (latitude, longitude, altitude) is recorded in the store.
• The store has no rig/frame rows. In the reconstruction stage, Reconstruction::add_image_own_frame creates a frame per image.