Skip to content
BranchesTags

Repository files navigation

OpenNavMap: Multi-Session Appearance-Based Topometric Mapping for Scalable Visual Navigation

License: MIT Webpage Paper GitHub Stars

OpenNavMap Concept

🏠 Introduction

OpenNavMap is a lightweight, structure-free topometric mapping system that enables large-scale collaborative localization across multiple sessions without requiring pre-built 3D models. It builds, aligns, merges, and maintains multi-session topometric maps for image-goal navigation.

The system represents environments using three complementary graph structures:

  • Covis Graph (covis): image keyframes with visual associations and descriptors
  • Odometry Graph (odom): sequential pose chain from odometry
  • Traversability Graph (trav): connectivity for path planning

The repository consists of three main lines:

  1. Multi-Session Mapping & Merging — python/map_merge_pipeline.py, python/map_manager.py
  2. Visual Localization — LiteVLoc submodule at third_party/litevloc_code (github), performing global VPR → local matching → pose solving on the built map
  3. Navigation & System Integration — global planning, pose fusion, and online ROS localization (within the LiteVLoc submodule)

Highlights

  • 🎯 Structure-free Map: Lightweight graph-based map representation
  • 🔗 Collaborative Localization: Global registration across sessions in large-scale environments
  • 📱 Cross-Device: Works on various mobile platforms
  • 🔄 Scalable & Lifelong: Automatic map maintenance
  • 🗺️ Multi-Session: Merge maps from different agents/times

🔥 News

Time Update
2026/09 OpenNavMap was accepted to IEEE T-RO!
2026/07 📦 Evaluation datasets released on Google Drive (map-free relocalization, VPR, and multi-session mapping; faces anonymized). See Testing Data.
2026/07 Full codebase released: multi-session mapping, submap merging, and benchmark.
Third-party libraries also published:
• litevloc_code — visual localization (global VPR → local matching → pose solving)
• pose_estimation_models — pose estimation
• VPR-methods-evaluation — visual place recognition benchmarking
• slam_trajectory_evaluation — trajectory evaluation
• vismatch — visual matching
2026/01 Paper submitted (Under Review).
2025/05 LiteVLoc accepted by ICRA 2025.

📋 Table of Contents

🛠️ Getting Started

Requirements

Create the workspace:

mkdir -p catkin_ws/src/
cd catkin_ws/src/

Create conda environment:

conda create --name opennavmap python=3.8
conda activate opennavmap

Clone with submodules and set up environment (NVIDIA GeForce RTX 4090 and CUDA 11.8):

git clone --recurse-submodules https://github.com/RPL-CS-UCL/OpenNavMap.git
cd OpenNavMap
git remote set-url origin git@github.com:RPL-CS-UCL/OpenNavMap.git
conda install pytorch=2.0.1 torchvision=0.15.2 pytorch-cuda=11.8 numpy=1.24.3 -c pytorch -c nvidia
pip install -r requirements.txt
pip install -e third_party/vismatch

Note: third_party/litevloc_code is a required submodule, not optional. It provides the core graph structures (image_graph.py, point_graph.py, etc.) and shared utility functions used directly by OpenNavMap. If you cloned without --recurse-submodules, run git submodule update --init --recursive before proceeding. All scripts must set PYTHONPATH to include both python/ and third_party/litevloc_code/python/, e.g.:

export PYTHONPATH=$(pwd)/python:$(pwd)/third_party/litevloc_code/python

Verify torch installation:

python test_torch_install.py

📦 Testing Data

We release all evaluation datasets used in the paper on Google Drive (a 19 km, multi-site, cross-device collection; all human faces are anonymized). Each released dataset corresponds to one experiment:

Dataset Paper experiment
vpr_eval Topological localization
map_free_eval Metric localization
map_multisession_eval Multi-session map merging

🔗 Download from Google Drive

See Benchmark Evaluation for the full archive list, the small-subset quick start, download/extract commands, test-time (temporal/spatial) coverage, and how to run each benchmark. The map data format is documented in Instruction in Processing Dataset.

📚 Documentation

OpenNavMap:

  1. Instruction in Running Map Merging
  2. Instruction in Processing Dataset
  3. Benchmark Evaluation (datasets ↔ experiments, how to run)
  4. Instruction in Data Collection (Project Aria)
  5. Web console: run map merging, browse steps in 3D, evaluate and export

LiteVLoc submodule (third_party/litevloc_code):

  1. Instruction in Running LiteVLoc with Offline Data
  2. Instruction in Running Visual Navigation with Simulated Matterport3d
  3. Instruction in Running Visual Navigation with Real Robots

Additional: 9. Repo Structure Guide

📊 Multi-Session Mapping Experiment

Run the multi-session mapping and submap-merging experiment on the released map_multisession_eval data (see Testing Data):

conda activate opennavmap
bash scripts/run_map_merging.sh <SCENE> <ORDER> <METHOD> <POSE_EST> [IQA] [IG] [TD] [MAX_SUBMAPS]

