Add new Mitsuba Python example + update CPU rendering docs (#5991)

* Add new material estimation example
* Update docs for CPU rendering for Ubuntu 22.04
Co-authored-by: Sameer Sheorey <[email protected]>

Author: errissa

docs/docker.in.rst

@@ -30,10 +30,11 @@ Python applications looks like this:
 .. code-block:: dockerfile
 
     # This could also be another Ubuntu or Debian based distribution
-    FROM ubuntu:latest
+    FROM ubuntu:22.04
 
     # Install Open3D system dependencies and pip
     RUN apt-get update && apt-get install --no-install-recommends -y \
+        libegl1 \
         libgl1 \
         libgomp1 \
         python3-pip \
@@ -52,11 +53,11 @@ To run GUI applications from the docker container, add these options to the
 
 1. GPU:
 
-  - Intel (Mesa drivers): ``--device=/dev/dri:/dev/dri``
+  - Intel (Mesa drivers): ``--device=/dev/dri:/dev/dri`` or ``--device=/dev/dri/card0:/dev/dri/card0 --device=/dev/dri/renderD128:/dev/dri/renderD128``, depending on your hardware.
 
   - NVIDIA: ``--gpus 'all,"capabilities=compute,utility,graphics"'``
 
-  - No GPU (CPU rendering): ``--env OPEN3D_CPU_RENDERING=true``
+  - No GPU (CPU rendering): ``--env OPEN3D_CPU_RENDERING=true`` on Ubuntu 18.04. Later versions automaticaly select CPU rendering if a GPU is not available.
 
 2. X server: ``-v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY``
 
@@ -72,7 +73,7 @@ folder that contains data you wish to visualize.
     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
+    FROM ubuntu:20.04
     COPY open3d*.deb /root/
     RUN apt-get update \
         && apt-get install --yes /root/open3d*.deb \
@@ -91,30 +92,65 @@ folder that contains data you wish to visualize.
         -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY \
         -v "$PWD":/root open3d-viewer:latest
     # Run Open3D viewer docker image without a GPU (CPU rendering)
-    docker run  --env OPEN3D_CPU_RENDERING=true\
-        -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY \
+    docker run -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.
+information. Note that differences in hardware, OS drivers and OS packages may
+require you to modify these instructions.
 
 
 Headless rendering
 ------------------
 If a GUI display server (X11 or Wayland) is not available (either in the docker
-container or the host OS), Open3D can still be used for headless rendering. This
-requires installing some additional dependencies. Here is an example Ubuntu /
-Debian based docker file that runs the ``render_to_image.py`` rendering example.
-Other Linux (e.g. RHEL) distributions will need different dependency packages.
+container or the host OS), Open3D can still be used for headless rendering. In
+Ubuntu 20.04+ (with Mesa version 20.2+) this requires configuring the Mesa
+driver with an environment variable (``EGL_PLATFORM=surfaceless``):
+
+.. code-block:: bash
+
+    mkdir open3d-headless-docker && cd open3d-headless-docker
+    wget https://raw.githubusercontent.com/isl-org/Open3D/v@OPEN3D_VERSION@/examples/python/visualization/render_to_image.py
+    # Build docker image
+    docker build -t open3d-headless -f- . <<EOF
+    FROM ubuntu:20.04
+    RUN apt-get update \
+        && apt-get install --yes --no-install-recommends \
+        libegl1 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 pip && \
+        python3 -m pip install --no-cache-dir --upgrade open3d==@OPEN3D_VERSION@
+
+    # Configure Mesa EGL for headless rendering
+    ENV EGL_PLATFORM=surfaceless
+    WORKDIR /root/
+    ENTRYPOINT ["python3", "/root/render_to_image.py"]
+    EOF
+
+    # Run headless rendering example with Intel GPU
+    docker run --device=/dev/dri:/dev/dri \
+        -v "$PWD":/root open3d-headless:latest
+    # Run headless rendering example with Nvidia GPU
+    docker run  --gpus 'all,"capabilities=compute,utility,graphics"' \
+        -v "$PWD":/root open3d-headless:latest
+    # Run headless rendering example without GPU (CPU rendering)
+    docker run -v "$PWD":/root open3d-headless:latest
+
+In Ubuntu 18.04, we need to install some additional dependencies. Here is an
+example Ubuntu / Debian based docker file that runs the ``render_to_image.py``
+rendering example.  Other (old) Linux (e.g. RHEL) distributions will need
+different dependency packages.
 
 .. code-block:: bash
 
     mkdir open3d-headless-docker && cd open3d-headless-docker
     wget https://raw.githubusercontent.com/isl-org/Open3D/v@OPEN3D_VERSION@/examples/python/visualization/render_to_image.py
     # Build docker image
     docker build -t open3d-headless -f- . <<EOF
