Setting up headless (offscreen) rendering for Mayavi (and VTK 5.8) in Ubuntu 13.04

The terms headless rendering (or offscreen rendering) seem to imply a number of differing rendering choices. ‘Headless rendering’ might involve rendering a scene:

  1. Without showing a window
  2. On a headless server (no active window manager)
  3. Without any graphics card (software rendering)

Unfortunately, the way to do these things changes a lot between VTK versions. I have chosen VTK 5.8 because I am particularly interested in using it for offscreen rendering using Mayavi in Python and Mayavi only (at the time of writing) supports VTK 5.8. Therefore, my examples will assume that we are attempting to use VTK 5.8.

Without showing a window

This is exactly the same as the example given in the Mayavi documentation:

from mayavi import mlab
mlab.options.offscreen = True
mlab.test_contour3d()
mlab.savefig('example.png')

This just involves setting the offscreen option to True. However, this assume that you are rendering inside an active X11 session. This obviously implies the existence of a graphics card!

On a headless server (no X11)

This, as documented in the Mayavi documentation, involves providing a virtual X11 buffer. This requires the command xvfb-run, which can be installed using apt-get:

sudo apt-get install xvfb

Once installed, a virtual X11 frame buffer can be provided with the command:

xvfb-run --server-args="-screen 0 1024x768x24" python my_script.py

You will still probably want to use the offscreen flag as previously shown!

Software rendering

This is when things start to get particularly tricky. In the case, we need to compile a custom version of VTK 5.8 that is linked against an appropriate software renderer. In the case of Linux, this is OSMesa. Now, given that we are running on Linux, we will want to use the fastest software rasterizer we can, which is llvmpipe. Therefore, we begin the complex process of building VTK 5.8 with offscreen rendering support. I was unable to generalise this process, and only able to get it working for very specific versions of the requisite libraries. Confirmation of using more recent versions is greatly appreciated.

Building OSMesa

Download OSMesa 9.2.3 from here. You will need to make sure you have all the dependencies as outlined here, but most probably, for Ubuntu, you will need

sudo apt-get install scons flex bison

You will also need LLVM with version greater than 3.0. I managed to get it working by installing LLVM 3.2 (though I think 3.3 works as well):

sudo apt-get install llvm-3.2-dev llvm-3.2-source

Given that we got this from aptitude, it doesn’t seem to setup LLVM properly, so we need to set up the correct sumbolic link to llvm-config:

sudo ln -s /usr/bin/llvm-config-3.2 /usr/local/bin/llvm-config

We can then build llvmpipe by navigating in to the extracted OSMesa folder and executing:

scons llvm=yes build=release mesa osmesa libgl-xlib

Which has then successfully built llvmpipe and OSMesa.

Building Offscren VTK 5.8

Download VTK 5.8 from here.

Unzip it, make a folder called ‘build’ inside it and then create a new script inside build called

configure_cmake.sh

Inside, paste the following script:

MESA_INSTALL_PREFIX=PATH_TO_MESA_9.2.3_FOLDER
 
cmake \
 -DBUILD_SHARED_LIBS=ON \
 -DVTK_WRAP_PYTHON=ON \
 -DVTK_USE_X=OFF \
 -DOPENGL_INCLUDE_DIR=${MESA_INSTALL_PREFIX}/include \
 -DOPENGL_gl_LIBRARY=${MESA_INSTALL_PREFIX}/build/linux-x86_64/gallium/targets/libgl-xlib/libGL.so \
 -DOPENGL_glu_LIBRARY=/usr/lib/x86_64-linux-gnu/libGLU.so \
 -DVTK_OPENGL_HAS_OSMESA=ON \
 -DOSMESA_INCLUDE_DIR=${MESA_INSTALL_PREFIX}/include \
 -DOSMESA_LIBRARY=${MESA_INSTALL_PREFIX}/build/linux-x86_64/mesa/drivers/osmesa/libosmesa.so \
 ..

Where MESA_INSTALL_PREFIX is the absolute path to wherever you extracted the OSMesa archive.

You can then run

make

