Struct NodeBuilder 

pub struct NodeBuilder { /* private fields */ }

Records a node configuration; NodeBuilder::build checks it and creates the node on a host.

The reconstruction settings are a Plan (same fields and TOML as crate::declare); the input folder is the image root, positions/stride are not used (input is declared live), and GPS comes with each set.

Implementations

impl NodeBuilder

pub fn id(self, id: impl Into<String>) -> Self

Node id on the host (default "default").

pub fn plan(self, plan: Plan) -> Self

Replaces the reconstruction settings with a plan (e.g. read from TOML). Input positions/stride and the GPS file are ignored; sinks are ignored (use NodeBuilder::output).

pub fn images(self, dir: impl Into<PathBuf>) -> Self

Image folder: file payloads are relative to it, in-memory payloads are spooled inside it.

pub fn cameras<S: Into<String>>(self, cams: impl IntoIterator<Item = S>) -> Self

Cameras of one synchronized set, in position order.

pub fn zones(self, span: usize, overlap: usize) -> Self

Zone size and overlap in positions.

pub fn align(self, frame: AlignFrame) -> Self

Coordinate alignment (ENU needs GPS fixes in the sets).

pub fn fixed_enu_origin(self, on: bool) -> Self

Fixes the ENU origin at the first GPS fix.

pub fn features(self, f: Features) -> Self

Feature extraction settings.

pub fn match_backend(self, name: &str) -> Self

Descriptor matching backend (cpu | cuda).

pub fn gpu(self) -> Self

CUDA for features, matching, the sparse stages, densification, undistortion and bundle adjustment.

pub fn stable_display(self, on: bool) -> Self

Stable display (see SessionConfig::stable_display): intrinsics are settled then frozen, later zones are anchored to the shown ones with shared 3D points, and shown zones are re-densified in place (ZoneRefined of an earlier zone again), so the displayed cloud only gets refined and never jumps. Settle parameters come from the plan (sparse.settle_tol, sparse.settle_max_zone). Combine with NodeBuilder::fixed_enu_origin(true) for a display in a fixed ENU frame.

pub fn display_deltas(self, opts: LiveOptions) -> Self

Computes the in-memory display updates in the library: after every dense zone result a point-keyed Event::DisplayDelta is delivered to subscribers and hooks (EventKind::DisplayDelta). Thinning (stride), overlap voxel ownership and zone composition follow crate::post::LiveDisplay; relocate is decided by the node (on only when previews exist). Needs dense clouds with point keys (.dense(..), which the session always keys). The composition runs on the composing thread right after the causing event; the ENU origin reported in the delta frame is the first GPS fix declared.

pub fn incremental_triangulation(self, on: bool) -> Self

Triangulate only newly registered images.

pub fn lookahead(self, positions: usize) -> Self

Feature lookahead (see SessionConfig::lookahead, default 2; 0 = off): on a spawned node (ReconNode::spawn) the features of up to this many queued positions are extracted by a worker thread while earlier positions are matched, registered and triangulated, so the throughput approaches the slowest stage instead of the sum of the stages. Nothing is read ahead for sets whose payload is raw RGB pixels (their spooling stays on the worker). Results do not change.

pub fn batch(self, threshold: usize) -> Self

Backlog batching (default 1 = off; 0 or 1 = off): when a spawned node finds at least threshold states waiting (the one it takes plus the queued ones), it processes up to 32 of them as one batch (ReconNode::compose_batch): features, matching of all pending pairs in one call, registration and triangulation once per batch (split where a zone closes), so a backlog is worked off at the cost of one triangulation instead of one per position. The result is equivalent to position by position within the tolerance of registration order. Off with ReconcilePolicy::ReplayWindow (a rewind needs the state after every position).

pub fn preview(self, on: bool) -> Self

Stable display: a sparse preview of every zone as soon as it closes (see SessionConfig::preview), before the refined zone replaces it. With NodeBuilder::display_deltas it arrives as a crate::live::DeltaKind::Preview delta.

pub fn settle(self, tol: f64, max_zone: usize) -> Self

Stable display settling: intrinsics change tolerance and the last zone that may still settle (see SessionConfig::settle_tol, SessionConfig::settle_max_zone).

pub fn live_stride(self, stride: usize) -> Self

Live display thinning of the live diff stream: keep 1 of stride points by key hash (1 = keep all; default 6).

pub fn stream_origin(self, lat: f64, lon: f64, alt: f64) -> Self

