This repository contains the ROVIO (Robust Visual Inertial Odometry) framework. The code is open-source (BSD License). Please remember that it is strongly coupled to on-going research and thus some parts are not fully mature yet. Furthermore, the code will also be subject to changes in the future which could include greater re-factoring of some parts.
Video: https://youtu.be/ZMAISVy-6ao
Papers:
- http://dx.doi.org/10.3929/ethz-a-010566547 (IROS 2015)
- http://dx.doi.org/10.1177/0278364917728574 (IJRR 2017)
Please also have a look at the wiki: https://github.com/ethz-asl/rovio/wiki
This repository is a modified version of ROVIO (see original README below). We facilitate the installation process and the use of Docker.
In order to facilitate the installation process, the system is wrapped up using Docker. We provide scripts to create a Docker image, build the system and run it in a Docker container.
- Docker
- ROS
pose_listener(if you userun_rosario_sequence.sh, see below)
Run:
./run.sh -b
This command creates a Docker image, installs all the dependencies and builds the system. The resulting image contains a version of the system ready to be run.
If you are not interested in making changes in the source code, you should run the system in VIS mode. Run:
./run.sh -v
The system is launched in a Docker container based on the previously built image. By default, this command executes a launch file which is configured to run the Rosario dataset. If you want to run your own dataset, write a launch file and placed it in the launch/ folder. Configuration files must be placed in the cfg/ folder. Then, run the script with the option -l <LAUNCH_FILE_NAME>. For example, if you are testing EuRoC, write euroc_dataset.launch, move it into launch/ and type:
./run.sh -v -l euroc_dataset.launch
Making changes in launch/configuration files in the host is possible because these folders are mounted into the Docker container. It is not necessary to access the container through a bash shell to modify these files.
See below for information about input data and visualization.
DEV mode allows developers to make changes in the source code, recompile the system and run it with the modifications. To do this, the whole repository is mounted in a container. Run:
./run.sh -d
This opens a bash shell in a docker container. You can edit source files in the host and after that you can use this shell to recompile the system. When the compilation process finishes, you can run the method using roslaunch.
See below for information about input data and visualization.
At this point, the system is waiting for input data. Either you can run rosbag play or you can use run_rosario_sequence.sh.
If you choose the latter, open a second terminal and run:
./run_rosario_sequence.sh -o <OUTPUT_TRAJECTORY_FILE> <ROSBAG_FILE>
In contrast to what run.sh does, run_rosario_sequence.sh executes commands in the host (you can modify it to use a Docker container).
ROSBAG_FILE is played using rosbag. Also, make sure you have cloned and built pose_listener in your catkin workspace. Default path for the workspace is ${HOME}/catkin_ws, set CATKIN_WS_DIR if the workspace is somewhere else (e.g.: export CATKIN_WS_DIR=$HOME/foo_catkin_ws). pose_listener saves the estimated trajectory in <OUTPUT_TRAJECTORY_FILE> (use absolute path). You can edit run_rosario_sequence.sh if you prefer to save the trajectory using your own methods. Additionally, run_rosario_sequence.sh launches rviz to display visual information during the execution of the system.
Alternatively, if you are not interested in development but in testing or visualization, instead of running run.sh and run_rosario_sequence.sh in two different terminals, you can just run:
./run_rosario_sequence.sh -r -o <OUTPUT_TRAJECTORY_FILE> <ROSBAG_FILE>
This launches a Docker container and executes the default launch file (see LAUNCH_FILE in run.sh). After that, the bagfile is played and rviz and pose_listener are launched. Add -b if you want to turn off the visualization.
Dependencies:
- ros
- kindr (https://github.com/ethz-asl/kindr)
- lightweight_filtering (as submodule, use "git submodule update --init --recursive")
#!command
catkin build rovio --cmake-args -DCMAKE_BUILD_TYPE=Release
Additional dependencies: opengl, glut, glew (sudo apt-get install freeglut3-dev, sudo apt-get install libglew-dev)
#!command
catkin build rovio --cmake-args -DCMAKE_BUILD_TYPE=Release -DMAKE_SCENE=ON
The rovio_node.launch file loads parameters such that ROVIO runs properly on the Euroc datasets. The datasets are available under: http://projects.asl.ethz.ch/datasets/doku.php?id=kmavvisualinertialdatasets
- Camera matrix and distortion parameters should be provided by a yaml file or loaded through rosparam
- The cfg/rovio.info provides most parameters for rovio. The camera extrinsics qCM (quaternion from IMU to camera frame, Hamilton-convention) and MrMC (Translation between IMU and Camera expressed in the IMU frame) should also be set there. They are being estimated during runtime so only a rough guess should be sufficient.
- Especially for application with little motion fixing the IMU-camera extrinsics can be beneficial. This can be done by setting the parameter doVECalibration to false. Please be carefull that the overall robustness and accuracy can be very sensitive to bad extrinsic calibrations.