deploy: eb1c76c

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: d8c4d04a9064022f205d49540eabdd7e
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/documentation.rst.txt

@@ -0,0 +1,69 @@
+##################################################
+Multi-modal elevation mapping's documentation
+##################################################
+Welcome to elevation mapping documentation
+
+.. image:: https://github.com/leggedrobotics/elevation_mapping_semantic_cupy/actions/workflows/python-tests.yml/badge.svg
+    :target: https://github.com/leggedrobotics/elevation_mapping_semantic_cupy/actions/workflows/python-tests.yml/badge.svg
+    :alt: python tests
+
+.. image:: https://github.com/leggedrobotics/elevation_mapping_semantic_cupy/actions/workflows/documentation.yml/badge.svg
+    :target: https://github.com/leggedrobotics/elevation_mapping_semantic_cupy/actions/workflows/documentation.yml/badge.svg
+    :alt: documentation
+
+Index
+---------------
+
+| :doc:`getting_started/introduction` - What is elevation mapping cupy
+| :doc:`getting_started/installation` - How to install the elevation map
+| :doc:`getting_started/tutorial` - How to launch the first elevation map
+
+
+This is a ROS package for elevation mapping on GPU. The elevation mapping code is written in python and uses cupy for GPU computation. The
+plane segmentation is done independently and runs on CPU. When the plane segmentation is generated, local convex approximations of the
+terrain can be efficiently generated.
+
+.. image:: ../media/main_repo.png
+    :alt: Elevation map examples
+.. image:: ../media/main_mem.png
+    :alt: Overview of the project
+
+
+Citing
+---------------
+If you use the elevation mapping cupy, please cite the following paper:
+Elevation Mapping for Locomotion and Navigation using GPU
+
+.. hint:: 
+
+    Elevation Mapping for Locomotion and Navigation using GPU  `Link <https://arxiv.org/abs/2204.12876>`_
+
+    Takahiro Miki, Lorenz Wellhausen, Ruben Grandia, Fabian Jenelten, Timon Homberger, Marco Hutter  
+
+.. code-block::
+
+    @misc{mikielevation2022,
+        doi = {10.48550/ARXIV.2204.12876},
+        author = {Miki, Takahiro and Wellhausen, Lorenz and Grandia, Ruben and Jenelten, Fabian and Homberger, Timon and Hutter, Marco},
+        keywords = {Robotics (cs.RO), FOS: Computer and information sciences, FOS: Computer and information sciences},
+        title = {Elevation Mapping for Locomotion and Navigation using GPU},
+        publisher = {International Conference on Intelligent Robots and Systems (IROS)},
+        year = {2022},
+    }
+
+Multi-modal elevation mapping if you use color or semantic layers
+
+.. hint::
+
+    MEM: Multi-Modal Elevation Mapping for Robotics and Learning  `Link <https://arxiv.org/abs/2309.16818v1>`_
+
+    Gian Erni, Jonas Frey, Takahiro Miki, Matias Mattamala, Marco Hutter
+
+.. code-block::
+
+    @misc{Erni2023-bs,
+        title = "{MEM}: {Multi-Modal} Elevation Mapping for Robotics and Learning",
+        author = "Erni, Gian and Frey, Jonas and Miki, Takahiro and Mattamala, Matias and Hutter, Marco",
+        publisher = {International Conference on Intelligent Robots and Systems (IROS)},
+        year = {2023},
+    }

_sources/getting_started/cuda_installation.rst.txt

