Documentation Index
Fetch the complete documentation index at: https://mintlify.com/rpng/open_vins/llms.txt
Use this file to discover all available pages before exploring further.
OpenVINS can be built in three modes: against ROS 1 (Kinetic, Melodic, Noetic), against ROS 2 (Dashing, Galactic), or entirely without ROS as a standalone library. All three paths share the same core dependencies — OpenCV (3.x or 4.x), Eigen3, and Ceres solver — but differ in how the workspace is set up and the system is built. The ROS paths are recommended for most users because they provide ready-made launch files, rosbag playback, and RViz visualization.
Install ROS 1
OpenVINS has been tested on Ubuntu 16.04 (Kinetic), 18.04 (Melodic), and 20.04 (Noetic). The instructions below target Noetic on 20.04; adjust the distro variable for older systems.Add the ROS apt repository
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
Install ROS 1 and core dependencies
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 python3-catkin-tools python3-osrf-pycommon # Ubuntu 20.04
# For Ubuntu 16.04 / 18.04 use: python-catkin-tools
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev
Source ROS 1 on every terminal
If ROS 1 is your only ROS install, add a permanent source to your shell: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
# Run `ros1_source` whenever you open a new terminal for ROS 1 work.
Create a catkin workspace and clone OpenVINS
mkdir -p ~/workspace/catkin_ws_ov/src/
cd ~/workspace/catkin_ws_ov/src/
git clone https://github.com/rpng/open_vins/
cd ..
Build the workspace
To build in Debug mode:catkin build --cmake-args -DCMAKE_BUILD_TYPE=Debug
Install ROS 2
OpenVINS supports ROS 2 Dashing (Ubuntu 18.04) and Galactic (Ubuntu 20.04). The instructions below target Galactic.Add the ROS 2 apt repository
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
Install ROS 2 and core dependencies
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*
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev
Source ROS 2 on every terminal
If ROS 2 is your only ROS install: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
# Run `ros2_source` whenever you open a new terminal for ROS 2 work.
Create a colcon workspace and clone OpenVINS
mkdir -p ~/workspace/catkin_ws_ov/src/
cd ~/workspace/catkin_ws_ov/src/
git clone https://github.com/rpng/open_vins/
cd ..
Build the workspace
To build with verbose per-package output and select specific packages:colcon build --event-handlers console_cohesion+ \
--packages-select ov_core ov_init ov_msckf ov_eval
colcon build --cmake-args -DCMAKE_BUILD_TYPE=Debug
Install standalone (no ROS)
The ROS-free path builds and installs OpenVINS as a shared library (libov_msckf_lib.so) that you can link against from any CMake project. ROS visualization and rosbag playback are not available in this mode.Install system dependencies
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev
Clone and build ov_msckf
cd ~/github/
git clone https://github.com/rpng/open_vins/
cd open_vins/ov_msckf/
mkdir build && cd build
cmake -DENABLE_ROS=OFF ..
make -j4
sudo make install
/usr/local/lib/libov_msckf_lib.so and headers to /usr/local/include/open_vins/.Link from your own CMake project
Add the following to your project’s CMakeLists.txt:# headers: /usr/local/include/open_vins/
# library: /usr/local/lib/libov_msckf_lib.so
set(OPENVINS_INCLUDE_DIR /usr/local/include/open_vins/)
set(OPENVINS_LIBRARIES ov_msckf_lib)
target_include_directories(your_binary PUBLIC
${CMAKE_CURRENT_SOURCE_DIR}
${EIGEN3_INCLUDE_DIR}
${BOOST_INCLUDE_DIR}
${OPENVINS_INCLUDE_DIR}
)
target_link_libraries(your_binary PRIVATE
${CERES_LIBRARIES}
${OPENVINS_LIBRARIES}
)
In ROS-free mode you must construct the VioManagerOptions struct manually and feed inertial and image data directly into the appropriate API calls. The run_simulation binary is a working example of this pattern.
Build options
All three build paths accept the same CMake flags. Pass them with catkin build -D<flag>=VALUE, colcon build --cmake-args -D<flag>=VALUE, or cmake -D<flag>=VALUE ...
| Flag | Default | Description |
|---|
ENABLE_ROS | ON | Enable or disable the ROS build. Set to OFF for the standalone build. |
ENABLE_ARUCO_TAGS | ON | Enable ArUco tag SLAM features. Requires OpenCV contrib modules. |
BUILD_OV_EVAL | ON | Build the ov_eval evaluation package. |
DISABLE_MATPLOTLIB | OFF | Disable matplotlib-based plot generation in ov_eval. |
Evaluation dependencies (ov_eval)
The ov_eval package can generate plots directly from C++ using the matplotlib-cpp wrapper. Install the Python dependencies matching your system:
# Python 3 systems (Ubuntu 20.04 / ROS Noetic)
sudo apt-get install python3-dev python3-matplotlib python3-numpy python3-psutil python3-tk
# Python 2 systems (Ubuntu 16.04 / 18.04)
sudo apt-get install python2.7-dev python-matplotlib python-numpy python-psutil
catkin build -DDISABLE_MATPLOTLIB=OFF # build with visualization (default)
catkin build -DDISABLE_MATPLOTLIB=ON # build without visualization
OpenCV from source
Try the system or ROS-provided OpenCV first. Build from source only if you cannot compile (e.g., you need ArUco support but have no contrib modules, or need a newer version). OpenVINS has been tested with OpenCV 3.2, 3.3, 3.4, 4.2, and 4.5.
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
catkin build -DENABLE_ARUCO_TAGS=OFF
# or for cmake builds:
cmake -DENABLE_ARUCO_TAGS=OFF ..
Ceres solver from source
Install Ceres from apt first with sudo apt-get install libceres-dev. Build from source only if you encounter an Eigen version mismatch error such as: "Failed to find Ceres - Found Eigen dependency, but the version of Eigen found (3.3.7) does not exactly match the version of Eigen Ceres was compiled with (3.3.4)."
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
Next steps
Once the build succeeds, follow the Tutorial to download the EuRoC MAV dataset and run your first estimation.