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:
The |
|
The |
|
The |
|
The |
|
The |
|
A |
|
A |
- class fsleyes.gl.annotations.Annotations(canvas, xax, yax)[source]
Bases:
__main__.docbuilder.run.<locals>.MockClass
An
Annotations
object provides functionality to draw 2D annotations on aSliceCanvas
. Annotations may be enqueued via any of theline()
,rect()
,ellpse()
,point()
,selection()
orobj()
, methods, and de-queued via thedequeue()
method.Annotations can be enqueued in one of three ways, using the hold and fixed parameters:
Transient: When calling
line
,rect
, etc, passinghold=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, passinghold=True
and`fixed=True
enqueues the annotation for all subsequent calls todraw()
. 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, passinghold=True
andfixed=False
adds the annotation to the accessibleannotations
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 theOrthoAnnotateProfile
.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 forhold
isFalse
, andfixed
isTrue
,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.- annotations = <MagicMock name='mock.List()' id='4117847248'>
Contains all persistent
AnnotationObject
instances, which have been added to the queue withhold=True
andfixed=False
.
- __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, fixed=True)[source]
Queues the given
AnnotationObject
for drawing.- Parameters
hold – If
True
, the givenAnnotationObject
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), andhold=True
, the givenAnnotationObject
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 whenhold=False
.
- dequeue(obj, hold=False, fixed=True)[source]
Removes the given
AnnotationObject
from the appropriate queue, but does not call itsGLObject.destroy()
method - this is the responsibility of the caller.
- clear()[source]
Clears all queues, and calls the
GLObject.destroy()
method on every object in the queue.
- draw(zpos, xform=None)[source]
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.
- __annotations__ = {}
- __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)[source]
Bases:
fsleyes.gl.globject.GLSimpleObject
,__main__.docbuilder.run.<locals>.MockClass
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
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 theexpiry
orcreation
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)[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.
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='4118213728'>
Annotation colour.
- alpha = <MagicMock name='mock.Percentage()' id='4117953264'>
Opacity.
- enabled = <MagicMock name='mock.Boolean()' id='4118803744'>
Whether to draw this annotation or not.
- lineWidth = <MagicMock name='mock.Int()' id='4117859440'>
Line width, for annotations which are drawn with lines.
- honourZLimits = <MagicMock name='mock.Boolean()' id='4118803744'>
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='4117617224'>
Minimum z value below which this annotation will not be drawn.
- zmax = <MagicMock name='mock.Real()' id='4117617224'>
Maximum z value below which this annotation will not be drawn.
- resetExpiry()[source]
Resets the expiry for this
AnnotationObject
so that it is valid from the current time.
- hit(x, y)[source]
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 theOrthoAnnotateProfile
.- Parameters
x – X coordinate (in display coordinates).
y – Y coordinate (in display coordinates).
- move(x, y)[source]
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 theOrthoAnnotateProfile
.- Parameters
x – X coordinate (in display coordinates).
y – Y coordinate (in display coordinates).
- expired(now)[source]
Returns
True
if thisAnnotation
has expired,False
otherwise.- Parameters
now – The current time
- __annotations__ = {}
- __module__ = 'fsleyes.gl.annotations'
- class fsleyes.gl.annotations.Point(annot, x, y, *args, **kwargs)[source]
Bases:
fsleyes.gl.annotations.AnnotationObject
The
Point
class is anAnnotationObject
which represents a point, drawn as a small crosshair. The size of the point is proportional to theAnnotationObject.lineWidth
.- __init__(annot, x, y, *args, **kwargs)[source]
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 thisPoint
.x – X coordinates of the point
y – Y coordinates of the point
All other arguments are passed through to
AnnotationObject.__init__()
.
- __annotations__ = {}
- __module__ = 'fsleyes.gl.annotations'
- class fsleyes.gl.annotations.Line(annot, x1, y1, x2, y2, *args, **kwargs)[source]
Bases:
fsleyes.gl.annotations.AnnotationObject
The
Line
class is anAnnotationObject
which represents a 2D line.- __init__(annot, x1, y1, x2, y2, *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
.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__()
.
- __annotations__ = {}
- __module__ = 'fsleyes.gl.annotations'
- class fsleyes.gl.annotations.Arrow(annot, x1, y1, x2, y2, *args, **kwargs)[source]
Bases:
fsleyes.gl.annotations.Line
The
Arrow
class is anAnnotationObject
which represents a 2D line with an arrow head at one end. The size of the is proportional to the currentAnnotationObject.lineWidth
.- __annotations__ = {}
- __module__ = 'fsleyes.gl.annotations'
- class fsleyes.gl.annotations.Rect(annot, x, y, w, h, filled=True, border=True, *args, **kwargs)[source]
Bases:
fsleyes.gl.annotations.AnnotationObject
The
Rect
class is anAnnotationObject
which represents a 2D rectangle.- __init__(annot, x, y, w, h, filled=True, border=True, *args, **kwargs)[source]
Create a
Rect
annotation.- Parameters
annot – The
Annotations
object that owns thisRect
.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 filledborder – If
True
, a border is drawn around the rectangle.
All other arguments are passed through to
AnnotationObject.__init__()
.Note that if
filled=False
andborder=False
, nothing will be drawn. The.AnnotationObject.alpha
value is ignored when drawing the border.
- filled = <MagicMock name='mock.Boolean()' id='4118803744'>
Whether to fill the rectangle.
- border = <MagicMock name='mock.Boolean()' id='4118803744'>
Whether to draw a border around the rectangle.
- __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.
- __annotations__ = {}
- __module__ = 'fsleyes.gl.annotations'
- class fsleyes.gl.annotations.Ellipse(annot, x, y, w, h, npoints=60, filled=True, border=True, *args, **kwargs)[source]
Bases:
fsleyes.gl.annotations.AnnotationObject
The
Ellipse
class is anAnnotationObject
which represents a ellipse.- __init__(annot, x, y, w, h, npoints=60, filled=True, border=True, *args, **kwargs)[source]
Create an
Ellipse
annotation.- Parameters
annot – The
Annotations
object that owns thisEllipse
.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 filledborder – If
True
, a border is drawn around the ellipse
All other arguments are passed through to
AnnotationObject.__init__()
.
- filled = <MagicMock name='mock.Boolean()' id='4118803744'>
Whether to fill the ellipse.
- border = <MagicMock name='mock.Boolean()' id='4118803744'>
Whether to draw a border around the ellipse.
- __annotations__ = {}
- __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.
- __annotations__ = {}
- __module__ = 'fsleyes.gl.annotations'
- destroy()[source]
Must be called when this
VoxelSelection
is no longer needed. Destroys theSelectionTexture
.
- property texture
Return the
SelectionTexture
used by thisVoxelSelection
.
- 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)[source]
Bases:
fsleyes.gl.annotations.AnnotationObject
A
TextAnnotation
is anAnnotationObject
which draws afsleyes.gl.text.Text
object.The
Text
class allows the text position to be specified as either x/y proportions, or as absolute pixels. TheTextAnnotation
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 settingpos
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)[source]
Create a
TextAnnotation
.- Parameters
annot – The
Annotations
object that owns thisTextAnnotation
.
See the
Text
class for details on the other arguments.
- text = <MagicMock name='mock.String()' id='4118522224'>
Text to draw.
- fontSize = <MagicMock name='mock.Int()' id='4117859440'>
Text font size in points. The size of the text annotation is kept proportional to the canvas zoom level.
- property gltext