1% File src/library/grDevices/man/convertColor.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2018 R Core Team
4% Distributed under GPL 2 or later
5
6\name{convertColor}
7\alias{convertColor}
8\alias{colorspaces}
9\title{Convert between Colour Spaces}
10\description{
11  Convert colours between their representations in standard
12  colour spaces.
13}
14\usage{
15convertColor(color, from, to, from.ref.white, to.ref.white,
16             scale.in = 1, scale.out = 1, clip = TRUE)
17}
18\arguments{
19  \item{color}{A matrix whose rows specify colors.
20    The function will also accept a data frame, but will silently
21    convert to a matrix internally. }
22  \item{from, to}{Input and output color spaces.  See \sQuote{Details} below.}
23  \item{from.ref.white, to.ref.white}{Reference whites or \code{NULL}
24    if these are built in to the definition, as for RGB
25    spaces. \code{D65} is the default, see \sQuote{Details} for others.
26  }
27  \item{scale.in, scale.out}{Input is divided by \code{scale.in}, output
28    is multiplied by \code{scale.out}. Use \code{NULL} to suppress
29    scaling when input or output is not numeric.}
30  \item{clip}{If \code{TRUE}, truncate RGB output to [0,1],
31    \code{FALSE} return out-of-range RGB, \code{NA} set out of range
32    colors to \code{NaN}.}
33}
34\details{
35  Color spaces are specified by objects of class \code{colorConverter},
36  created by \code{\link{colorConverter}} or \code{\link{make.rgb}}.
37  Built-in color spaces may be referenced by strings: \code{"XYZ"},
38  \code{"sRGB"}, \code{"Apple RGB"}, \code{"CIE RGB"}, \code{"Lab"},
39  \code{"Luv"}.  The converters for these colour spaces are in the object
40  \code{colorspaces}.
41
42  The \code{"sRGB"} color space is that used by standard PC monitors.
43  \code{"Apple RGB"} is used by Apple monitors. \code{"Lab"} and
44  \code{"Luv"} are approximately perceptually uniform
45  spaces standardized by the Commission Internationale
46  d'Eclairage. \code{XYZ} is a 1931 CIE standard capable of representing
47  all visible colors (and then some), but not in a perceptually uniform
48  way.
49
50  The \code{Lab} and \code{Luv} spaces describe colors of objects, and
51  so require the specification of a reference \sQuote{white light}
52  color.  Illuminant \code{D65} is a standard indirect daylight,
53  Illuminant \code{D50} is close to direct sunlight, and Illuminant
54  \code{A} is the light from a standard incandescent bulb. Other
55  standard CIE illuminants supported are \code{B}, \code{C}, \code{E} and
56  \code{D55}.  RGB colour spaces are defined relative to a particular
57  reference white, and can be only approximately translated to other
58  reference whites.  The von Kries chromatic adaptation algorithm is used
59  for this.  Prior to R 3.6, color conversions involving color spaces
60  created with \code{\link{make.rgb}} were carried out assuming a \code{D65}
61  illuminant, irrespective of the actual illuminant used in the creation of the
62  color space.  This affected the built-in \code{"CIE RGB"} color space.
63
64  The RGB color spaces are specific to a particular class of display.
65  An RGB space cannot represent all colors, and the \code{clip} option
66  controls what is done to out-of-range colors.
67
68  For the named color spaces \code{color} must be a matrix of values in
69  the \code{from} color space: in particular opaque colors.
70}
71\value{
72  A 3-column matrix whose rows specify the colors.
73}
74
75\references{
76  For all the conversion equations \url{http://www.brucelindbloom.com/}.
77
78  For the white points
79  \url{https://web.archive.org/web/20190613001950/http://efg2.com/Lab/Graphics/Colors/Chromaticity.htm}.
80}
81
82\seealso{
83  \code{\link{col2rgb}} and \code{\link{colors}} for ways to specify
84  colors in graphics.
85
86  \code{\link{make.rgb}} for specifying other colour spaces.
87}
88\examples{
89## The displayable colors from four planes of Lab space
90ab <- expand.grid(a = (-10:15)*10,
91                  b = (-15:10)*10)
92require(graphics); require(stats) # for na.omit
93par(mfrow = c(2, 2), mar = .1+c(3, 3, 3, .5), mgp = c(2,  .8,  0))
94
95Lab <- cbind(L = 20, ab)
96srgb <- convertColor(Lab, from = "Lab", to = "sRGB", clip = NA)
97clipped <- attr(na.omit(srgb), "na.action")
98srgb[clipped, ] <- 0
99cols <- rgb(srgb[, 1], srgb[, 2], srgb[, 3])
100image((-10:15)*10, (-15:10)*10, matrix(1:(26*26), ncol = 26), col = cols,
101  xlab = "a", ylab = "b", main = "Lab: L=20")
102
103Lab <- cbind(L = 40, ab)
104srgb <- convertColor(Lab, from = "Lab", to = "sRGB", clip = NA)
105clipped <- attr(na.omit(srgb), "na.action")
106srgb[clipped, ] <- 0
107cols <- rgb(srgb[, 1], srgb[, 2], srgb[, 3])
108image((-10:15)*10, (-15:10)*10, matrix(1:(26*26), ncol = 26), col = cols,
109  xlab = "a", ylab = "b", main = "Lab: L=40")
110
111Lab <- cbind(L = 60, ab)
112srgb <- convertColor(Lab, from = "Lab", to = "sRGB", clip = NA)
113clipped <- attr(na.omit(srgb), "na.action")
114srgb[clipped, ] <- 0
115cols <- rgb(srgb[, 1], srgb[, 2], srgb[, 3])
116image((-10:15)*10, (-15:10)*10, matrix(1:(26*26), ncol = 26), col = cols,
117  xlab = "a", ylab = "b", main = "Lab: L=60")
118
119Lab <- cbind(L = 80, ab)
120srgb <- convertColor(Lab, from = "Lab", to = "sRGB", clip = NA)
121clipped <- attr(na.omit(srgb), "na.action")
122srgb[clipped, ] <- 0
123cols <- rgb(srgb[, 1], srgb[, 2], srgb[, 3])
124image((-10:15)*10, (-15:10)*10, matrix(1:(26*26), ncol = 26), col = cols,
125  xlab = "a", ylab = "b", main = "Lab: L=80")
126
127cols <- t(col2rgb(palette())); rownames(cols) <- palette(); cols
128zapsmall(lab <- convertColor(cols, from = "sRGB", to = "Lab", scale.in = 255))
129stopifnot(all.equal(cols, # converting back.. getting the original:
130   round(convertColor(lab, from = "Lab", to = "sRGB", scale.out = 255)),
131                    check.attributes = FALSE))
132}
133\keyword{color}
134