PerceptualColormap

class PerceptualColormap(*args, space=None, clip=True, gamma=None, gamma1=None, gamma2=None, **kwargs)[source]

Bases: ContinuousColormap

A ContinuousColormap with linear transitions across hue, saturation, and luminance rather than red, blue, and green.

Parameters:

  • segmentdata (dict-like) – Dictionary containing the keys 'hue', 'saturation', 'luminance', and (optionally) 'alpha'. The key 'chroma' is treated as a synonym for 'saturation'. The shorthands 'h', 's', 'l', 'a', and 'c' are also acceptable. The key values can be callable functions that return channel values given a colormap index, or 3-column arrays indicating the coordinates and channel transitions. See LinearSegmentedColormap for a more detailed explanation.

  • name (str, default: '_no_name') – The colormap name. This can also be passed as the first positional string argument.

  • N (int, default: rc['image.lut'] = 256) – Number of points in the colormap lookup table.

  • space ({'hsl', 'hpl', 'hcl', 'hsv'}, optional) – The hue, saturation, luminance-style colorspace to use for interpreting the channels. See this page for a full description.

  • clip (bool, optional) – Whether to “clip” impossible colors (i.e. truncate HCL colors with RGB channels with values greater than 1) or mask them out as gray.

  • gamma (float, optional) – Set gamma1 and gamma2 to this identical value.

  • gamma1 (float, optional) – If greater than 1, make low saturation colors more prominent. If less than 1, make high saturation colors more prominent. Similar to the HCLWizard option.

  • gamma2 (float, optional) – If greater than 1, make high luminance colors more prominent. If less than 1, make low luminance colors more prominent. Similar to the HCLWizard option.

  • alpha (float, optional) – The opacity for the entire colormap. This overrides the input opacities.

  • cyclic (bool, optional) – Whether the colormap is cyclic. If True, this changes how the leftmost and rightmost color levels are selected, and extend can only be 'neither' (a warning will be issued otherwise).

Other Parameters:

**kwargs – Passed to matploitlib.colors.LinearSegmentedColormap.

Example

The below example generates a PerceptualColormap from a segmentdata dictionary that uses color names for the hue data, instead of channel values between 0 and 360.

>>> import ultraplot as uplt
>>> data = {
>>>     'h': [[0, 'red', 'red'], [1, 'blue', 'blue']],
>>>     's': [[0, 100, 100], [1, 100, 100]],
>>>     'l': [[0, 100, 100], [1, 20, 20]],
>>> }
>>> cmap = uplt.PerceptualColormap(data)

See also

ContinuousColormap, ultraplot.constructor.Colormap

Methods Summary

copy([name, segmentdata, N, alpha, gamma, ...])

Return a new colormap with relevant properties copied from this one if they were not provided as keyword arguments.

from_color(*args, **kwargs)

Return a simple monochromatic "sequential" colormap that blends from white or near-white to the input color.

from_hsl(*args, **kwargs)

Make a PerceptualColormap by specifying the hue, saturation, and luminance transitions individually.

from_list(*args[, adjust_grays])

Make a PerceptualColormap from a sequence of colors.

set_gamma([gamma, gamma1, gamma2])

Set the gamma value(s) for the luminance and saturation transitions.

to_continuous([name])

Convert the PerceptualColormap to a standard ContinuousColormap.

to_linear_segmented(*[, new_obj, message])

Methods Documentation

copy(name=None, segmentdata=None, N=None, *, alpha=None, gamma=None, cyclic=None, clip=None, gamma1=None, gamma2=None, space=None)[source]

Return a new colormap with relevant properties copied from this one if they were not provided as keyword arguments.

Parameters:

  • name (str, default: '_name_copy') – The new colormap name.

  • segmentdata, N, alpha, clip, cyclic, gamma, gamma1, gamma2, space (optional) – See PerceptualColormap. If not provided, these are copied from the current colormap.

See also

DiscreteColormap.copy, ContinuousColormap.copy

classmethod from_color(*args, **kwargs)[source]

Return a simple monochromatic “sequential” colormap that blends from white or near-white to the input color.

Parameters:

  • color (color-spec) – RGB tuple, hex string, or named color string.

  • name (str, default: '_no_name') – The colormap name. This can also be passed as the first positional string argument.

  • space ({'hsl', 'hpl', 'hcl', 'hsv'}, optional) – The hue, saturation, luminance-style colorspace to use for interpreting the channels. See this page for a full description.

  • l, s, a, c – Shorthands for luminance, saturation, alpha, and chroma.

  • luminance (float or color-spec, default: 100) – If float, this is the luminance channel strength on the left-hand side of the colormap. If RGB[A] tuple, hex string, or named color string, the luminance is inferred from the color.

  • saturation, alpha (float or color-spec, optional) – As with luminance, except the default saturation and the default alpha are the channel values taken from color.

  • chroma – Alias for saturation.

