https://github.com/mit-acl/roman_ros
ROS1/2 wrapper for ROMAN, a view-invariant global localization method
https://github.com/mit-acl/roman_ros
Last synced: 10 months ago
JSON representation
ROS1/2 wrapper for ROMAN, a view-invariant global localization method
- Host: GitHub
- URL: https://github.com/mit-acl/roman_ros
- Owner: mit-acl
- Created: 2024-12-13T17:43:41.000Z (over 1 year ago)
- Default Branch: ros2
- Last Pushed: 2025-07-29T00:19:55.000Z (12 months ago)
- Last Synced: 2025-07-29T02:31:14.793Z (12 months ago)
- Language: Python
- Size: 670 KB
- Stars: 88
- Watchers: 4
- Forks: 11
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ROMAN ROS2
Welcome to roman_ros2, a ROS2 wrapper for [ROMAN](https://github.com/mit-acl/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](https://acl.mit.edu/roman/).
Checkout the main branch for the ROS1 wrapper.
## Citation
If you find ROMAN useful in your work, please cite our [paper](https://www.roboticsproceedings.org/rss21/p029.pdf):
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=
```
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](./examples/README.md).
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.