Package 'colorSpec'

Description

Package colorSpec is for working with spectral color data in R.

Details

Features:

1. a clear classification of the commonly seen spectra into 4 types - depending on the vector space to which they belong

2. flexible organization for the spectra in memory, using an S3 class - colorSpec

3. a product algebra for the colorSpec objects

4. uniform handling of biological eyes, electronic cameras, and general action spectra

5. a few advanced calculations, such as computing optimal colors (aka Macadam Limits)

6. inverse colorimetry, e.g. reflectance recovery from response

7. built-in essential tables, such as the CIE illuminants and color matching functions

8. a package logging system with log levels taken from the popular Log4J

9. support for reading a few spectrum file types, including CGATS

10. bonus files containing some other interesting spectra

11. minimal dependencies on other R packages

Non-features:

1. there is no support for many common 3D color spaces, such as CIELAB, HSL, etc.. For these spaces see packages colorspace, colorscience, spacesRGB, and spacesXYZ.

2. there are few non-linear operations

3. there is little support for scientific units; for these see package colorscience

4. photons are parameterized by wavelength in nanometers; other wavelength units (such as Angstrom and micron) and alternative parameterizations (such as wavenumber and electronvolt) are not available

Regarding the non-linear operations in 2, the only such operations are conversion of linear RGB to display RGB, conversion of absorbance to transmittance, and the reparameterized wavelength in computeADL. The electronic camera model is purely linear with no dark current offset or other deviations.

Many ideas are taken from packages hyperSpec, hsdar, pavo, and zoo.

Author(s)

Glenn Davis <[email protected]>

See Also

colorSpec for the S3 class provided by this package.

colorSpec User Guide

Description

Format

Each is a colorSpec object organized as a vector, with quantity equal to "energy".

Details

All of these have been divided by 100, to make the values at 560nm near 1 instead of 100.

Source

http://www.cvrl.org

References

Günther Wyszecki and W. S. Stiles. Color Science : Concepts and Methods, Quantitative Data and Formulae. Second Edition. Wiley-Interscience. 1982.

See Also

D50 D65

Examples

summary(xyz1931.1nm)
white.point = product( D65.1nm, xyz1931.1nm, wave='auto' )

Description

Convert a radiometric colorSpec object to have quantity that is actinometric (number of photons). Test an object for whether it is actinometric.

Usage

## S3 method for class 'colorSpec'
actinometric( x, multiplier=1, warn=FALSE )

## S3 method for class 'colorSpec'
is.actinometric( x )

Arguments

Details

If the quantity of x does not start with 'energy' then the quantity is not radiometric and so x is returned unchanged. Otherwise x is radiometric (energy-based), and must be converted.

If type(x) is 'light' then the most common radiometric energy unit is joule.
The conversion equation is:

$Q = E * \lambda * 10^6 / (N_A * h * c)$

wher $Q$ is the photon count, $E$ is the energy of the photons, $N_A$ is Avogadro's constant, $h$ is Planck's constant, $c$ is the speed of light, and $\lambda$ is the wavelength. The output unit of photon count is ($\mu$mole of photons) = ($6.02214 * 10^{17}$ photons). If a different unit for Q is desired, then the output should be scaled appropriately. For example, if the desired unit of photon count is exaphotons, then set multiplier=0.602214.

If the quantity(x) is 'energy->electrical', then the most common radiometric unit of responsivity to light is coulombs/joule (C/J) or amps/watt (A/W). The conversion equation is:

$QE = R_e * ((h * c)/e) / \lambda$

where $QE$ is the quantum efficiency, $R_e$ is the energy-based responsivity, and $e$ is the charge of an electron (in C).
If the unit of x is not C/J, then multiplier should be set appropriately.

If the quantity(x) is 'energy->neural' or 'energy->action', the most common radiometric unit of energy is joule (J).

The conversion equation is:

$R_p = R_e * 10^{-6} * ( N_A * h * c) / \lambda$

where $R_p$ is the photon-based responsivity, and $R_e$ is the energy-based responsivity, The output unit of photon count is ($\mu$mole of photons) = ($6.02214 * 10^{17}$ photons). This essentially the reciprocal of the first conversion equation.

The argument multiplier is applied to the right side of all the above conversion equations.

Value

actinometric() returns a colorSpec object with quantity that is actinometric (photon-based) and not radiometric (energy-based). If type(x) is a material type ('material' or 'responsivity.material') then x is returned unchanged.

If quantity(x) starts with 'photons', then is.actinometric() returns TRUE, and otherwise FALSE.

Note

To log the executed conversion equation, execute cs.options(loglevel='INFO').

Source

Wikipedia. Photon counting. https://en.wikipedia.org/wiki/Photon_counting

See Also

quantity, type, cs.options, radiometric

Examples

colSums( solar.irradiance ) # step size is 1nm, from 280 to 1000 nm. organized as a matrix
# AirMass.0  GlobalTilt AirMass.1.5 
#  944.5458    740.3220    649.7749  # irradiance, watts*m^{-2}


colSums( actinometric(solar.irradiance) )
# AirMass.0  GlobalTilt AirMass.1.5 
#  4886.920    3947.761    3522.149  # photon irradiance, (umoles of photons)*sec^{-1}*m^{-2}

colSums( actinometric(solar.irradiance,multiplier=0.602214) )
# AirMass.0  GlobalTilt AirMass.1.5 
#  2942.972    2377.397    2121.088  # photon irradiance, exaphotons*sec^{-1}*m^{-2}

Description

apply a function to each spectrum in a colorSpec object

Usage

## S3 method for class 'colorSpec'
applyspec( x, FUN, ... )

Arguments

Details

applyspec() simply calls apply() with the right MARGIN.

Value

a colorSpec object with the same dimensions, wavelength, quantity, and organization. If FUN does not return an N-vector, it is an ERROR and applyspec() returns NULL.

See Also

quantity, wavelength, linearize, organization, apply

Examples

#  convert absorbance to transmittance
path = system.file( "extdata/stains/Hematoxylin.txt", package='colorSpec' )
x = readSpectra( path )
x = applyspec( x, function(y) {10^(-y)} ) # this is what linearize(x) does

Description

convert a colorSpec object to a data.frame

Usage

## S3 method for class 'colorSpec'
as.data.frame( x, row.names=NULL, optional=FALSE, organization='auto', ... )

Arguments

Details

If organization is 'auto', and the organization of x is 'df.row', then organization is set to 'row' and the returned data.frame has the spectra in the rows. Otherwise the returned data.frame has the spectra in the columns.

Value

If the returned data.frame has the spectra in the rows, then the spectra are in a matrix in the last column (with name spectra), and any existing extradata are also returned in the other columns. The wavelengths are only present in character form, as the colnames of the matrix.
If the returned data.frame has the spectra in the columns, then the wavelengths are in the first column, and the spectra are in the other columns.

See Also

as.matrix, extradata

Description

Calculate transmittance along a horizontal optical path in the atmosphere, as a function of length (distance) and the molecular and aerosol properties. Because the path is horizontal, the atmospheric properties are assumed to be constant on the path. Only molecular scattering is considered. There is no modeling of molecular absorption; for visible wavelengths this is reasonable.

Usage

atmosTransmittance( distance, wavelength=380:720, 
                    molecules=list(N=2.547305e25,n0=1.000293),
                    aerosols=list(metrange=25000,alpha=0.8,beta=0.0001) )

Arguments

Details

The list molecules has 2 parameters that describe the molecules in the atmosphere. N is the molecular density of the atmosphere at sea level, in $molecules/meter^3$. The given default is the density at sea level. n0 is the refractive index of pure molecular air (with no aerosols). For the molecular attenuation, the standard model for Rayleigh scattering is used, and there is no modeling of molecular absorption.

The list aerosols has 3 parameters that describe the aerosols in the atmosphere. The standard Angstrom aerosol attenuation model is:

$attenuation(\lambda) = \beta * (\lambda/\lambda_0)^{-\alpha}$

$\alpha$ is the Angstrom exponent, and is dimensionless. $attenuation$ and $\beta$ have unit $m^{-1}$. And $\lambda_0$=550nm.

metrange is the Meteorological Range of the atmosphere in meters, as defined by Koschmieder. This is the distance at which the transmittance=0.02 at $\lambda_0$. If metrange is not NULL (the default is 25000) then both $\alpha$ and $\beta$ are calculated to achieve this desired metrange, and the supplied $\alpha$ and $\beta$ are ignored. $\alpha$ is calculated from metrange using the Kruse model, see Note. $\beta$ is calculated so that the product of molecular and aerosol transmittance yields the desired metrange. In fact:

$\beta = -\mu_0 - log(0.02) / V_r$

where $\mu_0$ is the molecular attenuation at $\lambda_0$, and $V_r$ is the meteorological range. For a log message with the calculated values, execute cs.options(loglevel='INFO') before calling atmosTransmittance().

Value

atmosTransmittance() returns a colorSpec object with quantity equal to 'transmittance'. There is a spectrum in the object for each value in the vector distance. The specnames are set to sprintf("dist=%gm",distance).
The final transmittance is the product of the molecular transmittance and the aerosol transmittance. If both molecules and aerosols are NULL, then the final transmittance is identically 1; the atmosphere has become a vacuum.

Note

The Kruse model for $\alpha$ as a function of $V_r$ is defined in 3 pieces. For $0 \le V_r < 6000$, $\alpha = 0.585 * (V_r/1000)^{1/3}$. For $6000 \le V_r < 50000$, $\alpha = 1.3$. And for $V_r \ge$ 50000, $\alpha = 1.6$. So $\alpha$ is increasing, but not strictly, and not continuously. $V_r$ is in meters. See Kruse and Kaushal.

The built-in object atmosphere2003 is transmittance along an optical path that is NOT horizontal, and extends to outer space. This is much more complicated to calculate.

References

Angstrom, Anders. On the atmospheric transmission of sun radiation and on dust in the air. Geogr. Ann., no. 2. 1929.

Kaushal, H. and Jain, V.K. and Kar, S. Free Space Optical Communication. Springer. 2017.

