Headless implementation

anatomist.headless module implements a headless (off-screen) version of Anatomist, and some helper functions.

The main entry point is HeadlessAnatomist:

>>> import anatomist.headless as ana
>>> a = ana.HeadlessAnatomist()

Other functions are used by HeadlessAnatomist implementation.

anatomist.headless.HeadlessAnatomist(*args, **kwargs)[source]

Implements an off-screen headless Anatomist.


Only usable with X11. Needs Xvfb and xdpyinfo commands to be available, and possibly VirtualGL or Mesa.

All X rendering is deported to a virtual X server (Xvfb) which doesn’t actually display things.

Depending on the OpenGL implementation / driver, Xvfb will not necessarily support the GLX extension. This especially happens with NVidia OpenGL on Linux.

To overcome this, HeadlessAnatomist will automatically attempt to use VirtualGL (http://www.virtualgl.org), but:

  • whole application OpenGL rendering will be redirected through VirtualGL, OpenGL calls will be modified.
  • VirtualGL deports the rendering to a working X server, thus this one has to exist (other than Xvfb), to be running, and to have working OpenGL.

If VirtualGL is not available, or not working (no X server), then HeadlessAnatomist will attempt to find a software Mesa library and use it. This has other side effects, since all openGL calls will be software.


This implementation connects to a virtual X server, then runs a regular Anatomist. This has several limiations:

  • All the widgets from the application will be redirected to this display: it is not possible to mix on-screen and off-screen rendering, or a regular on-screen Qt application with off-screen anatomist snapshoting.
  • HeadlessAnatomist should be instantiated before any OpenGL library is loaded to allow tweaking, using either VirtualGL (http://virtualgl.org), or a software Mesa OpenGL if one can be found and is useable. This means any Qt module should not be imported yet, including anatomist.api. If OpenGL is already loaded, just hope its implementation will be compatible with Xvfb.
  • HeadlessAnatomist must be instantiated before any Qt widget is rendered, because Qt does not allow mixed-X displays. Once a widget is created, all others will go to the same display.

Otherwise, returns the unique instance of the configured Anatomist class anatomist.api.Anatomist, as configured via anatomist.setDefaultImplementation(), to it can use any of the different implementations of the Anatomist API.

If OpenGL has already been loaded, or Xvfb cannot be made to work, and if a regular X server conection is working, then a regular, on-screen Anatomist will be used.

Parameters are passed to Anatomist constructor, except the following keyword arguments:

allow_virtualgl: bool (optional)
If False, VirtualGL will not be attempted. Default is True. Use it if you experience crashes in your programs: it probably means that some incompatible libraries have alrealy been loaded.

Try to find a software Mesa library in the libraries search path. Parses the LD_LIBRARY_PATH env variable and libs listed by the command “ldconfig -p”, looks for a mesa/ subdir containing a libGL.so.1 file.

Return type:Mesa library file with full path, or None if not found

Sets up a headless virtual X server and tunes the current process libraries to use it appropriately.


calling this function may run a Xvfb process, and change the current process libraries to use VirtualGL or Mesa GL.

If OpenGL library or Qt QtGui module is loaded, then VirtualGL will not be allowed to prevent crashes.

If Qt QApplication is instantiated, headless mode is disabled because Qt is already connected to a display that cannot change afterwards.

If no configuration proves to work, raise an exception.

Parameters:allow_virtualgl (bool (optional)) – If False, VirtualGL will not be attempted. Default is True. Use it if you experience crashes in your programs: it probably means that some incompatible libraries have alrealy been loaded.

Load VirtualGL libraries and LD_PRELOAD env variable to run the current process via VirtualGL.


If the current process has already used some libraries (libX11? libGL certainly), setting VirtualGL libs afterwards may cause segfaults and program crashes. So it is not safe to use it unless you are sure to to it straight at the beginning of the program, prior to importing many modules.

Unfortunately, I don’t know how to test it.

anatomist.headless.test_glx(xdpyinfo_cmd, timeout=5.0)[source]

Test the presence of the GLX module in the X server, by running xdpyinfo command

  • xdpyinfo_cmd (str or list) – xdpyinfo command: may be a string (‘xdpyinfo’) or a list, which allows running it through a wrapper, ex: [‘vglrun’, ‘xdpyinfo’]
  • timeout (float (optional)) – try several times to connect the X server while waiting for it to startup. If 0, try only once and return.

Return type:

True if GLX is found, False otherwise.

anatomist.headless.test_opengl(pid=None, verbose=False)[source]

Test the presence of OpenGL libraries (and which ones) in the specified Unix process. Works only on Linux (or maybe ELF Unixes).

  • pid (int (optional)) – process id to look OpenbGL libs in. Default: current process
  • verbose (bool (optional)) – if True, print found libs

Return type:

set of loaded libGL libraries


If QtGui is already loaded, switching to VirtualGL in the running process leads to segfaults. Moreover if QApplication is instantiated, the display is already connected and cannot change in Qt afterwards.