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 provides dedicated test nodes for the KITTI benchmark that read image sequences directly from disk rather than from a ROS bag. Two distinct workflows are available: stereo odometry evaluation against the KITTI Odometry Benchmark, and GPS-fused localization using KITTI raw data. As of January 2019, VINS-Fusion ranked first among open-source stereo algorithms on the KITTI Odometry Benchmark.

​
KITTI Odometry (stereo, no IMU)

This workflow evaluates pure stereo visual odometry on the KITTI Odometry sequences. No IMU is used. The estimator reads left and right image frames directly from the dataset directory.
Loop closure is not used when submitting to the KITTI Odometry Benchmark. The published rankings for VINS-Fusion were produced without loop_fusion_node.

​
Download

Download the KITTI Odometry dataset and extract it to YOUR_DATASET_FOLDER. The directory structure should contain a sequences/ subdirectory with numbered sequence folders.

​
Run sequence 00

VINS-Fusion ships config files for all KITTI Odometry sequences grouped by their camera calibration:
Config fileSequences
kitti_config00-02.yaml00, 01, 02
kitti_config03.yaml03
kitti_config04-12.yaml04–12
kitti_config13-21.yaml13–21
Open two terminals: 
# Terminal 1 — visualization
roslaunch vins vins_rviz.launch

# Terminal 2 — odometry test node
rosrun vins kitti_odom_test \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_odom/kitti_config00-02.yaml \
  YOUR_DATASET_FOLDER/sequences/00/
To also run loop fusion alongside odometry evaluation: 
# Terminal 2 — loop fusion (optional)
rosrun loop_fusion loop_fusion_node \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_odom/kitti_config00-02.yaml

# Terminal 3 — odometry test node
rosrun vins kitti_odom_test \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_odom/kitti_config00-02.yaml \
  YOUR_DATASET_FOLDER/sequences/00/
Substitute the appropriate config file and sequence path for other sequences. For example, sequence 05 uses kitti_config04-12.yaml and sequences/05/.

​
Docker

# KITTI Odometry — sequence 00
./run.sh -k \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_odom/kitti_config00-02.yaml \
  YOUR_DATASET_FOLDER/sequences/00/

# With loop fusion
./run.sh -kl \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_odom/kitti_config00-02.yaml \
  YOUR_DATASET_FOLDER/sequences/00/

​
KITTI GPS Fusion (stereo + GPS)

This workflow uses KITTI raw data, which includes GPS measurements in addition to stereo images. The global_fusion_node fuses VIO output with GPS fixes to produce a globally consistent trajectory.

​
Download

Download the KITTI raw dataset and extract it to YOUR_DATASET_FOLDER. The examples below use the 2011_10_03_drive_0027_synced recording.

​
Run GPS fusion

Three processes must run concurrently: RViz, the VINS GPS test node, and the global fusion node. 
# Terminal 1 — visualization
roslaunch vins vins_rviz.launch

# Terminal 2 — GPS test node
rosrun vins kitti_gps_test \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_raw/kitti_10_03_config.yaml \
  YOUR_DATASET_FOLDER/2011_10_03_drive_0027_sync/

# Terminal 3 — global fusion node
rosrun global_fusion global_fusion_node
global_fusion_node must be running before or immediately after kitti_gps_test starts. If it starts late, early GPS measurements will be missed and the fused path may be inconsistent.

​
Docker

./run.sh -kg \
  ~/catkin_ws/src/VINS-Fusion/config/kitti_raw/kitti_10_03_config.yaml \
  YOUR_DATASET_FOLDER/2011_10_03_drive_0027_sync/

​
RViz visualization

ColorSource
GreenVIO odometry from kitti_gps_test
BlueGPS-fused odometry from global_fusion_node

​
Car demonstration (vi_car bag)

VINS-Fusion includes a real-world car demonstration recorded with a stereo camera and IMU mounted on a vehicle. Download the car bag to YOUR_DATASET_FOLDER, then run: 
# Terminal 1 — visualization
roslaunch vins vins_rviz.launch

# Terminal 2 — VIO estimator
rosrun vins vins_node ~/catkin_ws/src/VINS-Fusion/config/vi_car/vi_car.yaml

# Terminal 3 — loop closure (optional)
rosrun loop_fusion loop_fusion_node ~/catkin_ws/src/VINS-Fusion/config/vi_car/vi_car.yaml

# Terminal 4 — play the bag
rosbag play YOUR_DATASET_FOLDER/car.bag
The vi_car.yaml config uses stereo cameras with IMU (imu: 1, num_of_cam: 2) and subscribes to /cam0/image_raw, /cam1/image_raw, and /imu0. The color coding is the same as EuRoC: green for VIO odometry, red for loop-closure-corrected odometry.
To run VINS-Fusion on your own vehicle hardware, use vi_car.yaml as a starting template and see the custom device setup guide for how to adapt the config file.

Build docs developers (and LLMs) love

Get started for freeTalk to us