-    FROM ubuntu:latest
+    FROM ubuntu:18.04
     RUN apt-get update \
         && apt-get install --yes --no-install-recommends \
         libgl1 libgomp1 python3-pip \

docs/tutorial/visualization/cpu_rendering.rst

@@ -27,28 +27,35 @@ Headless CPU Rendering
 ----------------------
 
 For Python code, you can enable CPU rendering for headless rendering when using
-the :class: `.OffscreenRenderer` for a process by setting the environment
-variable ``OPEN3D_CPU_RENDERING=true`` before importing Open3D. Here are the
-different ways to do that:
+the :class: `.OffscreenRenderer` for a process by setting an environment
+variable  before importing Open3D::
+
+ - ``EGL_PLATFORM=surfaceless`` for Ubuntu 20.04+ (Mesa v20.2 or newer)
+ - ``OPEN3D_CPU_RENDERING=true`` for Ubuntu 18.04 (Mesa older than v20.2).
+
+Here are the different ways to do that:
 
 .. code:: bash
 
-    # from the command line
-    OPEN3D_CPU_RENDERING=true python
-    examples/python/visualization/render_to_image.py
+    # from the command line (Ubuntu 20.04+)
+    EGL_PLATFORM=surfaceless python examples/python/visualization/render_to_image.py
+    # or Ubuntu 18.04
+    OPEN3D_CPU_RENDERING=true python examples/python/visualization/render_to_image.py
 
 .. code:: python
 
     # In Python code
     import os
-    os.environ['OPEN3D_CPU_RENDERING'] = 'true'
+    os.environ['EGL_PLATFORM'] = 'surfaceless'   # Ubunu 20.04+
+    os.environ['OPEN3D_CPU_RENDERING'] = 'true'  # Ubuntu 18.04
     import open3d as o3d
 
     # In a Jupyter notebook
-    %env OPEN3D_CPU_RENDERING true
+    %env EGL_PLATFORM surfaceless   # Ubuntu 20.04+
+    %env OPEN3D_CPU_RENDERING true  # Ubuntu 18.04
     import open3d as o3d
 
-.. note:: Seeting the environment variable after importing ``open3d`` will not work,
+.. note:: Setting the environment variable after importing ``open3d`` will not work,
     even if ``open3d`` is re-imported. In this case, if no usable GPU is present, the
     Python interpreter or Jupyter kernel will crash when visualization functions are
     used.
@@ -89,8 +96,9 @@ The method for enabling interactive CPU rendering depends on your system:
     <https://github.com/isl-org/open3d_downloads/releases/download/mesa-libgl/mesa_libGL_22.0.tar.xz>`__.
     This is automatically downloaded to
     `build/_deps/download_mesa_libgl-src/libGL.so.1.5.0` when you build Open3D
-    from source. If you want to use CPU rendering all the time, install this
-    library to ``/usr/local/lib`` or ``$HOME/.local/lib`` and *prepend* it to your
+    from source. The prebuilt version works on Ubuntu 18.04 and Ubuntu 20.04. If
+    you want to use CPU rendering all the time, install this library to
+    ``/usr/local/lib`` or ``$HOME/.local/lib`` and *prepend* it to your
     ``LD_LIBRARY_PATH``:
 
     .. code:: bash

docs/versions.js

@@ -22,8 +22,8 @@ document.write('\
             <td><a href="http://www.open3d.org/docs/release/cpp_api">0.17.0 C++ (release)</a></td>\
         </tr>\
         <tr>\
-            <td><a href="http://www.open3d.org/docs/0.16.1">0.16.1</a></td>\
-            <td><a href="http://www.open3d.org/docs/0.16.1/cpp_api">0.16.1 C++</a></td>\
+            <td><a href="http://www.open3d.org/docs/0.16.0">0.16.0</a></td>\
+            <td><a href="http://www.open3d.org/docs/0.16.0/cpp_api">0.16.0 C++</a></td>\
         </tr>\
         <tr>\
             <td><a href="http://www.open3d.org/docs/0.15.1">0.15.1</a></td>\