fsleyes.displaycontext.displaycontext
¶
This module provides the DisplayContext
class, which defines
general display settings for displaying the overlays in a
OverlayList
.
-
exception
fsleyes.displaycontext.displaycontext.
InvalidOverlayError
[source]¶ Bases:
Exception
An error raised by the
DisplayContext.getDisplay()
andDisplayContext.getOpts()
methods to indicate that the specified overlay is not in theOverlayList
.-
__module__
= 'fsleyes.displaycontext.displaycontext'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
fsleyes.displaycontext.displaycontext.
DisplayContext
(overlayList, parent=None, defaultDs='ref', **kwargs)[source]¶ Bases:
__main__.MockClass
A
DisplayContext
instance contains a number of properties defining how the overlays in anOverlayList
are to be displayed, and related contextual information.A
DisplayContext
instance is responsible for creating and destroyingDisplay
instances for every overlay in theOverlayList
. TheseDisplay
instances, and the correspondingDisplayOpts
instances (which, in turn, are created/destroyed byDisplay
instances) can be accessed with thegetDisplay()
andgetOpts()
method respectively.A number of other useful methods are provided by a
DisplayContext
instance:Returns the
Display
instance for the specified overlay (or overlay index).Returns the
DisplayOpts
instance associated with the specified overlay.Convenience method which returns the reference image associated with the given overlay, or
None
if there is no reference image.Transforms the given coordinates from the display coordinate system into the world coordinate system.
Transforms the given coordinates from the world coordinate system into the display coordinate system.
Returns
True
if the currentdisplaySpace
aligns with a radiological orientation.Selects the specified
overlay
.Returns the currently selected overlay object, or
None
if there are no overlays.Returns the order in which the given overlay (or an index into the
OverlayList
list) should be displayed (see theoverlayOrder
property).Returns a list of overlay objects from the
OverlayList
list, sorted into the order that they should be displayed, as defined by theoverlayOrder
property.This method can be used as a context manager to suppress notification for all
Display
andDisplayOpts
properties related to the givenoverlay
.Suppresses notification for all
Display
andDisplayOpts
properties associated with the givenoverlay
.Enables notification for all
Display
andDisplayOpts
properties associated with the givenoverlay
.This property controls how the
displaySpace
is initialised when overlays are added to a previously emptyOverlayList
.Detaches the
displaySpace
andbounds
properties, and all relatedDisplayOpts
properties, from the parentDisplayContext
.-
selectedOverlay
= <MagicMock name='mock.Int()' id='140225916854528'>¶ Index of the currently ‘selected’ overlay.
Note
The value of this index is in relation to the
OverlayList
, rather than to theoverlayOrder
list.If you’re interested in the currently selected overlay, you must also listen for changes to the
OverlayList.images
list as, if the list changes, theselectedOverlay
index may not change, but the overlay to which it points may be different.
-
location
= <MagicMock name='mock.Point()' id='140225911661088'>¶ The location property contains the currently selected 3D location (xyz) in the display coordinate system. Different
DisplayContext
instances may be using different display coordinate systems - see thedisplaySpace
property.
-
worldLocation
= <MagicMock name='mock.Point()' id='140225911661088'>¶ The
location
property contains the currently selected 3D location (xyz) in the current display coordinate system. Whenever thelocation
changes, it gets transformed into the world coordinate system, and propagated to this property. The location of differentDisplayContext
instances is synchronised through this property.Note
If any
NiftiOpts.transform
properties have been modified independently of thedisplaySpace
, this value will be invalid.
-
bounds
= <MagicMock name='mock.Bounds()' id='140225916891392'>¶ This property contains the min/max values of a bounding box (in display coordinates) which is big enough to contain all of the overlays in the
OverlayList
.Warning
This property shouid be treated as read-only.
-
overlayOrder
= <MagicMock name='mock.List()' id='140225916767824'>¶ A list of indices into the
OverlayList.overlays
list, defining the order in which the overlays are to be displayed.See the
getOrderedOverlays()
method.
-
overlayGroups
= <MagicMock name='mock.List()' id='140225916767824'>¶ A list of
OverlayGroup
instances, each of which defines a group of overlays which share display properties.By default there is one overlay group, to which all new overlays are initially added. The
OverlayListPanel
allows the user to add/remove overlays from this default group.
-
syncOverlayDisplay
= <MagicMock name='mock.Boolean()' id='140225918039088'>¶ If this
DisplayContext
instance has a parent (seeprops.syncable
), and this property isTrue
, the properties of theDisplay
andDisplayOpts
instances for every overlay managed by thisDisplayContext
instance will be synchronised to those of the parent instance. Otherwise, the display properties for every overlay will be unsynchronised from the parent.Properties which control the current volume/timepoint in a 4D data set are not managed by this property - see the :attr:
syncOverlayVolume
property.Synchronisation of the following properties between child and parent
DisplayContext
instances is also controlled by this flag:Note
This property is accessed by the
Display
class, in its constructor, and when it creates newDisplayOpts
instances, to set initial sync states.
-
syncOverlayVolume
= <MagicMock name='mock.Boolean()' id='140225918039088'>¶ This property performs the same task as the
syncOverlayDisplay
property, but it only affectsDisplayOpts
properties which control the current volume/timepoint in a 4D overlay.
-
displaySpace
= <MagicMock name='mock.Choice()' id='140225920543424'>¶ The space in which overlays are displayed. This property defines the display coordinate system for this
DisplayContext
. When it is changed, theNiftiOpts.transform
property of allNifti
overlays in theOverlayList
is updated. It has two settings, described below. The options for this property are dynamically added by__updateDisplaySpaceOptions()
.World space (a.k.a.
'world'
)All
Nifti
overlays are displayed in the space defined by their affine transformation matrix - theNiftiOpts.transform
property for everyNifti
overlay is set toaffine
.Reference image space
A single
Nifti
overlay is selected as a reference image, and is displayed in scaled voxel space (with a potential L/R flip for neurological images - itsNiftiOpts.transform
is set topixdim-flip
). All otherNifti
overlays are transformed into this reference space - theirNiftiOpts.transform
property is set toreference
, which results in them being transformed into the scaled voxel space of the reference image.
Note
The
NiftiOpts.transform
property of anyNifti
overlay can be set independently of this property. However, whenever this property changes, it will change thetransform
property for everyNifti
, in the manner described above.The
defaultDisplaySpace()
can be used to control how thedisplaySpace
is initialised.
-
radioOrientation
= <MagicMock name='mock.Boolean()' id='140225918039088'>¶ If
True
, 2D views will show images in radiological convention (i.e.subject left on the right of the display). Otherwise, they will be shown in neurological convention (subject left on the left).Note
This setting is not enforced by the
DisplayContext
. It is the responsibility of theOrthoPanel
andLightBoxPanel
(and other potential future 2D view panels) to implement the flip.
-
autoDisplay
= <MagicMock name='mock.Boolean()' id='140225918039088'>¶ If
True
, whenever an overlay is added to theOverlayList
, theautodisplay
module will be used to automatically configure its display settings. Note that theDisplayContext
does not perform this configuration - this flag is used by other modules (e.g. theOverlayListPanel
and theOpenFileAction
).
-
loadInMemory
= <MagicMock name='mock.Boolean()' id='140225918039088'>¶ If
True
, allImage
instances will be loaded into memory, regardless of their size. Otherwise (the default), large compressedImage
overlays may be kept on disk.Note
Changing the value of this property will not affect existing
Image
overlays.Note
This property may end up being used in a more general sense by any code which needs to decide whether to do things in a more or less memory-intensive manner.
-
__init__
(overlayList, parent=None, defaultDs='ref', **kwargs)[source]¶ Create a
DisplayContext
.- Parameters
overlayList – An
OverlayList
instance.parent – Another
DisplayContext
instance to be used as the parent of this instance, passed to theSyncableHasProperties
constructor.defaultDs – Initial value for the
defaultDisplaySpace()
. Either'ref'
or'world'
. If'ref'
(the default), when overlays are added to an empty list, thedisplaySpace
will be set to the firstNifti
overlay. Otherwise ('world'
), the display space will be set to'world'
.
All other arguments are passed through to the
SyncableHasProperties
constructor, in addition to the following:The
syncOverlayDisplay
,,syncOverlayVolume
,location
, andbounds
properties are added to thenobind
argumentThe
overlayGroups
,autoDisplay
andloadInMemory
properties are added to thenounbind
argument.
-
destroy
()[source]¶ This method must be called when this
DisplayContext
is no longer needed.When a
DisplayContext
is destroyed, all of theDisplay
instances managed by it are destroyed as well.
-
property
destroyed
¶ Returns
True
if thisDisplayContext
has been, or is being, destroyed,False
otherwise.
-
getDisplay
(overlay, **kwargs)[source]¶ Returns the
Display
instance for the specified overlay (or overlay index).If the overlay is not in the
OverlayList
, anInvalidOverlayError
is raised. Otheriwse, if aDisplay
object does not exist for the given overlay, one is created.If this
DisplayContext
has been destroyed, aValueError
is raised.- Parameters
overlay – The overlay to retrieve a
Display
instance for, or an index into theOverlayList
.
All other keyword arguments are assumed to be
name=value
pairs, containing initial property values.
-
getOpts
(overlay)[source]¶ Returns the
DisplayOpts
instance associated with the specified overlay. SeegetDisplay()
andDisplay.opts()
for more details.
-
getReferenceImage
(overlay)[source]¶ Convenience method which returns the reference image associated with the given overlay, or
None
if there is no reference image.See the
DisplayOpts.referenceImage
method.
-
displayToWorld
(dloc, *args, **kwargs)[source]¶ Transforms the given coordinates from the display coordinate system into the world coordinate system.
Warning
If any
NiftiOpts.transform
properties have been modified manually, this method will return invalid results.All other arguments are passed to the
NiftiOpts.transformCoords()
method.
-
worldToDisplay
(wloc, *args, **kwargs)[source]¶ Transforms the given coordinates from the world coordinate system into the display coordinate system.
Warning
If any
NiftiOpts.transform
properties have been modified manually, this method will return invalid results.All other arguments are passed to the
NiftiOpts.transformCoords()
method.
-
displaySpaceIsRadiological
()[source]¶ Returns
True
if the currentdisplaySpace
aligns with a radiological orientation. A radiological orientation is one in which anatomical right is shown on the left of the screen, i.e.:The X axis corresponds to right -> left
The Y axis corresponds to posterior -> anterior
The Z axis corresponds to inferior -> superior
-
selectOverlay
(overlay)[source]¶ Selects the specified
overlay
. Raises anIndexError
if the overlay is not in the list.If you want to select an overlay by its index in the
OverlayList
, you can just assign to theselectedOverlay
property directly.
-
getSelectedOverlay
()[source]¶ Returns the currently selected overlay object, or
None
if there are no overlays.
-
getOverlayOrder
(overlay)[source]¶ Returns the order in which the given overlay (or an index into the
OverlayList
list) should be displayed (see theoverlayOrder
property).Raises an
IndexError
if the overlay is not in the list.
-
getOrderedOverlays
()[source]¶ Returns a list of overlay objects from the
OverlayList
list, sorted into the order that they should be displayed, as defined by theoverlayOrder
property.
-
freeze
(overlay)[source]¶ This method can be used as a context manager to suppress notification for all
Display
andDisplayOpts
properties related to the givenoverlay
:with displayCtx.freeze(overlay): # Do stuff which might trigger unwanted # Display/DisplayOpts notifications
See
freezeOverlay()
andthawOverlay()
.
-
freezeOverlay
(overlay)[source]¶ Suppresses notification for all
Display
andDisplayOpts
properties associated with the givenoverlay
. CallthawOverlay()
to re-enable notification.See also the
freeze()
method, which can be used as a context manager to automatically call this method andthawOverlay
.
-
thawOverlay
(overlay)[source]¶ Enables notification for all
Display
andDisplayOpts
properties associated with the givenoverlay
.
-
_DisplayContext__displaySpaceChanged
(*a)¶ Called when the
displaySpace
property changes. Updates theNiftiOpts.transform
property for allNifti
overlays in theOverlayList
.
-
_DisplayContext__locationChanged
(*a)¶ Called when the
location
property changes. Propagates the new location to theworldLocation
property.
-
_DisplayContext__overlayBoundsChanged
(value, valid, opts, name)¶ Called when the
DisplayOpts.bounds
property of any overlay changes. Updates thebounds
property and preserves the displaylocation
in terms of theworldLocation
.
-
_DisplayContext__overlayListChanged
(*a)¶ Called when the
OverlayList.overlays
property changes.Ensures that a
Display
andDisplayOpts
object exists for every image, updates thebounds
property, makes sure that theoverlayOrder
property is consistent, and updates constraints on theselectedOverlay
property.
-
_DisplayContext__propagateLocation
(dest)¶ Called by the
__locationChanged()
and__worldLocationChanged()
methods. Thedest
argument may be either'world'
(theworldLocation
is updated from thelocation
), or'display'
(vice-versa).
-
_DisplayContext__setTransform
(image)¶ Sets the
NiftiOpts.transform
property associated with the givenNifti
overlay to a sensible value, given the current value of thedisplaySpace
property.Called by the
__displaySpaceChanged()
method, and by__overlayListChanged()
for anyImage
overlays which have been newly added to theOverlayList
.- Parameters
image – An
Image
overlay.
-
_DisplayContext__syncOverlayDisplayChanged
(*a)¶ Called when the
syncOverlayDisplay
property changes.Synchronises or unsychronises the
Display
andDisplayOpts
instances for every overlay to/from their parent instances.
-
_DisplayContext__syncOverlayOrder
()¶ Ensures that the
overlayOrder
property is up to date with respect to theOverlayList
.
-
_DisplayContext__syncOverlayVolumeChanged
(*a)¶ Called when the
syncOverlayVolume
property changes.Synchronises or unsychronises the volume/timepoint properties of the
Display
andDisplayOpts
instances for every overlay.
-
_DisplayContext__updateBounds
(*a)¶ Called when the overlay list changes, or when any overlay display transform is changed. Updates the
bounds
property so that it is big enough to contain all of the overlays (as defined by theirDisplayOpts.bounds
properties).
-
_DisplayContext__updateDisplaySpaceOptions
()¶ Updates the
displaySpace
property so it is synchronised with the current contents of theOverlayList
This method is called by the
__overlayListChanged()
method.
-
_DisplayContext__worldLocationChanged
(*a)¶ Called when the
worldLocation
property changes. Propagates the new location to thelocation
property.
-
__module__
= 'fsleyes.displaycontext.displaycontext'¶
-
property
defaultDisplaySpace
¶ This property controls how the
displaySpace
is initialised when overlays are added to a previously emptyOverlayList
. If thedefaultDisplaySpace
is set to'ref'
, thedisplaySpace
will be initialised to the firstNifti
overlay. Otherwise (thedefaultDisplaySpace
is set to'world'
), thedisplaySpace
will be set to'world'
.
-
detachDisplaySpace
()[source]¶ Detaches the
displaySpace
andbounds
properties, and all relatedDisplayOpts
properties, from the parentDisplayContext
.This allows this
DisplayContext
to use a display coordinate system that is completely independent from other instances, and is not affected by changes to the parent properties.This is an irreversible operation.
-