OpenVSLAM: A Versatile Visual SLAM Framework

Authors: Shinya Sumikura, Mikiya Shibuya, Ken Sakurada;
Affiliation: Nagoya University; Tokyo Institute of Technology; National Institute of Advanced Industrial Science and Technology
Editors: Mathias Lux and Marco Bertini

URL: https://github.com/xdspacelab/openvslam

Visual simultaneous localization and mapping (VSLAM) systems are essential for augmented reality devices, autonomous control of robots and drones, etc. However, conventional open-source visual SLAM frameworks are not designed to be called as libraries from third-party programs. To overcome this situation, we have developed OpenVSLAM [1-3], a novel visual SLAM framework, and released it as open-source software under the 2-clause BSD license.
OpenVSLAM was presented and won first place in ACM Multimedia 2019 Open Source Software Competition.

In this article, we show examples of using OpenVSLAM and hope that this encourages and enables further use of OpenVSLAM in research and development.

Installation

Detailed instructions for installation and and prerequisites are to be found in the documentation pages [2]. Please install the dependencies and build OpenVSLAM according to it. We currently support Ubuntu and macOS environments. For our following examples we also need the DBoW2 vocabulary file to be downloaded from [4].

Using OpenVSLAM on Fisheye Camera Footage

A first example of the usage of OpenVSLAM is built on data from a wide angle lens camera. First, download and unzip the file aist_living_lab_3.zip from [5].  You can find a video and a configuration file in the unzipped data set directory. For all the following examples modify the path according to your environment. 

$ ls /path/to/aist_living_lab_3
config.yaml video.mp4

Then, you can run SLAM with the following command:

$ ./run_video_slam -v /path/to/orb_vocab/orb_vocab.dbow2 -m 
/path/to/aist_living_lab_3/video.mp4 -c 
/path/to/aist_living_lab_3/config.yaml

A frame viewer and a map viewer are launched after running above command. In the frame viewer, you can check how feature points are detected:

In the map viewer, you can see estimated camera trajectory and reconstructed 3D points:

Using OpenVSLAM on Equirectangular Camera Footage

A second example of the usage of OpenVSLAM is built on data from an equirectangular camera. First, download and unzip the file aist_store_2 datasets.zip from [6].  Again, you can find a video and a configuration file in the unzipped data set directory.

$ ls /path/to/aist_store_2
config.yaml video.mp4

Then, you can run SLAM with the following command:

$ ./run_video_slam -v /path/to/orb_vocab/orb_vocab.dbow2 -m 
/path/to/aist_store_2/video.mp4 -c /path/to/aist_store_2/config.yaml

Like in the previous example a frame viewer and a map viewer will be launched. In the frame viewer, you can check how feature points are detected:

In the map viewer, you can see estimated camera trajectory and reconstructed 3D points:

Using OpenVSLAM on the EuRoC MAV Data Set

A third example is built on the EuRoC MAV dataset [7], a standard SLAM dataset captured with a stereo camera equipped on a unmanned aerial vehicle (UAV or drone). It includes eleven sequences captured in indoor scenes. We will use the Machine Hall 04 (MH04) sequence for our example.

After downloading the dataset and unzipping it you can find the following files and directories in the data set directory:

$ ls /path/to/EuRoC/MH04
body.yaml cam0 cam1 imu0 leica0 state_groundtruth_estimate0

The OpenVSLAM repository [1] includes configuration files for EuRoC MAV dataset in ./exmaple/euroc. You can run monocular SLAM with the following command:

$ ./run_euroc_slam -v /path/to/orb_vocab/orb_vocab.dbow2 -d 
/path/to/EuRoC/MH_04 -c ../example/euroc/EuRoC_mono.yaml -p output.map

For stereo SLAM, use a configuration file for stereo camera model like this:

$ ./run_euroc_slam -v /path/to/orb_vocab/orb_vocab.dbow2 -d 
/path/to/EuRoC/MH_04 -c ../example/euroc/EuRoC_stereo.yaml -p output.map

Remember to modify paths according to your environment. The option -p output.map is for saving the reconstructed map after the mapping.

After the whole sequence is processed, the 3D map will be built as shown below.

Then, click the Terminate button to save the reconstructed map. You can confirm that output.map is created in the current directory.

$ ls
... output.map ...

Localization with EuRoC MAV dataset

For a final example the localization mode of OpenVSLAM based on the prebuilt map is used. More specifically, frames included in Machine Hall 05 (MH05) sequence of EuRoC MAV dataset [7] are localized based on the prebuilt map, which has been created using the Machine Hall 04 (MH04) sequence used also in the previous section. Machine Hall 04 and Machine Hall 05 were captured in the same scene, but have different camera trajectories.

First download the data and unzip it. Make sure you can see the following files and directories in the dataset directory. cam0 and cam1 are stereo images.

$ ls /path/to/EuRoC/MH05
body.yaml cam0 cam1 imu0 leica0 state_groundtruth_estimate0

The configuration files included in OpenVSLAM repository [1] can be used not only for the mapping mode but also for the localization mode. You can run localization of Machine Hall 05 sequence based on the prebuilt map (output.map) from previous example with the following command:

$ ./run_image_localization -v /path/to/orb_vocab/orb_vocab.dbow2 -i 
/path/to/EuRoC/MH_05/cam0/data -c ../example/euroc/EuRoC_mono.yaml -p output.map

The option -p output.map is for loading the prebuild map. You can confirm that images of Machine Hall 05 sequence are localized in the prebuilt map using the map viewer:

Conclusion

In this project, we have developed OpenVSLAM, a visual SLAM framework with high usability and extensibility. The software is designed to be easily used for various application scenarios of visual SLAM. It incorporates several useful functions for research and development. In this article, basic usage of OpenVSLAM is presented with sample data sets we have provided. In addition, examples of OpenVSLAM’s mapping and localization functions are presented using EuRoC MAV dataset. The authors are committed to continuously maintain this framework for the further development of computer vision, robotics, and multimedia fields.

References

[1] OpenVSLAM GitHub repository, https://github.com/xdspacelab/openvslam, accessed 2020-01-15
[2] OpenVSLAM D
ocumentation, https://openvslam.readthedocs.io/, accessed 2020-01-15
[3] OpenVSLAM demo video,
https://www.youtube.com/watch?v=Ro_s3Lbx5ms, accessed 2020-01-15
[4] DBoW2 vocabulary, https://drive.google.com/open?id=1wUPb328th8bUqhOk-i8xllt5mgRW4n84, accessed 2020-01-15
[5] Fisheye camera data set for OpenVSLAM, https://drive.google.com/open?id=1SVDsgz-ydm1pAbrdmhRQTmWhJnUl_xr8, accessed 2020-01-15
[6] Equirectangular camera data set for OpenVSLAM, https://drive.google.com/drive/folders/1A_gq8LYuENePhNHsuscLZQPhbJJwzAq4, accessed 2020-01-15
[7] EuRoC MAV Data Set, https://projects.asl.ethz.ch/datasets/doku.php?id=kmavvisualinertialdatasets, accessed 2020-01-15

Bookmark the permalink.