Skip to main content
`Ctrl`+`K`

# `colors`: Colors and colormap

This module provides API to manage colors.

DEFAULT_MIN_LIN = 0

  Default min value if in linear normalization

DEFAULT_MAX_LIN = 1

  Default max value if in linear normalization

ColorType = str | typing.Sequence[numbers.Real] | PyQt5.QtGui.QColor

  Type of `rgba()`’s color argument

RGBAColorType

  Type of `rgba()` return value

  alias of `Tuple`[`float`, `float`, `float`, `float`]

rgba(color, colorDict=None, colors=None)

  Convert different kind of color definition to a tuple (R, G, B, A) of floats.

  It supports: - color names: e.g., ‘green’ - color codes: ‘#RRGGBB’ and ‘#RRGGBBAA’ - indexed color names: e.g., ‘C0’ - RGB(A) sequence of uint8 in [0, 255] or float in [0, 1] - QColor

  Parameters:

    - color (`str` | `Sequence`[`Real`] | `QColor`) – The color to convert

    - colorDict (`dict`[`str`, `str`] | `None`) – A dictionary of color name conversion to color code

    - colors (`Sequence`[`str`] | `None`) – Sequence of colors to use for `

  Return type:

    `Tuple`[`float`, `float`, `float`, `float`]

  Returns:

    RGBA colors as floats in [0., 1.]

  Raises:

    ValueError – if the input is not a valid color

greyed(color, colorDict=None)

  Convert color code ‘#RRGGBB’ and ‘#RRGGBBAA’ to a grey color (R, G, B, A).

  It also supports RGB(A) from uint8 in [0, 255], float in [0, 1], and QColor as color argument.

  Parameters:

    - color (`str` | `Sequence`[`Real`] | `QColor`) – The color to convert

    - colorDict (`dict`[`str`, `str`] | `None`) – A dictionary of color name conversion to color code

  Return type:

    `Tuple`[`float`, `float`, `float`, `float`]

  Returns:

    RGBA colors as floats in [0., 1.]

asQColor(color)

  Convert color code ‘#RRGGBB’ and ‘#RRGGBBAA’ to a qt.QColor.

  It also supports RGB(A) from uint8 in [0, 255], float in [0, 1], and QColor as color argument.

  Parameters:

    color (`str` | `Sequence`[`Real`] | `QColor`) – The color to convert

  Return type:

    `QColor`

cursorColorForColormap(colormapName)

  Get a color suitable for overlay over a colormap.

  Parameters:

    colormapName (`str`) – The name of the colormap.

  Return type:

    `str`

  Returns:

    Name of the color.

class Colormap(name=None, colors=None, normalization='linear', vmin=None, vmax=None, autoscaleMode='minmax')

  Description of a colormap

  If no name nor colors are provided, a default gray LUT is used.

  Parameters:

    - name (`str` | `None`) – Name of the colormap

    - colors (`ndarray` | `None`) – optional, custom colormap. Nx3 or Nx4 numpy array of RGB(A) colors, either uint8 or float in [0, 1]. If ‘name’ is None, then this array is used as the colormap.

    - normalization (`str`) – Normalization: ‘linear’ (default) or ‘log’

    - vmin (`float` | `None`) – Lower bound of the colormap or None for autoscale (default)

    - vmax (`float` | `None`) – Upper bounds of the colormap or None for autoscale (default)

    - autoscaleMode (`str`)

  LINEAR = 'linear'

    constant for linear normalization

  LOGARITHM = 'log'

    constant for logarithmic normalization

  SQRT = 'sqrt'

    constant for square root normalization

  GAMMA = 'gamma'

    Constant for gamma correction normalization

  ARCSINH = 'arcsinh'

    constant for inverse hyperbolic sine normalization

  NORMALIZATIONS = ('linear', 'log', 'sqrt', 'gamma', 'arcsinh')

    Tuple of managed normalizations

  MINMAX = 'minmax'

    constant for autoscale using min/max data range

  STDDEV3 = 'stddev3'

    constant for autoscale using mean +/- 3*std(data) with a clamp on min/max of the data

  PERCENTILE_1_99 = 'percentile_1_99'

    constant for autoscale using 1st and 99th percentile of data

  AUTOSCALE_MODES = ('minmax', 'stddev3', 'percentile_1_99')

    Tuple of managed auto scale algorithms

  sigChanged

    Signal emitted when the colormap has changed.

  setFromColormap(other)

    Set this colormap using information from the other colormap.

    Parameters:

      other (`Colormap`) – Colormap to use as reference.

  getNColors(nbColors=None)

    Returns N colors computed by sampling the colormap regularly.

    Parameters:

      nbColors (`int` | `None`) – The number of colors in the returned array or None for the default value. The default value is the size of the colormap LUT.

    Return type:

      `ndarray`

    Returns:

      2D array of uint8 of shape (nbColors, 4)

  getName()

    Return the name of the colormap

    Return type:

      `str` | `None`

  setName(name)

    Set the name of the colormap to use.

    Parameters:

      name (`str`) – The name of the colormap. At least the following names are supported: ‘gray’, ‘reversed gray’, ‘temperature’, ‘red’, ‘green’, ‘blue’, ‘jet’, ‘viridis’, ‘magma’, ‘inferno’, ‘plasma’.

  getColormapLUT(copy=True)

    Return the list of colors for the colormap or None if not set.

    This returns None if the colormap was set with `setName()`. Use `getNColors()` to get the colormap LUT for any colormap.

    Parameters:

      copy (`bool`) – If true a copy of the numpy array is provided

    Return type:

      `ndarray` | `None`

    Returns:

      the list of colors for the colormap or None if not set

  setColormapLUT(colors)

    Set the colors of the colormap.

    Parameters:

      colors (`ndarray`) – the colors of the LUT. If float, it is converted from [0, 1] to uint8 range. Otherwise it is casted to uint8.

  getNaNColor()

    Returns the color to use for Not-A-Number floating point value.

    Return type:

      `QColor`

  setNaNColor(color)

    Set the color to use for Not-A-Number floating point value.

    Parameters:

      color (`str` | `Sequence`[`Real`] | `QColor`) – RGB(A) color to use for NaN values

  getNormalization()

    Return the normalization of the colormap.

    See `setNormalization()` for returned values.

    Return type:

      `str`

    Returns:

      the normalization of the colormap

  setNormalization(norm)

    Set the colormap normalization.

    Accepted normalizations: ‘log’, ‘linear’, ‘sqrt’

    Parameters:

      norm (`str`) – the norm to set

  setGammaNormalizationParameter(gamma)

    Set the gamma correction parameter.

    Only used for gamma correction normalization.

    Raises:

      ValueError – If gamma is not valid

    Parameters:

      gamma (`float`)

  getGammaNormalizationParameter()

    Returns the gamma correction parameter value.

    Return type:

      `float`

  getAutoscaleMode()

    Return the autoscale mode of the colormap (‘minmax’ or ‘stddev3’)

    Return type:

      `str`

  setAutoscaleMode(mode)

    Set the autoscale mode: either ‘minmax’ or ‘stddev3’

    Parameters:

      mode (`str`) – the mode to set

  isAutoscale()

    Return True if both min and max are in autoscale mode

    Return type:

      `bool`

  getVMin()

    Return the lower bound of the colormap

    Return type:

      `float` | `None`

    Returns:

      the lower bound of the colormap

  setVMin(vmin)

    Set the minimal value of the colormap

    Parameters:

      vmin (`float` | `None`) – Lower bound of the colormap or None for autoscale (initial value)

  getVMax()

    Return the upper bounds of the colormap or None

    Return type:

      `float` | `None`

    Returns:

      the upper bounds of the colormap or None

  setVMax(vmax)

    Set the maximal value of the colormap

    Parameters:

      vmax (`float` | `None`) – Upper bounds of the colormap or None for autoscale (initial value)

  isEditable()

    Return if the colormap is editable or not

    Return type:

      `bool`

    Returns:

      editable state of the colormap

  setEditable(editable)

    Set the editable state of the colormap

    Parameters:

      editable (`bool`) – is the colormap editable

  getColormapRange(data=None)

    Return (vmin, vmax) the range of the colormap for the given data or item.

    Parameters:

      data (`ndarray` | `_Colormappable` | `None`) – The data or item to use for autoscale bounds.

    Return type:

      `tuple`[`float`, `float`]

    Returns:

      (vmin, vmax) corresponding to the colormap applied to data if provided.

  getVRange()

    Get the bounds of the colormap

    Return type:

      `tuple`[`float` | `None`, `float` | `None`]

    Returns:

      A tuple of 2 values for min and max. Or None instead of float for autoscale

  setVRange(vmin, vmax)

    Set the bounds of the colormap

    Parameters:

      - vmin (`float` | `None`) – Lower bound of the colormap or None for autoscale (default)

      - vmax (`float` | `None`) – Upper bounds of the colormap or None for autoscale (default)

  copy()

    Return a copy of the Colormap.

    Return type:

      `Colormap`

  applyToData(data, reference=None)

    Apply the colormap to the data

    Parameters:

      - data (`ndarray` | `_Colormappable`) – The data to convert or the item for which to apply the colormap.

      - reference (`ndarray` | `_Colormappable` | `None`) – The data or item to use as reference to compute autoscale

    Return type:

      `ndarray`

  static getSupportedColormaps()

    Get the supported colormap names as a tuple of str.

    The list should at least contain and start by:

    > (‘gray’, ‘reversed gray’, ‘temperature’, ‘red’, ‘green’, ‘blue’, ‘viridis’, ‘magma’, ‘inferno’, ‘plasma’)

    Return type:

      `tuple`[`str`, `...`]

  restoreState(byteArray)

    Read the colormap state from a QByteArray.

    Parameters:

      byteArray (`QByteArray`) – Stream containing the state

    Return type:

      `bool`

    Returns:

      True if the restoration sussseed

  saveState()

    Save state of the colomap into a QDataStream.

    Return type:

      `QByteArray`

preferredColormaps()

  Returns the name of the preferred colormaps.

  This list is used by widgets allowing to change the colormap like the `ColormapDialog` as a subset of colormap choices.

  Return type:

    `tuple`[`str`, `...`]

setPreferredColormaps(colormaps)

  Set the list of preferred colormap names.

  Warning: If a colormap name is not available it will be removed from the list.

  Parameters:

    colormaps (`Iterable`[`str`]) – Not empty list of colormap names

  Raises:

    ValueError – if the list of available preferred colormaps is empty.

registerLUT(name, colors, cursor_color='black', preferred=True)

  Register a custom LUT to be used with Colormap objects.

  It can override existing LUT names.

  Parameters:

    - name (`str`) – Name of the LUT as defined to configure colormaps

    - colors (`ndarray`) – The custom LUT to register. Nx3 or Nx4 numpy array of RGB(A) colors, either uint8 or float in [0, 1].

    - preferred (`bool`) – If true, this LUT will be displayed as part of the preferred colormaps in dialogs.

    - cursor_color (`str`) – Color used to display overlay over images using colormap with this LUT.