convertColor            package:grDevices            R Documentation

_C_o_n_v_e_r_t _b_e_t_w_e_e_n _c_o_l_o_u_r _s_p_a_c_e_s

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

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

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     A 3-row matrix whose columns specify the colors.

_R_e_f_e_r_e_n_c_e_s:

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

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

_S_e_e _A_l_s_o:

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

     'make.rgb' for specifying other colour spaces.

_E_x_a_m_p_l_e_s:

     require(graphics); require(stats) # for na.omit
     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))