Metadata-Version: 2.4
Name: aquamvs
Version: 1.3.1
Summary: Multi-view stereo reconstruction of underwater surfaces with refractive modeling
Author: Tucker Lancaster
License: MIT
Project-URL: Repository, https://github.com/tlancaster6/AquaMVS
Keywords: multi-view-stereo,underwater,refraction,computer-vision,depth-estimation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
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: kornia>=0.7.0
Requires-Dist: open3d>=0.18.0
Requires-Dist: opencv-python>=4.6.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: aquacal>=0.1.0
Requires-Dist: lightglue
Requires-Dist: romav2
Requires-Dist: pydantic>=2.12.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: tabulate>=0.9.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: sphinx; extra == "dev"
Requires-Dist: furo; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid; extra == "dev"
Requires-Dist: myst-nb; extra == "dev"
Requires-Dist: nbformat; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: python-semantic-release; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

![AquaMVS reconstruction - multi-view stereo reconstruction of underwater surfaces](docs/_static/hero.png)

[![PyPI](https://img.shields.io/pypi/v/aquamvs)](https://pypi.org/project/aquamvs/)
[![Python](https://img.shields.io/pypi/pyversions/aquamvs)](https://pypi.org/project/aquamvs/)
[![CI](https://github.com/tlancaster6/AquaMVS/actions/workflows/test.yml/badge.svg)](https://github.com/tlancaster6/AquaMVS/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

# AquaMVS

Multi-view-stereo (MVS) reconstruction of underwater surfaces viewed through a flat water surface, with Snell's law refraction modeling.

## :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.

## What it does

AquaMVS is a companion library to [AquaCal](https://github.com/tlancaster6/AquaCal). It consumes calibration output and synchronized video from above-water cameras to produce time-series 3D surface reconstructions. The pipeline handles the unique challenge of cameras positioned in air observing underwater geometry, accounting for refraction at the air-water interface using Snell's law.

## Key Features

- **Refractive ray casting** through air-water interface (Snell's law)
- **Dual matching pathways**: LightGlue (sparse) and RoMa v2 (dense) for different accuracy/speed tradeoffs
- **Multi-view depth fusion** with geometric consistency filtering
- **Surface reconstruction** (Poisson, heightfield, Ball Pivoting Algorithm)
- **Mesh export** (PLY, OBJ, STL, GLTF) with simplification
- **Full CLI and Python API** for pipeline users and custom workflow developers

## Quick Start

```python
from aquamvs import Pipeline

pipeline = Pipeline("config.yaml")
pipeline.run()
```

See the [full documentation](https://aquamvs.readthedocs.io/) for configuration details, API reference, and examples.

## Installation

AquaMVS requires several prerequisites (PyTorch, LightGlue, RoMa v2) to be installed first.

**See [INSTALL.md](INSTALL.md) for complete installation instructions.**

Quick summary:
```bash
# 1. Install PyTorch from pytorch.org
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 2. Install git-based prerequisites
pip install -r requirements-prereqs.txt

# 3. Install AquaMVS
pip install aquamvs
```

## Documentation

Full documentation is available at [https://aquamvs.readthedocs.io/](https://aquamvs.readthedocs.io/)

Topics include:
- Installation guide
- Configuration reference
- API documentation
- Usage examples
- Extension points for custom workflows

## Citation

If you use AquaMVS in your research, please cite:

```
Lancaster, T. (2026). AquaMVS: Multi-view stereo reconstruction with refractive geometry.
GitHub: https://github.com/tlancaster6/AquaMVS
Example dataset: https://github.com/tlancaster6/AquaMVS/releases/tag/v0.1.0-example-data
```

A Zenodo DOI will be added in a future release.

## License

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