AquaCal

Build Coverage PyPI Python License

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

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.

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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

aquacal-2.1.0.tar.gz (200.7 kB view details)

Uploaded Aug 27, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

aquacal-2.1.0-py3-none-any.whl (222.1 kB view details)

Uploaded Aug 27, 2026 Python 3

File details

Details for the file aquacal-2.1.0.tar.gz.

File metadata

Download URL: aquacal-2.1.0.tar.gz
Upload date: Aug 27, 2026
Size: 200.7 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for aquacal-2.1.0.tar.gz
Algorithm	Hash digest
SHA256	`82ec27a24df85c1237f1afc513d30e824f92d92f9881ac707f63ba30eedb15d6`
MD5	`c416f7fb422a59dd6e0559976f43550d`
BLAKE2b-256	`8bbafead2ae18e5e8c08ded7620c00ff16941098b7bf9e9495b141cfbffbe103`

See more details on using hashes here.

Provenance

The following attestation bundles were made for aquacal-2.1.0.tar.gz:

Publisher: publish.yml on McGrathLab/AquaCal

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: aquacal-2.1.0.tar.gz
- Subject digest: 82ec27a24df85c1237f1afc513d30e824f92d92f9881ac707f63ba30eedb15d6
- Sigstore transparency entry: 2618907735
- Sigstore integration time: Aug 27, 2026
Source repository:
- Permalink: McGrathLab/AquaCal@d777e8fab2c5ade1e07ab306ea05919c2662d5f3
- Branch / Tag: refs/tags/v2.1.0
- Owner: https://github.com/McGrathLab
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@d777e8fab2c5ade1e07ab306ea05919c2662d5f3
- Trigger Event: push