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