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]  http://en.wikipedia.org/wiki/Lab_color_space
        (Last accessed 24 February 2014)
"""

from __future__ import division, unicode_literals

import math
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 - 2014 - 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] http://www.brucelindbloom.com/Eqn_XYZ_to_Lab.html (Last accessed 24 February 2014) Examples -------- >>> XYZ_to_Lab(np.array([0.92193107, 1, 1.03744246])) # doctest: +ELLIPSIS array([ 100. , -7.4178784..., -15.8574210...]) """ X, Y, Z = np.ravel(XYZ) Xr, Yr, Zr = np.ravel(xy_to_XYZ(illuminant)) xr = X / Xr yr = Y / Yr zr = Z / Zr fx = xr ** (1 / 3) if xr > CIE_E else (CIE_K * xr + 16) / 116 fy = yr ** (1 / 3) if yr > CIE_E else (CIE_K * yr + 16) / 116 fz = zr ** (1 / 3) if zr > CIE_E else (CIE_K * zr + 16) / 116 L = 116 * fy - 16 a = 500 * (fx - fy) b = 200 * (fy - fz) 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] http://www.brucelindbloom.com/Eqn_Lab_to_XYZ.html (Last accessed 24 February 2014) Examples -------- >>> Lab = np.array([100, -7.41787844, -15.85742105]) >>> Lab_to_XYZ(Lab) # doctest: +ELLIPSIS array([ 0.9219310..., 1. , 1.0374424...]) """ L, a, b = np.ravel(Lab) Xr, Yr, Zr = np.ravel(xy_to_XYZ(illuminant)) fy = (L + 16) / 116 fx = a / 500 + fy fz = fy - b / 200 xr = fx ** 3 if fx ** 3 > CIE_E else (116 * fx - 16) / CIE_K yr = ((L + 16) / 116) ** 3 if L > CIE_K * CIE_E else L / CIE_K zr = fz ** 3 if fz ** 3 > CIE_E else (116 * fz - 16) / CIE_K X = xr * Xr Y = yr * Yr Z = zr * Zr 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] http://www.brucelindbloom.com/Eqn_Lab_to_LCH.html (Last accessed 24 February 2014) Examples -------- >>> Lab = np.array([100, -7.41787844, -15.85742105]) >>> Lab_to_LCHab(Lab) # doctest: +ELLIPSIS array([ 100. , 17.5066479..., 244.9304684...]) """ L, a, b = np.ravel(Lab) H = 180 * math.atan2(b, a) / math.pi if H < 0: H += 360 return np.array([L, math.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] http://www.brucelindbloom.com/Eqn_LCH_to_Lab.html (Last accessed 24 February 2014) Examples -------- >>> LCHab = np.array([100, 17.50664796, 244.93046842]) >>> LCHab_to_Lab(LCHab) # doctest: +ELLIPSIS array([ 100. , -7.4178784..., -15.8574210...]) """ L, C, H = np.ravel(LCHab) return np.array([L, C * math.cos(math.radians(H)), C * math.sin(math.radians(H))])