Tested on Ubuntu 20.04.

If you want to avoid building all these dependencies yourself, we provide two options:

1. Docker image: that will install them for you. See section From Dockerfile below.

2. Catkin: if you use ROS, then Kimera-VIO-ROS can install all dependencies and Kimera inside a catkin workspace. Follow the instructions in there.

We recommend using the docker image for a quick demo, and catkin for actual development. Alternatively, you may install the dependencies and Kimera from "source" as detailed below:

• Third-party dependencies:

  • GTSAM >= 4.1
  • OpenCV >= 3.4
  • OpenGV
  • Glog, Gflags, Gtest (installed automagically).
  • DBoW2
  • Kimera-RPGO

Installation instructions below.

First, update package list: sudo apt-get update

• Build dependencies:

sudo apt-get install -y --no-install-recommends apt-utils
sudo apt-get install -y cmake

• Gtsam dependencies:

sudo apt-get install -y libboost-all-dev

• OpenCV dependencies:
  • on Mac:

brew install vtk

• On Ubuntu 20.04

# (libvtk5-dev, libgtk2.0-dev in ubuntu 16.04)
sudo apt-get install -y \
      build-essential unzip pkg-config \
      libjpeg-dev libpng-dev libtiff-dev \
      libvtk7-dev \
      libgtk-3-dev \
      libparmetis-dev \
      libatlas-base-dev gfortran

Install Intel Threaded Building Blocks (TBB): sudo apt-get install libtbb-dev

Clone GTSAM: git clone [email protected]:borglab/gtsam.git

(last tested with release 4.2)

Make build dir, and run cmake:

cd gtsam
git checkout 4.2
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release -DGTSAM_USE_SYSTEM_EIGEN=ON -DGTSAM_POSE3_EXPMAP=ON -DGTSAM_ROT3_EXPMAP=ON -DGTSAM_TANGENT_PREINTEGRATION=OFF ..

Ensure that:

• TBB is enabled: check for -- Use Intel TBB : Yes after running cmake.
• Compilation is in Release mode: check for -- Build type : Release after running cmake.
• Use GTSAM's Eigen, not the system-wide one (OpenGV and GTSAM must use same Eigen, see OpenGV install instructions below).
• Rot3 retract is full ExpMap is set to enabled, and Pose3 retract is full ExpMap is also set to enabled. Without these flags, Kimera-RPGO does not optimize the pose-graph well and may produce incorrect results.

Compile and install GTSAM:

make -j $(nproc) check # (optional, runs unit tests)
sudo make -j $(nproc) install

Alternatively, replace $(nproc) by the number of available cores in your computer.

Note 1a: if you use MKL in gtsam, you may need to add to ~/.bashrc a line similar to: source /opt/intel/parallel_studio_xe_2018/compilers_and_libraries_2018/linux/mkl/bin/mklvars.sh intel64 (Alternatively, type locate compilervars.sh and then source $output file.sh that you got from locate$, add to your .bashrc to automate).

Note 1b: sometimes you may need to add /usr/local/lib to LD_LIBRARY_PATH in ~/.bashrc (if you get lib not found errors at run or test time).

Note: we are considering to enable EPI in GTSAM, which will require to set the GTSAM_THROW_CHEIRALITY_EXCEPTION to false (cmake flag).

Note: for better performance when using the IMU factors, set GTSAM_TANGENT_PREINTEGRATION to 'false' (cmake flag)

Note: GTSAM_BUILD_WITH_MARCH_NATIVE is on by default which means that Kimera-VIO inherits -march=native as a build option. If you build with the option GTSAM_BUILD_WITH_MARCH_NATIVE=OFF, you will also have to build opengv without -march=native to avoid alignment issues between Kimera-VIO and opengv.

Note that you can use apt-get install libopencv-dev libopencv-contrib-dev on 20.04 instead of building from source.

Download OpenCV and run cmake:

git clone https://github.com/opencv/opencv.git
cd opencv
git checkout tags/4.2  # 3.4 or higher should be fine
mkdir build
cd build
cmake -DWITH_VTK=On .. # Use -DWITH_TBB=On if you have TBB

Finally, build and install OpenCV:

sudo make -j $(nproc) install

Alternatively, replace $(nproc) by the number of available cores in your computer.

