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.

VINS-Fusion is distributed as a set of ROS packages built with catkin, the standard ROS build system. You clone the repository into the src/ directory of a catkin workspace and run catkin_make from the workspace root. All four packages — the main estimator, loop closure, GPS fusion, and camera calibration — are built in a single pass.

​
Packages built

vins_estimator

The main VIO node. Runs the sliding-window nonlinear optimizer and publishes odometry. This is the only required package.

loop_fusion

Optional loop closure node. Uses DBoW2 to detect previously visited places and correct accumulated drift in the pose graph.

global_fusion

Optional GPS fusion node. Fuses VIO odometry with GPS measurements to produce a globally consistent position estimate.

camera_models

Camera calibration tool. Supports pinhole, mei (fisheye), and equidistant models. Use this to calibrate your cameras before running the estimator on your own device.

​
Build instructions

1

Create a catkin workspace

If you already have a catkin workspace you want to use, skip to the next step.
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws
catkin_make
source ~/catkin_ws/devel/setup.bash
2

Clone VINS-Fusion into the workspace

cd ~/catkin_ws/src
git clone https://github.com/HKUST-Aerial-Robotics/VINS-Fusion.git
This creates a VINS-Fusion/ directory inside src/ containing all four ROS packages.
3

Build all packages

Run catkin_make from the workspace root, not from inside the package directory:
cd ~/catkin_ws
catkin_make
catkin resolves inter-package dependencies automatically and compiles vins_estimator, loop_fusion, global_fusion, and camera_models in the correct order.
To speed up compilation on multi-core machines, pass a job flag:
catkin_make -j$(nproc)
4

Source the workspace

After a successful build, source the workspace overlay so that ROS can find the newly built packages:
source ~/catkin_ws/devel/setup.bash
Add this line to your ~/.bashrc to source the workspace automatically in every new terminal session:
echo "source ~/catkin_ws/devel/setup.bash" >> ~/.bashrc
5

Verify the build

Confirm that the packages are registered with ROS:
rospack find vins
rospack find loop_fusion
rospack find global_fusion
rospack find camera_models
Each command should print the absolute path to the corresponding package directory inside your workspace. If a package is not found, the build did not complete successfully.

​
Common build failures

If the build fails and you cannot resolve the error, the README recommends: “try to find another computer with clean system or reinstall Ubuntu and ROS.” Dependency conflicts from previously installed library versions are the most common cause of hard-to-diagnose build failures.
The most frequent causes of build failure are:
  • Wrong Ceres version or missing Ceres — VINS-Fusion requires Ceres Solver to be installed system-wide before running catkin_make. See Prerequisites for installation steps.
  • ROS environment not sourced — make sure /opt/ros/<distro>/setup.bash is sourced before running catkin_make.
  • Conflicting system OpenCV — a manually installed OpenCV that conflicts with the ROS-bundled version can cause linker errors. The cleanest solution is to use only the OpenCV that ships with ROS.
The VINS-Fusion Docker image (docker/Dockerfile) is the canonical reference for a known-working build environment. It uses ros:kinetic-perception as the base image, installs Ceres 1.12.0 from source, and builds with catkin_make. If you encounter environment-specific issues, comparing against the Dockerfile often reveals the missing step.

​
Next steps

Once the build succeeds and the workspace is sourced, you are ready to run the estimator.

EuRoC example

Run VINS-Fusion on the EuRoC MAV dataset to verify the installation with known-good data

KITTI example

Evaluate stereo odometry on the KITTI benchmark or run GPS fusion on raw sequences

Configuration

Write a config file for your own cameras and IMU

Camera calibration

Use the bundled camera_models tool to calibrate your sensor setup

Build docs developers (and LLMs) love

Get started for freeTalk to us