colour.notation.munsell Module¶

Munsell Renotation System¶

Defines various objects for Munsell Renotation System computations:

munsell_value_Priest1920(): Munsell value \(V\) computation of given luminance \(Y\) using Priest, Gibson and MacNicholas (1920) method.
munsell_value_Munsell1933(): Munsell value \(V\) computation of given luminance \(Y\) using ⁠Munsell, Sloan and Godlove (1933)⁠ method.
munsell_value_Moon1943(): Munsell value \(V\) computation of given luminance \(Y\) using Moon and Spencer (1943) method.
munsell_value_Saunderson1944(): Munsell value \(V\) computation of given luminance \(Y\) using Saunderson and Milner (1944) method.
munsell_value_Ladd1955(): Munsell value \(V\) computation of given luminance \(Y\) using Ladd and Pinney (1955) method.
munsell_value_McCamy1987(): Munsell value \(V\) computation of given luminance \(Y\) using McCamy (1987) method.
munsell_value_ASTMD153508() [1] [2]: Munsell value \(V\) computation of given luminance \(Y\) using ASTM D1535-08e1 (2008) method.
munsell_colour_to_xyY() [1] [2]
xyY_to_munsell_colour() [1] [2]

References

[1]	(1, 2, 3) Centore, P. (n.d.). Munsell Resources. Retrieved July 26, 2014, from http://www.99main.com/~centore/MunsellResources/MunsellResources.html

[2]	(1, 2, 3) Centore, P. (2012). An open-source inversion algorithm for the Munsell renotation. Color Research & Application, 37(6), 455–464. doi:10.1002/col.20715

