colorspace (version 2.1-1)

desaturate: Desaturate Colors by Chroma Removal in HCL Space

Description

Transform a vector of given colors to the corresponding colors with chroma reduced (by a tunable amount) in HCL space.

Usage

desaturate(col, amount = 1, ...)

Value

A color object as specified in the input col (hexadecimal string, RGB matrix, or formal color class) with desaturated colors.

Arguments

col

vector of R colors. Can be any of the three kinds of R colors, i.e., either a color name (an element of colors), a hexadecimal (hex) string of the form "#rrggbb" or "#rrggbbaa" (see rgb), or an integer i meaning palette()[i]. Additionally, col can be a formal color-class object or a matrix with three named rows (or columns) containing R/G/B (0-255) values.

amount

numeric specifying the amount of desaturation where 1 corresponds to complete desaturation, 0 to no desaturation, and values in between to partial desaturation.

...

additional arguments. If severity is specified it will overrule the input argument amount (for convenience).

Details

If input col is a vector given colors are first transformed to RGB (either using hex2RGB or col2rgb) and then to HCL (polarLUV). In HCL, chroma is reduced and then the color is transformed back to a hexadecimal string.

If input col is a matrix with three rows named R, G, and B (top down) they are interpreted as Red-Green-Blue values within the range [0-255]. The desaturation takes place in the HCL space as well. Instead of an (s)RGB color vector a matrix of the same size as the input col with desaturated Red-Green-Blue values will be returned. This can be handy to avoid too many conversions.

Similarly, col can be a formal color-class object, in which case the desaturated colors are returned as a formal object of the same class as the input.

References

Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2020). “colorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1--49. tools:::Rd_expr_doi("10.18637/jss.v096.i01")

See Also

polarLUV, hex, lighten

Examples

## rainbow of colors and their desaturated counterparts
rainbow_hcl(12)
desaturate(rainbow_hcl(12))

## convenience demo function
wheel <- function(col, radius = 1, ...)
  pie(rep(1, length(col)), col = col, radius = radius, ...) 

## compare base and colorspace palettes
## (in color and desaturated)
par(mar = rep(0, 4), mfrow = c(2, 2))
## rainbow color wheel
wheel(rainbow_hcl(12))
wheel(rainbow(12))
wheel(desaturate(rainbow_hcl(12)))
wheel(desaturate(rainbow(12)))

## apply desaturation directly on wide RGB matrix (with R/G/B channels in rows)
RGB <- diag(3) * 255
rownames(RGB) <- c("R", "G", "B")
desaturate(RGB)