vumichien's picture
First commit
b4c8bc3
.. _offscreen_guide:
Offscreen Rendering
===================
.. note::
If you're using a headless server, you'll need to use either EGL (for
GPU-accelerated rendering) or OSMesa (for CPU-only software rendering).
If you're using OSMesa, be sure that you've installed it properly. See
:ref:`osmesa` for details.
Choosing a Backend
------------------
Once you have a scene set up with its geometry, cameras, and lights,
you can render it using the :class:`.OffscreenRenderer`. Pyrender supports
three backends for offscreen rendering:
- Pyglet, the same engine that runs the viewer. This requires an active
display manager, so you can't run it on a headless server. This is the
default option.
- OSMesa, a software renderer.
- EGL, which allows for GPU-accelerated rendering without a display manager.
If you want to use OSMesa or EGL, you need to set the ``PYOPENGL_PLATFORM``
environment variable before importing pyrender or any other OpenGL library.
You can do this at the command line:
.. code-block:: bash
PYOPENGL_PLATFORM=osmesa python render.py
or at the top of your Python script:
.. code-block:: bash
# Top of main python script
import os
os.environ['PYOPENGL_PLATFORM'] = 'egl'
The handle for EGL is ``egl``, and the handle for OSMesa is ``osmesa``.
Running the Renderer
--------------------
Once you've set your environment variable appropriately, create your scene and
then configure the :class:`.OffscreenRenderer` object with a window width,
a window height, and a size for point-cloud points:
>>> r = pyrender.OffscreenRenderer(viewport_width=640,
... viewport_height=480,
... point_size=1.0)
Then, just call the :meth:`.OffscreenRenderer.render` function:
>>> color, depth = r.render(scene)
.. image:: /_static/scene.png
This will return a ``(w,h,3)`` channel floating-point color image and
a ``(w,h)`` floating-point depth image rendered from the scene's main camera.
You can customize the rendering process by using flag options from
:class:`.RenderFlags` and bitwise or-ing them together. For example,
the following code renders a color image with an alpha channel
and enables shadow mapping for all directional lights:
>>> flags = RenderFlags.RGBA | RenderFlags.SHADOWS_DIRECTIONAL
>>> color, depth = r.render(scene, flags=flags)
Once you're done with the offscreen renderer, you need to close it before you
can run a different renderer or open the viewer for the same scene:
>>> r.delete()
Google CoLab Examples
---------------------
For a minimal working example of offscreen rendering using OSMesa,
see the `OSMesa Google CoLab notebook`_.
.. _OSMesa Google CoLab notebook: https://colab.research.google.com/drive/1Z71mHIc-Sqval92nK290vAsHZRUkCjUx
For a minimal working example of offscreen rendering using EGL,
see the `EGL Google CoLab notebook`_.
.. _EGL Google CoLab notebook: https://colab.research.google.com/drive/1rTLHk0qxh4dn8KNe-mCnN8HAWdd2_BEh