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

Bases: Exception

An error raised by the DisplayContext.getDisplay() and DisplayContext.getOpts() methods to indicate that the specified overlay is not in the OverlayList.

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

Bases: __main__.docbuilder.run.<locals>.MockClass

A DisplayContext instance contains a number of properties defining how the overlays in an OverlayList are to be displayed, and related contextual information.

A DisplayContext instance is responsible for creating and destroying Display instances for every overlay in the OverlayList. These Display instances, and the corresponding DisplayOpts instances (which, in turn, are created/destroyed by Display instances) can be accessed with the getDisplay() and getOpts() method respectively.

A number of other useful methods are provided by a DisplayContext instance:

getDisplay	Returns the Display instance for the specified overlay (or overlay index).
getOpts	Returns the DisplayOpts instance associated with the specified overlay.
getReferenceImage	Convenience method which returns the reference image associated with the given overlay, or None if there is no reference image.
displaySpaceIsRadiological	Returns True if the current displaySpace aligns with a radiological orientation.
selectOverlay	Selects the specified overlay.
getSelectedOverlay	Returns the currently selected overlay object, or None if there are no overlays.
getOverlayOrder	Returns the order in which the given overlay (or an index into the OverlayList list) should be displayed (see the overlayOrder property).
getOrderedOverlays	Returns a list of overlay objects from the OverlayList list, sorted into the order that they should be displayed, as defined by the overlayOrder property.
freeze	This method can be used as a context manager to suppress notification for all Display and DisplayOpts properties related to the given overlay.
freezeOverlay	Suppresses notification for all Display and DisplayOpts properties associated with the given overlay.
thawOverlay	Enables notification for all Display and DisplayOpts properties associated with the given overlay.
defaultDisplaySpace	This property controls how the displaySpace is initialised when overlays are added to a previously empty OverlayList.
detachDisplaySpace	Detaches the displaySpace and bounds properties, and all related DisplayOpts properties, from the parent DisplayContext.

selectedOverlay = <MagicMock name='mock.Int()' id='4116300320'>

Index of the currently ‘selected’ overlay.

Note

The value of this index is in relation to the OverlayList, rather than to the overlayOrder 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, the selectedOverlay index may not change, but the overlay to which it points may be different.

location = <MagicMock name='mock.Point()' id='4116283672'>

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 the displaySpace property.

worldLocation = <MagicMock name='mock.Point()' id='4116283672'>

The location property contains the currently selected 3D location (xyz) in the current display coordinate system. Whenever the location changes, it gets transformed into the world coordinate system, and propagated to this property. The location of different DisplayContext instances is synchronised through this property.

Note

If any NiftiOpts.transform properties have been modified independently of the displaySpace, this value will be invalid.

bounds = <MagicMock name='mock.Bounds()' id='4116394552'>

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='4116324920'>

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='4116324920'>

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='4117273880'>

If this DisplayContext instance has a parent (see props.syncable), and this property is True, the properties of the Display and DisplayOpts instances for every overlay managed by this DisplayContext 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:

• displaySpace

• bounds

• radioOrientation

Note

This property is accessed by the Display class, in its constructor, and when it creates new DisplayOpts instances, to set initial sync states.

syncOverlayVolume = <MagicMock name='mock.Boolean()' id='4117273880'>

This property performs the same task as the syncOverlayDisplay property, but it only affects DisplayOpts properties which control the current volume/timepoint in a 4D overlay.

displaySpace = <MagicMock name='mock.Choice()' id='4117029600'>

The space in which overlays are displayed. This property defines the display coordinate system for this DisplayContext. When it is changed, the NiftiOpts.transform property of all Nifti overlays in the OverlayList is updated. It has two settings, described below. The options for this property are dynamically added by __updateDisplaySpaceOptions().

1. World space (a.k.a. 'world')

   All Nifti overlays are displayed in the space defined by their affine transformation matrix - the NiftiOpts.transform property for every Nifti overlay is set to affine.

2. Scaled-voxel space (a.k.a. 'scaledVoxel')

   All Nifti overlays are displayed in a scaled-voxel coordinate system, with origin set to the centre of voxel (0, 0, 0), and voxels scaled by image pixdims. This is accomplished by setting the NiftiOpts.transform property for every Nifti overlay to pixdim.

3. 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 - its NiftiOpts.transform is set to pixdim-flip). All other Nifti overlays are transformed into this reference space - their NiftiOpts.transform property is set to reference, which results in them being transformed into the scaled voxel space of the reference image.

Note

The NiftiOpts.transform property of any Nifti overlay can be set independently of this property. However, whenever this property changes, it will change the transform property for every Nifti, in the manner described above.

The defaultDisplaySpace() can be used to control how the displaySpace is initialised.

radioOrientation = <MagicMock name='mock.Boolean()' id='4117273880'>

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 the OrthoPanel and LightBoxPanel (and other potential future 2D view panels) to implement the flip.

autoDisplay = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, whenever an overlay is added to the OverlayList, the autodisplay module will be used to automatically configure its display settings. Note that the DisplayContext does not perform this configuration - this flag is used by other modules (e.g. the OverlayListPanel and the OpenFileAction).

loadInMemory = <MagicMock name='mock.Boolean()' id='4117273880'>

