|
| 1 | +# rpg_svo_pro |
| 2 | + |
| 3 | +This is the implementation of Semi-direct Visual Odometry (SVO) developed at RPG. SVO is a fast and versatile visual front-end as described in the [SVO paper (TRO-17)](http://rpg.ifi.uzh.ch/docs/TRO17_Forster-SVO.pdf). Different extensions have been integrated into SVO through various research and industrial projects over the past few years. In summary, this repository offers the following functionalities: |
| 4 | + |
| 5 | +* SVO 2.0 that supports perspective, fisheye and stereo cameras |
| 6 | +* Visual-inertial odometry: SVO 2.0 + visual-inertial sliding window optimization backend (modified from [OKVIS](https://github.com/ethz-asl/okvis)) |
| 7 | +* Visual-inertial SLAM: SVO 2.0 + visual-inertial backend + globally bundle adjusted map using iSAM2. The global map is updated in real-time (thanks to iSAM2) and used for localization at frame-rate. |
| 8 | +* Loop closure via [DBoW2](https://github.com/dorian3d/DBoW2) and pose graph is also supported for a lightweight, globally consistent (but not so accurate) map. |
| 9 | + |
| 10 | +An example of the visual-inertial SLAM pipeline on EuRoC dataset is below (green points - sliding window; blue points - iSAM2 map): |
| 11 | + |
| 12 | + |
| 13 | + |
| 14 | +SVO 2.0 and its extensions have been used to support various projects at RPG, such as our recent work on [multiple camera SLAM](http://rpg.ifi.uzh.ch/docs/ICRA20_Kuo.pdf), [voxel map for visual SLAM](http://rpg.ifi.uzh.ch/docs/ICRA20_Muglikar.pdf) and [the tight-coupling of global positional measurements into VIO](http://rpg.ifi.uzh.ch/docs/IROS20_Cioffi.pdf). We hope that the efforts we made can facilitate the research and applications of SLAM and spatial perception. |
| 15 | + |
| 16 | +## License |
| 17 | + |
| 18 | +The code is licensed under GPLv3. For commercial use, please contact `sdavide [at] ifi [dot] uzh [dot] ch`. |
| 19 | + |
| 20 | +The visual-inertial backend is modified from OKVIS, and the license is retained at the beginning of the related files. |
| 21 | + |
| 22 | +## Credits |
| 23 | + |
| 24 | +If you used the code in academic context, please cite: |
| 25 | + |
| 26 | +* Christian Forster, Matia Pizzoli, Davide Scaramuzza. SVO: Fast Semi-Direct Monocular Visual Odometry. ICRA, 2014. [bibtex](./doc/bib/Forster14icra.bib) |
| 27 | +* Christian Forster, Zichao Zhang, Michael Gassner, Manuel Werlberger, Davide Scaramuzza. SVO: Semi-Direct Visual Odometry for Monocular and Multi-Camera Systems. TRO, 2017. [bibtex](./doc/bib/Forster17tro.bib) |
| 28 | + |
| 29 | +Additionally, please cite the following papers for the specific extensions you make use of: |
| 30 | + |
| 31 | +* *Fisheye/catadioptric camera extension*: Zichao Zhang, Henri Rebecq, Christian Forster, Davide Scaramuzza. Benefit of Large Field-of-View Cameras for Visual Odometry. ICRA, 2016. [bibtex](./doc/bib/Zhang16icra.bib) |
| 32 | +* *Brightness/exposure compensation*: Zichao Zhang, Christian Forster, Davide Scaramuzza. Active Exposure Control for Robust Visual Odometry in HDR Environments. ICRA, 2017. [bibtex](./doc/bib/Zhang17icra.bib) |
| 33 | +* *Ceres-based optimization backend*: Stefan Leutenegger, Simon Lynen, Michael Bosse, Roland Siegwart, Paul Timothy Furgale. Keyframe-based visual–inertial odometry using nonlinear optimization. IJRR, 2015. [bibtex](./doc/bib/Leutenegger15ijrr.bib) |
| 34 | +* *Global map powered by iSAM2*: Michael Kaess, Hordur Johannsson, Richard Roberts, Viorela Ila, John Leonard, Frank Dellaert. iSAM2: Incremental Smoothing and Mapping Using the Bayes Tree. IJRR, 2012. [bibtex](./doc/bib/Kaess12ijrr.bib) |
| 35 | +* *Loop closure*: Dorian Gálvez-López and Juan D. Tardós. Bags of Binary Words for Fast Place Recognition in Image Sequences. TRO, 2012. [bibtex](./doc/bib/Galvez12tro.bib) |
| 36 | + |
| 37 | +## Install |
| 38 | + |
| 39 | +The code has been tested on |
| 40 | + |
| 41 | +* Ubuntu 18.04 with ROS Melodic |
| 42 | +* Ubuntu 20.04 with ROS Noetic |
| 43 | + |
| 44 | +### Install dependences |
| 45 | + |
| 46 | +Install [catkin tools](https://catkin-tools.readthedocs.io/en/latest/installing.html) and [vcstools](https://github.com/dirk-thomas/vcstool) if you haven't done so before. Depending on your operating system, run |
| 47 | +```sh |
| 48 | +# For Ubuntu 18.04 + Melodic |
| 49 | +sudo apt-get install python-catkin-tools python-vcstool |
| 50 | +``` |
| 51 | +or |
| 52 | +```sh |
| 53 | +# For Ubuntu 20.04 + Noetic |
| 54 | +sudo apt-get install python3-catkin-tools python3-vcstool python3-osrf-pycommon |
| 55 | +``` |
| 56 | +Install system dependencies and dependencies for Ceres Solver |
| 57 | +```sh |
| 58 | +# system dep. |
| 59 | +sudo apt-get install libglew-dev libopencv-dev libyaml-cpp-dev |
| 60 | +# Ceres dep. |
| 61 | +sudo apt-get install libblas-dev liblapack-dev libsuitesparse-dev |
| 62 | +``` |
| 63 | + |
| 64 | +### Clone and compile |
| 65 | +Create a workspace and clone the code (`ROS-DISTRO`=`melodic`/`noetic`): |
| 66 | +```sh |
| 67 | +mkdir svo_ws && cd svo_ws |
| 68 | +# see below for the reason for specifying the eigen path |
| 69 | +catkin config --init --mkdirs --extend /opt/ros/<ROS-DISTRO> --cmake-args -DCMAKE_BUILD_TYPE=Release -DEIGEN3_INCLUDE_DIR=/usr/include/eigen3 |
| 70 | +cd src |
| 71 | +git clone [email protected]:uzh-rpg/rpg_svo_pro_open.git |
| 72 | +vcs-import < ./rpg_svo_pro_open/dependencies.yaml |
| 73 | +touch minkindr/minkindr_python/CATKIN_IGNORE |
| 74 | +# vocabulary for place recognition |
| 75 | +cd rpg_svo_pro_open/svo_online_loopclosing/vocabularies && ./download_voc.sh |
| 76 | +cd ../../.. |
| 77 | +``` |
| 78 | +There are two types of builds that you can proceed from here |
| 79 | +1. Build without the global map (**front-end + sliding window back-end + loop closure/pose graph**) |
| 80 | + |
| 81 | + ```sh |
| 82 | + catkin build |
| 83 | + ``` |
| 84 | + |
| 85 | + |
| 86 | + |
| 87 | +2. Build with the global map using iSAM2 (**all functionalities**) |
| 88 | + |
| 89 | + First, enable the global map feature |
| 90 | + |
| 91 | + ```sh |
| 92 | + rm rpg_svo_pro_open/svo_global_map/CATKIN_IGNORE |
| 93 | + ``` |
| 94 | + and in `svo_cmake/cmake/Modules/SvoSetup.cmake` |
| 95 | + |
| 96 | + ```cmake |
| 97 | + SET(USE_GLOBAL_MAP TRUE) |
| 98 | + ``` |
| 99 | + |
| 100 | + Second, clone GTSAM |
| 101 | + |
| 102 | + ```sh |
| 103 | + git clone --branch 4.0.3 [email protected]:borglab/gtsam.git |
| 104 | + ``` |
| 105 | + |
| 106 | + and modify GTSAM compilation flags a bit: |
| 107 | + |
| 108 | + ```cmake |
| 109 | + # 1. gtsam/CMakelists.txt: use system Eigen |
| 110 | + -option(GTSAM_USE_SYSTEM_EIGEN "Find and use system-installed Eigen. If 'off', use the one bundled with GTSAM" OFF) |
| 111 | + +option(GTSAM_USE_SYSTEM_EIGEN "Find and use system-installed Eigen. If 'off', use the one bundled with GTSAM" ON) |
| 112 | + # 2. gtsam/cmake/GtsamBuildTypes: disable avx instruction set |
| 113 | + # below the line `list_append_cache(GTSAM_COMPILE_OPTIONS_PUBLIC "-march=native")` |
| 114 | + list_append_cache(GTSAM_COMPILE_OPTIONS_PUBLIC "-mno-avx") |
| 115 | + ``` |
| 116 | + |
| 117 | + > Using the same version of Eigen helps avoid [memory issues](https://github.com/ethz-asl/eigen_catkin/wiki/Eigen-Memory-Issues). Disabling `avx` instruction set also helps with some segment faults in our experience (this can be however OS and hardware dependent). |
| 118 | + |
| 119 | + And finally build the whole workspace |
| 120 | + |
| 121 | + ```sh |
| 122 | + # building GTSAM may take a while |
| 123 | + catkin build |
| 124 | + ``` |
| 125 | + |
| 126 | +## Instructions |
| 127 | + |
| 128 | +* Get started: running the pipeline |
| 129 | + * [The visual front-end](./doc/frontend/visual_frontend.md) |
| 130 | + * [Visual-inertial odometry](./doc/vio.md) |
| 131 | + * [VIO + global map](./doc/global_map.md) |
| 132 | +* [Benchmarking](./doc/benchmarking.md) |
| 133 | +* [Camera and sensor calibration](./doc/calibration.md) |
| 134 | +* [Known issues and possible improvements](./doc/known_issues_and_improvements.md) |
| 135 | + |
| 136 | +## Troubleshooting |
| 137 | + |
| 138 | +0. **Weird building issues after some tinkering**. It is recommend to |
| 139 | + |
| 140 | + * clean your workspace (`catkin clean --all` at the workspace root) and rebuild your workspace (`catkin build`) |
| 141 | + * or `catkin build --force-cmake` |
| 142 | + |
| 143 | + after your have made changes to CMake files (`CMakeLists.txt` or `*.cmake`) to make sure the changes take effect. |
| 144 | + |
| 145 | + <details> |
| 146 | + <summary>Longer explanation</summary> |
| 147 | + Catkin tools can detect changes in CMake files and re-build affected files only. But since we are working with a multi-package project, some changes may not be detected as desired. For example, changing the building flags in `svo_cmake/cmake/Modules/SvoSetup.cmake` will affect all the packages but the re-compiling may not be done automatically (since the files in each package are not changed). Also, we need to keep the linking (e.g., library version) and compiling flags consistent across different packages. Therefore, unless you are familiar with how the compilation works out, it is the safest to re-build the whole workspace. `catkin build --force-cmake` should also work in most cases. |
| 148 | + </details> |
| 149 | + |
| 150 | +1. **Compiling/linking error related to OpenCV**: find `find_package(OpenCV REQUIRED)` in the `CMakeLists.txt` files in each package (in `rpg_common`, `svo_ros`, `svo_direct`, `vikit/vikit_common` and `svo_online_loopclosing`) and replace it with |
| 151 | + |
| 152 | + ```cmake |
| 153 | + # Ubuntu 18.04 + Melodic |
| 154 | + find_package(OpenCV 3 REQUIRED) |
| 155 | + # Ubuntu 20.04 + Noetic |
| 156 | + find_package(OpenCV 4 REQUIRED) |
| 157 | + ``` |
| 158 | + |
| 159 | + <details> |
| 160 | + <summary>Longer explanation</summary> |
| 161 | + First, ROS is built against OpenCV 3 on Ubuntu 18.04 and OpenCV 4 on Ubuntu 20.04. It is desired to keep the OpenCV version linked in SVO consistent with the ROS one, since in `svo_ros` we need to link everything with ROS. Second, The original `CMakeLists.txt` files will work fine if you only have the default OpenCV installed. But if you have some customized version of OpenCV installed (e.g., from source), it is recommended to explicitly specify the version of OpenCV that should be used (=the version ROS uses) as mentione above. |
| 162 | + </details> |
| 163 | + |
| 164 | +2. **Visualization issues with the PointCloud2**: Using `Points` to visualize `PointCloud2` in RVIZ seems to be [problematic](https://github.com/ros-visualization/rviz/issues/1508) in Ubuntu 20.04. We use other visualization types instead of `Points` per default. However, it is good to be aware of this if you want to customize the visualization. |
| 165 | + |
| 166 | +3. **Pipeline crashes with loop closure enabled**: If the pipeline crashes calling `svo::loadVoc()`, did you forgot to download the vocabulary files as mentioned above? |
| 167 | +
|
| 168 | + ```sh |
| 169 | + cd rpg_svo_pro_open/svo_online_loopclosing/vocabularies && ./download_voc.sh |
| 170 | + ``` |
| 171 | +
|
| 172 | +4. **Inconsistent Eigen versions during compilation**: The same Eigen should be used across the whole project (which should be system Eigen, since we are also using ROS). Check whether `eigen_catkin` and `gtsam` find the same version of Eigen: |
| 173 | +
|
| 174 | + ```sh |
| 175 | + # for eigen_catkin |
| 176 | + catkin build eigen_catkin --force-cmake --verbose |
| 177 | + # for gtsam |
| 178 | + catkin build gtsam --force-cmake --verbose |
| 179 | + ``` |
| 180 | + |
| 181 | + <details> |
| 182 | + <summary>Longer explanation</summary> |
| 183 | + One common pitfall of using Eigen in your projects is have different libraries compiled against different Eigen versions. For SVO, eigen_catkin (https://github.com/ethz-asl/eigen_catkin) is used to keep the Eigen version same, which should be the system one (under /usr/include) on 18.04 and 20.04. For GTSAM, system Eigen is found via a cumstomized cmake file (https://github.com/borglab/gtsam/blob/develop/cmake/FindEigen3.cmake#L66). It searches for `/usr/local/include` first, which may contain Eigen versions that are manually installed. Therefore, we explicitly specifies `EIGEN_INCLUDE_PATH` when configuring the workspace to force GTSAM to find system Eigen. If you still encounter inconsistent Eigen versions, the first thing to check is whether different versions of Eigen are still used. |
| 184 | + </details> |
| 185 | +
|
| 186 | +## Acknowledgement |
| 187 | +
|
| 188 | +Thanks to Simon Klenk, Manasi Muglikar, Giovanni Cioffi and Javier Hidalgo-Carrió for their valuable help and comments for the open source code. |
| 189 | +
|
| 190 | +The work is made possible thanks to the efforts of many contributors from RPG. Apart from the authors listed in the above papers, Titus Cieslewski and Henri Rebecq made significant contributions to the visual front-end. Jeffrey Delmerico made great efforts to apply SVO on different real robots, which in turn helped improve the pipeline. Many PhD and master students and lab engineers have also contributed to the code. |
| 191 | +
|
| 192 | +The Ceres-based optimization back-end is based on code developed at [Zurich-eye](https://www.wysszurich.uzh.ch/projects/completed-projects/zurich-eye), a spin-off from RPG. Jonathan Huber is the main contributor that integrated the back-end with SVO. Kunal Shrivastava (now CEO of [SUIND](https://suind.com/)) developed the loop closure module during his semester project and internship at RPG. The integration of the iSAM2-based global map was developed by Zichao Zhang. |
| 193 | +
|
| 194 | +We would like to thank our collaborators at [Prophesee](https://www.prophesee.ai/) for pointing out several bugs in the visual front-end. Part of the code was developed during a funded project with [Huawei](https://www.huawei.com/en/). |
0 commit comments