adjust_transparency.RdAdjust (i.e., add, remove, or modify) or extract alpha transparency of a vector of colors.
adjust_transparency(col, alpha = TRUE)
extract_transparency(col, mode = "numeric", default = 1)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.
either a new alpha transparency value or logical (to add/remove alpha)
or NULL. See details.
character specifying the output mode for the alpha transparency, can be
"numeric", "integer", "character" or "hexmode". See details.
vector of length 1 specifying the default alpha transparency that should be returned for colors that do not specify any explicitly (defaulting to fully opaque). Can either be numeric, integer, character, or hexmode.
For adjust_transparency character vector with hexadecimal color strings with alpha transparency
corresponding to alpha argument. For extract_transparency a vector of
alpha transparency values with the indicated mode.
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).
The extract_transparency function can be used to extract the alpha transparency
from a set of colors. It allows to specify the default value - that should be used
for colors without an explicit alpha transparency (defaulting to fully opaque) - and
mode of the return value. This can either be numeric (in [0, 1]), integer
(0L, 1L, ..., 255L), character (“00”, “01”, ..., “FF”),
or an object of class hexmode (internally represented as integer
with printing as character). The default can use any of these modes as well
(independent of the output mode) or be NA.
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. doi:10.18637/jss.v096.i01
## modify transparency of a color (in different formats)
adjust_transparency("black", alpha = c(0, 0.5, 1)) ## name
#> [1] "#00000000" "#00000080" "#000000FF"
adjust_transparency("#000000", alpha = c(0, 0.5, 1)) ## hex string
#> [1] "#00000000" "#00000080" "#000000FF"
adjust_transparency(1, alpha = c(0, 0.5, 1)) ## palette() integer
#> [1] "#00000000" "#00000080" "#000000FF"
## 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
#> [1] "#BEBEBE" "#BEBEBE" "#BEBEBE80"
adjust_transparency(x, alpha = TRUE) ## add
#> [1] "#BEBEBEFF" "#BEBEBEFF" "#BEBEBE80"
adjust_transparency(x, alpha = FALSE) ## remove
#> [1] "#BEBEBE" "#BEBEBE" "#BEBEBE"
adjust_transparency(x, alpha = 0.8) ## modify
#> [1] "#BEBEBECC" "#BEBEBECC" "#BEBEBECC"
## extract transparency in different formats
extract_transparency(x, mode = "numeric") ## default
#> [1] 1.0000000 1.0000000 0.5019608
extract_transparency(x, mode = "integer")
#> [1] 255 255 128
extract_transparency(x, mode = "character")
#> [1] "FF" "FF" "80"
extract_transparency(x, mode = "hexmode")
#> [1] "ff" "ff" "80"
## extract transparency with different default values
extract_transparency(x, default = NA)
#> [1] NA NA 0.5019608
extract_transparency(x, default = 0.5)
#> [1] 0.5000000 0.5000000 0.5019608
extract_transparency(x, default = 128L)
#> [1] 0.5019608 0.5019608 0.5019608
extract_transparency(x, default = "80", mode = "integer")
#> [1] 128 128 128