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.
- Snell's law refractive projection — Accurate ray-tracing through air-water interfaces
- Multi-camera pose graph — BFS-based 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
pip install aquacal-
Install AquaCal:
pip install aquacal
-
Generate a configuration file from your calibration videos:
aquacal init --intrinsic-dir videos/intrinsic/ --extrinsic-dir videos/extrinsic/
-
Run calibration:
aquacal calibrate config.yaml
Results are saved to output/calibration.json with camera intrinsics, extrinsics, interface distances, and diagnostics.
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
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 = {1.7.0},
doi = {10.5281/zenodo.18644658}
}See CITATION.cff for full citation metadata.
We welcome contributions! See CONTRIBUTING.md for guidelines.
MIT License. See LICENSE for details.