colour.notation.munsell.munsell_value_Priest1920(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using ⁠⁠⁠⁠⁠Priest, Gibson and MacNicholas (1920) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

References

[3]	(1, 2, 3, 4) Wikipedia. (n.d.). Lightness. Retrieved April 13, 2014, from http://en.wikipedia.org/wiki/Lightness

Examples

>>> munsell_value_Priest1920(10.08)  
3.1749015...

colour.notation.munsell.munsell_value_Munsell1933(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using ⁠Munsell, Sloan and Godlove (1933) method. [3]

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

Examples

>>> munsell_value_Munsell1933(10.08)  
3.7918355...

colour.notation.munsell.munsell_value_Moon1943(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using Moon and Spencer (1943) method. [3]

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

Examples

>>> munsell_value_Moon1943(10.08)  
3.7462971...

colour.notation.munsell.munsell_value_Saunderson1944(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using Saunderson and Milner (1944) method. [3]

Parameters:	Y (numeric) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

Examples

>>> munsell_value_Saunderson1944(10.08)  
3.6865080...

colour.notation.munsell.munsell_value_Ladd1955(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using Ladd and Pinney (1955) method. [3]

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

Examples

>>> munsell_value_Ladd1955(10.08)  
3.6952862...

colour.notation.munsell.munsell_value_McCamy1987(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using McCamy (1987) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

References

[4]	ASTM International. (1989). ASTM D1535-89 Standard Test Method for Specifying Color by the Munsell System. Retrieved from http://www.astm.org/DATABASE.CART/HISTORICAL/D1535-89.htm

Examples

>>> munsell_value_McCamy1987(10.08)  
array(3.7347235...)

colour.notation.munsell.munsell_value_ASTMD153508(Y)[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using a reverse lookup table from ASTM D1535-08e1 (2008) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\)
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

Examples

>>> munsell_value_ASTMD153508(10.1488096782)  
3.7462971...

colour.notation.munsell.MUNSELL_VALUE_METHODS = CaseInsensitiveMapping({u'Saunderson 1944': <function munsell_value_Saunderson1944 at 0x2adc4931a7d0>, u'McCamy 1987': <function munsell_value_McCamy1987 at 0x2adc4931a8c0>, u'Ladd 1955': <function munsell_value_Ladd1955 at 0x2adc4931a848>, u'ASTM D1535-08': <function munsell_value_ASTMD153508 at 0x2adc4931a938>, u'Moon 1943': <function munsell_value_Moon1943 at 0x2adc4931a758>, u'Priest 1920': <function munsell_value_Priest1920 at 0x2adc4931a668>, u'Munsell 1933': <function munsell_value_Munsell1933 at 0x2adc4931a6e0>, u'astm2008': <function munsell_value_ASTMD153508 at 0x2adc4931a938>})¶

Supported Munsell value computations methods.

MUNSELL_VALUE_METHODS : CaseInsensitiveMapping: {‘Priest 1920’, ‘Munsell 1933’, ‘Moon 1943’, ‘Saunderson 1944’, ‘Ladd 1955’, ‘McCamy 1987’, ‘ASTM D1535-08’}

Aliases:

‘astm2008’: ‘ASTM D1535-08’

colour.notation.munsell.munsell_value(Y, method=u'ASTM D1535-08')[source]¶

Returns the Munsell value \(V\) of given luminance \(Y\) using given method.

Parameters:	Y (numeric or array_like) – luminance \(Y\). method (unicode, optional) – {‘ASTM D1535-08’, ‘Priest 1920’, ‘Munsell 1933’, ‘Moon 1943’, ‘Saunderson 1944’, ‘Ladd 1955’, ‘McCamy 1987’} Computation method.
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

Input Y is in domain [0, 100].
Output V is in domain [0, 10].

Examples

>>> munsell_value(10.08)  
3.7344764...
>>> munsell_value(10.08, method='Priest 1920')  
3.1749015...
>>> munsell_value(10.08, method='Munsell 1933')  
3.7918355...
>>> munsell_value(10.08, method='Moon 1943')  
3.7462971...
>>> munsell_value(10.08, method='Saunderson 1944')  
3.6865080...
>>> munsell_value(10.08, method='Ladd 1955')  
3.6952862...
>>> munsell_value(10.08, method='McCamy 1987')  
array(3.7347235...)

colour.notation.munsell.munsell_specification_to_xyY(specification)[source]¶

Converts given Munsell Colorlab specification to CIE xyY colourspace.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	CIE xyY colourspace array.
Return type:	ndarray, (3,)

Notes

Input Munsell Colorlab specification hue must be in domain [0, 10].
Input Munsell Colorlab specification value must be in domain [0, 10].
Output CIE xyY colourspace array is in domain [0, 1].

References

[5]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/MunsellToxyY.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> spc = (2.1, 8.0, 17.9, 4)
>>> munsell_specification_to_xyY(spc)  
array([ 0.4400632...,  0.5522428...,  0.5761962...])
>>> munsell_specification_to_xyY(8.9)  
array([ 0.31006  ,  0.31616  ,  0.746134...])

colour.notation.munsell.munsell_colour_to_xyY(munsell_colour)[source]¶

Converts given Munsell colour to CIE xyY colourspace.

Parameters:	munsell_colour (unicode) – Munsell colour.
Returns:	CIE xyY colourspace array.
Return type:	ndarray, (3,)

Notes

Output CIE xyY colourspace array is in domain [0, 1].

Examples

>>> munsell_colour_to_xyY('4.2YR 8.1/5.3')  
array([ 0.3873694...,  0.3575165...,  0.59362   ])
>>> munsell_colour_to_xyY('N8.9')  
array([ 0.31006  ,  0.31616  ,  0.746134...])

colour.notation.munsell.xyY_to_munsell_specification(xyY)[source]¶

Converts from CIE xyY colourspace to Munsell Colorlab specification.

Parameters:	xyY (array_like, (3,)) – CIE xyY colourspace array.
Returns:	Munsell Colorlab specification.
Return type:	numeric or tuple
Raises:	`ValueError` – If the given CIE xyY colourspace array is not within MacAdam limits. `RuntimeError` – If the maximum iterations count has been reached without converging to a result.

Notes

Input CIE xyY colourspace array is in domain [0, 1].

References

[6]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/xyYtoMunsell.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> xyY = np.array([0.38736945, 0.35751656, 0.59362000])
>>> xyY_to_munsell_specification(xyY)  
(4.1742530..., 8.0999999..., 5.3044360..., 6)

colour.notation.munsell.xyY_to_munsell_colour(xyY, hue_decimals=1, value_decimals=1, chroma_decimals=1)[source]¶

Converts from CIE xyY colourspace to Munsell colour.

Parameters:	xyY (array_like, (3,)) – CIE xyY colourspace array. hue_decimals (int) – Hue formatting decimals. value_decimals (int) – Value formatting decimals. chroma_decimals (int) – Chroma formatting decimals.
Returns:	Munsell colour.
Return type:	unicode

Notes

Input CIE xyY colourspace array is in domain [0, 1].

Examples

>>> xyY = np.array([0.38736945, 0.35751656, 0.59362000])
>>> # Doctests skip for Python 2.x compatibility.
>>> xyY_to_munsell_colour(xyY)  
'4.2YR 8.1/5.3'

colour.notation.munsell.parse_munsell_colour(munsell_colour)[source]¶

Parses given Munsell colour and returns an intermediate Munsell Colorlab specification.

Parameters:	munsell_colour (unicode) – Munsell colour.
Returns:	Intermediate Munsell Colorlab specification.
Return type:	float or tuple
Raises:	`ValueError` – If the given specification is not a valid Munsell Renotation System colour specification.

Examples

>>> parse_munsell_colour('N5.2')  
5.2...
>>> parse_munsell_colour('0YR 2.0/4.0')
(0.0, 2.0, 4.0, 6)

colour.notation.munsell.is_grey_munsell_colour(specification)[source]¶

Returns if given Munsell Colorlab specification is a single number form used for grey colour.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	Is specification a grey colour.
Return type:	bool

Examples

>>> is_grey_munsell_colour((0.0, 2.0, 4.0, 6))
False
>>> is_grey_munsell_colour(0.5)
True

colour.notation.munsell.normalize_munsell_specification(specification)[source]¶

Normalises given Munsell Colorlab specification.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	Normalised Munsell Colorlab specification.
Return type:	numeric or tuple

Examples

>>> normalize_munsell_specification((0.0, 2.0, 4.0, 6))
(10, 2.0, 4.0, 7)

colour.notation.munsell.munsell_colour_to_munsell_specification(munsell_colour)[source]¶

Convenient definition to retrieve a normalised Munsell Colorlab specification from given Munsell colour.

Parameters:	munsell_colour (unicode) – Munsell colour.
Returns:	Normalised Munsell Colorlab specification.
Return type:	numeric or tuple

Examples

>>> munsell_colour_to_munsell_specification('N5.2')  
5.2...
>>> munsell_colour_to_munsell_specification('0YR 2.0/4.0')
(10, 2.0, 4.0, 7)

colour.notation.munsell.munsell_specification_to_munsell_colour(specification, hue_decimals=1, value_decimals=1, chroma_decimals=1)[source]¶

Converts from Munsell Colorlab specification to given Munsell colour.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification. hue_decimals (int, optional) – Hue formatting decimals. value_decimals (int, optional) – Value formatting decimals. chroma_decimals (int, optional) – Chroma formatting decimals.
Returns:	Munsell colour.
Return type:	unicode

Examples

>>> # Doctests skip for Python 2.x compatibility.
>>> munsell_specification_to_munsell_colour(5.2)  
'N5.2'
>>> # Doctests skip for Python 2.x compatibility.
>>> spc = (10, 2.0, 4.0, 7)
>>> munsell_specification_to_munsell_colour(spc)  
'10.0R 2.0/4.0'

colour.notation.munsell.xyY_from_renotation(specification)[source]¶

Returns given existing Munsell Colorlab specification CIE xyY colourspace vector from Munsell Renotation System data.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	CIE xyY colourspace vector.
Return type:	tuple
Raises:	`ValueError` – If the given specification doesn’t exist in Munsell Renotation System data.

Examples

>>> xyY_from_renotation((2.5, 0.2, 2.0, 4))  
(0.71..., 1.41..., 0.23...)

colour.notation.munsell.is_specification_in_renotation(specification)[source]¶

Returns if given Munsell Colorlab specification is in Munsell Renotation System data.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	Is specification in Munsell Renotation System data.
Return type:	bool

Examples

>>> is_specification_in_renotation((2.5, 0.2, 2.0, 4))
True
>>> is_specification_in_renotation((64, 0.2, 2.0, 4))
False

colour.notation.munsell.bounding_hues_from_renotation(hue, code)[source]¶

Returns for a given hue the two bounding hues from Munsell Renotation System data.

Parameters:	hue (numeric) – Munsell Colorlab specification hue. code (numeric) – Munsell Colorlab specification code.
Returns:	Bounding hues.
Return type:	tuple

References

[7]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellSystemRoutines/BoundingRenotationHues.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> bounding_hues_from_renotation(3.2, 4)
((2.5, 4), (5.0, 4))

colour.notation.munsell.hue_to_hue_angle(hue, code)[source]¶

Converts from the Munsell Colorlab specification hue to hue angle in degrees.

Parameters:	hue (numeric) – Munsell Colorlab specification hue. code (numeric) – Munsell Colorlab specification code.
Returns:	Hue angle in degrees.
Return type:	numeric

References

[8]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/MunsellHueToChromDiagHueAngle.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> hue_to_hue_angle(3.2, 4)
65.5

colour.notation.munsell.hue_angle_to_hue(hue_angle)[source]¶

Converts from hue angle in degrees to the Munsell Colorlab specification hue.

Parameters:	hue_angle (numeric) – Hue angle in degrees.
Returns:	(Munsell Colorlab specification hue, Munsell Colorlab specification code).
Return type:	tuple

References

[9]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/ChromDiagHueAngleToMunsellHue.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> hue_angle_to_hue(65.54)  
(3.2160000..., 4)

colour.notation.munsell.hue_to_ASTM_hue(hue, code)[source]¶

Converts from the Munsell Colorlab specification hue to ASTM hue number in domain [0, 100].

Parameters:	hue (numeric) – Munsell Colorlab specification hue. code (numeric) – Munsell Colorlab specification code.
Returns:	ASM hue number.
Return type:	numeric

References

[10]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/MunsellHueToASTMHue.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> hue_to_ASTM_hue(3.2, 4)  
33.2...

colour.notation.munsell.interpolation_method_from_renotation_ovoid(specification)[source]¶

Returns whether to use linear or radial interpolation when drawing ovoids through data points in the Munsell Renotation System data from given specification.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	Interpolation method.
Return type:	unicode or None (‘Linear’, ‘Radial’, None)

Notes

Input Munsell Colorlab specification value must be an integer in domain [0, 10].
Input Munsell Colorlab specification chroma must be an integer and a multiple of 2 in domain [2, 50].

References

[11]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellSystemRoutines/LinearVsRadialInterpOnRenotationOvoid.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> spc = (2.5, 5.0, 12.0, 4)
>>> # Doctests skip for Python 2.x compatibility.
>>> interpolation_method_from_renotation_ovoid()  
'Radial'

colour.notation.munsell.xy_from_renotation_ovoid(specification)[source]¶

Converts given Munsell Colorlab specification to xy chromaticity coordinates on Munsell Renotation System ovoid. The xy point will be on the ovoid about the achromatic point, corresponding to the Munsell Colorlab specification value and chroma.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	xy chromaticity coordinates.
Return type:	tuple
Raises:	`ValueError` – If an invalid interpolation method is retrieved from internal computations.

Notes

Input Munsell Colorlab specification value must be an integer in domain [1, 9].
Input Munsell Colorlab specification chroma must be an integer and a multiple of 2 in domain [2, 50].

References

[12]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/FindHueOnRenotationOvoid.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> xy_from_renotation_ovoid((2.5, 5.0, 12.0, 4))  
(0.4333..., 0.5602...)
>>> xy_from_renotation_ovoid(8)
(0.31006, 0.31616)

colour.notation.munsell.LCHab_to_munsell_specification(LCHab)[source]¶

Converts from CIE LCHab colourspace to approximate Munsell Colorlab specification.

Parameters:	LCHab (array_like, (3,)) – CIE LCHab colourspace array.
Returns:	Munsell Colorlab specification.
Return type:	tuple

Notes

Input \(L^*\) is in domain [0, 100].

References

[13]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - GeneralRoutines/CIELABtoApproxMunsellSpec.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> LCHab = np.array([100, 17.50664796, 244.93046842])
>>> LCHab_to_munsell_specification(LCHab)  
(8.0362412..., 10.0, 3.5013295..., 1)

colour.notation.munsell.maximum_chroma_from_renotation(hue, value, code)[source]¶

Returns the maximum Munsell chroma from Munsell Renotation System data using given Munsell Colorlab specification hue, Munsell Colorlab specification value and Munsell Colorlab specification code.

Parameters:	hue (numeric) – Munsell Colorlab specification hue. value (numeric) – Munsell value code. code (numeric) – Munsell Colorlab specification code.
Returns:	Maximum chroma.
Return type:	numeric

References

[14]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/MaxChromaForExtrapolatedRenotation.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> maximum_chroma_from_renotation(2.5, 5, 5)
14.0

colour.notation.munsell.munsell_specification_to_xy(specification)[source]¶

Converts given Munsell Colorlab specification to xy chromaticity coordinates by interpolating over Munsell Renotation System data.

Parameters:	specification (numeric or tuple) – Munsell Colorlab specification.
Returns:	xy chromaticity coordinates.
Return type:	tuple

Notes

Input Munsell Colorlab specification value must be an integer in domain [0, 10].
Output xy chromaticity coordinates are in domain [0, 1].

References

[15]	Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/MunsellToxyForIntegerMunsellValue.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox

Examples

>>> # Doctests ellipsis for Python 2.x compatibility.
>>> munsell_specification_to_xy((2.1, 8.0, 17.9, 4))  
(0.440063..., 0.552242...)
>>> munsell_specification_to_xy(8)  
(0.31006..., 0.31616...)