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. The API is considered stable; breaking changes will follow semantic versioning.

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

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

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/McGrathLab/AquaMVS
Example dataset: https://doi.org/10.5281/zenodo.18702024

License

AquaMVS is released under the MIT License. See LICENSE for details.

Third-party components and commercial use

AquaMVS vendors no third-party source code or model weights; all optional components are installed separately at the user's request. The out-of-the-box configuration is fully MIT/permissive: the default matcher is RoMa v2 (MIT) and the default feature extractor is ALIKED (BSD-3-Clause).

The optional SuperPoint extractor (reachable via LightGlue by setting extractor_type: superpoint) is provided under Magic Leap's non-commercial academic-research-only license. It is not a default. Commercial users should select ALIKED (BSD-3) or DISK (Apache-2.0) instead of SuperPoint.

See THIRD_PARTY_LICENSES.md for the full breakdown.