Color Manipulation and Utilities¶

Overview¶

The colorspace package provides several color manipulation utilities that are useful for creating, assessing, or transforming color palettes, namely:

desaturate(): Desaturate colors by chroma removal in HCL space.
darken() and lighten(): Algorithmically lighten or darken colors in HCL and/or HLS space.
adjust_transparency() and extract_transparency(): Remove, adjust, and extract the transparency.
contrast_ratio(): Computing and visualizing W3C contrast ratios of colors.
max_chroma(): Compute maximum chroma for given hue and luminance in HCL space.

Desaturation in HCL space¶

Desaturation should map a given color to the gray with the same “brightness”. In principle, any perceptually-based color model (HCL, HLS, HSV, …) could be employed for this but HCL works particularly well because its coordinates capture the perceptual properties better than most other color models.

The desaturate() function converts any given hex color code to the corresponding HCL coordinates and sets the chroma to zero. Thus, only the luminance matters which captures the “brightness” mentioned above. Finally, the resulting HCL coordinates are transformed back to hex color codes.

For illustration, a few simple examples are presented below. More examples in the context of palettes for statistical graphics are discussed along with the color vision deficiency article.

In [1]: from colorspace import rainbow, desaturate

In [2]: rainbow().colors(3)
Out[2]: ['#FF0000', '#00FF00', '#0000FF']

In [3]: desaturate(rainbow().colors(3))
Out[3]: ['#7F7F7F', '#DCDCDC', '#4C4C4C']

# Allows for `colorspace.palettes.palette` objects and cmaps
In [4]: from colorspace import palette

In [5]: pal = palette(rainbow()(4), name = "custom palette")

In [6]: desaturate(pal)
Out[6]: ['#7F7F7F', '#E2E2E2', '#E5E5E5', '#606060']

In [7]: desaturate(pal.cmap())   # Returns cmap
Out[7]: <matplotlib.colors.LinearSegmentedColormap at 0x7f5e7d375330>

Even this simple example suffices to show that the three RGB rainbow colors have very different grayscale levels. This deficiency is even clearer when using a full color wheel (of colors with hues in [0, 360] degrees). While the RGB rainbow() is very unbalanced the HCL rainbow_hcl() (or also qualitative_hcl()) is (by design) balanced with respect to luminance.

In [8]: from matplotlib import pyplot as plt

In [9]: from colorspace import rainbow, rainbow_hcl, desaturate

In [10]: from numpy import repeat

In [11]: def wheel(ax, col): ax.pie(repeat(1, len(col)), colors = col, labels = range(len(col)))

In [12]: col     = rainbow()(8)

In [13]: col_hcl = rainbow_hcl()(8)

In [14]: fig, axes = plt.subplots(2, 2, figsize = (8, 8))

In [15]: wheel(axes[0, 0], col)

In [16]: wheel(axes[0, 1], desaturate(col))

In [17]: wheel(axes[1, 0], col_hcl)

In [18]: wheel(axes[1, 1], desaturate(col_hcl))

In [19]: fig.tight_layout()

In [20]: fig.show()

Lighten and darken colors¶

In principle, a similar approach for lightening and darkening colors can be employed as for desaturation above. The colors can simply be transformed to HCL space and then the luminance can either be decreased (turning the color darker) or increased (turning it lighter) while preserving the hue and chroma coordinates.

This strategy typically works well for lightening colors, although in some situations the result can be rather colorful. Conversely, when darkening rather light colors with little chroma, this can result in rather gray colors.

In these situations, an alternative might be to apply the analogous strategy in HLS space which is frequently used in HTML style sheets. However, this strategy may also yield colors that are either too gray or too colorful. A compromise that sometimes works well is to adjust the luminance coordinate in HCL space but to take the chroma coordinate corresponding to the HLS transformation.

We have found that typically the HCL-based transformation performs best for lightening colors and this is hence the default in lighten(). For darkening colors, the combined strategy often works best and is hence the default in darken(). In either case it is recommended to try the other available strategies in case the default yields unexpected results.

Regardless of the chosen color space, the adjustment of the L component can occur by two methods, relative (the default) and absolute. For example L - 100 * amount is used for absolute darkening, or L * (1 - amount) for relative darkening. See lighten() and darken() for more details.

For illustration a qualitative palette (Okabe-Ito) is transformed by two levels of both lightening and darkening, respectively.

In [21]: from colorspace import palette, swatchplot, lighten, darken

In [22]: oi = ["#61A9D9", "#ADD668", "#E6D152", "#CE6BAF", "#797CBA"]

In [23]: swatchplot([palette(lighten(oi, 0.4), "-40%"),
   ....:             palette(lighten(oi, 0.2), "-20%"),
   ....:             palette(oi, "0%"),
   ....:             palette(darken(oi, 0.2), "+20%"),
   ....:             palette(darken(oi, 0.4), "+40%")])
   ....: 
Out[23]: <Figure size 640x480 with 1 Axes>

savefig/manipulation_utilities_okabeito.png

Adjust or extract the transparency of colors¶

Alpha transparency is useful for making colors semi-transparent, e.g., for overlaying different elements in graphics. An alpha value (or alpha channel) of 0 (or 00 in hex strings) corresponds to fully transparent and an alpha value of 1 (or FF in hex strings) corresponds to fully opaque. If a color hex string does not provide an explicit alpha transparency, the color is assumed to be fully opaque.

Currently the package only allows to manipulate the transparency of objects inheriting from colorlib.colorobject (see Color Spaces: Classes and Utilities).

The adjust_transparency() function can be used to adjust the alpha transparency of a set of colors. It always returns a hex color specification. This hex color can have the alpha transparency added/removed/modified depending on the specification of the argument alpha. The function returns an object of the same class as provided on x with (possibly) adjusted transparency.

