| % File src/library/grDevices/man/make.rgb.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2012 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{make.rgb} |
| \alias{make.rgb} |
| \alias{colorConverter} |
| \title{Create colour spaces } |
| \description{ |
| These functions specify colour spaces for use in |
| \code{\link{convertColor}}. |
| } |
| \usage{ |
| make.rgb(red, green, blue, name = NULL, white = "D65", |
| gamma = 2.2) |
| |
| colorConverter(toXYZ, fromXYZ, name, white = NULL, vectorized = FALSE) |
| } |
| \arguments{ |
| \item{red,green,blue}{Chromaticity (xy or xyY) of RGB primaries} |
| \item{name}{Name for the colour space} |
| \item{white}{Character string specifying the reference white (see |
| \sQuote{Details}.)} |
| \item{gamma}{Display gamma (nonlinearity). A positive number or the |
| string \code{"sRGB"} } |
| \item{fromXYZ}{Function to convert from XYZ tristimulus coordinates |
| to this space} |
| \item{toXYZ}{Function to convert from this space to XYZ tristimulus |
| coordinates.} |
| \item{vectorized}{Whether \code{fromXYZ} and \code{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; \code{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 \code{...}. |
| |
| As of R 3.6.0 the built in color converters along with |
| \code{\link{convertColor}} were vectorized to process three column |
| color matrices in one call, instead of row by row via \code{\link{apply}}. |
| In order to maintain backwards compatibility, \code{colorConverter} wraps |
| \code{fromXYZ} and \code{toXYZ} in a \code{apply} loop in case they do not |
| also support matrix inputs. If the \code{fromXYZ} and \code{toXYZ} functions |
| you are using operate correctly on the whole color matrix at once instead of |
| row by row, you can set \code{vectorized=TRUE} for a performance improvement. |
| } |
| \value{ |
| An object of class \code{colorConverter} |
| } |
| \references{ |
| Conversion algorithms from \url{http://www.brucelindbloom.com}. |
| } |
| \seealso{ |
| \code{\link{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) |
| |
| } |
| \keyword{color} |
| |