Installation Guide¶

Python Installation¶

This package is available via pip.

pip install pyrender

If you’re on MacOS, you’ll need to pre-install my fork of pyglet, as the version on PyPI hasn’t yet included my change that enables OpenGL contexts on MacOS.

git clone https://github.com/mmatl/pyglet.git
cd pyglet
pip install .

Getting Pyrender Working with OSMesa¶

If you want to render scenes offscreen but don’t want to have to install a display manager or deal with the pains of trying to get OpenGL to work over SSH, you have two options.

The first (and preferred) option is using EGL, which enables you to perform GPU-accelerated rendering on headless servers. However, you’ll need EGL 1.5 to get modern OpenGL contexts. This comes packaged with NVIDIA’s current drivers, but if you are having issues getting EGL to work with your hardware, you can try using OSMesa, a software-based offscreen renderer that is included with any Mesa install.

If you want to use OSMesa with pyrender, you’ll have to perform two additional installation steps:

Installing OSMesa
Installing a Compatible Fork of PyOpenGL

Then, read the offscreen rendering tutorial. See Offscreen Rendering.

Installing OSMesa¶

As a first step, you’ll need to rebuild and re-install Mesa with support for fast offscreen rendering and OpenGL 3+ contexts. I’d recommend installing from source, but you can also try my .deb for Ubuntu 16.04 and up.

Installing from a Debian Package¶

If you’re running Ubuntu 16.04 or newer, you should be able to install the required version of Mesa from my .deb file.

sudo apt update
sudo wget https://github.com/mmatl/travis_debs/raw/master/xenial/mesa_18.3.3-0.deb
sudo dpkg -i ./mesa_18.3.3-0.deb || true
sudo apt install -f

If this doesn’t work, try building from source.

Building From Source¶

First, install build dependencies via apt or your system’s package manager.

sudo apt-get install llvm-6.0 freeglut3 freeglut3-dev

Then, download the current release of Mesa from here. Unpack the source and go to the source folder:

tar xfv mesa-18.3.3.tar.gz
cd mesa-18.3.3

Replace PREFIX with the path you want to install Mesa at. If you’re not worried about overwriting your default Mesa install, a good place is at /usr/local.

Now, configure the installation by running the following command:

./configure --prefix=PREFIX                                   \
            --enable-opengl --disable-gles1 --disable-gles2   \
            --disable-va --disable-xvmc --disable-vdpau       \
            --enable-shared-glapi                             \
            --disable-texture-float                           \
            --enable-gallium-llvm --enable-llvm-shared-libs   \
            --with-gallium-drivers=swrast,swr                 \
            --disable-dri --with-dri-drivers=                 \
            --disable-egl --with-egl-platforms= --disable-gbm \
            --disable-glx                                     \
            --disable-osmesa --enable-gallium-osmesa          \
            ac_cv_path_LLVM_CONFIG=llvm-config-6.0

Finally, build and install Mesa.

make -j8
make install

Finally, if you didn’t install Mesa in the system path, add the following lines to your ~/.bashrc file after changing MESA_HOME to your mesa installation path (i.e. what you used as PREFIX during the configure command).

MESA_HOME=/path/to/your/mesa/installation
export LIBRARY_PATH=$LIBRARY_PATH:$MESA_HOME/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$MESA_HOME/lib
export C_INCLUDE_PATH=$C_INCLUDE_PATH:$MESA_HOME/include/
export CPLUS_INCLUDE_PATH=$CPLUS_INCLUDE_PATH:$MESA_HOME/include/

Installing a Compatible Fork of PyOpenGL¶

Next, install and use my fork of PyOpenGL. This fork enables getting modern OpenGL contexts with OSMesa. My patch has been included in PyOpenGL, but it has not yet been released on PyPI.

git clone git@github.com:mmatl/pyopengl.git
pip install ./pyopengl

Building Documentation¶

The online documentation for pyrender is automatically built by Read The Docs. Building pyrender’s documentation locally requires a few extra dependencies – specifically, sphinx and a few plugins.

To install the dependencies required, simply change directories into the pyrender source and run

$ pip install .[docs]

Then, go to the docs directory and run make with the appropriate target. For example,

$ cd docs/
$ make html

will generate a set of web pages. Any documentation files generated in this manner can be found in docs/build.