% 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{\abbr{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 \abbr{CIE}-\abbr{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 \abbr{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{https://www.R-project.org/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 \abbr{sRGB} description.
  It is planned to adopt \abbr{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.arg = 72:85, xlab = "Year", ylab = "Students",
          legend.text = 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.out = 4)))

# Cool Colors
csphd(hcl(h = seq(120, 0, length.out = 4) + 150))

# Warm Colors
csphd(hcl(h = seq(120, 0, length.out = 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}