Add Instructions for IridescenceViewer

docs/docker.rst

@@ -5,6 +5,58 @@ Running on Docker
 =================
 
 
+.. _section-instructions-for-iridescenceviewer:
+
+Instructions for IridescenceViewer
+==================================
+
+``Dockerfile.iridescense`` can be used for easy installation.
+This chapter provides instructions on building and running examples with IridescenceViewer support using Docker.
+
+The instructions are tested on Ubuntu 20.04.
+
+Building Docker Image
+^^^^^^^^^^^^^^^^^^^^^
+
+Execute the following commands:
+
+.. code-block:: bash
+
+    git clone --recursive https://github.com/stella-cv/stella_vslam.git
+    cd stella_vslam
+    docker build -t stella_vslam-iridescense -f Dockerfile.iridescense .
+
+
+You can accelerate the build of the docker image with ``--build-arg NUM_THREADS=<number of parallel builds>`` option. For example:
+
+.. code-block:: bash
+
+    # building the docker image with four threads
+    docker build -t stella_vslam-iridescense -f Dockerfile.iridescense . --build-arg NUM_THREADS=`expr $(nproc) - 1`
+
+Starting Docker Container
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In order to enable X11 forwarding, supplemental options (``-e DISPLAY=$DISPLAY`` and ``-v /tmp/.X11-unix/:/tmp/.X11-unix:ro``) are needed for ``docker run``.
+
+.. code-block:: bash
+
+    # before launching the container, allow display access from local users
+    xhost +local:
+    # launch the container
+    docker run -it --rm --privileged -e DISPLAY=$DISPLAY -v /tmp/.X11-unix/:/tmp/.X11-unix:ro stella_vslam-iridescense
+
+.. NOTE ::
+
+    Additional option ``--gpus all`` is needed if you use NVIDIA graphics card(s).
+
+
+After launching the container, the shell interface will be launched in the docker container.
+See :ref:`Tutorial <chapter-simple-tutorial>` to run SLAM examples in the container.
+
+If you need to access to any files and directories on a host machine from the container, :ref:`bind directories <section-directory-binding>` between the host and the container.
+
+
 .. _section-instructions-for-pangolinviewer:
 
 Instructions for PangolinViewer

docs/example.rst

@@ -64,8 +64,6 @@ In addition, download a vocabulary file for FBoW from `here <https://github.com/
 
 A configuration file for each sequence is contained under ``./example/kitti/``.
 
-If you built examples with Pangolin Viewer support, a map viewer and frame viewer will be launced right after executing the following command.
-
 .. code-block:: bash
 
     # at the build directory of stella_vslam
@@ -103,8 +101,6 @@ In addition, download a vocabulary file for FBoW from `here <https://github.com/
 
 We provided the two config files for EuRoC, ``~/lib/stella_vslam/example/euroc/EuRoC_mono.yaml`` for monocular and ``~/lib/stella_vslam/example/euroc/EuRoC_stereo.yaml`` for stereo.
 
-If you have built examples with Pangolin Viewer support, a map viewer and frame viewer will be launched right after executing the following command.
-
 .. code-block:: bash
 
     # at the build directory of stella_vslam

docs/installation.rst

@@ -48,14 +48,27 @@ Requirements for stella_vslam
 
 .. NOTE ::
 
-    OpenCV with GUI support is necessary for using the built-in viewer (Pangolin Viewer).
+    OpenCV with GUI support is necessary for using the built-in viewer (Iridescence/Pangolin Viewer).
     OpenCV with video support is necessary if you plan on using video files (e.g. ``.mp4``) as inputs.
     If your CPU has many cores, it is recommended to enable TBB.
 
+.. _subsection-dependencies-iridescenceviewer:
+
+Requirements for IridescenceViewer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+| We provided an OpenGL-based simple viewer.
+| This viewer is implemented with `Iridescence <https://github.com/koide3/iridescence>`_. Thus, we call it **IridescenceViewer**.
+| Please install the following dependencies if you plan on using IridescenceViewer.
+
+* `Iridescence <https://github.com/koide3/iridescence>`_ : Please use the latest release. Tested on commit ID `085322e <https://github.com/koide3/iridescence/tree/085322e0c949f75b67d24d361784e85ad7f197ab>`_.
+
+.. _subsection-dependencies-pangolinviewer:
+
 Requirements for PangolinViewer
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-| We provided an OpenGL-based simple viewer.
+| We provided another OpenGL-based simple viewer. It is an older viewer with fewer features than IridescenceViewer.
 | This viewer is implemented with `Pangolin <https://github.com/stevenlovegrove/Pangolin>`_. Thus, we call it **PangolinViewer**.
 | Please install the following dependencies if you plan on using PangolinViewer.
 
@@ -106,7 +119,7 @@ Prerequisites for Unix
 Installing for Linux
 ^^^^^^^^^^^^^^^^^^^^
 
-Tested for **Ubuntu 20.04**.
+Tested for **Ubuntu 22.04**.
 
 Install the dependencies via ``apt``.
 
@@ -127,6 +140,10 @@ Install the dependencies via ``apt``.
     # other dependencies
     apt install -y libyaml-cpp-dev libgflags-dev sqlite3 libsqlite3-dev
 
+    # (if you plan on using IridescenceViewer)
+    # Iridescence dependencies
+    apt install -y libglm-dev libglfw3-dev libpng-dev libjpeg-dev libeigen3-dev libboost-filesystem-dev libboost-program-options-dev
+
     # (if you plan on using PangolinViewer)
     # Pangolin dependencies
     apt install -y libglew-dev
