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 aSliceCanvas
. Annotations may be enqueued via any of theline()
,rect()
,grid()
,selection()
orobj()
, 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 viadequeue()
, or the entire annotations queue is cleared viaclear()
.Annotations can be queued by one of the helper methods on the
Annotations
object (e.g.line()
orrect()
), or by manually creating anAnnotationObject
and passing it to theobj()
method.-
__init__
(canvas, xax, yax)¶ Creates an
Annotations
object.Parameters: - canvas – The
SliceCanvas
that owns thisAnnotations
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 – The
-
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 theSliceCanvas
that owns thisAnnotations
object.
-
rect
(*args, **kwargs)¶ Queues a rectangle for drawing - see the
Rectangle
class.
-
selection
(*args, **kwargs)¶ Queues a selection for drawing - see the
VoxelSelection
class.
-
obj
(obj, hold=False)¶ Queues the given
AnnotationObject
for drawing.Parameters: hold – If True
, the givenAnnotationObject
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 itsGLObject.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 theGLObject.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 anAnnotations
instance. TheAnnotationObject
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 theexpiry
orcreation
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 thisAnnotationObject
. - 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.
- annot – The
-
resetExpiry
()¶ Resets the expiry for this
AnnotationObject
so that it is valid from the current time.
-
expired
(now)¶ Returns
True
if thisAnnotation
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 anAnnotationObject
which represents a 2D line.-
__init__
(annot, xy1, xy2, *args, **kwargs)¶ Create a
Line
annotation.The
xy1
andxy2
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 thisLine
. - 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__()
.- annot – The
-
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 anAnnotationObject
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 thisRect
. - 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 thefillColour
. - fillColour – If
filled=True
, the colour to fill the rectangle with. Defaults to a transparent version of thecolour
.
All other arguments are passed through to
AnnotationObject.__init__()
.- annot – The
-
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 anAnnotationObject
which represents a collection of selected voxels. See also theVoxelSelection
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 thisVoxelGrid
. - 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 areTrue
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), theselectMask
must have the same shape as the image data being annotated. Alternately, you may setoffsets
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.
- annot – The
-
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 anAnnotationObject
which draws selected voxels from aSelection
instance. ASelectionTexture
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 thisVoxelSelection
. - 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), theselection
must have the same shape as the image data being annotated. Alternately, you may setoffsets
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.- annot – The
-
destroy
()¶ Must be called when this
VoxelSelection
is no longer needed. Destroys theSelectionTexture
.
-
texture
¶ Return the
SelectionTexture
used by thisVoxelSelection
.
-
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 anAnnotationObject
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 thisText
. - 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'
, orright
. - valign – Vertical alignemnt -
'bottom'
,'centre'
, ortop
. - 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
- annot – The
-
text
¶ Returns the current text value.
-
__module__
= 'fsleyes.gl.annotations'¶
-
fontSize
¶ Returns the current font size.
-
draw2D
(zpos, axes)¶ Draws this
Text
annotation.
-