Skip to content

Commit 37ec3fb

Browse files
gerni17gerni17
committed
deploy pages and first installation instructions
1 parent 00d0f0e commit 37ec3fb

File tree

11 files changed

+301
-14
lines changed

11 files changed

+301
-14
lines changed

‎.github/workflows/documentation.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: Docs
2+
on: [push, pull_request, workflow_dispatch]
3+
jobs:
4+
docs:
5+
runs-on: ubuntu-latest
6+
steps:
7+
- uses: actions/checkout@v2
8+
- uses: actions/setup-python@v2
9+
- name: Install dependencies
10+
run: |
11+
pip install sphinx sphinx_rtd_theme
12+
- name: Sphinx build
13+
run: |
14+
sphinx-build docs/source docs/_build
15+
- name: Deploy
16+
uses: peaceiris/actions-gh-pages@v3
17+
if: ${{ github.event_name == 'push' }}
18+
with:
19+
publish_branch: gh-pages
20+
github_token: ${{ secrets.GITHUB_TOKEN }}
21+
publish_dir: docs/_build/
22+
force_orphan: true

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,3 +5,4 @@
55
.pytest_cache
66
.run/
77
docs/build
8+
_build

‎docs/source/documentation.rst‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
##################################################
2+
Elevation Mapping cupy documentation
3+
##################################################
4+
Weclome to Elevation Mapping documentation
5+
6+
.. image:: https://github.com/leggedrobotics/elevation_mapping_semantic_cupy/actions/workflows/python-tests.yml/badge.svg
7+
:target: https://github.com/leggedrobotics/elevation_mapping_semantic_cupy/actions/workflows/python-tests.yml/badge.svg
8+
:alt: python tests
9+
10+
11+
Index
12+
---------------
13+
14+
| :doc:`getting_started/index` - What is elevation mapping cupy
15+
| :doc:`getting_started/installation` - How to install the elevation map
16+
| :doc:`getting_started/tutorial` - How to launch the first elevation map
17+
18+
19+
20+
21+
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
22+
plane segmentation is done independently and runs on CPU. When the plane segmentation is generated, local convex approximations of the
23+
terrain can be efficiently generated.
24+
25+
.. image:: ../media/main_repo.png
26+
:alt: Elevation map examples
27+
28+
29+
Citing
30+
---------------
31+
.. hint::
32+
33+
Takahiro Miki, Lorenz Wellhausen, Ruben Grandia, Fabian Jenelten, Timon Homberger, Marco Hutter
34+
35+
Elevation Mapping for Locomotion and Navigation using GPU `Link <https://arxiv.org/abs/2204.12876>`_
36+
37+
38+
39+
.. code-block:: none
40+
41+
@misc{https://doi.org/10.48550/arxiv.2204.12876,
42+
doi = {10.48550/ARXIV.2204.12876},
43+
url = {https://arxiv.org/abs/2204.12876},
44+
author = {Miki, Takahiro and Wellhausen, Lorenz and Grandia, Ruben and Jenelten, Fabian and Homberger, Timon and Hutter, Marco},
45+
keywords = {Robotics (cs.RO), FOS: Computer and information sciences, FOS: Computer and information sciences},
46+
title = {Elevation Mapping for Locomotion and Navigation using GPU},
47+
publisher = {arXiv},
48+
year = {2022},
49+
copyright = {arXiv.org perpetual, non-exclusive license}
50+
}
51+

‎docs/source/getting_started/index.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
1+
.. _introduction:
12

2-
Getting Started
3+
Introduction
34
==================================================
45

5-
.. toctree::
6+
67

78

89

‎docs/source/getting_started/installation.rst‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
.. _installation:
2+
3+
Installation
4+
==================================================
5+
6+
CUDA & cuDNN
7+
-----------------------
8+
9+
The tested versions are CUDA10.2, 11.6
10+
11+
`CUDA <https://docs.nvidia.com/cuda/cuda-installation-guide-linux/index.html#ubuntu-installation>`_
12+
`cuDNN <https://docs.nvidia.com/deeplearning/sdk/cudnn-install/index.html#install-linux>`_
13+
14+
15+
Check how to install :ref:`here<media/cuda-installation.md>`.
16+
17+
Python dependencies
18+
-------------------------------
19+
20+
You will need
21+
22+
* `cupy <https://cupy.chainer.org/>`_
23+
* `numpy <https://www.numpy.org/>`_
24+
* `scipy <https://www.scipy.org/>`_
25+
* `shapely==1.7.1 <https://github.com/Toblerity/Shapely>`_
26+
27+
For traversability filter, either of
28+
29+
* `torch <https://pytorch.org/>`_
30+
* `chainer <https://chainer.org/>`_
31+
32+
Optionally, OpenCV for inpainting filter.
33+
34+
* `opencv-python <https://opencv.org/>`_
35+
36+
Install `numpy`, `scipy`, `shapely`, `opencv-python` with the following command.
37+
38+
```bash
39+
pip3 install -r requirements.txt
40+
```
41+
42+
Cupy
43+
-------------------------------
44+
45+
46+
cupy can be installed with specific CUDA versions. (On jetson, only "from source" i.e. `pip install cupy` could work)
47+
> For CUDA 10.2
48+
> pip install cupy-cuda102
49+
>
50+
> For CUDA 11.0
51+
> pip install cupy-cuda110
52+
>
53+
> For CUDA 11.1
54+
> pip install cupy-cuda111
55+
>
56+
> For CUDA 11.2
57+
> pip install cupy-cuda112
58+
>
59+
> For CUDA 11.3
60+
> pip install cupy-cuda113
61+
>
62+
> For CUDA 11.4
63+
> pip install cupy-cuda114
64+
>
65+
> For CUDA 11.5
66+
> pip install cupy-cuda115
67+
>
68+
> For CUDA 11.6
69+
> pip install cupy-cuda116
70+
>
71+
> (Install CuPy from source)
72+
> % pip install cupy
73+
74+
Traversability filter
75+
-------------------------------
76+
77+
You can choose either pytorch, or chainer to run the CNN based traversability filter.
78+
Install by following the official documents.
79+
80+
* `torch <https://pytorch.org/>`_
81+
* `chainer <https://chainer.org/>`_
82+
83+
Pytorch uses ~2GB more GPU memory than Chainer, but runs a bit faster.
84+
Use parameter `use_chainer` to select which backend to use.
85+
86+
ROS package dependencies
87+
-------------------------------
88+
89+
* `pybind11_catkin <https://github.com/ipab-slmc/pybind11_catkin>`_
90+
* `grid_map <https://github.com/ANYbotics/grid_map>`_
91+
92+
```bash
93+
sudo apt install ros-noetic-pybind11-catkin
94+
sudo apt install ros-noetic-grid-map-core ros-noetic-grid-map-msgs
95+
```
96+
97+
On Jetson
98+
==================================================
99+
100+
CUDA CuDNN
101+
-------------------------------
102+
103+
`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.
104+
105+
python dependencies
106+
-------------------------------
107+
108+
On jetson, you need the version for its CPU arch:
109+
110+
```bash
111+
wget https://nvidia.box.com/shared/static/p57jwntv436lfrd78inwl7iml6p13fzh.whl -O torch-1.8.0-cp36-cp36m-linux_aarch64.whl
112+
pip3 install Cython
113+
pip3 install numpy==1.19.5 torch-1.8.0-cp36-cp36m-linux_aarch64.whl
114+
```
115+
116+
Also, you need to install cupy with
117+
118+
```bash
119+
pip3 install cupy
120+
```
121+
122+
This builds the packages from source so it would take time.
123+
124+
ROS dependencies
125+
-------------------------------
126+
127+
* `pybind11_catkin <https://github.com/ipab-slmc/pybind11_catkin>`_
128+
* `grid_map <https://github.com/ANYbotics/grid_map>`_
129+
130+
```bash
131+
sudo apt install ros-melodic-pybind11-catkin
132+
sudo apt install ros-melodic-grid-map-core ros-melodic-grid-map-msgs
133+
```
134+
135+
Also, on jetson you need fortran (should already be installed).
136+
137+
```bash
138+
sudo apt install gfortran
139+
```
140+
141+
If the Jetson is set up with Jetpack 4.5 with ROS Melodic the following package is additionally required:
142+
143+
```bash
144+
git clone [email protected]:ros/filters.git -b noetic-devel
145+
```
146+
147+
### Plane segmentation dependencies
148+
149+
#### OpenCV
150+
151+
```bash
152+
sudo apt install libopencv-dev
153+
```
154+
155+
#### Eigen
156+
157+
```bash
158+
sudo apt install libeigen3-dev
159+
```
160+
161+
#### CGAL
162+
163+
CGAL5 is required. It will be automatically downloaded and installed into the catkin workspace by the cgal5_catkin package. Make sure you
164+
have the third-party libaries installed on you machine:
165+
166+
```bash
167+
sudo apt install libgmp-dev
168+
sudo apt install libmpfr-dev
169+
sudo apt install libboost-all-dev
170+
```
171+

‎docs/source/getting_started/tutorial.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _tutorial:
2+
3+
Tutorial
4+
==================================================

‎docs/source/index.rst‎

Lines changed: 29 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,40 @@
1-
##################################################
2-
Welcome to elevation_mapping_cupy's documentation!
3-
##################################################
41

2+
.. include:: documentation.rst
53

64
.. toctree::
7-
:maxdepth: 2
8-
:caption: Pages:
5+
:maxdepth: 1
6+
:caption: Overview <documentation>
97

108

11-
getting_started/index
12-
python/index
9+
.. toctree::
10+
:hidden:
11+
:maxdepth: 2
12+
:caption: Getting Started
13+
14+
Introduction <getting_started/index>
15+
Installation <getting_started/installation>
16+
Tutorial <getting_started/tutorial>
17+
18+
.. toctree::
19+
:hidden:
20+
:maxdepth: 2
21+
:caption: Usage
22+
23+
Plugins <usage/plugins>
24+
Parameters <usage/parameters>
25+
Plane Segmentation <usage/plane_segmentation>
26+
Semantics <usage/semantics>
27+
28+
29+
.. toctree::
30+
:hidden:
31+
:maxdepth: 2
32+
:caption: Library
33+
34+
Python <python/index>
1335

14-
Getting Started
15-
---------------
1636

17-
For getting started checkout :doc:`getting_started/index`..
1837

1938

20-
Old Documentation
21-
-----------------
2239

2340

‎docs/source/usage/parameters.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
.. _parameters:
2+
Parameters
3+
==================================================
4+

‎docs/source/usage/plane_segmentation.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
.. _plane_segmentation:
2+
3+
Plane Segmentation
4+
==================================================
5+
6+
.. image:: ../media/convex_approximation.gif
7+
:alt: Convex approximation

‎docs/source/usage/plugins.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.. _plugins:
2+
3+
Plugins
4+
==================================================
5+

0 commit comments

Comments
 (0)