calibrate {colorSpec}

make a linear modification to a colorSpec responder

Description

make a linear modification to a colorSpec responder with M spectra, so a specific stimulus (a single spectrum) creates a specific response (an M-vector). It is generalized form of white balance.
The options are complicated, but in all cases the returned object is multiply(x,gmat) where gmat is an internally calculated MxM matrix - called the gain 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

## 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 either '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 then replicated to length M. Normally all entries are not NA, but it is OK to have exactly one that is not NA. In this special case, a single scaling factor is computed from that non-NA coordinate, and then applied to all M coordinates; the method must be 'scaling'. This is useful for the recommended method for calibration in ASTM E308-01 section 7.1.2. The same type of scaling is also recommended method in CIE 15: Technical Report section 7.1. In this case response=c(NA,100,NA) so the special coordinate is the luminance Y. See the Examples below and the vignettes Viewing Object Colors in a Gallery and The Effect of the Aging Human Lens on Color Vision.
All entries in response, that are not NA, must be positive.
If response is NULL, then an appropriate default may be chosen, see Details.

method

an MxM adaptation 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', 'MCAT02', or 'Bianco+Schettini', and it is then set to the popular corresponding chromatic adaptation 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, its assignment is complicated.
If M=3 and the response of x is neural, and the specnames of x partially match c('x','y','z') (case-insensitive), and none of the components of response are NA, then the neural response is assumed to be human, and the method is set to 'Bradford'.
Otherwise method is set to 'scaling'.

Value

a colorSpec object equal to multiply(x,gmat) where gmat is an internally calculated MxM matrix. The quantity() and wavelength() are preserved.
Note that gmat is not the same as the the MxM adaptation matrix. To inspect gmat execute summary() on the returned object. If method is 'scaling' then gmat 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 adaptation transforms, such as 'Bradford', do not belong in the realm of spectra, for this is not really a spectral calculation. For more about this subject see the explanation in Digital Color Management, Chapter 15 - Myths and Misconceptions. These sophisticated adaptation transforms are provided in calibrate() because it is possible and convenient.

References

ASTM E308-01. Standard Practice for Computing the Colors of Objects by Using the CIE System. 2001.

CIE 15: Technical Report: Colorimetry, 3rd edition. CIE 15:2004.

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(), multiply(), quantity(), wavelength(), colorSpec, summary(), illuminantE(), neutralMaterial(), product()

Examples

wave = 380:780

# make an art gallery illuminated by illuminant A, and with tristimulus XYZ as output
gallery = product( A.1nm, 'artwork', xyz1931.1nm, wave=wave )

#  calibrate simplistically,
#  so the perfect reflecting diffuser has the standard XYZ coordinates for Illuminant A
#  using the convention that Y=100 (instead of Y=1)
A = 100 * spacesXYZ::standardXYZ('A')
A
##         X   Y      Z
##  A 109.85 100 35.585


gallery.cal1 = calibrate( gallery, response=A, method='scaling' )

#  calibrate following the ASTM and CIE recommendation
gallery.cal2 = calibrate( gallery, response=c(NA,100,NA), method='scaling' )

#   make the Perfect Reflecting Diffuser for testing
prd = neutralMaterial( 1, wave=wave ) ; specnames(prd) = 'PRD'

#   compare responses to the PRD for gallery.cal1 and gallery.cal2
white.1 = product( prd, gallery.cal1 )
white.2 = product( prd, gallery.cal2 )
white.1 ; white.2 ; white.1 - white.2 

##           X   Y      Z
##  PRD 109.85 100 35.585
##             X   Y        Z
##  PRD 109.8488 100 35.58151
##                X             Y           Z
##  PRD 0.001210456 -2.842171e-14 0.003489313


# 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