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.

Warning

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:

  • all 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.

Note

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, default: True)
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.
force_virtualgl: bool (optional, default: False)
only meaningful if allow_virtualgl is True. If force_virtualgl True, virtualGL will be attempted even if the X server advertises a GLX extension through the xdpyinfo command (if glxinfo is OK, then this command is trusted). This is useful when GLX is present but does not work when OpenGL is used.
anatomist.headless.find_mesa()[source]

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.

Returns:
Return type:Mesa library file with full path, or None if not found
anatomist.headless.on_parent_exit(signame)[source]

Return a function to be run in a child process which will trigger SIGNAME to be sent when the parent process dies

found on https://gist.github.com/evansd/2346614

anatomist.headless.setup_headless(allow_virtualgl=True, force_virtualgl=False)[source]

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

Warning

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.
  • force_virtualgl (bool (optional)) – only meaningful if allow_virtualgl is True. If force_virtualgl True, virtualGL will be attempted even if the X server advertises a GLX extension. This is useful when GLX is present but does not work when OpenGL is used.
anatomist.headless.setup_virtualGL()[source]

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

Warning

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 do 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(glxinfo_cmd=None, xdpyinfo_cmd=None, timeout=5.0)[source]

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

Parameters:
  • glxinfo_cmd (str or list) – glxinfo command: may be a string (‘glxinfo’) or a list, which allows running it through a wrapper, ex: [‘vglrun’, ‘glxinfo’]
  • 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’]. xdpyinfo is only used if glxinfo is not present, and can produce an inaccurate result (some xvfb servers advertise a GLX extension which does not work in fact).
  • timeout (float (optional)) – try several times to connect the X server while waiting for it to startup. If 0, try only once and return.
Returns:

  • 2 if GLX is recognized trough glxinfo (trustable), 1 if GLX is recognized
  • through xdpyinfo (not always trustable), 0 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).

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

set of loaded libGL libraries
anatomist.headless.test_qapp()[source]

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.