| % File src/library/grDevices/man/hcl.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2013 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{hcl} |
| \alias{hcl} |
| \encoding{UTF-8} |
| \title{HCL Color Specification} |
| \description{ |
| Create a vector of colors from vectors specifying hue, |
| chroma and luminance. |
| } |
| \usage{ |
| hcl(h = 0, c = 35, l = 85, alpha, fixup = TRUE) |
| } |
| \arguments{ |
| \item{h}{The hue of the color specified as an angle in the range |
| [0,360]. 0 yields red, 120 yields green 240 yields blue, etc.} |
| \item{c}{The chroma of the color. The upper bound for chroma depends |
| on hue and luminance.} |
| \item{l}{A value in the range [0,100] giving the luminance of the |
| colour. For a given combination of hue and chroma, only |
| a subset of this range is possible.} |
| \item{alpha}{numeric vector of values in the range \code{[0,1]} for |
| alpha transparency channel (0 means transparent and 1 means opaque).} |
| \item{fixup}{a logical value which indicates whether the resulting |
| RGB values should be corrected to ensure that a real color results. |
| if \code{fixup} is \code{FALSE} RGB components lying outside the |
| range [0,1] will result in an \code{NA} value.} |
| } |
| \details{ |
| This function corresponds to polar coordinates in the CIE-LUV |
| color space. Steps of equal size in this space correspond to |
| approximately equal perceptual changes in color. Thus, \code{hcl} |
| can be thought of as a perceptually based version of \code{\link{hsv}}. |
| |
| The function is primarily intended as a way of computing |
| colors for filling areas in plots where area corresponds to a |
| numerical value (pie charts, bar charts, mosaic plots, histograms, |
| etc). Choosing colors which have equal chroma and luminance |
| provides a way of minimising the irradiation illusion which |
| would otherwise produce a misleading impression of how large |
| the areas are. |
| |
| The default values of chroma and luminance make it possible |
| to generate a full range of hues and have a relatively pleasant |
| pastel appearance. |
| |
| The RGB values produced by this function correspond to the sRGB |
| color space used on most PC computer displays. There are other |
| packages which provide more general color space facilities. |
| |
| Semi-transparent colors (\code{0 < alpha < 1}) are supported only on |
| some devices: see \code{\link{rgb}}. |
| } |
| \value{ |
| A vector of character strings which can be used as color |
| specifications by \R graphics functions. |
| |
| Missing or infinite values of any of \code{h}, \code{c}, \code{l} |
| result in \code{NA}: such values of \code{alpha} are taken as \code{1} |
| (opaque). |
| } |
| \references{ |
| Ihaka, R. (2003). |
| Colour for Presentation Graphics, Proceedings of the 3rd International |
| Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, |
| 2003, Technische Universität Wien, Vienna, Austria. |
| \url{http://www.ci.tuwien.ac.at/Conferences/DSC-2003}. |
| } |
| \author{Ross Ihaka} |
| \note{ |
| At present there is no guarantee that the colours rendered by R |
| graphics devices will correspond to their sRGB description. |
| It is planned to adopt sRGB as the standard R color description |
| in future. |
| } |
| \seealso{ |
| \code{\link{hsv}}, |
| \code{\link{rgb}}. |
| } |
| \examples{ |
| require(graphics) |
| |
| # The Foley and Van Dam PhD Data. |
| csd <- matrix(c( 4,2,4,6, 4,3,1,4, 4,7,7,1, |
| 0,7,3,2, 4,5,3,2, 5,4,2,2, |
| 3,1,3,0, 4,4,6,7, 1,10,8,7, |
| 1,5,3,2, 1,5,2,1, 4,1,4,3, |
| 0,3,0,6, 2,1,5,5), nrow = 4) |
| |
| csphd <- function(colors) |
| barplot(csd, col = colors, ylim = c(0,30), |
| names = 72:85, xlab = "Year", ylab = "Students", |
| legend = c("Winter", "Spring", "Summer", "Fall"), |
| main = "Computer Science PhD Graduates", las = 1) |
| |
| # The Original (Metaphorical) Colors (Ouch!) |
| csphd(c("blue", "green", "yellow", "orange")) |
| |
| # A Color Tetrad (Maximal Color Differences) |
| csphd(hcl(h = c(30, 120, 210, 300))) |
| |
| # Same, but lighter and less colorful |
| # Turn off automatic correction to make sure |
| # that we have defined real colors. |
| csphd(hcl(h = c(30, 120, 210, 300), |
| c = 20, l = 90, fixup = FALSE)) |
| |
| # Analogous Colors |
| # Good for those with red/green color confusion |
| csphd(hcl(h = seq(60, 240, by = 60))) |
| |
| # Metaphorical Colors |
| csphd(hcl(h = seq(210, 60, length = 4))) |
| |
| # Cool Colors |
| csphd(hcl(h = seq(120, 0, length = 4) + 150)) |
| |
| # Warm Colors |
| csphd(hcl(h = seq(120, 0, length = 4) - 30)) |
| |
| # Single Color |
| hist(stats::rnorm(1000), col = hcl(240)) |
| |
| ## Exploring the hcl() color space {in its mapping to R's sRGB colors}: |
| demo(hclColors) |
| |
| } |
| \keyword{color} |
| \keyword{dplot} |