EVOLUTION-MANAGER

Edit File: lighten.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: Algorithmically Lighten or Darken Colors</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 lighten {colorspace}"><tr><td>lighten {colorspace}</td><td style="text-align: right;">R Documentation</td></tr></table>

<h2>Algorithmically Lighten or Darken Colors</h2>

<h3>Description</h3>

<p>The functions <code>lighten</code> and <code>darken</code> take a vector of R colors and adjust the colors such that
they appear lightened or darkened, respectively.
</p>

<h3>Usage</h3>

<pre>
lighten(col, amount = 0.1, method = c("relative", "absolute"),
  space = c("HCL", "HLS", "combined"), fixup = TRUE)

darken(col, amount = 0.1, space = "combined", ...)
</pre>

<h3>Arguments</h3>

<table summary="R argblock">
<tr valign="top"><td><code>col</code></td>
<td>
<p>vector of any of the three kind of R colors, i.e., either a color
name (an element of <code><a href="../../grDevices/html/colors.html">colors</a></code>), a hexadecimal string
of the form <code>"#rrggbb"</code> or <code>"#rrggbbaa"</code> (see
<code><a href="../../grDevices/html/rgb.html">rgb</a></code>), or an integer <code>i</code> meaning
<code>palette()[i]</code>.</p>
</td></tr>
<tr valign="top"><td><code>amount</code></td>
<td>
<p>numeric specifying the amount of lightening. This is applied either
multiplicatively or additively to the luminance value, depending on the
setting of <code>method</code> (either relative or absolute). Negative numbers
cause darkening.</p>
</td></tr>
<tr valign="top"><td><code>method</code></td>
<td>
<p>character string specifying the adjustment method. Can be either <code>"relative"</code> or <code>"absolute"</code>.</p>
</td></tr>
<tr valign="top"><td><code>space</code></td>
<td>
<p>character string specifying the color space in which adjustment happens. Can be either <code>"HLS"</code> or <code>"HCL"</code>.</p>
</td></tr>
<tr valign="top"><td><code>fixup</code></td>
<td>
<p>logical If set to <code>TRUE</code>, colors that fall outside of the RGB color gamut are slightly modified
by translating individual primary values so they lie between 0 and 255. If set to <code>FALSE</code>, out-of-gamut colors
are replaced by <code>NA</code>.</p>
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
<p>Other parameters handed to the function <code>lighten()</code>.</p>
</td></tr>
</table>

<h3>Details</h3>

<p>The color adjustment can be calculated in three different color spaces. </p>

<ol>
<li><p> If <code>space = "HCL"</code>, the colors are transformed to HCL, (<code><a href="polarLUV.html">polarLUV</a></code>),
the luminance component L is adjusted, and then the colors are transformed back to a hexadecimal
RGB string.
</p>
</li>
<li><p> If <code>space = "HLS"</code>, the colors are transformed to HLS, the lightness component L is adjusted,
and then the color is transformed back to a hexadecimal RGB string.
</p>
</li>
<li><p> If <code>space = "combined"</code>, the colors are first adjusted in both the HCL and HLS spaces. Then,
the adjusted HLS colors are converted into HCL, and then the chroma components of the adjusted HLS
colors are copied to the adjusted HCL colors. Thus, in effect, the combined model adjusts luminance
in HCL space but chroma in HLS space.
</p>
</li></ol>

<p>We have found that typically <code>space = "HCL"</code> performs best for lightening colors and <code>space = "combined"</code>
performs best for darkening colors, and these are the default settings for <code>lighten</code> and <code>darken</code>,
respectively.
</p>
<p>Regardless of the chosen color space, the adjustment of the L component can occur by two methods, relative
(the default) and absolute. Under the absolute method, the adjustment is <code>L +/- 100 * amount</code> when
lightening/darkening colors. Under the relative method, the adjustment is <code>100 - (100 - L) * (1 - amount)</code> when
lightening colors and <code>L * (1 - amount)</code> when darkening colors.
</p>
<p>Programmatically lightening and darkening colors can yield unexpected results (see examples). In HCL space,
colors can become either too gray or overly colorful. By contrast, in HLS space it can happen that the
overall amount of lightening or darkening appears to be non-uniform among a group of colors that are 
lightened or darkened jointly, and again, colors can become either too gray or overly colorful. We
recommend to try different color spaces if the default space for the chosen function (<code>lighten</code> 
or <code>darken</code>) does not look right in a specific application.
</p>

