Qualitative 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. 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, qualitative_hcl returns an object of class hclpalette which allows to draw a number of colors (n) uniformly distributed around the circle ([0, 360 * (n - 1) / n]) controlled via the h (Hue) argument. As the number of colors is not yet defined, the upper hue limit (h[1], h2) is defined via lambda function.

Usage

qualitative_hcl(h=[0, <function qualitative_hcl.<lambda>>],
                c=80, l=60, fixup=True,
                palette=None, rev=False, **kwargs)

Arguments

hlist, str: Hue values defining the ‘color’ or name of pre-defined palette (str) or a list of two numeric values (float/int) defining the hue on the two ends of the palette. If str, it acts as the input argument palette. Elements in list can also be lambda functions with one single input argument n (number of colors; see default value).
cint, float: Chroma value (colorfullness), a single numeric value.
lint, float: luminance value (lightness), a single numeric value.
fixupbool: Only used when converting the HCL colors to hex. Should RGB values outside the defined RGB color space be corrected?
paletteNone, str: Can be used to load a default diverging color qpalette 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 qthe color palette.
revbool: Should the color map be reversed? Default False.
**kwargs: Additional named arguments to overwrite the palette settings. Allowed: h1, h2, c1, l1.

Return

qualitative_hcl: Initialize new object. Raises exceptions 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

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

Examples

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

['#E16A86',
 '#CE7D3B',
 '#AA9000',
 '#6F9F00',
 '#00AA5A',
 '#00AD9A',
 '#00A6CA',
 '#5991E4',
 '#B675E0',
 '#DD64BE']

b = qualitative_hcl("Warm")
b.colors(10)

['#ABB065',
 '#B8AC65',
 '#C4A86A',
 '#CFA373',
 '#D79F7F',
 '#DE9B8C',
 '#E2979A',
 '#E495A8',
 '#E393B6',
 '#E093C3']

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

# The standard call of the object also returns hex colors
qualitative_hcl("Warm")(10)

['#ABB065',
 '#B8AC65',
 '#C4A86A',
 '#CFA373',
 '#D79F7F',
 '#DE9B8C',
 '#E2979A',
 '#E495A8',
 '#E393B6',
 '#E093C3']

# Example where `h` is a list of two lambda functions
from colorspace import hexcols
pal = qualitative_hcl([lambda n: 100. * (n - 1) / n,  
                       lambda n, h1: 300. * (n - 1) / n + h1], c = 30)
cols = hexcols(pal.colors(5))
cols

#979269
#6D9B7C
#5D9A9F
#898FB2
#AE84A4

cols.to("HCL")
cols

polarLUV color object (5 colors)
            H       C       L
  1:    79.95   30.27   60.03
       139.94   29.80   60.02
       199.99   29.96   59.83
       260.21   29.94   60.05
       319.54   29.66   60.05

Raises

TypeError: If h is neither str nor list of length 2.
TypeError: If h is list of length 2, the elements must be int, float, or lambda functions.
ValueError: If c and/or l contain unexpected values.
ValueError: If h is str or palette is set, but a pre-defined palette with this name does not exist.