# OrienterNet localizes a photo by matching a neural bird's-eye view against OpenStreetMap > OrienterNet is the Meta Reality Labs research code behind a CVPR 2023 paper on visual localization in 2D public maps. Instead of building 3D point clouds like earlier approaches, it renders a neural bird's-eye view of the query image and matches it against 2D map tiles, which means the only external data it needs is OpenStreetMap. **facebookresearch/OrienterNet** — Source Code for Paper "OrienterNet Visual Localization in 2D Public Maps with Neural Matching" - Repository: https://github.com/facebookresearch/OrienterNet - Stars: 581 · Forks: 66 - Language: Python - License: NOASSERTION - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/facebookresearch-orienternet ## The bird's-eye view replaces the point cloud OrienterNet is a deep neural network that can accurately localize an image using the same 2D semantic maps that humans use to orient themselves. The repository hosts the source code for the project, described as a research project by Meta Reality Labs, and the paper is titled Visual Localization in 2D Public Maps with Neural Matching. The technical claim in the README is the one that separates it from earlier work. OrienterNet leverages deep learning to provide accurate positioning of images using free and globally-available maps from OpenStreetMap, and as opposed to complex existing algorithms that rely on 3D point clouds, OrienterNet estimates a position and orientation by matching a neural Bird's-Eye-View with 2D maps. That is the whole architectural bet. The alternative to a learned map prior is to reconstruct or download the geometry of the world in 3D and align against that. OrienterNet instead learns what the world looks like from above, renders that learned view for the query image, and matches it against a rendered map tile. The map side is free, global and two dimensional, which is why the data requirement is modest. The output is a position and an orientation, not just a point on a map. The evaluation metrics in the README are reported separately for position error in metres and yaw error in degrees, at thresholds of 1, 3 and 5 m/°, which is the right way to describe a pose estimate rather than a place lookup. ## Two requirement files, and the demo needs far less than training OrienterNet requires Python 3.8 or newer and PyTorch. The installation is split into two requirement files, and the split is a useful signal about the weight of the two workflows. For the demo, you clone and install the minimal set: ```bash git clone https://github.com/facebookresearch/OrienterNet python -m pip install -r requirements/demo.txt ``` For evaluation and training you install the full requirements instead: ```bash python -m pip install -r requirements/full.txt ``` The README also points at three demo entry points, and each one suits a different situation. There is a web demo with Gradio on Hugging Face Spaces, a cloud demo on Google Colab, and a local demo as a Jupyter notebook, demo.ipynb at the repository root. The stated pitch is to take a picture with your phone in any city and find its exact location in a few seconds. The Colab route is the one worth knowing about, because it removes the GPU question entirely for anyone who just wants to try the model. The local notebook gives you the same thing with your own hardware. The package itself is set up as maploc in setup.py, with the version pinned at 0.0.0 and python_requires of 3.8 or above, which is a fair signal that this is research code rather than a released library. The repository also has an app.py at the root, notebooks/ and assets/ directories, and a format.sh with a .flake8 and .isort.cfg, so the code is linted and import-sorted. ## Evaluation is a module invocation with Hydra overrides The evaluation scripts follow a consistent pattern that is worth learning, because the same shape appears in training. For the Mapillary Geo-Localization dataset you first prepare the data, and the data preparation step needs a Mapillary access token: ```bash python -m maploc.data.mapillary.prepare --token $YOUR_ACCESS_TOKEN ``` Getting that token means creating a developer account at mapillary.com, and the README notes it is free. By default the data is written to the directory ./datasets/MGL/. Then you run the evaluation with the pre-trained model: ```bash python -m maploc.evaluation.mapillary --experiment OrienterNet_MGL model.num_rotations=256 ``` The trailing model.num_rotations=256 is a Hydra style override, and the README says the pre-trained models are downloaded if necessary. The expected results are given as recall at error thresholds: ``` Recall xy_max_error: [14.37, 48.69, 61.7] at (1, 3, 5) m/° Recall yaw_max_error: [20.95, 54.96, 70.17] at (1, 3, 5) m/° ``` Two knobs matter for anyone with less hardware. The evaluation requires a GPU with 11GB of memory, and the README suggests reducing the number of rotations if you hit out of memory errors, since the default is 256. There is also a sequential mode, which processes the input as a sequence of frames, and the README says it uses 10 frames by default, with chunking.max_length=20 raising that. The KITTI dataset follows the same shape, with a prepare step writing to ./datasets/kitti/ and an evaluation module taking the same experiment name and rotation override, and the expected numbers are given in the same recall form. ## The paper's own evaluation data was never released There is a short section in the README that is easy to skim past and impossible to ignore for anyone planning an evaluation. Under the heading Aria Detroit & Seattle, the README states: we are currently unable to release the dataset used to evaluate OrienterNet in the CVPR 2023 paper. That is a direct statement that the headline numbers in the paper are not reproducible from this repository. What you can reproduce is the Mapillary Geo-Localization evaluation and the KITTI evaluation, with the expected results printed in the README, but the dataset behind the original paper's figures is not available. This shapes how you should treat the project. It is a code release for a paper, which is a normal and reasonable thing for a research group to publish, and the evaluation infrastructure around the public datasets is complete enough to run and check. What it is not is a project with a maintained, self-contained benchmark you can rely on for a regression test in your own pipeline. There is also a data source question that is worth separating from a licence question. The Mapillary data requires an account and a token from the provider, and OpenStreetMap is described as free and globally-available, so the map side of the pipeline has no access barrier. The Aria data, which comes from Meta's own hardware, is simply not available. ## Training is one command and three 24GB GPUs The training section describes the recipe for the MGL dataset in concrete terms. The README states the model was trained on the MGL dataset using 3x 3090 GPUs with 24GB VRAM each and a total batch size of 12 for 340k iterations, which it puts at about 3 to 4 days. The command is a single module invocation: ```bash python -m maploc.train experiment.name=OrienterNet_MGL_reproduce ``` And the README notes you are free to use any other experiment name. The configuration system is Hydra with OmegaConf, so any entry can be overridden from the command line, and the same mechanism you saw on the evaluation scripts applies here. That combination of a module-per-entry-point and a config system with command line overrides is the reason the evaluation commands look the way they do. Everything the script needs is a named config, and the override syntax is how you change one value without editing a file. The model.num_rotations override in the evaluation and the chunking.max_length override in the sequential mode are the same idea. The practical number to hold onto is the hardware. Three 24GB cards for three to four days is a research budget, not an afternoon, and the 11GB requirement for evaluation is the smaller sibling of that figure. Anyone planning to retrain should look at the rotation count first, since the README flags it as the first thing to reduce when memory is tight, and the number of rotations is also what sets the angular resolution of the search. ## Where this differs from a 3D point cloud pipeline The alternative approaches the README names are the complex existing algorithms that rely on 3D point clouds. The difference in approach is worth being precise about, because it is the difference between a system with a data dependency and one without. A 3D point cloud pipeline needs the geometry of the world in 3D: reconstructed from imagery, downloaded from a mapping provider, or assembled from some combination of both. That is the expensive and fragile part, and it is where a lot of the complexity in prior localisation systems lives. OrienterNet removes that dependency by learning the map prior instead, and matching against a 2D tile rendered from OpenStreetMap. The trade-off is that the network is a learned component of the mapping, and a learned component has to be trained and, in the OrienterNet case, has to be evaluated on data the authors can release. That is exactly why the Aria dataset gap matters. The approach removes a heavy external dependency and replaces it with a model that depends on training data and a released evaluation set. There is a second alternative worth naming, and it is not a research project at all. If you need to place a photo on a map for a product, a commercial geocoding or reverse geocoding service with a street level image search is a different shape of solution: it is a hosted API with a contract, a price and a support commitment, rather than a network you train and host yourself. OrienterNet's appeal is that it is free, open, self-hosted and built on data anyone can download. Its cost is that you own the training, the evaluation and the accuracy question, and that the paper's own numbers are not reproducible from what is published here. On maintenance, the last push was on 2026-08-04 and the repository is not archived, so the code is not being deleted. The repository has no GitHub releases, and the licence is classified as a custom one that GitHub cannot classify, with a LICENSE file at the root, so the terms are in that file rather than in a standard identifier. That is a licensing note rather than legal advice, and it is worth reading before you build on research code from a corporate lab. ## Conclusion Adopt OrienterNet if you need image localization against open map data and want to start from a working research implementation with a demo, evaluation scripts and training code rather than a maintained library. Do not adopt it for production use as it stands, since the paper's own evaluation dataset cannot be released, the Aria Detroit and Seattle data is unavailable, and the training recipe calls for three 24GB GPUs over several days. Verify first which dataset you can legally obtain, since Mapillary requires a developer account and its own token, and check the memory requirement before running the evaluation, which the README puts at 11GB of GPU memory. ## FAQ ### What does OrienterNet do and what does it need to localize an image? OrienterNet is a deep neural network that localizes an image using 2D semantic maps from OpenStreetMap, estimating a position and orientation by matching a neural Bird's-Eye-View against 2D maps rather than relying on 3D point clouds. It requires Python 3.8 or newer and PyTorch. ### How do I run the OrienterNet demo? Clone the repository and install the minimal requirements with python -m pip install -r requirements/demo.txt. There is also a web demo on Hugging Face Spaces, a Google Colab notebook, and a local demo.ipynb in the repository root, and the stated goal is to take a photo with a phone in any city and find its exact location in a few seconds. ### How do I evaluate OrienterNet on the Mapillary dataset? Create a Mapillary developer account for a free access token, run python -m maploc.data.mapillary.prepare with the token, which writes to ./datasets/MGL/ by default, then run python -m maploc.evaluation.mapillary with the OrienterNet_MGL experiment and model.num_rotations=256. The evaluation needs a GPU with 11GB of memory. ### Can I reproduce the results from the OrienterNet paper? Not the paper's own figures. The README states that the dataset used to evaluate OrienterNet in the CVPR 2023 paper, the Aria Detroit and Seattle data, is currently unable to be released. The Mapillary and KITTI evaluations can be run, with expected results printed in the README. ### What hardware do I need to train OrienterNet? The README states the model was trained on the MGL dataset using 3x 3090 GPUs with 24GB VRAM each and a total batch size of 12 for 340k iterations, about 3 to 4 days, with the command python -m maploc.train experiment.name=OrienterNet_MGL_reproduce. Configurations are managed by Hydra and OmegaConf so any entry can be overridden from the command line. ## Sources - [facebookresearch/OrienterNet on GitHub](https://github.com/facebookresearch/OrienterNet) - [Issues](https://github.com/facebookresearch/OrienterNet/issues) - [README](https://github.com/facebookresearch/OrienterNet/blob/main/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/facebookresearch-orienternet