vismatch: one interface over fifty local feature matching models

The point is comparison, not conversion

The package describes itself as a unified API for quickly and easily trying 50+ and growing image matching models, and the repository description says wrapper of 50+ image matching models with a unified interface.

The problem it solves is specific. Local feature matching, the technology behind feature detection, image registration and visual localization, has accumulated a large number of independent implementations. Each has its own way of loading images, its own way of returning keypoints and descriptors, its own way of reporting a homography, and its own idea of what a confidence score means. A researcher who wants to know whether a new matcher beats SIFT on a particular set of photographs has, in the absence of a wrapper, an integration problem before they have a research problem.

vismatch removes that integration problem. The topic list on the project record names the scope precisely: feature-matching, image-matching, image-registration, local-features and visual-localization.

The comparison framing is also visible in the example gallery, which is not a set of marketing screenshots but a controlled comparison. The README shows SIFT-LightGlue and LoFTR matches on the same image pairs, over six scene types: outdoor, indoor, satellite remote sensing, paintings, a false positive, and spherical. Including the false positive case in a comparison gallery is a good sign, because it is the case that distinguishes a matcher that works from one that appears to work. There is a second gallery for extraction, showing SIFT and DeDoDe keypoints side by side.

So the library is a research instrument. Its value is that a benchmark you write against it is a benchmark of the models rather than of your integration code.

One call returns one dictionary, whatever the model underneath

The Python API is short enough to read in one go, and the important part is the result object.

from vismatch import get_matcher
from vismatch.viz import plot_matches, plot_keypoints

matcher = get_matcher("superpoint-lightglue", device="cuda")
img_size = 512  # optional

img0 = matcher.load_image("vismatch/assets/example_pairs/outdoor/montmartre_close.jpg", resize=img_size)
img1 = matcher.load_image("vismatch/assets/example_pairs/outdoor/montmartre_far.jpg", resize=img_size)

result = matcher(img0, img1)

The result dictionary has a fixed key set across models, and the README lists them: num_inliers, H, all_kpts0, all_kpts1, all_desc0, all_desc1, matched_kpts0, matched_kpts1, inlier_kpts0, inlier_kpts1 and matched_confidences. That uniformity is the whole product. H is the homography, the matched and inlier keypoint sets let you draw the correspondences that survived the geometric check, the descriptor arrays let you re-run the matching yourself, and num_inliers gives you the number a paper would report.

Note what is not in the list. There is no per-model timing, no training curve, and no parameter sweep structure. The interface is deliberately narrow: load an image, call the matcher, read a dictionary.

The extraction path has the same shape. The result of matcher.extract(img0) has two keys, all_kpts0 and all_desc0, and the visualisation helper plot_keypoints takes that result and a save path. And the match path has plot_matches, which takes the images, the result and a save_path and produces the annotated image seen in the gallery.

The device argument and the resize parameter on load_image are the two knobs on the front door, and the resize is applied at load time, which matters because the models expect particular input sizes and a resized image is cheaper to run through a neural network.

Weights are downloaded for you, and the optional extras are the real dependency list

All model weights are automatically downloaded by vismatch, which removes the usual friction of these models, where each repository has its own checkpoint download step.

The installation is documented in two forms, a plain install from PyPI and a development install from a clone. The recommended path uses uv:

pip install uv             # install uv
uv venv                    # create uv venv
source .venv/bin/activate  # activate uv venv
uv pip install vismatch
# or, if you don't want to use uv
pip install vismatch

The development path clones the repository recursively, which matters because there is a .gitmodules file and the recursive flag is needed to pull the submodules:

# Clone recursively
git clone --recursive https://github.com/gmberton/vismatch
cd vismatch

uv venv                    # create uv venv
source .venv/bin/activate  # activate uv venv
# editable install for dev work
uv pip install -e . 
# or non-editable install
uv pip install .

The extras are where the real weight sits. Some models require additional optional dependencies which are not included in the default list, and the documentation names torch-geometric as required by SphereGlue and tensorflow/larq as required by OmniGlue and ZippyPoint. To install them:

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

The pyproject manifest defines the extras explicitly, and the naming tells you what each one costs. The omniglue extra is tensorflow. The sphereglue extra is torch-geometric and torch-cluster. The zippypoint extra is tensorflow pinned to a narrow range, keras below 3, and larq. And the all extra is a composition of the first two plus zippypoint, but with a Python version condition, since the zippypoint extra is only pulled in for python_version below 3.12.

That version condition is the detail to notice. On Python 3.12 and above, installing the all extra does not give you ZippyPoint, because the pinned tensorflow and keras combination it needs is not available there. If your environment is 3.12 or 3.13, which the classifiers say are supported, that extra will silently not include the model you were expecting.

The base requirements pull in three heavyweight stacks

The requirements file is the honest description of what you are installing, and it is long.

The base set includes torch at 2.0 or newer and torchvision at 0.15 or newer, so PyTorch is not optional, and opencv-python at 4.5.4 or newer for the image handling. Then matplotlib for plotting, and kornia pinned below 0.8.3 with an explicit comment explaining why: version 0.8.3 removed kornia.utils.grid, used by LoFTR and others. That comment is the kind of detail that tells you the requirements were maintained by running the code, not by guessing.