Koschmieder, Harald. Theorie der horizontalen Sichtweite. Beitrage zur Physik der Atmosphare. 1924. 12. pages 33-53.

P. W. Kruse, L. D. McGlauchlin, and R. B. McQuistan. Elements of Infrared Technology: Generation, Transmission, and Detection. J. Wiley & Sons, New York, 1962.

See Also

solar.irradiance, specnames

Examples

trans = atmosTransmittance( c(5,10,15,20,25)*1000 ) # 5 distances with atmospheric defaults

# verify that transmittance[550]=0.02 at dist=25000
plot( trans, legend='bottomright', log='y' )

# repeat, but this time assign alpha and beta explicitly
trans = atmosTransmittance( c(5,10,15,20,25)*1000, aero=list(alpha=1,beta=0.0001) )

Description

A band-based material spectrum is a superimposition of bandpass filters, and (optionally) a bandstop filter. The 2 functions in this topic convert a vector of numbers between 0 and 1 to a band representation, and back again.

Usage

bandMaterial( lambda, wavelength=380:780 )

## S3 method for class 'colorSpec'
bandRepresentation( x )

Arguments

Details

bandRepresentation() is a right-inverse of bandMaterial(), see Examples and the test script test-bands.R. For more mathematical details, see the vignette Convexity and Transitions.

Value

bandMaterial() returns a colorSpec object with quantity equal to 'transmitance'. If lambda is a matrix, then the object has 1 spectrum. If lambda is a list of matrices with length N, then the object has N spectra.

bandRepresentation() returns a list of matrices with 2 columns. There is a matrix in the list for each spectrum in x.

See Also

rectangularMaterial(), vignette Convexity and Transitions

Examples

#  make a vector superimposing a bandpass and a bandstop filter, and of the proper length 401
vec = c( rep(1,100), 0.5, rep(0,40), .25, rep(1,50), 0.9, rep(0,100), 0.4, rep(1,107) )

#	 convert that vector to a colorSpec object, with a single spectrum
spec = colorSpec( vec, wavelength=380:780, quantity='transmittance', specnames='sample' )

#	 extract and print the 2 bands
lambda = bandRepresentation( spec ) ;  print(lambda)

##  $sample
##      lambda1 lambda2
##  BS   673.10   480.0
##  BP1  521.25   572.4

#  convert the 2 bands  (the transition wavelengths) back to a vector of length 401
#  and compare with the original vector
delta = vec - coredata( bandMaterial(lambda) )

range(delta)
##  [1] -9.092727e-14  2.275957e-14

Description

Take a sequence of colorSpec objects and combine their spectra

Usage

## S3 method for class 'colorSpec'
bind( ... )

Arguments

Details

The organization of the returned object is the most complex of those in the inputs, where the order of complexity is:

'matrix' < 'df.col' < 'df.row'

If the selected organization is 'df.row', the extradata is combined in a way that preserves all the columns. Missing data is filled with NAs, analogous to rbind.fill().

The metadata of the returned object is copied from the first object in the input list.

Value

bind() returns a colorSpec object, or NULL in case of ERROR. If the bind is successful, the number of spectra in the output object is the sum of the number of spectra in the input objects.

See Also

wavelength, quantity, specnames, organization, extradata, metadata, rbind.fill()

Examples

Rosco = readSpectra( system.file( 'extdata/objects/Rosco.txt', package='colorSpec' ) )
Rosco = resample( Rosco, wave=wavelength(Hoya) )
numSpectra(Hoya)        # prints 4
numSpectra(Rosco)       # prints 42

filters = bind( Hoya, Rosco )
numSpectra(filters)     # prints 46

colnames( extradata(Hoya) )
## [1] "SAMPLE_NAME"  "FresnelReflectance"  "Thickness"

colnames( extradata(Rosco) )
## [1] "Model"  "SampleID"  "SAMPLE_NAME"  "Substrate"  "RefractiveIndex"  "Thickness"

##  The columns in common are "SAMPLE_NAME" and "Thickness"


colnames( extradata(filters) )
## [1] "FresnelReflectance" "Model" "RefractiveIndex" "SAMPLE_NAME"
## [5] "SampleID" "Substrate" "Thickness"
##
## "SAMPLE_NAME" and "Thickness" are combined in the usual way
## The other columns are present, and missing data is filled with NAs

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

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

Description

Consider a colorSpec object x with type equal to 'responsivity.material'. The set of all possible material reflectance functions (or transmittance functions) is convex, closed, and bounded (in any reasonable function space), and this implies that the set of all possible output responses from x is also convex, closed, and bounded. The latter set is called the object-color solid or Rösch Farbkörper for x. A color on the boundary of the object-color solid is called an optimal color for x. The corresponding transmittance spectrum is called an optimal spectrum for x. The special points W (the response to the perfect reflecting diffuser) and 0 (the response to the perfect absorbing diffuser) are optimal.

Currently the function only works if the number of spectra in x is 3 (e.g. RGB or XYZ). In this case the object-color solid is a zonohedron whose boundary is the union of parallelograms, which may be coplanar. These parallelograms are indexed by distinct pairs of the wavelengths of x; if x has N wavelengths, then there are N*(N-1) parallelograms. The center of each parallelogram is called a canonical optimal color. Interestingly, the special points W and 0 are not canonical.

Usage

## S3 method for class 'colorSpec'
canonicalOptimalColors( x, lambda, spectral=FALSE )

Arguments

Details

The 3 responsivities are regarded not as continuous functions, but as step functions. This implies that the color solid is a zonohedron. In the preprocessing phase the zonohedral representation is calculated. The faces of the zonohedron are either parallelograms, or compound faces that can be partitioned into parallelograms. The centers of all these parallelograms are the canonical optimal colors.
The optimal spectra take value 1/2 at the 2 given wavelengths, and 0 or 1 elsewhere. If the 2 wavelengths are $\lambda_1$ and $\lambda_2$, and $\lambda_1 < \lambda_2$ then the spectrum is approximately a bandpass filter. If the 2 wavelengths are swapped, then the spectrum is "flipped" and is approximately a bandstop filter.

Value

If argument spectral=FALSE, canonicalOptimalColors() returns a data.frame with a row for each row in lambda. The columns in the output are:

If rownames(lambda) is not NULL, they are copied to the row names of the output.

If argument spectral=TRUE, it returns a colorSpec object with quantity 'transmittance'. This object contains the optimal spectra, and the above-mentioned data.frame can then be obtained by applying extradata() to the returned object.

In case of global error, the function returns NULL.

References

Centore, Paul. A zonohedral approach to optimal colours. Color Research & Application. Vol. 38. No. 2. pp. 110-119. April 2013.

Logvinenko, A. D. An object-color space. Journal of Vision. 9(11):5, 1-23, (2009).
https://jov.arvojournals.org/article.aspx?articleid=2203976 doi:10.1167/9.11.5.

Schrödinger, E. (1920). Theorie der Pigmente von grösster Leuchtkraft. Annalen der Physik. 62, 603-622.

West, G. and M. H. Brill. Conditions under which Schrödinger object colors are optimal. Journal of the Optical Society of America. 73. pp. 1223-1225. 1983.

See Also

probeOptimalColors(), bandRepresentation(), scanner.ACES, extradata(), type, vignette Convexity and Transitions

Examples

wave    = seq(400,700,by=5)
D50.eye = product( D50.5nm, 'material', xyz1931.1nm, wavelength=wave )
canonicalOptimalColors( D50.eye, c(500,600, 550,560, 580,585) )
##    lambda.1 lambda.2   optimal.x   optimal.y   optimal.z transitions
##  1      500      600 47.02281830 80.07281030  4.33181530           2
##  2      550      560  5.18490614 10.09045773  0.06121505           2
##  3      580      585 26.91247649 21.49031008  0.03457904           6

Description

chop all spectra in a colorSpec object into low and high parts at a blending interval

Usage

## S3 method for class 'colorSpec'
chop( x, interval, adj=0.5 )

Arguments

Details

For each spectrum, the low and high parts sum to the original spectrum. The low part vanishes on the right of the interval, and the high part vanishes on the left.

Value

chop(x) returns a colorSpec object with twice the number of spectra in x and with organization equal to 'matrix'. The names of the new spectra are formed by appending ".lo" and ".hi" to the original spectrum names.

See Also

organization,

Examples

# chop blue butane flame into diatomic carbon and hydrocarbon parts
path = system.file( "extdata/sources/BlueFlame.txt", package="colorSpec" )
blueflame = readSpectra( path, seq(375,650,0.5) )
plot( chop( blueflame, interval=c(432,435), adj=0.8 ) )

# chop 'white' LED into blue and yellow parts
path = system.file( "extdata/sources/Gepe-G-2001-LED.sp", package="colorSpec" )
LED = readSpectra( path )
plot( chop( LED, c(470,495) ) )

Description

The function colorSpec() is the constructor for colorSpec objects.

is.colorSpec() tests whether an object is a valid colorSpec object.
as.colorSpec() converts other variables to a colorSpec object, and is designed to be overridden by other packages.

Usage

colorSpec( data, wavelength, quantity='auto', organization='auto', specnames=NULL )

is.colorSpec(x)

## Default S3 method:
as.colorSpec( ... )

Arguments

Details

Under the hood, a colorSpec object is either a vector, matrix, or data.frame. It is of S3 class 'colorSpec' with these extra attributes:

wavelength

a numeric vector of wavelengths for all the spectra. If the organization of the object is 'df.col', then this is absent.

quantity

a character string that gives the physical quantity of all spectra, see quantity() for a list of possible values.

metadata

a named list for user-defined data. The names 'path', 'header' and 'date' are already reserved; see metadata().

step.wl

step between adjacent wavelengths in nm. This is assigned only when the wavelengths are regular; see is.regular().

specname

only assigned when the organization is 'vector', in which case it is equal to the single character string name of the single spectrum. Note that the word specname is singular. Also see specnames().

And there are a few more attributes that exist only in special cases; see the colorSpec User Guide.