Geodetic origin [lat, lon, alt] written to the live diff stream manifest. Give the first GPS fix the node will see (with NodeBuilder::fixed_enu_origin it is the origin of every zone); without it the manifest frame is display.

pub fn stream_only(self, on: bool) -> Self

With NodeBuilder::stable_display and NodeBuilder::output: write only run.log, the timeline and the live diff stream, not the zone PLYs, the display PLYs, the per-zone models or the post-processing snapshots (default off).

pub fn dense(self, d: Dense) -> Self

Densification settings (enables it).

pub fn no_dense(self) -> Self

No densification (default).

pub fn seed(self, seed: u64) -> Self

RANSAC seed.

pub fn reconcile(self, p: ReconcilePolicy) -> Self

Reconciliation policy (default ReconcilePolicy::AppendOnly).

pub fn backpressure(self, b: Backpressure) -> Self

Producer queue policy for ReconNode::spawn (default Block { max_pending: 8 }).

pub fn source(self, id: impl Into<String>) -> Self

Accept only this source id (default: the first declared source).

pub fn spool(self, rel: impl Into<PathBuf>) -> Self

Spool folder for in-memory payloads, relative to the image folder (default .live).

pub fn output(self, dir: impl Into<PathBuf>, opts: SinkOptions) -> Self

Writes the standard output files (timeline, run.log, zone PLYs, snapshots) to dir. With NodeBuilder::stable_display also the live diff stream (live/stream/).

pub fn on<F>(self, kind: EventKind, f: F) -> Self

where F: FnMut(&Event) + Send + 'static,

Hook for one event kind (Pipeline::on). FrameDecoded turns frame decoding on.

pub fn on_event<F>(self, f: F) -> Self

where F: FnMut(&Event) + Send + 'static,

Hook for every event (Pipeline::on_any).

pub fn on_frame<F>(self, f: F) -> Self

where F: FnMut(&Arc<Frame>) + Send + 'static,

Decoded input frames (Pipeline::on_frame); turns frame decoding on.

pub fn on_zone_preview<F>(self, f: F) -> Self

where F: FnMut(ZoneRange, &Arc<PointCloud>) + Send + 'static,

Zone preview clouds (Pipeline::on_zone_preview).

pub fn on_zone_refined<F>(self, f: F) -> Self

where F: FnMut(ZoneRange, &Arc<PointCloud>) + Send + 'static,

Zone refined clouds (Pipeline::on_zone_refined).

pub fn on_message<F>(self, f: F) -> Self

where F: FnMut(EventKind, &str) + Send + 'static,

Warnings and errors (Pipeline::on_message); includes reconciliation warnings.

pub fn event_policy(self, kind: EventKind, p: QueuePolicy) -> Self

Per-kind hook queue policy (Pipeline::policy), e.g. LatestPerKey for ZonePreview.

pub fn sync_hooks(self, on: bool) -> Self

Runs hooks synchronously on the composing thread (Pipeline::sync).

pub fn intrinsics_prior(self, prior: IntrinsicsPrior) -> Self

Soft intrinsics prior (the CLI’s --intrinsics-prior): every camera starts from the given parameters (except the principal point) and the bundle adjustment is pulled towards them with the prior’s σ values. Cameras are keyed by camera name (one of NodeBuilder::cameras) or by id; a camera without an entry is left alone. Checked by build.

use cumulus3d_cli::compose::ReconNode;
use cumulus3d_cli::intrinsics::IntrinsicsPrior;
let prior = IntrinsicsPrior::new()
    .sigmas(0.005, 0.01) // focal: relative, distortion: absolute
    .opencv("camF", [1607.4, 1611.2, 1024.0, 576.0, 0.082, -0.084, 0.0013, 0.0014]);
let _builder = ReconNode::declare().images("live/images").cameras(["camF"]).intrinsics_prior(prior);

pub fn intrinsics_prior_json(self, path: impl AsRef<Path>) -> Self

Reads the prior from a JSON file (same format as the CLI’s --intrinsics-prior; default σ values 0.005 / 0.01). A read or parse error is reported by build. For other σ values use IntrinsicsPrior::load and NodeBuilder::intrinsics_prior.

pub fn build(self, host: &CompositionHost) -> Result<ReconNode, ComposeError>

Checks the configuration, creates the session and pipeline, and registers the node on host. Creates the image folder’s spool folder; nothing else is written until frames are declared.

Trait Implementations

impl Debug for NodeBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.