fsleyes.displaycontext.colourmapopts
¶
This module provides the ColourMapOpts
class, a mixin for use with
DisplayOpts
sub-classes.
-
class
fsleyes.displaycontext.colourmapopts.
ColourMapOpts
[source]¶ Bases:
object
The
ColourMapOpts
class is a mixin for use withDisplayOpts
sub-classes. It provides properties and logic for displaying overlays which are coloured according to some data values. See theMeshOpts
andVolumeOpts
classes for examples of classes which inherit from this class.To use the
ColourMapOpts
class, you must:Define your class to inherit from both
DisplayOpts
andColourMapOpts
:class MyOpts(DisplayOpts, ColourMapOpts): ...
Call the
ColourMapOpts.__init__
method afterDisplayOpts.__init__()
:def __init__(self, *args, **kwargs): DisplayOpts.__init__(self, *args, **kwargs) ColourMapOpts.__init__(self)
Implement the
getDataRange()
and (if necessary)getClippingRange()
methods.Call
updateDataRange()
whenever the data driving the colouring changes.
The
ColourMapOpts
class links theDisplay.brightness
andDisplay.contrast
properties to its owndisplayRange
property, so changes in either of the former will result in a change to the latter, and vice versa. This relationship is defined by thedisplayRangeToBricon()
andbriconToDisplayRange()
functions, in thecolourmaps
module.ColourMapOpts
instances provide the following methods:Must be called by sub-classes whenever the ranges of the underlying data or clipping values change.
Must be overridden by sub-classes.
Can be overridden by sub-classes if necessary.
-
displayRange
= <MagicMock name='mock.Bounds()' id='3030104000'>¶ 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
andDisplay.contrast
properties. ThedisplayRange
andclippingRange
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='3030104000'>¶ 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='3031712864'>¶ If
True
, the behaviour ofclippingRange
is inverted, i.e. values inside the clipping range are clipped, instead of those outside the clipping range.
-
cmap
= <MagicMock name='mock.ColourMap()' id='3029491688'>¶ The colour map, a
matplotlib.colors.Colourmap
instance.
-
gamma
= <MagicMock name='mock.Real()' id='3030854648'>¶ Gamma correction factor - exponentially weights the
cmap
andnegCmap
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.
-
cmapResolution
= <MagicMock name='mock.Int()' id='3030091688'>¶ Resolution for the colour map, i.e. the number of colours to use.
-
interpolateCmaps
= <MagicMock name='mock.Boolean()' id='3031712864'>¶ If
True
, the colour maps are applied using linear interpolation. Otherwise they are applied using nearest neighbour interpolation.
-
negativeCmap
= <MagicMock name='mock.ColourMap()' id='3029491688'>¶ A second colour map, used if
useNegativeCmap
isTrue
. When active, thecmap
is used to colour positive values, and thenegativeCmap
is used to colour negative values.
-
useNegativeCmap
= <MagicMock name='mock.Boolean()' id='3031712864'>¶ When
True
, thecmap
is used to colour positive values, and thenegativeCmap
is used to colour negative values. When this property is enabled, the minimum value for both thedisplayRange
andclippingRange
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
, theDisplay.brightness
andDisplay.contrast
properties are disabled, as managing the interaction between them would be far too complicated.
-
invert
= <MagicMock name='mock.Boolean()' id='3031712864'>¶ Use an inverted version of the current colour map (see the
cmap
property).
-
linkLowRanges
= <MagicMock name='mock.Boolean()' id='3031712864'>¶ If
True
, the low bounds on both thedisplayRange
andclippingRange
ranges will be linked together.
-
linkHighRanges
= <MagicMock name='mock.Boolean()' id='3031712864'>¶ If
True
, the high bounds on both thedisplayRange
andclippingRange
ranges will be linked together.
-
static
realGamma
(gamma)[source]¶ Return the value of
gamma
property, scaled appropriately. for use as an exponent.
-
__init__
()[source]¶ Create a
ColourMapOpts
instance. This must be called after theDisplayOpts.__init__()
method.
-
getColourMapOptsListenerName
()[source]¶ 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.
-
_ColourMapOpts__briconChanged
(*a)¶ Called when the
brightness
/contrast
properties of theDisplay
instance change.Updates the
displayRange
property accordingly.
-
_ColourMapOpts__displayRangeChanged
(*a)¶ Called when the attr:`displayRange property changes.
Updates the
Display.brightness
andDisplay.contrast
properties accordingly.
-
_ColourMapOpts__linkHighRangesChanged
(*a)¶ Called when the
linkHighRanges
property changes. Calls the__linkRangesChanged()
method.
-
_ColourMapOpts__linkLowRangesChanged
(*a)¶ Called when the
linkLowRanges
property changes. Calls the__linkRangesChanged()
method.
-
_ColourMapOpts__linkRangesChanged
(val, idx)¶ Called when either the
linkLowRanges
orlinkHighRanges
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.
-
_ColourMapOpts__toggleListeners
(enable=True)¶ This method enables/disables the property listeners which are registered on the
displayRange
andDisplay.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
andDisplay
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 siblingColourMapOpts
andDisplay
instances.
-
_ColourMapOpts__useNegativeCmapChanged
(*a, **kwa)¶ Called when the
useNegativeCmap
property changes. Enables/disables theDisplay.brightness
andDisplay.contrast
properties, and callsupdateDataRange()
.- Parameters
updateDatRange – Must be passed as a keyword argument. If
True
(the default), callsupdateDataRange()
.
-
__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` 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 ', 'displayRange': <MagicMock name='mock.Bounds()' id='3030104000'>, 'clippingRange': <MagicMock name='mock.Bounds()' id='3030104000'>, 'invertClipping': <MagicMock name='mock.Boolean()' id='3031712864'>, 'cmap': <MagicMock name='mock.ColourMap()' id='3029491688'>, 'gamma': <MagicMock name='mock.Real()' id='3030854648'>, 'cmapResolution': <MagicMock name='mock.Int()' id='3030091688'>, 'interpolateCmaps': <MagicMock name='mock.Boolean()' id='3031712864'>, 'negativeCmap': <MagicMock name='mock.ColourMap()' id='3029491688'>, 'useNegativeCmap': <MagicMock name='mock.Boolean()' id='3031712864'>, 'invert': <MagicMock name='mock.Boolean()' id='3031712864'>, 'linkLowRanges': <MagicMock name='mock.Boolean()' id='3031712864'>, 'linkHighRanges': <MagicMock name='mock.Boolean()' id='3031712864'>, 'realGamma': <staticmethod object>, '__init__': <function ColourMapOpts.__init__>, 'getColourMapOptsListenerName': <function ColourMapOpts.getColourMapOptsListenerName>, 'destroy': <function ColourMapOpts.destroy>, 'getDataRange': <function ColourMapOpts.getDataRange>, 'getClippingRange': <function ColourMapOpts.getClippingRange>, '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>, '__dict__': <attribute '__dict__' of 'ColourMapOpts' objects>, '__weakref__': <attribute '__weakref__' of 'ColourMapOpts' objects>})¶
-
__module__
= 'fsleyes.displaycontext.colourmapopts'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
destroy
()[source]¶ Must be called when this
ColourMapOpts
is no longer needed, and beforeDisplayOpts.destroy()
is called. Removes property listeners.
-
getDataRange
()[source]¶ 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 formin
andmax
(e.g.(0, 1)
), because otherwise the relationship between thedisplayRange
and theDisplay.brightness
andDisplay.contrast
properties will be corrupted.
-
getClippingRange
()[source]¶ 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.
-
resetDisplayRange
()[source]¶ Resets the
displayRange
andclippingRange
to their initial values.
-
updateDataRange
(resetDR=True, resetCR=True)[source]¶ Must be called by sub-classes whenever the ranges of the underlying data or clipping values change. Configures the minimum/maximum bounds of the
displayRange
andclippingRange
properties.- Parameters
resetDR – If
True
(the default), thedisplayRange
property will be reset to the data range returned bygetDataRange()
. Otherwise the existing value will be preserved.resetCR – If
True
(the default), theclippingRange
property will be reset to the clipping range returned bygetClippingRange()
. Otherwise the existing value will be preserved.
Note that both of these flags will be ignored if the existing low/high
displayRange
/clippingRange
values and limits are equal to each other.