Our codebase is built on top of the Robot Operating System (ROS) and has been tested building on Ubuntu 16.04, 18.04, 20.04 systems with ROS Kinetic, Melodic, and Noetic. We also recommend installing the catkin_tools build for easy ROS building. All ROS installs include OpenCV, but if you need to build OpenCV from source ensure you build the contributed modules as we use Aruco feature extraction. See the opencv_contrib readme on how to configure your cmake command when you build the core OpenCV library. We have tested building with OpenCV 3.2, 3.3, 3.4, 4.2, and 4.5. Please see the official instructions to install ROS:
We do support ROS-free builds, but don't recommend using this interface as we have limited support for it. You will need to ensure you have installed OpenCV 3 or 4, Eigen3, and Ceres which are the only dependencies. For Ubuntu linux-based system the system dependencies are:
If ROS is not found on the system, one can use command line options to run the simulation without any visualization or cmake -DENABLE_ROS=OFF ... If you are using the ROS-free interface, you will need to properly construct the ov_msckf::VioManagerOptions struct with proper information and feed inertial and image data into the correct functions with proper buffers. The simulator binary run_simulation can give you and example on how to do this. To build without ROS installed, please refer to Installation Guide (ROS Free).
To install we can perform the following:
If you only have ROS1 on your system and are not cross installing ROS2, then you can run the following to append this to your bashrc file. Every time a terminal is open, thus will load the ROS1 environmental variables required to find all dependencies for building and system installed packages.
Otherwise, if you want to also install ROS2, you must NOT have a global source. Instead we can have a nice helper command which can be used when we build a ROS1 workspace. Additionally, the source_devel command can be used when in your workspace root to source built packages. Once appended simply run ros1_source to load your ROS1 environmental variables.
To install we can perform the following:
If you only have ROS2 on your system and are not cross installing ROS1, then you can run the following to append this to your bashrc file. Every time a terminal is open, thus will load the ROS2 environmental variables required to find all dependencies for building and system installed packages.
Otherwise, if you want to also install ROS1, you must NOT have a global source. Instead we can have a nice helper command which can be used when we build a ROS1 workspace. Additionally, the source_install command can be used when in your workspace root to source built packages. Once appended simply run ros2_source to load your ROS1 environmental variables.
Now that we have ROS installed we can setup a catkin workspace and build the project! If you did not install the catkin_tools build system, you should be able to build using the standard catkin_make command that is included with ROS. If you run into any problems please google search the issue first and if you are unable to find a solution please open an issue on our github page. After the build is successful please following the Simple Tutorial guide on getting a dataset and running the system.
There are additional options that users might be interested in. Configure these with catkin build -D<option_name>=OFF or cmake -D<option_name>=ON .. in the ROS free case.
ENABLE_ROS - (default ON) - Enable or disable building with ROS (see Installation Guide (ROS Free))ENABLE_ARUCO_TAGS - (default ON) - Enable or disable aruco tag (disable if no contrib modules)BUILD_OV_EVAL - (default ON) - Enable or disable building of ov_evalDISABLE_MATPLOTLIB - (default OFF) - Disable or enable matplotlib plot scripts in ov_evalTo build without ROS installed, please refer to Installation Guide (ROS Free). We recommend compiling with RelWithDebInfo as we always include -g for debug symbols. If you wish to Debug, the workspace can configure as:
If you want to use the plotting utility wrapper of matplotlib-cpp to generate plots directly from running the cpp code in ov_eval you will need to make sure you have a valid Python 2.7 or 3 install of matplotlib. On ubuntu 16.04 you can do the following command which should take care of everything you need. If you can't link properly, make sure you can call it from Python normally (i.e. that your Python environment is not broken). You can disable this visualization if it is broken for you by passing the -DDISABLE_MATPLOTLIB=ON parameter to your catkin build. Additionally if you wish to record CPU and memory usage of the node, you will need to install the psutil library.
We leverage OpenCV for this project which you can typically use the install from ROS. If the ROS version of cv_bridge does not work (or are using non-ROS building), then you can try building OpenCV from source ensuring you include the contrib modules. One should make sure you can see some of the "contrib" (e.g. aruco) when you cmake to ensure you have linked to the contrib modules.
@m_class{m-block m-warning}
If you do not want to build the modules, you should also be able to do this (while it is not as well tested). The ArucoTag tracker depends on a non-free module in the contrib repository, thus this will need to be disabled. You can disable this with catkin build -DENABLE_ARUCO_TAGS=OFF or cmake -DENABLE_ARUCO_TAGS=OFF .. in your build folder.
Ceres solver [ceres-solver] is required for dynamic initialization and backend optimization. Please refer to their documentation for specifics to your platform. It should be able to build on most platforms (including ARM android devices). To install we can perform the following:
@m_class{m-block m-warning}
sudo apt-get install libceres-dev. Only fall back onto this if it does not allow you to compile, or want a newer version! You will need to build from source if there is an Eigen miss-match: "Failed to find Ceres - Found Eigen dependency, but the version of Eigen found (3.3.7) does not exactly match the version of Eigen Ceres was compiled with (3.3.4)."