None: If alpha = None existing transparency will be removed (if any exists).
Constant: In case a single float or integer (\(\in [0., 1.]\)) is provided constant transparency will be added to all colors on x.
List or numpy ndarray: If a list or numpy.ndarray is provided the length of the object must match the number of colors of the object provided on x. All elements of the list/array must be convertable to float and must be in \(\in [0., 1.]\).

For illustration, the transparency of a single black color is modified to three alpha levels: fully transparent, semi-transparent, and fully opaque, respectively. Black can be equivalently specified by name ("black"), hex string ("#000000"), or integer position in the standard palette ("0").

In [24]: from colorspace.colorlib import hexcols

In [25]: from colorspace import adjust_transparency

In [26]: cols = hexcols(["black", "#000000", "0"])

In [27]: print(cols)
hexcols color object (3 colors)
        hex_
  1:b'#000000'
    b'#000000'
    b'#000000'

In [28]: print(cols.colors())
['#000000', '#000000', '#000000']

In [29]: cols = adjust_transparency(cols, [0.0, 0.5, 1.0])

In [30]: print(cols)
hexcols color object (3 colors)
        hex_   alpha
  1:b'#000000'    00
    b'#000000'    7F
    b'#000000'    FF

In [31]: print(cols.colors())
['#00000000', '#00000050', '#000000']

Subsequently we can set a constant transparency for all colors by providing one single value, or remove transparency information by setting alpha = None. Given the same object as above:

In [32]: from colorspace import extract_transparency

In [33]: cols = adjust_transparency(cols, 0.8)   # Set to constant

In [34]: print(cols)
hexcols color object (3 colors)
        hex_   alpha
  1:b'#000000'    CC
    b'#000000'    CC
    b'#000000'    CC

In [35]: cols = adjust_transparency(cols, None)  # Remove transparency

In [36]: print(cols)
hexcols color object (3 colors)
        hex_
  1:b'#000000'
    b'#000000'
    b'#000000'

The extract_transparency() function can be used to extract the alpha transparency from a set of colors. It allows to define the mode of the return value. This can either be "float" (\(\in [0., 1.]\)), "int" (\(0, 1, ..., 255\)), or "str" ("00", "01", …, "FF"). In case no transparency is defined at all, None will be returned.

For illustration we extract the transparency from the gray colors in x in different formats.

In [37]: from colorspace.colorlib import hexcols

# Some colors with transparency 80%, 40%, 80%
In [38]: x = hexcols(['#023FA5CC', '#E2E2E266', '#8E063BCC'])

In [39]: extract_transparency(x, mode = "float")
Out[39]: array([0.8, 0.4, 0.8])

In [40]: extract_transparency(x, mode = "int")
Out[40]: array([204, 102, 204], dtype=int16)

In [41]: extract_transparency(x, mode = "str")
Out[41]: array(['CC', '66', 'CC'], dtype='<U2')

Compute and visualize W3C contrast ratios¶

The Web Content Accessibility Guidelines (WCAG) by the World Wide Web Consortium (W3C) recommend a contrast ratio of at least 4.5 for the color of regular text on the background color, and a ratio of at least 3 for large text. See . This relies on a specific definition of relative luminances (essentially based on power-transformed sRGB coordinates) that is different from the perceptual luminance as defined, for example, in the HCL color model. Note also that the WCAG pertain to text and background color and not to colors used in data visualization.

For illustration we compute and visualize the contrast ratios of the default palette in R compared to a white background.

In [42]: from colorspace import rainbow, contrast_ratio

In [43]: cols = rainbow().colors(7)

In [44]: contrast_ratio(cols, "#FFFFFF") # Against white
Out[44]: 
array([3.99847677, 1.36500073, 1.34725121, 1.33595736, 3.20339072,
       7.69994138, 3.34666975])

In [45]: contrast_ratio(cols, "#000000") # Against black
Out[45]: 
array([ 5.252     , 15.38460716, 15.58729349, 15.71906457,  6.55555374,
        2.72729349,  6.27489463])

In [46]: contrast_ratio(cols, plot = True)
Out[46]: 
array([3.99847677, 1.36500073, 1.34725121, 1.33595736, 3.20339072,
       7.69994138, 3.34666975])

savefig/manipulation_utilities_contrast_ratio.png

Maximum chroma for given hue and luminance¶

As the possible combinations of chroma and luminance in HCL space depend on hue, it is not obvious which trajectories through HCL space are possible prior to trying a specific HCL coordinate by calling polarLUV(). <colorspace.colorlib.polarLUV>. To avoid having to fix up the color upon conversion to RGB hex color codes, the max_chroma() function computes (approximately) the maximum chroma possible.

For illustration we show that for given luminance (here: L = 50) the maximum chroma varies substantially with hue:

In [47]: from colorspace import max_chroma

In [48]: from numpy import linspace

In [49]: max_chroma(linspace(0, 360, 7), L = 50)
Out[49]: array([137.96,  59.99,  69.06,  39.81,  65.45, 119.54, 137.96])

Similarly, maximum chroma also varies substantially across luminance values for a given hue (here: H = 120, green):

In [50]: from colorspace import max_chroma

In [51]: from numpy import linspace

In [52]: max_chroma(H = 120, L = linspace(0, 100, 6))
Out[52]: array([  0.  ,  28.04,  55.35,  82.79, 110.28,   0.  ])

In the plots below more combinations are visualized: In the left panel for maximum chroma across hues given luminance and in the right panel with increasing luminance given hue.

(Source code, png, hires.png, pdf)