Document how to use VTK/vtki in Docker containers & Travis

Trying to run any VTKI rendering within a Dockerized Jupyter notebook causes a kernel crash, with the message:

ERROR: In ../Rendering/OpenGL2/vtkXOpenGLRenderWindow.cxx, line 452
vtkXOpenGLRenderWindow (0x560a53bb7ce0): bad X server connection. DISPLAY=[I 00:12:28.476 NotebookApp] KernelRestarter: restarting kernel (1/5), keep random ports
kernel 0839b810-c699-472b-bd57-11c5cfed7fa5 restarted

I believe this is a more fundamental issue than VTKI (I have a VTK issue open here), but I am hoping that someone else using VTKI has experienced this and has a workaround, or that there is a way to run VTKI in ‘headless’ (virtual framebuffer) mode.

[daniellivingston]

Thank you so much! You’ve been so helpful.

I was having trouble propagating environment var DISPLAY to the subshell that Python lives in (it turns out it’s a little tricky in Docker to do this…), but I settled on this as a working solution:

def activate_virtual_framebuffer():
    '''
    Activates a virtual (headless) framebuffer for rendering 3D
    scenes via VTK.

    Most critically, this function is useful when this code is being run
    in a Dockerized notebook, or over a server without X forwarding.

    * Requires the following packages:
      * `sudo apt-get install libgl1-mesa-dev xvfb`
    '''

    import subprocess
    import vtki

    vtki.OFFSCREEN = True
    os.environ['DISPLAY']=':99.0'

    commands = ['Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &',
                'sleep 3',
                'exec "$@"']

    for command in commands:
        subprocess.call(command,shell=True)

And then, on module import, I check if I’m in the Docker container (in a rather inelegant way…) and run the function from there:

if os.path.isdir('/home/jovyan'):
    activate_virtual_framebuffer()

Thank you again!

[banesullivan]

It’s going to really bring it to the masses.

Hopefully, this gets it started:

Now all examples from the gallery are available on MyBinder 🎉 🎉