Configuration

class aquamvs.PipelineConfig(*, calibration_path='', output_dir='', camera_input_map=<factory>, mask_dir=None, pipeline_mode='full', matcher_type='lightglue', quality_preset=None, preprocessing=<factory>, sparse_matching=<factory>, dense_matching=<factory>, reconstruction=<factory>, runtime=<factory>, **extra_data)[source]

Top-level configuration for the AquaMVS reconstruction pipeline.

Parameters:
calibration_path

Path to AquaCal calibration JSON file.

Type:

str

output_dir

Root output directory for reconstruction results.

Type:

str

camera_input_map

Mapping from camera name to input path (video file or image directory).

Type:

dict[str, str]

mask_dir

Optional directory containing per-camera ROI mask PNGs.

Type:

str | None

pipeline_mode

Pipeline execution mode (“sparse” or “full”).

Type:

Literal[‘sparse’, ‘full’]

matcher_type

Matcher backend (“lightglue” or “roma”).

Type:

Literal[‘lightglue’, ‘roma’]

quality_preset

Optional quality preset (fast/balanced/quality) to apply default values.

Type:

aquamvs.config.QualityPreset | None

preprocessing

Preprocessing configuration.

Type:

aquamvs.config.PreprocessingConfig

sparse_matching

Sparse matching configuration.

Type:

aquamvs.config.SparseMatchingConfig

dense_matching

Dense matching configuration.

Type:

aquamvs.config.DenseMatchingConfig

reconstruction

Reconstruction configuration.

Type:

aquamvs.config.ReconstructionConfig

runtime

Runtime configuration.

Type:

aquamvs.config.RuntimeConfig

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

apply_preset(preset)[source]

Apply a quality preset to this configuration.

Only applies preset values to parameters that are still at their defaults. User-specified values take precedence and are not overridden.

Parameters:

preset (QualityPreset) – Quality preset to apply.

Returns:

Self for method chaining.

Return type:

PipelineConfig

auto_apply_preset()[source]

Warn when quality_preset is present in config (no longer applied at runtime).

Presets are now baked in at init time via aquamvs init --preset <name>. Loading a config with quality_preset set does NOT silently override user-specified values.

Return type:

PipelineConfig

check_cross_stage_constraints()[source]

Validate cross-stage constraints and warn about extra fields.

Return type:

PipelineConfig

classmethod from_yaml(path)[source]

Load configuration from a YAML file.

Missing fields use their default values. Loaded values are merged over defaults. Supports backward compatibility with old flat structure.

Parameters:

path (str | Path) – Path to YAML configuration file.

Returns:

Loaded configuration with defaults filled in.

Raises:

  • FileNotFoundError – If the file does not exist.

  • yaml.YAMLError – If the file is not valid YAML.

  • ValueError – If validation fails (with all errors collected).

Return type:

PipelineConfig

to_yaml(path)[source]

Save configuration to a YAML file.

All fields including defaults are written for explicitness.

Parameters:

path (str | Path) – Path to output YAML file.

Return type:

None

validate()[source]

Validate configuration values.

This method exists for backward compatibility. Pydantic now validates automatically during construction.

Raises:

ValidationError – If any configuration value is invalid.

Return type:

None

class aquamvs.PreprocessingConfig(*, color_norm_enabled=False, color_norm_method='gain', frame_start=0, frame_stop=None, frame_step=1, **extra_data)[source]

Configuration for preprocessing (color normalization + frame sampling).

Consolidates ColorNormConfig and FrameSamplingConfig.

Parameters:

  • color_norm_enabled (bool)

  • color_norm_method (Literal['gain', 'histogram'])

  • frame_start (int)

  • frame_stop (int | None)

  • frame_step (int)

  • extra_data (Any)

color_norm_enabled

Enable cross-camera color normalization.

Type:

bool

color_norm_method

Normalization method (“gain” or “histogram”).

Type:

Literal[‘gain’, ‘histogram’]

frame_start

First frame index to process.

Type:

int

frame_stop

Last frame index to process (None = end of video).

Type:

int | None

frame_step

Frame step interval (e.g., 100 = every 100th frame).

Type:

int

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

warn_extra_fields()[source]

Warn about unknown configuration keys.

Return type:

PreprocessingConfig

class aquamvs.SparseMatchingConfig(*, extractor_type='superpoint', max_keypoints=2048, detection_threshold=0.005, clahe_enabled=False, clahe_clip_limit=2.0, num_neighbors=4, include_center=True, filter_threshold=0.1, **extra_data)[source]

Configuration for sparse matching (extraction + pair selection + matching).

Consolidates FeatureExtractionConfig, PairSelectionConfig, and MatchingConfig.

Parameters:

  • extractor_type (Literal['superpoint', 'aliked', 'disk'])

  • max_keypoints (int)

  • detection_threshold (float)

  • clahe_enabled (bool)

  • clahe_clip_limit (float)

  • num_neighbors (int)

  • include_center (bool)

  • filter_threshold (float)

  • extra_data (Any)

extractor_type

Feature extractor backend.

Type:

Literal[‘superpoint’, ‘aliked’, ‘disk’]

max_keypoints

Maximum number of keypoints to extract per image.

Type:

int

detection_threshold

Detection confidence threshold.

Type:

float

clahe_enabled

Apply CLAHE preprocessing before feature detection.

Type:

bool

clahe_clip_limit

Contrast limit for CLAHE (higher = more enhancement).

Type:

float

num_neighbors

Number of nearest ring cameras to use as sources.

Type:

int

include_center

Whether to include the center (auxiliary) camera as a source.

Type:

bool

filter_threshold

Match confidence threshold for filtering.

Type:

