Metadata-Version: 2.4
Name: aquacal
Version: 1.3.2
Summary: Refractive multi-camera calibration for underwater arrays with Snell's law modeling
Author: Tucker Lancaster
License: MIT
Project-URL: Homepage, https://github.com/tlancaster6/AquaCal
Project-URL: Documentation, https://aquacal.readthedocs.io
Project-URL: Repository, https://github.com/tlancaster6/AquaCal
Project-URL: Issues, https://github.com/tlancaster6/AquaCal/issues
Project-URL: Changelog, https://github.com/tlancaster6/AquaCal/blob/main/CHANGELOG.md
Keywords: calibration,multi-camera,underwater,refraction,computer-vision,charuco
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: opencv-python>=4.6
Requires-Dist: pyyaml
Requires-Dist: matplotlib
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: tqdm
Requires-Dist: natsort>=8.4.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: python-semantic-release; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=6.2; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: nbsphinx>=0.9.8; extra == "docs"
Dynamic: license-file

# AquaCal

![AquaCal ray trace](docs/_static/hero_ray_trace.png)

![Build](https://img.shields.io/github/actions/workflow/status/tlancaster6/AquaCal/test.yml?branch=main&label=build) ![Coverage](https://img.shields.io/codecov/c/github/tlancaster6/AquaCal?label=coverage) ![PyPI](https://img.shields.io/pypi/v/aquacal) ![Python](https://img.shields.io/pypi/pyversions/aquacal) ![License](https://img.shields.io/github/license/tlancaster6/AquaCal) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18644658.svg)](https://doi.org/10.5281/zenodo.18644658)

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.

## :construction: Status :construction:
**02/17/26: This project is under active and rapid development.**
The API and internal structure are subject to frequent breaking changes without notice. It is not yet recommended for
production use. A stable release is planned by the end of the month. This section will be updated accordingly once that
milestone is reached.

## Features

- **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

## Installation

```bash
pip install aquacal
```

## Quick Start

1. Install AquaCal:
   ```bash
   pip install aquacal
   ```

2. Generate a configuration file from your calibration videos:
   ```bash
   aquacal init --intrinsic-dir videos/intrinsic/ --extrinsic-dir videos/extrinsic/
   ```

3. Run calibration:
   ```bash
   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](https://aquacal.readthedocs.io):

- **[Overview](https://aquacal.readthedocs.io/en/latest/overview.html)** — What is refractive calibration and when do you need it?
- **[User Guide](https://aquacal.readthedocs.io/en/latest/guide/index.html)** — Theory, methodology, and coordinate conventions
- **[API Reference](https://aquacal.readthedocs.io/en/latest/api/index.html)** — Detailed module and function documentation
- **[Tutorials](https://aquacal.readthedocs.io/en/latest/tutorials/index.html)** — Interactive Jupyter notebook examples
- **[Configuration Reference](https://aquacal.readthedocs.io/en/latest/api/config.html)** — YAML config schema and options

## Citation

If you use AquaCal in your research, please cite:

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

See [CITATION.cff](CITATION.cff) for full citation metadata.

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License. See [LICENSE](LICENSE) for details.
