nianticlabs/map-free-reloc: a benchmark for relocalizing against a single photo

The problem: relocalization without a scene map

Standard visual relocalization assumes you already have a scene-specific 3D map, typically built from hundreds of images plus scale calibration. The README states the contrast directly: Map-free Relocalization uses only one photo of a scene to enable instant, metric scaled relocalization. That single image is the map. The output is not a coarse place label but a metric pose relative to that reference frame.

The audience is narrow and specific. This is a benchmark repository for people who train or evaluate pose regression and feature matching methods. If your product needs a phone to know where it is in a shopping mall, this repository gives you a dataset and an evaluation protocol, not a deployable SDK. The dataset covers 655 outdoor scenes, each containing what the README calls a small place of interest such as a sculpture, sign or mural. That choice of subject matter matters: these are compact, visually distinctive objects, not corridors or parking lots.

How the dataset encodes poses and overlaps

The data layout is the part of this repository worth understanding before you write any code. A scene directory holds intrinsics.txt, poses.txt, poses_device.txt and overlaps.npz, plus seq0 and seq1 image folders. Training scenes have two sequences from two different scans and absolute poses for every image, which lets you derive the relative pose between any pair. Validation and test scenes instead give one reference image from seq0 and a query sequence from seq1.

The pose convention is explicit in the README: world-to-camera, so R(q) and t transform a world point p into the camera frame as Rp + t, with t in metric units. For val and test scenes the reference frame seq0/frame_00000.jpg always has identity pose, which means the absolute pose of a query frame equals the relative pose between reference and query. If you get the direction of that transform backwards, every translation error you report will be wrong by a sign.

overlaps.npz exists only for training scenes. It stores two numpy arrays, idxs and overlaps, where idxs holds seq_A, frame_A, seq_B, frame_B and overlaps holds a view-overlap ratio in [0,1] derived from SfM co-visibility. The README notes that rows are provided only for pairs with non-zero overlap, so absence of a row means zero, not missing data. That is a useful pair-sampling signal, and the README points to the supplemental PDF for how the score is computed.

Setup and a first evaluation run

The README gives a conda-based setup. The environment file is at the repository root, and the environment name it creates is mapfree.

conda env create -f environment.yml
conda activate mapfree

The README states the authors used PyTorch 1.8, PyTorch Lightning 1.6.5, CUDA toolkit 11.1, Python 3.7.12 and Debian GNU/Linux 10. Treat those as the supported combination rather than a suggestion. A newer PyTorch will probably import, but nothing in the repository claims it was tested that way.

Next, download the dataset from the project page and extract the train, val and test zip files into data/mapfree, as the README instructs. After extraction you should see scene directories such as s00000 under data/mapfree/train, each with seq0 and seq1.

To inspect a training scene's overlap scores, the README gives this snippet, which filters the arrays by an exact index tuple:

import numpy as np
f = np.load('overlaps.npz', allow_pickle=True)
idxs, overlaps = f['idxs'], f['overlaps']
filter_idx = (idxs == np.array((0, 23, 1, 58))).all(axis=1)
overlap = overlaps[filter_idx]

For evaluation and visualisation the repository provides two top-level entry points, submission.py and train.py, and the README's table of contents lists sections for evaluating your method and visualising it. The README does not reproduce the exact command lines for those scripts in the portion available, so read the scripts and the corresponding README sections before running them.

Where the benchmark breaks down

The most consequential limitation is stated plainly: ground-truth poses are not provided for test scenes. The poses shipped for test sequences are invalid lines containing 0 for all parameters, so any script that reads them without checking will silently produce meaningless error numbers. Scoring happens through the online benchmarking site instead. That makes local iteration on test performance impossible, and it means your validation split is the only offline signal you have.

A second constraint is the scene distribution. The dataset is 460 training scenes, 65 validation scenes and 130 test scenes of outdoor places of interest. A method tuned here is tuned on small, distinctive objects photographed outdoors. Indoor relocalization, large-scale structure, and scenes without a clear focal object are outside what the benchmark measures.

Third, the README warns about skipped frames: the linear id of a frame does not necessarily correspond to its frame number. Any code that assumes contiguous frame numbering will misalign poses and images. Combined with the withheld test poses, this is a dataset where you should validate your loading code against a training scene before trusting a single reported metric.

Compared with feature matching plus estimated depth

The repository itself contains the alternative. Its baseline section splits into Relative Pose Regression baselines, with single frame and multi frame tracks, and Feature Matching + Scale from Estimated Depth baselines. These two families differ in how they recover metric scale, and that difference is the interesting part.

A relative pose regression network predicts the pose directly from the image pair and learns scale from training data. A feature matching pipeline instead matches correspondences between the reference and query images, then recovers scale from estimated depth. The README presents both as baselines against which new methods are measured, which means you can compare your approach to either family inside the same evaluation harness rather than reimplementing an evaluation from scratch.

The practical consequence: if your method is a learned regressor, the single frame and multi frame tracks are your reference points. If your method is a matcher, the depth-scaled baseline is. Choosing the wrong family as your comparison makes your numbers look better or worse for reasons that have nothing to do with your contribution.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-13. That is recent enough that the code has seen activity within the last six months, but there are no retrieved releases, so there is no tagged version to pin against. You are tracking the main branch.

The environment is the real upgrade cost. Python 3.7.12 and PyTorch 1.8 are both old, and the repository ships two environment files, environment.yml and environment_eccv22.yml, which suggests the ECCV 2022 setup was preserved separately from the working one. If your lab standardizes on a current PyTorch, you will be maintaining a compatibility layer yourself, and the repository does not document one.

The licence is the other open question. GitHub reports the licence as NOASSERTION, meaning it could not map the LICENSE file to a known identifier. The README has a License section, so a licence text exists, but what it permits for commercial use, redistribution of the dataset, or derivative models is something you have to read for yourself. This is a research release from a corporate lab with a companion dataset, and dataset terms are frequently stricter than code terms.

Editorial conclusion

Adopt map-free-reloc if you are evaluating a relocalization method against a public leaderboard or need a dataset where a single reference image defines the map. Do not adopt it as a runtime localization component: it is a research benchmark with no documented serving path, no rollback guidance, and a licence file that GitHub classifies as NOASSERTION, so read LICENSE yourself before shipping anything. Before you start, verify that the val and test pose files are the ones you expect, since test ground truth is withheld and the provided test poses are invalid lines of zeros, and check that your environment matches the pinned PyTorch 1.8 and Python 3.7.12 stack before blaming your model for a training failure.

Frequently asked questions

Official sources

1. Issues
2. nianticlabs/map-free-reloc on GitHub
3. Project website
4. README