Getting Started » Installation Guide (ROS1 and ROS2)

ROS Dependency

Our codebase is built on top of the Robot Operating System (ROS) and has been tested building on Ubuntu 16.04, 18.04, 20.04 systems with ROS Kinetic, Melodic, and Noetic. We also recommend installing the catkin_tools build for easy ROS building. All ROS installs include OpenCV, but if you need to build OpenCV from source ensure you build the contributed modules as we use Aruco feature extraction. See the opencv_contrib readme on how to configure your cmake command when you build the core OpenCV library. We have tested building with OpenCV 3.2, 3.3, 3.4, 4.2, and 4.5. Please see the official instructions to install ROS:

• Ubuntu 16.04 ROS 1 Kinetic (uses OpenCV 3.3)
• Ubuntu 18.04 ROS 1 Melodic (uses OpenCV 3.2)
• Ubuntu 20.04 ROS 1 Noetic (uses OpenCV 4.2)
• Ubuntu 18.04 ROS 2 Dashing (uses OpenCV 3.2)
• Ubuntu 20.04 ROS 2 Galactic (uses OpenCV 4.2)

We do support ROS-free builds, but don't recommend using this interface as we have limited support for it. You will need to ensure you have installed OpenCV 3 or 4, Eigen3, and Ceres which are the only dependencies. For Ubuntu linux-based system the system dependencies are:

sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev

If ROS is not found on the system, one can use command line options to run the simulation without any visualization or cmake -DENABLE_ROS=OFF ... If you are using the ROS-free interface, you will need to properly construct the ov_msckf::VioManagerOptions struct with proper information and feed inertial and image data into the correct functions with proper buffers. The simulator binary run_simulation can give you and example on how to do this. To build without ROS installed, please refer to Installation Guide (ROS Free).

sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654
sudo apt-get update
export ROS1_DISTRO=noetic # kinetic=16.04, melodic=18.04, noetic=20.04
sudo apt-get install ros-$ROS1_DISTRO-desktop-full
sudo apt-get install python-catkin-tools # ubuntu 16.04, 18.04
sudo apt-get install python3-catkin-tools python3-osrf-pycommon # ubuntu 20.04
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev

echo "source /opt/ros/$ROS1_DISTRO/setup.bash" >> ~/.bashrc
source ~/.bashrc

echo "alias ros1_source=\"source /opt/ros/$ROS1_DISTRO/setup.bash\"" >> ~/.bashrc
echo "alias source_devel=\"source devel/setup.bash\"" >> ~/.bashrc
source ~/.bashrc

sudo apt update && sudo apt install curl gnupg lsb-release
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key  -o /usr/share/keyrings/ros-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
sudo apt-get update
export ROS2_DISTRO=galactic # dashing=18.04, galactic=20.04
sudo apt install ros-$ROS2_DISTRO-desktop
sudo apt-get install ros-$ROS2_DISTRO-ros2bag ros-$ROS2_DISTRO-rosbag2* # rosbag utilities (seems to be separate)
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev

echo "source /opt/ros/$ROS2_DISTRO/setup.bash" >> ~/.bashrc
source ~/.bashrc

echo "alias ros2_source=\"source /opt/ros/$ROS2_DISTRO/setup.bash\"" >> ~/.bashrc
echo "alias source_install=\"source install/setup.bash\"" >> ~/.bashrc
source ~/.bashrc

Cloning the OpenVINS Project

Now that we have ROS installed we can setup a catkin workspace and build the project! If you did not install the catkin_tools build system, you should be able to build using the standard catkin_make command that is included with ROS. If you run into any problems please google search the issue first and if you are unable to find a solution please open an issue on our github page. After the build is successful please following the Simple Tutorial guide on getting a dataset and running the system.

There are additional options that users might be interested in. Configure these with catkin build -D<option_name>=OFF or cmake -D<option_name>=ON .. in the ROS free case.

• ENABLE_ROS - (default ON) - Enable or disable building with ROS (see Installation Guide (ROS Free))
• ENABLE_ARUCO_TAGS - (default ON) - Enable or disable aruco tag (disable if no contrib modules)
• BUILD_OV_EVAL - (default ON) - Enable or disable building of ov_eval
• DISABLE_MATPLOTLIB - (default OFF) - Disable or enable matplotlib plot scripts in ov_eval

mkdir -p ~/workspace/catkin_ws_ov/src/
cd ~/workspace/catkin_ws_ov/src/
git clone https://github.com/rpng/open_vins/
cd ..
catkin build # ROS1
colcon build # ROS2
colcon build --event-handlers console_cohesion+ --packages-select ov_core ov_init ov_msckf ov_eval # ROS2 with verbose output

To build without ROS installed, please refer to Installation Guide (ROS Free). We recommend compiling with RelWithDebInfo as we always include -g for debug symbols. If you wish to Debug, the workspace can configure as:

catkin config --cmake-args -DCMAKE_BUILD_TYPE=Debug
catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug

Additional Evaluation Requirements

If you want to use the plotting utility wrapper of matplotlib-cpp to generate plots directly from running the cpp code in ov_eval you will need to make sure you have a valid Python 2.7 or 3 install of matplotlib. On ubuntu 16.04 you can do the following command which should take care of everything you need. If you can't link properly, make sure you can call it from Python normally (i.e. that your Python environment is not broken). You can disable this visualization if it is broken for you by passing the -DDISABLE_MATPLOTLIB=ON parameter to your catkin build. Additionally if you wish to record CPU and memory usage of the node, you will need to install the psutil library.

sudo apt-get install python2.7-dev python-matplotlib python-numpy python-psutil # for python2 systems
sudo apt-get install python3-dev python3-matplotlib python3-numpy python3-psutil python3-tk # for python3 systems
catkin build -DDISABLE_MATPLOTLIB=OFF # build with viz (default)
catkin build -DDISABLE_MATPLOTLIB=ON # build without viz

OpenCV Dependency (from source)

We leverage OpenCV for this project which you can typically use the install from ROS. If the ROS version of cv_bridge does not work (or are using non-ROS building), then you can try building OpenCV from source ensuring you include the contrib modules. One should make sure you can see some of the "contrib" (e.g. aruco) when you cmake to ensure you have linked to the contrib modules.

git clone https://github.com/opencv/opencv/
git clone https://github.com/opencv/opencv_contrib/
mkdir opencv/build/
cd opencv/build/
cmake -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules ..
make -j8
sudo make install

If you do not want to build the modules, you should also be able to do this (while it is not as well tested). The ArucoTag tracker depends on a non-free module in the contrib repository, thus this will need to be disabled. You can disable this with catkin build -DENABLE_ARUCO_TAGS=OFF or cmake -DENABLE_ARUCO_TAGS=OFF .. in your build folder.

Ceres Solver (from source)

Ceres solver [1] is required for dynamic initialization and backend optimization. Please refer to their documentation for specifics to your platform. It should be able to build on most platforms (including ARM android devices). To install we can perform the following:

sudo apt-get install -y cmake libgoogle-glog-dev libgflags-dev libatlas-base-dev libeigen3-dev libsuitesparse-dev
CERES_VERSION="2.0.0"
git clone https://ceres-solver.googlesource.com/ceres-solver
cd ceres-solver
git checkout tags/${CERES_VERSION}
mkdir build && cd build
cmake ..
make
sudo make install