Other Parameters:

**kwargs – Passed to PerceptualColormap.from_hsl.

Returns:

PerceptualColormap – The colormap.

See also

PerceptualColormap.from_hsl, PerceptualColormap.from_list

classmethod from_hsl(*args, **kwargs)[source]

Make a PerceptualColormap by specifying the hue, saturation, and luminance transitions individually.

Parameters:

  • space ({'hsl', 'hpl', 'hcl', 'hsv'}, optional) – The hue, saturation, luminance-style colorspace to use for interpreting the channels. See this page for a full description.

  • name (str, default: '_no_name') – The colormap name. This can also be passed as the first positional string argument.

  • ratios (sequence of float, optional) – Relative extents of each color transition. Must have length len(colors) - 1. Larger numbers indicate a slower transition, smaller numbers indicate a faster transition. For example, luminance=(100, 50, 0) with ratios=(2, 1) results in a colormap with the transition from luminance 100 to 50 taking twice as long as the transition from luminance 50 to 0.

  • h, s, l, a, c – Shorthands for hue, saturation, luminance, alpha, and chroma.

  • hue (float or color-spec or sequence, default: 0) – Hue channel value or sequence of values. The shorthand keyword h is also acceptable. Values can be any of the following.

    1. Numbers, within the range 0 to 360 for hue and 0 to 100 for saturation and luminance.

    2. Color string names or hex strings, in which case the channel value for that color is looked up.

  • saturation (float or color-spec or sequence, default: 50) – As with hue, but for the saturation channel.

  • luminance (float or color-spec or sequence, default: :py:class:`(100`, :py:class:`20)`) – As with hue, but for the luminance channel.

  • alpha (float or color-spec or sequence, default: 1) – As with hue, but for the alpha (opacity) channel.

  • chroma – Alias for saturation.

Other Parameters:

**kwargs – Passed to PerceptualColormap.

Returns:

PerceptualColormap – The colormap.

See also

PerceptualColormap.from_color, PerceptualColormap.from_list

classmethod from_list(*args, adjust_grays=True, **kwargs)[source]

Make a PerceptualColormap from a sequence of colors.

Parameters:

  • colors (sequence of color-spec or tuple) – If a sequence of RGB[A] tuples or color strings, the colormap transitions evenly from colors[0] at the left-hand side to colors[-1] at the right-hand side.

    If a sequence of (float, color-spec) tuples, the float values are the coordinate of each transition and must range from 0 to 1. This can be used to divide the colormap range unevenly.

  • name (str, default: '_no_name') – The colormap name. This can also be passed as the first positional string argument.

  • ratios (sequence of float, optional) – Relative extents of each color transition. Must have length len(colors) - 1. Larger numbers indicate a slower transition, smaller numbers indicate a faster transition. For example, ('red', 'blue', 'green') with ratios=(2, 1) creates a colormap with the transition from red to blue taking twice as long as the transition from blue to green.

  • adjust_grays (bool, optional) – Whether to adjust the hues of grayscale colors (including 'white', 'black', and the 'grayN' open-color colors) to the hues of the preceding and subsequent colors in the sequence. This facilitates the construction of diverging colormaps with monochromatic segments using e.g. PerceptualColormap.from_list(['blue', 'white', 'red']).

Other Parameters:

**kwargs – Passed to PerceptualColormap.

Returns:

PerceptualColormap – The colormap.

See also

matplotlib.colors.LinearSegmentedColormap.from_list, ContinuousColormap.from_list, PerceptualColormap.from_color, PerceptualColormap.from_hsl

set_gamma(gamma=None, gamma1=None, gamma2=None)[source]

Set the gamma value(s) for the luminance and saturation transitions.

Parameters:

  • gamma (float, optional) – Set gamma1 and gamma2 to this identical value.

  • gamma1 (float, optional) – If greater than 1, make low saturation colors more prominent. If less than 1, make high saturation colors more prominent. Similar to the HCLWizard option.

  • gamma2 (float, optional) – If greater than 1, make high luminance colors more prominent. If less than 1, make low luminance colors more prominent. Similar to the HCLWizard option.

to_continuous(name=None, **kwargs)[source]

Convert the PerceptualColormap to a standard ContinuousColormap. This is used to merge such colormaps.

Parameters:

name (str, default: '_name_copy') – The new colormap name.

Other Parameters:

**kwargs – Passed to ContinuousColormap.

See also

ContinuousColormap.to_discrete

to_linear_segmented(*, new_obj=<function PerceptualColormap.to_continuous>, message="'to_linear_segmented' was deprecated in version 0.8.0 and may be removed in the next major release (version 2.0.0). Please use 'to_continuous' instead.", **kwargs)