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