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:
The |
|
The |
|
The |
|
A |
-
class
fsleyes.gl.annotations.
Annotations
(canvas, xax, yax)[source]¶ 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)[source]¶ 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.
-
property
canvas
¶ Returns a ref to the canvas that owns this
Annotations
instance.
-
setAxes
(xax, yax)[source]¶ This method must be called if the display orientation changes. See
__init__()
.
-
getDisplayBounds
()[source]¶ Returns a tuple containing the
(xmin, xmax, ymin, ymax)
display bounds of theSliceCanvas
that owns thisAnnotations
object.
-
selection
(*args, **kwargs)[source]¶ Queues a selection for drawing - see the
VoxelSelection
class.
-
obj
(obj, hold=False)[source]¶ 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)[source]¶ Removes the given
AnnotationObject
from the queue, but does not call itsGLObject.destroy()
method - this is the responsibility of the caller.
-
clear
()[source]¶ 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)[source]¶ 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>, '__annotations__': {}})¶
-
__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)[source]¶ 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)[source]¶ 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.
-
resetExpiry
()[source]¶ Resets the expiry for this
AnnotationObject
so that it is valid from the current time.
-
expired
(now)[source]¶ Returns
True
if thisAnnotation
has expired,False
otherwise.- Parameters
now – The current time
-
__module__
= 'fsleyes.gl.annotations'¶
-
-
class
fsleyes.gl.annotations.
Line
(annot, xy1, xy2, *args, **kwargs)[source]¶ Bases:
fsleyes.gl.annotations.AnnotationObject
The
Line
class is anAnnotationObject
which represents a 2D line.-
__init__
(annot, xy1, xy2, *args, **kwargs)[source]¶ 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__()
.
-
__module__
= 'fsleyes.gl.annotations'¶
-
-
class
fsleyes.gl.annotations.
Rect
(annot, xy, w, h, filled=False, fillColour=None, *args, **kwargs)[source]¶ 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)[source]¶ 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__()
.
-
__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.
VoxelGrid
(annot, selectMask, displayToVoxMat, voxToDisplayMat, offsets=None, *args, **kwargs)[source]¶ 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)[source]¶ 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.
-
__module__
= 'fsleyes.gl.annotations'¶
-
-
class
fsleyes.gl.annotations.
VoxelSelection
(annot, selection, opts, offsets=None, *args, **kwargs)[source]¶ Bases:
fsleyes.gl.annotations.AnnotationObject
A
VoxelSelection
is anAnnotationObject
which draws selected voxels from aselection.Selection
instance. ASelectionTexture
is used to draw the selected voxels.-
__init__
(annot, selection, opts, offsets=None, *args, **kwargs)[source]¶ Create a
VoxelSelection
annotation.- Parameters
annot – The
Annotations
object that owns thisVoxelSelection
.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), 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.
-
destroy
()[source]¶ Must be called when this
VoxelSelection
is no longer needed. Destroys theSelectionTexture
.
-
property
texture
¶ Return the
SelectionTexture
used by thisVoxelSelection
.
-
__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)[source]¶ 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)[source]¶ 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
-
property
text
¶ Returns the current text value.
-
__module__
= 'fsleyes.gl.annotations'¶
-
property
fontSize
¶ Returns the current font size.
-