fsleyes.gl.annotations

This module provides the Annotations class, which implements functionality to draw 2D OpenGL annotations on a SliceCanvas.

The Annotations class is used by the SliceCanvas and LightBoxCanvas classes, and users of those class, to annotate the canvas.

All annotations derive from the AnnotationObject base class. The following annotation types are defined:

Line The Line class is an AnnotationObject which represents a 2D line.
Rect The Rect class is an AnnotationObject which represents a 2D rectangle.
VoxelGrid The VoxelGrid is an AnnotationObject which represents a collection of selected voxels.
VoxelSelection A VoxelSelection is an AnnotationObject which draws selected voxels from a Selection instance.
class fsleyes.gl.annotations.Annotations(canvas, xax, yax)

Bases: object

An Annotations object provides functionality to draw 2D annotations on a SliceCanvas. Annotations may be enqueued via any of the line(), rect(), grid(), selection() or obj(), methods.

A call to draw() will then draw each of the queued annotations on the canvas, and clear the queue.

If an annotation is to be persisted, it can be enqueued, as above, but passing hold=True to the queueing method. The annotation will then remain in the queue until it is removed via dequeue(), or the entire annotations queue is cleared via clear().

Annotations can be queued by one of the helper methods on the Annotations object (e.g. line() or rect()), or by manually creating an AnnotationObject and passing it to the obj() method.

__init__(canvas, xax, yax)

Creates an Annotations object.

Parameters:
  • canvas – The SliceCanvas that owns this Annotations object.
  • xax – Index of the display coordinate system axis that corresponds to the horizontal screen axis.
  • yax – Index of the display coordinate system axis that corresponds to the vertical screen axis.
canvas

Returns a ref to the canvas that owns this Annotations instance.

setAxes(xax, yax)

This method must be called if the display orientation changes. See __init__().

getDisplayBounds()

Returns a tuple containing the (xmin, xmax, ymin, ymax) display bounds of the SliceCanvas that owns this Annotations object.

line(*args, **kwargs)

Queues a line for drawing - see the Line class.

rect(*args, **kwargs)

Queues a rectangle for drawing - see the Rectangle class.

grid(*args, **kwargs)

Queues a voxel grid for drawing - see the VoxelGrid class.

selection(*args, **kwargs)

Queues a selection for drawing - see the VoxelSelection class.

text(*args, **kwargs)

Queues a text annotation for drawing - see the Text class.

obj(obj, hold=False)

Queues the given AnnotationObject for drawing.

Parameters:hold – If True, the given AnnotationObject will be kept in the queue until it is explicitly removed. Otherwise (the default), the object will be removed from the queue after it has been drawn.
dequeue(obj, hold=False)

Removes the given AnnotationObject from the queue, but does not call its GLObject.destroy() method - this is the responsibility of the caller.

clear()

Clears both the normal queue and the persistent (a.k.a. hold) queue, and calls the GLObject.destroy() method on every object in the queue.

draw(zpos, xform=None, skipHold=False)

Draws all enqueued annotations.

Parameters:
  • zpos – Position along the Z axis, above which all annotations should be drawn.
  • xform – Transformation matrix which should be applied to all objects.
  • skipHold – Do not draw items on the hold queue - only draw one-off items.
__dict__ = mappingproxy({'__module__': 'fsleyes.gl.annotations', '__doc__': 'An :class:`Annotations` object provides functionality to draw 2D\n annotations on a :class:`.SliceCanvas`. Annotations may be enqueued via\n any of the :meth:`line`, :meth:`rect`, :meth:`grid`, :meth:`selection` or\n :meth:`obj`, methods.\n\n\n A call to :meth:`draw` will then draw each of the queued annotations on\n the canvas, and clear the queue.\n\n\n If an annotation is to be persisted, it can be enqueued, as above, but\n passing ``hold=True`` to the queueing method. The annotation will then\n remain in the queue until it is removed via :meth:`dequeue`, or the\n entire annotations queue is cleared via :meth:`clear`.\n\n\n Annotations can be queued by one of the helper methods on the\n :class:`Annotations` object (e.g. :meth:`line` or :meth:`rect`), or by\n manually creating an :class:`AnnotationObject` and passing it to the\n :meth:`obj` method.\n ', '__init__': <function Annotations.__init__>, 'canvas': <property object>, 'setAxes': <function Annotations.setAxes>, 'getDisplayBounds': <function Annotations.getDisplayBounds>, 'line': <function Annotations.line>, 'rect': <function Annotations.rect>, 'grid': <function Annotations.grid>, 'selection': <function Annotations.selection>, 'text': <function Annotations.text>, 'obj': <function Annotations.obj>, 'dequeue': <function Annotations.dequeue>, 'clear': <function Annotations.clear>, 'draw': <function Annotations.draw>, '__dict__': <attribute '__dict__' of 'Annotations' objects>, '__weakref__': <attribute '__weakref__' of 'Annotations' objects>})
__module__ = 'fsleyes.gl.annotations'
__weakref__

