fsleyes.gl.annotations

This module provides the Annotations class, which implements functionality to draw annotations (lines, text, etc)

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

Not all annotation types currently support being drawn on a 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(*args, **kwargs)

Bases: HasProperties

An Annotations object provides functionality to draw annotations on an OpenGL canvas. 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 draw2D() or draw3D() 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

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

__init__(canvas)

Creates an Annotations object.

Parameters:

canvas – The SliceCanvas that owns this Annotations object.

property canvas

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

destroy()

Must be called when this Annotations object is no longer needed.

property defaultShader

Returns a shader program used by most AnnotationObject types.

__create(atype, *args, **kwargs)

Used by the annotation creation methods below. Creates and enqueues an annotation of type atype.

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

draw2D(zpos, axes)

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.

• axes – Display coordinate system axis mapping to the screen coordinate system.

draw3D(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:

xform

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.AnnotationObject(*args, **kwargs)

Bases: GLSimpleObject, HasProperties

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)
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.vertices2D() method.

__init__(annot, colour=None, alpha=None, lineWidth=None, enabled=None, expiry=None, honourZLimits=None, zmin=None, zmax=None, occlusion=None, applyMvp=None, **kwargs)

Create an AnnotationObject.

Parameters:

• annot – The Annotations object that created this AnnotationObject.

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

• occlusion – Whether to draw with depth testing.

• applyMvp – Whether to apply the canvas MVP matrix.

Any other arguments are ignored.

colour

Annotation colour.

alpha

Opacity.

lineWidth

Line width in pixels (approx), for annotations which are drawn with lines. See also the normalisedLineWidth() method.

enabled

Whether to draw this annotation or not.

honourZLimits

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

Only relevant when being drawn via draw2D().

zmin

Minimum z value below which this annotation will not be drawn. Only relevant when being drawn via draw2D().

zmax

Maximum z value below which this annotation will not be drawn. Only relevant when being drawn via draw2D().

occlusion

Only relevant when drawing via draw3D(). If True, depth testing is enabled.

applyMvp

If True (the default), it is assumed that the annotation coordinates are specified in the display coordinate system, and therefore that they should be transformed by the SliceCanvas.mvpMatrix() (or Scene3DCanvas.mvpMatrix()). If False, it is assumed that the annotation coordinates are in normalised device coordinates. Not honoured by all annotation types.

destroy()

Must be called when this AnnotationObject is no longer needed. The default implementation does nothing, but may be overridden by sub-classes.

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.

Only relevant for annotations drawn on a SliceCanvas() of an OrthoPanel.

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.

Only relevant for annotations drawn on a SliceCanvas() of an OrthoPanel.

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

property normalisedLineWidth

Returns the lineWidth, converted into units proportional to either display coordinates (if applyMvp is True), or normalised device coordinates (if applyMvp is False).

vertices2D(zpos, axes)

Must be implemented by sub-classes which rely on the default draw2D() implementation. Generates and returns verticws to display this annotation. The exact return type may differ depending on the annotation type.

vertices3D()

Must be implemented by sub-classes which rely on the default draw3D() implementation. Generates and returns verticws to display this annotation. The exact return type may differ depending on the annotation type.

__draw(canvas, vertices, xform=None)

Used by the default draw2D() and draw3D() implementations.

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

Draw this annotation on a 2D plane. This method implements a default routine used by most annotation types - the annotation is drawn using vertices returned by the overridden vertices2D() method.

This method may be overridden by sub-classes which require a different routine.

draw3D(canvas, xform=None)

Draw this annotation in 3D. This method implements a default routine used by most annotation types - the annotation is drawn using vertices returned by the overridden vertices3D() method.

This method may be overridden by sub-classes which require a different routine.

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Point(*args, **kwargs)

Bases: 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, z=None, **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

• z – Z coordinates, if this Point is being drawn via draw3D().

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

vertices2D(zpos, axes)

Returns vertices to draw this Point annotation.

vertices3D()

Returns vertices to draw 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.

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Line(*args, **kwargs)

Bases: AnnotationObject

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

__init__(annot, x1, y1, x2, y2, z1=None, z2=None, **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__().

vertices2D(zpos, axes)

Returns a set of vertices for drawing this line on a 2D plane, with the GL_TRIANGLES primitive.

vertices3D()

Returns a set of vertices for drawing this line in a 3D space, with the GL_TRIANGLES primitive.

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

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Arrow(*args, **kwargs)

Bases: 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.

vertices2D(zpos, axes)

Draw the arrow.

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.BorderMixin

Bases: object

Mixin for AnnotationObject classes which display a shape which can be filled or unfilled, and can have a border or no border.

filled

Whether to fill the rectangle.

border

Whether to draw a border around the rectangle.

draw2D(canvas, zpos, axes)

__dict__ = mappingproxy({'__module__': 'fsleyes.gl.annotations', '__doc__': 'Mixin for ``AnnotationObject`` classes which display a shape which\n    can be filled or unfilled, and can have a border or no border.\n    ', 'filled': <fsleyes_props.properties_types.Boolean object>, 'border': <fsleyes_props.properties_types.Boolean object>, 'draw2D': <function BorderMixin.draw2D>, '__dict__': <attribute '__dict__' of 'BorderMixin' objects>, '__weakref__': <attribute '__weakref__' of 'BorderMixin' objects>, '__annotations__': {}})

__module__ = 'fsleyes.gl.annotations'

__weakref__

list of weak references to the object

class fsleyes.gl.annotations.Rect(*args, **kwargs)

Bases: BorderMixin, AnnotationObject

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

__init__(annot, x, y, w, h, filled=True, border=True, **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.

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

vertices2D(zpos, axes)

Generates vertices to draw this Rectangle annotation.

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

Generate the rectangle fill.

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

Generate the rectangle outline.

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.Ellipse(*args, **kwargs)

Bases: BorderMixin, AnnotationObject

The Ellipse class is an AnnotationObject which represents a ellipse.

__init__(annot, x, y, w, h, npoints=60, filled=True, border=True, **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__().

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

vertices2D(zpos, axes)

Generate vertices for this Ellipse annotation.

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

class fsleyes.gl.annotations.VoxelSelection(*args, **kwargs)

Bases: 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, overlay, offsets=None, **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.

• overlay – A Nifti 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.

__createShader()

Called by __init__(). Creates a shader program.

destroy()

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

__annotations__ = {}

__module__ = 'fsleyes.gl.annotations'

property texture

Return the SelectionTexture used by this VoxelSelection.

vertices2D(zpos, axes)

Returns vertices and texture coordinates to draw this VoxelSelection.

draw2D(canvas, zpos, axes)

Draw a VoxelSelection annotation.

class fsleyes.gl.annotations.TextAnnotation(*args, **kwargs)

Bases: 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.

__annotations__ = {}

__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

Text to draw.

fontSize

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(canvas, 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.