To make VTK, which takes a while. You may want to use the -j switch to decrease compile times.

Once VTK is finished, we can set up a virtualenv to use the offscreen VTK.

Setting up Mayavi

Create a virtualenv, then cd to

PATH_TO_VTK5.8/build/Wrapping/Python

where PATH_TO_VTK5.8 is the absolute path to wherever you built VTK 5.8.

You can then install it in to the virtualenv by running

LD_LIBRARY_PATH=PATH_TO_VTK5.8/build/bin/ python setup.py install

Then, to test it worked, run

LD_LIBRARY_PATH=/PATH_TO_VTK5.8/build/bin/ python

Then try

import vtk

which should work without error.

Then install mayavi by running

pip install numpy
LD_LIBRARY_PATH=/PATH_TO_VTK5.8/build/bin/ pip install mayavi

Then, we can test everything worked by running

LD_LIBRARY_PATH=/PATH_TO_VTK5.8/build/bin/ python

and trying

from mayavi import mlab
mlab.options.offscreen = True
mlab.test_contour3d()
mlab.savefig('example.png')

which should successfully create the image!

In order to avoid pre-pending every command with

LD_LIBRARY_PATH=/PATH_TO_VTK5.8/build/bin/

You can update your LD_LIBRARY_PATH using any of the normal ways on Linux (creating a conf file in /etc/ld.so.conf.d/ or updating your .bashrc file).

Transferring files to an Amazon EC2 instance (setting up SFTP)

Just a quick tutorial on the basic steps to get SFTP set up and running on an Amazon EC2 instance. First you need to launch an instance. In this particular case I assume the use of the Amazon EC2 web interface and not the command line tools. If you wish to use the command tools then there are many good resources that can be found using Google.

Server Setup

Use the web interface to begin launching an instance. In this case I choose to launch a default Ubuntu 12.04 Server instance. The next few tabs are not particularly relevant – until we reach the create a key-pair tab. Give the key-pair a unique name and download and save it somewhere secure. Also make sure that the a security group that has Port 22 open.

If you are using Windows and putty you will need to convert the key-pair to an appropriate format. You can do this by downloading putty-gen and then load the generated key-pair using the File menu. You will need to switch the file type filter to All Files to be able to see the .pem file. You can then convert the file to a .ppk file for use with programs that use the Putty protocol.

WinSCP Setup

Assuming you were going to use WinSCP:

Add a new Host and set up the detail as follows (bold implies an explicit value and italics implies a value to be provided by you):

Host Name: EC2 Public DNS (eg. ec2-255-255-255-255.eu-west-1.compute.amazonaws.com)
User Name: ubuntu
Password: blank
Private Key File: The .ppk file we just generated (e.g. my_key.ppk)
Protocol: SFTP

Notice that this tutorial follows on from my previous tutorial on setting up FTP on an EC2 instance. As noted on this StackOverflow question it is much safer to use SFTP over FTP as your authentication details are not sent in plaintext.

Maven dependency for org.netbeans.* (AbsoluteLayout) in a Swing application

Just a quick post about how to resolve dependency errors in Netbeans when setting up Maven for a Swing application. I struggled to find any information on which repositories to use so thought I would post in case other people had the same issues as me.

If you create a Maven project and add existing Swing .java files then you may find errors such as:

Error package org.netbeans.lib.awtextra does not exist ...

This package resides in the AbsoluteLayout.jar that is normally automatically supplied by Netbeans. In order to add this dependency to your Maven pom.xml you need to add the following lines:

<repositories>
  <!--These are needed for Swing/Netbeans -->
  <repository>
    <id>maven2-repository.netbeans.maven2</id>
    <name>Netbeans Maven Repository</name>
    <url>http://bits.netbeans.org/maven2/</url>
    <layout>default</layout>
  </repository> 
</repositories>

This should be added somewhere above the opening tag.
Then add:

<dependency>
      <groupId>org.netbeans.external</groupId>
      <artifactId>AbsoluteLayout</artifactId>
      <version>RELEASE701</version>
</dependency>

You can check for the latest version of AbsoluteLayout.jar here.