Docker provides a sandboxed environment that makes VINS-Fusion environment-independent, removing the need to manually install Ceres Solver and ROS dependencies on the host machine. The providedDocumentation 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.
Dockerfile builds on ros:kinetic-perception, installs Ceres 1.12.0, and compiles VINS-Fusion using catkin build. The companion run.sh script in docker/ handles launching roscore, RViz, and the correct VINS nodes based on the flags you pass, while mounting your local VINS-Fusion source directory into the container so code changes take effect immediately without rebuilding the image.
Prerequisites
- Docker installed and running. See the Docker CE installation guide for Ubuntu.
- ROS installed on the host (the
run.shscript startsroscoreand RViz on the host, not inside the container). - Your user account added to the
dockergroup (see Permission fix below).
Building the Docker Image
Navigate to thedocker/ subdirectory and run make build. This builds the image tagged as ros:vins-fusion using the Dockerfile located one directory up:
catkin build -DCMAKE_BUILD_TYPE=Release. Depending on your machine and network connection, this step can take 15–30 minutes.
To remove the image when you no longer need it:
Running VINS-Fusion with run.sh
After the image is built, use run.sh to start an estimation session. The script:
- Starts
roscoreon the host. - Opens RViz with the bundled
config/vins_rviz_config.rvizlayout. - Runs a Docker container with
--net=hostand mounts your local VINS-Fusion directory into the container at/root/catkin_ws/src/VINS-Fusion/, so any edits you make on the host are immediately visible inside the container. - Inside the container, runs
catkin build(using cached configuration) and then launches the appropriate ROS node.
Flags
| Flag | Mode | Nodes launched inside container |
|---|---|---|
| (none) | EuRoC mono or stereo | rosrun vins vins_node <config> |
-l | Loop fusion enabled | loop_fusion_node + vins_node |
-k | KITTI odometry | rosrun vins kitti_odom_test <config> <dataset> |
-kl | KITTI + loop fusion | loop_fusion_node + kitti_odom_test |
-kg | KITTI + GPS global fusion | global_fusion_node + kitti_gps_test |
-g | Global fusion (KITTI GPS) | rosrun global_fusion global_fusion_node |
-h | Help | Prints usage and exits |
Usage Examples
EuRoC monocular camera + IMU:Permission Fix
If you see aPermission denied error when running make build or ./run.sh, your user is not yet in the docker group. Fix this with:
Iterating on Code
Becauserun.sh mounts your local VINS-Fusion source tree directly into the container, you do not need to rebuild the Docker image after making code changes. The container re-runs catkin build each time run.sh is invoked, picking up any modifications. Simply re-run the appropriate ./run.sh command after editing source files.