aquamvs 1.3.1

Multi-view stereo reconstruction of underwater surfaces with refractive modeling

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

from aquamvs import Pipeline

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

See the full documentation for configuration details, API reference, and examples.

Installation

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

See INSTALL.md for complete installation instructions.

Quick summary:

# 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/

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 for details.