fsleyes.overlay

This module defines the OverlayList class, which is a simple but fundamental class in FSLeyes - it is a container for all loaded overlays. Only one OverlayList ever exists, and it is shared throughout the entire application.

What is an overlay?

The definition of an overlay is fairly broad; any object can be added to the OverlayList - there is no Overlay base class, nor any interface which must be provided by an overlay object. The only requirements imposed on an overlay type are:

• Must be able to be created with a single __init__ parameter, which is a string specifying the data source location (e.g. a file name) (but see the note below about Image overlays).

• Must have an attribute called name, which is used as the initial display name for the overlay.

• Must have an attribute called dataSource, which is used to identify the source of the overlay data.

• Must be hashable (i.e. usable as a dictionary key).

• Must be supported by the gl package .. ok, this is a pretty big requirement .. See the globject and the displaycontext.OVERLAY_TYPES documentation for details on how to get started with this one.

One further requirement is imposed on overlay types which derive from the Image class:

• The __init__ method for sub-classes of the Image class must accept the loadData, calcRange, indexed , and threaded parameters, and pass them through to the base class __init__ method.

Currently (fsleyes version 0.34.2) the only overlay types in existence (and able to be rendered) are:

Image
FEATImage
MelodicImage
MGHImage
DTIFitTensor
VTKMesh
GiftiMesh
FreesurferMesh
Bitmap

This module also provides a few convenience classes and functions:

ProxyImage	MagicMock is a subclass of Mock with default implementations of most of the magic methods.
findFEATImage	Searches the given OverlayList to see if there is a FEATImage associated with the given overlay.

class fsleyes.overlay.OverlayList(overlays=None)

Bases: __main__.MockClass

Class representing a collection of overlays to be displayed together.

Contains a props.properties_types.List property called overlays, containing overlay objects (e.g. Image or Mesh objects). Listeners can be registered on the overlays property, so they are notified when the overlay list changes.

An OverlayList object has a few wrapper methods around the overlays property, allowing the OverlayList to be used as if it were a list itself.

The loadoverlay module contains some convenience functions for loading and adding overlays.

The getData() and setData() methods allow arbitrary bits of data associated with an overlay to be stored and retrieved.

overlays = <MagicMock name='mock.List()' id='281473495788224'>

A list of overlay objects to be displayed.

__init__(overlays=None)

Create an OverlayList object from the given sequence of overlays.

initProps(overlay)

Returns a dict containing initial Display and DisplayOpts property values to be used for the given overlay, if they were specified via the append() or insert() methods.

This method requires that there is no overlap between the property names used in Display and DisplayOpts classes.

getData(overlay, key, *args)

Returns any stored value associated with the specified overlay and key.

Parameters

default – Default value if there is no value associated with the given key. If not specified, and an unknown key is given, a KeyError is raised.

setData(overlay, key, value)

Stores the given value via the specified overlay and key.

find(name)

Returns the first overlay with the given name or dataSource, or None if there is no overlay with said name/dataSource.

__str__()

Return str(self).

__repr__()

Return repr(self).

__len__()

__getitem__(key)

__iter__()

__contains__(item)

__setitem__(key, val)

__delitem__(key)

index(item)

count(item)

insert(index, item, **initProps)

Insert a new overlay into the overlay list.

Any initial Display/DisplayOpts property values may be passed in as keyword arguments.

append(item, **initProps)

Add a new overlay to the end of the overlay list.

Any initial Display/DisplayOpts property values may be passed in as keyword arguments.

extend(iterable, **initProps)

Add new overlays to the overlay list.

Any initial Display/DisplayOpts property values may be passed in as keyword arguments, where the argument name is the property name, and the argument value is a dict of {overlay : value} mappings.

insertAll(index, items)

pop(index=-1)

move(from_, to)

remove(item)

clear()

_OverlayList__validateOverlay(atts, overlay)

Makes sure that the given overlay object is valid.

__module__ = 'fsleyes.overlay'

class fsleyes.overlay.PropCache

Bases: object

Deprecated - use fsleyes_props.PropCache instead.

A little convenience class which can be used to track and cache property values, related to each overlay in the OverlayList, on some HasProperties object.

Whenever the selected overlay changes, the property values of the previously selected overlay are cached. Later on, when that overlay is re-selected, the cached property values may be retrieved via the get() method.

__init__ = <MagicMock name='mock.utils.deprecated.deprecated()()' id='281473495817568'>

destroy()

Must be called when this PropCache is no longer needed. Removes property listeners and clears references.

get(overlay, propName, *args)

Returns the cached property value for the specified overlay. If there is no cached property value for the overlay, the specified default value is returned. If a default value is not provided, the current property value is returned.

Parameters

• overlay – Overlay to retrieve the property value for

• propName – Name of the property to return a value for

• default – Value to return if a value for the the overlay/property is not cached

_PropCache__cacheGC()

Removes any obsolete entries (those pertaining to overlays which are no longer present in the OverlayList) from the cache.

_PropCache__selectedOverlayChanged(*a)

Called when either the DisplayContext.selectedOverlay, or the OverlayList.overlays change. Caches property values pertaining to the previously selected overlay.

__dict__ = mappingproxy({'__module__': 'fsleyes.overlay', '__doc__': 'Deprecated - use :class:`fsleyes_props.PropCache` instead.\n\n A little convenience class which can be used to track and cache\n property values, related to each overlay in the :class:`.OverlayList`,\n on some :class:`.HasProperties` object.\n\n\n Whenever the selected overlay changes, the property values of the\n previously selected overlay are cached. Later on, when that overlay\n is re-selected, the cached property values may be retrieved via\n the :meth:`get` method.\n ', '__init__': <MagicMock name='mock.utils.deprecated.deprecated()()' id='281473495817568'>, 'destroy': <function PropCache.destroy>, 'get': <function PropCache.get>, '_PropCache__selectedOverlayChanged': <function PropCache.__selectedOverlayChanged>, '_PropCache__cacheGC': <function PropCache.__cacheGC>, '__dict__': <attribute '__dict__' of 'PropCache' objects>, '__weakref__': <attribute '__weakref__' of 'PropCache' objects>})

__module__ = 'fsleyes.overlay'

__weakref__

list of weak references to the object (if defined)

fsleyes.overlay.findFEATImage(overlayList, overlay)

Searches the given OverlayList to see if there is a FEATImage associated with the given overlay. Returns the FEATImage if found, otherwise returns None.

fsleyes.overlay.findMeshReferenceImage(overlayList, overlay)

Searches the OverlayList and tries to identify a reference image for the given Mesh overlay. Returns the identified overlay, or None if one can’t be found.