Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HKUST-Aerial-Robotics/Vins-Fusion/llms.txt

Use this file to discover all available pages before exploring further.

Before building VINS-Fusion, you need a compatible Ubuntu environment with ROS and a set of C++ libraries. The core dependencies are ROS (which bundles OpenCV and Eigen), and Ceres Solver for nonlinear optimization. Meeting the hardware recommendations below will also have a direct impact on the quality of your state estimates.

​
Supported operating systems

VINS-Fusion targets Ubuntu 64-bit 16.04 (Xenial) or Ubuntu 64-bit 18.04 (Bionic). Other distributions or architectures are not officially supported.
Ubuntu versionROS distribution
16.04 XenialROS Kinetic
18.04 BionicROS Melodic

​
Dependencies overview

ROS Kinetic / Melodic

Middleware layer that also provides OpenCV and Eigen. Required for all VINS-Fusion nodes.

Ceres Solver

Google’s nonlinear least-squares optimizer. VINS-Fusion uses Ceres for the sliding-window bundle adjustment at the core of the VIO pipeline.

OpenCV

Computer vision library used for feature tracking and image processing. Installed automatically as part of ROS.

Eigen 3

C++ linear algebra library used throughout the estimator. Installed automatically as part of ROS.

​
Dependency installation

1

Install ROS

Follow the official installation guide at wiki.ros.org/ROS/Installation for your Ubuntu version:
  • Ubuntu 16.04 — install ROS Kinetic
  • Ubuntu 18.04 — install ROS Melodic
The ros-<distro>-desktop-full meta-package is recommended because it includes OpenCV, Eigen, and the full sensor driver stack.
# Example for ROS Melodic on Ubuntu 18.04
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
sudo apt-get install ros-melodic-desktop-full
OpenCV and Eigen 3 ship with the desktop-full install. You do not need to build or install them separately.
2

Install Ceres Solver build dependencies

Ceres requires several system libraries before it can be compiled. These match what the VINS-Fusion Docker build installs:
sudo apt-get update
sudo apt-get install -y \
  cmake \
  libatlas-base-dev \
  libeigen3-dev \
  libgoogle-glog-dev \
  libsuitesparse-dev
3

Build and install Ceres Solver

Follow the full instructions at ceres-solver.org/installation.html. The VINS-Fusion Docker environment uses Ceres 1.12.0, which is a known-good version:
git clone https://ceres-solver.googlesource.com/ceres-solver
cd ceres-solver
git checkout tags/1.12.0
mkdir build && cd build
cmake ..
make -j$(nproc)
sudo make install
On machines with many cores, make -j$(nproc) will use all available threads and significantly speed up compilation.
4

Initialize your ROS environment

Source the ROS setup script so that ROS tools and package paths are available in your shell. Add this line to your ~/.bashrc to make it permanent:
echo "source /opt/ros/melodic/setup.bash" >> ~/.bashrc
source ~/.bashrc
Replace melodic with kinetic if you are on Ubuntu 16.04.

​
Hardware recommendations

Hardware quality directly affects estimation accuracy. Poor-quality cameras or loosely synchronized IMUs will degrade or break the VIO pipeline regardless of software configuration. For reliable results, use the equipment described below.
VINS-Fusion is a visual-inertial odometry system. The README explicitly notes:
“VIO is not only a software algorithm, it heavily relies on hardware quality. For beginners, we recommend you to run VIO with professional equipment.”
Recommended hardware characteristics:
  • Global shutter cameras — rolling shutter cameras introduce motion blur and geometric distortion that corrupt feature tracking.
  • Hardware IMU synchronization — the camera and IMU timestamps must be accurately aligned. Software-only timestamp correction (which VINS-Fusion supports via online temporal calibration) cannot fully compensate for large or inconsistent hardware delays.
  • High-rate IMU — an IMU running at 200 Hz or above provides sufficient integration accuracy between camera frames.
The EuRoC MAV dataset, which is the standard benchmark for VINS-Fusion, was collected with hardware-synchronized global-shutter cameras and a 200 Hz IMU. It is a good reference point for what the system expects.

Build docs developers (and LLMs) love

Get started for freeTalk to us