convertColor {grDevices} | R Documentation

## Convert between Colour Spaces

### Description

Convert colours between their representations in standard colour spaces.

### 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.

For the named color spaces `color` must be a matrix of values in the `from` color space: in particular opaque colors.

### Value

A 3-column matrix whose rows 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

    ## The displayable colors from four planes of Lab space
    ab <- expand.grid(a = (-10:15)*10,
                      b = (-15:10)*10)
    require(graphics); require(stats) # for na.omit
    par(mfrow = c(2, 2), mar = .1+c(3, 3, 3, .5), mgp = c(2,  .8,  0))

    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())); rownames(cols) <- palette(); cols
    zapsmall(lab <- convertColor(cols, from = "sRGB", to = "Lab", scale.in = 255))
    stopifnot(all.equal(cols, # converting back.. getting the original:
       round(convertColor(lab, from = "Lab", to = "sRGB", scale.out = 255)),
                        check.attributes = FALSE))

[Package grDevices version 3.3.0 Index]