calibrate: make a linear modification to a colorSpec responder

Description Usage Arguments Details Value Note References See Also Examples

View source: R/colorSpec.calibrate.R

Description

make a linear modification to a colorSpec responder with M spectra so a specific single spectrum (the stimulus) creates a given specific response. It is generalized white balance.
The options are complicated, but in all cases the returned object is multiply(x,mat) where mat is an internally calculated MxM matrix. Stated another way, the spectra in the output are linear combinations of spectra in the input x.
In case of ERROR, a message is logged and the original x is returned.

Usage

1
2
## S3 method for class 'colorSpec'
calibrate( x, stimulus=NULL, response=NULL, method=NULL )

Arguments

x

a colorSpec responder with M spectra. The type must be 'responsivity.light' or 'responsivity.material'.

stimulus

a colorSpec object with a single spectrum, with type 'light' or 'material' to match x. The wavelength sequence of stimulus must be equal to that of x.
If stimulus is NULL, then an appropriate default is chosen, see Details.

response

an M-vector, or a scalar which is replicated to length M. All entries in response must be positive.
If response is NULL, then an appropriate default may be chosen, see Details.

method

an MxM adaption matrix. method can also be 'scaling' and it is then set to the MxM identity matrix, which scales each responsivity spectrum in x independently.
If M=3, method can also be 'Bradford', 'Von Kries', or 'MCAT02', and it is then set to the popular corresponding chromatic adaption matrix. For these special matrices, the spectra in x are not scaled independently; there is "cross-talk".
If method is NULL, then an appropriate default is chosen, see Details.

Details

If stimulus is NULL, it is set to illuminantE() or neutralMaterial() to match x.

If response is NULL and the response of x is electrical or action, then response is set to an M-vector of all 1s. If response is NULL and the response of x is neural, then this is an ERROR and the user is prompted to supply a specific response.

If method is NULL and M=3 and the response of x is neural, then the neural response is assumed to be human, and the method is set to the 3x3 Bradford matrix.
Otherwise method is set to the MxM identity matrix, which scales each responsivity spectrum in x independently. In cameras this is usally called white balance, and so calibrate() can be considered a generalization of white balance.

Value

a colorSpec object equal to multiply(x,mat) where mat is an internally calculated MxM matrix. The quantity and wavelength are preserved.
Note that mat is not the same as the the MxM adaption matrix. To inspect mat execute summary on the returned object. If method is 'scaling' then mat is diagonal and the diagonal entries are the M gain factors needed to achieve the calibration.
Useful data is attached as attribute "calibrate".

Note

Chromatic adaption transforms, such as 'Bradford', do not belong in the realm of spectra; this is not really a spectral calculation. For more about this subject see the explanation in Digital Color Management. This adaption option is provided in calibrate because it is possible and convenient.

References

Edward J. Giorgianni and Thomas E. Madden. Digital Color Management: Encoding Solutions. 2nd Edition John Wiley. 2009. Chapter 15 - Myths and Misconceptions.

See Also

is.regular, quantity, wavelength, colorSpec, summary, illuminantE, neutralMaterial, product

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# make an art gallery illuminated by illuminant A, and with tristimulus XYZ as output
gallery = product( A.1nm, 'artwork', xyz1931.1nm, wave='auto')      
# chromatically adapt the output XYZs to D50 white point, using Bradford matrix
gallery.D50 = calibrate( gallery, response=officialXYZ('D50') )

# make an RGB flatbead scanner from illuminant F11 and a Flea2 camera
scanner = product( subset(Fs.5nm,'F11'), 'paper', Flea2.RGB, wave='auto')  
# adjust RGB gain factors (white balance) so the perfect reflecting diffuser yields RGB=(1,1,1)
scanner = calibrate( scanner )

# same flatbead scanner, but this time with some "white headroom"
scanner = product( subset(Fs.5nm,'F11'), 'paper', Flea2.RGB, wave='auto' )  
scanner = calibrate( scanner, response=0.95 )
scanner

colorSpec documentation built on April 2, 2018, 5:05 p.m.