Calibration¶

class aquamvs.CalibrationData(cameras, water_z, interface_normal, n_air, n_water)[source]¶

Complete calibration data converted to PyTorch tensors.

Parameters:

cameras (dict[str, CameraData])
water_z (float)
interface_normal (Tensor)
n_air (float)
n_water (float)

cameras¶

Per-camera calibration data, keyed by camera name.

Type:: dict[str, aquamvs.calibration.CameraData]

water_z¶

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

Type:: float

interface_normal¶

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

Type:: torch.Tensor

n_air¶

Refractive index of air.

Type:: float

n_water¶

Refractive index of water.

Type:: float

property ring_cameras: list[str]¶

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

Returns:: List of camera names where is_auxiliary=False, sorted alphabetically.

property auxiliary_cameras: list[str]¶

Names of auxiliary cameras (sorted for determinism).

Returns:: List of camera names where is_auxiliary=True, sorted alphabetically.

camera_positions()[source]¶

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,), same dtype as R and t.
Return type:: dict[str, Tensor]

class aquamvs.CameraData(name, K, dist_coeffs, R, t, image_size, is_fisheye, is_auxiliary)[source]¶

Per-camera calibration data as PyTorch tensors.

Parameters:

name (str)
K (Tensor)
dist_coeffs (Tensor)
R (Tensor)
t (Tensor)
image_size (tuple[int, int])
is_fisheye (bool)
is_auxiliary (bool)

name¶

Camera identifier (e.g., “e3v82e0”).

Type:: str

K¶

Intrinsic matrix, shape (3, 3), float32.

Type:: torch.Tensor

dist_coeffs¶

Distortion coefficients, shape (N,), float64. Pinhole: N=5 or N=8. Fisheye: N=4.

Type:: torch.Tensor

R¶

Rotation matrix (world to camera), shape (3, 3), float32.

Type:: torch.Tensor

t¶

Translation vector (world to camera), shape (3,), float32.

Type:: torch.Tensor

image_size¶

Image dimensions as (width, height) in pixels.

Type:: tuple[int, int]

is_fisheye¶

Whether this camera uses the fisheye lens model.

Type:: bool

is_auxiliary¶

Whether this is an auxiliary camera (center camera).

Type:: bool

aquamvs.load_calibration_data(calibration_path)[source]¶

Load AquaCal calibration and convert to PyTorch tensors.

Parameters:

calibration_path (str | Path) – Path to AquaCal calibration JSON file.

Returns:

CalibrationData with all parameters as PyTorch tensors.

Raises:

FileNotFoundError – If calibration file does not exist.
ValueError – If calibration file format is invalid.

Return type:

CalibrationData

aquamvs.compute_undistortion_maps(camera)[source]¶

Compute undistortion remap tables and updated intrinsic matrix.

Dispatches between standard pinhole and fisheye OpenCV paths based on the camera’s lens model.

Parameters:: camera (CameraData) – Per-camera calibration data from load_calibration_data().
Returns:: Precomputed undistortion data for use with undistort_image().
Return type:: UndistortionData