fsleyes.displaycontext.colourmapopts

This module provides the ColourMapOpts class, a mixin for use with DisplayOpts sub-classes.

class fsleyes.displaycontext.colourmapopts.ColourMapOpts

Bases: object

The ColourMapOpts class is a mixin for use with DisplayOpts sub-classes. It provides properties and logic for displaying overlays which are coloured according to some data values. See the MeshOpts and VolumeOpts classes for examples of classes which inherit from this class.

To use the ColourMapOpts class, you must:

1. Define your class to inherit from both DisplayOpts and ColourMapOpts:

   class MyOpts(DisplayOpts, ColourMapOpts):
       ...
   

2. Call the ColourMapOpts.__init__ method after DisplayOpts.__init__():

   def __init__(self, *args, **kwargs):
       DisplayOpts.__init__(self, *args, **kwargs)
       ColourMapOpts.__init__(self)
   

3. Implement the getDataRange() and (if necessary) getClippingRange() and getModulateRange() methods.

4. Call updateDataRange() whenever the data driving the colouring changes.

The ColourMapOpts class links the Display.brightness and Display.contrast properties to its own displayRange property, so changes in either of the former will result in a change to the latter, and vice versa. This relationship is defined by the displayRangeToBricon() and briconToDisplayRange() functions, in the colourmaps module.

ColourMapOpts instances provide the following methods:

updateDataRange	Must be called by sub-classes whenever the ranges of the underlying data or clipping/modulate values change.
getDataRange	Must be overridden by sub-classes.
getClippingRange	Can be overridden by sub-classes if necessary.
getModulateRange	Can be overridden by sub-classes if necessary.

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

Values which map to the minimum and maximum colour map colours.

Note

The values that this property can take are unbound because of the interaction between it and the Display.brightness and Display.contrast properties. The displayRange and clippingRange properties are not clamped (they can take values outside of their minimum/maximum values) because the data range for large NIFTI images may not be known, and may change as more data is read from disk.

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

Values outside of this range are not shown. Clipping works as follows:

• Values less than or equal to the minimum clipping value are clipped.

• Values greater than or equal to the maximum clipping value are clipped.

Because of this, a small amount of padding is added to the low and high clipping range limits, to make it possible for all values to be displayed.

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

If True, the behaviour of clippingRange is inverted, i.e. values inside the clipping range are clipped, instead of those outside the clipping range.

cmap = <MagicMock name='mock.ColourMap()' id='4116140696'>

The colour map, a matplotlib.colors.Colourmap instance.

gamma = <MagicMock name='mock.Real()' id='4116054224'>

Gamma correction factor - exponentially weights the cmap and negCmap towards the low or high ends.

This property takes values between -1 and +1. The exponential weight that should actually be used to apply gamma correction should be derived as follows:

• -1 corresponds to a gamma of 0.01

• 0 corresponds to a gamma of 1

• +1 corresponds to a gamma of 10

The realGamma() method will apply this scaling and return the exponent to be used.

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

Applies a logarithmic function to the display range.

Normally, the display range is linearly mapped to the colour map - if this setting is enabled, the logarithm of the display range is linearly mapped to the colour map.

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

Resolution for the colour map, i.e. the number of colours to use.

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

If True, the colour maps are applied using linear interpolation. Otherwise they are applied using nearest neighbour interpolation.

negativeCmap = <MagicMock name='mock.ColourMap()' id='4116140696'>

A second colour map, used if useNegativeCmap is True. When active, the cmap is used to colour positive values, and the negativeCmap is used to colour negative values.

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

When True, the cmap is used to colour positive values, and the negativeCmap is used to colour negative values. When this property is enabled, the minimum value for both the displayRange and clippingRange is set to zero. Both ranges are applied to positive values, and negated/inverted for negative values.

Note

When this property is set to True, the Display.brightness and Display.contrast properties are disabled, as managing the interaction between them would be far too complicated.

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

Use an inverted version of the current colour map (see the cmap property).

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

If True, the low bounds on both the displayRange and clippingRange ranges will be linked together.

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

If True, the high bounds on both the displayRange and clippingRange ranges will be linked together.

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

If True, the Display.alpha is modulated by the data. Regions with a value near to the low modulateRange will have an alpha near 0, and regions with a value near to the high modulateRange will have an alpha near 1.

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

Range used to determine how much to modulate Display.alpha by, when modulateAlpha is active.

static realGamma(gamma)

Return the value of gamma property, scaled appropriately. for use as an exponent.

__init__()

Create a ColourMapOpts instance. This must be called after the DisplayOpts.__init__() method.

