Add docker GUI instructions (isl-org#4671)

ECNURoboLab · Feb 1, 2022 · cf6a7a6 · cf6a7a6
1 parent 476cfc2
commit cf6a7a6
Show file tree

Hide file tree

Showing 5 changed files with 166 additions and 77 deletions.
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
@@ -1,9 +1,9 @@
 configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in
     ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile @ONLY)
-
-configure_file(${CMAKE_CURRENT_SOURCE_DIR}/getting_started.rst.in
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/getting_started.in.rst
     ${CMAKE_CURRENT_SOURCE_DIR}/getting_started.rst @ONLY)
-
+configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docker.in.rst
+    ${CMAKE_CURRENT_SOURCE_DIR}/docker.rst @ONLY)
 
 include(FetchContent)
 

diff --git a/docs/arm.rst b/docs/arm.rst
@@ -60,22 +60,12 @@ install is the Docker engine itself. This is especially useful since ARM64 Linux
 has many variants and it could be difficult to configure all dependencies
 manually.
 
-First, install Docker following the `official guide <https://docs.docker.com/get-docker/>`_.
-Also, complete the `post-installation steps for Linux <https://docs.docker.com/engine/install/linux-postinstall/>`_.
-Make sure that ``docker`` can be executed without root privileges. To verify
-Docker is installed correctly, run:
+To build Open3D Python wheel with Docker, you can run one of the following
+commands:
 
 .. code-block:: bash
 
-    # You should be able to run this without sudo.
-    docker run hello-world
-
-The next step is to build Open3D Python wheel with Docker. You can run one of
-the following commands:
-
-.. code-block:: bash
-
-    cd Docker
+    cd docker
 
     ./docker_build.sh openblas-arm64-py36  # Python 3.6
     ./docker_build.sh openblas-arm64-py37  # Python 3.7
@@ -96,8 +86,8 @@ current directly on the host. Then simply install the ``.whl`` file by:
     python -c "import open3d as o3d; c = o3d.geometry.TriangleMesh.create_box(); o3d.visualization.draw_geometries([c])"
     python -c "import open3d as o3d; c = o3d.geometry.TriangleMesh.create_box(); o3d.visualization.draw(c)"
 
-The ``./docker_build.sh`` script works on both Linux and macOS ARM64 hosts.
-You can even cross-compile an ARM64 wheel on an x86-64 host. Install Docker and
+The ``./docker_build.sh`` script works on both Linux and macOS ARM64 hosts.  You
+can even cross-compile an ARM64 wheel on an x86-64 host. Install Docker and
 Qemu:
 
 .. code-block:: bash

