installRGB: Manage RGB Spaces
In spacesRGB: Standard and User-Defined RGB Color Spaces, with Conversion Between RGB and CIE XYZ

Description Usage Arguments Details Value Primaries and Whitepoint Details Transfer Function Details Warning References See Also Examples

View source: R/installation.R

Install/uninstall RGB spaces in a dictionary. The dictionary comes with 8 RGB spaces pre-installed. To query the dictionary, use getRGB() and summaryRGB().

1 2	installRGB( space, scene, display=NULL, OETF=NULL, EOTF=NULL, OOTF=NULL, overwrite=FALSE ) uninstallRGB( space )

`space`	name of the RGB space to install or uninstall or query. After the RGB space is installed, the string `space` can be used in the conversion functions, e.g. `RGBfromXYZ()` and `XYZfromRGB()`.
`scene`	the specification of the scene primaries and whitepoint. There are many options here. The 1st option is a 4x2 matrix with the CIE xy chromaticities of R,G,B,W in the rows, in that order. The 2nd option is a list with 2 items: the primaries data and the whitepoint data. These are described in the section Primaries and Whitepoint Details below. If `scene` is `NULL`, it will duplicate the data from argument `display`.
`display`	the specification of the display primaries and whitepoint. The options are the same as for argument `scene`. If this is `NULL` (the default), the function will first look at the metadata of the transfer functions. These built-in transfer functions - `general.OOTF()` and `general.PODT()` - already have this metadata assigned. If the metadata is not found, it will duplicate the data from argument `scene`.
`OETF`	a `TransferFunction` of dimension 1 or 3. `OETF` can also be a positive number γ, which is then passed to `power.OETF()` to create the `TransferFunction`. This is the classical 1/γ power law. `OETF` can also be `NULL`; see section Transfer Function Details for valid combinations.
`EOTF`	a `TransferFunction` of dimension 1 or 3. `EOTF` can also be a positive number γ, which is then passed to `power.EOTF()` to create the `TransferFunction`. This is the classical γ power law. `EOTF` can also be one of these strings: `'sRGB'`, `'ProPhotoRGB'`, `'BT.709'`, `'BT.2020'`, or `'240M'`, which then installs the appropriate special EOTF function. `EOTF` can also be `NULL`; see section Transfer Function Details for valid combinations.
`OOTF`	a `TransferFunction` of dimension 1 or 3. `OOTF` can also be a positive number γ, which is then passed to `power.OOTF()` to create the `TransferFunction`. This is the classical γ power law. `EOTF` can also be `NULL`; see section Transfer Function Details for valid combinations.
`overwrite`	in `installRGB()`, `space` is compared with previously installed RGB space names in case-insensitive way. If there is a match, and `overwrite` is `FALSE`, then the installation fails. If `overwrite` is `TRUE`, then the existing space is overwritten.

Both installRGB() and uninstallRGB() check for matches with existing names. The matching is full (not partial) and case-insensitive. So it is impossible to have 2 spaces that differ only in case.

installRGB() and uninstallRGB() return TRUE or FALSE.

The arguments scene and display can be a list with 2 items: primaries and white in that order. There are 3 options for this list, as given in this table:

`dim(primaries)`	`length(white)`	Description
4x2	1	`primaries` is a 4x2 matrix with CIE xy chromaticities of R,G,B,W in the rows
3x2	2	`primaries` is a 3x2 matrix with CIE xy chromaticities of R,G,B in the rows
3x2	3	`primaries` is a 3x2 matrix with CIE xy chromaticities of R,G,B in the rows

If length(white) is 1, then white is the whitepoint Y. If length(white) is 2, then white is the whitepoint xy (CIE chromaticity); the whitepoint Y is taken to be 1. If length(white) is 3, white is the whitepoint XYZ (CIE tristimulus).
The whitepoint is linearly transformed to RGB=(1,1,1). For better numeric compatibility with standards, xy is recommended. For better numeric compatibility with Lindbloom, XYZ is recommended. See the Examples below.

The 3 transfer functions - OETF, EOTF, OOTF - can be NULL (the default) or given. This yields 8 combinations, but only 6 are valid, as given in this table:

`OETF`	`EOTF`	`OOTF`	Description
given	given	given	INVALID
given	given	`OETF*EOTF`	`OOTF` is the composition `OETF` followed by `EOTF`
given	`OETF^-1*OOTF`	given	`EOTF` is the composition `OETF^-1` followed by `OOTF`
`OOTF*EOTF^-1`	given	given	`OETF` is the composition `OOTF` followed by `EOTF^-1`
given	`OETF^-1`	`identity.TF`	`EOTF` is set to `OETF^-1`, and `OOTF` is set to the identity
`EOTF^-1`	given	`identity.TF`	`OETF` is set to `EOTF^-1`, and `OOTF` is set to the identity
`NULL`	`NULL`	given	INVALID
`NULL`	`NULL`	`NULL`	all 3 transfer functions are set to `identity.TF`.

Think of these 3 functions as forming a triangle. If all 3 are given, the transfers may be ambiguous, i.e. the triangle may not commute. If 2 functions are given, the 3rd is computed from those 2. If only 1 function is given, and it is EOTF or OETF, then it makes sense to make the other one the inverse of the given one, so that the OOTF is the identity. If only the OOTF is given, there is no well-defined way to define the other 2. If none are given, as in the last row, this might be useful for testing conversion between RGB and XYZ.

All the RGB spaces are stored in a dictionary. If installRGB() is successful, the installed space is only in the dictionary until the end of the R session. To make it persist, please put the function call in an R script that is executed after the package is loaded.
The dictionary comes with 8 RGB spaces pre-installed.

Lindbloom, Bruce. RGB/XYZ Matrices. http://brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html

getRGB(), summaryRGB() RGBfromXYZ(), XYZfromRGB(), TransferFunction, power.OETF(), power.EOTF(), power.OOTF()

#  install native RGB space for NEC PA242W display
prim = matrix( c(0.675,0.316, 0.199,0.715, 0.157,0.026), 3, 2, byrow=TRUE )
installRGB( 'PA242W', scene=NULL, display=list(primaries=prim,white=c(0.95047,1,1.08883)), OETF=2 )

#  install a linear version of sRGB  (OETF=1)
prim    = matrix( c(0.64,0.33,  0.30,0.60, 0.15,0.06), 3, 2, byrow=TRUE )
installRGB( 'linear-sRGB', scene=NULL, display=list(prim,c(0.3127,0.3290)), OETF=1 )

# make plot comparing three EOTFs
plot( getRGB('sRGB')$EOTF, col='black' )
plot( getRGB('linear')$EOTF, col='red', add=TRUE )
plot( getRGB('PA242W')$EOTF, col='blue', add=TRUE )

# Install an RGB space named 'HD+2.4', with encoding from BT.709 and display from BT.1886.
# the OOTF for this space is non-trivial
prim    = matrix( c(0.64,0.33,  0.30,0.60,  0.15,0.06 ), 3, 2, byrow=TRUE )
white   = c( 0.3127, 0.3290 )
installRGB( "HD+2.4", scene=NULL, display=list(prim,white),
                          OETF=(BT.709.EOTF)^-1, EOTF=BT.1886.EOTF(), over=TRUE )

# make plot comparing two OOTFs
plot( getRGB('HD+2.4')$OOTF, col='red')
plot( getRGB('sRGB')$OOTF, col='black', add=TRUE  )