VINS-MONO-ROS2

ROS2 version of VINS-MONO

1. Introduction

This repository implements the ROS2 version of VINS-MONO; and is forked by the Lunar Lab @ GT to generate odometry estimates for SLAM systems and to use as a baseline. NOTE: Since the get_package_share_directory command in ROS2 launch files can only locate packages in the install directory instead of the src directory like ROS1, we create a package called config_pkg to store the config/ and support_files/ folders from VINS-MONO.

2. Prerequisites

• System
  • Ubuntu 20.04
  • ROS2 foxy
• Libraries
  • OpenCV 4.2.0
  • Ceres Solver 1.14.0
  • Eigen 3.3.7

3. Build VINS-MONO-ROS2

Docker Setup

Make sure to install:

• Docker

Then, clone this repository in a ROS2 workspace at a desired location on your computer.

After that, navigate to the docker directory. Log in to the user that you want the docker file to create in the container. Then, edit the DOCKERFILE to update these lines:

• ARG USERNAME=: Your username
• ARG USER_UID=: Output of echo $UID
• ARG USER_GID=: Output of id -g

Edit the enter_container.sh script with the following paths:

• DATA_DIR=: The directory where the any datasets are located
• ROS_WS_DIR=: The directory of the ros workspace this repository is a part of

Now, run the following commands:

build_container.sh
run_container.sh

The rest of this README assumes that you are inside the Docker container. For easier debugging and use, its highly recommended to install the VSCode Docker extension, which allows you to start/stop the container and additionally attach VSCode to the container by right-clicking on the container and selecting Attach Visual Studio Code.

Build

Next navigate to the root of your ROS workspace, and run the following commands:

colcon build
source install/setup.bash

Finally, install the python dependencies (for WandB sweeps) with the following commands:

cd src/VINS-MONO-ROS2/dependencies/robotdataprocess/
unset PYTHONPATH
source /opt/miniconda3/bin/activate robotdataprocess
pip install .

Then, kill the shell to deactivate the robotdataprocess environment.

4. VINS-MONO-ROS2 on EuRoC datasets

4.1. ROS1 bag to ROS2 bag

Download EuRoC datasets. However, the datasets are in ROS1 format. To run the code in ROS2, we need to first convert these datasets to ROS2 format. We can use rosbags for this purpose, which can convert ROS built-in messages between ROS1 and ROS2.

4.2. Visual-inertial odometry and loop closure

All configuration files are in the package, config_pkg, so in launch files, the path to the EuRoC configuration files is found using get_package_share_directory('config_pkg').

Then, navigate to this repositories folder and run the following command:

tmuxp load tmux/euroc.yaml

4.3. Visualize ground truch

First, take the MH01 for example, modifying the 'sequence_name' in the launch file: benchmark_publisher/launch/benchmark_publisher.launch.py

sequence_name_arg = DeclareLaunchArgument(
    'sequence_name',
    default_value='MH_01_easy',
    description='Sequence name for the benchmark'
)
sequence_name = LaunchConfiguration('sequence_name')

PS: After modifying the launch file, don't forget to run colcon build for this package again.
Then, run the following command:

tmuxp load tmux/euroc_w_benchmark.yaml

4.4. AR Demo

Download the bag file.
Then open two terminals

ros2 launch ar_demo 3dm_bag.launch.py               # for featuer tracking, backend optimization, ar demo and rviz2.
ros2 bag play $(PATH_TO_YOUR_DATASET)/ar_box        # for ros2 bag

5. VINS-MONO-ROS2 on GRaCo dataset

Run the following command to run VINS-Mono on sequence Ground-04 of the GRaCo Dataset:

tmuxp load ./src/VINS-MONO-ROS2/tmux/graco_ground4.yaml

For sequence Ground-05, run the following:

tmuxp load ./src/VINS-MONO-ROS2/tmux/graco_ground5.yaml

Note on Parameters

In order to adapt GRaCo to work successfully with VINS-Mono, two types of parameters were changed:

• 1. Robot parameters, or those that would always have to change due to differences in the robots/systems we are using.
• 2. Tunable parameters, or those that don't fall in the category above.

Below we document all parameters that were changed in both categories 1 & 2:

Category 1:

imu_topic, image_topic, output_path, image_width, image_height, distortion_parameters, projection_parameters, extrinsicRotation, extrinsicTranslation, acc_n, gyr_n, acc_w, gyr_w, pose_graph_save_path, support_path

Category 2:

loop_closure, freq

For reasons for changes in category 2, see the corresponding .yaml files.

6. VINS-MONO-ROS2 on HERCULES Dataset (Australia Environment)

First, absolute paths in files in tmux/HERCULES/tmuxp_launch.py and config_pkg/config/hercules/ will need to be updated.

Then, run the following command to run VINS-Mono on a robot trajectory for the HERCULES dataset:

source install/setup.bash
python3 src/VINS-MONO-ROS2/tmux/HERCULES/tmuxp_launch.py <version_number> <robot_name> <use_rosbag_play>

To run a sweep of the IMU noise parameters, run the following commands:

source install/setup.bash
wandb sweep -e <entity> -p <project> src/VINS-MONO-ROS2/research/sweep.yaml
wandb agent '<entity>/<project>/<sweep_id>'

Note on Parameters

Here are the parameters changed in categories 1 & 2 (referring to same categories from GRaCo dataset in Section 5 above):

Category 1:

imu_topic, image_topic, output_path, distortion_parameters, projection_parameters, extrinsicRotation, extrinsicTranslation, pose_graph_save_path, support_path

Category 2:

freq, loop_closure