Value

colorSpec() returns a colorSpec object, or NULL in case of ERROR. Compare this function with stats::ts().

is.colorSpec() returns TRUE or FALSE. It does more than check the class, and also checks wavelength, quantity, and organization. If FALSE, it logs (at loglevel='DEBUG') the reason that x is invalid.

as.colorSpec.default() issues an ERROR message and returns NULL

See Also

wavelength, quantity, organization, metadata, step.wl, specnames, is.regular, coredata

Examples

#  make a synthetic Gaussian bandpass filter

center = 600
wave   = 400:700
trans  = exp( -(wave-center)^2 / 20^2 )

filter.bp   = colorSpec( trans, wave, quantity='transmittance', specnames='myfilter' )

organization( filter.bp )  # returns:  "vector"

# and now plot it
plot( filter.bp )

Description

Consider a colorSpec object x with type equal to responsivity.material. The set of all possible material reflectance functions (or transmittance functions) is convex, closed, and bounded (in any reasonable function space), and this implies that the set of all possible output responses from x is also convex, closed, and bounded. The latter set is called the object-color solid or Rösch Farbkörper for x. A color on the boundary of the object-color solid is called an optimal color. The special points W (the response to the perfect reflecting diffuser) and 0 are on the boundary of this set. The interior of the line segment of neutrals joining 0 to W is in the interior of the object-color solid. It is natural to parameterize this segment from 0 to 1 (from 0 to W). The solid is symmetrical about the neutral gray midpoint G=W/2.

Now suppose that x has 3 spectra (3 responses) and consider a color response R not equal to G. There is a ray based at G and passing through R that intersects the boundary of the object-color solid at an optimal color B on the boundary with Logvinenko coordinates $(\delta,\omega)$. If these 2 coordinates are combined with $\alpha$, where R = $(1-\alpha)$G + $\alpha$B, it yields the Logvinenko coordinates $(\alpha,\delta,\omega)$ of R. These coordinates are also denoted by ADL; see References. A response is in the object-color solid iff $\alpha \le 1$. A response is optimal iff $\alpha=1$.

The coordinates of 0 are $(\alpha,\delta,\omega)$=(1,0,0). The coordinates of W are $(\alpha,\delta,\omega)$=(1,1,0). The coordinates of G are undefined.

Usage

## S3 method for class 'colorSpec'
computeADL( x, response )

Arguments

Details

For each response, a ray is computed and the ray tracing is done by probeOptimalColors().

Value

computeADL() returns a data.frame with a row for each response. The columns in the data frame are:

If an individual ray could not be traced, or if the optimal spectrum has more than 2 transitions, the row contains NA in appropriate columns.
In case of global error, the function returns NULL.

WARNING

Since this function is really a simple wrapper around probeOptimalColors(), please see the performance warnings there.

References

Logvinenko, A. D. An object-color space. Journal of Vision. 9(11):5, 1-23, (2009).
https://jov.arvojournals.org/article.aspx?articleid=2203976. doi:10.1167/9.11.5.

Godau, Christoph and Brian Funt. XYZ to ADL: Calculating Logvinenko's Object Color Coordinates. Proceedings Eighteenth IS&T Color Imaging Conference. San Antonio. Nov 2009.

See Also

type(), probeOptimalColors(), vignette Plotting Chromaticity Loci of Optimal Colors

Examples

D50.eye = product( D50.5nm, 'varmat', xyz1931.1nm, wave=seq(360,830,by=5) )
computeADL( D50.eye, c(30,50,70) )
##    response.X response.Y response.Z   ADL.alpha   ADL.delta  ADL.lambda     omega 
##  1         30         50         70   0.7371475   0.5384104 473.3594572 0.3008817

##  lambda.1 lambda.2
##  427.2011 555.5261

## since alpha < 1, XYZ=c(30,50,70) is *inside* the object-color solid of D50.eye

Description

Compute the CCT, in K, of a colorSpec object with type equal to 'light'

Usage

## S3 method for class 'colorSpec'
computeCCT( x, isotherms='robertson', locus='robertson', strict=FALSE )

Arguments

Details

In computeCCT(), for each spectrum, XYZ is computed using xyz1931.1nm, and the result passed to spacesXYZ::CCTfromXYZ(). If the quantity of x is 'photons' (actinometric) each spectrum is converted to 'energy' (radiometric) on the fly.

Value

computeCCT() returns a numeric vector of length M, where M is the number of spectra in x. The vector's names is set to specnames(x).
If the type of x is not 'light', then a warning is issued and all values are NA_real_.

References

McCamy, C. S. Correlated color temperature as an explicit function of chromaticity coordinates. Color Research & Application. Volume 17. Issue 2. pages 142-144. April 1992.

Robertson, A. R. Computation of correlated color temperature and distribution temperature. Journal of the Optical Society of America. 58. pp. 1528-1535 (1968).

Wyszecki, Günther and W. S. Stiles. Color Science: Concepts and Methods, Quantitative Data and Formulae, Second Edition. John Wiley & Sons, 1982. Table 1(3.11). pp. 227-228.

See Also

type(), quantity(), xyz1931, planckSpectra(), specnames(), spacesXYZ::CCTfromXYZ()

Examples

computeCCT( D65.1nm )                       # returns 6502.068
computeCCT( D65.1nm, isotherms='native' )   # returns 6503.323
computeCCT( A.1nm )                         # returns 2855.656
computeCCT( A.1nm, isotherms='native' )     # returns 2855.662
computeCCT( A.1nm, isotherms='mccamy' )     # returns 2857.188

moon = readSpectra( system.file( "extdata/sources/moonlight.txt", package='colorSpec' ) )
computeCCT( moon )                  # returns 4482.371

Description

Compute the CIE 1974 color rendering index (CRI) of a light spectrum, called the the test illuminant.
From the given spectrum a reference illuminant is selected with the same CCT (Correlated Color Temperature). A selected set of 8 color samples is rendered in XYZ (1931) with both illuminants and 8 color differences are computed in a special CIEUVW color space. For each color difference a CRI is computed, where 100 is a perfect color match. The final CRI is the average of these 8 CRI values.

Usage

## S3 method for class 'colorSpec'
computeCRI( x, adapt=TRUE, attach=FALSE, tol=5.4e-3 )

Arguments

Details

The CCT of x is computed by computeCCT() with default options.
If adapt is TRUE the 8 test uv points are chromatically adapted from the test illuminant to the reference illuminant using a special von Kries type transformation; see Oleari and Wikipedia. The test UVW values are computed relative to the reference illuminant.
If adapt is FALSE the 8 test uv points are not chromatically adapted, and the test UVW values are computed relative to the test illuminant.

Value

computeCRI() returns a single number $\le$ 100. In case of ERROR it returns NA. If attach is TRUE a large list of intermediate calculations is attached to the returned number.

Source

The test color reflectance spectra are taken from:
http://www.lrc.rpi.edu/programs/nlpip/lightinganswers/lightsources/scripts/NLPIP_LightSourceColor_Script.m

References

Oleari, Claudio, Gabriele Simone. Standard Colorimetry: Definitions, Algorithms and Software. John Wiley. 2016. pp. 465-470.

Günther Wyszecki and W. S. Stiles. Color Science: Concepts and Methods, Quantitative Data and Formulae, Second Edition. John Wiley & Sons, 1982. Table 1(3.11). p. 828.

Wikipedia. Color rendering index. https://en.wikipedia.org/wiki/Color_rendering_index

Hunt, R. W. G. and M. R. Pointer. Measuring Colour. 4th edition. John Wiley & Sons. 2011. Appendix 7.

See Also

type, xyz1931, computeCCT

Examples

computeCRI( subset(Fs.5nm,'F2') )       # returns 64.15195
computeCRI( subset(Fs.5nm,'F4') )       # returns 51.36348

Description

Compute the Spectrum Similarity Index (SSI), an index between 0 and 100, of a colorSpec object with type equal to 'light'. It compares a test spectrum with a reference spectrum (an ideal). The value 100 means a perfect match to the reference, and a smaller value mean a poorer match (similar to CRI). Only values in the interval [375,675] nm are used; for details see Holm.

Usage

## S3 method for class 'colorSpec'
computeSSI( x, reference=NULL, digits=0, isotherms='mccamy', locus='robertson' )

Arguments

Details

If reference contains a single spectrum, then each test spectrum is compared to that one reference spectrum. If reference contains M spectra, then the i'th test spectrum is compared to the i'th reference spectrum.

If reference=NULL then for each test spectrum the CCT is computed and used to compute a reference spectrum with the same CCT. It is either a Planckian (black-body) or daylight illuminant, see Holm for details. The test spectrum and auto-computed reference spectrum are then compared.

Value

computeSSI() returns a numeric vector of length M, where M is the number of spectra in x. The vector's names is set from specnames(x) and a compact code for the corresponding reference spectrum.

If the type of x is not 'light', or reference is not valid, then the function returns NULL.

References

J. Holm and T. Maier and P. Debevec and C. LeGendre and J. Pines and J. Erland and G. Joblove and S. Dyer and B. Sloan and J. di Gennaro and D. Sherlock. A Cinematographic Spectral Similarity Index. SMPTE 2016 Annual Technical Conference and Exhibition. pp. 1-36. (2016).

See Also

type(), computeCCT(), planckSpectra(), daylightSpectra(), specnames()

Examples

computeSSI( planckSpectra( 1000*(2:6) )  )
##  P2000_SSI[2027K] P3000_SSI[3057K] P4000_SSI[D4063] P5000_SSI[D5061] P6000_SSI[D6063] 
##                99               98               93               92               92

Description

This function convolves each spectrum in a colorSpec object with a kernel of odd length. Its primary purpose is to correct raw spectrometer data (with positive instrumental bandwidth) to have bandwidth=0. Two popular correction kernels for this, with lengths 3 and 5, are built-in options, see Details.

Usage

## S3 method for class 'colorSpec'
convolvewith( x, coeff )

Arguments

Details