<h3>Value</h3>

<p>A character vector with (s)RGB codings of the colors in the palette.
</p>

<h3>References</h3>

<p>Zeileis A, Fisher JC, Hornik K, Ihaka R, McWhite CD, Murrell P, Stauffer R, Wilke CO (2019).
&ldquo;ccolorspace: A Toolbox for Manipulating and Assessing Colors and Palettes.&rdquo;
arXiv:1903.06490, arXiv.org E-Print Archive. <a href="http://arxiv.org/abs/1903.06490">http://arxiv.org/abs/1903.06490</a>
</p>

<p><code><a href="polarLUV.html">polarLUV</a></code>, <code><a href="hex.html">hex</a></code>, <code><a href="desaturate.html">desaturate</a></code>
</p>

<h3>Examples</h3>

<pre>
# lighten dark colors, example 1
cl &lt;- qualitative_hcl(5)
swatchplot(list(
  HCL = rbind("0%" = cl,
              "15%" = lighten(cl, 0.15),
              "30%" = lighten(cl, 0.3)),
  HLS = rbind("0%" = cl,
              "15%" = lighten(cl, 0.15, space = "HLS"),
              "30%" = lighten(cl, 0.3, space = "HLS")),
  combined = rbind("0%" = cl,
              "15%" = lighten(cl, 0.15, space = "combined"),
              "30%" = lighten(cl, 0.3, space = "combined"))),
  nrow = 4, line = 2.5
)

# lighten dark colors, example 2
cl &lt;- c("#61A9D9", "#ADD668", "#E6D152", "#CE6BAF", "#797CBA")
swatchplot(list(
  HCL = rbind("0%" = cl,
              "15%" = lighten(cl, 0.15),
              "30%" = lighten(cl, 0.3)),
  HLS = rbind("0%" = cl,
              "15%" = lighten(cl, 0.15, space = "HLS"),
              "30%" = lighten(cl, 0.3, space = "HLS")),
  combined = rbind("0%" = cl,
              "15%" = lighten(cl, 0.15, space = "combined"),
              "30%" = lighten(cl, 0.3, space = "combined"))),
  nrow = 4, line = 2.5
)

# darken light colors, example 1
cl &lt;- qualitative_hcl(5, "Pastel 1")
swatchplot(list(
  combined = rbind("0%" = cl,
              "15%" = darken(cl, 0.15),
              "30%" = darken(cl, 0.3)),
  HCL = rbind("0%" = cl,
              "15%" = darken(cl, 0.15, space = "HCL"),
              "30%" = darken(cl, 0.3, space = "HCL")),
  HLS = rbind("0%" = cl,
              "15%" = darken(cl, 0.15, space = "HLS"),
              "30%" = darken(cl, 0.3, space = "HLS"))),
  nrow = 4, line = 2.5
)

# darken light colors, example 2 
cl &lt;- c("#CDE4F3","#E7F3D3","#F7F0C7","#EFCFE5","#D0D1E7")
swatchplot(list(
  combined = rbind("0%" = cl,
              "15%" = darken(cl, 0.15),
              "30%" = darken(cl, 0.3)),
  HCL = rbind("0%" = cl,
              "15%" = darken(cl, 0.15, space = "HCL"),
              "30%" = darken(cl, 0.3, space = "HCL")),
  HLS = rbind("0%" = cl,
              "15%" = darken(cl, 0.15, space = "HLS"),
              "30%" = darken(cl, 0.3, space = "HLS"))),
  nrow = 4, line = 2.5
)
</pre>

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