Glue Factory: Training and Evaluating Local Feature Matchers

What Glue Factory is for, and who it is aimed at

Local feature matching is the step where two images of the same scene are tied together by corresponding points or lines. Most published matchers ship as inference code plus a checkpoint. Glue Factory is the other half: the training and evaluation harness behind models such as LightGlue and GlueStick, released by CVG under Apache-2.0. The README states three goals, reproducing training of state-of-the-art point and line matchers, training them on multiple datasets with your own local features or lines, and evaluating extractors or matchers on standard benchmarks like HPatches or MegaDepth-1500.

The audience is narrow and technical. You need to be comfortable with PyTorch, with configuration files, and with reading evaluation output as a dictionary of metrics. If you only want to match two images in a product, this is a heavier dependency than you need. If you are trying to reproduce a paper number, swap a detector, or test whether a line-based matcher beats a point-based one on your data, it is built for exactly that.

How the library is structured: configs, models, datasets, estimators

The repository layout tells most of the story. Everything runnable lives in the gluefactory package, with evaluation entry points under gluefactory.eval, model and dataset configurations under gluefactory/configs, and robust estimators split by task: gluefactory/robust_estimators/homography holds opencv.py, poselib.py and homography_est.py, while gluefactory/robust_estimators/relative_pose holds pycolmap.py, opencv.py and poselib.py. A parallel package, gluefactory_nonfree, holds models whose licences are not compatible with Apache-2.0.

The data flow is configuration driven. You name a configuration such as superpoint+lightglue-official, and the entry point builds the feature extractor, the matcher, the dataset and the estimator from it. Datasets download automatically, which the README calls out as a design goal, so an evaluation run does not begin with a manual data wrangling step. Estimators are pluggable at the command line, which matters because the README notes that the default estimator is opencv but that poselib is strongly recommended instead. That single flag changes the numbers you report, so the estimator is part of the experiment, not an implementation detail.

Installing Glue Factory and running a first evaluation

The README gives a source install in editable mode. The package requires Python 3 and PyTorch; pyproject.toml declares requires-python >=3.6 and pins torch>=1.7 and torchvision>=0.8, so a modern environment will satisfy it, but the git dependency on LightGlue means the install reaches out to GitHub.

git clone https://github.com/cvg/glue-factory
cd glue-factory
python3 -m pip install -e .  # editable mode

Some features need the optional dependency group, which the README describes as the full set of dependencies. That group pulls in pycolmap, poselib, pytlsd, deeplsd and homography_est, all of which are needed for the line-based and PoseLib paths.

python3 -m pip install -e .[extra]

For a first real run, evaluate the pre-trained SuperPoint+LightGlue model on HPatches. The dataset downloads automatically to data/ by default and the README puts the disk requirement at about 1.8 GB. The --overwrite flag forces the run to replace previous results.

python -m gluefactory.eval.hpatches --conf superpoint+lightglue-official --overwrite

The README prints the expected output, a dictionary including H_error_dlt@1px at 0.3515, mprec@3px at 0.89 and ransac_mAA at 0.5378. If your run lands on those values, the install and the data pipeline are working. To match the recommended setup, switch the estimator and let the inlier threshold auto-tune.

python -m gluefactory.eval.hpatches --conf superpoint+lightglue-official --overwrite \
    eval.estimator=poselib eval.ransac_th=-1

Setting eval.ransac_th=-1 runs the evaluation across a range of thresholds and reports the optimal one, which the README explains as auto-tuning. For MegaDepth-1500 the entry point is gluefactory.eval.megadepth1500, the download is about 1.5 GB, and the adaptive LightGlue variant is reached by overriding nested config keys: model.matcher.{depth_confidence=0.95,width_confidence=0.95}.

The estimator choice changes your reported numbers

This is the most practically useful thing in the README, and it is easy to skim past. The same SuperPoint+LightGlue model on HPatches scores 35.1 / 67.2 / 77.6 AUC with DLT, 34.2 / 57.9 / 69.9 with the OpenCV estimator, and 37.1 / 67.4 / 77.8 with PoseLib. SuperGlue shows a wider spread, 32.9 / 55.7 / 68.0 with OpenCV against 37.0 / 68.2 / 78.7 with PoseLib. A reader who runs the default and compares against a paper that used PoseLib will conclude the model regressed when nothing about the model changed.