The built-in kernels, 'SS3' and 'SS5', were derived by Stearns & Stearns under specific hypotheses on the spectrometer profile, bandpass, and pitch; see References.
Missing values at both ends are filled by copying from the nearest valid value.
The function creates a function calling stats::filter() and passes that function to applyspec().

Value

a colorSpec object with the same dimensions, wavelength, quantity, and organization. If coeff is invalid it is an ERROR and convolvewith() returns NULL.

References

Stearns, E.I., Stearns R.E. An example of a method for correction radiance data for bandpass error. Color Research and Application. 13-4. 257-259. 1988.

Schanda, Janos. CIE Colorimetry, in Colorimetry: Understanding the CIE System. Wiley Interscience. 2007. p. 124.

Oleari, Claudio, Gabriele Simone. Standard Colorimetry: Definitions, Algorithms and Software. John Wiley. 2016. p. 309.

See Also

quantity, wavelength, linearize, applyspec, organization

Description

functions for extracting the core data contained in a colorSpec object.

Usage

## S3 method for class 'colorSpec'
coredata( x, forcemat=FALSE )

## S3 method for class 'colorSpec'
as.matrix( x, ... )

Arguments

Value

See Also

organization

Description

colorSpec has a few options. The options are stored in the R global list and they are:

colorSpec.loglevel, colorSpec.logformat, and colorSpec.stoponerror

For details on what they do see logging.

They can be set using the built-in function options(). When R starts up, an option can be set using a call to options() in the file Rprofile.site. If colorSpec is later loaded, the value of the option will not be changed. If an option has not been assigned, then it is created with a default value.

The function cs.options() makes setting the options a little easier in a few ways:

• it automatically prepends the string 'colorSpec.'

• partial matching of the option name is enabled

• a warning is issued when the option value has the wrong type

Usage

cs.options( ... )

Arguments

Value

returns a list with all the colorSpec options.

See Also

logging, options

Examples

cs.options( loglevel="DEBUG", stop=FALSE )  # 'stop' partially matches 'stoponerror'
cs.options( stop='TRUE' )                   # warns that value has the wrong type
cs.options( stop=FALSE, "DEBUG" )           # warns that the 2nd argument has no name
cs.options( loglevel="WARN" )               # back to default

Description

Format

A colorSpec object organized as a vector, with 107 data points and specnames equal to 'D50'.

Details

This spectrum is not copied from a table from a CIE publication, though it does match such a table. It is computed using the function daylightSpectra() by following the special CIE recipe given in the References. The temperature is set to (14388/14380) * 5000 = 5002.781 Kelvin. The coefficients of the daylight components $S_0, S_1$, and $S_2$ are rounded to 3 decimal places. This linear combination is computed at 10nm intervals and then linearly interpolated to 5nm intervals. The result is normalized to value 1 at 560nm (instead of the usual 100), and finally rounded to 5 decimal places. See Examples.

References

Günther Wyszecki and W.S. Stiles. Color Science : Concepts and Methods, Quantitative Data and Formulae. Second Edition. Wiley-Interscience. 1982. Table I(3.3.4) pp. 754-758

CIE 15: Technical Report: Colorimetry, 3rd edition. CIE 15:2004. Table T.1, pp 30-32, and Note 5 on page 69.

Schanda, Janos. CIE Colorimetry, in Colorimetry: Understanding the CIE System. Wiley Interscience. 2007. p. 42.

See Also

ABC , D65 , daylightSpectra

Examples

#   the CIE recipe for computing D50.5nm
correction  = 14388 / 14380     # note 5, page 69 in CIE 15:2004
D50.10nm    = daylightSpectra( correction*5000, wavelength=seq(300,830,by=10), roundMs=TRUE )
D50.5nm     = resample( D50.10nm, seq(300,830,by=5), method='linear' )
D50.5nm     = round( D50.5nm, 5 )

summary( D50.5nm )
white.point = product( D50.5nm, xyz1931.1nm, wave='auto' )

Description

Format

Each is a colorSpec object organized as a vector, with specnames equal to 'D65'.

Details

Both of these have been divided by 100, to make the values at 560nm equal to 1 instead of 100.

Source

http://www.cvrl.org

References

Günther Wyszecki and W.S. Stiles. Color Science : Concepts and Methods, Quantitative Data and Formulae. Second Edition. Wiley-Interscience. 1982. Table I(3.3.4) pp. 754-758

ASTM E 308-01. Standard Practice for Computing the Colors of Objects by Using the CIE System. Table 3. pages 3-4.

See Also

ABC, D50, daylightSpectra , daylight

Examples

summary( D65.1nm )
white.point = product( D65.1nm, xyz1931.1nm, wave='auto' )

Description

Format

Each is a colorSpec object organized as a matrix with 3 columns

Source

http://www.cie.co.at/publ/abst/datatables15_2004/CIE_sel_colorimetric_tables.xls

http://vision.vein.hu/~schanda/CIE%20TC1-74/

References

Günther Wyszecki and W.S. Stiles. Color Science : Concepts and Methods, Quantitative Data and Formulae. Second Edition. Wiley-Interscience. 1982. Table V(3.3.4) p. 762.

Smoothing spectral power distribution of daylights. Zsolt Kosztyan and Janos Schanda. Color Research & Application. Volume 38, Issue 5, pages 316-321, October 2013.

CIE 15: Technical Report: Colorimetry, 3rd edition. CIE 15:2004. Table T.2, pp 33-34

JUDD, D.B., MACADAM, D.L. and WYSZECKI, G., with the collaboration of BUDDE, H.W, CONDIT, H.R, HENDERSON, S.T, and SIMONDS, J.L. Spectral distribution of typical daylight as a function of correlated color temperature. J Opt. Soc. Am. 54, 1031-1040, 1964.

Zsolt Kosztyan and Janos Schanda. Smoothing spectral power distribution of daylights. Color Research & Application. Volume 38, Issue 5, pages 316-321, October 2013.

See Also

D65, D50, daylightSpectra

Examples

summary( daylight1964 )
day1964 = daylightSpectra( c(5000,6500), comp=daylight1964 )
day2013 = daylightSpectra( c(5000,6500), comp=daylight2013 )

plot( day1964, col='black' )
plot( day2013, col='black', add=TRUE )

Description

All RGB displays have a non-linear "gamma function" of some sort. This function converts from linear RGB to an RGB appropriate for the gamma function of the display; which is also called the electro-optical conversion function (EOCF).

Usage

DisplayRGBfromLinearRGB( RGB, gamma='sRGB' )

Arguments

Value

The function first clamps the input RGB to the interval [0,1]. If gamma='sRGB' (not case-sensitive) it then maps [0,1] to [0,1] using the special piecewise-defined sRGB function, see Wikipedia. In case gamma is a positive number, the function raises all values to the power 1/gamma. The dimensions and names of the input are copied to the output.
In case of error, the function returns the clamped input values.

WARNING

This function is deprecated. New software should use spacesRGB::SignalRGBfromLinearRGB() instead.

Source

Wikipedia. sRGB. https://en.wikipedia.org/wiki/SRGB

See Also

RGBfromXYZ

Examples

DisplayRGBfromLinearRGB( c(0.2, 0.5) )
# [1] 0.4845292 0.7353570     #  this is display sRGB, in [0,1]

DisplayRGBfromLinearRGB( c(-0.1, 0.2, 0.5, 1), 2.2 )
# [1] 0.0000000 0.4811565 0.7297401 1.0000000    #  gamma=2.2

x = seq( 0, 1, len=101)
plot( x, DisplayRGBfromLinearRGB(x), type='l' )

Description

The two possible modifications are:

• pre-multiplication by a transmitting filter

• post-multiplication by a matrix

Both of these are optional. If neither of these modifications is enabled, the original x is returned.

Usage

## S3 method for class 'colorSpec'
emulate( x, y, filter=FALSE, matrix=TRUE )

Arguments

Details

If filter=FALSE and matrix=TRUE then the returned value is multiply(x,A), where the matrix A is computed to minimize the difference with y, in the least squares sense (Frobenius matrix norm). The function ginv() is used here.

If filter=TRUE and matrix=FALSE then the returned value is product(filter,x), where the object filter is computed to minimize the difference with y, in the least squares sense (Frobenius matrix norm). This calculation is fairly straightforward, but requires that the responsivity of x does not vanish at any wavelength. It also requires that M=N. The computed filter may be unrealistic, i.e. the transmittance may be > 1. If this happens a WARN message is issued.

If filter=TRUE and matrix=TRUE then the returned value is product(filter,multiply(x,A)), where (filter,A) are chosen with the above minimization criterion. If N=1 then we must have M=1 as well; the calculation is trivial and the emulation is exact. If N $\ge$ 2, the calculation is iterative - solving alternatively for filter and A until convergence. The function ginv() is used on each iteration. This is a bilinear optimization. If convergence fails, it is an error and the function returns NULL. If convergence succeeds, there is 1 degree of freedom in the (filter,A) pair. If one is scaled by a positive constant, the other can be scaled by the inverse, and the returned object is the same. The filter is scaled so the maximum transmittance is 1.

If filter=FALSE and matrix=FALSE then the original x is returned, with a WARN message.

Value

a colorSpec object close to y, as in Details. The quantity is the same as y. The specnames() are the same as those of y, except that ".em" is appended to each one. The function attaches attribute "emulate", whose value is a list containing filter and/or A as appropriate.

Examples

see the vignette Emulation of one Camera by another Camera

See Also

wavelength, type, quantity, multiply, product, specnames

Description

Retrieve or set the extradata of a colorSpec object.

Usage

## S3 method for class 'colorSpec'
extradata(x)

## S3 replacement method for class 'colorSpec'
extradata(x,add=FALSE) <- value

Arguments

Details

If the organization of x is not 'df.row', then extradata cannot be stored in x and the assignment is ignored, with a warning. First change the organization to 'df.row', and then assign the extradata.

If the organization of x is 'df.row', but value does not have the right number of rows, the assignment is ignored, with a warning.

Value

