This function lets you convert between different representations of colours. The API is reminiscent of grDevices::convertColor(), but the performance is much better. It is not assured that grDevices::convertColor() and convert_colour() provide numerically equivalent conversion at 16bit level as the formula used are potentially slightly different. For all intend and purpose, the resulting colours will be equivalent though.

convert_colour(colour, from, to, white_from = "D65", white_to = white_from)

Arguments

colour

A numeric matrix (or an object coercible to one) with colours encoded in the rows and the different colour space values in the columns. For all colourspaces except 'cmyk' this will mean a matrix with three columns - for 'cmyk' it means four columns.

from, to

The input and output colour space. Allowed values are: "cmy", "cmyk", "hsl", "hsb", "hsv", "lab" (CIE L*ab), "hunterlab" (Hunter Lab), "oklab", "lch" (CIE Lch(ab) / polarLAB), "luv", "rgb" (sRGB), "xyz", "yxy" (CIE xyY), "hcl" (CIE Lch(uv) / polarLuv), or "oklch" (Polar form of oklab)

white_from, white_to

The white reference of the from and to colour space. Will only have an effect for relative colour spaces such as Lab and luv. Any value accepted by as_white_ref() allowed.

Value

A numeric matrix with the same number of rows as colour and either 3 or 4 columns depending on the value of to. If colour is given as a data.frame the output will be a data.frame as well

Note

This function and convertColor() are not numerically equivalent due to rounding errors, but for all intend and purpose they give the same results.

Handling of non-finite and out of bounds values

NA, NaN, -Inf, and Inf are treated as invalid input and will result in NA values for the colour. If a given colourspace has finite bounds in some of their channels, the input will be capped before conversion, and the output will be capped before returning, so that both input and output colours are valid colours in their respective space. This means that converting back and forth between two colourspaces may result in a change in the colour if the gamut of one of the spaces is less than the other.

Examples

spectrum <- decode_colour(rainbow(10))
spec_lab <- convert_colour(spectrum, 'rgb', 'lab')
spec_lab
#>              l         a          b
#>  [1,] 53.24079  80.09796   67.20432
#>  [2,] 72.26072  30.17136   77.22610
#>  [3,] 93.60533 -41.93879   90.27635
#>  [4,] 88.07403 -83.10282   83.59544
#>  [5,] 88.19634 -80.27407   57.92961
#>  [6,] 91.11322 -48.08151  -14.12690
#>  [7,] 47.90478  35.20130  -82.00196
#>  [8,] 33.81896  79.70472 -105.27489
#>  [9,] 51.90416  91.00028  -74.83009
#> [10,] 55.65103  86.53436   -9.71618

# Convert between different white references
convert_colour(spec_lab, 'lab', 'lab', white_from = 'D65', white_to = 'F10')
#>              l         a           b
#>  [1,] 53.24080  80.09793   67.204334
#>  [2,] 72.26073  30.17134   77.226110
#>  [3,] 93.60534 -41.93880   90.276365
#>  [4,] 88.07403 -83.10282   83.595455
#>  [5,] 88.19634 -80.27406   57.929616
#>  [6,] 91.11322 -48.08151  -14.126901
#>  [7,] 47.90478  35.20131  -82.001964
#>  [8,] 33.81896  79.70473 -105.274888
#>  [9,] 51.90416  91.00027  -74.830083
#> [10,] 55.65103  86.53433   -9.716171