fsleyes.gl.globject

This module provides the GLObject class, which is a superclass for all FSLeyes OpenGL overlay types. The following classes are defined in this module:

GLObject The GLObject class is a base class for all OpenGL objects displayed in FSLeyes.
GLSimpleObject The GLSimpleObject class is a convenience superclass for simple rendering tasks (probably fixed-function) which are not associated with a specific overlay, and require no setup or initialisation/management of GL memory or state.

See also the GLImageObject, which is the base class for all GLObject sub-types that display Nifti overlays.

This module also provides a few functions, most importantly createGLObject():

getGLObjectType This function returns an appropriate GLObject type for the given Display.overlayType value.
createGLObject Create GLObject instance for the given overlay, as specified by the Display.overlayType property.
fsleyes.gl.globject.getGLObjectType(overlayType)

This function returns an appropriate GLObject type for the given Display.overlayType value.

fsleyes.gl.globject.createGLObject(overlay, overlayList, displayCtx, canvas, threedee=False)

Create GLObject instance for the given overlay, as specified by the Display.overlayType property.

Parameters:
  • overlay – An overlay object (e.g. a Image instance).
  • overlayList – The OverlayList
  • displayCtx – The DisplayContext managing the scene.
  • canvas – The canvas which will be displaying this GLObject.
  • threedee – If True, the GLObject will be configured for 3D rendering. Otherwise it will be configured for 2D slice-based rendering.
class fsleyes.gl.globject.GLObject(overlay, overlayList, displayCtx, canvas, threedee)

Bases: __main__.MockClass

The GLObject class is a base class for all OpenGL objects displayed in FSLeyes.

Instance attributes

The following attributes will always be available on GLObject instances:

  • name: A unique name for this GLObject instance.
  • overlay: The overlay to be displayed.
  • display: The Display instance describing the
    overlay display properties.
  • opts: The DisplayOpts instance describing the
    overlay-type specific display properties.
  • displayCtx: The DisplayContext managing the scene
    that this GLObject is a part of.
  • canvas: The canvas which is displaying this GLObject.
    Could be a SliceCanvas, a LightBoxCanvas, a Scene3DCanvas, or some future not-yet-created canvas.
  • threedee: A boolean flag indicating whether this GLObject
    is configured for 2D or 3D rendering.

Usage

Once you have created a GLObject:

  1. Do not use the GLObject until its ready() method returns True.
  2. In order to render the GLObject to a canvas, call (in order) the preDraw(), draw2D() (or draw3D()), and postDraw(), methods. Multple calls to draw2D()/draw3D() may occur between calls to preDraw() and postDraw().
  3. Once you are finished with the GLObject, call its destroy() method.

Note that a GLObject which has been created for 2D rendering is not expected be able to render in 3D, nor vice-versa.

Update listeners

A GLObject instance will notify registered listeners when its state changes and it needs to be re-drawn. Entities which are interested in changes to a GLObject instance may register as update listeners, via the Notifier.register() method. It is the resposibility of sub-classes of GLObject to call the Notifier.notify() method to facilitate this notification process.

Sub-class resposibilities*

Sub-class implementations must do the following:

  • Call __init__(). A GLObject.__init__ sub-class method must have the following signature, and must pass all arguments through to GLObject.__init__:

    def __init__(self, overlay, displayCtx, canvas, threedee)

  • Call notify() whenever its OpenGL representation changes.

  • Override the following methods:

    getDisplayBounds This method must calculate and return a bounding box, in the display coordinate system, which contains the entire GLObject.
    getDataResolution This method must calculate and return a sequence of three values, which defines a suitable pixel resolution, along the display coordinate system (x, y, z) axes, for rendering a 2D slice of this GLObject to screen.
    ready This method must return True or False to indicate whether this GLObject is ready to be drawn.
    destroy This method must be called when this GLObject is no longer needed.
    destroyed This method may be called to test whether a call has been made to destroy().
    preDraw This method is called at the start of a draw routine.
    draw2D This method is called on GLObject instances which are configured for 2D rendering.
    draw3D This method is called on GLObject instances which are configured for 3D rendering.
    postDraw This method is called after the draw2D()/draw3D() methods have been called one or more times.

Alternately, a sub-class could derive from one of the following classes, instead of deriving directly from the GLObject class:

GLSimpleObject The GLSimpleObject class is a convenience superclass for simple rendering tasks (probably fixed-function) which are not associated with a specific overlay, and require no setup or initialisation/management of GL memory or state.
__init__(overlay, overlayList, displayCtx, canvas, threedee)

Create a GLObject. The constructor adds one attribute to this instance, name, which is simply a unique name for this instance.

Subclass implementations must call this method, and should also perform any necessary OpenGL initialisation, such as creating textures.

Parameters:
  • overlay – The overlay
  • overlayList – The OverlayList
  • displayCtx – The DisplayContext managing the scene
  • canvas – The canvas that is displaying this GLObject.
  • threedee – Whether this GLObject is to be used for 2D or 3D rendering.
__del__()

Prints a log message.

name

A unique name for this GLObject.

overlay

The overlay being drawn by this GLObject.

canvas

The canvas which is drawing this GLObject.

display

The Display instance containing overlay display properties.

opts

The DisplayOpts instance containing overlay (type-specific) display properties.

overlayList

The OverlayList.

displayCtx

The DisplayContext dsecribing thef scene that this GLObject is a part of.

threedee

Property which is True if this GLObject was configured for 3D rendering, or False if it was configured for 2D slice rendering.

ready()

This method must return True or False to indicate whether this GLObject is ready to be drawn. The method should, for example, make sure that all ImageTexture objects are ready to be used.

getDisplayBounds()

This method must calculate and return a bounding box, in the display coordinate system, which contains the entire GLObject. The bounds must be returned as a tuple with the following structure:

((xlo, ylo, zlo), (xhi, yhi, zhi))

This method must be implemented by sub-classes.

getBoundsLengths()

Convenience method which returns a tuple containing the (x, y, z) lengths of the bounding box which contains the GLObject.

getDataResolution(xax, yax)

This method must calculate and return a sequence of three values, which defines a suitable pixel resolution, along the display coordinate system (x, y, z) axes, for rendering a 2D slice of this GLObject to screen.

This method should be implemented by sub-classes. If not implemented, a default resolution is used. The returned resolution might be used to render this GLObject, but typically only in a low performance environment where off-screen rendering to a GLObjectRenderTexture is used - see the SliceCanvas documentation for more details.

Parameters:
  • xax – Axis to be used as the horizontal screen axis.
  • yax – Axis to be used as the vertical screen axis.
destroy()

This method must be called when this GLObject is no longer needed.

It should perform any necessary cleaning up, such as deleting texture objects.

Note

Sub-classes which override this method must call this implementation.

destroyed()

This method may be called to test whether a call has been made to destroy().

It should return True if this GLObject has been destroyed, False otherwise.

preDraw(xform=None, bbox=None)

This method is called at the start of a draw routine.

It should perform any initialisation which is required before one or more calls to the draw2D()/draw3D() methods are made, such as binding and configuring textures.

See draw2D() for details on the xform and bbox arguments. They are only guaranteed to be passed to the preDraw method in scenarios where only a single call to draw2D or``draw3D`` is made between calls to preDraw and postDraw.

draw2D(zpos, axes, xform=None, bbox=None)

This method is called on GLObject instances which are configured for 2D rendering. It should draw a view of this GLObject - a 2D slice at the given Z location, which specifies the position along the screen depth axis.

Parameters:
  • zpos – Position along Z axis to draw.
  • axes – Tuple containing the (x, y, z) axes in the display coordinate system The x and y axes correspond to the horizontal and vertical display axes respectively, and the z to the depth.
  • xform – If provided, it must be applied to the model view transformation before drawing.
  • bbox – If provided, defines the bounding box, in the display coordinate system, which is to be displayed. Can be used as a performance hint (i.e. to limit the number of things that are rendered).
draw3D(xform=None, bbox=None)

This method is called on GLObject instances which are configured for 3D rendering. It should draw a 3D view of this GLObject.

Parameters:
  • xform – If provided, it must be applied to the model view transformation before drawing.
  • bbox – If provided, defines the bounding box, in the display coordinate system, which is to be displayed. Can be used as a performance hint (i.e. to limit the number of things that are rendered).
drawAll(axes, zposes, xforms)

This is a convenience method for 2D lightboxD canvases, where multple 2D slices at different depths are drawn alongside each other.

This method should do the same as multiple calls to the draw2D() method, one for each of the Z positions and transformation matrices contained in the zposes and xforms arrays (axes is fixed).

In some circumstances (hint: the LightBoxCanvas), better performance may be achieved in combining multiple renders, rather than doing it with separate calls to draw().

The default implementation does exactly this, so this method need only be overridden for subclasses which are able to get better performance by combining the draws.

postDraw(xform=None, bbox=None)

This method is called after the draw2D()/draw3D() methods have been called one or more times.

It should perform any necessary cleaning up, such as unbinding textures.

See the draw2D() method for details on the xform and bbox arguments.

__module__ = 'fsleyes.gl.globject'
class fsleyes.gl.globject.GLSimpleObject(threedee)

Bases: fsleyes.gl.globject.GLObject

The GLSimpleObject class is a convenience superclass for simple rendering tasks (probably fixed-function) which are not associated with a specific overlay, and require no setup or initialisation/management of GL memory or state. It is used by the annotations module.

All subclasses need to do is implement the GLObject.draw2D() and GLObject.draw3D() methods. The annotations module uses the GLSimpleObject class.

Subclasses should not assume that any of the other methods will ever be called.

Note

The GLObject.overlay, GLObject.display, GLObject.opts, GLObject.canvas, GLObject.overlayList and GLObject.displayCtx properties of a GLSimpleObject are all set to None.

__init__(threedee)

Create a GLSimpleObject.

ready()

Overrides GLObject.ready(). Returns True.

destroy()

Overrides GLObject.destroy(). Does nothing.

destroyed()

Overrides GLObject.destroy(). Returns True if destroy() hs been called, False otherwise.

__module__ = 'fsleyes.gl.globject'
preDraw(*args, **kwargs)

Overrides GLObject.preDraw(). Does nothing.

postDraw(*args, **kwargs)

Overrides GLObject.postDraw(). Does nothing.