fsleyes.colourmaps
¶
This module manages the colour maps and lookup tables available for overlay rendering in FSLeyes.
The init()
function must be called before any colour maps or lookup
tables can be accessed [*].
FSLeyes colour maps and lookup tables are stored in the following locations:
[assetsbase]/assets/colourmaps/
[assetsbase]/assets/luts/
[settingsbase]/colourmaps/
[settingsbase]/luts/
where [assetsbase]
is the location of the FSLeyes assets directory (see
the fsleyes.assetDir
attribute), and [settingsbase]
is the base
directory use by the fsl.utils.settings
module for storing FSLeyes
application settings and data. “Built-in” colour maps and lookup tables are
stored underneath [assetsbase]
, and user-added ones are stored under
[settingsbase]
.
When init()
is called, it searches in the above locations, and attempts
to load all files within which have the suffix .cmap
or .lut
respectively. If a user-added map file has the same name as a built-in map
file, the user-added one will override the built-in.
[*] | Only the scanColourMaps() and scanLookupTables() functions
may be called before init() is called. |
Colour maps¶
A .cmap
file defines a colour map which may be used to display a range of
intensity values - see the VolumeOpts.cmap
property for an example. A
.cmap
file must contain a list of RGB colours, one per line, with each
colour specified by three space-separated floating point values in the range
0.0 - 1.0
, for example:
1.000000 0.260217 0.000000
0.000000 0.687239 1.000000
0.738949 0.000000 1.000000
This list of RGB values is used to create a ListedColormap
object,
which is then registered with the matplotlib.cm
module (using the file
name prefix as the colour map name), and thus made available for rendering
purposes.
The following functions are available for managing and accessing colour maps:
scanColourMaps |
Scans the colour maps directories, and returns a list containing the names of all colour maps contained within. |
getColourMaps |
Returns a list containing the names of all available colour maps. |
getColourMap |
Returns the colour map instance of the specified key. |
getColourMapLabel |
Returns a label/display name for the specified colour map. |
getColourMapFile |
Returns the file associated with the specified colour map, or None if the colour map is registered but not installed. |
registerColourMap |
Loads RGB data from the given file, and registers it as a matplotlib ListedColormap instance. |
installColourMap |
Attempts to install a previously registered colourmap into the [settingsbase]/colourmaps/ directory. |
isColourMapRegistered |
Returns True if the specified colourmap is registered, False otherwise. |
isColourMapInstalled |
Returns True if the specified colourmap is installed, False otherwise. |
Display name and ordering¶
For built-in colour maps, a file named [assetsbase]/colourmaps/order.txt
is assumed to contain a list of colour map names, and colour map identifiers,
defining the order in which the colour maps should be displayed to the
user. Any colour maps which are present in [assetsbase]/colourmaps/
, but
are not listed in the order.txt
, file will be appended to the end of the
list, and their name will be derived from the file name.
If a file [settingsbase]/colourmaps/order.txt
exists, then it will be used
in place of the order.txt
file in [assetsbase]
.
User-added colour maps¶
An identifier and display name for all user-added colour maps are added to a
persistent setting called fsleyes.colourmaps
, which is a dictionary of {
cmapid : displayName }
mappings. The cmapid
is typically the display
name, converted to lower case, with spaces replaced with underscores. A
user-added colour map with id cmapid
will be saved as
[settingsbase]/colourmaps/cmapid.cmap
. All user-added colour maps wll be
displayed after all built-in colour maps, and their order cannot be
customised. Any user-added colour map files which are not present in the
fsleyes.colourmaps
dictionary will be given a display name the same as
the colour map ID (which is taken from the file name).
Installing a user-added colour map is a two-step process:
- First, the colour map must be registered, via the
registerColourMap()
function. This adds the colour map to the register, but does not persist it beyond the current execution environment.- Calling the
installColourMap()
function will add the colour map permanently.
Lookup tables¶
A .lut
file defines a lookup table which may be used to display images
wherein each voxel has a discrete integer label. Each of the possible voxel
values such an image has an associated colour and name. Each line in a
.lut
file must specify the label value, RGB colour, and associated name.
The first column (where columns are space-separated) defines the label value,
the second to fourth columns specify the RGB values, and all remaining columns
give the label name. For example:
1 0.00000 0.93333 0.00000 Frontal Pole
2 0.62745 0.32157 0.17647 Insular Cortex
3 1.00000 0.85490 0.72549 Superior Frontal Gyrus
This list of label, colour, and name mappings is used to create a
LookupTable
instance, which can be used to access the colours and
names associated with each label value.
Once created, LookupTable
instances may be modified - labels can be
added/removed, and the name/colour of existing labels can be modified. The
installLookupTable()
method will install a new lookup table, or save
any changes made to an existing one.
Built-in and user-added lookup tables are managed in the same manner as
described for colour maps above. The following functions are available to
access and manage LookupTable
instances:
scanLookupTables |
Scans the lookup tables directories, and returns a list containing the names of all lookup tables contained within. |
getLookupTables |
Returns a list containing all available lookup tables. |
getLookupTable |
Returns the LookupTable instance of the specified key/ID. |
getLookupTableFile |
Returns the file associated with the specified lookup table, or None if the lookup table is registered but not installed. |
registerLookupTable |
Registers the given LookupTable instance (if lut is a string, it is assumed to be the name of a .lut file, which is loaded). |
installLookupTable |
Attempts to install/save a previously registered lookup table into the [settingsbase]/luts directory. |
isLookupTableRegistered |
Returns True if the specified lookup table is registered, False otherwise. |
isLookupTableInstalled |
Returns True if the specified loolup table is installed, False otherwise. |
Miscellaneous¶
Some utility functions are also kept in this module. These functions are used for querying installed colour maps and lookup tables,
getCmapDir |
Returns the directory in which all built-in colour map files are stored. |
getLutDir |
Returns the directory in which all built-in lookup table files are stored. |
scanBuiltInCmaps |
Returns a list of IDs for all built-in colour maps. |
scanBuiltInLuts |
Returns a list of IDs for all built-in lookup tables. |
scanUserAddedCmaps |
Returns a list of IDs for all user-added colour maps. |
scanUserAddedLuts |
Returns a list of IDs for all user-added lookup tables. |
makeValidMapKey |
Turns the given string into a valid key for use as a colour map or lookup table identifier. |
isValidMapKey |
Returns True if the given string is a valid key for use as a colour map or lookup table identifier, False otherwise. |
The following functions may be used for calculating the relationship between a data display range and brightness/contrast scales, and generating/manipulating colours:
displayRangeToBricon |
Converts the given brightness/contrast values to a display range, given the data range. |
briconToDisplayRange |
Converts the given brightness/contrast values to a display range, given the data range. |
applyBricon |
Applies the given brightness and contrast levels to the given rgb colour(s). |
randomColour |
Generates a random RGB colour. |
randomBrightColour |
Generates a random saturated RGB colour. |
randomDarkColour |
Generates a random saturated and darkened RGB colour. |
complementaryColour |
Generate a colour which can be used as a complement/opposite to the given colour. |
-
fsleyes.colourmaps.
getCmapDir
()¶ Returns the directory in which all built-in colour map files are stored.
-
fsleyes.colourmaps.
getLutDir
()¶ Returns the directory in which all built-in lookup table files are stored.
-
fsleyes.colourmaps.
_walk
(dirname, suffix)¶ Recursively searches
dirname
, returning a list of all files with the specifiedsuffix
.
-
fsleyes.colourmaps.
_find
(mapid, dirname)¶ Finds the file associated with the given (built-in) colour map or lookup table ID.
-
fsleyes.colourmaps.
scanBuiltInCmaps
()¶ Returns a list of IDs for all built-in colour maps.
-
fsleyes.colourmaps.
scanBuiltInLuts
()¶ Returns a list of IDs for all built-in lookup tables.
-
fsleyes.colourmaps.
scanUserAddedCmaps
()¶ Returns a list of IDs for all user-added colour maps.
-
fsleyes.colourmaps.
scanUserAddedLuts
()¶ Returns a list of IDs for all user-added lookup tables.
-
fsleyes.colourmaps.
makeValidMapKey
(name)¶ Turns the given string into a valid key for use as a colour map or lookup table identifier.
-
fsleyes.colourmaps.
isValidMapKey
(key)¶ Returns
True
if the given string is a valid key for use as a colour map or lookup table identifier,False
otherwise. A valid key comprises lower case letters, numbers, underscores and hyphens.
-
fsleyes.colourmaps.
scanColourMaps
()¶ Scans the colour maps directories, and returns a list containing the names of all colour maps contained within. This function may be called before
init()
.
-
fsleyes.colourmaps.
scanLookupTables
()¶ Scans the lookup tables directories, and returns a list containing the names of all lookup tables contained within. This function may be called before
init()
.
-
fsleyes.colourmaps.
_cmaps
= None¶ An
OrderedDict
which contains all registered colour maps as{key : _Map}
mappings.
-
fsleyes.colourmaps.
_luts
= None¶ An
OrderedDict
which contains all registered lookup tables as{key : _Map}
mappings.
-
fsleyes.colourmaps.
init
(force=False)¶ This function must be called before any of the other functions in this module can be used.
It initialises the colour map and lookup table registers, loading all built-in and user-added colour map and lookup table files that exist.
Parameters: force – Forces the registers to be re-initialised, even if they have already been initialised.
-
fsleyes.colourmaps.
registerColourMap
(cmapFile, overlayList=None, displayCtx=None, key=None, name=None)¶ Loads RGB data from the given file, and registers it as a
matplotlib
ListedColormap
instance.Note
If the
overlayList
anddisplayContext
arguments are provided, thecmap
property of allVolumeOpts
instances are updated to support the new colour map.Parameters: - cmapFile – Name of a file containing RGB values
- overlayList – A
OverlayList
instance which contains all overlays that are being displayed (can beNone
). - displayCtx – A
DisplayContext
instance describing how the overlays inoverlayList
are being displayed. Must be provided ifoverlayList
is provided. - key – Name to give the colour map. If
None
, defaults to the file name prefix. - name – Display name for the colour map. If
None
, defaults to thename
.
-
fsleyes.colourmaps.
registerLookupTable
(lut, overlayList=None, displayCtx=None, key=None, name=None)¶ Registers the given
LookupTable
instance (iflut
is a string, it is assumed to be the name of a.lut
file, which is loaded).Note
If the
overlayList
anddisplayContext
arguments are provided, thelut
property of allLabelOpts
instances are updated to support the new lookup table.Parameters: - lut – A
LookupTable
instance, or the name of a.lut
file. - overlayList – A
OverlayList
instance which contains all overlays that are being displayed (can beNone
). - displayCtx – A
DisplayContext
instance describing how the overlays inoverlayList
are being displayed. Must be provided ifoverlayList
is provided. - key – Name to give the lookup table. If
None
, defaults to the file name prefix. - name – Display name for the lookup table. If
None
, defaults to thename
.
- lut – A
-
fsleyes.colourmaps.
getLookupTables
()¶ Returns a list containing all available lookup tables.
-
fsleyes.colourmaps.
getLookupTable
(key)¶ Returns the
LookupTable
instance of the specified key/ID.
-
fsleyes.colourmaps.
getColourMaps
()¶ Returns a list containing the names of all available colour maps.
-
fsleyes.colourmaps.
getColourMap
(key)¶ Returns the colour map instance of the specified key.
-
fsleyes.colourmaps.
getColourMapLabel
(key)¶ Returns a label/display name for the specified colour map.
-
fsleyes.colourmaps.
getColourMapFile
(key)¶ Returns the file associated with the specified colour map, or
None
if the colour map is registered but not installed.
-
fsleyes.colourmaps.
getLookupTableFile
(key)¶ Returns the file associated with the specified lookup table, or
None
if the lookup table is registered but not installed.
-
fsleyes.colourmaps.
isColourMapRegistered
(key)¶ Returns
True
if the specified colourmap is registered,False
otherwise.
-
fsleyes.colourmaps.
isLookupTableRegistered
(key)¶ Returns
True
if the specified lookup table is registered,False
otherwise.
-
fsleyes.colourmaps.
isColourMapInstalled
(key)¶ Returns
True
if the specified colourmap is installed,False
otherwise. AKeyError
is raised if the colourmap is not registered.
-
fsleyes.colourmaps.
isLookupTableInstalled
(key)¶ Returns
True
if the specified loolup table is installed,False
otherwise. AKeyError
is raised if the lookup tabler is not registered.
-
fsleyes.colourmaps.
installColourMap
(key)¶ Attempts to install a previously registered colourmap into the
[settingsbase]/colourmaps/
directory.
-
fsleyes.colourmaps.
installLookupTable
(key)¶ Attempts to install/save a previously registered lookup table into the
[settingsbase]/luts
directory.
-
fsleyes.colourmaps.
_briconToScaleOffset
(brightness, contrast, drange)¶ Used by the
briconToDisplayRange()
and theapplyBricon()
functions.Calculates a scale and offset which can be used to transform a display range of the given size so that the given brightness/contrast settings are applied.
Parameters: - brightness – Brightness, between 0.0 and 1.0.
- contrast – Contrast, between 0.0 and 1.0.
- drange – Data range.
-
fsleyes.colourmaps.
briconToDisplayRange
(dataRange, brightness, contrast)¶ Converts the given brightness/contrast values to a display range, given the data range.
Parameters: - dataRange – The full range of the data being displayed, a (min, max) tuple.
- brightness – A brightness value between 0 and 1.
- contrast – A contrast value between 0 and 1.
-
fsleyes.colourmaps.
displayRangeToBricon
(dataRange, displayRange)¶ Converts the given brightness/contrast values to a display range, given the data range.
Parameters: - dataRange – The full range of the data being displayed, a (min, max) tuple.
- displayRange – A (min, max) tuple containing the display range.
-
fsleyes.colourmaps.
applyBricon
(rgb, brightness, contrast)¶ Applies the given
brightness
andcontrast
levels to the givenrgb
colour(s).Passing in
0.5
for both thebrightness
andcontrast
will result in the colour being returned unchanged.Parameters: - rgb – A sequence of three or four floating point numbers in
the range
[0, 1]
specifying an RGB(A) value, or anumpy
array of shape(n, 3)
or(n, 4)
specifyingn
colours. If alpha values are passed in, they are returned unchanged. - brightness – A brightness level in the range
[0, 1]
. - contrast – A contrast level in the range
[0, 1]
.
- rgb – A sequence of three or four floating point numbers in
the range
-
fsleyes.colourmaps.
randomColour
()¶ Generates a random RGB colour.
-
fsleyes.colourmaps.
randomBrightColour
()¶ Generates a random saturated RGB colour.
-
fsleyes.colourmaps.
randomDarkColour
()¶ Generates a random saturated and darkened RGB colour.
-
fsleyes.colourmaps.
complementaryColour
(rgb)¶ Generate a colour which can be used as a complement/opposite to the given colour.
If the given
rgb
sequence contains four values, the fourth value (e.g. alpha) is returned unchanged.
-
fsleyes.colourmaps.
_caseInsensitiveLookup
(d, k, default=None)¶ Performs a case-insensitive lookup on the dictionary
d
, with the keyk
.This function is used to allow case-insensitive retrieval of colour maps and lookup tables.
-
class
fsleyes.colourmaps.
_Map
(key, name, mapObj, mapFile, installed)¶ Bases:
object
A little class for storing details on registered colour maps and lookup tables. This class is only used internally.
-
__init__
(key, name, mapObj, mapFile, installed)¶ Create a
_Map
.Parameters: - key – The identifier name of the colour map/lookup table,
which must be passed to the
getColourMap()
andgetLookupTable()
functions to look up this map object. - name – The display name of the colour map/lookup table.
- mapObj – The colourmap/lut object, either a
matplotlib.colors..Colormap
, or aLookupTable
instance. - mapFile – The file from which this map was loaded,
or
None
if this cmap/lookup table only exists in memory, or is a built inmatplotlib
colourmap. - installed –
True
if this is a built inmatplotlib
colourmap or is installed in thefsleyes/colourmaps/
orfsleyes/luts/
directory,False
otherwise.
- key – The identifier name of the colour map/lookup table,
which must be passed to the
-
__str__
()¶ Returns a string representation of this
_Map
.
-
__repr__
()¶ Returns a string representation of this
_Map
.
-
__dict__
= mappingproxy({'__module__': 'fsleyes.colourmaps', '__doc__': 'A little class for storing details on registered colour maps and lookup\n tables. This class is only used internally.\n ', '__init__': <function _Map.__init__>, '__str__': <function _Map.__str__>, '__repr__': <function _Map.__repr__>, '__dict__': <attribute '__dict__' of '_Map' objects>, '__weakref__': <attribute '__weakref__' of '_Map' objects>})¶
-
__module__
= 'fsleyes.colourmaps'¶
-
__weakref__
¶ list of weak references to the object (if defined)
-
-
class
fsleyes.colourmaps.
LutLabel
(value, name=None, colour=None, enabled=None)¶ Bases:
__main__.MockClass
This class represents a mapping from a value to a colour and name.
LutLabel
instances are created and managed byLookupTable
instances.Listeners may be registered on the
name
,colour
, andenabled
properties to be notified when they change.-
__init__
(value, name=None, colour=None, enabled=None)¶ Create a
LutLabel
.Parameters: - value – The label value.
- name – The label name.
- colour – The label colour.
- enabled – Whether the label is enabled/disabled.
-
name
= <MagicMock name='mock.String()' id='139845843558864'>¶ The display name for this label. Internally (for comparison), the
internalName()
is used, which is simply this name, converted to lower case.
-
colour
= <MagicMock name='mock.Colour()' id='139845842273280'>¶ The colour for this label.
-
enabled
= <MagicMock name='mock.Boolean()' id='139845844115072'>¶ Whether this label is currently enabled or disabled.
-
value
¶ Returns the value of this
LutLabel
.
-
internalName
¶ Returns the internal name of this
LutLabel
, which is just itsname
, converted to lower-case. This is used by__eq__()
and__hash__()
, and by theLookupTable
class.
-
__eq__
(other)¶ Equality operator - returns
True
if thisLutLabel
has the same value as the given one.
-
__lt__
(other)¶ Less-than operator - compares two
LutLabel
instances based on their value.
-
__hash__
()¶ The hash of a
LutLabel
is a combination of its value, name, and colour, but not its enabled state.
-
__str__
()¶ Returns a string representation of this
LutLabel
.
-
__repr__
()¶ Returns a string representation of this
LutLabel
.
-
__module__
= 'fsleyes.colourmaps'¶
-
-
class
fsleyes.colourmaps.
LookupTable
(key, name, lutFile=None)¶ Bases:
__main__.MockClass
A
LookupTable
encapsulates a list of label values and associated colours and names, defining a lookup table to be used for colouring label images.A label value typically corresponds to an anatomical region (as in e.g. atlas images), or a classification (as in e.g. white/grey matter/csf segmentations).
The label values, and their associated names/colours, in a
LookupTable
are stored inLutLabel
instances, ordered by their value in ascending order. These are accessible by label value via theget()
method, by index, by directly indexing theLookupTable
instance, or by name, via thegetByName()
method. New label values can be added via theinsert()
andnew()
methods. Label values can be removed via the meth:delete method.Notifications
The
LookupTable
class implements theNotifier
interface. If you need to be notified when aLookupTable
changes, you may register to be notified on the following topics:Topic Meaning label
The properties of a LutLabel
have changed.saved
The saved state of this LookupTable
has changed.added
A new LutLabel
has been added.removed
A LutLabel
has been removed.-
__init__
(key, name, lutFile=None)¶ Create a
LookupTable
.Parameters: - key – The identifier for this
LookupTable
. Must be a valid key (seeisValidMapKey()
). - name – The display name for this
LookupTable
. - lutFile – A file to load lookup table label values, names, and
colours from. If
None
, thisLookupTable
will be empty - labels can be added with thenew()
orinsert()
methods.
- key – The identifier for this
-
lazyparse
()¶ Decorator which is used to lazy-parse the LUT file only when it is first needed.
-
__str__
()¶ Returns the name of this
LookupTable
.
-
__repr__
()¶ Returns the name of this
LookupTable
.
-
__len__
(*args, **kwargs)¶
-
__getitem__
(*args, **kwargs)¶
-
max
(*args, **kwargs)¶
-
saved
¶ Returns
True
if thisLookupTable
is registered and saved,False
if it is not registered, or has been modified.
-
index
(*args, **kwargs)¶
-
_LookupTable__labelChanged
(value, valid, label, propName)¶ Called when the properties of any
LutLabel
change. Triggers notification on thelabel
topic.
-
_LookupTable__load
(lutFile)¶ Called by
__init__()
. Loads aLookupTable
specification from the given file.
-
_LookupTable__parse
(lut, names)¶ Parses
lut
, a numpy array containing a LUT.
-
__module__
= 'fsleyes.colourmaps'¶
-
labels
(*args, **kwargs)¶
-
get
(*args, **kwargs)¶
-
getByName
(*args, **kwargs)¶
-
new
(*args, **kwargs)¶
-
insert
(*args, **kwargs)¶
-
delete
(*args, **kwargs)¶
-
save
(*args, **kwargs)¶
-