@@ -320,6 +337,22 @@ Download, build and install backward-cpp.
         ..
     make -j4 && sudo make install
 
+| (**if you plan on using IridescenceViewer**)
+| Download, build and install Iridescence from source.
+
+.. code-block:: bash
+
+    cd /tmp
+    git clone https://github.com/koide3/iridescence.git
+    cd iridescence
+    git checkout 085322e0c949f75b67d24d361784e85ad7f197ab
+    git submodule update --init --recursive
+    mkdir build && cd build
+    cmake \
+        -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+        ..
+    make -j4 && sudo make install
+
 | (**if you plan on using SocketViewer**)
 | Download, build and install socket.io-client-cpp from source.
 
@@ -382,9 +415,18 @@ Build Instructions
     make -j4
     sudo make install
 
+    # When building with support for IridescenceViewer
+    cd ~/lib
+    git clone --recursive https://github.com/stella-cv/iridescence_viewer.git
+    mkdir -p iridescence_viewer/build
+    cd iridescence_viewer/build
+    cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
+    make -j
+    sudo make install
+
     # When building with support for PangolinViewer
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/pangolin_viewer.git
+    git clone --recursive https://github.com/stella-cv/pangolin_viewer.git
     mkdir -p pangolin_viewer/build
     cd pangolin_viewer/build
     cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
@@ -393,7 +435,7 @@ Build Instructions
 
     # When building with support for SocketViewer
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/socket_publisher.git
+    git clone --recursive https://github.com/stella-cv/socket_publisher.git
     mkdir -p socket_publisher/build
     cd socket_publisher/build
     cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
@@ -402,7 +444,7 @@ Build Instructions
 
     # Install stella_vslam executables
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/stella_vslam_examples.git
+    git clone --recursive https://github.com/stella-cv/stella_vslam_examples.git
     mkdir -p stella_vslam_examples/build
     cd stella_vslam_examples/build
     cmake \

docs/ros2_package.rst

@@ -25,7 +25,24 @@ Please install the following dependencies.
 Build Instructions
 ^^^^^^^^^^^^^^^^^^
 
-(If using Pangolin)
+(If using IridescenceViewer)
+
+.. code-block:: bash
+
+    sudo apt install -y libglm-dev libglfw3-dev libpng-dev libjpeg-dev libeigen3-dev libboost-filesystem-dev libboost-program-options-dev
+    git clone https://github.com/koide3/iridescence.git
+    cd iridescence
+    git checkout 085322e0c949f75b67d24d361784e85ad7f197ab
+    git submodule update --init --recursive
+    mkdir -p build
+    cd build
+    cmake \
+        -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+        ..
+    make -j$(($(nproc) / 2))
+    sudo make install
+
+(If using PangolinViewer)
 
 .. code-block:: bash
 
@@ -110,9 +127,18 @@ Build Instructions
     make -j
     sudo make install
 
+    # When building with support for IridescenceViewer
+    cd ~/lib
+    git clone --recursive https://github.com/stella-cv/iridescence_viewer.git
+    mkdir -p iridescence_viewer/build
+    cd iridescence_viewer/build
+    cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
+    make -j
+    sudo make install
+
     # When building with support for PangolinViewer
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/pangolin_viewer.git
+    git clone --recursive https://github.com/stella-cv/pangolin_viewer.git
     mkdir -p pangolin_viewer/build
     cd pangolin_viewer/build
     cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
@@ -121,7 +147,7 @@ Build Instructions
 
     # When building with support for SocketViewer
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/socket_publisher.git
+    git clone --recursive https://github.com/stella-cv/socket_publisher.git
     mkdir -p socket_publisher/build
     cd socket_publisher/build
     cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..

docs/ros_package.rst

@@ -23,7 +23,24 @@ Please install the following dependencies.
 Build Instructions
 ^^^^^^^^^^^^^^^^^^
 
-(If using Pangolin)
+(If using IridescenceViewer)
+
+.. code-block:: bash
+
+    sudo apt install -y libglm-dev libglfw3-dev libpng-dev libjpeg-dev libeigen3-dev libboost-filesystem-dev libboost-program-options-dev
+    git clone https://github.com/koide3/iridescence.git
+    cd iridescence
+    git checkout 085322e0c949f75b67d24d361784e85ad7f197ab
+    git submodule update --init --recursive
+    mkdir -p build
+    cd build
+    cmake \
+        -DCMAKE_BUILD_TYPE=RelWithDebInfo \
+        ..
+    make -j$(($(nproc) / 2))
+    sudo make install
+
+(If using PangolinViewer)
 
 .. code-block:: bash
 
@@ -108,9 +125,18 @@ Build Instructions
     make -j
     sudo make install
 
+    # When building with support for IridescenceViewer
+    cd ~/lib
+    git clone --recursive https://github.com/stella-cv/iridescence_viewer.git
+    mkdir -p iridescence_viewer/build
+    cd iridescence_viewer/build
+    cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
+    make -j
+    sudo make install
+
     # When building with support for PangolinViewer
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/pangolin_viewer.git
+    git clone --recursive https://github.com/stella-cv/pangolin_viewer.git
     mkdir -p pangolin_viewer/build
     cd pangolin_viewer/build
     cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..
@@ -119,7 +145,7 @@ Build Instructions
 
     # When building with support for SocketViewer
     cd ~/lib
-    git clone -b 0.0.1 --recursive https://github.com/stella-cv/socket_publisher.git
+    git clone --recursive https://github.com/stella-cv/socket_publisher.git
     mkdir -p socket_publisher/build
     cd socket_publisher/build
     cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo ..