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.

Note

The Annotations class only works with the SliceCanvas and LightBoxCanvas - there is no support for the Scene3DCanvas.

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

Point	The Point class is an AnnotationObject which represents a point, drawn as a small crosshair.
Line	The Line class is an AnnotationObject which represents a 2D line.
Arrow	The Arrow class is an AnnotationObject which represents a 2D line with an arrow head at one end.
Rect	The Rect class is an AnnotationObject which represents a 2D rectangle.
Ellipse	The Ellipse class is an AnnotationObject which represents a ellipse.
VoxelSelection	A VoxelSelection is an AnnotationObject which draws selected voxels from a selection.Selection instance.
TextAnnotation	A TextAnnotation is an AnnotationObject which draws a fsleyes.gl.text.Text object.

class fsleyes.gl.annotations.Annotations(canvas, xax, yax)

Bases: __main__.docbuilder.run.<locals>.MockClass

An Annotations object provides functionality to draw 2D annotations on a SliceCanvas. Annotations may be enqueued via any of the line(), rect(), ellpse(), point(), selection() or obj(), methods, and de-queued via the dequeue() method.

Annotations can be enqueued in one of three ways, using the hold and fixed parameters:

• Transient: When calling line, rect, etc, passing hold=False` enqueues the annotation for the next call to :meth:`draw`. After the annotation is drawn, it is removed from the queue, and would need to be re-queued to draw it again. The ``fixed parameter has no effect for transient annotations.

• Fixed: When calling line, rect, etc, passing hold=True and `fixed=True enqueues the annotation for all subsequent calls to draw(). Fixed annotations are stored in an internal, inaccessible queue, so if you need to manipulate a fixed annotation, you need to maintain your own reference to it.

• **Persistent`**: When calling ``line`, rect, etc, passing hold=True and fixed=False adds the annotation to the accessible annotations list.

Transient annotations are intended for one-off annotations, e.g. a cursor mark at the current mouse location.

Fixed annotations are intended for persistent annotations which are intended to be immutable, i.e. that cannot be directly manipulated by the user, e.g. anatomical orientation labels on the canvases of an OrthoPanel.

Persistent annotations are intended for persistent annotations which are intended to be manipulated by the user - these annotations are used by the AnnotationPanel in conjunction with the OrthoAnnotateProfile.

After annotations have been enqueued in one of the above manners, a call to draw() will draw each annotation on the canvas, and clear the transient queue. The default value for hold is False, and fixed is True,

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.

annotations = <MagicMock name='mock.List()' id='4116324920'>

Contains all persistent AnnotationObject instances, which have been added to the queue with hold=True and fixed=False.

__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.

property 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.

arrow(*args, **kwargs)

Queues an arrow for drawing - see the Arrow class.

point(*args, **kwargs)

Queues a point for drawing - see the Point class.

rect(*args, **kwargs)

Queues a rectangle for drawing - see the Rectangle class.

ellipse(*args, **kwargs)

Queues a circle for drawing - see the Ellipse 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, fixed=True)

Queues the given AnnotationObject for drawing.

Parameters

• hold – If True, the given AnnotationObject will be added to the fixed or persistent queues, and will remain there until it is explicitly removed. Otherwise (the default), the object will be added to the transient queue, and removed from the queue after it has been drawn.

• fixed – If True (the default), and hold=True, the given AnnotationObject will be added to the fixed queue, and will remain there until it is explicitly removed. Otherwise, the object will be added to the persistent queue and, again, will remain there until it is explicitly removed. Has no effect when hold=False.

dequeue(obj, hold=False, fixed=True)

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

clear()

Clears all queues, and calls the GLObject.destroy() method on every object in the queue.

draw(zpos, xform=None)

Draws all enqueued annotations. Fixed annotations are drawn first, then persistent, then transient - i.e. transient annotations will be drawn on top of persistent, which will be drawn on to of fixed.

Parameters

• zpos – Position along the Z axis, above which all annotations should be drawn.

• xform – Transformation matrix which should be applied to all objects.

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.AnnotationObject(annot, xform=None, colour=None, alpha=None, lineWidth=None, enabled=True, expiry=None, honourZLimits=False, zmin=None, zmax=None, **kwargs)

Bases: fsleyes.gl.globject.GLSimpleObject, __main__.docbuilder.run.<locals>.MockClass

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
alpha	Transparency
enabled	Whether the annotation should be drawn or not.
lineWidth	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, alpha=None, lineWidth=None, enabled=True, expiry=None, honourZLimits=False, zmin=None, zmax=None, **kwargs)

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.

• alpha – Opacity.

• lineWidth – 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.

• honourZLimits – Whether to enforce zmin/zmax.

• zmin – Minimum z value below which this annotation should not be drawn.

• zmax – Maximum z value above which this annotation should not be drawn.

Any other arguments are ignored.

colour = <MagicMock name='mock.Colour()' id='4116519520'>

Annotation colour.

alpha = <MagicMock name='mock.Percentage()' id='4116877904'>

Opacity.

enabled = <MagicMock name='mock.Boolean()' id='4117273880'>

Whether to draw this annotation or not.

lineWidth = <MagicMock name='mock.Int()' id='4116300320'>

Line width, for annotations which are drawn with lines.

honourZLimits = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, the zmin/zmax properties are enforced. Otherwise (the default) they are ignored, and the annotation is always drawn.

zmin = <MagicMock name='mock.Real()' id='4116054224'>

Minimum z value below which this annotation will not be drawn.

zmax = <MagicMock name='mock.Real()' id='4116054224'>

Maximum z value below which this annotation will not be drawn.

resetExpiry()

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

hit(x, y)

Return True if the given X/Y point is within the bounds of this annotation, False otherwise. Must be implemented by sub-classes, but only those annotations which are drawn by the OrthoAnnotateProfile.

Parameters

• x – X coordinate (in display coordinates).

• y – Y coordinate (in display coordinates).

move(x, y)

Move this annotation acording to (x, y), which is specified as an offset relative to the current location. Must be implemented by sub-classes, but only those annotations which are drawn by the OrthoAnnotateProfile.

Parameters

• x – X coordinate (in display coordinates).

• y – Y coordinate (in display coordinates).

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.Point(annot, x, y, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

The Point class is an AnnotationObject which represents a point, drawn as a small crosshair. The size of the point is proportional to the AnnotationObject.lineWidth.

__init__(annot, x, y, *args, **kwargs)

Create a Point annotation.

The xy coordinate tuple 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 Point.

• x – X coordinates of the point

• y – Y coordinates of the point

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

draw2D(zpos, axes)

Draws this Point annotation.

hit(x, y)

Returns True if (x, y) is within the bounds of this Point, False otherwise.

move(x, y)

Move this Point according to x and y.

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Line(annot, x1, y1, x2, y2, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

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

__init__(annot, x1, y1, x2, y2, *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.

• x1 – X coordinate of one endpoint.

• y1 – Y coordinate of one endpoint.

• x2 – X coordinate of the other endpoint.

• y2 – Y coordinate of the second endpoint.

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

draw2D(zpos, axes)

Draws this Line annotation.

hit(x, y)

Returns True if (x, y) is within the bounds of this Line, False otherwise.

http://paulbourke.net/geometry/pointlineplane/

move(x, y)

Move this Line according to (x, y).

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Arrow(annot, x1, y1, x2, y2, *args, **kwargs)

Bases: fsleyes.gl.annotations.Line

The Arrow class is an AnnotationObject which represents a 2D line with an arrow head at one end. The size of the is proportional to the current AnnotationObject.lineWidth.

draw2D(zpos, axes)

Draw the arrow.

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Rect(annot, x, y, w, h, filled=True, border=True, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

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

__init__(annot, x, y, w, h, filled=True, border=True, *args, **kwargs)

Create a Rect annotation.

Parameters

• annot – The Annotations object that owns this Rect.

• x – X coordinate of one corner of the rectangle, in the display coordinate system.

• y – Y coordinate of one corner of the rectangle, in the display coordinate system.

• w – Rectangle width (actually an offset relative to x)

• h – Rectangle height (actually an offset relative to y)

• filled – If True, the rectangle is filled

• border – If True, a border is drawn around the rectangle.

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

Note that if filled=False and border=False, nothing will be drawn. The .AnnotationObject.alpha value is ignored when drawing the border.

filled = <MagicMock name='mock.Boolean()' id='4117273880'>

Whether to fill the rectangle.

border = <MagicMock name='mock.Boolean()' id='4117273880'>

Whether to draw a border around the rectangle.

hit(x, y)

Returns True if (x, y) is within the bounds of this Rect, False otherwise.

move(x, y)

Move this Rect according to (x, y).

draw2D(zpos, axes)

Draws this Rectangle annotation.

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

Draw a filled version of the rectangle.

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

Draw the rectangle outline.

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Ellipse(annot, x, y, w, h, npoints=60, filled=True, border=True, *args, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

The Ellipse class is an AnnotationObject which represents a ellipse.

__init__(annot, x, y, w, h, npoints=60, filled=True, border=True, *args, **kwargs)

Create an Ellipse annotation.

Parameters

• annot – The Annotations object that owns this Ellipse.

• x – X coordinate of ellipse centre, in the display coordinate system.

• y – Y coordinate of ellipse centre, in the display coordinate system.

• w – Horizontal radius.

• h – Vertical radius.

• npoints – Number of vertices used to draw the ellipse outline.

• filled – If True, the ellipse is filled

• border – If True, a border is drawn around the ellipse

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

filled = <MagicMock name='mock.Boolean()' id='4117273880'>

Whether to fill the ellipse.

border = <MagicMock name='mock.Boolean()' id='4117273880'>

Whether to draw a border around the ellipse.

hit(x, y)

Returns True if (x, y) is within the bounds of this Ellipse, False otherwise.

move(x, y)

Move this Rect according to (x, y).

draw2D(zpos, axes)

Draws this Ellipse 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.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.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.

__module__ = 'fsleyes.gl.annotations'

destroy()

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

property texture

Return the SelectionTexture used by this VoxelSelection.

draw2D(zpos, axes)

Draws this VoxelSelection.

class fsleyes.gl.annotations.TextAnnotation(annot, text=None, x=None, y=None, off=None, coordinates='proportions', fontSize=10, halign=None, valign=None, colour=None, **kwargs)

Bases: fsleyes.gl.annotations.AnnotationObject

A TextAnnotation is an AnnotationObject which draws a fsleyes.gl.text.Text object.

The Text class allows the text position to be specified as either x/y proportions, or as absolute pixels. The TextAnnotation class adds an additional option to specify the location in terms of a 3D position in the display coordinate system.

This can be achieved by setting coordinates to 'display', and setting pos to the 3D position in the display coordinate system.

__module__ = 'fsleyes.gl.annotations'

__init__(annot, text=None, x=None, y=None, off=None, coordinates='proportions', fontSize=10, halign=None, valign=None, colour=None, **kwargs)

Create a TextAnnotation.

Parameters

annot – The Annotations object that owns this TextAnnotation.

See the Text class for details on the other arguments.

text = <MagicMock name='mock.String()' id='4116890720'>

Text to draw.

fontSize = <MagicMock name='mock.Int()' id='4116300320'>

Text font size in points. The size of the text annotation is kept proportional to the canvas zoom level.

property gltext

destroy()

Must be called when this TextAnnotation is no longer needed.

draw2D(zpos, axes)

Draw this TextAnnotation.

hit(x, y)

Returns True if (x, y) is within the bounds of this TextAnnotation, False otherwise. Only supported for text drawn relative to the display coordinate system (coordinates='display') - raises a NotImplementedError otherwise.

move(x, y)

Move this TextAnnotation according to (x, y).

Only supported for text drawn relative to the display coordinate system (coordinates='display') - raises a NotImplementedError otherwise.