Official code release for MacroNav: Multi-Task Context Representation Learning Enables Efficient Navigation in Unknown Environments.

MacroNav is a learning-based navigation framework for unknown environments. It first trains a lightweight context encoder with multi-task self-supervised learning, then integrates the learned dense contextual representation with an RL navigation policy.

Demo video: Bilibili

MacroNav/
|-- dataset/
|   |-- GridMapV1/             # Encoder pre-training maps
|   `-- NavSimMapV1/           # Navigation simulation maps
|-- exps/
|   |-- pretrain/              # Pre-trained context encoder weights
|   `-- nav_policy/            # Policy checkpoints and validation outputs
|-- macronav/
|   |-- pretrain/              # Context encoder pre-training
|   `-- nav_policy/            # RL navigation policy training, validation, demo, export
|-- pyproject.toml
`-- README.md

git clone https://github.com/SimonKennethRobo/MacroNav
cd MacroNav

conda create -n macronav python=3.10
conda activate macronav

pip install -e .

Download zip from GoogleDrive

unzip macronav_dataset_and_ckpt.zip

After extraction, the expected paths are:

dataset/GridMapV1
dataset/NavSimMapV1
exps

Edit macronav/pretrain/config/train_param.py if you want to change the experiment name, dataset path, batch size, or logging settings.

python macronav/pretrain/train_encoder.py

Outputs are saved under exps/<EXP_NAME>/, including checkpoints, copied config files, and logs.

Edit macronav/nav_policy/config/train_param.py if you want to change the experiment settings.

python macronav/nav_policy/train_nav.py

Configure the target experiment in macronav/nav_policy/config/valid_param.py.

python macronav/nav_policy/valid_nav.py

valid_iter.py provides an OpenCV-based interactive demo. It can run out of the box with the released maps and policy checkpoints after extraction.

The default dependency list installs opencv-python-headless, which is suitable for training and batch validation. For the interactive demo, install the GUI-enabled OpenCV package:

pip uninstall -y opencv-python-headless
pip install opencv-python

If you want to run ONNX policy inference in the interactive demo, install ONNX Runtime, refer link. Use the GPU package when CUDA is available:

First, check macronav/nav_policy/config/valid_param.py:

LOG_DIR = "exps/nav_policy/<exp_name>"
ENV_LEVEL = "real"          # easy, medium, hard, or real
CUSTOM_MAP_IDX = 0 # set the map you want

Then run:

python macronav/nav_policy/valid_iter.py

Controls:

• Left click: select a point on the map
• s: set selected point as start
• e: set selected point as goal
• Space: start navigation
• + / =: zoom in
• -: zoom out
• r: reset
• Esc: exit

Export a trained policy to ONNX, TensorRT, or both:

python macronav/nav_policy/scripts/export_policy.py \
  --checkpoint exps/nav_policy/<exp_name>/models/checkpoint_best.pth \
  --config exps/nav_policy/<exp_name>/train_param.py \
  --format both

For TensorRT export, install the matching CUDA/PyTorch/TensorRT packages for your system.

@article{sima2026macronav,
  title={MacroNav: Multi-Task Context Representation Learning Enables Efficient Navigation in Unknown Environments},
  author={Sima, Kuankuan and Tang, Longbin and Yang, Zhenyu and Ma, Haozhe and Zhao, Lin},
  journal={IEEE Robotics and Automation Letters},
  year={2026}
}

This codebase builds on ideas and components from the following open-source repositories:

• Context_Aware_Navigation
• mae

This project is released under the MIT License. See LICENSE for details.