PerceptualColormap

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

Bases: proplot.colors.ContinuousColormap, proplot.colors._Colormap

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, optional) – The colormap name. This can also be passed as the first positional string argument. Default is '_no_name'.

  • 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. Default is 'hsl'.

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

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

  • 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).

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

  • gamma1 (float, optional) – If >1, makes low saturation colors more prominent. If <1, makes high saturation colors more prominent. Similar to the HCLWizard option.

  • gamma2 (float, optional) – If >1, makes high luminance colors more prominent. If <1, makes low luminance colors more prominent. Similar to the HCLWizard option.

Other Parameters

**kwargs – Passed to ContinuousColormap.

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 proplot as pplt
>>> data = {
>>>     'h': [[0, 'red', 'red'], [1, 'blue', 'blue']],
>>>     's': [[0, 100, 100], [1, 100, 100]],
>>>     'l': [[0, 100, 100], [1, 20, 20]],
>>> }
>>> cmap = pplt.PerceptualColormap(data)

See also

ContinuousColormap, proplot.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])

Modify the gamma value(s) and refresh the lookup table.

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) – The name of the new colormap. Default is '_name_copy'.

  • 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, optional) – The colormap name. This can also be passed as the first positional string argument. Default is '_no_name'.

  • 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. Default is 'hsl'.

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

  • luminance (float or color-spec, optional) – If float, this is the luminance channel strength on the left-hand side of the colormap (default is 100). 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. Default is 'hsl'.

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

  • 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, optional) – 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.

    If scalar, the hue does not change across the colormap. Default is 0 (i.e., red).

  • saturation, luminance, alpha (float or color-spec or sequence, optional) – As with hue, but for the saturation, luminance, and alpha (opacity) channels, respectively. The default saturation is 50, luminance is (100, 20), and alpha is 1 (i.e., no transparency).

  • 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, optional) – The colormap name. This can also be passed as the first positional string argument. Default is '_no_name'.

  • 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]

Modify the gamma value(s) and refresh the lookup table.

Parameters

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

  • gamma1 (float, optional) – If >1, makes low saturation colors more prominent. If <1, makes high saturation colors more prominent. Similar to the HCLWizard option.

  • gamma2 (float, optional) – If >1, makes high luminance colors more prominent. If <1, makes 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, optional) – The name of the new colormap. Default is '_name_copy'.

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 and will be removed in a future release. Please use 'to_continuous' instead.", **kwargs)