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 loadMeta and dataMgr parameters, and pass them through to the base class __init__ method.

Currently (fsleyes version 1.19.0.dev0+g1d541d09b.d20260312) the only overlay types in existence (and able to be rendered) are:

Image	Class which represents a NIFTI image.
FEATImage	An Image which contains the input data from a FEAT analysis.
MelodicImage	The MelodicImage class is an Image which encapsulates the results of a FSL MELODIC analysis.
MGHImage	The MGHImage class is a NIFTI Image which has been converted from a Freesurfer .mgh file.
DTIFitTensor	The DTIFitTensor class is able to load and encapsulate the diffusion tensor data generated by the FSL dtifit tool.
VTKMesh	The VTKMesh class represents a triangle mesh loaded from a VTK file.
GiftiMesh	Class which represents a GIFTI surface image.
FreesurferMesh	The FreesurferMesh class represents a triangle mesh loaded from a Freesurfer geometry file.
Bitmap	The Bitmap class can be used to load a bitmap image.

This module also provides a few convenience classes and functions:

ProxyImage	The ProxyImage class is a simple wrapper around an Image instance.
findFEATImage	Searches the given OverlayList to see if there is a FEATImage associated with the given overlay.
findMeshReferenceImage	Uses heuristics to try to identify a reference image for the given Mesh overlay.

fsleyes.overlay.rungc(func)

Decorator which triggers garbage collection. Used by the OverlayList on various methods. Schedules the Python garbage collector to be executed on the idle loop.

class fsleyes.overlay.OverlayList(*args, **kwargs)

Bases: HasProperties

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.

__validateOverlay(atts, overlay)

Makes sure that the given overlay object is valid.

overlays

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

Returns a multi-line string containing the names and values of all the properties of this object.

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

replace(iterable, **initProps)

Replace the contents of 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.

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)

Alias for removeListener().

clear()

__annotations__ = {}

__module__ = 'fsleyes.overlay'

class fsleyes.overlay.ProxyImage(*args, **kwargs)

Bases: Image

The ProxyImage class is a simple wrapper around an Image instance. It is intended to be used to represent images or data which are derived from another image.

__init__(base, *args, **kwargs)

Create a ProxyImage.

Parameters:

• base – The Image instance upon which this ProxyImage is based.

• volume – Must be passed as a keyword argument. If provided, is a slice into the image data specifying the 3D volume to copy. If not provided, the entire image is copied.

getBase()

Returns the base Image of this ProxyImage.

__annotations__ = {}

__module__ = 'fsleyes.overlay'

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)

Uses heuristics to try to identify a reference image for the given Mesh overlay. Returns the identified overlay, or None if one can’t be found.

fsleyes.overlay.findVTKReferenceImage(overlayList, overlay)

Sub-function of findMeshReferenceImage(). If this is a mesh generated by FIRST, it will have a common file prefix with the input image, e.g. struc-L_Hipp_first.vtk.

fsleyes.overlay.findFreeSurferReferenceImage(overlayList, overlay)

Sub-function of findMeshReferenceImage(). If this is a freesurfer mesh from a typical freesurfer output directory, it will be in <dir>/surf/, and the source image will be in <dir>/mri/. Let’s check if there are any images loaded from the /mri/ directory.

fsleyes.overlay.findAnyReferenceImage(overlayList, overlay)

Sub-function of findMeshReferenceImage(). Tries to find a reference image for a mesh overlay. if an image has been loaded from the same directory as the mesh, it is set as the reference.