Metadata-Version: 2.4
Name: aquamvs
Version: 1.5.2
Summary: Multi-view stereo reconstruction of underwater surfaces with refractive modeling
Author: Tucker Lancaster
License-Expression: MIT
Project-URL: Repository, https://github.com/tlancaster6/AquaMVS
Project-URL: Documentation, https://aquamvs.readthedocs.io/
Project-URL: Bug Tracker, https://github.com/tlancaster6/AquaMVS/issues
Project-URL: Changelog, https://github.com/tlancaster6/AquaMVS/blob/main/CHANGELOG.md
Keywords: multi-view-stereo,underwater,refraction,computer-vision,depth-estimation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Image Recognition
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: pydantic>=2.12.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: tabulate>=0.9.0
Requires-Dist: aquacal>=0.1.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

<table>
  <tr>
    <td><img src="docs/_static/tank_image.jpg" alt="Experimental setup" width="480"></td>
    <td><img src="docs/_static/orbit.gif" alt="3D surface reconstruction" width="480"></td>
  </tr>
</table>

[![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)
[![Dataset DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18702024.svg)](https://doi.org/10.5281/zenodo.18702024)

# AquaMVS

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

## Status
**v1.3.5 released.** AquaMVS is feature-complete for the v1.0 milestone and available on [PyPI](https://pypi.org/project/aquamvs/). The API is considered stable; breaking changes will follow semantic versioning.

## 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. AquaCal is installed automatically as a dependency.

**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 (LightGlue, RoMa v2)
pip install -r requirements-prereqs.txt

# 3. Install AquaMVS (pulls AquaCal automatically)
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://doi.org/10.5281/zenodo.18702024
```

## License

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