convertColor {grDevices} | R Documentation

## Convert between colour spaces

### Description

Convert colours between standard colour space representations. This function is experimental.

### Usage

    convertColor(color, from, to, from.ref.white, to.ref.white,
                 scale.in=1, scale.out=1, clip=TRUE)

### Arguments

`color` | A matrix whose rows specify colors
`from,to` | Input and output color spaces. See Details below
`from.ref.white,to.ref.white` | Reference whites or `NULL` if these are built in to the definition, as for RGB spaces. `D65` is the default, see Details for others
`scale.in, scale.out` | Input is divided by `scale.in`, output is multiplied by `scale.out`. Use `NULL` to suppress scaling when input or output is not numeric.
`clip` | If `TRUE`, truncate RGB output to [0,1], `FALSE` return out-of-range RGB, `NA` set out of range colors to `NaN`.

### Details

Color spaces are specified by objects of class `colorConverter`, created by `colorConverter` or `make.rgb`. Built-in color spaces may be referenced by strings: `"XYZ"`, `"sRGB"`, `"Apple RGB"`, `"CIE RGB"`, `"Lab"`, `"Luv"`. The converters for these colour spaces are in the object `colorspaces`.

The `"sRGB"` color space is that used by standard PC monitors. `"Apple RGB"` is used by Apple monitors. `"Lab"` and `"Luv"` are approximately perceptually uniform spaces standardized by the Commission Internationale d'Eclairage. `XYZ` is a 1931 CIE standard capable of representing all visible colors (and then some), but not in a perceptually uniform way.

The `Lab` and `Luv` spaces describe colors of objects, and so require the specification of a reference “white light” color. Illuminant `D65` is a standard indirect daylight, Illuminant `D50` is close to direct sunlight, and Illuminant `A` is the light from a standard incandescent bulb. Other standard CIE illuminants supported are `B`, `C`, `E` and `D55`. RGB colour spaces are defined relative to a particular reference white, and can be only approximately translated to other reference whites. The Bradford chromatic adaptation algorithm is used for this.

The RGB color spaces are specific to a particular class of display. An RGB space cannot represent all colors, and the `clip` option controls what is done to out-of-range colors.

### Value

A 3-row matrix whose columns specify the colors.

### References

For all the conversion equations http://www.brucelindbloom.com/

For the white points http://www.efg2.com/Lab/Graphics/Colors/Chromaticity.htm

### See Also

`col2rgb` and `colors` for ways to specify colors in graphics.

`make.rgb` for specifying other colour spaces.

### Examples

    par(mfrow=c(2,2))
    ## The displayable colors from four planes of Lab space
    ab <- expand.grid(a=(-10:15)*10,b=(-15:10)*10)

    Lab <- cbind(L=20,ab)
    srgb <- convertColor(Lab,from="Lab",to="sRGB",clip=NA)
    clipped <- attr(na.omit(srgb),"na.action")
    srgb[clipped,] <- 0
    cols <- rgb(srgb[,1],srgb[,2],srgb[,3])
    image((-10:15)*10,(-15:10)*10,matrix(1:(26*26),ncol=26),col=cols,
      xlab="a",ylab="b",main="Lab: L=20")

    Lab <- cbind(L=40,ab)
    srgb <- convertColor(Lab,from="Lab",to="sRGB",clip=NA)
    clipped <- attr(na.omit(srgb),"na.action")
    srgb[clipped,] <- 0
    cols <- rgb(srgb[,1],srgb[,2],srgb[,3])
    image((-10:15)*10,(-15:10)*10,matrix(1:(26*26),ncol=26),col=cols,
      xlab="a",ylab="b",main="Lab: L=40")

    Lab <- cbind(L=60,ab)
    srgb <- convertColor(Lab,from="Lab",to="sRGB",clip=NA)
    clipped <- attr(na.omit(srgb),"na.action")
    srgb[clipped,] <- 0
    cols <- rgb(srgb[,1],srgb[,2],srgb[,3])
    image((-10:15)*10,(-15:10)*10,matrix(1:(26*26),ncol=26),col=cols,
      xlab="a",ylab="b",main="Lab: L=60")

    Lab <- cbind(L=80,ab)
    srgb <- convertColor(Lab,from="Lab",to="sRGB",clip=NA)
    clipped <- attr(na.omit(srgb),"na.action")
    srgb[clipped,] <- 0
    cols <- rgb(srgb[,1],srgb[,2],srgb[,3])
    image((-10:15)*10,(-15:10)*10,matrix(1:(26*26),ncol=26),col=cols,
      xlab="a",ylab="b",main="Lab: L=80")

    (cols <- t(col2rgb(palette())))
    (lab <- convertColor(cols,from="sRGB",to="Lab",scale.in=255))
    round(convertColor(lab,from="Lab",to="sRGB",scale.out=255))

[Package grDevices version 2.1.1 Index]