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 structured as three independent ROS nodes — vins_node (the core VIO estimator), loop_fusion_node (place recognition and pose graph optimization), and global_fusion_node (GPS-fused global odometry). Each node has a defined set of subscribed and published topics. Understanding these interfaces is essential for integrating VINS-Fusion with your own sensor stack, recording the right topics for post-processing, or connecting downstream navigation software.
vins_node (rosrun vins vins_node)
Subscribed Topics
| Topic | Type | Notes |
|---|
IMU_TOPIC | sensor_msgs/Imu | Configured via imu_topic in the YAML config (e.g. /imu0). Subscribed only when imu: 1 in config. Queue depth 2000, TCP no-delay hint applied. |
IMAGE0_TOPIC | sensor_msgs/Image | Left (or mono) camera image. Configured via image0_topic in the YAML config. Queue depth 100. Accepts mono8 or 8UC1 encoding. |
IMAGE1_TOPIC | sensor_msgs/Image | Right camera image for stereo. Configured via image1_topic. Queue depth 100. Subscribed only when num_of_cam: 2 (stereo mode). |
/feature_tracker/feature | sensor_msgs/PointCloud | Pre-tracked feature points from the feature tracker node. Each point carries normalized coordinates, pixel UV, optical flow velocity, and optionally ground-truth 3D position. Queue depth 2000. |
/vins_restart | std_msgs/Bool | When true, clears the estimator state and reloads parameters — equivalent to a soft restart without killing the node. Queue depth 100. |
/vins_imu_switch | std_msgs/Bool | Dynamically enables (true) or disables (false) IMU integration at runtime by calling estimator.changeSensorType. Queue depth 100. |
/vins_cam_switch | std_msgs/Bool | Dynamically switches between stereo (true) and monocular left-camera-only (false) mode at runtime. Queue depth 100. |
Published Topics
All topics are published under the vins_estimator namespace (the node’s private namespace ~). With the default rosrun invocation the full topic paths are:
| Topic | Type | Notes |
|---|
/vins_estimator/odometry | nav_msgs/Odometry | Body-frame pose (position + orientation + linear velocity) in the world frame. Published only when the solver is in NON_LINEAR (fully initialized) state. |
/vins_estimator/imu_propagate | nav_msgs/Odometry | High-rate odometry propagated by IMU integration between vision updates. Published on every IMU message. |
/vins_estimator/path | nav_msgs/Path | Accumulated trajectory of all NON_LINEAR state estimates. Frame ID world. |
/vins_estimator/point_cloud | sensor_msgs/PointCloud | Triangulated 3D landmarks in the world frame for the current sliding window (used by features seen in ≥2 frames and not yet marginalized). |
/vins_estimator/margin_cloud | sensor_msgs/PointCloud | 3D landmarks that are about to be marginalized out of the sliding window. Useful for building a longer-horizon map for visualization. |
/vins_estimator/key_poses | visualization_msgs/Marker | SPHERE_LIST marker showing the positions of all keyframes in the current sliding window. Colored red. |
/vins_estimator/camera_pose | nav_msgs/Odometry | Pose of the left camera in the world frame (derived from body pose + extrinsic calibration tic[0], ric[0]). |
/vins_estimator/camera_pose_visual | visualization_msgs/MarkerArray | 3D camera frustum visualization for RViz. Includes both cameras in stereo mode. |
/vins_estimator/keyframe_pose | nav_msgs/Odometry | Pose of the keyframe at WINDOW_SIZE - 2 when a marginalization event occurs. Consumed by loop_fusion_node. |
/vins_estimator/keyframe_point | sensor_msgs/PointCloud | 3D points and 2D pixel coordinates associated with the keyframe pose above. Consumed by loop_fusion_node for DBoW2 loop detection. |
/vins_estimator/extrinsic | nav_msgs/Odometry | Online-calibrated camera-IMU extrinsic transform (tic[0], ric[0]), expressed as a pose. Published via pubTF every time TF is broadcast. |
/vins_estimator/image_track | sensor_msgs/Image | Debug image showing tracked feature points overlaid on the current frame. BGR8 encoding. |
loop_fusion_node (rosrun loop_fusion loop_fusion_node)
Subscribed Topics
| Topic | Type | Notes |
|---|
/vins_estimator/odometry | nav_msgs/Odometry | VIO odometry used to propagate the loop-corrected path in real time. |
image0_topic (from config) | sensor_msgs/Image | Raw camera image used to build BRIEF descriptors for DBoW2 place recognition. Topic name read from image0_topic in the YAML config. |
/vins_estimator/keyframe_pose | nav_msgs/Odometry | Keyframe pose used to create new KeyFrame objects for the pose graph. |
/vins_estimator/keyframe_point | sensor_msgs/PointCloud | 3D-2D point correspondences for the keyframe, used during PnP-based loop verification. |
/vins_estimator/extrinsic | nav_msgs/Odometry | Live extrinsic calibration used to transform poses between body and camera frames inside the pose graph. |
/vins_estimator/margin_cloud | sensor_msgs/PointCloud | Marginalized points re-published (with loop-corrected drift) for visualization. |
Published Topics
All topics are under the loop_fusion private namespace:
| Topic | Type | Notes |
|---|
/loop_fusion/match_image | sensor_msgs/Image | Debug image showing matched keypoints between the current frame and the retrieved loop-closure candidate. |
/loop_fusion/camera_pose_visual | visualization_msgs/MarkerArray | Camera frustum showing the drift-corrected camera pose in the world frame. |
/loop_fusion/point_cloud_loop_rect | sensor_msgs/PointCloud | Keyframe 3D points after drift correction from pose graph optimization. |
/loop_fusion/margin_cloud_loop_rect | sensor_msgs/PointCloud | Marginalized points after drift correction. |
/loop_fusion/odometry_rect | nav_msgs/Odometry | Loop-corrected body odometry, computed by applying the pose graph’s drift transform to the incoming VIO odometry. |
posegraph.registerPub(n) and posegraph.publish().
global_fusion_node (rosrun global_fusion global_fusion_node)
Subscribed Topics
| Topic | Type | Notes |
|---|
/vins_estimator/odometry | nav_msgs/Odometry | VIO odometry input. GPS measurements are temporally aligned to this stream with a ±10 ms tolerance. |
/gps | sensor_msgs/NavSatFix | GPS measurements (latitude, longitude, altitude + position covariance). The topic name is hardcoded as /gps. |
Published Topics
All topics are under the globalEstimator private namespace:
| Topic | Type | Notes |
|---|
/globalEstimator/global_odometry | nav_msgs/Odometry | GPS-fused global odometry in the world frame, published on every VIO callback after GPS alignment. |
/globalEstimator/global_path | nav_msgs/Path | Accumulated GPS-fused trajectory path. Frame ID world. Shown in blue in the default RViz config. |
/globalEstimator/car_model | visualization_msgs/MarkerArray | 3D car mesh visualization used in the KITTI car demonstration. |
The global fusion node does not take a config file argument and does not need one — it only requires that /vins_estimator/odometry and /gps are being published before it is started. For the KITTI GPS example, kitti_gps_test publishes /gps from the dataset’s raw GPS data.