AquaCal

Refractive multi-camera calibration for underwater arrays. AquaCal calibrates cameras in air viewing through a flat water surface, using Snell's law to achieve accurate 3D reconstruction in refractive environments.

Features

• Snell's law refractive projection — Accurate ray-tracing through air-water interfaces
• Multi-camera pose graph — Best-first extrinsic initialization for camera arrays
• Joint bundle adjustment — Simultaneous optimization of extrinsics, interface distances, and board poses
• Sparse Jacobian optimization — Scalable to 10+ cameras with column grouping
• ChArUco board detection — Robust corner detection for calibration targets
• Validation diagnostics — Holdout reprojection, 3D triangulation checks, and per-camera error breakdowns
• Active re-calibration (beta) — refine_calibration() updates an existing calibration from point correspondences collected in the field; not yet fully tested

Installation

pip install aquacal

Quick Start

1. Install AquaCal:

   pip install aquacal
   

2. Generate a configuration file from your calibration videos:

   aquacal init --intrinsic-dir videos/intrinsic/ --extrinsic-dir videos/extrinsic/
   

3. Run calibration:

   aquacal calibrate config.yaml
   

Results are saved to output/calibration.json with camera intrinsics, extrinsics, interface distances, and diagnostics.

Documentation

Full documentation is available at aquacal.readthedocs.io:

• Overview — What is refractive calibration and when do you need it?
• User Guide — Theory, methodology, and coordinate conventions
• API Reference — Detailed module and function documentation
• Tutorials — Interactive Jupyter notebook examples
• Configuration Reference — YAML config schema and options

Citation

If you use AquaCal in your research, please cite:

@software{aquacal,
  title = {AquaCal: Refractive Multi-Camera Calibration},
  author = {Lancaster, Tucker},
  year = {2026},
  url = {https://github.com/McGrathLab/AquaCal},
  version = {2.0.0},
  doi = {10.5281/zenodo.18644658}
}

See CITATION.cff for full citation metadata.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License. See LICENSE for details.