colorspace (version 2.0-0)

adjust_transparency: Adjust Transparency of Colors

Description

Add, remove, or modify alpha transparency of a vector of colors.

Usage

adjust_transparency(col, alpha = TRUE)

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 rows containing R/G/B (0-255) values.

alpha

either a new numeric alpha transparency value or logical (to add/remove alpha) or NULL. See details.

Value

A character vector with hexadecimal color strings with alpha transparency corresponding to alpha argument.

Details

Alpha transparency is useful for making colors semi-transparent, e.g., for overlaying different elements in graphics. An alpha value 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 in R does not provide an explicit alpha transparency, the color is assumed to be fully opaque.

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 alpha:

• alpha = NULL: Returns a hex vector with alpha transparency only if needed. Thus, it keeps the alpha transparency for the colors (if any) but only if different from opaque.

• alpha = TRUE: Returns a hex vector with alpha transparency for all colors, using opaque (FF) as the default if missing.

• alpha = FALSE: Returns a hex vector without alpha transparency for all colors (even if the original colors had non-opaque alpha).

• alpha numeric: Returns a hex vector with alpha transparency for all colors set to the alpha argument (recycled if necessary).

References

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

See Also

rgb, desaturate, lighten

Examples

# NOT RUN {
## modify transparency of a color (in different formats)
adjust_transparency("black",   alpha = c(0, 0.5, 1)) ## name
adjust_transparency("#000000", alpha = c(0, 0.5, 1)) ## hex string
adjust_transparency(1,         alpha = c(0, 0.5, 1)) ## palette() integer

## three shades of gray (in different formats:
## name/opaque, hex/opaque, hex/semi-transparent)
x <- c("gray", "#BEBEBE", "#BEBEBE80")

## adjust transparency
adjust_transparency(x, alpha = NULL)  ## only if necessary
adjust_transparency(x, alpha = TRUE)  ## add
adjust_transparency(x, alpha = FALSE) ## remove
adjust_transparency(x, alpha = 0.8)   ## modify
# }