Home

Awesome

DSM: Direct Sparse Mapping

Authors: Jon Zubizarreta, Iker Aguinaga, Juan D. Tardós and J. M. M. Montiel.

Contact: dsm (at) unizar (dot) es

DSM is a novel approach to monocular SLAM. It is a fully direct system that estimates the camera trajectory and a consistent global map. Is is able to detect and handle map point reobservations when revisiting already mapped areas using the same photometric model and map points. We provide examples to run the SLAM system in the EuRoC dataset and with custom videos. We also provide an optional GUI for 3D visualization of the system results.

<a href="https://youtu.be/sj1GIF-7BYo" target="_blank"><img src="http://img.youtube.com/vi/sj1GIF-7BYo/0.jpg" alt="DSM" width="240" height="180" border="10" /></a>

1. Related Publications

2. Installation

We tested DSM int two different system configurations: Ubuntu 18.04 and Windows 10 (VS15 and VS17). It should be easy to compile in other platforms. See below for experimental macOS support. The library requires at least C++11.

Clone the repository:

git clone https://github.com/jzubizarreta/dsm.git

2.1 Required Dependencies

Eigen3

We use Eigen3 for almost any mathematical operation.

Install with

sudo apt-get install libeigen3-dev

OpenCV

We use OpenCV to manipulate images (read/write/display) and to bootstrap the monocular system. Feel free to implement those functionalities with your prefered library, if you want to get rid off Opencv.

Install with

sudo apt-get install libopencv-dev

Ceres Solver

We use Ceres Solver to perform the photometric bundle adjustment. In addition to the standard installation process, we generate a custom template specialization corresponding to our Schur structure, which speeds up the Schur elimination step. This is an optional step that can be skipped.

git clone https://ceres-solver.googlesource.com/ceres-solver

Ceres dependencies:

# glog & gflags
sudo apt-get install libgoogle-glog-dev

# BLAS & LAPACK
sudo apt-get install libatlas-base-dev

# SuiteSparse
sudo apt-get install libsuitesparse-dev

Generate the custom template specialization (optional):

cp ./dsm/thirdparty/Ceres/generate_template_specializations.py ./ceres-solver/internal/ceres/
python2 ceres-solver/internal/ceres/generate_template_specializations.py

Install with

cd ceres-solver
mkdir build
cd build
cmake ..
make -j4
sudo make install

2.2 Optional Dependencies

Qt

We use Qt for GUI and visualization. Although Qt is required to compile the whole project in the current version, it is easy to remove it. DSM does not depend on Qt. All the code related with Qt is in the QtVisualizer folder. Feel free to implement your own version of IVisualizer and replace the current visualizer QtVisualizer.

Install with

sudo apt-get install qt5-default

2.3 DSM build

Now we are ready to build DSM. Execute:

cd ../../dsm
mkdir build
cd build
cmake ..
make -j4

This will compile two libraries libdsm.so and libQtVisualizer.so at lib folder, which can be linked from external projects. It will also create two executables EurocExample and VideoExample at bin folder to run DSM in the EuRoC dataset and with custom videos respectively.

2.4 macOS

Support for macOS is experimental and not extensively tested, but in principle DSM including the GUI should be functional.

External dependencies on macOS can be installed with Homebrew

brew install cmake eigen opencv ceres-solver qt

From this point, you can follow the instructions above for 2.3 DSM build.

Note: In some cases, the Qt5 installation location is not automatically found and you need to specify the modules manually to cmake with

cmake -DQt5Core_DIR="$(brew --prefix qt5)/lib/cmake/Qt5Core" -DQt5Widgets_DIR="$(brew --prefix qt5)/lib/cmake/Qt5Widgets" -DQt5OpenGL_DIR="$(brew --prefix qt5)/lib/cmake/Qt5OpenGL" ..

3. Usage

3.1 Calibration format

DSM requires the geometric calibration of the camera as an input. Currently it uses the radial-tangential model of OpenCV. However, it should be easy to add new camera models. Take a look at Unidistorter.h.

The calibration file has the format

fx fy cx cy k1 k2 p1 p2
in_width in_height
out_width out_height

It is also possible to use higher order distortion models. You have to add the additional distortion coefficients using the OpenCV order. If no distortion coefficients are provided, they are assumed to be zero.

3.2 EuRoC Example

  1. Download a sequence (ASL format) from https://projects.asl.ethz.ch/datasets/doku.php?id=kmavvisualinertialdatasets.

  2. Extract the sequence in a folder <SEQ_FOLDER>.

  3. Run the executable with the following arguments

./EurocExample <IMAGE_FOLDER> <TIMESTAMPS_FILE> <CALIB_FILE> <SETTINGS_FILE>

where

The <IMAGE_FOLDER> can be usually found in <SEQ_FOLDER>/mav0/camX/data, where the X indicates if the left (0) or right (1) camera is used. The specific <TIMESTAMPS_FILE>, <CALIB_FILE> and <SETTINGS_FILE> for the EuRoC dataset are provided in Examples/EurocData.

3.3 Video Example

It is also possible to run your own custom videos with known camera calibration. Run the executable as

./VideoExample <VIDEO_FILE> <CALIB_FILE> <SETTINGS_FILE>

where

4. Parameter options

The system parameter options can be found in settings.h. Those can also be loaded using an external .txt file, such as the one in Examples/EurocData/settings.txt. The most relevant parameters are:

5. License

DSM is released under a GPLv3 license. For a list of all code/library dependencies (and associated licenses), please see Dependencies.md.

For a closed-source version of DSM for commercial purposes, please contact the authors.

If you use DSM in an academic work, please cite:

@article{Zubizarreta2020,
  title={Direct Sparse Mapping},
  author={Zubizarreta, Jon, Aguinaga, Iker and Montiel, J. M. M.},
  journal={IEEE Transactions on Robotics},
  doi = {10.1109/TRO.2020.2991614},
  year={2020}
 }