Colorspace: a Toolbox for Manipulating and Assessing Colors and Palettes.” Journal of Statistical Software, 96(1), 1–49
Total Page:16
File Type:pdf, Size:1020Kb
Package ‘colorspace’ June 24, 2021 Version 2.0-2 Date 2021-06-24 Title A Toolbox for Manipulating and Assessing Colors and Palettes Description Carries out mapping between assorted color spaces including RGB, HSV, HLS, CIEXYZ, CIELUV, HCL (polar CIELUV), CIELAB, and polar CIELAB. Qualitative, sequential, and diverging color palettes based on HCL colors are provided along with corresponding ggplot2 color scales. Color palette choice is aided by an interactive app (with either a Tcl/Tk or a shiny graphical user interface) and shiny apps with an HCL color picker and a color vision deficiency emulator. Plotting functions for displaying and assessing palettes include color swatches, visualizations of the HCL space, and trajectories in HCL and/or RGB spectrum. Color manipulation functions include: desaturation, lightening/darkening, mixing, and simulation of color vision deficiencies (deutanomaly, protanomaly, tritanomaly). Details can be found on the project web page at <https: //colorspace.R-Forge.R-project.org/> and in the accompanying scientific paper: Zeileis et al. (2020, Journal of Statistical Software, <doi:10.18637/jss.v096.i01>). Depends R (>= 3.0.0), methods Imports graphics, grDevices, stats Suggests datasets, utils, KernSmooth, MASS, kernlab, mvtnorm, vcd, tcltk, shiny, shinyjs, ggplot2, dplyr, scales, grid, png, jpeg, knitr, rmarkdown, RColorBrewer, rcartocolor, scico, viridis, wesanderson VignetteBuilder knitr License BSD_3_clause + file LICENSE URL https://colorspace.R-Forge.R-project.org/, https://hclwizard.org/ BugReports https://colorspace.R-Forge.R-project.org/contact.html LazyData yes RoxygenNote 7.1.1 NeedsCompilation yes 1 2 R topics documented: Author Ross Ihaka [aut], Paul Murrell [aut] (<https://orcid.org/0000-0002-3224-8858>), Kurt Hornik [aut] (<https://orcid.org/0000-0003-4198-9911>), Jason C. Fisher [aut] (<https://orcid.org/0000-0001-9032-8912>), Reto Stauffer [aut] (<https://orcid.org/0000-0002-3798-5507>), Claus O. Wilke [aut] (<https://orcid.org/0000-0002-7470-9261>), Claire D. McWhite [aut] (<https://orcid.org/0000-0001-7346-3047>), Achim Zeileis [aut, cre] (<https://orcid.org/0000-0003-0918-3766>) Maintainer Achim Zeileis <[email protected]> Repository CRAN Date/Publication 2021-06-24 07:00:06 UTC R topics documented: adjust_transparency . .3 choose_palette . .5 color-class . .7 contrast_ratio . .8 coords . 10 cvd.............................................. 10 cvd_emulator . 11 cvd_image . 12 demoplot . 12 desaturate . 14 divergingx_hcl . 15 hclplot . 18 hcl_color_picker . 20 hcl_palettes . 21 hex.............................................. 27 hex2RGB . 28 HLS............................................. 29 HSV............................................. 30 LAB............................................. 31 lighten . 32 LUV............................................. 34 max_chroma . 36 mixcolor . 37 polarLAB . 38 polarLUV . 39 rainbow_hcl . 40 readhex . 43 readRGB . 44 RGB............................................. 45 scale_colour_binned_diverging . 46 scale_colour_binned_divergingx . 48 scale_colour_binned_qualitative . 50 scale_colour_binned_sequential . 52 adjust_transparency 3 scale_colour_continuous_diverging . 55 scale_colour_continuous_divergingx . 57 scale_colour_continuous_qualitative . 60 scale_colour_continuous_sequential . 62 scale_colour_discrete_diverging . 64 scale_colour_discrete_divergingx . 66 scale_colour_discrete_qualitative . 69 scale_colour_discrete_sequential . 70 simulate_cvd . 73 specplot . 74 sRGB ............................................ 77 swatchplot . 78 USSouthPolygon . 79 whitepoint . 80 writehex . 81 XYZ............................................. 82 Index 84 adjust_transparency Adjust or Extract Transparency of Colors Description Adjust (i.e., add, remove, or modify) or extract alpha transparency of a vector of colors. Usage adjust_transparency(col, alpha = TRUE) extract_transparency(col, mode = "numeric", default = 1) 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]. Addition- ally, col can be a formal color-class object or a matrix with three rows con- taining R/G/B (0-255) values. alpha either a new alpha transparency value or logical (to add/remove alpha) or NULL. See details. mode character specifying the output mode for the alpha transparency, can be "numeric", "integer", "character" or "hexmode". See details. default vector of length 1 specifying the default alpha transparency that should be re- turned for colors that do not specify any explicitly (defaulting to fully opaque). Can either be numeric, integer, character, or hexmode. 4 adjust_transparency Details Alpha transparency is useful for making colors semi-transparent, e.g., for overlaying different ele- ments 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 col- ors. 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. Value 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. 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. doi: 10.18637/jss.v096.i01 See Also rgb, desaturate, lighten Examples ## 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: choose_palette 5 ## 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 ## extract transparency in different formats extract_transparency(x, mode = "numeric") ## default extract_transparency(x, mode = "integer") extract_transparency(x, mode = "character") extract_transparency(x, mode = "hexmode") ## extract transparency with different default values extract_transparency(x, default = NA) extract_transparency(x, default = 0.5) extract_transparency(x, default = 128L) extract_transparency(x, default = "80", mode = "integer") choose_palette Graphical User Interface for Choosing HCL Color Palettes Description A graphical user interface (GUI) for viewing, manipulating, and choosing HCL color palettes. Usage choose_palette(pal = diverging_hcl, n = 7L, parent = NULL, gui = "tcltk", ...) hclwizard(n = 7L, gui = "shiny", ...) Arguments pal function; the initial palette, see ‘Value’ below. Only used if gui = "tcltk". n integer; the initial number of colors in the palette. parent tkwin; the GUI parent window. Only used if gui = "tcltk". gui character; GUI to use. Available options are tcltk and shiny, see ‘Details’ below. ... used for development purposes only. 6 choose_palette Details Computes palettes based on the HCL (hue-chroma-luminance) color model (as implemented by polarLUV). The GUIs interface the palette functions qualitative_hcl for qualitative palettes, sequential_hcl for sequential palettes with a single or multiple hues, and diverging_hcl for diverging palettes (composed from two single-hue sequential palettes). Two different GUIs are implemented and can be selected using the function input argument gui ("tcltk" or "shiny"). Both GUIs allows for interactive modification of the arguments of the respective palette-generating functions, i.e., starting/ending hue (wavelength, type of color), min- imal/maximal chroma (colorfulness), minimal maximal luminance (brightness, amount of gray), and a power transformations that control