Diverging HCL Color Palettes

Description

The HCL (hue-chroma-luminance) color model is a perceptual color model obtained by using polar coordinates in CIELUV space (i.e., polarLUV), where steps of equal size correspond to approximately equal perceptual changes in color. By taking polar coordinates the resulting three dimensions capture the three perceptual axes very well: hue is the type of color, chroma the colorfulness compared to the corresponding gray, and luminance the brightness. This makes it relatively easy to create balanced palettes through trajectories in this HCL space. In contrast, in the more commonly-used ‘HSV’ (hue-saturation-value) model (a simple transformation of ‘RGB’), the three axes are confounded so that luminance changes along with the hue leading to very unbalanced palettes.

diverging_hcl codes the underlying numeric values by a triangular luminance sequence with different hues in the left and in the right arm of the palette. Thus, it can be seen as a combination of two sequential palettes with some restrictions: (a) a single hue is used for each arm of the palette, (b) chroma and luminance trajectory are balanced between the two arms, (c) the neutral central value has zero chroma. To specify such a palette a vector of two hues h (or equivalently h1 and h2), either a single chroma value c (or c1) or a vector of two chroma values c (or c1 and cmax), a vector of two luminances l (or l1 and l2), and power parameter(s) power (or p1 and p2) are used. For more flexible diverging palettes without the restrictrictions above (and consequently more parameters) divergingx_hcl is available. For backward compatibility, diverge_hcl is a copy of diverging_hcl.

If h is str it will overwrite the palette argument. In this case, pre-specified palette settings will be loaded but are allowed to be overwritten by the user. At any time the user can overwrite any of the settings. By default, diverging_hcl returns an object of class hclpalette identical to the pre-defined "Blue-Red" palette.

Usage

diverging_hcl(h=[260, 0], c=80, l=[30, 90],
              power=1.5, fixup=True, palette=None,
              rev=False, *args, **kwargs)

Arguments

hlist, float, int: Hue values (color), diverging color palettes should have different hues for both ends of the palette. If only one value is present it will be recycled ending up in a diverging color palette with the same colors on both ends. If more than two values are provided the first two will be used while the rest is ignored. If input h is a str this argument acts like the palette argument (see palette input parameter).
cfloat, int, list: Chroma value (colorfullness), a single numeric value. If two values are provided the first will be taken as c1, the second as cmax.
lfloat, int, list: luminance values (lightness). The first value is for the two ends of the color palette, the second one for the neutral center point. If only one value is given this value will be recycled.
powerfloat, int, list: Power parameter for non-linear behaviour of the color palette.
fixupbool: Only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?
palettestr: Can be used to load a default diverging color palette specification. If the palette does not exist an exception will be raised. Else the settings of the palette as defined will be used to create the color palette.
revbool: Should the color map be reversed.
*args: Currently unused.
**kwargs: Additional named arguments to overwrite the palette settings. Allowed: h1, h2, c1, cmax, l1, l2, p1, p2.

Return

Initialize new object, no return. Raises a set of errors if the parameters are misspecified. Note that the object is callable, the default object call can be used to return hex colors (identical to the .colors() method), see examples.

Methods

diverging_hcl.cmap(n=256, name='custom_hcl_cmap'): Create Matplotlib Compatible Color Map
diverging_hcl.colors(n=11, fixup=None, alpha=None, **kwargs): Get Colors
diverging_hcl.get(key): Get Specific Palette Setting
diverging_hcl.hclplot(n=7, **kwargs): Palette Plot in HCL Space
diverging_hcl.name(): Get Palette Name
diverging_hcl.show_settings(): Show Palette Settings
diverging_hcl.specplot(n=180, *args, **kwargs): Color Spectrum Plot
diverging_hcl.swatchplot(n=7, **kwargs): Palette Swatch Plot

Examples

from colorspace import diverging_hcl
a = diverging_hcl()
a.colors(10)

['#023FA5',
 '#6371AF',
 '#959CC3',
 '#BEC1D4',
 '#DBDCE0',
 '#E0DBDC',
 '#D6BCC0',
 '#C6909A',
 '#AE5A6D',
 '#8E063B']

# Different color palette by name
b = diverging_hcl("Tropic")
b.colors(10)

['#009B9F',
 '#00ADB1',
 '#6CC0C2',
 '#A7D3D5',
 '#D9E7E7',
 '#EDE1E8',
 '#E4C1D8',
 '#DBA1C8',
 '#D180B9',
 '#C75DAA']

b.swatchplot(show_names = False, figsize = (5.5, 0.5));

# The standard call of the object also returns hex colors
diverging_hcl("Tropic")(10)

['#009B9F',
 '#00ADB1',
 '#6CC0C2',
 '#A7D3D5',
 '#D9E7E7',
 '#EDE1E8',
 '#E4C1D8',
 '#DBA1C8',
 '#D180B9',
 '#C75DAA']