make a linear modification to a colorSpec responder
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.
## S3 method for class 'colorSpec' calibrate( x, stimulus=NULL, response=NULL, method=NULL )
x |
a colorSpec responder with M spectra.
The |
stimulus |
a colorSpec object with a single spectrum, with |
response |
an M-vector, or a scalar which is replicated to length M.
All entries in |
method |
an MxM adaptation matrix.
|
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.
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 adaptation 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".
Chromatic adaptation 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,
Chapter 15 - Myths and Misconceptions.
This adaptation option is provided in calibrate because it is possible and convenient.
Edward J. Giorgianni and Thomas E. Madden. Digital Color Management: Encoding Solutions. 2nd Edition John Wiley. 2009. Chapter 15 - Myths and Misconceptions.
# 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=spacesXYZ::standardXYZ('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 )
scannerPlease choose more modern alternatives, such as Google Chrome or Mozilla Firefox.