Add ROS Package

.gitignore

@@ -1,4 +1,5 @@
 build/
+devel/
 lib/
 .idea/
 cmake-build-debug/

docs/index.rst

@@ -23,6 +23,7 @@ Contents
     ./simple_tutorial
     ./example
     ./docker
+    ./ros_package
     ./trouble_shooting
 
 Cite Us

docs/overview.rst

@@ -29,6 +29,9 @@ Some code snippets to understand the core functionalities of the system are prov
 You can employ these snippets for in your own programs.
 Please see the ``*.cc`` files in ``./example`` directory or check  :ref:`Simple Tutorial <chapter-simple-tutorial>` and :ref:`Example <chapter-example>`.
 
+Also, some examples you can run OpenVSLAM on ROS are provides provide.
+Please check :ref:`ROS Package <chapter-ros-package>`.
+
 Please contact us via `GitHub issues <https://github.com/xdspacelab/openvslam/issues>`__ if you have any questions or notice any bugs about the software.
 
 .. _section-overview-installation:

docs/ros_package.rst

@@ -0,0 +1,204 @@
+.. _chapter-ros-package:
+
+===========
+ROS Package
+===========
+
+We provide ROS package examples to help you run OpenVSLAM on ROS framework.
+
+.. NOTE ::
+
+    Please build OpenVSLAM with **OpenCV 3.3.1 or later** if you plan on using ROS package.
+    OpenCV 4.x is not supported yet.
+
+.. _section-installation:
+
+Installation
+============
+
+Requirements
+^^^^^^^^^^^^
+
+* `ROS <http://wiki.ros.org/>`_ : Please use the version ``kinetic`` or later.
+
+* :ref:`OpenVSLAM <chapter-installation>` : Please build it with **OpenCV 3.x**.
+
+* `image_transport <http://wiki.ros.org/image_transport>`_ : Required by this ROS package examples.
+
+* `cv_bridge <http://wiki.ros.org/cv_bridge>`_ : Please build it with the same version of OpenCV used in OpenVSLAM. (**We recommend building it from source.**)
+
+.. _section-prerequisites:
+
+Prerequisites
+^^^^^^^^^^^^^
+
+Tested for **Ubuntu 16.04**.
+
+Please install the following dependencies.
+
+* ROS : Please follow `Installation of ROS <http://wiki.ros.org/ROS/Installation>`_.
+
+* OpenVSLAM : Please follow :ref:`Installation of OpenVSLAM <chapter-installation>`.
+
+.. NOTE ::
+
+    Please build OpenVSLAM with PangolinViewer or SocketViewer if you plan on using it for the examples.
+
+Install the dependencies via ``apt``.
+
+.. code-block:: bash
+
+    apt update -y
+    apt install ros-${ROS_DISTRO}-image-transport
+
+Download the source of ``cv_bridge``.
+
+.. code-block:: bash
+
+    cd /path/to/openvslam/ros
+    git clone --branch ${ROS_DISTRO} --depth 1 https://github.com/ros-perception/vision_opencv.git
+    cp -r vision_opencv/cv_bridge src/
+    rm -rf vision_opencv
+
+.. NOTE ::
+
+    We recommend building ``cv_bridge`` from the source even if it has been installed via ``apt``.
+
+Build Instructions
+^^^^^^^^^^^^^^^^^^
+
+When building with support for PangolinViewer, please specify the following cmake options: ``-DUSE_PANGOLIN_VIEWER=ON`` and ``-DUSE_SOCKET_PUBLISHER=OFF`` as described in :ref:`build of OpenVSLAM <section-build-unix>`.
+
+.. code-block:: bash
+
+    cd /path/to/openvslam/ros
+    catkin_make \
+        -DBUILD_WITH_MARCH_NATIVE=ON \
+        -DUSE_PANGOLIN_VIEWER=ON \
+        -DUSE_SOCKET_PUBLISHER=OFF \
+        -DUSE_STACK_TRACE_LOGGER=ON \
+        -DBOW_FRAMEWORK=DBoW2
+
+Alternatively, when building with support for SocketViewer, please specify the following cmake options: ``-DUSE_PANGOLIN_VIEWER=OFF`` and ``-DUSE_SOCKET_PUBLISHER=ON`` as described in :ref:`build of OpenVSLAM <section-build-unix>`.
+
+.. code-block:: bash
+
+    cd /path/to/openvslam/ros
+    catkin_make \
+        -DBUILD_WITH_MARCH_NATIVE=ON \
+        -DUSE_PANGOLIN_VIEWER=OFF \
+        -DUSE_SOCKET_PUBLISHER=ON \
+        -DUSE_STACK_TRACE_LOGGER=ON \
+        -DBOW_FRAMEWORK=DBoW2
+
+Examples
+========
+
+Run the core program required for ROS-based system in advance.
+
+.. code-block:: bash
+
+    roscore
+
+.. NOTE ::
+
+    Please leave the **roscore** run.
+
+Publisher
+^^^^^^^^^
+
+Publishers continually broadcast images as a ROS topic.
+Please execute one of the following command snippets in the new terminal.
+
+Publish a Video File
+--------------------
+
+For using video files (e.g. ``.mp4``) for visual SLAM or localization.
+
+.. code-block:: bash
+
+    source /path/to/openvslam/ros/devel/setup.bash
+    rosrun publisher video -m /path/to/video.mp4
+
+Republish the ROS topic to ``/camera/image_raw``.
+
+.. code-block:: bash
+
+    rosrun image_transport republish \
+        raw in:=/video/image_raw raw out:=/camera/image_raw
+
+
+Publish a Image Sequence
+------------------------
+
+For using image sequences for visual SLAM or localization.
+
+.. code-block:: bash
+
+    source /path/to/openvslam/ros/devel/setup.bash
+    rosrun publisher image -i /path/to/images/
+
+Republish the ROS topic to ``/camera/image_raw``.
+
+.. code-block:: bash
+
+    rosrun image_transport republish \
+        raw in:=/video/image_raw raw out:=/camera/image_raw
+
+Publish Images of a USB Camera
+------------------------------
+
+For using a standard USB camera for visual SLAM or localization.
+
+.. code-block:: bash
+
+    apt install ros-${ROS_DISTRO}-usb-cam
+
+.. code-block:: bash
+
+    rosparam set usb_cam/pixel_format yuyv
+    rosrun usb_cam usb_cam_node
+
+Republish the ROS topic to ``/camera/image_raw``.
+
+.. code-block:: bash
+
+    rosrun image_transport republish \
+        raw in:=/usb_cam/image_raw raw out:=/camera/image_raw
+
+Subscriber
+^^^^^^^^^^
+
+Subscribers continually receive images.
+Please execute one of the following command snippets in the new terminal.
+
+.. NOTE ::
+
+    Option arguments are the same as :ref:`the examples of OpenVSLAM <chapter-example>`.
+
+Tracking and Mapping
+--------------------
+
+We provide an example snippet for visual SLAM.
+The source code is placed at ``./openvslam/ros/src/openvslam/src/run_slam.cc``.
+
+.. code-block:: bash
+
+    source /path/to/openvslam/ros/devel/setup.bash
+    rosrun openvslam run_slam \
+        -v /path/to/orb_vocab.dbow2 \
+        -c /path/to/config.yaml
+
+Localization
+------------
+
+We provide an example snippet for localization based on a prebuilt map.
+The source code is placed at ``./ros/src/openvslam/src/run_localization.cc``.
+
+.. code-block:: bash
+
+    source /path/to/openvslam/ros/devel/setup.bash
+    rosrun openvslam run_localization \
+        -v /path/to/orb_vocab.dbow2 \
+        -c /path/to/config.yaml \
+        --map-db /path/to/map.msg

ros/.catkin_workspace

@@ -0,0 +1 @@
+# This file currently only serves to mark the location of a catkin workspace for tool integration