munsellinterpol (version 3.5-1)

XYZtoMunsell: Convert XYZ coordinates to Munsell HVC

Description

XYZtoMunsell() converts XYZ coordinates to Munsell HVC, by interpolating over the Munsell renotation data.

Note that by default the input XYZ is relative to the white point of Illuminant C. Since Illuminant C is obsolete, it is almost certain that an XYZ appearing in modern calculations must be chromatically adapted to the white point of Illuminant C before interpolating. This chromatic adaptation is done internally if the white point of XYZ is supplied as argument white. The adaptation is performed by spacesXYZ::adaptXYZ().

If the input XYZ is computed from a reflectance spectrum, then ideally the white point should be set to the XYZ computed when that reflectance spectrum has constant value 1 - the so-called Perfect Reflecting Diffuser. The white points in published standards, e.g. D65 white = (95.047, 100, 108.883), can differ from spectrally-derived white points because of different wavelength step sizes and ranges. For an example, see the vignette Soil Colors.

Usage

XYZtoMunsell( XYZ, white=NULL, adapt='Bradford', ... )

Value

an Nx3 matrix with Munsell HVC in the rows. The rownames are copied from input to output, unless the input rownames are NULL

when the ouput rownames are set to the Munsell notations for HVC.

In case of error, it returns NULL.

Arguments

XYZ

a numeric Nx3 matrix with CIE XYZ coordinates in the rows, or a vector that can be converted to such a matrix, by row. Ideally, XYZ should be scaled so that Y=100 for the perfect reflecting diffuser.

white

XYZ for the source white point. If NULL then the input XYZ are for viewing in an environment with Illuminant C, and the input XYZ is not chromatically adapted. If white is not NULL, then the input XYZ is chromatically adapted from the given white to the white point of Illuminant C before conversion to HVC. white can be a numeric 3-vector; by convention Y=100 for Munsell work. white can also be a numeric 2-vector; which is interpreted as xy chromaticity and converted to XYZ with Y=100. white can also be the name of any standard illuminant recognized by spacesXYZ::standardXYZ() which is then scaled so that Y=100.

If the input XYZ is computed from a reflectance spectrum, then ideally white should be set to the XYZ computed when that reflectance spectrum has constant value 1 (see Description).

adapt

method for chromatic adaptation, see spacesXYZ::CAT() for valid values. Also see Details. If white=NULL then adapt is ignored.

...

other parameters passed to xyYtoMunsell()

Condition Signaling

For an overview see: Appendix E - Logging and Condition Signaling in the User Guide.

In case of an ERROR or FATAL event, a condition is signaled with one of these additional S3 classes: "invalid_argument" or "package_unavailable", whichever is appropriate. The invalid argument, or the name of the unavailable package, is added to the condition object.

Author

Jose Gama and Glenn Davis

Details

The conversion is done in these steps:

• If white is not NULL, XYZ is chromatically adapted from the given white to the white point of Illuminant C using spacesXYZ::adaptXYZ() and the given adapt method.

• XYZ → xyY using spacesXYZ::xyYfromXYZ()

• xyY → HVC using xyYtoMunsell() and .... This function does the interpolation over the Munsell renotation data.

References

Paul Centore 2014. The Munsell and Kubelka-Munk Toolbox. https://www.munsellcolorscienceforpainters.com/MunsellAndKubelkaMunkToolbox/MunsellAndKubelkaMunkToolbox.html

See Also

MunsellToXYZ(), xyYtoMunsell(), spacesXYZ::xyYfromXYZ(), spacesXYZ::adaptXYZ()

Examples

## make XYZ for an 18% gray card, under Illuminant D65
white.D65 = 100 * as.numeric( spacesXYZ::standardXYZ( 'D65' ) )
gray18 = 0.18 * white.D65
XYZtoMunsell( gray18 )
##                       H        V         C
##  7.6GY 4.9/0.65 37.6456 4.851927 0.6466169

## This is not neutral gray, as expected.  The hue is green-yellow.
## Chroma = 0.6466 is too large; it should be 0, up to numerical truncation.
## The problem is that the white points are not equal.
## Redo and supply the true white point.

XYZtoMunsell( gray18, white=white.D65 )
##         H        V C
##  N 4.9/ 0 4.851927 0        #  much better; an exact neutral

##  Although the hue H=0 here, it is actually undefined because C=0
##  (as in polar coordinates, theta is undefined when r=0).


## When XYZ=(0,0,0) then Value should be exactly 0.
## And when XYZ is equal to the white point, then Value should be exactly 10.
XYZtoMunsell( c( 0,0,0, white.D65 ), white=white.D65 )
##        H  V C
##  N 0/  0  0 0
##  N 10/ 0 10 0


##  By convention, Y=100 for the reference white; but this is not strictly required.
gray18
##              X  Y        Z
##  [1,] 17.10846 18 19.59894

XYZtoMunsell( gray18, white=gray18 )
##        H  V C
##  N 10/ 0 10 0
##  The Value is still exactly 10.