CLI Reference

AquaCal provides three command-line tools for calibration workflows. All values are in meters.

aquacal calibrate

Run the complete calibration pipeline from a configuration file.

Syntax:

aquacal calibrate <config_path> [options]

Arguments:

Argument	Type	Description
config_path	Path	Path to configuration YAML file (required)

Options:

Flag	Description
-v, --verbose	Enable verbose output showing optimizer iteration details
-o, --output-dir PATH	Override the output directory specified in config
--dry-run	Validate configuration file without running calibration

Examples:

# Run calibration with default settings
aquacal calibrate config.yaml

# Run with verbose output to see optimizer progress
aquacal calibrate config.yaml -v

# Validate config without running calibration
aquacal calibrate config.yaml --dry-run

# Override output directory
aquacal calibrate config.yaml -o /path/to/output

Exit Codes:

• 0: Success

• 1: File not found or I/O error

• 2: Invalid configuration

• 3: Calibration failed (e.g., insufficient data, optimization divergence)

• 130: User interrupt (Ctrl+C)

---

aquacal init

Generate a configuration file by scanning video directories.

Syntax:

aquacal init --intrinsic-dir PATH --extrinsic-dir PATH [options]

Required Options:

Flag	Type	Description
--intrinsic-dir PATH	Path	Directory containing in-air calibration videos
--extrinsic-dir PATH	Path	Directory containing underwater calibration videos

Optional Flags:

Flag	Default	Description
-o, --output PATH	config.yaml	Output path for generated config file
--pattern REGEX	(.+)	Regex with one capture group to extract camera name from filename stem

How It Works:

1. Scans both directories for video files (.mp4, .avi, .mov, .mkv)

2. Extracts camera names from filenames using the regex pattern (default: entire filename stem)

3. Matches cameras between intrinsic and extrinsic directories

4. Generates a config YAML with placeholder board parameters and matched video paths

Examples:

# Basic usage with default pattern
aquacal init --intrinsic-dir videos/in_air --extrinsic-dir videos/underwater

# Extract camera names from filenames like "camera_cam0_inair.mp4" → "cam0"
aquacal init --intrinsic-dir in_air/ --extrinsic-dir underwater/ --pattern "camera_(.+)_"

# Custom output path
aquacal init --intrinsic-dir in_air/ --extrinsic-dir underwater/ -o my_config.yaml

Camera Name Extraction:

The --pattern regex must have exactly one capture group. For example:

Filename	Pattern	Extracted Name
cam0.mp4	(.+)	cam0
camera_cam0_inair.mp4	camera_(.+)_inair	cam0
2024-01-15_cam0.mp4	[0-9-]+_(.+)	cam0

Exit Codes:

• 0: Success

• 1: Directory not found, no videos found, no common cameras, or invalid regex pattern

---

aquacal compare

Compare multiple calibration runs and generate diagnostic reports.

Syntax:

aquacal compare <dir1> <dir2> [dir3 ...] [options]

Arguments:

Argument	Type	Description
directories	Paths	Two or more directories containing calibration.json files (minimum 2)

Options:

Flag	Default	Description
-o, --output-dir PATH	comparison_output	Output directory for comparison results
--no-plots	False	Skip PNG plot generation (only generate CSV files)

Output Files:

The command generates:

• metrics.csv — Overall metrics (RMS, camera counts) for each run

• per_camera.csv — Per-camera metrics across all runs

• parameter_diffs.csv — Pairwise differences in extrinsics and water_z

• rms_bar_chart.png — Bar chart comparing RMS reprojection errors

• position_overlay.png — 3D scatter plot of camera positions across runs

• z_position_dumbbell.png — Camera Z-positions with connecting lines between runs

• depth_error_plot.png — (if spatial_measurements.csv exists) Error vs. depth analysis

• depth_binned.csv — (if spatial data available) Binned error statistics

Examples:

# Compare two calibration runs
aquacal compare output_run1/ output_run2/

# Compare three runs with custom output directory
aquacal compare run1/ run2/ run3/ -o comparison_results/

# Generate only CSV files (no plots)
aquacal compare run1/ run2/ --no-plots

Exit Codes:

• 0: Success

• 1: Directory not found, calibration.json missing, or I/O error

• 2: Comparison failed (e.g., incompatible camera sets)

---

Global Options

Flag	Description
--version	Display AquaCal version and exit

Example:

aquacal --version
# Output: aquacal 0.1.0

---

Configuration File Format

All three commands work with YAML configuration files. The init command generates a template config with:

• board: ChArUco board parameters (squares_x, squares_y, square_size, marker_size, dictionary)

• cameras: List of camera names (first camera is the reference camera, world origin)

• paths: Intrinsic and extrinsic video paths per camera

• interface: Refractive indices and optional initial water_z estimates

• optimization: Robust loss settings, max frames, intrinsic refinement flags

• detection: Corner detection thresholds and frame sampling

• validation: Holdout fraction for validation set

After running init, you must edit the generated config to:

1. Set accurate board dimensions (measure your physical board)

2. Optionally add initial_water_z estimates per camera (improves Stage 3 initialization)

3. Configure auxiliary_cameras, rational_model_cameras, or fisheye_cameras if needed

See the User Guide for detailed explanations of calibration theory and the API Reference for programmatic usage.