The same pattern holds for relative pose on MegaDepth-1500, where the README's table compares pycolmap, OpenCV and PoseLib. SuperGlue scores 54.4 / 70.4 / 82.4 under pycolmap and 64.8 / 77.9 / 87.0 under PoseLib. GlueStick is a separate case: because it uses points and lines, it needs a different estimator, Hest, and its HPatches table only lists DLT against Hest, at 33.6 / 66.4 / 77.1 and 39.2 / 69.7 / 79.6. If you report GlueStick numbers with a point-only estimator, you are not measuring what the model does.

Where Glue Factory is the wrong tool

There are no releases. The version in pyproject.toml is 0.0, and the install path is an editable checkout of main. That means no pinned artifact to depend on and no changelog to read before upgrading; you are tracking a branch. For a research group reproducing a paper this is normal. For a team that needs a stable dependency with a support window, it is a poor fit.

The licence boundary is the second constraint. The README is explicit that the code and trained models are Apache-2.0, and that this covers LightGlue and an open version of SuperPoint. SuperPoint (original) and SuperGlue are not compatible with that licence and are provided in gluefactory_nonfree, where each model may follow its own restrictive licence. If your intended use depends on those specific checkpoints, the permissive part of the repository will not cover you, and the README does not resolve what the non-free terms are.

The third limitation is scope. Glue Factory trains and evaluates matchers. It does not claim to be an inference server, a deployment format, or a pipeline for large-scale reconstruction. The README documents evaluation commands and their expected outputs; it does not document packaging, serving, or versioning policy.

How it compares to using LightGlue or GlueStick directly

The obvious alternative is to use the upstream model repositories, cvg/LightGlue and cvg/GlueStick, directly. They give you the model and the inference path. Glue Factory gives you the training loop that produced them, the dataset plumbing that feeds it, and an evaluation harness with several estimators already wired in. If your goal is to run a matcher on a pair of images, the upstream repositories are the shorter path and Glue Factory adds a training stack you will not call.

The difference shows up the moment you want to change something. Training on your own local features or lines, or evaluating an extractor you wrote, requires the config and dataset machinery that Glue Factory provides and that the inference repositories do not. Conversely, if you want the adaptive LightGlue variant, the README shows it is reachable here through config overrides rather than a separate code path, which keeps the comparison between the standard and adaptive settings inside one harness. That is the trade: more moving parts to install, in exchange for a single place where training and evaluation configs live.

Licence and the cost of keeping up

The project is Apache-2.0, declared in the LICENSE file and in the pyproject.toml classifier. The README extends that to the code and trained models, specifically naming LightGlue and an open version of SuperPoint. Anything in gluefactory_nonfree is outside that grant and may carry restrictive terms, so the practical question for a commercial user is which checkpoints the work depends on. This is not legal advice; read the licence files for the specific models you ship.

The upgrade cost is real because there is nothing to upgrade to. With no releases, staying current means pulling main. The dependency list includes a git URL for LightGlue and the extra group pins pytlsd and homography_est to specific commits, so a fresh install resolves against moving upstream repositories. The declared floor of torch>=1.7 is old enough that most users will be far above it, which means the floor tells you little about what is actually exercised. Budget for the possibility that a fresh checkout needs dependency debugging before the first evaluation finishes.

Editorial conclusion

Adopt Glue Factory if you are a researcher who needs to reproduce LightGlue or GlueStick training, swap in your own local features or lines, or benchmark extractors and matchers on HPatches and MegaDepth-1500 with the estimators the project already wires up. Do not adopt it if you want a packaged inference API or a supported product with releases; there are no releases, the version is 0.0, and the repository is a research codebase you install from source. Before committing, verify that your Python and PyTorch versions satisfy the declared floors, that you have the disk space the evaluation datasets need, and that every model you plan to use sits in the Apache-2.0 part of the tree rather than in gluefactory_nonfree.

Frequently asked questions

Official sources

1. cvg/glue-factory on GitHub
2. Issues
3. License: Apache-2.0
4. README