If True, all Image instances will be loaded into memory, regardless of their size. Otherwise (the default), large compressed Image 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)

Create a DisplayContext.

Parameters

• overlayList – An OverlayList instance.

• parent – Another DisplayContext instance to be used as the parent of this instance, passed to the SyncableHasProperties constructor.

• defaultDs – Initial value for the defaultDisplaySpace(). Either 'ref' or 'world'. If 'ref' (the default), when overlays are added to an empty list, the displaySpace will be set to the first Nifti 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, and bounds properties are added to the nobind argument

• The overlayGroups, autoDisplay and loadInMemory properties are added to the nounbind argument.

__del__()

Prints a log message.

destroy()

This method must be called when this DisplayContext is no longer needed.

When a DisplayContext is destroyed, all of the Display instances managed by it are destroyed as well.

property destroyed

Returns True if this DisplayContext has been, or is being, destroyed, False otherwise.

getDisplay(overlay, **kwargs)

Returns the Display instance for the specified overlay (or overlay index).

If the overlay is not in the OverlayList, an InvalidOverlayError is raised. Otheriwse, if a Display object does not exist for the given overlay, one is created.

If this DisplayContext has been destroyed, a ValueError is raised.

Parameters

overlay – The overlay to retrieve a Display instance for, or an index into the OverlayList.

All other keyword arguments are assumed to be name=value pairs, containing initial property values.

getOpts(overlay)

Returns the DisplayOpts instance associated with the specified overlay. See getDisplay() and Display.opts() for more details.

getReferenceImage(overlay)

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.

displaySpaceIsRadiological()

Returns True if the current displaySpace 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)

Selects the specified overlay. Raises an IndexError 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 the selectedOverlay property directly.

getSelectedOverlay()

Returns the currently selected overlay object, or None if there are no overlays.

getOverlayOrder(overlay)

Returns the order in which the given overlay (or an index into the OverlayList list) should be displayed (see the overlayOrder property).

Raises an IndexError if the overlay is not in the list.

getOrderedOverlays()

Returns a list of overlay objects from the OverlayList list, sorted into the order that they should be displayed, as defined by the overlayOrder property.

freeze(overlay)

This method can be used as a context manager to suppress notification for all Display and DisplayOpts properties related to the given overlay:

with displayCtx.freeze(overlay):
    # Do stuff which might trigger unwanted
    # Display/DisplayOpts notifications

See freezeOverlay() and thawOverlay().

freezeOverlay(overlay)

Suppresses notification for all Display and DisplayOpts properties associated with the given overlay. Call thawOverlay() to re-enable notification.

See also the freeze() method, which can be used as a context manager to automatically call this method and thawOverlay.

thawOverlay(overlay)

Enables notification for all Display and DisplayOpts properties associated with the given overlay.

__module__ = 'fsleyes.displaycontext.displaycontext'

property defaultDisplaySpace

This property controls how the displaySpace is initialised when overlays are added to a previously empty OverlayList. If the defaultDisplaySpace is set to 'ref', the displaySpace will be initialised to the first Nifti overlay. Otherwise (the defaultDisplaySpace is set to 'world'), the displaySpace will be set to 'world'.

detachDisplaySpace()

Detaches the displaySpace and bounds properties, and all related DisplayOpts properties, from the parent DisplayContext.

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.

__overlayListChanged(*a)

Called when the OverlayList.overlays property changes.

Ensures that a Display and DisplayOpts object exists for every image, updates the bounds property, makes sure that the overlayOrder property is consistent, and updates constraints on the selectedOverlay property.

__updateDisplaySpaceOptions()

Updates the displaySpace property so it is synchronised with the current contents of the OverlayList

This method is called by the __overlayListChanged() method.

__setTransform(image)

Sets the NiftiOpts.transform property associated with the given Nifti overlay to a sensible value, given the current value of the displaySpace property.

Called by the __displaySpaceChanged() method, and by __overlayListChanged() for any Image overlays which have been newly added to the OverlayList.

Parameters

image – An Image overlay.

__displaySpaceChanged(*a)

Called when the displaySpace property changes. Updates the NiftiOpts.transform property for all Nifti overlays in the OverlayList.

__syncOverlayOrder()

Ensures that the overlayOrder property is up to date with respect to the OverlayList.

__overlayBoundsChanged(value, valid, opts, name)

Called when the DisplayOpts.bounds property of any overlay changes. Updates the bounds property and preserves the display location in terms of the worldLocation.

__syncOverlayDisplayChanged(*a)

Called when the syncOverlayDisplay property changes.

Synchronises or unsychronises the Display and DisplayOpts instances for every overlay to/from their parent instances.

__syncOverlayVolumeChanged(*a)

Called when the syncOverlayVolume property changes.

Synchronises or unsychronises the volume/timepoint properties of the Display and DisplayOpts instances for every overlay.

__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 their DisplayOpts.bounds properties).

__locationChanged(*a)

Called when the location property changes. Propagates the new location to the worldLocation property.

__worldLocationChanged(*a)

Called when the worldLocation property changes. Propagates the new location to the location property.

__propagateLocation(dest)

Called by the __locationChanged() and __worldLocationChanged() methods. The dest argument may be either 'world' (the worldLocation is updated from the location), or 'display' (vice-versa).