__dict__ = mappingproxy({'__module__': 'fsleyes.displaycontext.colourmapopts', '__doc__': 'The ``ColourMapOpts`` class is a mixin for use with\n :class:`.DisplayOpts` sub-classes. It provides properties and logic\n for displaying overlays which are coloured according to some data values.\n See the :class:`.MeshOpts` and :class:`.VolumeOpts` classes for examples\n of classes which inherit from this class.\n\n\n To use the ``ColourMapOpts`` class, you must:\n\n 1. Define your class to inherit from both :class:`.DisplayOpts` and\n ``ColourMapOpts``::\n\n class MyOpts(DisplayOpts, ColourMapOpts):\n ...\n\n 2. Call the ``ColourMapOpts.__init__`` method *after*\n :meth:`.DisplayOpts.__init__`::\n\n def __init__(self, *args, **kwargs):\n DisplayOpts.__init__(self, *args, **kwargs)\n ColourMapOpts.__init__(self)\n\n 3. Implement the :meth:`getDataRange` and (if necessary)\n :meth:`getClippingRange` and :meth:`getModulateRange` methods.\n\n 4. Call :meth:`updateDataRange` whenever the data driving the colouring\n changes.\n\n\n The ``ColourMapOpts`` class links the :attr:`.Display.brightness` and\n :attr:`.Display.contrast` properties to its own :attr:`displayRange`\n property, so changes in either of the former will result in a change to\n the latter, and vice versa. This relationship is defined by the\n :func:`~.colourmaps.displayRangeToBricon` and\n :func:`~.colourmaps.briconToDisplayRange` functions, in the\n :mod:`.colourmaps` module.\n\n\n ``ColourMapOpts`` instances provide the following methods:\n\n .. autosummary::\n :nosignatures:\n\n updateDataRange\n getDataRange\n getClippingRange\n getModulateRange\n ', 'displayRange': <MagicMock name='mock.Bounds()' id='4116394552'>, 'clippingRange': <MagicMock name='mock.Bounds()' id='4116394552'>, 'invertClipping': <MagicMock name='mock.Boolean()' id='4117273880'>, 'cmap': <MagicMock name='mock.ColourMap()' id='4116140696'>, 'gamma': <MagicMock name='mock.Real()' id='4116054224'>, 'logScale': <MagicMock name='mock.Boolean()' id='4117273880'>, 'cmapResolution': <MagicMock name='mock.Int()' id='4116300320'>, 'interpolateCmaps': <MagicMock name='mock.Boolean()' id='4117273880'>, 'negativeCmap': <MagicMock name='mock.ColourMap()' id='4116140696'>, 'useNegativeCmap': <MagicMock name='mock.Boolean()' id='4117273880'>, 'invert': <MagicMock name='mock.Boolean()' id='4117273880'>, 'linkLowRanges': <MagicMock name='mock.Boolean()' id='4117273880'>, 'linkHighRanges': <MagicMock name='mock.Boolean()' id='4117273880'>, 'modulateAlpha': <MagicMock name='mock.Boolean()' id='4117273880'>, 'modulateRange': <MagicMock name='mock.Bounds()' id='4116394552'>, 'realGamma': <staticmethod object>, '__init__': <function ColourMapOpts.__init__>, 'getColourMapOptsListenerName': <function ColourMapOpts.getColourMapOptsListenerName>, 'destroy': <function ColourMapOpts.destroy>, 'getDataRange': <function ColourMapOpts.getDataRange>, 'getClippingRange': <function ColourMapOpts.getClippingRange>, 'getModulateRange': <function ColourMapOpts.getModulateRange>, 'resetDisplayRange': <fsleyes.actions.ActionFactory object>, 'updateDataRange': <function ColourMapOpts.updateDataRange>, '_ColourMapOpts__toggleListeners': <function ColourMapOpts.__toggleListeners>, '_ColourMapOpts__briconChanged': <function ColourMapOpts.__briconChanged>, '_ColourMapOpts__displayRangeChanged': <function ColourMapOpts.__displayRangeChanged>, '_ColourMapOpts__useNegativeCmapChanged': <function ColourMapOpts.__useNegativeCmapChanged>, '_ColourMapOpts__linkLowRangesChanged': <function ColourMapOpts.__linkLowRangesChanged>, '_ColourMapOpts__linkHighRangesChanged': <function ColourMapOpts.__linkHighRangesChanged>, '_ColourMapOpts__linkRangesChanged': <function ColourMapOpts.__linkRangesChanged>, '_ColourMapOpts__modulateAlphaChanged': <function ColourMapOpts.__modulateAlphaChanged>, '__dict__': <attribute '__dict__' of 'ColourMapOpts' objects>, '__weakref__': <attribute '__weakref__' of 'ColourMapOpts' objects>, '__annotations__': {}})

