1% File src/library/grDevices/man/hcl.Rd 2% Part of the R package, https://www.R-project.org 3% Copyright 1995-2013 R Core Team 4% Distributed under GPL 2 or later 5 6\name{hcl} 7\alias{hcl} 8\encoding{UTF-8} 9\title{HCL Color Specification} 10\description{ 11 Create a vector of colors from vectors specifying hue, 12 chroma and luminance. 13} 14\usage{ 15hcl(h = 0, c = 35, l = 85, alpha, fixup = TRUE) 16} 17\arguments{ 18 \item{h}{The hue of the color specified as an angle in the range 19 [0,360]. 0 yields red, 120 yields green 240 yields blue, etc.} 20 \item{c}{The chroma of the color. The upper bound for chroma depends 21 on hue and luminance.} 22 \item{l}{A value in the range [0,100] giving the luminance of the 23 colour. For a given combination of hue and chroma, only 24 a subset of this range is possible.} 25 \item{alpha}{numeric vector of values in the range \code{[0,1]} for 26 alpha transparency channel (0 means transparent and 1 means opaque).} 27 \item{fixup}{a logical value which indicates whether the resulting 28 RGB values should be corrected to ensure that a real color results. 29 if \code{fixup} is \code{FALSE} RGB components lying outside the 30 range [0,1] will result in an \code{NA} value.} 31} 32\details{ 33This function corresponds to polar coordinates in the CIE-LUV 34color space. Steps of equal size in this space correspond to 35approximately equal perceptual changes in color. Thus, \code{hcl} 36can be thought of as a perceptually based version of \code{\link{hsv}}. 37 38The function is primarily intended as a way of computing 39colors for filling areas in plots where area corresponds to a 40numerical value (pie charts, bar charts, mosaic plots, histograms, 41etc). Choosing colors which have equal chroma and luminance 42provides a way of minimising the irradiation illusion which 43would otherwise produce a misleading impression of how large 44the areas are. 45 46The default values of chroma and luminance make it possible 47to generate a full range of hues and have a relatively pleasant 48pastel appearance. 49 50The RGB values produced by this function correspond to the sRGB 51color space used on most PC computer displays. There are other 52packages which provide more general color space facilities. 53 54 Semi-transparent colors (\code{0 < alpha < 1}) are supported only on 55 some devices: see \code{\link{rgb}}. 56} 57\value{ 58 A vector of character strings which can be used as color 59 specifications by \R graphics functions. 60 61 Missing or infinite values of any of \code{h}, \code{c}, \code{l} 62 result in \code{NA}: such values of \code{alpha} are taken as \code{1} 63 (opaque). 64} 65\references{ 66Ihaka, R. (2003). 67Colour for Presentation Graphics, Proceedings of the 3rd International 68Workshop on Distributed Statistical Computing (DSC 2003), March 20-22, 692003, Technische Universität Wien, Vienna, Austria. 70\url{http://www.ci.tuwien.ac.at/Conferences/DSC-2003/}. 71} 72\author{Ross Ihaka} 73\note{ 74 At present there is no guarantee that the colours rendered by R 75 graphics devices will correspond to their sRGB description. 76 It is planned to adopt sRGB as the standard R color description 77 in future. 78} 79\seealso{ 80 \code{\link{hsv}}, 81 \code{\link{rgb}}. 82} 83\examples{ 84require(graphics) 85 86# The Foley and Van Dam PhD Data. 87csd <- matrix(c( 4,2,4,6, 4,3,1,4, 4,7,7,1, 88 0,7,3,2, 4,5,3,2, 5,4,2,2, 89 3,1,3,0, 4,4,6,7, 1,10,8,7, 90 1,5,3,2, 1,5,2,1, 4,1,4,3, 91 0,3,0,6, 2,1,5,5), nrow = 4) 92 93csphd <- function(colors) 94 barplot(csd, col = colors, ylim = c(0,30), 95 names.arg = 72:85, xlab = "Year", ylab = "Students", 96 legend.text = c("Winter", "Spring", "Summer", "Fall"), 97 main = "Computer Science PhD Graduates", las = 1) 98 99# The Original (Metaphorical) Colors (Ouch!) 100csphd(c("blue", "green", "yellow", "orange")) 101 102# A Color Tetrad (Maximal Color Differences) 103csphd(hcl(h = c(30, 120, 210, 300))) 104 105# Same, but lighter and less colorful 106# Turn off automatic correction to make sure 107# that we have defined real colors. 108csphd(hcl(h = c(30, 120, 210, 300), 109 c = 20, l = 90, fixup = FALSE)) 110 111# Analogous Colors 112# Good for those with red/green color confusion 113csphd(hcl(h = seq(60, 240, by = 60))) 114 115# Metaphorical Colors 116csphd(hcl(h = seq(210, 60, length.out = 4))) 117 118# Cool Colors 119csphd(hcl(h = seq(120, 0, length.out = 4) + 150)) 120 121# Warm Colors 122csphd(hcl(h = seq(120, 0, length.out = 4) - 30)) 123 124# Single Color 125hist(stats::rnorm(1000), col = hcl(240)) 126 127## Exploring the hcl() color space {in its mapping to R's sRGB colors}: 128demo(hclColors) 129 130} 131\keyword{color} 132\keyword{dplot} 133