The pipeline incrementally aligns submaps into a globally consistent map (topological localization → metric localization → PGO → node culling) and reports the ATE against ground truth. See Instruction in Running Map Merging for the full argument reference, and Benchmark Evaluation for how each released dataset maps to a paper experiment.

🖥️ Web Console

A browser UI (app/navmap_console) that starts map-merging runs, follows every merge step in an interactive 3D view, evaluates the ATE and packs the results for download. It needs the opennavmap conda environment plus Node >= 20 and pnpm; the first launch builds the frontend:

conda activate opennavmap
cd app/navmap_console/frontend && pnpm install && cd ../../..
bash app/navmap_console/scripts/build.sh      # bundles the frontend into frontend/dist (once, and after every UI change)
NAVMAP_CONSOLE_DATA_ROOT=/path/to/console_data bash app/navmap_console/scripts/serve.sh

Then open http://<server-ip>:8765 in a browser on the same LAN (the API docs are at /api/docs). NAVMAP_CONSOLE_DATA_ROOT is where the console keeps its sessions, runs and job records; every other setting has a default. There is no login, so keep it on a trusted network. bash app/navmap_console/scripts/dev.sh starts the hot-reloading development setup instead. See the console README for the full usage.

🎬 Results Gallery

Multi-Session Map Merging

Vineyard Map Merging

Vineyard — outdoor multi-session map merging.

HKUST Campus Map Merging

HKUST Campus — multi-session submaps aligned and merged into a unified topometric map.

UCL Campus Map Merging

UCL Campus — multi-session map merging across heterogeneous devices.

Dataset

Dataset

Overview of our self-collected dataset using multiple devices, spanning diverse environments over 3.5 months, 35 sequences, and 18.7km.

Multi-Session Mapping

HKUST Campus UCL Campus

Multi-session mapping with heterogeneous devices across two regions.

Real-World Image-Goal Navigation

VNav Lab VNav Outdoor

Quadruped robot performing image-goal navigation in lab (left) and outdoor environments (right).

🐛 Known Issues

Issue: cannot import name 'cache' from 'functools'

Replace the original code with Link

from functools import lru_cache
@lru_cache(maxsize=None)
    def xxx

Issue: /lib/aarch64-linux-gnu/libp11-kit.so.0: undefined symbol: ffi_type_pointer, version LIBFFI_BASE_7.0 using cv_bridge

Change the .so. Complete tutorial is shown here

rm /Rocket_ssd/miniconda3/envs/opennavmap/lib/libffi.so.7
ln -s /usr/lib/aarch64-linux-gnu/libffi.so.7 /Rocket_ssd/miniconda3/envs/opennavmap/lib/libffi.so.7
rm /Rocket_ssd/miniconda3/envs/opennavmap/lib/libtiff.so.5
ln -s /usr/lib/x86_64-linux-gnu/libtiff.so.5 /Rocket_ssd/miniconda3/envs/opennavmap/lib/libtiff.so.5

Issue: ImportError: /lib/aarch64-linux-gnu/libgomp.so.1: cannot allocate memory in static TLS block

Set this in the bash file: export LD_PRELOAD=/usr/lib/aarch64-linux-gnu/libgomp.so.1

🔗 Citation

If this work is helpful to your research, please consider citing OpenNavMap or our related works:

@article{jiao2025opennavmap,
  title={OpenNavMap: Multi-Session Appearance-Based Topometric Mapping for Scalable Visual Navigation},
  author={Jiao, Jianhao and Liu, Changkun and Yu, Jingwen and Liu, Boyi and Zhang, Qianyi and Wang, Yue and Kanoulas, Dimitrios},
  journal={IEEE Transactions on Robotics},
  year={2026}
}
@inproceedings{jiao2025litevloc,
  title={LiteVLoc: Map-lite visual localization for image goal navigation},
  author={Jiao, Jianhao and He, Jinhao and Liu, Changkun and Aegidius, Sebastian and Hu, Xiangcheng and Braud, Tristan and Kanoulas, Dimitrios},
  booktitle={2025 IEEE International Conference on Robotics and Automation (ICRA)},
  pages={5244--5251},
  year={2025},
  organization={IEEE}
}
@article{wei2025fusionportablev2,
  title={Fusionportablev2: A unified multi-sensor dataset for generalized slam across diverse platforms and scalable environments},
  author={Wei, Hexiang and Jiao, Jianhao and Hu, Xiangcheng and Yu, Jingwen and Xie, Xupeng and Wu, Jin and Zhu, Yilong and Liu, Yuxuan and Wang, Lujia and Liu, Ming},
  journal={The International Journal of Robotics Research},
  volume={44},
  number={7},
  pages={1093--1116},
  year={2025},
  publisher={SAGE Publications Sage UK: London, England}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👏 Acknowledgements

Supported by UKRI Future Leaders Fellowship [MR/V025333/1] (RoboHike), built by the Robot Perception and Learning Lab at UCL.

📞 Contact

About

OpenNavMap: Multi-Session Appearance-Based Topometric Mapping for Scalable Visual Navigation

rpl-cs-ucl.github.io/OpenNavMap_page

Resources

Readme
Apache-2.0 license
Activity
Custom properties

Stars

71 stars

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages