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)[source]¶ This function returns an appropriate
GLObject
type for the givenDisplay.overlayType
value.
-
fsleyes.gl.globject.
createGLObject
(overlay, overlayList, displayCtx, canvas, threedee=False)[source]¶ Create
GLObject
instance for the given overlay, as specified by theDisplay.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
, theGLObject
will be configured for 3D rendering. Otherwise it will be configured for 2D slice-based rendering.
- overlay – An overlay object (e.g. a
-
class
fsleyes.gl.globject.
GLObject
(overlay, overlayList, displayCtx, canvas, threedee)[source]¶ 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 thisGLObject
instance.overlay
: The overlay to be displayed.display
: TheDisplay
instance describing the- overlay display properties.
opts
: TheDisplayOpts
instance describing the- overlay-type specific display properties.
displayCtx
: TheDisplayContext
managing the scene- that this
GLObject
is a part of.
canvas
: The canvas which is displaying thisGLObject
.- Could be a
SliceCanvas
, aLightBoxCanvas
, aScene3DCanvas
, or some future not-yet-created canvas.
threedee
: A boolean flag indicating whether thisGLObject
- is configured for 2D or 3D rendering.
Usage
Once you have created a
GLObject
:- Do not use the
GLObject
until itsready()
method returnsTrue
. - In order to render the
GLObject
to a canvas, call (in order) thepreDraw()
,draw2D()
(ordraw3D()
), andpostDraw()
, methods. Multple calls todraw2D()
/draw3D()
may occur between calls topreDraw()
andpostDraw()
. - Once you are finished with the
GLObject
, call itsdestroy()
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 aGLObject
instance may register as update listeners, via theNotifier.register()
method. It is the resposibility of sub-classes ofGLObject
to call theNotifier.notify()
method to facilitate this notification process.Sub-class resposibilities*
Sub-class implementations must do the following:
Call
__init__()
. AGLObject.__init__
sub-class method must have the following signature, and must pass all arguments through toGLObject.__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 thisGLObject
to screen.ready
This method must return True
orFalse
to indicate whether thisGLObject
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)[source]¶ 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.
-
name
¶ A unique name for this
GLObject
.
-
overlay
¶ The overlay being drawn by this
GLObject
.
-
canvas
¶ The canvas which is drawing this
GLObject
.
-
opts
¶ The
DisplayOpts
instance containing overlay (type-specific) display properties.
-
overlayList
¶ The
OverlayList
.
-
displayCtx
¶ The
DisplayContext
dsecribing thef scene that thisGLObject
is a part of.
-
threedee
¶ Property which is
True
if thisGLObject
was configured for 3D rendering, orFalse
if it was configured for 2D slice rendering.
-
ready
()[source]¶ This method must return
True
orFalse
to indicate whether thisGLObject
is ready to be drawn. The method should, for example, make sure that allImageTexture
objects are ready to be used.
-
getDisplayBounds
()[source]¶ 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
()[source]¶ Convenience method which returns a tuple containing the
(x, y, z)
lengths of the bounding box which contains theGLObject
.
-
getDataResolution
(xax, yax)[source]¶ 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 thisGLObject
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 aGLObjectRenderTexture
is used - see theSliceCanvas
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
()[source]¶ 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 thisGLObject
has been destroyed,False
otherwise.
-
preDraw
(xform=None, bbox=None)[source]¶ 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 thexform
andbbox
arguments. They are only guaranteed to be passed to thepreDraw
method in scenarios where only a single call todraw2D
or``draw3D`` is made between calls topreDraw
andpostDraw
.
-
draw2D
(zpos, axes, xform=None, bbox=None)[source]¶ This method is called on
GLObject
instances which are configured for 2D rendering. It should draw a view of thisGLObject
- 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 Thex
andy
axes correspond to the horizontal and vertical display axes respectively, and thez
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)[source]¶ This method is called on
GLObject
instances which are configured for 3D rendering. It should draw a 3D view of thisGLObject
.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)[source]¶ 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 thezposes
andxforms
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 todraw()
.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)[source]¶ 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 thexform
andbbox
arguments.
-
__module__
= 'fsleyes.gl.globject'¶
-
class
fsleyes.gl.globject.
GLSimpleObject
(threedee)[source]¶ 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 theannotations
module.All subclasses need to do is implement the
GLObject.draw2D()
andGLObject.draw3D()
methods. Theannotations
module uses theGLSimpleObject
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
andGLObject.displayCtx
properties of aGLSimpleObject
are all set toNone
.-
ready
()[source]¶ Overrides
GLObject.ready()
. ReturnsTrue
.
-
destroy
()[source]¶ Overrides
GLObject.destroy()
. Does nothing.
-
destroyed
¶ Overrides
GLObject.destroy()
. ReturnsTrue
ifdestroy()
hs been called,False
otherwise.
-
__module__
= 'fsleyes.gl.globject'¶
-
preDraw
(*args, **kwargs)[source]¶ Overrides
GLObject.preDraw()
. Does nothing.
-
postDraw
(*args, **kwargs)[source]¶ Overrides
GLObject.postDraw()
. Does nothing.
-