Pipeline

class aquamvs.Pipeline(config)

Multi-view stereo reconstruction pipeline.

Primary programmatic entry point for AquaMVS.

Example

pipeline = Pipeline(config) pipeline.run()

Parameters:

config (PipelineConfig)

run()

Run the full reconstruction pipeline.

Equivalent to calling run_pipeline(config).

Return type:

None

class aquamvs.PipelineContext(config, calibration, undistortion_maps, projection_models, pairs, ring_cameras, auxiliary_cameras, device, masks)

Precomputed data that is constant across all frames.

Created once by setup_pipeline() and reused for every frame.

Parameters:

• config (PipelineConfig)

• calibration (CalibrationData)

• undistortion_maps (dict[str, UndistortionData])

• projection_models (dict[str, ProjectionModel])

• pairs (dict[str, list[str]])

• ring_cameras (list[str])

• auxiliary_cameras (list[str])

• device (str)

• masks (dict[str, ndarray])

aquamvs.run_pipeline(config)

Run the full reconstruction pipeline over video frames.

Uses a two-pass architecture to avoid Open3D OpenGL / CUDA GPU memory conflicts on Windows:

1. Compute pass — matching, depth estimation, fusion, surface reconstruction. All outputs saved to disk.

2. Viz pass — reload saved artifacts from disk, render all visualizations.

Between passes, torch.cuda.empty_cache() frees GPU memory so Open3D’s OpenGL context can allocate without competing with CUDA.

Parameters:

config (PipelineConfig) – Full pipeline configuration.

Return type:

None

aquamvs.process_frame(frame_idx, raw_images, ctx)

Process a single frame through the full reconstruction pipeline.

Runs all stages sequentially, saving outputs to the frame’s output directory. Each stage logs its completion. Visualization calls are gated by VizConfig and output persistence by OutputConfig.

Parameters:

• frame_idx (int) – Frame index (for output directory naming).

• raw_images (dict[str, ndarray]) – Camera name to raw BGR image (H, W, 3) uint8 mapping. May contain None values for cameras that failed to read.

• ctx (PipelineContext) – Precomputed pipeline context from setup_pipeline().

Return type:

None

Protocols

class aquamvs.pipeline.interfaces.FrameSource(*args, **kwargs)

Protocol for frame iteration over multi-camera video or image sequences.

Abstracts both VideoSet and ImageDirectorySet to allow uniform iteration over synchronized frames from multiple cameras.

iterate_frames(start, stop, step)

Iterate over synchronized frames from all cameras.

Parameters:

• start (int) – Starting frame index.

• stop (int | None) – Ending frame index (exclusive), or None for all remaining frames.

• step (int) – Frame step size (1 = every frame, 2 = every other frame, etc.).

Yields:

Tuple of (frame_idx, images) where images is a dict mapping camera name to raw BGR image (H, W, 3) uint8 array. May contain None values for cameras that failed to read.

Return type:

Iterator[tuple[int, dict[str, ndarray]]]

class aquamvs.pipeline.interfaces.CalibrationProvider(*args, **kwargs)

Protocol for providing calibration data to the pipeline.

Defines the interface for accessing camera calibration parameters and refractive geometry. The existing CalibrationData class already satisfies this protocol structurally — no modifications needed.

property cameras: dict[str, CameraData]

Per-camera calibration data, keyed by camera name.

property water_z: float

Z-coordinate of the water surface in world frame (meters).

property n_water: float

Refractive index of water.

property n_air: float

Refractive index of air.

property interface_normal: Tensor

Interface normal vector, shape (3,), float32.

property ring_cameras: list[str]

Names of non-auxiliary cameras (sorted for determinism).

property auxiliary_cameras: list[str]

Names of auxiliary cameras (sorted for determinism).

camera_positions()

World-frame camera centers, computed as C = -R^T @ t.

Returns:

Dictionary mapping camera names to their centers in world frame. Each center is a tensor of shape (3,), float32.

Return type:

dict[str, Tensor]