Installation

Source code

The source code can be viewed from this GitHub repository.

Cloning the repository:

git clone https://github.com/xdspacelab/openvslam

If you are Windows 10 user, please install the dependencies and OpenVSLAM with SocketViewer support on Windows Subsystem for Linux (WSL). We have checked the correct operation of OpenVSLAM and SocketViewer on Ubuntu 16.04 running on WSL.

Docker systems can be used instead of preparing the dependencies manually.

Dependencies

OpenVSLAM requires a C++11-compliant compiler. It relies on several open-source libraries as shown below.

Requirements for OpenVSLAM

Eigen : version 3.3.0 or later.
g2o : Please use the latest release. Tested on commit ID 9b41a4e.
SuiteSparse : Required by g2o.
DBoW2 : Please use the custom version of DBoW2 released in https://github.com/shinsumicco/DBoW2.
yaml-cpp : version 0.6.0 or later.
OpenCV : version 3.3.1 or later.

Note

OpenCV with GUI support is necessary for using the built-in viewer (Pangolin Viewer).

Note

OpenCV with video support is necessary if you plan on using video files (e.g. .mp4) as inputs.

Requirements for PangolinViewer

We provided an OpenGL-based simple viewer.
This viewer is implemented with Pangolin. Thus, we call it PangolinViewer.
Please install the following dependencies if you plan on using PangolinViewer.

Pangolin : Please use the latest release. Tested on commit ID ad8b5f8.
GLEW : Required by Pangolin.

Requirements for SocketViewer

We provided an WebGL-based simple viewer running on web browsers.
The SLAM systems publish the map and the frame to the server implemented with Node.js via WebSocket. Thus, we call it SocketViewer.
Please install the following dependencies if you plan on using SocketViewer.

socket.io-client-cpp : Please use the custom version of socket.io-client-cpp released in https://github.com/shinsumicco/socket.io-client-cpp.
Protobuf : version 3 or later.

The following libraries are the dependencies for the server.

Node.js : version 6 or later.
npm : Tested on version 3.5.2.

Recommended

google-glog : Used for stack-trace logger.

Prerequisites for Unix

Note

In the following instruction, we assume that CMAKE_INSTALL_PREFIX is /usr/local. If you want to install the libraries to the different location, set CMAKE_INSTALL_PREFIX to your environment and set the environment variables accordingly.

Note

If your PC is frozen during the build, please reduce the number of parallel compile jobs when executing make (e.g. make -j2).

Installing for Linux

Tested for Ubuntu 16.04.

Install the dependencies via apt.

apt update -y
apt upgrade -y --no-install-recommends
# basic dependencies
apt install -y build-essential pkg-config cmake git wget curl unzip
# g2o dependencies
apt install -y libatlas-base-dev libsuitesparse-dev
# OpenCV dependencies
apt install -y libgtk-3-dev
apt install -y ffmpeg
apt install -y libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libavresample-dev
# eigen dependencies
apt install -y gfortran
# other dependencies
apt install -y libyaml-cpp-dev libgoogle-glog-dev libgflags-dev

# (if you plan on using PangolinViewer)
# Pangolin dependencies
apt install -y libglew-dev

# (if you plan on using SocketViewer)
# Protobuf dependencies
apt install -y autogen autoconf libtool
# Node.js
curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
apt install -y nodejs

Download and install Eigen from source.

cd /path/to/working/dir
wget -q http://bitbucket.org/eigen/eigen/get/3.3.4.tar.bz2
tar xf 3.3.4.tar.bz2
rm -rf 3.3.4.tar.bz2
cd eigen-eigen-5a0156e40feb
mkdir -p build && cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    ..
make -j4
make install

Download, build and install OpenCV from source.

cd /path/to/working/dir
wget -q https://github.com/opencv/opencv/archive/3.4.0.zip
unzip -q 3.4.0.zip
rm -rf 3.4.0.zip
cd opencv-3.4.0
mkdir -p build && cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DENABLE_CXX11=ON \
    -DBUILD_DOCS=OFF \
    -DBUILD_EXAMPLES=OFF \
    -DBUILD_JASPER=OFF \
    -DBUILD_OPENEXR=OFF \
    -DBUILD_PERF_TESTS=OFF \
    -DBUILD_TESTS=OFF \
    -DWITH_EIGEN=ON \
    -DWITH_FFMPEG=ON \
    -DWITH_OPENMP=ON \
    ..
make -j4
make install

Jump to Common Installation Instructions for the next step.

Installing for macOS

Tested for macOS High Sierra.

Install the dependencies via brew.

brew update
# basic dependencies
brew install pkg-config cmake git
# g2o dependencies
brew install suite-sparse
# OpenCV dependencies and OpenCV
brew install eigen
brew install ffmpeg
brew install opencv
# other dependencies
brew install yaml-cpp glog gflags

# (if you plan on using PangolinViewer)
# Pangolin dependencies
brew install glew

# (if you plan on using SocketViewer)
# Protobuf dependencies
brew install automake autoconf libtool
# Node.js
brew install node

Jump to Common Installation Instructions for the next step.

Common Installation Instructions

Download, build and install the custom DBoW2 from source.

cd /path/to/working/dir
git clone https://github.com/shinsumicco/DBoW2.git
cd DBoW2
mkdir build && cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    ..
make -j4
make install

Download, build and install g2o.

