The Problem
Dense feature matching for high‑resolution image pairs remains computationally heavy and often yields sparse, noisy correspondences. Existing pipelines either sacrifice speed or accuracy, which hampers downstream tasks such as 3D reconstruction or SLAM in production systems.
What This Does
RoMaV2 implements the “Harder Better Faster Denser” matching algorithm introduced in the accompanying paper (see README.md). The core library lives under src/romav2/, with the main entry point in src/romav2/romav2.py exposing the RoMaV2 class. Supporting modules provide:
Vision Transformer backbone – src/romav2/vit/.py (attention, patch embedding, rope, etc.). Matching pipeline – src/romav2/matcher.py, src/romav2/localcorrelation.py, and src/romav2/refiner.py. Benchmark definitions – src/romav2/benchmarks/.py (Mega1500, ScanNet1500, etc.).
Utility functions for I/O (io.py), geometry (geometry.py), and visualization (vis.py) are also bundled, enabling end‑to‑end use without external glue code.
How To Use It
Setup
The project uses uv for dependency management, declared in pyproject.toml. Install in an editable environment:
Create a virtualenv (optional)
python -m venv .venv && source .venv/bin/activate
Install the package and its optional fused‑local‑corr kernel
uv pip install -e .[fused-local-corr] or equivalently uv sync --extra fused-local-corr
The repository includes a GitHub Actions CI (.github/workflows/.yml) that runs the test suite on push.
Configuration
No external configuration files are required for basic operation. Benchmark datasets are fetched by the helper script scripts/evalprep.sh, which populates the data/ directory. Ensure the script runs successfully before executing benchmark tests.
Running it
Typical usage is demonstrated in demo/demomatch.py:
from romav2 import RoMaV2
model = RoMaV2() # loads pretrained weights matches, overlaps, pAB, pBA = model.sample( model.match("imgA.png", "imgB.png"), 5000 ) kptsA, kptsB = model.topixelcoordinates( matches, HA, WA, HB, WB )
For a quick sanity check, run the provided smoke test:
uv run tests/testsmoke.py
Benchmarks can be reproduced with:
uv run tests/testmega1500.py # MegaDepth‑1500 uv run tests/testscannet1500.py # ScanNet‑1500
Real‑World Use
In a SLAM pipeline, replace the traditional SIFT/ORB matcher with RoMaV2:
from romav2 import RoMaV2 matcher = RoMaV2() densecorr = matcher.match(framei, framej) ptsi, ptsj = matcher.topixelcoordinates(densecorr, framei.shape[:2], framej.shape[:2]) F, mask = cv2.findFundamentalMat( ptsi.cpu().numpy(), ptsj.cpu().numpy(), method=cv2.USAC_MAGSAC, ransacReprojThreshold=0.2 ) Feed F into the pose estimator
The dense correspondences improve pose hypothesis robustness while the optional fused‑local‑corr kernel accelerates inference on GPUs.
Code Health & Issues
Low – Missing lockfile – Dependencies are listed only in pyproject.toml; no uv.lock or requirements.txt makes reproducible builds harder. Low – Limited test coverage – 5 test files exist, but they focus on benchmarks and a smoke test; core modules (matcher.py, refiner.py) lack unit tests for edge cases. Low – Optional license nuance – LICENSE states MIT for most code, but DINOv3 components have a separate license; the repo does not ship the DINOv3 source, which could cause redistribution ambiguity. Low – No explicit Python version pin – .python-version exists but the code does not enforce a version; the README mentions Python 3.12, but CI does not verify it. Low – No type‑checking enforcement – src/romav2/types.py defines type aliases, yet the project lacks a mypy configuration or CI step to enforce static typing.
Overall, the repository compiles cleanly, CI runs the test suite, and documentation (README, demo scripts) is sufficient for a developer to get started.
The Bottom Line
RoMaV2 provides a ready‑to‑use dense matcher with competitive accuracy and optional GPU‑accelerated kernels. It is suitable for research prototypes and production pipelines that can accommodate a Python‑centric stack. The main drawbacks are the absence of a lockfile and limited unit testing, so teams should add their own reproducibility safeguards and test coverage before deploying at scale.