EVOLUTION-MANAGER

Edit File: hcl.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: HCL Color Specification</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<link rel="stylesheet" type="text/css" href="R.css" />
</head><body>

<table width="100%" summary="page for hcl {grDevices}"><tr><td>hcl {grDevices}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>HCL Color Specification</h2>

<h3>Description</h3>

<p>Create a vector of colors from vectors specifying hue,
chroma and luminance.
</p>

<h3>Usage</h3>

<pre>
hcl(h = 0, c = 35, l = 85, alpha, fixup = TRUE)
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>h</code></td>
<td>
<p>The hue of the color specified as an angle in the range
[0,360].  0 yields red, 120 yields green 240 yields blue, etc.</p>
</td></tr>
<tr valign="top"><td><code>c</code></td>
<td>
<p>The chroma of the color.  The upper bound for chroma depends
on hue and luminance.</p>
</td></tr>
<tr valign="top"><td><code>l</code></td>
<td>
<p>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.</p>
</td></tr>
<tr valign="top"><td><code>alpha</code></td>
<td>
<p>numeric vector of values in the range <code>[0,1]</code> for
alpha transparency channel (0 means transparent and 1 means opaque).</p>
</td></tr>
<tr valign="top"><td><code>fixup</code></td>
<td>
<p>a logical value which indicates whether the resulting
RGB values should be corrected to ensure that a real color results.
if <code>fixup</code> is <code>FALSE</code> RGB components lying outside the
range [0,1] will result in an <code>NA</code> value.</p>
</td></tr>
</table>

<h3>Details</h3>

<p>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</code>
can be thought of as a perceptually based version of <code><a href="hsv.html">hsv</a></code>.
</p>
<p>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.
</p>
<p>The default values of chroma and luminance make it possible
to generate a full range of hues and have a relatively pleasant
pastel appearance.
</p>
<p>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.
</p>
<p>Semi-transparent colors (<code>0 &lt; alpha &lt; 1</code>) are supported only on
some devices: see <code><a href="rgb.html">rgb</a></code>.
</p>

<h3>Value</h3>

<p>A vector of character strings which can be used as color
specifications by <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> graphics functions.
</p>
<p>Missing or infinite values of any of <code>h</code>, <code>c</code>, <code>l</code>
result in <code>NA</code>: such values of <code>alpha</code> are taken as <code>1</code>
(opaque).  
</p>

<p>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.
</p>

<h3>Author(s)</h3>

<p>Ross Ihaka</p>

<h3>References</h3>

<p>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.
<a href="http://www.ci.tuwien.ac.at/Conferences/DSC-2003">http://www.ci.tuwien.ac.at/Conferences/DSC-2003</a>.
</p>

<h3>Examples</h3>

<pre>
require(graphics)

# The Foley and Van Dam PhD Data.
csd &lt;- 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 &lt;- 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)

</pre>

<hr /><div style="text-align: center;">[Package <em>grDevices</em> version 3.6.0 <a href="00Index.html">Index</a>]</div>
</body></html>