__module__ = 'fsleyes.displaycontext.colourmapopts'

__weakref__

list of weak references to the object (if defined)

getColourMapOptsListenerName()

Returns the name used by this ColourMapOpts instance for registering internal property listeners.

Sibling ColourMapOpts instances need to toggle each other’s property listeners (see the __toggleListeners() method), so they use this method to retrieve each other’s listener names.

destroy()

Must be called when this ColourMapOpts is no longer needed, and before DisplayOpts.destroy() is called. Removes property listeners.

getDataRange()

Must be overridden by sub-classes. Must return the range of the data used for colouring as a (min, max) tuple. Note that, even if there is no effective data range, you should return two different values for min and max (e.g. (0, 1)), because otherwise the relationship between the displayRange and the Display.brightness and Display.contrast properties will be corrupted.

getClippingRange()

Can be overridden by sub-classes if necessary. If the clipping range is always the same as the data range, this method does not need to be overridden.

Otherwise, if the clipping range differs from the data range (see e.g. the VolumeOpts.clipImage property), this method must return the clipping range as a (min, max) tuple.

When a sub-class implementation wishes to use the default clipping range/behaviour, it should return the value returned by this base-class implementation.

getModulateRange()

Can be overridden by sub-classes if necessary. If the modulate range is always the same as the data range, this method does not need to be overridden.

Otherwise, if the modulate ange differs from the data range (see e.g. the VolumeOpts.modulateImage property), this method must return the modulate range as a (min, max) tuple.

When a sub-class implementation wishes to use the default modulate range/behaviour, it should return the value returned by this base-class implementation.

resetDisplayRange()

Resets the displayRange, clippingRange, and modulateRange to their initial values.

updateDataRange(resetDR=True, resetCR=True, resetMR=True)

Must be called by sub-classes whenever the ranges of the underlying data or clipping/modulate values change. Configures the minimum/ maximum bounds of the displayRange, clippingRange, and modulateRange properties.

Parameters

• resetDR – If True (the default), the displayRange property will be reset to the data range returned by getDataRange(). Otherwise the existing value will be preserved.

• resetCR – If True (the default), the clippingRange property will be reset to the clipping range returned by getClippingRange(). Otherwise the existing value will be preserved.

• resetMR – If True (the default), the modulateRange property will be reset to the modulate range returned by getModulateRange(). Otherwise the existing value will be preserved.

Note that both of these flags will be ignored if the existing low/high displayRange/clippingRange/modulateRange values and limits are equal to each other.

__toggleListeners(enable=True)

This method enables/disables the property listeners which are registered on the displayRange and Display.brightness/Display.contrast/properties.

Because these properties are linked via the __displayRangeChanged() and __briconChanged() methods, we need to be careful about avoiding recursive callbacks.

Furthermore, because the properties of both ColourMapOpts and Display instances are possibly synchronised to a parent instance (which in turn is synchronised to other children), we need to make sure that the property listeners on these other sibling instances are not called when our own property values change. So this method disables/enables the property listeners on all sibling ColourMapOpts and Display instances.

__briconChanged(*a)

Called when the brightness/contrast properties of the Display instance change.

Updates the displayRange property accordingly.

See colourmaps.briconToDisplayRange().

__displayRangeChanged(*a)

Called when the attr:`displayRange property changes.

Updates the Display.brightness and Display.contrast properties accordingly.

See colourmaps.displayRangeToBricon().

__useNegativeCmapChanged(*a, **kwa)

Called when the useNegativeCmap property changes. Enables/disables the Display.brightness and Display.contrast properties, and calls updateDataRange().

Parameters

updateDatRange – Must be passed as a keyword argument. If True (the default), calls updateDataRange().

__linkLowRangesChanged(*a)

Called when the linkLowRanges property changes. Calls the __linkRangesChanged() method.

__linkHighRangesChanged(*a)

Called when the linkHighRanges property changes. Calls the __linkRangesChanged() method.

__linkRangesChanged(val, idx)

Called when either the linkLowRanges or linkHighRanges properties change. Binds/unbinds the specified range properties together.

Parameters

• val – Boolean indicating whether the range values should be linked or unlinked.

• idx – Range value index - 0 corresponds to the low range value, and 1 to the high range value.

__modulateAlphaChanged(*a)

Called when the modulateAlpha property changes.

When modulateAlpha is active, Display.alpha is disabled, and vice-versa.