extradata(x) returns a data.frame with M rows, where M is the number of spectra in x. The rownames are set to the specnames of x. If there is no extra data then the number of columns in this data.frame is 0.

Note

Do not confuse extradata and metadata.
metadata is unstructured data that is attached to the entire colorSpec object. extradata is structured data, with a row of data for each spectrum in the object.

See Also

metadata, organization

Description

F96T12
Sylvania F96T12 CW/VHO 215-Watt fluorescent bulb photon irradiance, measured with a LI-COR LI-1800 spectroradiometer, from 300 to 900 nm at 1 nm intervals.

Format

A colorSpec object organized as a vector, with 601 data points and specnames equal to 'F96T12'.

Details

The unit is ($\mu$mole of photons)$*sec^{-1}*m^{-2}*nm^{-1}$.

Source

Pedro J. Aphalo. https://www.mv.helsinki.fi/home/aphalo/photobio/lamps.html

See Also

ABC , D65 , daylightSpectra

Examples

sum( F96T12 ) 
# [1] 320.1132  photon irradiance, (micromoles of photons)*m^{-2}

sum( radiometric(F96T12) )
# [1] 68.91819  irradiance, watts*m^{-2}

Description

Format

A colorSpec object with quantity equal to 'energy->electrical' and 3 spectra: Red, Green, and Blue.

Details

This data is read from the file Flea2-spectral.txt which was digitized from the plot in Flea2-spectral.png.

Source

https://ptgreycamera.com/product/camera/flir/flea2/firewireb-flea2/fl2-14s3c-c/

See Also

quantity, vignette Blue Flame and Green Comet

Examples

#  Make a scanner from a tungsten source and a Flea2 camera
Flea2.scanner = product( A.1nm, "VARMATERIAL", Flea2.RGB, wavelength=420:680 )
Flea2.scanner = calibrate( Flea2.scanner )

Description

Fs.5nm contains 12 CIE Fluorescent Illuminants, from 380 to 780 nm, at 5nm intervals.

Format

Fs.5nm is a colorSpec object with 12 spectra. It is organized as a data frame with quantity equal to "energy".

Note

The series F illuminants do not seem to be normalized in a consistent way.

Source

http://www.rit-mcsl.org/UsefulData/Fluorescents.htm

See Also

ABC, D50, D65

Examples

#   plot only F4
plot( subset(Fs.5nm,"F4") )

Description

Format

A colorSpec object organized as a matrix with the 4 spectra:

The wavelength is from 300 to 700 nm, at 1nm intervals.

Source

https://onlinelibrary.wiley.com/doi/full/10.1111/j.1095-8312.2005.00540.x

References

Endler & Mielke. Comparing entire colour patterns as birds see them. Biological Journal of the Linnean Society. Volume 86, Issue 4, pages 405-431, December 2005. Original Name of File: BIJ_540_Endler_Mielke_OnlineAppendix.txt.

See Also

lms2000

Examples

summary(HigherPasserines)

Description

Format

A colorSpec object with quantity equal to 'transmittance' and 4 spectra:

Source

https://hoyaoptics.com/

See Also

quantity

Examples

#   compute response of ACES scanner to the Hoya filters
product( Hoya, scanner.ACES, wave='auto' )

Description

interpolate along a 1-parameter path of spectra

Usage

## S3 method for class 'colorSpec'
interpolate( x, p, pout, pname=deparse(substitute(p)) )

Arguments

Details

Each spectrum in x can be thought of as a point in a high-dimensional space, and each point has a real-valued parameter associated with it. The function performs natural spline interpolation on these points, one coordinate at a time. For each wavelength value it calls spline with method='natural'.

Value

interpolate(x) returns a colorSpec object y with a spectrum for each value in pout. The organization of y is 'df.row', and extradata(y) has a single column which is a copy of pout. The name of the column is pname. The names in specnames(y) are <pname>=<pout>. Other properties of y, e.g. wavelength, quantity, ..., are the same as x.
In case of ERROR, the function returns NULL.

See Also

organization, wavelength, extradata, spline

Examples

path = system.file( "extdata/stains/PhenolRed-Fig7.txt", package="colorSpec" )
wave = 350:650
phenolred = readSpectra( path, wavelength=wave )
pH = as.numeric( sub( '[^0-9]+([0-9]+)$', '\\1', specnames(phenolred) ) )
pHvec = seq(min(pH),max(pH),by=0.05)
phenolinterp = interpolate( phenolred, pH, pHvec )

Description

Given a light responder (e.g. an eye or a camera), two light spectra that produce the same response from the responder are called metamers for that responder. Similarly, given a material responder (e.g. a scanner), two reflectance spectra that produce the same response from the responder are called metamers for that responder.

For a given responder and response, there are typically infinitely many metamers. The set of all of them is often called the metameric suite. The goal of the function invert() is to calculate a "good" metamer in the "suite". Koenderink calls this topic inverse colorimetry. In the case that the estimated spectrum is a reflectance spectrum, the topic is often called reflectance estimation or reflectance recovery, see Bianco.

The centroid method, which is the default and the featured method in this package, computes the centroid of the set of all the metamers (if any). The centroid is computed in an infinite-dimensional context and is expounded further in Davis.

The Hawkyard method, see Hawkyard and Bianco, has been around a long time. The centroid and Hawkyard methods have similarities, e.g. both are low-dimensional with the number of variables equal to the number of responses (usually 3). The Hawkyard method is very fast, but has a key problem, see below.

The Transformed Least Slope Squared (TLSS) method was developed by Scott Burns, see References. This is my name for it, not his. What I call TLLS is actually is a combination of Burns' LHTSS and LLSS methods; the one that invert() chooses depends on type(x), see below. Both of these are high-dimensional, with the number of variables equal to #(responses) + #(wavelengths).

The first argument to invert() is the responder x, and the second is the matrix response of responses (e.g. XYZs or RGBs).

The goal is to return a "good" spectrum for each response so that:

The error is returned as column estim.precis, see below.

First consider the case where x has type type='responsivity.material'. The goal is to compute a reflectance spectra. All the methods will fail if the response is on the object-color boundary (an optimal color) or outside the boundary. They may also fail if the response is inside the object-color solid (the Rösch Farbkörper) and very close to the boundary.
The centroid method solves a non-linear system that contains a Langevin-function-based squashing function, see Davis for details. When successful it always returns a feasible spectrum with small estim.precis.
The Hawkyard method is linear and very fast, but in raw form it may return a non-feasible reflectance spectrum. In this case invert() simply clamps to the interval [0,1] and so estim.precis can be large.
The TLSS method solves a non-linear system that contains the squashing function $(\tanh(z) + 1)/2$, see Burns for details. When successful it always returns a feasible spectrum with small estim.precis.

Now consider the case where x has type='responsivity.light'. The goal is to compute the spectrum of a light source. All the methods will fail if chromaticity of the response is on the boundary of the inverted-U (assuming x models the human eye) or outside the boundary. They may also fail if the response is inside the inverted-U and very close to the boundary.
The centroid method works on a relatively small range of chromaticities; it will fail if the response is too far from the response to Illuminant E. See Davis for the details. When successful it always returns an everywhere positive spectrum with small estim.precis. This method has the desirable property that if the response is multiplied by a positive number, the computed spectrum is multiplied by that same number.
The Hawkyard method does not work in this case.
The TLSS method solves a non-linear system that contains the squashing function $\exp(z)$, see Burns for the details. When successful it always returns an everywhere positive spectrum with small estim.precis. This method succeeds on a larger set of chromaticities than the centroid method. It also has the desirable scaling multiplication property mentioned above.

The centroid and Hawkyard methods have an equalization option, which is controlled by the argument alpha and is enabled by default, see below. When enabled, if the response comes from a constant spectrum (a perfectly neutral gray material, or a multiple of Illuminant E), then the computed spectrum is that same constant spectrum (up to numerical precision). I call this the neutral-exact property. Equalization is a complicated mechanism, for details see Davis. For the TLSS method, the neutral-exact property is intrinsic, and alpha is ignored.
NOTE: If the responder has only one output channel (e.g. a monochrome camera) and equalization is enabled, then all responses are inverted to a constant spectrum. This may or may not be desirable.

Usage

## S3 method for class 'colorSpec'
invert( x, response, method='centroid', alpha=1 )

Arguments

Details

For method='centroid' the function calls the non-linear root-finder rootSolve::multiroot(), which is general purpose and "full Newton".

