RGB Space Management {spacesRGB} | R Documentation |
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 )
Arguments
space |
name of the RGB space to install or uninstall or query.
After the RGB space is installed,
the string |
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 |
display |
the specification of the display primaries and whitepoint.
The options are the same as for argument |
OETF |
a |
EOTF |
a |
OOTF |
a |
overwrite |
in |
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.
Value
installRGB()
and uninstallRGB()
return TRUE
or FALSE
.
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.
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 )