@@ -0,0 +1,40 @@
+Cuda installation
+==================================================================
+.. _cuda_installation:
+
+
+CUDA
+-------------------------------------------------------------------
+
+You can download CUDA10.2 from `here <https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/cuda-ubuntu1804.pin>`_.
+You can follow the instruction.
+
+.. code-block:: bash
+
+  wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/cuda-ubuntu1804.pin
+
+  sudo mv cuda-ubuntu1804.pin /etc/apt/preferences.d/cuda-repository-pin-600
+
+  sudo apt-key adv --fetch-keys https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/7fa2af80.pub
+
+  sudo add-apt-repository "deb https://developer.download.nvidia.com/compute/cuda/repos/ubuntu1804/x86_64/ /"
+
+  sudo apt-get update
+
+  sudo apt-get -y install cuda
+
+
+cuDNN
+-------------------------------------------------------------------
+
+You can download specific version from `here <https://developer.download.nvidia.com/compute/machine-learning/repos/ubuntu1804/x86_64/>`_.
+For example, the tested version is with `libcudnn8_8.0.0.180-1+cuda10.2_amd64.deb`.
+
+Then install them using the command below.
+
+.. code-block:: bash
+
+  sudo dpkg -i libcudnn8_8.0.0.180-1+cuda10.2_amd64.deb
+
+  sudo dpkg -i libcudnn8-dev_8.0.0.180-1+cuda10.2_amd64.deb
+

_sources/getting_started/installation.rst.txt

