initial commit
This commit is contained in:
221
docs/gs-installing.dox
Normal file
221
docs/gs-installing.dox
Normal file
@@ -0,0 +1,221 @@
|
||||
/**
|
||||
|
||||
|
||||
@page gs-installing Installation Guide
|
||||
@tableofcontents
|
||||
|
||||
|
||||
@section gs-install-ros ROS Dependency
|
||||
|
||||
Our codebase is built on top of the [Robot Operating System (ROS)](https://www.ros.org/) 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](https://github.com/catkin/catkin_tools) build for easy ROS building.
|
||||
All ROS installs include [OpenCV](https://github.com/opencv/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](https://github.com/opencv/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:
|
||||
|
||||
- [Ubuntu 16.04 ROS 1 Kinetic](http://wiki.ros.org/kinetic/Installation/Ubuntu) (uses OpenCV 3.3)
|
||||
- [Ubuntu 18.04 ROS 1 Melodic](http://wiki.ros.org/melodic/Installation/Ubuntu) (uses OpenCV 3.2)
|
||||
- [Ubuntu 20.04 ROS 1 Noetic](http://wiki.ros.org/noetic/Installation/Ubuntu) (uses OpenCV 4.2)
|
||||
- [Ubuntu 18.04 ROS 2 Dashing](https://docs.ros.org/en/dashing/) (uses OpenCV 3.2)
|
||||
- [Ubuntu 20.04 ROS 2 Galactic](https://docs.ros.org/en/galactic/) (uses OpenCV 4.2)
|
||||
|
||||
|
||||
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:
|
||||
|
||||
@code{.shell-session}
|
||||
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev
|
||||
@endcode
|
||||
|
||||
|
||||
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 @ref ov_msckf::VioManagerOptions struct with proper information and feed inertial and image data into the correct functions.
|
||||
The simulator binary `run_simulation` can give you and example on how to do this.
|
||||
|
||||
|
||||
|
||||
|
||||
@subsection gs-install-ros-1 ROS1 Install
|
||||
|
||||
To install we can perform the following:
|
||||
|
||||
@code{.shell-session}
|
||||
sudo sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'
|
||||
sudo apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654
|
||||
sudo apt-get update
|
||||
export ROS1_DISTRO=noetic # kinetic=16.04, melodic=18.04, noetic=20.04
|
||||
sudo apt-get install ros-$ROS1_DISTRO-desktop-full
|
||||
sudo apt-get install python-catkin-tools # ubuntu 16.04, 18.04
|
||||
sudo apt-get install python3-catkin-tools python3-osrf-pycommon # ubuntu 20.04
|
||||
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
@code{.shell-session}
|
||||
echo "source /opt/ros/$ROS1_DISTRO/setup.bash" >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
@endcode
|
||||
|
||||
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 `source_ros1` to load your ROS1 environmental variables.
|
||||
|
||||
@code{.shell-session}
|
||||
echo "alias source_ros1=\"source /opt/ros/$ROS1_DISTRO/setup.bash\"" >> ~/.bashrc
|
||||
echo "alias source_devel=\"source devel/setup.bash\"" >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection gs-install-ros-2 ROS2 Install
|
||||
|
||||
To install we can perform the following:
|
||||
|
||||
@code{.shell-session}
|
||||
sudo apt update && sudo apt install curl gnupg lsb-release
|
||||
sudo curl -sSL https://raw.githubusercontent.com/ros/rosdistro/master/ros.key -o /usr/share/keyrings/ros-archive-keyring.gpg
|
||||
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/ros-archive-keyring.gpg] http://packages.ros.org/ros2/ubuntu $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/ros2.list > /dev/null
|
||||
sudo apt-get update
|
||||
export ROS2_DISTRO=galactic # dashing=18.04, galactic=20.04
|
||||
sudo apt install ros-$ROS2_DISTRO-desktop
|
||||
sudo apt-get install ros-$ROS2_DISTRO-ros2bag ros-$ROS2_DISTRO-rosbag2* # rosbag utilities (seems to be separate)
|
||||
sudo apt-get install libeigen3-dev libboost-all-dev libceres-dev
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
@code{.shell-session}
|
||||
echo "source /opt/ros/$ROS2_DISTRO/setup.bash" >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
@endcode
|
||||
|
||||
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 `source_ros2` to load your ROS1 environmental variables.
|
||||
|
||||
@code{.shell-session}
|
||||
echo "alias source_ros2=\"source /opt/ros/$ROS2_DISTRO/setup.bash\"" >> ~/.bashrc
|
||||
echo "alias source_install=\"source install/setup.bash\"" >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
@endcode
|
||||
|
||||
|
||||
@section gs-install-openvins Cloning the OpenVINS Project
|
||||
|
||||
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 @ref gs-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 (if it is found)
|
||||
- `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_eval
|
||||
- `DISABLE_MATPLOTLIB` - (default OFF) - Disable or enable matplotlib plot scripts in ov_eval
|
||||
|
||||
@code{.shell-session}
|
||||
mkdir -p ~/workspace/catkin_ws_ov/src/
|
||||
cd ~/workspace/catkin_ws_ov/src/
|
||||
git clone https://github.com/rpng/open_vins/
|
||||
cd ..
|
||||
catkin build # ROS1
|
||||
colcon build # ROS2
|
||||
colcon build --event-handlers console_cohesion+ --packages-select ov_core ov_init ov_msckf ov_eval # ROS2 with verbose output
|
||||
@endcode
|
||||
|
||||
If you do not have ROS installed, then you can do the following:
|
||||
|
||||
|
||||
@code{.shell-session}
|
||||
cd ~/github/
|
||||
git clone https://github.com/rpng/open_vins/
|
||||
cd open_vins/ov_msckf/
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
make -j4
|
||||
@endcode
|
||||
|
||||
|
||||
@section gs-install-oveval Additional Evaluation Requirements
|
||||
|
||||
If you want to use the plotting utility wrapper of [matplotlib-cpp](https://github.com/lava/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](https://github.com/giampaolo/psutil) library.
|
||||
|
||||
@code{.shell-session}
|
||||
sudo apt-get install python2.7-dev python-matplotlib python-numpy python-psutil # for python2 systems
|
||||
sudo apt-get install python3-dev python3-matplotlib python3-numpy python3-psutil python3-tk # for python3 systems
|
||||
catkin build -DDISABLE_MATPLOTLIB=OFF # build with viz (default)
|
||||
catkin build -DDISABLE_MATPLOTLIB=ON # build without viz
|
||||
@endcode
|
||||
|
||||
|
||||
@section gs-install-opencv OpenCV Dependency (from source)
|
||||
|
||||
We leverage [OpenCV](https://opencv.org/) for this project which you can typically use the install from ROS.
|
||||
If the ROS version of [cv_bridge](http://wiki.ros.org/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}
|
||||
|
||||
@par OpenCV Source Installation
|
||||
Try to first build with your system / ROS OpenCV.
|
||||
Only fall back onto this if it does not allow you to compile, or want a newer version!
|
||||
|
||||
@code{.shell-session}
|
||||
git clone https://github.com/opencv/opencv/
|
||||
git clone https://github.com/opencv/opencv_contrib/
|
||||
mkdir opencv/build/
|
||||
cd opencv/build/
|
||||
cmake -DOPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules ..
|
||||
make -j8
|
||||
sudo make install
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
|
||||
@subsection gs-install-ceres Ceres Solver
|
||||
|
||||
Ceres solver @cite ceres-solver is required for dynamic initialization and backend optimization.
|
||||
Please refer to their [documentation](http://ceres-solver.org/installation.html#linux) 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}
|
||||
|
||||
@par Ceres Source Installation
|
||||
Try to first build with your system with `sudo apt-get install libceres-dev`.
|
||||
Only fall back onto this if it does not allow you to compile, or want a newer version!
|
||||
|
||||
@code{.shell-session}
|
||||
sudo apt-get install -y cmake libgoogle-glog-dev libgflags-dev libatlas-base-dev libeigen3-dev libsuitesparse-dev
|
||||
CERES_VERSION="2.0.0"
|
||||
git clone https://ceres-solver.googlesource.com/ceres-solver
|
||||
cd ceres-solver
|
||||
git checkout tags/${CERES_VERSION}
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
make
|
||||
sudo make install
|
||||
@endcode
|
||||
|
||||
*/
|
||||
Reference in New Issue
Block a user