Offscreen rendering in a Linux docker container


Staff member
This is to share my recent discovery. I was looking for a way to dump PNG images in a headless offscreen mode in a Linux docker container (Ubuntu image, but that does not really matter). As it appears, there are few things to keep in mind:
  1. There are no specific flags for compilation, whatever you should be aware of. OpenCascade will be able to do the offscreen rendering job out of the box. This releases you from the necessity to have two versions of the library (one for the offscreen mode, another's for UI), as I have for VTK.
  2. Install and enable freeimage (with the USE_FREEIMAGE CMake variable of OpenCascade) if you'd like to dump to the familiar PNG format. By default, OpenCascade dumps the images to Netpbm format on Linux, which is weird.
  3. Install and enable xvfb to create windows (even virtual offscreen ones demand this). Without a virtual window constructed by an X server, offscreen rendering is impossible. In the video related to Docker and OpenCascade, I used another technique of binding a client to the docker container. That might work in some cases but does not allow for remote batch processing (the most popular use case for this whole offscreen rendering + OpenCascade + docker story).
  4. Initialize your virtual X server when running your program in a docker container (see bash script below).
Here is the bash script that I run on my docker. The idea here is to launch xvfb before starting the main app that is supposed to render offscreen. I found this script somewhere in VTK forums, and it all worked like a charm.


export DISPLAY=:99.0
which Xvfb
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
sleep 3

EXEC_PATH=$(dirname "$0")
export LD_LIBRARY_PATH="${EXEC_PATH}/;${EXEC_PATH}/../lib;${EXEC_PATH}/asi-plugins"
eval "${EXEC_PATH}/asiExe $@"

The Dockerfile for OpenCascade itself is here:

If you have experience with offscreen rendering in Docker, you're very welcome to share it here.