SparkVIO: Open-Source Visual Inertial Odometry

For evaluation plots, check our jenkins server.

Authors: Antoni Rosinol, Yun Chang, Marcus Abate, Sandro Berchier, Luca Carlone

What is SparkVIO?

SparkVIO is a Visual Inertial Odometry pipeline for accurate State Estimation from Stereo + IMU data. (Mono-only capabilities soon to be released).

Related Publications

We kindly ask to cite the papers below if you find this library useful:

• TODO: add latest paper.

Backend optimization is based on:

• C. Forster, L. Carlone, F. Dellaert, and D. Scaramuzza. On-Manifold Preintegration Theory for Fast and Accurate Visual-Inertial Navigation. IEEE Trans. Robotics, 33(1):1-21, 2016.

• L. Carlone, Z. Kira, C. Beall, V. Indelman, and F. Dellaert. Eliminating Conditionally Independent Sets in Factor Graphs: A Unifying Perspective based on Smart Factors. IEEE Intl. Conf. on Robotics and Automation (ICRA), 2014.

Alternatively, the Regular VIO backend, using structural regularities, is described in this paper:

• A. Rosinol, T. Sattler, M. Pollefeys, and L. Carlone. Incremental Visual-Inertial 3D Mesh Generation with Structural Regularities. IEEE Int. Conf. on Robotics and Automation (ICRA), 2019.

Demo

1. Installation

Tested on Mac, Ubuntu 14.04 & 16.04.

Prerequisites

• GTSAM >= 4.0
• OpenCV >= 3.3.1
• OpenGV
• Glog, Gflags, Gtest (installed automagically).

Note: if you want to avoid building all dependencies yourself, we provide a docker image that will install them for you. Check installation instructions in docs/sparkvio_installation.md.

Installation Instructions

Find how to install SparkVIO and its dependencies here: Installation instructions.

2. Usage

i. Euroc Dataset

Download Euroc's dataset

• Download one of Euroc's datasets, for example V1_01_easy.zip.

Datasets MH_04 and V2_03 have different number of left/right frames. We suggest using instead our version of Euroc here.

• Unzip the dataset to your preferred directory, for example, in ~/Euroc/V1_01_easy:

mkdir -p ~/Euroc/V1_01_easy
unzip -o ~/Downloads/V1_01_easy.zip -d ~/Euroc/V1_01_easy

Yamelize Euroc's dataset

Add %YAML:1.0 at the top of each .yaml file inside Euroc. You can do this manually or run the yamelize.bash script by indicating where the dataset is (it is assumed below to be in ~/path/to/euroc):

cd SparkVIO
bash ./scripts/euroc/yamelize.bash -p ~/path/to/euroc

Run SparkVIO in Euroc's dataset

Using a bash script bundling all command-line options and gflags:

cd SparkVIO
./scripts/stereoVIOEuroc.bash -p "PATH_TO_DATASET/V1_01_easy"

Alternatively, one may directly use the executable in the build folder: ./build/stereoVIOEuroc. Nevertheless, check the script ./scripts/stereoVIOEuroc.bash to understand what parameters are expected, or check the parameters section below.

ii. Kitti Dataset

Download Kitti's dataset

• Download raw data from Kitti (in order to have IMU messages). For example:
  • Download unsynced + unrectified raw dataset (e.g. 2011_09_26_drive_0005_extract).
  • Download as well the calibration data (three files) from raw dataset (e.g. 2011_09_26_calib), and save them inside the folder 2011_09_26.

Run SparkVIO in Kitti's dataset

• Run:

  cd SparkVIO
  ./scripts/stereoVIOEuroc.bash -p "PATH_TO_DATASET/2011_09_26_drive_0005_extract" -d 1

  where you specify the path to the dataset (e.g. path to 2011_09_26_drive_0005_extract folder).

iii. Using ROS wrapper

We provide a ROS wrapper of SparkVIO that you can find at: https://github.mit.edu/SPARK/spark_vio_ros.

This library can be cloned into a catkin workspace and built alongside the ROS wrapper.

3. Parameters

SparkVIO accepts two sources of parameters:

• YAML files: contains parameters for Backend and Frontend.
• gflags contains parameters for all the rest.

To get help on what each gflag parameter does, just run the executable with the --help flag: ./build/stereoVIOEuroc --help. You should get a list of gflags similar to the ones here.

• Optionally, you can try the VIO using structural regularities, as in Toni's thesis, by specifying the option -r: ./stereoVIOEuroc.bash -p "PATH_TO_DATASET/V1_01_easy" -r

Also, check tips for usage for interacting with OpenCV's 3D visualizer.

4. Contribution guidelines

We follow the branch, open PR, review, and merge workflow.

To contribute to this repo, ensure your commits pass the linter pre-commit checks. To enable these checks you will need to install linter. We also provide a .clang-format file with the style rules that the repo uses, so that you can use clang-format to reformat your code.

Also, check tips for development and our developer guide

6. FAQ

1. Gflags

Q: I have added/changed a gflag but it has no effect?

A: Mind that according to gflags specs:

If a flag is specified more than once, only the last specification is used; the others are ignored.

2. Euroc dataset

Q: Frame mismatch in Euroc? Seeing this error msg:

  W0911 10:22:30.347504 27725 ETH_parser.cpp:520] Different number of images in left and right camera!
  Left: 2033
  Right: 2032

A: Euroc has datasets with mismatching number of frames, use instead our dataset files here.

7. Chart

8. BSD License

SparkVIO is open source under the BSD license, see the LICENSE.BSD file.