Source code for colour.notation.munsell

#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""
Munsell Renotation System
=========================

Defines various objects for *Munsell Renotation System* computations:

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

See Also
--------
`Munsell Renotation System IPython Notebook
<http://nbviewer.ipython.org/github/colour-science/colour-ipython/blob/master/notebooks/notation/munsell.ipynb>`_  # noqa

References
----------
.. [1]  Centore, P. (n.d.). Munsell Resources. Retrieved July 26, 2014, from
        http://www.99main.com/~centore/MunsellResources/MunsellResources.html
.. [2]  Centore, P. (2012). An open-source inversion algorithm for the Munsell
        renotation. Color Research & Application, 37(6), 455–464.
        doi:10.1002/col.20715
"""

from __future__ import division, unicode_literals

import numpy as np
import re

try:
    from collections import OrderedDict
except ImportError:
    from ordereddict import OrderedDict

from colour.algebra import (
    Extrapolator1d,
    LinearInterpolator1d,
    cartesian_to_cylindrical,
    is_numeric,
    is_integer)
from colour.algebra.common import (
    INTEGER_THRESHOLD,
    FLOATING_POINT_NUMBER_PATTERN)
from colour.colorimetry import ILLUMINANTS, luminance_ASTMD153508
from colour.models import Lab_to_LCHab, XYZ_to_Lab, XYZ_to_xy, xyY_to_XYZ
from colour.volume import is_within_macadam_limits
from colour.notation import MUNSELL_COLOURS_ALL
from colour.utilities import CaseInsensitiveMapping, Lookup

__author__ = 'Colour Developers, Paul Centore'
__copyright__ = 'Copyright (C) 2013 - 2015 - Colour Developers'
__license__ = 'New BSD License - http://opensource.org/licenses/BSD-3-Clause'
__maintainer__ = 'Colour Developers'
__email__ = 'colour-science@googlegroups.com'
__status__ = 'Production'

__all__ = ['MUNSELL_GRAY_PATTERN',
           'MUNSELL_COLOUR_PATTERN',
           'MUNSELL_GRAY_FORMAT',
           'MUNSELL_COLOUR_FORMAT',
           'MUNSELL_GRAY_EXTENDED_FORMAT',
           'MUNSELL_COLOUR_EXTENDED_FORMAT',
           'MUNSELL_HUE_LETTER_CODES',
           'MUNSELL_DEFAULT_ILLUMINANT',
           'MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES',
           'munsell_value_Priest1920',
           'munsell_value_Munsell1933',
           'munsell_value_Moon1943',
           'munsell_value_Saunderson1944',
           'munsell_value_Ladd1955',
           'munsell_value_McCamy1987',
           'munsell_value_ASTMD153508',
           'MUNSELL_VALUE_METHODS',
           'munsell_value',
           'munsell_specification_to_xyY',
           'munsell_colour_to_xyY',
           'xyY_to_munsell_specification',
           'xyY_to_munsell_colour',
           'parse_munsell_colour',
           'is_grey_munsell_colour',
           'normalize_munsell_specification',
           'munsell_colour_to_munsell_specification',
           'munsell_specification_to_munsell_colour',
           'xyY_from_renotation',
           'is_specification_in_renotation',
           'bounding_hues_from_renotation',
           'hue_to_hue_angle',
           'hue_angle_to_hue',
           'hue_to_ASTM_hue',
           'interpolation_method_from_renotation_ovoid',
           'xy_from_renotation_ovoid',
           'LCHab_to_munsell_specification',
           'maximum_chroma_from_renotation',
           'munsell_specification_to_xy']

MUNSELL_GRAY_PATTERN = 'N(?P<value>{0})'.format(FLOATING_POINT_NUMBER_PATTERN)
MUNSELL_COLOUR_PATTERN = (
    '(?P<hue>{0})\s*(?P<letter>BG|GY|YR|RP|PB|B|G|Y|R|P)\s*(?P<value>{0})\s*\/\s*(?P<chroma>[-+]?{0})'.format(  # noqa
        FLOATING_POINT_NUMBER_PATTERN))

MUNSELL_GRAY_FORMAT = 'N{0}'
MUNSELL_COLOUR_FORMAT = '{0} {1}/{2}'
MUNSELL_GRAY_EXTENDED_FORMAT = 'N{0:.{1}f}'
MUNSELL_COLOUR_EXTENDED_FORMAT = '{0:.{1}f}{2} {3:.{4}f}/{5:.{6}f}'

MUNSELL_HUE_LETTER_CODES = Lookup({
    'BG': 2,
    'GY': 4,
    'YR': 6,
    'RP': 8,
    'PB': 10,
    'B': 1,
    'G': 3,
    'Y': 5,
    'R': 7,
    'P': 9})

MUNSELL_DEFAULT_ILLUMINANT = 'C'
MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES = ILLUMINANTS.get(
    'CIE 1931 2 Degree Standard Observer').get(
    MUNSELL_DEFAULT_ILLUMINANT)

_MUNSELL_SPECIFICATIONS_CACHE = None
_MUNSELL_VALUE_ASTM_D1535_08_INTERPOLATOR_CACHE = None
_MUNSELL_MAXIMUM_CHROMAS_FROM_RENOTATION_CACHE = None


def _munsell_specifications():
    """
    Returns the *Munsell Renotation System* specifications and caches them if
    not existing.

    The *Munsell Renotation System* data is stored in
    :attr:`colour.notation.dataset.munsell.MUNSELL_COLOURS` attribute in a 2
    columns form:

    (('2.5GY', 0.2, 2.0), (0.713, 1.414, 0.237)),
    (('5GY', 0.2, 2.0), (0.449, 1.145, 0.237)),
    (('7.5GY', 0.2, 2.0), (0.262, 0.837, 0.237)),
    ...,)

    The first column is converted from *Munsell* colour to specification using
    :func:`munsell_colour_to_munsell_specification` definition:

    ('2.5GY', 0.2, 2.0) ---> (2.5, 0.2, 2.0, 4)

    Returns
    -------
    list
        *Munsell Renotation System* specifications.
    """

    global _MUNSELL_SPECIFICATIONS_CACHE
    if _MUNSELL_SPECIFICATIONS_CACHE is None:
        _MUNSELL_SPECIFICATIONS_CACHE = [
            munsell_colour_to_munsell_specification(
                MUNSELL_COLOUR_FORMAT.format(*colour[0]))
            for colour in MUNSELL_COLOURS_ALL]
    return _MUNSELL_SPECIFICATIONS_CACHE


def _munsell_value_ASTMD153508_interpolator():
    """
    Returns the *Munsell* value interpolator for ASTM D1535-08e1 (2008) method
    and caches it if not existing.

    Returns
    -------
    Extrapolator1d
        *Munsell* value interpolator for ASTM D1535-08e1 (2008) method.
    """

    global _MUNSELL_VALUE_ASTM_D1535_08_INTERPOLATOR_CACHE
    munsell_values = np.arange(0, 10, 0.001)
    if _MUNSELL_VALUE_ASTM_D1535_08_INTERPOLATOR_CACHE is None:
        _MUNSELL_VALUE_ASTM_D1535_08_INTERPOLATOR_CACHE = Extrapolator1d(
            LinearInterpolator1d([luminance_ASTMD153508(x)
                                  for x in munsell_values],
                                 munsell_values))

    return _MUNSELL_VALUE_ASTM_D1535_08_INTERPOLATOR_CACHE


def _munsell_maximum_chromas_from_renotation():
    """
    Returns the maximum *Munsell* chromas from *Munsell Renotation System* data
    and caches them if not existing.

    Returns
    -------
    tuple
        Maximum *Munsell* chromas.
    """

    global _MUNSELL_MAXIMUM_CHROMAS_FROM_RENOTATION_CACHE
    if _MUNSELL_MAXIMUM_CHROMAS_FROM_RENOTATION_CACHE is None:
        chromas = OrderedDict()
        for munsell_colour in MUNSELL_COLOURS_ALL:
            hue, value, chroma, code = munsell_colour_to_munsell_specification(
                MUNSELL_COLOUR_FORMAT.format(*munsell_colour[0]))
            index = (hue, value, code)
            if index in chromas:
                chroma = max(chromas[index], chroma)

            chromas[index] = chroma

        _MUNSELL_MAXIMUM_CHROMAS_FROM_RENOTATION_CACHE = tuple(
            zip(chromas.keys(), chromas.values()))
    return _MUNSELL_MAXIMUM_CHROMAS_FROM_RENOTATION_CACHE


[docs]def munsell_value_Priest1920(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using *⁠⁠⁠⁠⁠Priest, Gibson and MacNicholas (1920)* method. Parameters ---------- Y : numeric *luminance* :math:`Y`. Returns ------- numeric *Munsell* value :math:`V`. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. References ---------- .. [3] Wikipedia. (n.d.). Lightness. Retrieved April 13, 2014, from http://en.wikipedia.org/wiki/Lightness Examples -------- >>> munsell_value_Priest1920(10.08) # doctest: +ELLIPSIS 3.1749015... """ Y /= 100 V = 10 * np.sqrt(Y) return V
[docs]def munsell_value_Munsell1933(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using *⁠Munsell, Sloan and Godlove (1933)* method. [3]_ Parameters ---------- Y : numeric *luminance* :math:`Y`. Returns ------- numeric *Munsell* value :math:`V`. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. Examples -------- >>> munsell_value_Munsell1933(10.08) # doctest: +ELLIPSIS 3.7918355... """ V = np.sqrt(1.4742 * Y - 0.004743 * (Y * Y)) return V
[docs]def munsell_value_Moon1943(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using Moon and Spencer (1943) method. [3]_ Parameters ---------- Y : numeric *luminance* :math:`Y`. Returns ------- numeric *Munsell* value :math:`V`. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. Examples -------- >>> munsell_value_Moon1943(10.08) # doctest: +ELLIPSIS 3.7462971... """ V = 1.4 * Y ** 0.426 return V
[docs]def munsell_value_Saunderson1944(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using Saunderson and Milner (1944) method. [3]_ Parameters ---------- Y : numeric *luminance* :math:`Y`. Returns ------- numeric *Munsell* value :math:`V`. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. Examples -------- >>> munsell_value_Saunderson1944(10.08) # doctest: +ELLIPSIS 3.6865080... """ V = 2.357 * (Y ** 0.343) - 1.52 return V
[docs]def munsell_value_Ladd1955(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using Ladd and Pinney (1955) method. [3]_ Parameters ---------- Y : numeric *luminance* :math:`Y`. Returns ------- numeric *Munsell* value :math:`V`. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. Examples -------- >>> munsell_value_Ladd1955(10.08) # doctest: +ELLIPSIS 3.6952862... """ V = 2.468 * (Y ** (1 / 3)) - 1.636 return V
[docs]def munsell_value_McCamy1987(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using McCamy (1987) method. Parameters ---------- Y : numeric *luminance* :math:`Y`. Returns ------- numeric *Munsell* value :math:`V`. 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) # doctest: +ELLIPSIS 3.7347235... """ if Y <= 0.9: V = 0.87445 * (Y ** 0.9967) else: V = (2.49268 * (Y ** (1 / 3)) - 1.5614 - (0.985 / (((0.1073 * Y - 3.084) ** 2) + 7.54)) + (0.0133 / (Y ** 2.3)) + 0.0084 * np.sin(4.1 * (Y ** (1 / 3)) + 1) + (0.0221 / Y) * np.sin(0.39 * (Y - 2)) - (0.0037 / (0.44 * Y)) * np.sin(1.28 * (Y - 0.53))) return V
[docs]def munsell_value_ASTMD153508(Y): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using a reverse lookup table from ASTM D1535-08e1 (2008) method. Parameters ---------- Y : numeric *luminance* :math:`Y` Returns ------- numeric *Munsell* value :math:`V`.. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. Examples -------- >>> munsell_value_ASTMD153508(10.1488096782) # doctest: +ELLIPSIS 3.7462971... """ V = _munsell_value_ASTMD153508_interpolator()(Y) return V
MUNSELL_VALUE_METHODS = CaseInsensitiveMapping( {'Priest 1920': munsell_value_Priest1920, 'Munsell 1933': munsell_value_Munsell1933, 'Moon 1943': munsell_value_Moon1943, 'Saunderson 1944': munsell_value_Saunderson1944, 'Ladd 1955': munsell_value_Ladd1955, 'McCamy 1987': munsell_value_McCamy1987, 'ASTM D1535-08': munsell_value_ASTMD153508}) """ 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' """ MUNSELL_VALUE_METHODS['astm2008'] = ( MUNSELL_VALUE_METHODS['ASTM D1535-08'])
[docs]def munsell_value(Y, method='ASTM D1535-08'): """ Returns the *Munsell* value :math:`V` of given *luminance* :math:`Y` using given method. Parameters ---------- Y : numeric *luminance* :math:`Y`. method : unicode, optional {'ASTM D1535-08', 'Priest 1920', 'Munsell 1933', 'Moon 1943', 'Saunderson 1944', 'Ladd 1955', 'McCamy 1987'} Computation method. Returns ------- numeric *Munsell* value :math:`V`. Notes ----- - Input *Y* is in domain [0, 100]. - Output *V* is in domain [0, 10]. Examples -------- >>> munsell_value(10.08) # doctest: +ELLIPSIS 3.7344764... >>> munsell_value(10.08, method='Priest 1920') # doctest: +ELLIPSIS 3.1749015... >>> munsell_value(10.08, method='Munsell 1933') # doctest: +ELLIPSIS 3.7918355... >>> munsell_value(10.08, method='Moon 1943') # doctest: +ELLIPSIS 3.7462971... >>> munsell_value(10.08, method='Saunderson 1944') # doctest: +ELLIPSIS 3.6865080... >>> munsell_value(10.08, method='Ladd 1955') # doctest: +ELLIPSIS 3.6952862... >>> munsell_value(10.08, method='McCamy 1987') # doctest: +ELLIPSIS 3.7347235... """ return MUNSELL_VALUE_METHODS.get(method)(Y)
[docs]def munsell_specification_to_xyY(specification): """ Converts given *Munsell* *Colorlab* specification to *CIE xyY* colourspace. Parameters ---------- specification : numeric or tuple *Munsell* *Colorlab* specification. Returns ------- ndarray, (3,) *CIE xyY* colourspace matrix. 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 matrix 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) # doctest: +ELLIPSIS array([ 0.4400632..., 0.5522428..., 0.5761962...]) >>> munsell_specification_to_xyY(8.9) # doctest: +ELLIPSIS array([ 0.31006 , 0.31616 , 0.746134...]) """ if is_grey_munsell_colour(specification): value = specification else: hue, value, chroma, code = specification assert 0 <= hue <= 10, ( '"{0}" specification hue must be in domain [0, 10]!'.format( specification)) assert 0 <= value <= 10, ( '"{0}" specification value must be in domain [0, 10]!'.format( specification)) Y = luminance_ASTMD153508(value) if is_integer(value): value_minus = value_plus = round(value) else: value_minus = np.floor(value) value_plus = value_minus + 1 specification_minus = (value_minus if is_grey_munsell_colour(specification) else (hue, value_minus, chroma, code)) x_minus, y_minus = munsell_specification_to_xy(specification_minus) plus_specification = (value_plus if (is_grey_munsell_colour(specification) or value_plus == 10) else (hue, value_plus, chroma, code)) x_plus, y_plus = munsell_specification_to_xy(plus_specification) if value_minus == value_plus: x = x_minus y = y_minus else: Y_minus = luminance_ASTMD153508(value_minus) Y_plus = luminance_ASTMD153508(value_plus) x = LinearInterpolator1d([Y_minus, Y_plus], [x_minus, x_plus])(Y) y = LinearInterpolator1d([Y_minus, Y_plus], [y_minus, y_plus])(Y) return np.array([x, y, Y / 100])
[docs]def munsell_colour_to_xyY(munsell_colour): """ Converts given *Munsell* colour to *CIE xyY* colourspace. Parameters ---------- munsell_colour : unicode *Munsell* colour. Returns ------- ndarray, (3,) *CIE xyY* colourspace matrix. Notes ----- - Output *CIE xyY* colourspace matrix is in domain [0, 1]. Examples -------- >>> munsell_colour_to_xyY('4.2YR 8.1/5.3') # doctest: +ELLIPSIS array([ 0.3873694..., 0.3575165..., 0.59362 ]) >>> munsell_colour_to_xyY('N8.9') # doctest: +ELLIPSIS array([ 0.31006 , 0.31616 , 0.746134...]) """ specification = munsell_colour_to_munsell_specification(munsell_colour) return munsell_specification_to_xyY(specification)
[docs]def xyY_to_munsell_specification(xyY): """ Converts from *CIE xyY* colourspace to *Munsell* *Colorlab* specification. Parameters ---------- xyY : array_like, (3,) *CIE xyY* colourspace matrix. Returns ------- numeric or tuple *Munsell* *Colorlab* specification. Raises ------ ValueError If the given *CIE xyY* colourspace matrix is not within MacAdam limits. RuntimeError If the maximum iterations count has been reached without converging to a result. Notes ----- - Input *CIE xyY* colourspace matrix 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.59362]) >>> xyY_to_munsell_specification(xyY) # doctest: +ELLIPSIS (4.1742530..., 8.0999999..., 5.3044360..., 6) """ if not is_within_macadam_limits(xyY, MUNSELL_DEFAULT_ILLUMINANT): raise ValueError( ('"{0}" is not within "MacAdam" limits for illuminant ' '"{1}"!').format(xyY, MUNSELL_DEFAULT_ILLUMINANT)) x, y, Y = np.ravel(xyY) # Scaling *Y* for algorithm needs. value = munsell_value_ASTMD153508(Y * 100) if is_integer(value): value = round(value) x_center, y_center, Y_center = np.ravel( munsell_specification_to_xyY(value)) z_input, theta_input, rho_input = cartesian_to_cylindrical((x - x_center, y - y_center, Y_center)) theta_input = np.degrees(theta_input) grey_threshold = 0.001 if rho_input < grey_threshold: return value X, Y, Z = np.ravel(xyY_to_XYZ((x, y, Y))) xi, yi = MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES Xr, Yr, Zr = np.ravel(xyY_to_XYZ((xi, yi, Y))) XYZ = np.array((X, Y, Z)) XYZr = np.array(((1 / Yr) * Xr, 1, (1 / Yr) * Zr)) Lab = XYZ_to_Lab(XYZ, XYZ_to_xy(XYZr)) LCHab = Lab_to_LCHab(Lab) hue_initial, value_initial, chroma_initial, code_initial = ( LCHab_to_munsell_specification(LCHab)) specification_current = [hue_initial, value, (5 / 5.5) * chroma_initial, code_initial] convergence_threshold = 0.0001 iterations_maximum = 64 iterations = 0 while iterations <= iterations_maximum: iterations += 1 hue_current, value_current, chroma_current, code_current = ( specification_current) hue_angle_current = hue_to_hue_angle(hue_current, code_current) chroma_maximum = maximum_chroma_from_renotation(hue_current, value, code_current) if chroma_current > chroma_maximum: chroma_current = specification_current[2] = chroma_maximum x_current, y_current, Y_current = np.ravel( munsell_specification_to_xyY(specification_current)) z_current, theta_current, rho_current = cartesian_to_cylindrical( (x_current - x_center, y_current - y_center, Y_center)) theta_current = np.degrees(theta_current) theta_current_difference = (360 - theta_input + theta_current) % 360 if theta_current_difference > 180: theta_current_difference -= 360 theta_differences = [theta_current_difference] hue_angles = [hue_angle_current] hue_angles_differences = [0] iterations_maximum_inner = 16 iterations_inner = 0 extrapolate = False while np.sign(min(theta_differences)) == np.sign( max(theta_differences)) and extrapolate is False: iterations_inner += 1 if iterations_inner > iterations_maximum_inner: raise RuntimeError(('Maximum inner iterations count reached ' 'without convergence!')) hue_angle_inner = ((hue_angle_current + iterations_inner * (theta_input - theta_current)) % 360) hue_angle_difference_inner = (iterations_inner * (theta_input - theta_current) % 360) if hue_angle_difference_inner > 180: hue_angle_difference_inner -= 360 hue_inner, code_inner = hue_angle_to_hue(hue_angle_inner) x_inner, y_inner, Y_inner = np.ravel( munsell_specification_to_xyY((hue_inner, value, chroma_current, code_inner))) if len(theta_differences) >= 2: extrapolate = True if extrapolate is False: z_inner, theta_inner, rho_inner = cartesian_to_cylindrical( (x_inner - x_center, y_inner - y_center, Y_center)) theta_inner = np.degrees(theta_inner) theta_inner_difference = ( (360 - theta_input + theta_inner) % 360) if theta_inner_difference > 180: theta_inner_difference -= 360 theta_differences.append(theta_inner_difference) hue_angles.append(hue_angle_inner) hue_angles_differences.append(hue_angle_difference_inner) theta_differences = np.array(theta_differences) hue_angles_differences = np.array(hue_angles_differences) theta_differences_indexes = theta_differences.argsort() theta_differences = theta_differences[theta_differences_indexes] hue_angles_differences = hue_angles_differences[ theta_differences_indexes] hue_angle_difference_new = Extrapolator1d( LinearInterpolator1d( theta_differences, hue_angles_differences))(0) % 360 hue_angle_new = (hue_angle_current + hue_angle_difference_new) % 360 hue_new, code_new = hue_angle_to_hue(hue_angle_new) specification_current = [hue_new, value, chroma_current, code_new] x_current, y_current, Y_current = np.ravel( munsell_specification_to_xyY(specification_current)) difference = np.linalg.norm( np.array((x, y)) - np.array((x_current, y_current))) if difference < convergence_threshold: return tuple(specification_current) # TODO: Consider refactoring implementation. hue_current, value_current, chroma_current, code_current = ( specification_current) chroma_maximum = maximum_chroma_from_renotation(hue_current, value, code_current) if chroma_current > chroma_maximum: chroma_current = specification_current[2] = chroma_maximum x_current, y_current, Y_current = np.ravel( munsell_specification_to_xyY(specification_current)) z_current, theta_current, rho_current = cartesian_to_cylindrical( (x_current - x_center, y_current - y_center, Y_center)) rho_bounds = [rho_current] chroma_bounds = [chroma_current] iterations_maximum_inner = 16 iterations_inner = 0 while rho_input < min(rho_bounds) or rho_input > max(rho_bounds): iterations_inner += 1 if iterations_inner > iterations_maximum_inner: raise RuntimeError(('Maximum inner iterations count reached ' 'without convergence!')) chroma_inner = (((rho_input / rho_current) ** iterations_inner) * chroma_current) if chroma_inner > chroma_maximum: chroma_inner = specification_current[2] = chroma_maximum specification_inner = ( hue_current, value, chroma_inner, code_current) x_inner, y_inner, Y_inner = np.ravel( munsell_specification_to_xyY(specification_inner)) z_inner, theta_inner, rho_inner = cartesian_to_cylindrical( (x_inner - x_center, y_inner - y_center, Y_center)) rho_bounds.append(rho_inner) chroma_bounds.append(chroma_inner) rho_bounds = np.array(rho_bounds) chroma_bounds = np.array(chroma_bounds) rhos_bounds_indexes = rho_bounds.argsort() rho_bounds = rho_bounds[rhos_bounds_indexes] chroma_bounds = chroma_bounds[rhos_bounds_indexes] chroma_new = LinearInterpolator1d(rho_bounds, chroma_bounds)(rho_input) specification_current = [hue_current, value, chroma_new, code_current] x_current, y_current, Y_current = np.ravel( munsell_specification_to_xyY(specification_current)) difference = np.linalg.norm( np.array((x, y)) - np.array((x_current, y_current))) if difference < convergence_threshold: return tuple(specification_current) raise RuntimeError( 'Maximum outside iterations count reached without convergence!')
[docs]def xyY_to_munsell_colour(xyY, hue_decimals=1, value_decimals=1, chroma_decimals=1): """ Converts from *CIE xyY* colourspace to *Munsell* colour. Parameters ---------- xyY : array_like, (3,) *CIE xyY* colourspace matrix. hue_decimals : int Hue formatting decimals. value_decimals : int Value formatting decimals. chroma_decimals : int Chroma formatting decimals. Returns ------- unicode *Munsell* colour. Notes ----- - Input *CIE xyY* colourspace matrix is in domain [0, 1]. Examples -------- >>> xyY = np.array([0.38736945, 0.35751656, 0.59362]) >>> # Doctests skip for Python 2.x compatibility. >>> xyY_to_munsell_colour(xyY) # doctest: +SKIP '4.2YR 8.1/5.3' """ specification = xyY_to_munsell_specification(xyY) return munsell_specification_to_munsell_colour(specification, hue_decimals, value_decimals, chroma_decimals)
[docs]def parse_munsell_colour(munsell_colour): """ Parses given *Munsell* colour and returns an intermediate *Munsell* *Colorlab* specification. Parameters ---------- munsell_colour : unicode *Munsell* colour. Returns ------- float or tuple Intermediate *Munsell* *Colorlab* specification. Raises ------ ValueError If the given specification is not a valid *Munsell Renotation System* colour specification. Examples -------- >>> parse_munsell_colour('N5.2') # doctest: +ELLIPSIS 5.2... >>> parse_munsell_colour('0YR 2.0/4.0') (0.0, 2.0, 4.0, 6) """ match = re.match(MUNSELL_GRAY_PATTERN, munsell_colour, flags=re.IGNORECASE) if match: return float(match.group('value')) match = re.match(MUNSELL_COLOUR_PATTERN, munsell_colour, flags=re.IGNORECASE) if match: return (float(match.group('hue')), float(match.group('value')), float(match.group('chroma')), MUNSELL_HUE_LETTER_CODES.get(match.group('letter').upper())) raise ValueError( ('"{0}" is not a valid "Munsell Renotation System" colour ' 'specification!').format(munsell_colour))
[docs]def is_grey_munsell_colour(specification): """ Returns if given *Munsell* *Colorlab* specification is a single number form used for grey colour. Parameters ---------- specification : numeric or tuple *Munsell* *Colorlab* specification. Returns ------- bool Is specification a grey colour. Examples -------- >>> is_grey_munsell_colour((0.0, 2.0, 4.0, 6)) False >>> is_grey_munsell_colour(0.5) True """ return is_numeric(specification)
[docs]def normalize_munsell_specification(specification): """ Normalises given *Munsell* *Colorlab* specification. Parameters ---------- specification : numeric or tuple *Munsell* *Colorlab* specification. Returns ------- numeric or tuple Normalised *Munsell* *Colorlab* specification. Examples -------- >>> normalize_munsell_specification((0.0, 2.0, 4.0, 6)) (10, 2.0, 4.0, 7) """ if is_grey_munsell_colour(specification): return specification else: hue, value, chroma, code = specification if hue == 0: # 0YR is equivalent to 10R. hue, code = 10, (code + 1) % 10 return value if chroma == 0 else (hue, value, chroma, code)
[docs]def munsell_colour_to_munsell_specification(munsell_colour): """ Convenient definition to retrieve a normalised *Munsell* *Colorlab* specification from given *Munsell* colour. Parameters ---------- munsell_colour : unicode *Munsell* colour. Returns ------- numeric or tuple Normalised *Munsell* *Colorlab* specification. Examples -------- >>> munsell_colour_to_munsell_specification('N5.2') # doctest: +ELLIPSIS 5.2... >>> munsell_colour_to_munsell_specification('0YR 2.0/4.0') (10, 2.0, 4.0, 7) """ return normalize_munsell_specification( parse_munsell_colour(munsell_colour))
[docs]def munsell_specification_to_munsell_colour(specification, hue_decimals=1, value_decimals=1, chroma_decimals=1): """ 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 ------- unicode *Munsell* colour. Examples -------- >>> # Doctests skip for Python 2.x compatibility. >>> munsell_specification_to_munsell_colour(5.2) # doctest: +SKIP 'N5.2' >>> # Doctests skip for Python 2.x compatibility. >>> spc = (10, 2.0, 4.0, 7) >>> munsell_specification_to_munsell_colour(spc) # doctest: +SKIP '10.0R 2.0/4.0' """ if is_grey_munsell_colour(specification): return MUNSELL_GRAY_EXTENDED_FORMAT.format( specification, value_decimals) else: hue, value, chroma, code = specification code_values = MUNSELL_HUE_LETTER_CODES.values() assert 0 <= hue <= 10, ( '"{0}" specification hue must be in domain [0, 10]!'.format( specification)) assert 0 <= value <= 10, ( '"{0}" specification value must be in domain [0, 10]!'.format( specification)) assert 2 <= chroma <= 50, ( '"{0}" specification chroma must be in domain [2, 50]!'.format( specification)) assert code in code_values, ( '"{0}" specification code must one of "{1}"!'.format( specification, code_values)) if hue == 0: hue, code = 10, (code + 1) % 10 if value == 0: return MUNSELL_GRAY_EXTENDED_FORMAT.format( specification, value_decimals) else: hue_letter = MUNSELL_HUE_LETTER_CODES.first_key_from_value( code) return MUNSELL_COLOUR_EXTENDED_FORMAT.format(hue, hue_decimals, hue_letter, value, value_decimals, chroma, chroma_decimals)
[docs]def xyY_from_renotation(specification): """ Returns given existing *Munsell* *Colorlab* specification *CIE xyY* colourspace vector from *Munsell Renotation System* data. Parameters ---------- specification : numeric or tuple *Munsell* *Colorlab* specification. Returns ------- tuple *CIE xyY* colourspace vector. 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)) # doctest: +ELLIPSIS (0.71..., 1.41..., 0.23...) """ specifications = _munsell_specifications() try: return MUNSELL_COLOURS_ALL[specifications.index(specification)][1] except ValueError: # TODO: Should raise KeyError, need to check the tests. raise ValueError( ('"{0}" specification does not exists in ' '"Munsell Renotation System" data!').format(specification))
[docs]def is_specification_in_renotation(specification): """ Returns if given *Munsell* *Colorlab* specification is in *Munsell Renotation System* data. Parameters ---------- specification : numeric or tuple *Munsell* *Colorlab* specification. Returns ------- bool Is specification in *Munsell Renotation System* data. Examples -------- >>> is_specification_in_renotation((2.5, 0.2, 2.0, 4)) True >>> is_specification_in_renotation((64, 0.2, 2.0, 4)) False """ try: xyY_from_renotation(specification) return True except ValueError: return False
[docs]def bounding_hues_from_renotation(hue, code): """ 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 ------- tuple Bounding hues. 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)) """ if hue % 2.5 == 0: if hue == 0: hue_cw = 10 code_cw = (code + 1) % 10 else: hue_cw = hue code_cw = code hue_ccw = hue_cw code_ccw = code_cw else: hue_cw = 2.5 * np.floor(hue / 2.5) hue_ccw = (hue_cw + 2.5) % 10 if hue_ccw == 0: hue_ccw = 10 code_ccw = code if hue_cw == 0: hue_cw = 10 code_cw = (code + 1) % 10 if code_cw == 0: code_cw = 10 else: code_cw = code code_ccw = code return (hue_cw, code_cw), (hue_ccw, code_ccw)
[docs]def hue_to_hue_angle(hue, code): """ 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 ------- numeric Hue angle in degrees. 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 """ single_hue = ((17 - code) % 10 + (hue / 10) - 0.5) % 10 return LinearInterpolator1d( [0, 2, 3, 4, 5, 6, 8, 9, 10], [0, 45, 70, 135, 160, 225, 255, 315, 360])(single_hue)
[docs]def hue_angle_to_hue(hue_angle): """ Converts from hue angle in degrees to the *Munsell* *Colorlab* specification hue. Parameters ---------- hue_angle : numeric Hue angle in degrees. Returns ------- tuple (*Munsell* *Colorlab* specification hue, *Munsell* *Colorlab* specification code). References ---------- .. [9] Centore, P. (2014). MunsellAndKubelkaMunkToolboxApr2014 - MunsellRenotationRoutines/ChromDiagHueAngleToMunsellHue.m. Retrieved from https://github.com/colour-science/MunsellAndKubelkaMunkToolbox Examples -------- >>> hue_angle_to_hue(65.54) # doctest: +ELLIPSIS (3.2160000..., 4) """ single_hue = LinearInterpolator1d( [0, 45, 70, 135, 160, 225, 255, 315, 360], [0, 2, 3, 4, 5, 6, 8, 9, 10])(hue_angle) if single_hue <= 0.5: code = 7 elif single_hue <= 1.5: code = 6 elif single_hue <= 2.5: code = 5 elif single_hue <= 3.5: code = 4 elif single_hue <= 4.5: code = 3 elif single_hue <= 5.5: code = 2 elif single_hue <= 6.5: code = 1 elif single_hue <= 7.5: code = 10 elif single_hue <= 8.5: code = 9 elif single_hue <= 9.5: code = 8 else: code = 7 hue = (10 * (single_hue % 1) + 5) % 10 if hue == 0: hue = 10 return hue, code
[docs]def hue_to_ASTM_hue(hue, code): """ 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 ------- numeric *ASM* hue number. 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) # doctest: +ELLIPSIS 33.2... """ ASTM_hue = 10 * ((7 - code) % 10) + hue return 100 if ASTM_hue == 0 else ASTM_hue
[docs]def interpolation_method_from_renotation_ovoid(specification): """ 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 ------- unicode or None ('Linear', 'Radial', None) Interpolation method. 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() # doctest: +SKIP 'Radial' """ interpolation_methods = {0: None, 1: 'Linear', 2: 'Radial'} interpolation_method = 0 if is_grey_munsell_colour(specification): # No interpolation needed for grey colours. interpolation_method = 0 else: hue, value, chroma, code = specification assert 0 <= value <= 10, ( '"{0}" specification value must be in domain [0, 10]!'.format( specification)) assert is_integer(value), ( '"{0}" specification value must be an integer!'.format( specification)) value = round(value) # Ideal white, no interpolation needed. if value == 10: interpolation_method = 0 assert 2 <= chroma <= 50, ( '"{0}" specification chroma must be in domain [2, 50]!'.format( specification)) assert abs( 2 * (chroma / 2 - round(chroma / 2))) <= INTEGER_THRESHOLD, ( ('"{0}" specification chroma must be an integer and ' 'multiple of 2!').format(specification)) chroma = 2 * round(chroma / 2) # Standard Munsell Renotation System hue, no interpolation needed. if hue % 2.5 == 0: interpolation_method = 0 ASTM_hue = hue_to_ASTM_hue(hue, code) if value == 1: if chroma == 2: if 15 < ASTM_hue < 30 or 60 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 4: if 12.5 < ASTM_hue < 27.5 or 57.5 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 6: if 55 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 8: if 67.5 < ASTM_hue < 77.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 10: if 72.5 < ASTM_hue < 77.5: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 2: if chroma == 2: if 15 < ASTM_hue < 27.5 or 77.5 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 4: if 12.5 < ASTM_hue < 30 or 62.5 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 6: if 7.5 < ASTM_hue < 22.5 or 62.5 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 8: if 7.5 < ASTM_hue < 15 or 60 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 10: if 65 < ASTM_hue < 77.5: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 3: if chroma == 2: if 10 < ASTM_hue < 37.5 or 65 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 4: if 5 < ASTM_hue < 37.5 or 55 < ASTM_hue < 72.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 6 or chroma == 8 or chroma == 10: if 7.5 < ASTM_hue < 37.5 or 57.5 < ASTM_hue < 82.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 12: if 7.5 < ASTM_hue < 42.5 or 57.5 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 4: if chroma == 2 or chroma == 4: if 7.5 < ASTM_hue < 42.5 or 57.5 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 6 or chroma == 8: if 7.5 < ASTM_hue < 40 or 57.5 < ASTM_hue < 82.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 10: if 7.5 < ASTM_hue < 40 or 57.5 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 5: if chroma == 2: if 5 < ASTM_hue < 37.5 or 55 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 4 or chroma == 6 or chroma == 8: if 2.5 < ASTM_hue < 42.5 or 55 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 10: if 2.5 < ASTM_hue < 42.5 or 55 < ASTM_hue < 82.5: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 6: if chroma == 2 or chroma == 4: if 5 < ASTM_hue < 37.5 or 55 < ASTM_hue < 87.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 6: if 5 < ASTM_hue < 42.5 or 57.5 < ASTM_hue < 87.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 8 or chroma == 10: if 5 < ASTM_hue < 42.5 or 60 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 12 or chroma == 14: if 5 < ASTM_hue < 42.5 or 60 < ASTM_hue < 82.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 16: if 5 < ASTM_hue < 42.5 or 60 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 7: if chroma == 2 or chroma == 4 or chroma == 6: if 5 < ASTM_hue < 42.5 or 60 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 8: if 5 < ASTM_hue < 42.5 or 60 < ASTM_hue < 82.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma == 10: if (30 < ASTM_hue < 42.5 or 5 < ASTM_hue < 25 or 60 < ASTM_hue < 82.5): interpolation_method = 2 else: interpolation_method = 1 elif chroma == 12: if (30 < ASTM_hue < 42.5 or 7.5 < ASTM_hue < 27.5 or 80 < ASTM_hue < 82.5): interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 14: if (32.5 < ASTM_hue < 40 or 7.5 < ASTM_hue < 15 or 80 < ASTM_hue < 82.5): interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 8: if (chroma == 2 or chroma == 4 or chroma == 6 or chroma == 8 or chroma == 10 or chroma == 12): if 5 < ASTM_hue < 40 or 60 < ASTM_hue < 85: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 14: if (32.5 < ASTM_hue < 40 or 5 < ASTM_hue < 15 or 60 < ASTM_hue < 85): interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 elif value == 9: if chroma == 2 or chroma == 4: if 5 < ASTM_hue < 40 or 55 < ASTM_hue < 80: interpolation_method = 2 else: interpolation_method = 1 elif (chroma == 6 or chroma == 8 or chroma == 10 or chroma == 12 or chroma == 14): if 5 < ASTM_hue < 42.5: interpolation_method = 2 else: interpolation_method = 1 elif chroma >= 16: if 35 < ASTM_hue < 42.5: interpolation_method = 2 else: interpolation_method = 1 else: interpolation_method = 1 return interpolation_methods.get(interpolation_method)
[docs]def xy_from_renotation_ovoid(specification): """ 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 ------- tuple *xy* chromaticity coordinates. 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)) # doctest: +ELLIPSIS (0.4333..., 0.5602...) >>> xy_from_renotation_ovoid(8) (0.31006, 0.31616) """ if is_grey_munsell_colour(specification): return MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES else: hue, value, chroma, code = specification assert 1 <= value <= 9, ( '"{0}" specification value must be in domain [1, 9]!'.format( specification)) assert is_integer(value), ( '"{0}" specification value must be an integer!'.format( specification)) value = round(value) assert 2 <= chroma <= 50, ( '"{0}" specification chroma must be in domain [2, 50]!'.format( specification)) assert abs( 2 * (chroma / 2 - round(chroma / 2))) <= INTEGER_THRESHOLD, ( ('"{0}" specification chroma must be an integer and ' 'multiple of 2!').format(specification)) chroma = 2 * round(chroma / 2) # Checking if renotation data is available without interpolation using # given threshold. threshold = 0.001 if (abs(hue) < threshold or abs(hue - 2.5) < threshold or abs(hue - 5) < threshold or abs(hue - 7.5) < threshold or abs(hue - 10) < threshold): hue = 2.5 * round(hue / 2.5) x, y, Y = xyY_from_renotation((hue, value, chroma, code)) return x, y hue_cw, hue_ccw = bounding_hues_from_renotation(hue, code) hue_minus, code_minus = hue_cw hue_plus, code_plus = hue_ccw x_grey, y_grey = MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES specification_minus = (hue_minus, value, chroma, code_minus) x_minus, y_minus, Y_minus = xyY_from_renotation( specification_minus) z_minus, theta_minus, rho_minus = cartesian_to_cylindrical( (x_minus - x_grey, y_minus - y_grey, Y_minus)) theta_minus = np.degrees(theta_minus) specification_plus = (hue_plus, value, chroma, code_plus) x_plus, y_plus, Y_plus = xyY_from_renotation(specification_plus) z_plus, theta_plus, rho_plus = cartesian_to_cylindrical( (x_plus - x_grey, y_plus - y_grey, Y_plus)) theta_plus = np.degrees(theta_plus) lower_hue_angle = hue_to_hue_angle(hue_minus, code_minus) hue_angle = hue_to_hue_angle(hue, code) upper_hue_angle = hue_to_hue_angle(hue_plus, code_plus) if theta_minus - theta_plus > 180: theta_plus += +360 if lower_hue_angle == 0: lower_hue_angle = 360 if lower_hue_angle > upper_hue_angle: if lower_hue_angle > hue_angle: lower_hue_angle -= 360 else: lower_hue_angle -= 360 hue_angle -= 360 interpolation_method = interpolation_method_from_renotation_ovoid( specification).lower() if interpolation_method == 'linear': x = LinearInterpolator1d([lower_hue_angle, upper_hue_angle], [x_minus, x_plus])(hue_angle) y = LinearInterpolator1d([lower_hue_angle, upper_hue_angle], [y_minus, y_plus])(hue_angle) elif interpolation_method == 'radial': theta = LinearInterpolator1d([lower_hue_angle, upper_hue_angle], [theta_minus, theta_plus])(hue_angle) rho = LinearInterpolator1d([lower_hue_angle, upper_hue_angle], [rho_minus, rho_plus])(hue_angle) x = rho * np.cos(np.radians(theta)) + x_grey y = rho * np.sin(np.radians(theta)) + y_grey else: raise ValueError( 'Invalid interpolation method: "{0}"'.format( interpolation_method)) return x, y
[docs]def LCHab_to_munsell_specification(LCHab): """ Converts from *CIE LCHab* colourspace to approximate *Munsell* *Colorlab* specification. Parameters ---------- LCHab : array_like, (3,) *CIE LCHab* colourspace matrix. Returns ------- tuple *Munsell* *Colorlab* specification. Notes ----- - Input :math:`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) # doctest: +ELLIPSIS (8.0362412..., 10.0, 3.5013295..., 1) """ L, C, Hab = np.ravel(LCHab) if Hab == 0: code = 8 elif Hab <= 36: code = 7 elif Hab <= 72: code = 6 elif Hab <= 108: code = 5 elif Hab <= 144: code = 4 elif Hab <= 180: code = 3 elif Hab <= 216: code = 2 elif Hab <= 252: code = 1 elif Hab <= 288: code = 10 elif Hab <= 324: code = 9 else: code = 8 hue = LinearInterpolator1d([0, 36], [0, 10])(Hab % 36) if hue == 0: hue = 10 value = L / 10 chroma = C / 5 return hue, value, chroma, code
[docs]def maximum_chroma_from_renotation(hue, value, code): """ 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 ------- numeric Maximum chroma. 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 """ # Ideal white, no chroma. if value >= 9.99: return 0 assert 1 <= value <= 10, ( '"{0}" value must be in domain [1, 10]!'.format(value)) if value % 1 == 0: value_minus = value value_plus = value else: value_minus = np.floor(value) value_plus = value_minus + 1 hue_cw, hue_ccw = bounding_hues_from_renotation(hue, code) hue_cw, code_cw = hue_cw hue_ccw, code_ccw = hue_ccw maximum_chromas = _munsell_maximum_chromas_from_renotation() spc_for_indexes = [chroma[0] for chroma in maximum_chromas] ma_limit_mcw = maximum_chromas[ spc_for_indexes.index((hue_cw, value_minus, code_cw))][1] ma_limit_mccw = maximum_chromas[ spc_for_indexes.index((hue_ccw, value_minus, code_ccw))][1] if value_plus <= 9: ma_limit_pcw = maximum_chromas[ spc_for_indexes.index((hue_cw, value_plus, code_cw))][1] ma_limit_pccw = maximum_chromas[ spc_for_indexes.index((hue_ccw, value_plus, code_ccw))][1] max_chroma = min(ma_limit_mcw, ma_limit_mccw, ma_limit_pcw, ma_limit_pccw) else: L = luminance_ASTMD153508(value) L9 = luminance_ASTMD153508(9) L10 = luminance_ASTMD153508(10) max_chroma = min(LinearInterpolator1d([L9, L10], [ma_limit_mcw, 0])(L), LinearInterpolator1d([L9, L10], [ma_limit_mccw, 0])( L)) return max_chroma
[docs]def munsell_specification_to_xy(specification): """ 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 ------- tuple *xy* chromaticity coordinates. 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)) # doctest: +ELLIPSIS (0.440063..., 0.552242...) >>> munsell_specification_to_xy(8) # doctest: +ELLIPSIS (0.31006..., 0.31616...) """ if is_grey_munsell_colour(specification): return MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES else: hue, value, chroma, code = specification assert 0 <= value <= 10, ( '"{0}" specification value must be in domain [0, 10]!'.format( specification)) assert is_integer(value), ( '"{0}" specification value must be an integer!'.format( specification)) value = round(value) if chroma % 2 == 0: chroma_minus = chroma_plus = chroma else: chroma_minus = 2 * np.floor(chroma / 2) chroma_plus = chroma_minus + 2 if chroma_minus == 0: # Smallest chroma ovoid collapses to illuminant chromaticity # coordinates. x_minus, y_minus = ( MUNSELL_DEFAULT_ILLUMINANT_CHROMATICITY_COORDINATES) else: x_minus, y_minus = xy_from_renotation_ovoid( (hue, value, chroma_minus, code)) x_plus, y_plus = xy_from_renotation_ovoid( (hue, value, chroma_plus, code)) if chroma_minus == chroma_plus: x = x_minus y = y_minus else: x = LinearInterpolator1d([chroma_minus, chroma_plus], [x_minus, x_plus])(chroma) y = LinearInterpolator1d([chroma_minus, chroma_plus], [y_minus, y_plus])(chroma) return x, y