openvins_linux/docs/gs-installing.dox

/**


@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

*/