CCT: Compute Correlated Color Temperature (CCT) and Points on the...
In spacesXYZ: CIE XYZ and some of Its Derived Color Spaces
Correlated Color Temperature R Documentation
Compute Correlated Color Temperature (CCT) and Points on the Planckian Locus
Description
Compute the CCT in Kelvin, of XYZ, xy, and uv, by multiple methods.
And compute points on the Planckian locus.
The reference Planckian locus is defined spectrally - from
the famous equation for the Planckian radiator
(with c_2 = 1.4388 \times 10^{-2})
and from the tabulated CIE 1931 standard observer color matching functions,
from 360 to 830nm in 1nm steps.
The reference locus is a C^∞ curve, parameterized by temperature,
in a 2D chromaticity space,
usually either xy (1931) or uv (1960).
Computing uv values (and derivatives) is lengthy because there are 471 wavelengths.
An approximation to the reference locus is desirable.
The default locus approximation is a spline
(using stats::splinefun() with method="fmm")
through the 31 uv locus points in Robertson and Wyszecki & Stiles.
This spline does not appear in Robertson, but I think he would approve of it.
It has C^2 continuity and good agreement with the reference locus.
The maximum RMS error in the uv-plane is about 7.3 \times 10^{-6}
over the valid temperature interval [1667,∞] K.
A similar piecewise-linear interpolating path has a maximum RMS error about 10 times larger.
The 31 uv values in the table are accurate to the given 5 decimal places
(but see Note), and the rounding to 5 places is a big limitation in accuracy.
The locus is parameterized directly by reciprocal color temperature (10^6/T),
and therefore indirectly by T.
We call either of these the native pameterization of the locus.
See Planckian Loci.
The lines that are perpendicular to the locus are called the native isotherms.
The second available locus is a quintic spline through 65 points (knots),
that were computed and saved with full precision.
The maximum RMS error in the uv-plane is about 7.2 \times 10^{-12}
over the valid temperature interval [1000,∞] K.
For this one the 1st and 2nd derivatives were also computed,
so the normal vectors at the knots are accurate,
and the curve is also C^2.
See Planckian Loci.
The lines that are perpendicular to the locus are also called the native isotherms.
Two more families of isotherms are available.
The Robertson isotherms are tabulated just like the points on the locus,
and a special linear interpolation is used for intermediate temperatures.
The McCamy isotherms are defined by a single cubic rational function in xy,
and no interpolation is necessary.
Each isotherm family induces a slightly different parameterization of the locus -
the temperature at a locus point is the temperature of the isotherm
passing through that point.
The Robertson parameterization is only continuous of class C^0,
but the geometric continuity class is G^2.
The McCamy parameterization is as smooth as the locus itself, which is C^2.
For the Robertson parameterization the
valid temperature interval is [1667,∞] K.
For the McCamy parameterization the valid temperature interval
is at most [1621,34530] K, and may be smaller depending on the locus.
Usage
CCTfromXYZ( XYZ, isotherms='robertson', locus='robertson', strict=FALSE )
CCTfromxy( xy, isotherms='robertson', locus='robertson', strict=FALSE )
CCTfromuv( uv, isotherms='robertson', locus='robertson', strict=FALSE )
planckLocus( temperature, locus='robertson', param='robertson', delta=0, space=1960 )
Arguments
XYZ
a numeric Mx3 matrix with XYZ tristimulus values (CIE 1931) in the rows,
or a numeric vector that can be converted to such a matrix, by row.
xy
a numeric Mx2 matrix with xy chromaticity values (CIE 1931) in the rows,
or a numeric vector that can be converted to such a matrix, by row.
uv
a numeric Mx2 matrix with uv chromaticity values (CIE UCS 1960) in the rows,
or a numeric vector that can be converted to such a matrix, by row.
isotherms
A character vector whose elements match one
of the available isotherm families:
'robertson', 'mccamy', and 'native'.
Matching is partial and case-insensitive.
When more than one family is given, a matrix is returned, see Value.
When isotherms='native' the isotherms are defined implicitly
as lines perpendicular to the locus, see Details.
The character NA (NA_character_) is taken as
a synonym for 'native'.
locus
valid values are 'robertson' and 'precision', see above.
Matching is partial and case-insensitive.
strict
The CIE considers the CCT of a chromaticity uv to be meaningful only
if the distance from uv to the Planckian locus is less than or equal to 0.05
[in CIE UCS 1960].
If strict=FALSE, then this condition is ignored.
Otherwise, the distance is computed along the corresponding isotherm,
and if it exceeds 0.05 the returned CCT is set to NA.
temperature
a M-vector of temperatures (in K) at which to compute points on the
Planckian locus, either for uv, u'v', or xy; see space.
param
the desired parameterization of the locus.
It can be either 'native', or a parameterization induced by the
'robertson' or 'mccamy' isotherms.
The character NA (NA_character_) is taken as
a synonym for 'native'.
delta
a vector of offset distances in uv (CIE UCS 1960),
along the corresponding isotherms, from the locus.
Positive offsets are above the locus, and negative are below.
delta can have length M or 1, where M is the length of temperature.
If delta has length 1, that value is replicated to length M.
space
the year of the chromaticity space to return.
Valid values are 1960 (the default uv),
1976 (u'v'), and 1931 (xy).
Details
Each of the isotherm families correspond to a parameterization of the locus.
All this is designed so a round trip:
temperature \rarrow uv \rarrow CCT
(with the same choice of isotherm/parameterization)
has neglible error.
When isotherms='native'
the tangent line at a point on the locus is computed using the deriv=1 argument to
stats::splinefun()
and the normal line - the isotherm at the point - is then easily computed from the tangent line.
When isotherms='robertson' or isotherms='mccamy' the locus curve
has no effect on the computed CCT.
The locus is only used when computing the distance from the given uv point to the locus
(along the corresponding isotherm),
and therefore only affects the decision whether the CCT is meaningful
when strict=TRUE.
Value
CCTfromXYZ(), CCTfromxy(), and CCTfromuv()
return a numeric vector of length M, or an MxN matrix.
It returns a matrix iff length(isotherms) = N ≥ 2,
and the column names are set to the isotherm family names.
The names or rownames are set to the rownames of the input.
In case of error, the element of the vector or matrix is set to NA_real_.
In case there is an error in the arguments, the functions return NULL.
In these functions, the locus is not used unless
isotherms='native' or strict=TRUE.
planckLocus() returns an Mx2 matrix with chromaticies in the rows.
The column names are set appropriately for the value of space.
The row names are set from temperature.
In case of a single error, both entries in the row are set to NA_real_.
In case there is an error in the arguments, the functions return NULL.
Note
The lookup table on page 228 in Wyszecki & Stiles
contains an error at 325 mired,
which was corrected by Bruce Lindbloom (see Source).
Source
http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_T.html
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
stats::splinefun(),
colorSpec::computeCCT(),
RobertsonLocus,
PrecisionLocus,
the vignette Correlated Color Temperature Isotherms
Examples
# do a round trip and then compare
temperature = c(5003,6504)
uv = planckLocus( temperature, delta=0.05 )
CCTfromuv( uv ) - temperature
## 2.772227e-05 5.094369e-05
# find some points on the daylight locus, and then their CCT
temperature = seq( 2000, 10000, by=1000 )
xy = daylightLocus( temperature )
cbind( xy, CCT=CCTfromxy(xy,iso='mccamy') )
## x y CCT
## D2000 NA NA NA
## D3000 NA NA NA
## D4000 0.3823436 0.3837663 4005.717
## D5000 0.3457410 0.3586662 4999.998
## D6000 0.3216915 0.3377984 5999.437
## D7000 0.3053570 0.3216459 6997.542
## D8000 0.2937719 0.3092195 7985.318
## D9000 0.2852645 0.2995816 8948.809
## D10000 0.2787996 0.2919672 9881.115
# compare all 3 different isotherms
CCTfromxy( xy, isotherms=c('robertson',NA,'mccamy') )
## Robertson native McCamy
## D2000 NA NA NA
## D3000 NA NA NA
## D4000 4000.096 4000.062 4005.717
## D5000 4999.749 4999.608 4999.998
## D6000 5998.015 5999.242 5999.437
## D7000 6997.858 6998.258 6997.542
## D8000 7997.599 7996.985 7985.318
## D9000 8999.301 8993.811 8948.809
## D10000 9991.920 9992.672 9881.115
cbind( default=CCTfromxy(xy), prec.native=CCTfromxy(xy,locus='prec',iso=NA) )
## default prec.native
## 2000K NA NA
## 3000K NA NA
## 4000K 4000.096 4000.052
## 5000K 4999.749 4999.767
## 6000K 5998.015 5999.097
## 7000K 6997.858 6997.857
## 8000K 7997.599 7997.951
## 9000K 8999.301 8995.835
## 10000K 9991.920 9992.839
spacesXYZ documentation built on April 1, 2022, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Correlated Color Temperature | R Documentation |
Compute Correlated Color Temperature (CCT) and Points on the Planckian Locus
Description
Compute the CCT in Kelvin, of XYZ, xy, and uv, by multiple methods. And compute points on the Planckian locus.
The reference Planckian locus is defined spectrally - from the famous equation for the Planckian radiator (with c_2 = 1.4388 \times 10^{-2}) and from the tabulated CIE 1931 standard observer color matching functions, from 360 to 830nm in 1nm steps. The reference locus is a C^∞ curve, parameterized by temperature, in a 2D chromaticity space, usually either xy (1931) or uv (1960). Computing uv values (and derivatives) is lengthy because there are 471 wavelengths. An approximation to the reference locus is desirable.
The default locus approximation is a spline
(using stats::splinefun() with method="fmm")
through the 31 uv locus points in Robertson and Wyszecki & Stiles.
This spline does not appear in Robertson, but I think he would approve of it.
It has C^2 continuity and good agreement with the reference locus.
The maximum RMS error in the uv-plane is about 7.3 \times 10^{-6}
over the valid temperature interval [1667,∞] K.
A similar piecewise-linear interpolating path has a maximum RMS error about 10 times larger.
The 31 uv values in the table are accurate to the given 5 decimal places
(but see Note), and the rounding to 5 places is a big limitation in accuracy.
The locus is parameterized directly by reciprocal color temperature (10^6/T),
and therefore indirectly by T.
We call either of these the native pameterization of the locus.
See Planckian Loci.
The lines that are perpendicular to the locus are called the native isotherms.
The second available locus is a quintic spline through 65 points (knots), that were computed and saved with full precision. The maximum RMS error in the uv-plane is about 7.2 \times 10^{-12} over the valid temperature interval [1000,∞] K. For this one the 1st and 2nd derivatives were also computed, so the normal vectors at the knots are accurate, and the curve is also C^2. See Planckian Loci. The lines that are perpendicular to the locus are also called the native isotherms.
Two more families of isotherms are available.
The Robertson isotherms are tabulated just like the points on the locus,
and a special linear interpolation is used for intermediate temperatures.
The McCamy isotherms are defined by a single cubic rational function in xy,
and no interpolation is necessary.
Each isotherm family induces a slightly different parameterization of the locus -
the temperature at a locus point is the temperature of the isotherm
passing through that point.
The Robertson parameterization is only continuous of class C^0,
but the geometric continuity class is G^2.
The McCamy parameterization is as smooth as the locus itself, which is C^2.
For the Robertson parameterization the
valid temperature interval is [1667,∞] K.
For the McCamy parameterization the valid temperature interval
is at most [1621,34530] K, and may be smaller depending on the locus.
Usage
CCTfromXYZ( XYZ, isotherms='robertson', locus='robertson', strict=FALSE ) CCTfromxy( xy, isotherms='robertson', locus='robertson', strict=FALSE ) CCTfromuv( uv, isotherms='robertson', locus='robertson', strict=FALSE ) planckLocus( temperature, locus='robertson', param='robertson', delta=0, space=1960 )
Arguments
XYZ |
a numeric Mx3 matrix with XYZ tristimulus values (CIE 1931) in the rows, or a numeric vector that can be converted to such a matrix, by row. |
xy |
a numeric Mx2 matrix with xy chromaticity values (CIE 1931) in the rows, or a numeric vector that can be converted to such a matrix, by row. |
uv |
a numeric Mx2 matrix with uv chromaticity values (CIE UCS 1960) in the rows, or a numeric vector that can be converted to such a matrix, by row. |
isotherms |
A character vector whose elements match one
of the available isotherm families:
|
locus |
valid values are |
strict |
The CIE considers the CCT of a chromaticity |
temperature |
a M-vector of temperatures (in K) at which to compute points on the
Planckian locus, either for |
param |
the desired parameterization of the locus.
It can be either |
delta |
a vector of offset distances in |
space |
the year of the chromaticity space to return.
Valid values are 1960 (the default |
Details
Each of the isotherm families correspond to a parameterization of the locus. All this is designed so a round trip: temperature \rarrow uv \rarrow CCT (with the same choice of isotherm/parameterization) has neglible error.
When isotherms='native'
the tangent line at a point on the locus is computed using the deriv=1 argument to
stats::splinefun()
and the normal line - the isotherm at the point - is then easily computed from the tangent line.
When isotherms='robertson' or isotherms='mccamy' the locus curve
has no effect on the computed CCT.
The locus is only used when computing the distance from the given uv point to the locus
(along the corresponding isotherm),
and therefore only affects the decision whether the CCT is meaningful
when strict=TRUE.
Value
CCTfromXYZ(), CCTfromxy(), and CCTfromuv()
return a numeric vector of length M, or an MxN matrix.
It returns a matrix iff length(isotherms) = N ≥ 2,
and the column names are set to the isotherm family names.
The names or rownames are set to the rownames of the input.
In case of error, the element of the vector or matrix is set to NA_real_.
In case there is an error in the arguments, the functions return NULL.
In these functions, the locus is not used unless
isotherms='native' or strict=TRUE.
planckLocus() returns an Mx2 matrix with chromaticies in the rows.
The column names are set appropriately for the value of space.
The row names are set from temperature.
In case of a single error, both entries in the row are set to NA_real_.
In case there is an error in the arguments, the functions return NULL.
Note
The lookup table on page 228 in Wyszecki & Stiles contains an error at 325 mired, which was corrected by Bruce Lindbloom (see Source).
Source
http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_T.html
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
stats::splinefun(),
colorSpec::computeCCT(),
RobertsonLocus,
PrecisionLocus,
the vignette Correlated Color Temperature Isotherms
Examples
# do a round trip and then compare
temperature = c(5003,6504)
uv = planckLocus( temperature, delta=0.05 )
CCTfromuv( uv ) - temperature
## 2.772227e-05 5.094369e-05
# find some points on the daylight locus, and then their CCT
temperature = seq( 2000, 10000, by=1000 )
xy = daylightLocus( temperature )
cbind( xy, CCT=CCTfromxy(xy,iso='mccamy') )
## x y CCT
## D2000 NA NA NA
## D3000 NA NA NA
## D4000 0.3823436 0.3837663 4005.717
## D5000 0.3457410 0.3586662 4999.998
## D6000 0.3216915 0.3377984 5999.437
## D7000 0.3053570 0.3216459 6997.542
## D8000 0.2937719 0.3092195 7985.318
## D9000 0.2852645 0.2995816 8948.809
## D10000 0.2787996 0.2919672 9881.115
# compare all 3 different isotherms
CCTfromxy( xy, isotherms=c('robertson',NA,'mccamy') )
## Robertson native McCamy
## D2000 NA NA NA
## D3000 NA NA NA
## D4000 4000.096 4000.062 4005.717
## D5000 4999.749 4999.608 4999.998
## D6000 5998.015 5999.242 5999.437
## D7000 6997.858 6998.258 6997.542
## D8000 7997.599 7996.985 7985.318
## D9000 8999.301 8993.811 8948.809
## D10000 9991.920 9992.672 9881.115
cbind( default=CCTfromxy(xy), prec.native=CCTfromxy(xy,locus='prec',iso=NA) )
## default prec.native
## 2000K NA NA
## 3000K NA NA
## 4000K 4000.096 4000.052
## 5000K 4999.749 4999.767
## 6000K 5998.015 5999.097
## 7000K 6997.858 6997.857
## 8000K 7997.599 7997.951
## 9000K 8999.301 8995.835
## 10000K 9991.920 9992.839
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.