R: Create colour spaces

make.rgb {grDevices} | R Documentation

## Create colour spaces

### Description

These functions specify colour spaces for use in `convertColor`.

### Usage

    make.rgb(red, green, blue, name = NULL, white = "D65",
             gamma = 2.2)

    colorConverter(toXYZ, fromXYZ, name, white = NULL, vectorized = FALSE)

### Arguments

`red,green,blue` | Chromaticity (xy or xyY) of RGB primaries
`name` | Name for the colour space
`white` | Character string specifying the reference white (see ‘Details’.)
`gamma` | Display gamma (nonlinearity). A positive number or the string `"sRGB"`
`fromXYZ` | Function to convert from XYZ tristimulus coordinates to this space
`toXYZ` | Function to convert from this space to XYZ tristimulus coordinates.
`vectorized` | Whether `fromXYZ` and `toXYZ` are vectorized internally to handle input color matrices.

### Details

An RGB colour space is defined by the chromaticities of the red, green and blue primaries. These are given as vectors of length 2 or 3 in xyY coordinates (the Y component is not used and may be omitted). The chromaticities are defined relative to a reference white, which must be one of the CIE standard illuminants: "A", "B", "C", "D50", "D55", "D60", "E" (usually "D65").

The display gamma is most commonly 2.2, though 1.8 is used for Apple RGB. The sRGB standard specifies a more complicated function that is close to a gamma of 2.2; `gamma = "sRGB"` uses this function.

Colour spaces other than RGB can be specified directly by giving conversions to and from XYZ tristimulus coordinates. The functions should take two arguments. The first is a vector giving the coordinates for one colour. The second argument is the reference white. If a specific reference white is included in the definition of the colour space (as for the RGB spaces) this second argument should be ignored and may be `...`.

As of R 3.6.0 the built in color converters along with `convertColor` were vectorized to process three column color matrices in one call, instead of row by row via `apply`. In order to maintain backwards compatibility, `colorConverter` wraps `fromXYZ` and `toXYZ` in a `apply` loop in case they do not also support matrix inputs. If the `fromXYZ` and `toXYZ` functions you are using operate correctly on the whole color matrix at once instead of row by row, you can set `vectorized=TRUE` for a performance improvement.

### Value

An object of class `colorConverter`

### References

Conversion algorithms from http://www.brucelindbloom.com.

### See Also

`convertColor`

### Examples

    (pal <- make.rgb(red =   c(0.6400, 0.3300),
                     green = c(0.2900, 0.6000),
                     blue =  c(0.1500, 0.0600),
                     name = "PAL/SECAM RGB"))

    ## converter for sRGB in #rrggbb format
    hexcolor <- colorConverter(toXYZ = function(hex, ...) {
                                rgb <- t(col2rgb(hex))/255
                                colorspaces$sRGB$toXYZ(rgb, ...) },
                               fromXYZ = function(xyz, ...) {
                                  rgb <- colorspaces$sRGB$fromXYZ(xyz, ...)
                                  rgb <- round(rgb, 5)
                                  if (min(rgb) < 0 || max(rgb) > 1)
                                       as.character(NA)
                                  else rgb(rgb[1], rgb[2], rgb[3])},
                               white = "D65", name = "#rrggbb")

    (cols <- t(col2rgb(palette())))
    zapsmall(luv <- convertColor(cols, from = "sRGB", to = "Luv", scale.in = 255))
    (hex <- convertColor(luv, from = "Luv",  to = hexcolor, scale.out = NULL))

    ## must make hex a matrix before using it
    (cc <- round(convertColor(as.matrix(hex), from = hexcolor, to = "sRGB",
                              scale.in = NULL, scale.out = 255)))
    stopifnot(cc == cols)

    ## Internally vectorized version of hexcolor, notice the use
    ## of `vectorized = TRUE`:

    hexcolorv <- colorConverter(toXYZ = function(hex, ...) {
                                rgb <- t(col2rgb(hex))/255
                                colorspaces$sRGB$toXYZ(rgb, ...) },
                               fromXYZ = function(xyz, ...) {
                                  rgb <- colorspaces$sRGB$fromXYZ(xyz, ...)
                                  rgb <- round(rgb, 5)
                                  oob <- pmin(rgb[,1],rgb[,2],rgb[,3]) < 0 |
                                         pmax(rgb[,1],rgb[,2],rgb[,3]) > 0
                                  res <- rep(NA_character_, nrow(rgb))
                                  res[!oob] <- rgb(rgb[!oob,,drop=FALSE])},
                               white = "D65", name = "#rrggbb",
                               vectorized=TRUE)
    (ccv <- round(convertColor(as.matrix(hex), from = hexcolor, to = "sRGB",
                               scale.in = NULL, scale.out = 255)))
    stopifnot(ccv == cols)

[Package grDevices version 4.0.5 Index]