calibrate: make a linear modification to a colorSpec responder
In colorSpec: Color Calculations with Emphasis on Spectral Data

calibrate

R Documentation

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.

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

colorSpec documentation built on May 29, 2024, 6 a.m.