Sequential 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.

qualitative_hcl distinguishes the underlying categories by a sequence of hues while keeping both chroma and luminance constant to give each color in the resulting palette the same perceptual weight. Thus, h should be a pair of hues (or equivalently h1 and h2 can be used) with the starting and ending hue of the palette. Then, an equidistant sequence between these hues is employed, by default spanning the full color wheel (i.e, the full 360 degrees). Chroma c (or equivalently c1) and luminance l (or equivalently l1) are constants. 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, sequential_hcl returns an object of class hclpalette identical to the pre-defined "Blues 2" palette.

h1 and h2 both allow for lambda functions to create uniformly distributed hues around the (full) circle (360 degrees).

h1: can be a lambda function with one single argument n (number of colors).
h2: can be a lambda function with one or two arguments. If only one, n (number of colors) will be handed over when evaluated. If two, the first one is expected to be n (number of colors), as second argument the value h1 will be used.

Usage

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

Arguments

hfloat, int, list, str: Hue values (color). If only one value is given the value is recycled which yields a single-hue sequential color palette. If input h is a str this argument acts like the palette argument (see palette input parameter).
cfloat, int, list: Chroma values (colorfullness), int or float (linear to zero), list of two numerics (linear in interval), = or three numerics (advanced; [c1, cmax, c2]).
lfloat, int, list: Luminance values (luminance). If float or int, the element will be recycled, or a list of two numerics (defining [l1, l2]).
powerfloat, int, list: Power parameter for non-linear behaviour of the color palette. Single float or int, or a list of numerics (defining [p1, p2]).
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, c2, 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

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

Examples

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

['#023FA5',
 '#4359A7',
 '#6371AF',
 '#7D87B9',
 '#959CC3',
 '#ABB0CC',
 '#BEC1D4',
 '#CFD0DA',
 '#DBDCE0',
 '#E2E2E2']

# Different color palette by name
b = sequential_hcl("Peach")
b.colors(10)

['#EA4C3B',
 '#ED6343',
 '#F0764E',
 '#F3885B',
 '#F5996B',
 '#F7A87C',
 '#F8B78E',
 '#F9C5A0',
 '#FAD2B3',
 '#FADDC3']

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

# The standard call of the object also returns hex colors
sequential_hcl("Peach")(10)

['#EA4C3B',
 '#ED6343',
 '#F0764E',
 '#F3885B',
 '#F5996B',
 '#F7A87C',
 '#F8B78E',
 '#F9C5A0',
 '#FAD2B3',
 '#FADDC3']