The rest of the list is the accumulated dependencies of fifty models. einops, transforms3d, kornia_moons, yacs, gdown, huggingface_hub, packaging, safetensors, imageio, tensorboard, scipy, trimesh, e2cnn, scikit-learn, scikit-image, tqdm, py3_wget, roma, loguru, timm, omegaconf, poselib, lightning, flow_vis, uniception and h5py are all there, with inline comments identifying two of them as being for specific models: lightning is for EDM and RIPE, flow_vis is for UFM, and uniception is also for UFM.

That last group is the reason the extras exist as well as the base list. Rather than depending on TensorFlow in the base install, only the models that need it declare it, which is a sensible structure. The cost is that the base install is still large, because PyTorch and OpenCV are needed by most of the fifty models regardless.

The package metadata is modern in other ways. The build backend is setuptools with setuptools-scm, so the version is derived from the git tags and written to vismatch/_version.py, and the version and the dependencies are both listed as dynamic. The package requires Python 3.10 or newer, and the classifiers list 3.10 through 3.13 with a development status of Beta.

The maintainers are listed as Alex Stoken and Gabriele Berton, with Gabriele Trivigno of Politecnico di Torino as an author, and the project is hosted on PyPI with a Hugging Face organisation for the models and a readthedocs site for the documentation.

There is a command line for the same operations

The API is not the only entry point. The documentation describes a command line interface and standalone scripts, giving the same results as the Python API, and the repository listing shows the scripts themselves at the top level: vismatch_match.py, vismatch_extract.py and vismatch_test.py.

That is a small design decision with a large effect on how the library is used. A researcher who wants to run a matcher over a directory of image pairs does not have to write a script, and a script is exactly the thing you do not want to write fifty times. It also means the comparison in a paper can be reproduced by someone who does not read Python.

The three scripts cover the three operations the API exposes, matching, extraction and testing, which is a clean mapping. The vismatch_test.py name suggests it runs the models against a test set, which is how you would build the comparison the library is for in the first place.

The package also ships a Colab notebook, demo.ipynb at the repository root, linked from the README with an Open In Colab badge. A hosted notebook for an image matching library is a strong signal about the intended audience: this is a library for experimentation, and the fastest path from curiosity to a working comparison is a notebook that downloads weights and runs.

There is also a downloads tracker, hosted on GitHub Pages, with badges for both PyPI downloads per month and Hugging Face downloads per month. The presence of a download counter is itself a detail about the project: it treats usage as a quantity worth tracking, which is what you would expect from something whose purpose is to become the default entry point for a task that many people attempt once and then give up on because of integration friction.

Where the wrapper is the wrong abstraction

Three situations rule it out, and the first one is about using a research tool in production.

If you have already chosen a matcher, the wrapper is overhead. You are paying for fifty models' worth of dependency graph, and the model you want is the only one you call. The interface it gives you is a thin convenience over the underlying library's own API, and once you know which model you want, calling that library directly is both faster and more honest about what the code is doing. This library is for the exploration phase, and the correct pattern is to explore with vismatch and then depend on the chosen implementation.

The second is a constrained environment. The base requirements include PyTorch, torchvision and OpenCV, and the models download weights, some of which are large neural networks. On a machine with a small disk, on a laptop without a GPU, or in a container with a tight image size budget, this is a hard install rather than a soft one. The device argument defaults through to a choice you make per matcher, and the CUDA path in the example assumes a machine with a GPU.

The third is when the model set changes under you. The description says 50+ and growing, and the pyproject extras are version sensitive in the way described earlier, with a Python version condition on the all extra. A new model can arrive with a new extra that pulls a new framework version, and that interacts with your own pinned dependencies in ways the wrapper does not control.

There is also a question about the comparison itself that the library does not answer. A uniform dictionary tells you the models agree on a schema, not that they are being evaluated fairly. The number of inliers depends on the image resolution you loaded, on the confidence threshold each model uses internally, and on the preprocessing each expects. The library makes the comparison easy, and easy comparisons are the ones most likely to be run and least likely to be checked. The gallery's inclusion of a false positive case is the model here: a comparison that does not include the failure mode is not a comparison.

Editorial conclusion

vismatch fits a researcher or engineer who needs to compare local feature matching models on their own images before choosing one, because the value of the library is precisely that the comparison is apples to apples across model families. It is the wrong choice for a production system that has already picked a matcher, where the wrapper and its dependency tree are pure overhead, and it is the wrong choice on a machine with a small disk or no GPU, since the base requirements pull in PyTorch and OpenCV, and some models need TensorFlow. Before adopting it, install only the extras your chosen model needs rather than the all extra, check the download volume the weights will take, and pin a version, because the model list is described as growing and a new release can add a model whose extra dependencies are not in the set you already have.

Frequently asked questions

Official sources

1. gmberton/vismatch on GitHub
2. License: BSD-3-Clause
3. Project website
4. README
5. Releases