cd /path/to/working/dir
git clone https://github.com/RainerKuemmerle/g2o.git
cd g2o
git checkout 9b41a4ea5ade8e1250b9c1b279f3a9c098811b5a
mkdir build && cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DCMAKE_CXX_FLAGS=-std=c++11 \
    -DBUILD_SHARED_LIBS=ON \
    -DBUILD_UNITTESTS=OFF \
    -DBUILD_WITH_MARCH_NATIVE=ON \
    -DG2O_USE_CHOLMOD=OFF \
    -DG2O_USE_CSPARSE=ON \
    -DG2O_USE_OPENGL=OFF \
    -DG2O_USE_OPENMP=ON \
    ..
make -j4
make install

(if you plan on using PangolinViewer)

Download, build and install Pangolin from source.

cd /path/to/working/dir
git clone https://github.com/stevenlovegrove/Pangolin.git
cd Pangolin
git checkout ad8b5f83222291c51b4800d5a5873b0e90a0cf81
mkdir build && cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    ..
make -j4
make install

(if you plan on using SocketViewer)

Download, build and install socket.io-client-cpp from source.

cd /path/to/working/dir
git clone https://github.com/shinsumicco/socket.io-client-cpp
cd socket.io-client-cpp
git submodule init
git submodule update
mkdir build && cd build
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    -DCMAKE_INSTALL_PREFIX=/usr/local \
    -DBUILD_UNIT_TESTS=OFF \
    ..
make -j4
make install

(if you plan on using SocketViewer)

Install Protobuf.

If you use Ubuntu 18.04 or macOS, Protobuf 3.x can be installed via apt or brew.

# for Ubuntu 18.04 (or later)
apt install -y libprotobuf-dev protobuf-compiler
# for macOS
brew install protobuf

Otherwise, please download, build and install Protobuf from source.

wget -q https://github.com/google/protobuf/archive/v3.6.1.tar.gz
tar xf v3.6.1.tar.gz
cd protobuf-3.6.1
./autogen.sh
./configure \
    --prefix=/usr/local \
    --enable-static=no
make -j4
make install

Build Instructions

When building with support for PangolinViewer, please specify the following cmake options: -DUSE_PANGOLIN_VIEWER=ON and -DUSE_SOCKET_PUBLISHER=OFF.

cd /path/to/openvslam
mkdir build && cd build
cmake \
    -DBUILD_WITH_MARCH_NATIVE=ON \
    -DUSE_PANGOLIN_VIEWER=ON \
    -DUSE_SOCKET_PUBLISHER=OFF \
    -DUSE_STACK_TRACE_LOGGER=ON \
    -DBOW_FRAMEWORK=DBoW2 \
    -DBUILD_TESTS=ON \
    ..
make -j4

When building with support for SocketViewer, please specify the following cmake options: -DUSE_PANGOLIN_VIEWER=OFF and -DUSE_SOCKET_PUBLISHER=ON.

cd /path/to/openvslam
mkdir build && cd build
cmake \
    -DBUILD_WITH_MARCH_NATIVE=ON \
    -DUSE_PANGOLIN_VIEWER=OFF \
    -DUSE_SOCKET_PUBLISHER=ON \
    -DUSE_STACK_TRACE_LOGGER=ON \
    -DBOW_FRAMEWORK=DBoW2 \
    -DBUILD_TESTS=ON \
    ..
make -j4

Note

If cmake cannot find any dependencies, set the environment variables directly. For example, when CMAKE_INSTALL_PREFIX is /usr/local:

Eigen3_DIR=/usr/local/share/eigen3/cmake
OpenCV_DIR=/usr/local/share/OpenCV
DBoW2_DIR=/usr/local/lib/cmake/DBoW2
g2o_DIR=/usr/local/lib/cmake/g2o
Pangolin_DIR=/usr/local/lib/cmake/Pangolin (if installed)
sioclient_DIR=/usr/local/lib/cmake/sioclient (if installed)

After building, check to see if it was successfully built by executing ./run_kitti_slam -h.

$ ./run_kitti_slam -h
Allowed options:
-h, --help             produce help message
-v, --vocab arg        vocabulary file path
-d, --data-dir arg     directory path which contains dataset
-c, --config arg       config file path
--frame-skip arg (=1)  interval of frame skip
--no-sleep             not wait for next frame in real time
--auto-term            automatically terminate the viewer
--debug                debug mode
--eval-log             store trajectory and tracking times for evaluation
-p, --map-db arg       store a map database at this path after SLAM

Note

If OpenVSLAM terminates abnormaly, rebuild g2o and OpenVSLAM with -DBUILD_WITH_MARCH_NATIVE=OFF option for cmake configulation.

Server Setup for SocketViewer

If you plan on using SocketViewer, please setup the environment for the server with npm.

$ cd /path/to/openvslam/viewer
$ ls
Dockerfile  app.js  package.json  public  views
$ npm install
added 88 packages from 60 contributors and audited 204 packages in 2.105s
found 0 vulnerabilities
$ ls
Dockerfile  app.js  node_modules  package-lock.json  package.json  public  views

Then, launch the server with node app.js.

$ cd /path/to/openvslam/viewer
$ ls
Dockerfile  app.js  node_modules  package-lock.json  package.json  public  views
$ node app.js
WebSocket: listening on *:3000
HTTP server: listening on *:3001

After launching, please access to http://localhost:3001/ to check whether the server is correctly launched.

Note

When you try the tutotial and the examples with SocketViewer, please launch the server in the other terminal and access to it with the web browser in advance.