vismatch – A Unified Python Library for Image‑Matching Models

🎯 What it does

vismatch provides a single, easy‑to‑use Python API (and a small CLI) that wraps 50+ image‑matching methods – from classic keypoint detectors like SIFT to modern deep‑learning matchers such as LoFTR, SuperPoint‑LightGlue, DeDoDe, SphereGlue, etc. The library handles:

Downloading model weights automatically (via Hugging Face or the authors’ releases).
Loading and preprocessing images (optional resizing).
Running matching (producing keypoint correspondences, homographies, inlier counts, confidence scores).
Extracting raw keypoints & descriptors.
Visualising results with ready‑made plot_matches and plot_keypoints helpers.

All of this is exposed through a single function get_matcher(name, device=…) so you can swap models with a one‑liner.

🛠️ How to get started

# Recommended: uv (fast installer) – pip works as well
pip install uv               # install uv if you don’t have it
uv venv                      # create a virtual environment
source .venv/bin/activate    # activate it
uv pip install vismatch       # install the library

Optional: install extra dependencies for models that need them (e.g., torch‑geometric, tensorflow):

uv pip install "[all]"   # or pip install .[all]

💻 Quick code example

from vismatch import get_matcher
from vismatch.viz import plot_matches

# Choose any of the 50+ matchers – here SuperPoint‑LightGlue on GPU
matcher = get_matcher("superpoint-lightglue", device="cuda")

# Load and optionally resize images
img0 = matcher.load_image("vismatch/assets/example_pairs/outdoor/montmartre_close.jpg", resize=512)
img1 = matcher.load_image("vismatch/assets/example_pairs/outdoor/montmartre_far.jpg",   resize=512)

# Run matching
result = matcher(img0, img1)
# result contains keys like: num_inliers, H, all_kpts0, all_kpts1, matched_kpts0, …

# Visualise the matches
plot_matches(img0, img1, result, save_path="plot_matches.png")

The same workflow works for keypoint extraction via matcher.extract(img) and plot_keypoints.

📦 Command‑line interface (CLI)

The package ships tiny helper scripts that can be called directly after installation:

# Matching two images
vismatch-match \
    --matcher superpoint-lightglue \
    --out-dir outputs/sp-lg \
    --input img0.jpg img1.jpg

# Extracting keypoints from a folder
vismatch-extract \
    --matcher superpoint-lightglue \
    --out-dir outputs/sp-lg \
    --input path/to/images/

The CLI accepts single images, directories, or text files listing image pairs.

📚 Model catalogue

The library groups the supported methods into three families:

Dense – e.g., roma, tiny-roma, duster.
Semi‑dense – e.g., loftr, eloftr, matchformer.
Sparse – classic + modern keypoint‑based pipelines such as sift-lightglue, superpoint-lightglue, disk-lightglue, dedode, sphereglue, zippypoint, etc.

A full list with runtime, device support, source repo, and license details lives in the Model Details documentation page.

🤝 Contributing / Extending

If you have a new matcher, the repo provides a CONTRIBUTING guide. The design follows PyTorch’s “usability over performance” principle: the goal is a clean, consistent API rather than squeezing out every last millisecond.

📖 Documentation & Resources

ReadTheDocs – https://vismatch.readthedocs.io/en/latest/
Colab demo – ready‑to‑run notebook linked from the README.
Hugging Face model hub – all wrapped weights are hosted under the vismatch organization.
Download statistics – live tracker shows daily HF model downloads.

📜 Citation

If you use vismatch in research, cite the accompanying EarthMatch paper (CVPR 2024 Workshop) as shown in the README.

TL;DR

vismatch is a real, production‑ready Python package that unifies a large collection of image‑matching algorithms behind a single, beginner‑friendly interface, making it trivial to experiment with, benchmark, or integrate state‑of‑the‑art visual correspondence methods.

gmberton/vismatch