Sometimes VTK is not correctly detected when running OpenCV cmake: if you see -- VTK is not found in the cmake trace (a somewhat common issue on mac), consider going back and reinstalling VTK from source as follows. Clone VTK from https://gitlab.kitware.com/vtk/vtk and check-out tag 7.1.0. In the VTK folder execute:

brew uninstall vtk # uninstall other vtk versions
mkdir build
cd build
sudo make -j $(nproc) install

Finally, go to the OpenCV build folder and build and install OpenCV:

cmake -DWITH_VTK=On .. # now VTK should be correctly detected, Use -DWITH_TBB=On if you have TBB
sudo make -j $(nproc) install

Another common issue on mac is that OpenCV may not compile from source due to ffmpeg version issues. In that case, a potential solution is this (borrowed from this stackoverflow page): copy-paste the following 3 lines at the top of opencv-3.3.0/modules/videoio/src/cap_ffmpeg_impl.hpp:

#define AV_CODEC_FLAG_GLOBAL_HEADER (1 << 22)
#define CODEC_FLAG_GLOBAL_HEADER AV_CODEC_FLAG_GLOBAL_HEADER
#define AVFMT_RAWPICTURE 0x0020

after which OpenCV should compile.

Clone the repo:

git clone https://github.com/laurentkneip/opengv.git

Set opengv to use the same Eigen version than GTSAM (for example: $HOME/gtsam/gtsam/3rdparty/Eigen), by modifying the cmake flags EIGEN_INCLUDE_DIR and EIGEN_INCLUDE_DIRS. If you don't do so, errors may appear (maybe due to GTSAM and OpenGV using different versions of Eigen!) Note that if using cmake-gui to modify paths, make sure you tick the Advanced box so that both flags are visible:

cd opengv
mkdir build
cd build
# Replace path to your GTSAM's Eigen
cmake .. -DEIGEN_INCLUDE_DIR=/home/tonirv/Code/gtsam/gtsam/3rdparty/Eigen -DEIGEN_INCLUDE_DIRS=/home/tonirv/Code/gtsam/gtsam/3rdparty/Eigen

Finally, install opengv:

sudo make -j $(nproc) install

Alternatively, replace $(nproc) by the number of available cores in your computer.

Clone the repo and run cmake:

git clone https://github.com/dorian3d/DBoW2.git
cd DBoW2
mkdir build
cd build
cmake ..
sudo make -j $(nproc) install

Clone the repo and run cmake:

git clone https://github.com/MIT-SPARK/Kimera-RPGO.git
cd Kimera-RPGO
mkdir build
cd build
cmake ..
sudo make -j $(nproc)

Linux

sudo apt-get install libgflags-dev libgoogle-glog-dev

MacOS

brew install gflags glog

Gtest will be automatically downloaded using cmake.

For loop closure detection, we use a bag-of-words method based on DBoW2. This requires a vocabulary of visual words. If you wish to use the loop closure detection module, you must download a vocabulary file.

We have packaged a large vocabulary made by the creators of ORB_SLAM_2 along with their license at this location. Follow that link to download the files, and put them in the vocabulary directory.

Alternatively, cmake will automatically download these files for you when you make Kimera-VIO. Follow the instructions below:

Before proceeding, ensure all dependencies are installed or use the provided dockerfile.

Clone this repository:

git clone [email protected]:MIT-SPARK/Kimera-VIO.git Kimera-VIO

Build Kimera-VIO

cd Kimera-VIO
mkdir build
cd build
cmake ..
make -j $(nproc)

Alternatively, replace '$(nproc)' by the number of available cores in your computer.

If you want to avoid building all these dependencies yourself, we provide a docker image that will install all dependencies for you. For that, you will need to install Docker.

Once installed, clone this repo, build the image and run it:

# Clone the repo
git clone [email protected]:MIT-SPARK/Kimera-VIO.git Kimera-VIO

# Build the image
cd Kimera-VIO
docker build --rm -t kimera_vio -f ./scripts/docker/Dockerfile . 

This may take a while (>15min), so you can go and grab a cup of coffee. Once done, you can run the kimera_vio_docker.bash:

# Run an example dataset
./scripts/docker/kimera_vio_docker.bash

Make sure to give the docker container access to datasets to run on Kimera by adding a volume. For example, add the following line to the script:

--volume="/data/datasets/Euroc:/data/datasets/Euroc" \