@@ -0,0 +1,275 @@
+.. _installation:
+
+
+Installation
+******************************************************************
+
+This section provides instructions for installing the necessary dependencies for the project. The installation process includes setting up CUDA & cuDNN, installing Python dependencies, and configuring Cupy.
+Follow the instructions carefully to avoid any installation issues.
+
+
+Dockers
+==================================================================
+We provide a docker setup for the project.
+To build the docker image, run the following command:
+
+
+.. code-block:: bash
+
+  cd <project_root>/docker
+  ./build.sh
+
+
+To run the docker image, run the following command:
+
+
+.. code-block:: bash
+
+  cd <project_root>/docker
+  ./run.sh
+
+This will start the docker container and mount the home directory of the host machine to the docker container.
+After you clone the project repository into your catkin_ws, you can build the packages inside the docker container.
+To build the packages inside the docker container, follow the instructions in the `Build section <#build>`_ of this document.
+
+
+On Desktop or Laptop with NVIDIA GPU
+==================================================================
+
+CUDA & cuDNN
+------------------------------------------------------------------
+
+If you do not have CUDA and cuDNN installed, please install them first.
+The tested versions are CUDA10.2, 11.6
+
+`CUDA <https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#ubuntu-installation>`_
+`cuDNN <https://docs.nvidia.com/deeplearning/sdk/cudnn-install/index.html#install-linux>`_
+
+
+You can check how to install :ref:`here<cuda_installation>`.
+
+Python dependencies
+------------------------------------------------------------------
+
+You will need
+
+* `cupy <https://cupy.chainer.org/>`_
+* `numpy <https://www.numpy.org/>`_
+* `scipy <https://www.scipy.org/>`_
+* `shapely==1.7.1 <https://github.com/Toblerity/Shapely>`_
+
+For traversability filter, either of
+
+* `torch <https://pytorch.org/>`_
+* `chainer <https://chainer.org/>`_
+
+Optionally, OpenCV for inpainting filter.
+
+* `opencv-python <https://opencv.org/>`_
+
+Install `numpy`, `scipy`, `shapely`, `opencv-python` with the following command.
+
+.. code-block:: bash
+
+  pip3 install -r requirements.txt
+
+
+Cupy
+-------------------------------------------------------------------
+
+
+cupy can be installed with specific CUDA versions. (On jetson, only "from source" i.e. `pip install cupy` could work)
+For CUDA 10.2
+
+.. code-block:: bash
+
+  pip install cupy-cuda102
+
+For CUDA 11.0
+
+.. code-block:: bash
+
+  pip install cupy-cuda110
+
+For CUDA 11.1
+
+.. code-block:: bash
+
+  pip install cupy-cuda111
+
+For CUDA 11.2
+
+.. code-block:: bash
+
+  pip install cupy-cuda112
+
+For CUDA 11.3
+
+.. code-block:: bash
+
+  pip install cupy-cuda113
+
+For CUDA 11.4
+
+.. code-block:: bash
+
+  pip install cupy-cuda114
+
+For CUDA 11.5
+
+.. code-block:: bash
+
+  pip install cupy-cuda115
+
+For CUDA 11.6
+
+.. code-block:: bash
+
+  pip install cupy-cuda116
+
+(Install CuPy from source)
+
+.. code-block:: bash
+
+  pip install cupy
+
+Traversability filter
+-------------------------------------------------------------------
+
+You can choose either pytorch, or chainer to run the CNN based traversability filter.  
+Install by following the official documents.
+
+* `torch <https://pytorch.org/>`_
+* `chainer <https://chainer.org/>`_
+
+Pytorch uses ~2GB more GPU memory than Chainer, but runs a bit faster.  
+Use parameter `use_chainer` to select which backend to use.
+
+ROS package dependencies
+-------------------------------------------------------------------
+
+* `pybind11_catkin <https://github.com/ipab-slmc/pybind11_catkin>`_
+* `grid_map <https://github.com/ANYbotics/grid_map>`_
+
+.. code-block:: bash
+
+  sudo apt install ros-noetic-pybind11-catkin
+  sudo apt install ros-noetic-grid-map-core ros-noetic-grid-map-msgs
+
+
+On Jetson
+==================================================================
+
+CUDA CuDNN
+-------------------------------------------------------------------
+
+`CUDA` and `cuDNN` can be installed via apt. It comes with nvidia-jetpack. The tested version is jetpack 4.5 with L4T 32.5.0.
+
+Python dependencies
+-------------------------------------------------------------------
+
+On jetson, you need the version for its CPU arch:
+
+.. code-block:: bash
+    
+    wget https://nvidia.box.com/shared/static/p57jwntv436lfrd78inwl7iml6p13fzh.whl -O torch-1.8.0-cp36-cp36m-linux_aarch64.whl
+    pip3 install Cython
+    pip3 install numpy==1.19.5 torch-1.8.0-cp36-cp36m-linux_aarch64.whl
+
+
+Also, you need to install cupy with
+
+.. code-block:: bash
+
+  pip3 install cupy
+
+
+This builds the packages from source so it would take time.
+
+ROS dependencies
+-----------------------
+
+* `pybind11_catkin <https://github.com/ipab-slmc/pybind11_catkin>`_
+* `grid_map <https://github.com/ANYbotics/grid_map>`_
+
+.. code-block:: bash
+
+  sudo apt install ros-melodic-pybind11-catkin
+  sudo apt install ros-melodic-grid-map-core ros-melodic-grid-map-msgs
+
+
+Also, on jetson you need fortran (should already be installed).
+
+.. code-block:: bash
+
+  sudo apt install gfortran
+
+
+If the Jetson is set up with Jetpack 4.5 with ROS Melodic the following package is additionally required:
+
+.. code-block:: bash
+
+  git clone [email protected]:ros/filters.git -b noetic-devel
+
+
+Plane segmentation dependencies
+==================================================================
+
+OpenCV
+-------------------------------------------------------------------
+
+.. code-block:: bash
+
+  sudo apt install libopencv-dev
+
+Eigen
+-------------------------------------------------------------------
+
+.. code-block:: bash
+
+  sudo apt install libeigen3-dev
+
+CGAL
+-------------------------------------------------------------------
+
+CGAL5 is required. It will be automatically downloaded and installed into the catkin workspace by the cgal5_catkin package. Make sure you
+have the third-party libaries installed on you machine:
+
+.. code-block:: bash
+
+  sudo apt install libgmp-dev
+  sudo apt install libmpfr-dev
+  sudo apt install libboost-all-dev
+
+
+Semantic Sensors
+==================================================================
+Elevation mapping node can receive multi-modal point cloud and image topics.
+In this example, we use semantic segmentation models to process color images and publish those topics.
+
+Python dependencies
+-------------------------------------------------------------------
+
+.. code-block:: bash
+
+  pip3 install torchvision scikit-learn
+
+Detectron
+
+.. code-block:: bash
+
+  python3 -m pip install 'git+https://github.com/facebookresearch/detectron2.git'
+
+
+Build
+==================================================================
+After installing all the dependencies, you can build the packages.
+Clone the project repository into your catkin_ws/src directory.
+Then, build the packages with catkin.
+
+.. code-block:: bash
+
+  cd <your_catkin_ws>
+  catkin build elevation_mapping_cupy  # The core package
+  catkin build convex_plane_decomposition_ros  # If you want to use plane segmentation
+  catkin build semantic_sensor  # If you want to use semantic sensors