For method='Hawkyard' the function solves a linear system by inverting a small matrix (#[responses] x #[responses]). The spectra are then clamped to [0,1].

For method='TLSS' the function solves a constrained least-squares problem using Lagrange multipliers. A critical point is found using a "full Newton" iteration. The original MATLAB code is posted at Burns, and was ported from MATLAB to R with only trivial changes. When computing a reflectance spectrum, the Hawkyard method is used for the initial guess, after little extra clamping. This improved guess cuts the number of iterations substantially, and the extra computation time is negligible.

Value

If type(x)='responsivity.material' it returns a colorSpec object with type = 'material' (quantity = 'reflectance').

If type(x)='responsivity.light' it returns a colorSpec object with type = 'light' (quantity='energy' or quantity='photons' depending on quantity(x)).

In either case, the returned object has organization = 'df.row' and the extradata is a data.frame with these columns:

If a response could not be estimated, the row contains NA in appropriate columns, and a warning is issued.

In case of global error, the function returns NULL.

Known Issues

If type(x)='responsivity.light' the centroid method may fail (not converge) if the response is too far from that of Illuminant E.

References

Davis, Glenn. A Centroid for Sections of a Cube in a Function Space, with Application to Colorimetry. https://arxiv.org/abs/1811.00990. [math.FA]. 2018.

Bianco, Simone. Reflectance spectra recovery from tristimulus values by adaptive estimation with metameric shape correction. vol. 27, no 8. Journal of the Optical Society of America A. pages 1868-1877. 2010 https://opg.optica.org/josaa/abstract.cfm?uri=josaa-27-8-1868.

Burns, Scott A. Generating Reflectance Curves from sRGB Triplets. http://scottburns.us/reflectance-curves-from-srgb/.

Hawkyard, C. J. Synthetic reflectance curves by additive mixing. Journal of the Society of Dyers and Colourists. vol. 109. no. 10. Blackwell Publishing Ltd. pp. 323-329. 1993.

Koenderink, J.J. Color for the Sciences. MIT Press. 2010.

See Also

type(), quantity(), organization(), specnames(), product(), extradata(), rootSolve::multiroot(), vignette Estimating a Spectrum from its Response

Examples

wave = 400:700
E.eye = product( illuminantE(1,wave), "material", xyz1931.1nm, wavelength=wave )
path = system.file( 'extdata/targets/CC_Avg30_spectrum_CGATS.txt', package='colorSpec' )
MacbethCC = readSpectra( path, wavelength=wave )
XYZ = product( MacbethCC, E.eye, wavelength=wave )
est.eq   = invert( E.eye, XYZ, method='centroid', alpha=1 )
extra   = extradata(est.eq)
range(extra$estim.precis)       # prints   0.000000e+00 3.191741e-08

Description

Some action spectra standards are defined by simple equations; the erythemal spectrum for human sunburn is one of them.

Usage

erythemalSpectrum( wavelength=250:400 )

Arguments

Details

This erythemal spectrum is defined in 4 pieces: $\lambda \le 298$, $298 \le \lambda \le 328$, $328 \le \lambda \le 400$, and $400 < \lambda$. The unit is nm. The spectrum is used in the definition of the international standard UV Index.

Value

For erythemalSpectrum()
A colorSpec object with quantity equal to 'energy->action'. The responsivity is 0 for $\lambda$ > 400 nm, so this putting this spectrum in the category of human vision is a bit of a stretch.

Source

https://en.wikipedia.org/wiki/Ultraviolet_index

References

McKinlay, A.F., and B.L. Diffey. A reference action spectrum for ultraviolet induced erythema in human skin. CIE Res. Note, 6(1), 17-22. (1987)

See Also

daylight, quantity, materialSpectra, lightSpectra

Description

Two families of standard illuminants that are parameterized by temperature are the Planckian spectra (black-body spectra), and daylight spectra. For the daylight spectra, a smoothed version is available. Illuminant E, a third and trivial spectrum, is also available.

Usage

planckSpectra( temperature, wavelength=300:830, normalize=TRUE, c2=1.4388e-2 )

daylightSpectra( temperature, wavelength=NULL, 
                    components=colorSpec::daylight1964, roundMs=FALSE )

illuminantE( energy=1, wavelength=380:780 )

Arguments

Details

For planckSpectra() the valid range of temperatures is 0 to Inf ($\infty$) K, but with exceptions at the endpoints. For a negative temperature the spectrum is set to all NAs.
If temperature=0 and normalize=TRUE, the spectrum is set to all NAs. If temperature=0 and normalize=FALSE, the spectrum is set to all 0s.
Conversely, if temperature=Inf and normalize=FALSE, the spectrum is set to all NAs. If temperature=Inf and normalize=TRUE, the spectrum is set to the pointwise limit $(560/\lambda)^4$ (which appears blue).

For daylightSpectra() the valid range of temperatures is 4000 to 25000 K. For a temperature outside this range the spectrum is set to all NAs.

The equations for daylightSpectra() and planckSpectra() are complex and can be found in the References.

IlluminantE() is trivial - all constant energy.

Value

For planckSpectra() and daylightSpectra() :
A colorSpec object with quantity equal to 'energy', and organization equal to 'matrix' or 'vector'. The specnames are PNNNN or DNNNN for planckSpectra() and daylightSpectra() respectively.
The number of spectra in the object is the number of temperatures = length(temperature).

For illuminantE() :
A colorSpec object with quantity equal to 'energy'.
The number of spectra in the object is the number of energy levels = length(energy).

References

Günther Wyszecki and W.S. Stiles. Color Science : Concepts and Methods, Quantitative Data and Formulae. Second Edition. Wiley-Interscience. 1982. page 146.

CIE 15: Technical Report: Colorimetry, 3rd edition. CIE 15:2004. Table T.1, pp 30-32, and Note 5 on page 69.

Schanda, Janos. CIE Colorimetry, in Colorimetry: Understanding the CIE System. Wiley Interscience. 2007. p. 42.

See Also

daylight, resample, organization, quantity, materialSpectra

Description

linearize spectra and return modified object

Usage

## S3 method for class 'colorSpec'
linearize( x )

Arguments

Details

If the quantity(x) is not 'absorbance' then x is returned unchanged.

If the quantity(x) is 'absorbance' then absorbance is converted to transmittance using

$transmittance = 10^{-absorbance}$

Surprisingly, there does not seem to be a similar logarithmic version of reflectance. Plots with log(responsivity) is somewhat common, but does not seem to have a separate name. I have not seen log(radiometric power).

Value

linearize returns a colorSpec object with linear quantities.

See Also

quantity

Description

Format

A colorSpec object organized as a matrix with 3 columns:

Source

http://www.cvrl.org/database/text/cones/vw.htm

References

Vos, J. J. & Walraven, P. L. On the derivation of the foveal receptor primaries. Vision Research. 11 (1971) pp. 799-818.

See Also

lms2000

Examples

summary(lms1971.5nm)
white.point = product( D65.1nm, lms1971.5nm, wave='auto' )

Description

Format

A colorSpec object organized as a matrix with 3 columns:

Source

http://www.cvrl.org/cones.htm

References

Stockman, A., Sharpe, L. T., & Fach, C. C. (1999). The spectral sensitivity of the human short-wavelength cones. Vision Research. 39, 2901-2927.

Stockman, A., & Sharpe, L. T. (2000). Spectral sensitivities of the middle- and long-wavelength sensitive cones derived from measurements in observers of known genotype. Vision Research. 40, 1711-1737.

See Also

lms1971

Examples

summary(lms2000.1nm)
white.point = product( D65.1nm, lms2000.1nm, wave='auto' )

Description

There is some flexibility in the colorSpec logging level and format. Logging output goes to stderr(), just like the message stream; but see sink() (and the pitfalls of using it).

Logging Options

colorSpec.loglevel

The levels are: "FATAL", "ERROR", "WARN", "INFO", "DEBUG", and "TRACE" - the usual ones from Log4j. The initial level is "WARN". A "FATAL" event usually means an internal package error. When setting colorSpec.loglevel an initial letter is sufficient.

colorSpec.logformat

The format is given by a string with standard Log4j conversion specifications:

%t	the date/time of the logging event.	%t can be followed by standard strftime specs in braces; see example.
%l	the level of the logging event
%n	namespace where event occurred
%f	function where event occurred
%m	the message itself

colorSpec.stoponerror

If the this option is TRUE (the default), a log event with level "ERROR" stops execution; otherwise, execution keeps going. For interactive use, TRUE is probably better. For long batch jobs, FALSE might be appropriate, since then a single error may not force a complete repeat.
A "FATAL" event always stops execution.

References

Wikipedia. Log4j. https://en.wikipedia.org/wiki/Log4j

See Also

options, cs.options, sink, stderr

Examples

options( colorSpec.logformat="%t{%H:%M:%OS3} %l %n::%f(). %m", colorSpec.stoponerror=TRUE )

# or equivalently
cs.options( logformat="%t{%H:%M:%OS3} %l %n::%f(). %m", stop=TRUE )

Description

Format

A colorSpec object, with quantity 'energy->neural', and with 4 spectra:

photopic1924

The luminous efficiency function adopted by the CIE in 1924, and defining the standard photopic observer. It is only to be used when light levels are high enough that the sensitivity of the eye is mediated by cones, and not rods. It is the same as the y-bar function in xyz1931.1nm. It is used to define the candela in the International System (SI) and is the only one of these functions to appear in the SI. It was downloaded from http://www.cvrl.org/database/data/lum/vl1924e_1.csv where it is defined from 360 to 830 nm.

scotopic1951

The luminous efficiency function adopted by the CIE in 1951, and defining the standard scotopic observer. It is only to be used when light levels are low enough to exclude the activation of cones. It has no effective role in colorimetry. It was downloaded from http://www.cvrl.org/database/data/lum/scvle_1.csv where it is defined from 380 to 780 nm. It has been padded with 0s to 360 to 830 nm.

photopic1978

The luminous efficiency function for photopic vision, with adjustments in the blue region by Judd (1951) and Vos (1978). It was published by the CIE in 1988. It was downloaded from http://www.cvrl.org/database/data/lum/vme_1.csv where it is defined from 380 to 780 nm. It has been padded with 0s to 360 to 830 nm.

photopic2008

The CIE (2008) physiologically-relevant luminous efficiency function for photopic vision, by Stockman, Jagle, Pirzer, & Sharpe. It was downloaded from http://www.cvrl.org/database/data/lum/linCIE2008v2e_1.csv where it is defined from 390 to 830 nm. It has been padded with 0s to 360 to 830 nm.

Note

Luminsivity is a self-coined portmanteau word: luminsivity = luminous * responsivity. The word is unrelated to emissivity. The term luminous responsivity is not common, but appears on page 15 of Grum. The term luminous efficiency function is standard, but too long. The term luminosity function is common, but luminosity is ambiguous and also appears in astronomy and scattering theory.
The object luminsivity.1nm is used by the function photometric().

Source

Colour & Vision Research Laboratory. Institute of Opthalmology. University College London. UK. http://www.cvrl.org/

References

Grum, Franc and Richard J. Becherer. Radiometry. Optical Radiation Measurements, Volume 1. Academic Press. 1979.

Stockman, A., Jagle, H., Pirzer, M., & Sharpe, L. T. (2008). The dependence of luminous efficiency on chromatic adaptation. Journal of Vision, 8, 16:1, 1-26.

See Also

xyz1931.1nm, photometric

Examples

summary(luminsivity.1nm)
product( D65.1nm, luminsivity.1nm, wave='auto' )

Description

Compute neutral gray material constant reflectance/transmittance, and rectangular spectra. Also compute absorbance of the human lens, as a function of age.

Usage

neutralMaterial( gray=1, wavelength=380:780 )
rectangularMaterial( lambda, alpha=1, wavelength=380:780 )

lensAbsorbance( age=32, wavelength=400:700 )

Arguments

Details

A rectangular spectrum, or rectangular metamer, is easiest to define when $\alpha=1$ and $\lambda_1 < \lambda_2$. In this case it is a band-pass filter with transmittance=1 for $\lambda \in [\lambda_1 , \lambda_2]$ and transmittance=0 otherwise. To create a long-pass filter, just set $\lambda_2$ to Inf, or any large wavelength outside the spectrum range; and similarly for a short-pass filter.
When $0<\alpha<1$ the spectrum is a weighted mixture of this band-pass filter with a perfect neutral gray filter with transmittance=0.5 at all $\lambda$, using $\alpha$ and $1-\alpha$ as the two weights. The minimum transmittance is $(1-\alpha)/2$ and the maximum is $(1+\alpha)/2$, and their difference, the chromatic amplitude, is $\alpha$. It is still a band-pass filter.
If $\alpha=0$ the spectrum is a perfect neutral with transmittance=0.5.
To "flip" the spectrum to its complement (change band-pass to band-stop, etc.), change $\alpha$ to a negative number, or swap $\lambda_1$ and $\lambda_2$. If $\lambda_1==\lambda_2$ then the spectrum is undefined and a warning is issued (unless $\alpha=0$).

Value

neutralMaterial() returns a colorSpec object with quantity equal to 'reflectance'. The reflectance of each spectrum is constant and taken from gray. There are N spectra in the object - one for each gray level.

rectangularMaterial() returns a colorSpec object with quantity equal to 'transmitance'. The transmitance of each spectrum is a step function with 0, 1 or 2 transitions (jumps) defined by the corresponding row in lambda. If rownames(lambda) is not NULL, they are copied to specnames of the output. Otherwise the specnames are computed from the shape of the spectrum using these acronyms: LP (long-pass), SP (short-pass), BP (band-pass), BS (band-stop), and N (neutral, in case alpha==0).

lensAbsorbance() returns a colorSpec object with quantity equal to 'absorbance'. The absorbance model for the human lens is taken from Pokorny. There are N spectra in the object - one for each age (N=length(age)).

Logvinenko

It is clear that there are 3 degrees-of-freedom in the spectra returned by rectangularMaterial(). Logvinenko shows that these spectra in fact form a 3D ball, which he calls the rectangle color atlas. He also shows that if a material responder satisfies the 2-transition condition, then these spectra uniquely generate all colors in the corresponding object color solid. For more on this, see the vignette Estimating a Spectrum from its Response.

Ostwald

Every spectrum returned by rectangularMaterial() is an Ostwald ideal spectrum. In Ostwald's terminology, the color content = chromatic amplitude = $\alpha$. And the black content = white content = $(1-\alpha)/2$. Note that the sum of these 3 contents is 1. However, Ostwald allows black content and white content to be unequal, as long as the sum of the 3 contents is 1, and all are non-negative. Thus there is one extra degree-of-freedom for Ostwald's ideal spectra, for a total of 4 degrees-of-freedom. If an additional argument (or arguments) were added to rectangularMaterial(), then it could return all Ostwald ideal spectra.

References

Foss, Carl E. and Dorothy Nickerson and Walter C. Granville. Analysis of the Ostwald Color System. J. Opt. Soc. Am.. vol. 34. no. 7. pp. 361-381. July, 1944.

Logvinenko, A. D. An object-color space. Journal of Vision. 9(11):5, 1-23, (2009).
https://jov.arvojournals.org/article.aspx?articleid=2203976. doi:10.1167/9.11.5.

Pokorny, Joel, Vivianne C. Smith, and Margaret Lutze. Aging of the Human Lens. Applied Optics. Vol. 26, No. 8. 15 April 1987. Table I. Page 1439.

See Also

lightSpectra, quantity(), specnames(), computeADL(), vignette Estimating a Spectrum from its Response

Examples

#   make a perfect reflecting diffuser (PRD)
prd = neutralMaterial( 1 )

#   make a perfect transmitting filter (PTF)
ptf = prd
quantity(ptf) = 'transmittance'

#   make a band-stop filter (for interval [500,550])
#   with 1% transmittance in the band, and 99% outside the band
bs = rectangularMaterial( c(500,550), -0.98, 400:700 )
bs = rectangularMaterial( c(550,500),  0.98, 400:700 )  # equivalent to previous line

#   compare transmittance at 3 ages: 20, 32, and 80 years
plot( linearize(lensAbsorbance( c(20,32,80) )), col='black', lty=1:3 )

Description

compute mean of all spectra in a colorSpec object

Usage

## S3 method for class 'colorSpec'
mean( x, ... )

Arguments

Details

This function might be useful when capturing many spectra on a spectrometer and averaging them to reduce noise.

Value

a colorSpec object with single spectrum = average of all spectra in colorSpec.

Description

Retrieve or set the metadata of a colorSpec object.

Usage

## S3 method for class 'colorSpec'
metadata(x, ...)

## S3 replacement method for class 'colorSpec'
metadata(x, add=FALSE ) <- value

Arguments

Details

The metadata list is stored as attr(x,'metadata'). After construction this list is empty.

Value

metadata(x) with no additional arguments returns the complete named list of metadata. If arguments are present, then only those metadata items are returned.

Note

Do not confuse extradata and metadata.
metadata is unstructured data that is attached to the entire colorSpec object. extradata is structured data, with a row of data for each spectrum in the object.

See Also

extradata, modifyList

Examples

## Not run: 
# get list of *all* metadata
metadata(x)

# get just the file 'path'
metadata( x, 'path' )

# set the 'date'
metadata( x ) = list( date="2016-04-01" )

## End(Not run)

Description

multiply spectra by coefficients and return modified object

Usage

## S3 method for class 'colorSpec'
multiply( x, s )

## S3 method for class 'colorSpec'
normalize( x, norm='L1' )

Arguments

Details

For multiply():
If s is an MxP matrix, say S, and one thinks of the spectra as organized in an NxM matrix X, then the new spectra are defined by the matrix XS, which is NxP. If the P column names of s are set, then they are copied to the specnames of the output. Otherwise, default spectrum names are assigned as in colorSpec(), with a warning.
If s is an M-vector, then S=diag(s) is computed and used in the previous sentence. This has the effect of multiplying spectrum i by s[i].
If s is a scalar then every spectrum is multiplied by s.
The multiplication may produce negative entries, but no check is made for this.
WARNING: An M-vector and an Mx1 matrix may yield quite different results.

For normalize():
normalize() calls multiply() with s = an M-vector. If the norm of a spectrum is 0, then it is left unchanged.

Value

multiply returns a colorSpec object with the matrix of spectra of x multiplied by s.

normalize returns a colorSpec object with each spectrum of x scaled to have given norm equal to 1.

In both functions, the quantity and wavelength are preserved.

Note

If x is organized as a matrix, and s is a scalar, the one can use the simpler and equivalent s*x.

See Also

product(), quantity(), wavelength(), specnames(), colorSpec()

Description

In careful calcuations with standard illuminants, it is often helpful to have the 'official' values of XYZ, i.e. with the right number of decimal places.

Usage

officialXYZ( name )

Arguments

Details

All XYZ values are taken from the ASTM publication in References, except B which is taken from Wyszecki & Stiles and D50.ICC which is taken from ICC publications. The latter is different than that of ASTM.

Value

An Mx3 matrix where M is the length of name. Each row filled with the official XYZ, but if the illuminant name is not recognized the row is all NAs. The matrix rownames are set to name, and colnames to c('X','Y','Z').

WARNING

This function is deprecated. New software should use spacesRGB::standardXYZ() instead.

Note

The input names are case-sensitive. The output XYZ is normalized so that Y=1.

References

ASTM E 308 - 01. Standard Practice for Computing the Colors of Objects by Using the CIE System. (2001).

Günther Wyszecki and W. S. Stiles. Color Science: Concepts and Methods, Quantitative Data and Formulae, Second Edition. John Wiley & Sons, 1982. Table I(3.3.8) p. 769.

See Also

ABC, D50, D65, Fluorescents, illuminantE

Examples

officialXYZ( c('A','D50','D50.ICC','D65') ) 
#                 X Y         Z
# A       1.0985000 1 0.3558500
# D50     0.9642200 1 0.8252100
# D50.ICC 0.9642029 1 0.8249054
# D65     0.9504700 1 1.0888300

Description

Retrieve or set the organization of a colorSpec object.

Usage

## S3 method for class 'colorSpec'
organization(x)

## S3 replacement method for class 'colorSpec'
organization(x) <- value

Arguments

Details

If organization(x) is "vector", then x is a vector representing a single spectrum. Compare this with stats::ts().

If organization(x) is "matrix", then x is a matrix and the spectra are stored in the columns.

If organization(x) is "df.col", then x is a data.frame with M+1 columns, where M is the number of spectra. The wavelengths are stored in column 1, and the spectra in columns 2:(M+1). This organization is good for printing to the console, and writing to files.

If the organization of x is "df.row", then x is a data.frame with N rows, where N is the number of spectra. The spectra are stored in the last column, which is a matrix with the name "spectra". The other columns preceding spectra (if present) contain extra data associated with the spectra; see extradata.

Value

organization(x) returns a valid organization: 'vector', 'matrix', 'df.col', or 'df.row'.

Note

In organization(x) <- value
if x has more than 1 spectrum, then value equal to 'vector' is invalid and ignored.
If organization(x) is equal to 'df.row' and also has extradata, then changing the organization silently discards the extradata.

See Also

colorSpec; extradata

Examples

organization(Hoya)              # returns 'df.row'
organization(Hoya) = 'matrix'   # extradata in Hoya is silently discarded

Description

Convert radiometric units of power or energy to photometric units, using 4 standard photometric weighting curves. Actinometric units (number of photons) are converted to radiometric units (energy of photons) on-the-fly.

Usage

## S3 method for class 'colorSpec'
photometric( x, photopic=683, scotopic=1700, multiplier=1 )

Arguments

Details

The function computes the product of x with luminsivity.1nm. This product is an Mx4 matrix, where M is the number of spectra in x. There are 3 columns for photopic vision, and 1 column for scotopic vision. These columns are multiplied by the appropriate conversion factors and the resulting Mx4 matrix is returned.

The 5 power-based input quantities and corresponding photometric outputs are:

The 2 common energy-based input quantities and corresponding photometric outputs are:

and there are 3 more obtained by integrating over time. For example "time-integrated radiance" —> "time integrated luminance". But I have not been able to find names for these 3. The talbot is the unofficial name for a lumen-second.

Value

photometric() returns an Mx4 matrix, where M is the number of spectra in x. The rownames are specnames(x), and the colnames are specnames(luminsivity.1nm).
In case of ERROR it returns NULL.

Note

To get the right output quantity and units, the user must know the input quantity and units. If the units are different than those in the above list, then set multiplier appropriately.
It is up to the user to determine whether photopic or scotopic vision (or neither) is appropriate. The intermediate mesopic vision is currently a subject of research by the CIE, and might be added to this function in the future.

References

Poynton, Charles. Digital Video and HD - Algorithms and Interfaces. Morgan Kaufmann. Second Edition. 2012. Appendix B, pp. 573-580.

See Also

quantity, type, luminsivity.1nm, radiometric

Examples

photometric( solar.irradiance )  # unit is watt*m^{-2}

#             photopic1924 scotopic1951 photopic1978 photopic2008  # units are lux
# AirMass.0      133100.41     313883.2    133843.65     140740.3
# GlobalTilt     109494.88     250051.5    110030.31     115650.0
# AirMass.1.5     97142.25     215837.1     97571.57     102513.7

Description

plot the spectra in a colorSpec object as lines or points

Usage

## S3 method for class 'colorSpec'
plot( x, color=NULL, subset=NULL, main=TRUE, legend=TRUE, CCT=FALSE, add=FALSE, ... )

Arguments

Details

Commonly used graphical parameters are:

type

passed to lines.default(), with default type='l'. Other valid values are 'p' (points), 'b', 'c', 'o', 'h', 'S', 's', and 'n', see plot() for their meanings.
An additional type='step' is available. This option draws each spectrum as a step function, similar to 'S' and 's', except that the jumps are between the wavelengths (with appropriate extensions at min and max wavelengths). The function segments() is used for the drawing. For type='step', lwd and lty should be vectors of length 1 or 2. If the length of lwd is 1, then horizontal segments are draw with that width, but vertical segments are not drawn. If the length of lwd is 2, then vertical segments are draw with width lwd[2]. If the length of lty is 2, then the styles are applied to the horizontal and vertical segments in that order. If the length of lty is 1, then that style is applied to both horizontal and vertical segments. For examples of this plotting option, see the vignette Convexity and Transitions.

lwd, lty

passed to lines.default(), except when type='step' when they are passed to segments(). In the former case these can be vectors, and components are passed sequentially to each spectrum, similar to matplot(). In the latter case, see the description in type. The default value for both is 1.

pch

passed to lines.default(), but it only has meaning when type='p', 'b', or 'o'. This can be a vector, and components are passed sequentially to each spectrum.

ylab

If ylab is a string then it is passed on to plot.default(), otherwise suitable default string is generated.

xlim, ylim

If xlim and ylim are 2-vectors, they are passed to plot.default. If one of the components is NA then a suitable default is supplied.

log

passed on to plot.default(). Care must be taken for y because many spectra are 0 at some wavelengths, and even negative. Use ylim in such cases.

Value

TRUE or FALSE

See Also

computeCCT(), subset(), lines(), segments(), plot(), matplot(), colorRamp()

Examples

plot( 100 * BT.709.RGB )
plot( xyz1931.1nm, add=TRUE, lty=2, legend=FALSE )

Description

Consider a colorSpec object x with type equal to 'responsivity.material' and 3 responsivity spectra. The function plotOptimals3D() makes a plot of the object-color solid for x. This solid is a zonohedron in 3D. The 3D drawing package rgl is required.
Consider a colorSpec object x with type equal to 'responsivity.material' and 2 responsivity spectra. The function plotOptimals2D() makes a plot of the object-color solid for x. This solid is a zonogon in 2D. The 3D drawing package rgl is not required.
The set of all possible material reflectance functions (or transmittance functions) is convex, closed, and bounded (in any reasonable function space), and this implies that the set of all possible output responses from x is also convex, closed, and bounded. The latter set is called the object-color solid, or Rösch Farbkörper, for x. A color on the boundary of the object-color solid is called an optimal color. For more discussion see sectionOptimalColors().

Usage

## S3 method for class 'colorSpec'
plotOptimals3D( x, size=50, type='w', both=TRUE )

## S3 method for class 'colorSpec'
plotOptimals2D( x )

Arguments

Value

The functions return TRUE or FALSE.

Details for 3D

If n is the number of wavelengths, the number of parallelogram faces of the zonohedron is n*(n-1). The time to compute these faces increase with n even faster, so that is why the default size=50 is a fairly small number. It was chosen to be a reasonable compromise between detail and performance.
In addition to the wireframe or points, it draws the box with opposite vertices at the "poles" 0 and W and the diagonal segment of neutral grays that connects 0 and W.

Details for 2D

If n is the number of wavelengths, the number of edges in the zonogon is 2*n. Computing these edges is fast and visualization is easy, so there are no plotting options at this time.

Note

If all responsivity functions of x are non-negative, the object-color solid of x is inside the box. If the responsivity functions of x have negative lobes, the object-color solid of x extends outside the box. Indeed, the box may actually be inside the optimals.

References

Centore, Paul. A Zonohedral Approach to Optimal Colours. Color Research & Application. Vol. 38. No. 2. pp. 110-119. April 2013.

Logvinenko, A. D. An object-color space. Journal of Vision. 9(11):5, 1-23, (2009).
https://jov.arvojournals.org/article.aspx?articleid=2203976. doi:10.1167/9.11.5.

West, G. and M. H. Brill. Conditions under which Schrödinger object colors are optimal. Journal of the Optical Society of America. 73. pp. 1223-1225. 1983.

See Also

type(), probeOptimalColors(), sectionOptimalColors(), vignette Plotting Chromaticity Loci of Optimal Colors

Examples

human = product( D50.5nm, 'slot', xyz1931.5nm, wave=seq(400,770,by=5) )
plotOptimals3D( human )

plotOptimals2D( subset(human,2:3) )     # y and z only

scanner = product( D50.5nm, 'slot', BT.709.RGB, wave=seq(400,770,by=5) )
plotOptimals3D( scanner )

Description

display a colorSpec object as readable text. Output goes to stdout().

Usage

## S3 method for class 'colorSpec'
print( x, ...)

## S3 method for class 'colorSpec'
summary( object, long=TRUE, ... )

Arguments

Details

If long=FALSE, summary() prints a summary of the wavelength vector, and names of all spectra. For each spectrum it prints the range of values, LambdaMax, and extradata if any. If long=TRUE it also prints data listed above (if any).
The function print() simply calls summary() with long=FALSE.

Value

Both functions return (invisibly) the character vector that was just printed to stdout().

See Also

extradata, print, summary, stdout

Examples

print( xyz1931.1nm )

xyz1931.1nm     # same thing, just calls print()

Description

Consider a colorSpec object x with type equal to 'responsivity.material'. The set of all possible material reflectance functions (or transmittance functions) is convex, closed, and bounded (in any reasonable function space), and this implies that the set of all possible output responses from x is also convex, closed, and bounded. The latter set is called the object-color solid or Rösch Farbkörper for x. A color on the boundary of the object-color solid is called an optimal color. The special points W (the response to the perfect reflecting diffuser) and 0 are on the boundary of this set. The interior of the line segment of neutrals joining 0 to W is in the interior of the object-color solid. It is natural to parameterize this segment from 0 to 1 (from 0 to W).

A ray $r$ that is based at a point on the interior of the neutral line segment must intersect the boundary of the object-color solid in a unique optimal color. The purpose of the function probeOptimalColors() is to compute that intersection point.

Currently the function only works if the number of spectra in x is 3 (e.g. RGB or XYZ).

Before colorSpec v 0.8-1 this function used a 2D root-finding method that could only find optimal colors whose spectra contain 0, 1, or 2 transitions. But starting with v0.8-1, we have switched to zonohedral representation of the object-color solid, which makes it possible to discover more than 2 transitions. The inspiration for this change is the article by Centore. To inspect these computed spectra, the argument spectral must be set to TRUE.

Usage

## S3 method for class 'colorSpec'
probeOptimalColors( x, gray, direction, aux=FALSE, spectral=FALSE, tol=1.e-6 )

Arguments

Details

Each gray level and each direction defines a ray. So the total number of rays traced is length(gray) * nrow(direction). The 3 responsivities are regarded not as continuous functions, but as step functions. This implies that the color solid is a zonohedron. In the preprocessing phase the zonohedral representation is calculated. The faces of the zonohedron are either parallelograms, or compound faces that can be partitioned into parallelograms. The centers of all these parallelograms are computed, along with their normals and plane constants.
This representation of the color solid is very strict regarding the 2-transition assumption. During use, one can count on there being some spectra with more than two transitions. Forcing the best 2-transition spectrum is a possible topic for the future.

Value

If argument spectral=FALSE, probeOptimalColors() returns a data.frame with a row for each traced ray. There are length(gray) * nrow(direction) rays. The columns in the output are:

If aux is TRUE, these auxiliary columns related to performance and diagnostics are added:

If argument spectral=TRUE, probeOptimalColors() returns a colorSpec object with quantity 'reflectance'. This object contains the optimal spectra, and can be used to inspect the spectra with more than 2 transitions, which will happen. The above-mentioned data.frame can then be obtained by applying extradata() to the returned object.