float

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

warn_extra_fields()[source]

Warn about unknown configuration keys.

Return type:

SparseMatchingConfig

class aquamvs.DenseMatchingConfig(*, certainty_threshold=0.5, max_correspondences=100000, **extra_data)[source]

Configuration for RoMa v2 dense matching.

Parameters:

  • certainty_threshold (float)

  • max_correspondences (int)

  • extra_data (Any)

certainty_threshold

Minimum overlap certainty for correspondence extraction.

Type:

float

max_correspondences

Maximum number of correspondences to keep per pair.

Type:

int

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

warn_extra_fields()[source]

Warn about unknown configuration keys.

Return type:

DenseMatchingConfig

class aquamvs.ReconstructionConfig(*, num_depths=128, cost_function='ncc', window_size=11, depth_margin=0.05, depth_batch_size=4, min_consistent_views=3, depth_tolerance=0.005, roma_depth_tolerance=0.02, voxel_size=0.001, min_confidence=0.1, surface_method='poisson', poisson_depth=9, grid_resolution=0.002, bpa_radii=None, target_faces=None, outlier_removal_enabled=True, outlier_nb_neighbors=20, outlier_std_ratio=2.0, **extra_data)[source]

Configuration for reconstruction (stereo + fusion + surface + outliers).

Consolidates DenseStereoConfig, FusionConfig, SurfaceConfig, and OutlierRemovalConfig.

Parameters:

  • num_depths (int)

  • cost_function (Literal['ncc', 'ssim'])

  • window_size (int)

  • depth_margin (float)

  • depth_batch_size (int)

  • min_consistent_views (int)

  • depth_tolerance (float)

  • roma_depth_tolerance (float)

  • voxel_size (float)

  • min_confidence (float)

  • surface_method (Literal['poisson', 'heightfield', 'bpa'])

  • poisson_depth (int)

  • grid_resolution (float)

  • bpa_radii (list[float] | None)

  • target_faces (int | None)

  • outlier_removal_enabled (bool)

  • outlier_nb_neighbors (int)

  • outlier_std_ratio (float)

  • extra_data (Any)

num_depths

Number of depth hypotheses in plane sweep.

Type:

int

cost_function

Photometric cost function.

Type:

Literal[‘ncc’, ‘ssim’]

window_size

Local window size for cost computation (pixels, must be odd).

Type:

int

depth_margin

Margin added to sparse depth range [d_min, d_max] (meters).

Type:

float

depth_batch_size

Number of depth planes to process per batch in plane sweep (1 = no batching).

Type:

int

min_consistent_views

Minimum number of views that must agree for a point to survive.

Type:

int

depth_tolerance

Maximum depth disagreement for consistency (meters).

Type:

float

roma_depth_tolerance

Maximum depth disagreement for RoMa pairwise depth aggregation (meters).

Type:

float

voxel_size

Voxel grid cell size for deduplication (meters).

Type:

float

min_confidence

Minimum confidence threshold to consider a depth pixel.

Type:

float

surface_method

Surface reconstruction method.

Type:

Literal[‘poisson’, ‘heightfield’, ‘bpa’]

poisson_depth

Octree depth for Poisson reconstruction.

Type:

int

grid_resolution

Grid cell size for height-field interpolation (meters).

Type:

float

bpa_radii

List of ball radii for Ball Pivoting Algorithm (meters), or None to auto-estimate.

Type:

list[float] | None

target_faces

Target triangle count for mesh simplification (None = no simplification).

Type:

int | None

outlier_removal_enabled

Enable statistical outlier removal.

Type:

bool

outlier_nb_neighbors

Number of neighbors for mean distance calculation.

Type:

int

outlier_std_ratio

Standard deviation ratio threshold.

Type:

float

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_window_size(v)[source]

Validate that window_size is positive and odd.

Parameters:

v (int)

Return type:

int

warn_extra_fields()[source]

Warn about unknown configuration keys.

Return type:

ReconstructionConfig

class aquamvs.RuntimeConfig(*, device='cpu', save_features=False, keep_intermediates=True, save_consistency_maps=False, viz_enabled=False, viz_stages=<factory>, benchmark_extractors=<factory>, benchmark_clahe=<factory>, icp_max_distance=0.01, quiet=False, **extra_data)[source]

Configuration for runtime settings (device + output + viz + benchmark + evaluation).

Consolidates DeviceConfig, OutputConfig, VizConfig, BenchmarkConfig, and EvaluationConfig.

Depth maps, point clouds, and meshes are always saved (no toggle).

Parameters:
device

PyTorch device string.

Type:

Literal[‘cpu’, ‘cuda’]

save_features

Save features and matches (.pt files).

Type:

bool

keep_intermediates

Keep depth maps after fusion.

Type:

bool

save_consistency_maps

Save consistency maps as colormapped PNG + NPZ.

Type:

bool

viz_enabled

Master switch for all visualization.

Type:

bool

viz_stages

List of visualization stages to run.

Type:

list[str]

benchmark_extractors

List of extractor backends to sweep.

Type:

list[str]

benchmark_clahe

List of CLAHE on/off settings to sweep.

Type:

list[bool]

icp_max_distance

ICP correspondence distance threshold (meters).

Type:

float

quiet

Suppress progress output.

Type:

bool

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

classmethod validate_viz_stages(v)[source]

Validate that all viz_stages are valid.

Parameters:

v (list[str])

Return type:

list[str]

classmethod validate_benchmark_extractors(v)[source]

Validate that all benchmark_extractors are valid.

Parameters:

v (list[str])

Return type:

list[str]

warn_extra_fields()[source]

Warn about unknown configuration keys.

Return type:

RuntimeConfig