spacesRGB (version 1.5-0)

RGB Space Management: Manage RGB Spaces

Description

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

Usage

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

Value

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

Arguments

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 \(\gamma\), which is then passed to power.OETF() to create the TransferFunction. This is the classical \(1/\gamma\) 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 \(\gamma\), which is then passed to power.EOTF() to create the TransferFunction. This is the classical \(\gamma\) 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 \(\gamma\), which is then passed to power.OOTF() to create the TransferFunction. This is the classical \(\gamma\) 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.

Primaries and Whitepoint Details

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.

Transfer Function Details

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.

Warning

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.

Details

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.

References

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

See Also

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

Examples

#  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  )