.. _slam_app:

Slam application
################

SLAM stands for "simultaneous location and mapping" and refers to a image-based
technique to identify and trace certain keypoints in an image stream and
reconstruct the surroundings (map) and the camera movement (location).

A small sample application, based on `openVSlam
<https://github.com/xdspacelab/openvslam>`_ (external link) is available through
the HemiStereo eco-system. It is not meant for production use but for
illustration purposes.

Installation
------------

The application is available as docker image (as other HemiStereo apps), and
can be installed automatically using apt:

.. code-block:: bash

    sudo apt update
    sudo apt install 3dvl-slam


.. note::

    The slam application contains a seperate image-processing pipeline and
    requires exclusive access to the camera devices, thus it must be operated
    without other apps using the camera beeing active (e.g. the stereo-backend
    must be switched off)

For the activation of the app, make sure the stereo-backend (and possibly other
camera-requiring apps) is stopped and disabled first:

.. code-block:: bash

    sudo hemistereo_app_stop stereo-backend
    sudo hemistereo_app_disable stereo-backend

Finally, the slam app can be activated:

.. code-block:: bash

    sudo hemistereo_app_enable slam
    sudo hemistereo_app_start slam

This should download and start two docker images/containers.

Usage
------

The app is only meant for demonstration purposes and contains a viewer
application available through your web-browser as:

http://<SENSOR-IP>:3001

.. _fig_slamviewer:
.. figure:: images/slam-viewer.png
   :scale: 30 %
   :align: center
   
   Fig. 1.1: Visualization of the slam algorithm

To terminate the application, use the "terminate" button of the viewer.

For restarting the slam algorithm, the app should be restarted via:

.. code-block:: bash

    sudo hemistereo_app_stop slam
    sudo hemistereo_app_start slam