ROMAN ROS2

Welcome to roman_ros2, a ROS2 wrapper for ROMAN (Robust Object Map Alignment Anywhere). ROMAN is a view-invariant global localization method that maps open-set objects and uses the geometry, shape, and semantics of objects to find the transformation between a current pose and previously created object map. This enables loop closure between robots even when a scene is observed from opposite views.

Demo videos, the paper, and more can be found at the ROMAN project website. Checkout the main branch for the ROS1 wrapper.

Citation

If you find ROMAN useful in your work, please cite our paper:

M.B. Peterson, Y.X. Jia, Y. Tian, A. Thomas, and J.P. How, "ROMAN: Open-Set Object Map Alignment for Robust View-Invariant Global Localization," Robotics: Science and Systems, 2025.

@inproceedings{peterson2025roman,
  title={{ROMAN: Open-Set Object Map Alignment for Robust View-Invariant Global Localization}},
  author={Peterson, Mason B and Jia, Yi Xuan and Tian, Yulun and Thomas, Annika and How, Jonathan P},
  booktitle={Robotics: Science and Systems (RSS)},
  pdf={https://www.roboticsproceedings.org/rss21/p029.pdf},
  year={2025}
}

Install

Step 1: Set up and build ROS workspace

In the root directory of your ROS workspace (for example, mkdir ~/roman_ws && cd ~/roman_ws) run:

git clone https://github.com/mit-acl/roman_ros.git src/roman_ros2
vcs import src < src/roman_ros2/install/packages.yaml
colcon build

Step 2: Install ROMAN Python package

First, activate the python environment you would like to use with ROMAN. For example, build and source a python virtual environment as follows:

python3 -m venv ./venv
touch ./venv/COLCON_IGNORE # so that colcon does not try to build packages in the environment
source ./venv/bin/activate

Once your environment has been activated, run

./src/roman_ros2/install/install_roman.bash

to install the ROMAN python package and download required model weights.

Step 3: Set up environment variables

For running roman_ros2, you will need to set the ROMAN_WEIGHTS environment variable. You may want to run the following to add this environment variable to your .zshrc file:

echo export ROMAN_WEIGHTS=$(realpath ./src/roman_ros2/weights) >> ~/.zshrc

or .bashrc file:

echo export ROMAN_WEIGHTS=$(realpath ./src/roman_ros2/weights) >> ~/.bashrc

Finally, the examples will source your python environment by calling $ROMAN_ENV_ACTIVATE. Before running the examples run (or put the following in your ~/.zshrc or ~/.bashrc):

export ROMAN_ENV_ACTIVATE=<environment activation command>

If you used a Python virtual environment as described above, this would look something like: export ROMAN_ENV_ACTIVATE="source ~/roman_ws/venv/bin/activate"

Step 4: Build the ROS2 workspace

Note that roman_ros2 currently requires that --simlink-install option is not used when building. In ~/roman_ws or the root of your workspace location, run:

colcon build

Examples

A few example demos can be run following the examples instructions. The provided examples include running ROMAN on a pre-recorded bag, using ROMAN for single robot loop closures, and the main roman_ros2 demo that creates ROMAN maps across two camera sessions and then aligns the maps from the camera sessions without any initial pose information.

Device Requirements

To run ROMAN with full performance, a GPU is required. However, ROMAN can still be run on CPU only although semantics cannot be computed and ROMAN will run much slower, which both cause a degradation in performance.

If you would like to configure the repo to use CPU, cd into this repo and run

python3 ./scripts/configure_cpu_or_gpu.py --device cpu

---

This research is supported by Ford Motor Company, DSTA, ONR, and ARL DCIST under Cooperative Agreement Number W911NF-17-2-0181.