list of weak references to the object (if defined)

class fsleyes.gl.annotations.AnnotationObject(annot, xform=None, colour=None, width=None, enabled=True, expiry=None, zmin=None, zmax=None)

Bases: fsleyes.gl.globject.GLSimpleObject

Base class for all annotation objects. An AnnotationObject is drawn by an Annotations instance. The AnnotationObject contains some attributes which are common to all annotation types:

colour Annotation colour
width Annotation line width (if the annotation is made up of lines)
xform Custom transformation matrix to apply to annotation vertices.
expiry Time (in seconds) after which the annotation will expire and not be drawn.
zmin Minimum z value below which this annotation will not be drawn.
zmax Maximum z value above which this annotation will not be drawn.
creation Time of creation.

All of these attributes can be modified directly, after which you should trigger a draw on the owning SliceCanvas to refresh the annotation. You shouldn’t touch the expiry or creation attributes though.

Subclasses must, at the very least, override the globject.GLObject.draw2D() method.

__init__(annot, xform=None, colour=None, width=None, enabled=True, expiry=None, zmin=None, zmax=None)

Create an AnnotationObject.

Parameters:
  • annot – The Annotations object that created this AnnotationObject.
  • xform – Transformation matrix which will be applied to all vertex coordinates.
  • colour – RGB/RGBA tuple specifying the annotation colour.
  • width – Line width to use for the annotation.
  • enabled – Initially enabled or disabled.
  • expiry – Time (in seconds) after which this annotation should be expired and not drawn.
  • zmin – Minimum z value below which this annotation should not be drawn.
  • zmax – Maximum z value above which this annotation should not be drawn.
resetExpiry()

Resets the expiry for this AnnotationObject so that it is valid from the current time.

expired(now)

Returns True if this Annotation has expired, False otherwise.

Parameters:now – The current time
preDraw(*args, **kwargs)

Overrides GLObject.preDraw(). Does nothing.

postDraw(*args, **kwargs)

Overrides GLObject.postDraw(). Does nothing.

__module__ = 'fsleyes.gl.annotations'
class fsleyes.gl.annotations.Line(annot, xy1, xy2, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

The Line class is an AnnotationObject which represents a 2D line.

__init__(annot, xy1, xy2, *args, **kwargs)

Create a Line annotation.

The xy1 and xy2 coordinate tuples should be in relation to the axes which map to the horizontal/vertical screen axes on the target canvas.

Parameters:
  • annot – The Annotations object that owns this Line.
  • xy1 – Tuple containing the (x, y) coordinates of one endpoint.
  • xy2 – Tuple containing the (x, y) coordinates of the second endpoint.

All other arguments are passed through to AnnotationObject.__init__().

draw2D(zpos, axes)

Draws this Line annotation.

__module__ = 'fsleyes.gl.annotations'
class fsleyes.gl.annotations.Rect(annot, xy, w, h, filled=False, fillColour=None, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

The Rect class is an AnnotationObject which represents a 2D rectangle.

__init__(annot, xy, w, h, filled=False, fillColour=None, *args, **kwargs)

Create a Rect annotation.

Parameters:
  • annot – The Annotations object that owns this Rect.
  • xy – Tuple specifying bottom left of the rectangle, in the display coordinate system.
  • w – Rectangle width.
  • h – Rectangle height.
  • filled – If True, the rectangle is filled with the fillColour.
  • fillColour – If filled=True, the colour to fill the rectangle with. Defaults to a transparent version of the colour.

All other arguments are passed through to AnnotationObject.__init__().

draw2D(zpos, axes)

Draws this Rectangle annotation.

_Rect__drawFill(zpos, xax, yax, zax, bl, br, tl, tr)

Draw a filled version of the rectangle.

_Rect__drawRect(zpos, xax, yax, zax, bl, br, tl, tr)

Draw the rectangle outline.

__module__ = 'fsleyes.gl.annotations'
class fsleyes.gl.annotations.VoxelGrid(annot, selectMask, displayToVoxMat, voxToDisplayMat, offsets=None, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

The VoxelGrid is an AnnotationObject which represents a collection of selected voxels. See also the VoxelSelection annotation.

Each selected voxel is highlighted with a rectangle around its border.

__init__(annot, selectMask, displayToVoxMat, voxToDisplayMat, offsets=None, *args, **kwargs)

Create a VoxelGrid annotation.

Parameters:
  • annot – The Annotations object that owns this VoxelGrid.
  • selectMask – A 3D numpy array, the same shape as the image being annotated (or a sub-space of the image - see the offsets argument), which is interpreted as a mask array - values which are True denote selected voxels.
  • displayToVoxMat – A transformation matrix which transforms from display space coordinates into voxel space coordinates.
  • voxToDisplayMat – A transformation matrix which transforms from voxel coordinates into display space coordinates.
  • offsets – If None (the default), the selectMask must have the same shape as the image data being annotated. Alternately, you may set offsets to a sequence of three values, which are used as offsets for the xyz voxel values. This is to allow for a sub-space of the full image space to be annotated.
draw2D(zpos, axes)

Draws this VoxelGrid annotation.

__module__ = 'fsleyes.gl.annotations'
class fsleyes.gl.annotations.VoxelSelection(annot, selection, opts, offsets=None, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

A VoxelSelection is an AnnotationObject which draws selected voxels from a Selection instance. A SelectionTexture is used to draw the selected voxels.

__init__(annot, selection, opts, offsets=None, *args, **kwargs)

Create a VoxelSelection annotation.

Parameters:
  • annot – The Annotations object that owns this VoxelSelection.
  • selection – A Selection instance which defines the voxels to be highlighted.
  • opts – A NiftiOpts instance which is used for its voxel-to-display transformation matrices.
  • offsets – If None (the default), the selection must have the same shape as the image data being annotated. Alternately, you may set offsets to a sequence of three values, which are used as offsets for the xyz voxel values. This is to allow for a sub-space of the full image space to be annotated.

All other arguments are passed through to the AnnotationObject.__init__() method.

destroy()

Must be called when this VoxelSelection is no longer needed. Destroys the SelectionTexture.

texture

Return the SelectionTexture used by this VoxelSelection.

draw2D(zpos, axes)

Draws this VoxelSelection.

__module__ = 'fsleyes.gl.annotations'
class fsleyes.gl.annotations.Text(annot, text, xpos, ypos, fontSize=10, xoff=None, yoff=None, halign=None, valign=None, bgColour=None, angle=None, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

A Text is an AnnotationObject which draws a string of text on the display.

__init__(annot, text, xpos, ypos, fontSize=10, xoff=None, yoff=None, halign=None, valign=None, bgColour=None, angle=None, *args, **kwargs)

Create a Text annotation.

Parameters:
  • annot – The Annotations object that owns this Text.
  • text – The text to draw.
  • xpos – Position along the horizontal axis as a proportion between 0 (left) and 1 (right).
  • xpos – Position along the vertial axis as a proportion between 0 (bottom) and 1 (top).
  • xoff – Fixed horizontal offset in pixels
  • yoff – Fixed vertical offset in pixels
  • fontSize – Font size.
  • halign – Horizontal alignemnt - 'left', 'centre', or right.
  • valign – Vertical alignemnt - 'bottom', 'centre', or top.
  • bcColour – If not None, a border will be drawn around the text.
  • angle – Angle, in degrees, by which to rotate the text. NOT IMPLEMENTED YET
text

Returns the current text value.

__module__ = 'fsleyes.gl.annotations'
fontSize

Returns the current font size.

draw2D(zpos, axes)

Draws this Text annotation.