Source code for colour.models.cie_lab

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

"""
CIE Lab Colourspace
===================

Defines the *CIE Lab* colourspace transformations:

-   :func:`XYZ_to_Lab`
-   :func:`Lab_to_XYZ`
-   :func:`Lab_to_LCHab`
-   :func:`LCHab_to_Lab`

See Also
--------
`CIE Lab Colourspace IPython Notebook
<http://nbviewer.ipython.org/github/colour-science/colour-ipython/blob/master/notebooks/models/cie_lab.ipynb>`_  # noqa

References
----------
.. [1]  Wikipedia. (n.d.). Lab color space. Retrieved February 24, 2014, from
        http://en.wikipedia.org/wiki/Lab_color_space
"""

from __future__ import division, unicode_literals

import numpy as np

from colour.colorimetry import ILLUMINANTS
from colour.constants import CIE_E, CIE_K
from colour.models import xy_to_XYZ

__author__ = 'Colour Developers'
__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__ = ['XYZ_to_Lab',
           'Lab_to_XYZ',
           'Lab_to_LCHab',
           'LCHab_to_Lab']


[docs]def XYZ_to_Lab(XYZ, illuminant=ILLUMINANTS.get( 'CIE 1931 2 Degree Standard Observer').get('D50')): """ Converts from *CIE XYZ* colourspace to *CIE Lab* colourspace. Parameters ---------- XYZ : array_like, (3,) *CIE XYZ* colourspace matrix. illuminant : array_like, optional Reference *illuminant* chromaticity coordinates. Returns ------- ndarray, (3,) *CIE Lab* colourspace matrix. Notes ----- - Input *CIE XYZ* is in domain [0, 1]. - Input *illuminant* chromaticity coordinates are in domain [0, 1]. - Output *Lightness* :math:`L^*` is in domain [0, 100]. References ---------- .. [2] Lindbloom, B. (2003). XYZ to Lab. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_XYZ_to_Lab.html Examples -------- >>> XYZ = np.array([0.07049534, 0.1008, 0.09558313]) >>> XYZ_to_Lab(XYZ) # doctest: +ELLIPSIS array([ 37.9856291..., -23.6230288..., -4.4141703...]) """ X, Y, Z = np.ravel(XYZ) X_r, Y_r, Z_r = np.ravel(xy_to_XYZ(illuminant)) x_r = X / X_r y_r = Y / Y_r z_r = Z / Z_r f_x = x_r ** (1 / 3) if x_r > CIE_E else (CIE_K * x_r + 16) / 116 f_y = y_r ** (1 / 3) if y_r > CIE_E else (CIE_K * y_r + 16) / 116 f_z = z_r ** (1 / 3) if z_r > CIE_E else (CIE_K * z_r + 16) / 116 L = 116 * f_y - 16 a = 500 * (f_x - f_y) b = 200 * (f_y - f_z) return np.array([L, a, b])
[docs]def Lab_to_XYZ(Lab, illuminant=ILLUMINANTS.get( 'CIE 1931 2 Degree Standard Observer').get('D50')): """ Converts from *CIE Lab* colourspace to *CIE XYZ* colourspace. Parameters ---------- Lab : array_like, (3,) *CIE Lab* colourspace matrix. illuminant : array_like, optional Reference *illuminant* chromaticity coordinates. Returns ------- ndarray, (3,) *CIE XYZ* colourspace matrix. Notes ----- - Input *Lightness* :math:`L^*` is in domain [0, 100]. - Input *illuminant* chromaticity coordinates are in domain [0, 1]. - Output *CIE XYZ* colourspace matrix is in domain [0, 1]. References ---------- .. [3] Lindbloom, B. (2008). Lab to XYZ. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_Lab_to_XYZ.html Examples -------- >>> Lab = np.array([37.9856291, -23.62302887, -4.41417036]) >>> Lab_to_XYZ(Lab) # doctest: +ELLIPSIS array([ 0.0704953..., 0.1008 , 0.0955831...]) """ L, a, b = np.ravel(Lab) X_r, Y_r, Z_r = np.ravel(xy_to_XYZ(illuminant)) f_y = (L + 16) / 116 f_x = a / 500 + f_y f_z = f_y - b / 200 x_r = f_x ** 3 if f_x ** 3 > CIE_E else (116 * f_x - 16) / CIE_K y_r = ((L + 16) / 116) ** 3 if L > CIE_K * CIE_E else L / CIE_K z_r = f_z ** 3 if f_z ** 3 > CIE_E else (116 * f_z - 16) / CIE_K X = x_r * X_r Y = y_r * Y_r Z = z_r * Z_r return np.array([X, Y, Z])
[docs]def Lab_to_LCHab(Lab): """ Converts from *CIE Lab* colourspace to *CIE LCHab* colourspace. Parameters ---------- Lab : array_like, (3,) *CIE Lab* colourspace matrix. Returns ------- ndarray, (3,) *CIE LCHab* colourspace matrix. Notes ----- - *Lightness* :math:`L^*` is in domain [0, 100]. References ---------- .. [4] Lindbloom, B. (2007). Lab to LCH(ab). Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_Lab_to_LCH.html Examples -------- >>> Lab = np.array([37.9856291, -23.62302887, -4.41417036]) >>> Lab_to_LCHab(Lab) # doctest: +ELLIPSIS array([ 37.9856291..., 24.0319036..., 190.5841597...]) """ L, a, b = np.ravel(Lab) H = 180 * np.arctan2(b, a) / np.pi if H < 0: H += 360 return np.array([L, np.sqrt(a ** 2 + b ** 2), H])
[docs]def LCHab_to_Lab(LCHab): """ Converts from *CIE LCHab* colourspace to *CIE Lab* colourspace. Parameters ---------- LCHab : array_like, (3,) *CIE LCHab* colourspace matrix. Returns ------- ndarray, (3,) *CIE Lab* colourspace matrix. Notes ----- - *Lightness* :math:`L^*` is in domain [0, 100]. References ---------- .. [5] Lindbloom, B. (2006). LCH(ab) to Lab. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_LCH_to_Lab.html Examples -------- >>> LCHab = np.array([37.9856291, 24.03190365, 190.58415972]) >>> LCHab_to_Lab(LCHab) # doctest: +ELLIPSIS array([ 37.9856291..., -23.6230288..., -4.4141703...]) """ L, C, H = np.ravel(LCHab) return np.array([L, C * np.cos(np.radians(H)), C * np.sin(np.radians(H))])