diff --git a/docs/docker.in.rst b/docs/docker.in.rst
@@ -0,0 +1,117 @@
+.. _docker:
+
+Docker
+======
+
+Docker provides a convenient way to build, install and run applications isolated
+from the rest of your system. You do not need to change software versions on
+your system or install new software, except the Docker engine itself.
+
+First, install Docker following the `official guide <https://docs.docker.com/get-docker/>`_.
+Also, complete the `post-installation steps for Linux <https://docs.docker.com/engine/install/linux-postinstall/>`_.
+Make sure that ``docker`` can be executed without root privileges. To verify
+Docker is installed correctly, run:
+
+.. code-block:: bash
+
+    # You should be able to run this without sudo.
+    docker run hello-world
+
+
+Install and run Open3D apps in docker
+-------------------------------------
+
+You can install and run Open3D applications from a docker container.
+
+For Python application, you will need to install a minimum set of dependencies.
+For more details please see `this issue
+<https://github.com/isl-org/Open3D/issues/3388>`__. A minimal ``Dockerfile`` for
+Python applications looks like this:
+
+.. code-block:: dockerfile
+
+    # This could also be another Ubuntu or Debian based distribution
+    FROM ubuntu:latest
+
+    # Install Open3D system dependencies and pip
+    RUN apt-get update && apt-get install --no-install-recommends -y \
+        libgl1 \
+        libgomp1 \
+        python3-pip \
+        && rm -rf /var/lib/apt/lists/*
+
+    # Install Open3D from the pypi repositories
+    RUN python3 -m pip install --no-cache-dir --upgrade open3d
+
+If you have an NVIDIA GPU and want to use it for computation (``CUDA``) or
+visualization, follow these `directions.
+<https://docs.docker.com/config/containers/resource_constraints/#gpu>`__
+
+To run GUI applications from the docker container, add these options to the
+``docker run`` command line to ensure that docker has access to the:
+
+1. GPU:
+
+  - Intel (Mesa drivers): ``--device=/dev/dri:/dev/dri``
+
+  - NVIDIA: ``--gpus 'all,"capabilities=compute,utility,graphics"'``
+
+2. X server: ``-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY``
+
+For example, the following commands will build and run the docker container with
+the Open3D viewer application, and provide access to the current directory as
+``/root``.  Once the docker image is built, you can run the container from any
+folder that contains data you wish to visualize.
+
+.. code-block:: bash
+
+    mkdir open3d-viewer-docker && cd open3d-viewer-docker
+    # Download Open3D viewer deb package.
+    wget https://github.com/isl-org/Open3D/releases/download/v@OPEN3D_VERSION@/open3d-app-@[email protected]
+    # Build docker image in folder containing Open3D deb package.
+    docker build -t open3d-viewer -f- . <<EOF
+    FROM ubuntu:latest
+    COPY open3d*.deb /root/
+    RUN apt-get update \
+        && apt-get install --yes /root/open3d*.deb \
+        && rm -rf /var/lib/apt/lists/*
+    ENTRYPOINT ["Open3D"]
+    EOF
+
+    # Allow local X11 connections
+    xhost local:root
+    # Run Open3D viewer docker image with the Intel GPU
+    docker run --device=/dev/dri:/dev/dri \
+        -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY \
+        -v "$PWD":/root open3d-viewer:latest
+    # Run Open3D viewer docker image with the NVIDIA GPU
+    docker run  --gpus 'all,"capabilities=compute,utility,graphics"' \
+        -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY \
+        -v "$PWD":/root open3d-viewer:latest
+
+Also see the `docker tutorial for ROS
+<http://wiki.ros.org/docker/Tutorials/Hardware%20Acceleration>`__ for more
+information.
+
+Building Open3D in Docker
+-------------------------
+
+If your current system does not support the minimum system requirements for
+building Open3D or if you have different versions of Open3D dependencies
+installed, you can build Open3D from source in docker without interfering with
+your system. This may be the case for older OS such as Ubuntu 16.04 or CentOS 7.
+We provide docker build scripts and dockerfiles to build Python wheels in
+various configurations. You can choose between different versions of Python
+(3.7-3.9), hardware architectures (AMD64, ARM64, CUDA) and developer vs release
+modes. Some sample configuration options available are shown below.
+
+.. code-block:: bash
+
+    cd docker
+
+    ./docker_build.sh cuda_wheel_py38_dev  # Python 3.8, AMD64, CUDA with MKL, developer mode
+    ./docker_build.sh openblas-amd64-py36  # Python 3.6, AMD64 with OpenBLAS instead of MKL, release mode
+    ./docker_build.sh openblas-arm64-py37  # Python 3.7, ARM64 with OpenBLAS, release mode
+
+Run ``./docker_build.sh`` without arguments to get a list of all available build
+configurations.
diff --git a/docs/getting_started.rst.in → docs/getting_started.in.rst b/docs/getting_started.rst.in → docs/getting_started.in.rst
@@ -39,8 +39,10 @@ Pip (PyPI)
     pip install open3d
 
 .. note::
-   We recommend using ``pip`` version >=20.3 for better platform compatibility
-   checking in Linux.
+   Please upgrade your ``pip`` to a version >=20.3 to install Open3D in Linux,
+   e.g. with
+
+        ``pip install -U pip>=20.3``
 
 .. note::
     In general, we recommend using a
@@ -85,11 +87,14 @@ version (``HEAD`` of ``master`` branch):
       - `Python 3.8 <https://storage.googleapis.com/open3d-releases-master/python-wheels/open3d-@OPEN3D_VERSION_FULL@-cp38-cp38-win_amd64.whl>`__
       - `Python 3.9 <https://storage.googleapis.com/open3d-releases-master/python-wheels/open3d-@OPEN3D_VERSION_FULL@-cp39-cp39-win_amd64.whl>`__
 
-Please use these links from the `latest version of this page <http://www.open3d.org/docs/latest/getting_started.html>`__ only. For example, to install the latest development version on Linux for Python 3.9:
+Please use these links from the `latest version of this page
+<http://www.open3d.org/docs/latest/getting_started.html>`__ only. For example,
+to install the latest development version on Linux for Python 3.9:
 
 .. code-block:: bash
 
-    pip install --user --pre https://storage.googleapis.com/open3d-releases-master/python-wheels/open3d-@OPEN3D_VERSION_FULL@-cp39-cp39-linux_x86_64.whl
+    pip install --user --pre \
+        https://storage.googleapis.com/open3d-releases-master/python-wheels/open3d-@OPEN3D_VERSION_FULL@-cp39-cp39-linux_x86_64.whl
 
 .. note::
    The development wheels for Linux are named according to PEP600. Please
@@ -112,32 +117,6 @@ Conda
     `the official documentation <https://conda.io/projects/conda/en/latest/user-guide/install/index.html>`_.
 
 
-Docker
-------
-
-If you want to install the Open3D Python packages in a docker container you will
-need to install a minimum set of dependencies. For more details please see `this issue <https://github.com/isl-org/Open3D/issues/3388>`__.
-
-A minimal ``Dockerfile`` looks like this:
-
-.. code-block:: dockerfile
-
-    # This could also be another ubuntu or debian based distributions
-    FROM ubuntu:20.04
-
-    # Install Open3D system dependencies and pip
-    RUN apt-get update && apt-get install --no-install-recommends -y \
-        libgl1 \
-        libgomp1 \
-        python3-pip \
-        && rm -rf /var/lib/apt/lists/*
-
-    # Install Open3D from the pypi repositories
-    RUN python3 -m pip install --no-cache-dir --upgrade open3d
-
-.. note:: If you need ``CUDA`` support, follow these `directions.
-    <https://docs.docker.com/config/containers/resource_constraints/#gpu>`__
-
 Try it
 ------
 
@@ -170,7 +149,7 @@ all Python examples.
 
 .. note:: Open3D's Python tutorial utilizes some external packages: ``numpy``,
     ``matplotlib``, ``opencv-python``. OpenCV is only used for reconstruction
-    system. Please read util/install-deps-python.sh for installing these
+    system. Please read ``util/install-deps-python.sh`` for installing these
     packages.
 
 
@@ -191,7 +170,7 @@ provided here [#]_:
     .. hlist::
         :columns: 2
 
-        * `x86_64 (CXX11 ABI [#]_) <https://storage.googleapis.com/open3d-releases-master/devel/open3d-devel-linux-x86_64-cxx11-abi-@[email protected]>`__
+        * `x86_64 (CXX11 ABI) <https://storage.googleapis.com/open3d-releases-master/devel/open3d-devel-linux-x86_64-cxx11-abi-@[email protected]>`__
         * `x86_64 (CXX11 ABI) with CUDA 11.x <https://storage.googleapis.com/open3d-releases-master/devel/open3d-devel-linux-x86_64-cxx11-abi-cuda-@[email protected]>`__
         * `x86_64 (pre CXX11 ABI) <https://storage.googleapis.com/open3d-releases-master/devel/open3d-devel-linux-x86_64-pre-cxx11-abi-@[email protected]>`__
         * `x86_64 (pre CXX11 ABI) with CUDA 11.x <https://storage.googleapis.com/open3d-releases-master/devel/open3d-devel-linux-x86_64-pre-cxx11-abi-cuda-@[email protected]>`__
@@ -211,8 +190,9 @@ provided here [#]_:
 
 .. [#] Please use these links from the `latest version of this page <http://www.open3d.org/docs/latest/getting_started.html>`__
     only.
-.. [#] To check the `glibc` version on your system, run :code:`ldd --version`
-.. [#] In Linux, do not link code with different CXX11 ABIs, since this will
+.. [#] To check the `glibc` version on your system, run :code:`ldd --version`.
+
+.. note:: In Linux, do not link code with different CXX11 ABIs, since this will
     most likely cause linker errors or crashes. Most system libraries in recent
     Linux versions (e.g. if the OS came with GCC versions 5+) use the CXX11 ABI,
     while PyTorch and Tensorflow libraries typically use the pre CXX11 ABI.
@@ -224,31 +204,32 @@ Try it
 ------
 
 Extract the archive and move the contents to a local folder (such as
-``~/Documents/Open3D_install``):
-
-.. code-block:: bash
-
-    Open3D_install
-    ├── include
-    │   └── open3d
-    │       ├── core
-    │       ├── ...
-    │       ├── Open3DConfig.h
-    │       ├── Open3D.h
-    │       ├── ...
-    └── lib
-        ├── cmake
-        │   └── Open3D
-        ├── libOpen3D.so
-        ├── open3d_tf_ops.so
-        └── open3d_torch_ops.so
-
-
-In Windows, you will have an additional ``bin`` folder with ``Open3D.dll``. Some
-files may be absent in the case of unsupported functionality. To use Open3D with
-your programs through `cmake`, add ``-D Open3D_ROOT=~/Documents/Open3D_install``
-to your CMake configure command line. See the following example CMake projects for
-reference:
+``$HOME/Documents/Open3D_install``):
+
+.. code-block::
+
+    Linux / MacOSX:                       Windows:
+    Open3D_install                        Open3D_install
+    ├── include                           ├── bin
+    │   └── open3d                        │   └── Open3D.dll
+    │       ├── core                      ├── CMake
+    │       ├── ...                       │   ├── Open3DConfig.cmake
+    │       ├── Open3DConfig.h            │   ├── ...
+    │       ├── Open3D.h                  ├── include
+    │       ├── ...                       │   └── open3d
+    └── lib                               │       ├── core
+        ├── cmake                         │       ├── ...
+        │   └── Open3D                    │       ├── Open3DConfig.h
+        │        ├── ...                  │       ├── Open3D.h
+        ├── libOpen3D.so                  │       ├── ...
+        ├── open3d_tf_ops.so              └── lib
+        └── open3d_torch_ops.so               └── Open3D.lib
+
+
+Some files may be absent in the case of unsupported functionality. To use Open3D
+with your programs through `cmake`, add ``-D
+Open3D_ROOT=$HOME/Documents/Open3D_install`` to your CMake configure command
+line. See the following example CMake projects for reference:
 
 * `Find Pre-Installed Open3D Package in CMake <https://github.com/isl-org/open3d-cmake-find-package>`__
 * `Use Open3D as a CMake External Project <https://github.com/isl-org/open3d-cmake-external-project>`__

diff --git a/docs/index.rst b/docs/index.rst
@@ -28,6 +28,7 @@ Open3D: A Modern Library for 3D Data Processing
     builddocs
     open3d_ml
     arm
+    docker
 
 
 .. toctree::
-Original file line number
+Diff line change
@@ Expand Up / @@ -28,6 +28,7 @@ Open3D: A Modern Library for 3D Data Processing @@
         builddocs
         open3d_ml
         arm
+        docker
     .. toctree::
@@ Expand Down @@