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

# # !!! D . R . A . F . T !!!

# # Lightness

# [Lightness](http://en.wikipedia.org/wiki/Lightness) is defined as the brightness of an area judged relative to the brightness of a similarly illuminated area that appears to be white or highly transmitting. <a name="back_reference_1"></a><a href="#reference_1">[1]</a>
# 
# [Colour](https://github.com/colour-science/colour/) defines the following *Lightness* computation methods:

# In[1]:


import colour

sorted(colour.LIGHTNESS_METHODS.keys())


# > Note: `'Lstar1976'` is a convenient aliases for `'CIE 1976'`.

# ## Glasser, Mckinney, Reilly and Schnelle (1958) Method

# Glasser, Mckinney, Reilly and Schnelle (1958) described a visually uniform colour coordinate system close to *Adams* chromatic-value system but where the quintic-parabola function has been replaced with a cube-root function: the *Cube-Root Color Coordinate System*.
# 
# *Lightness* $L$ in the *Cube-Root Color Coordinate System* is calculated as follows: <a name="back_reference_2"></a><a href="#reference_2">[2]</a>
# 
# $$
# \begin{equation}
# L=25.29Y^{1/3}-18.38
# \end{equation}
# $$
# 
# where $Y$ defines the *luminance* in domain [0, 100].
# 
# The `colour.lightness_Glasser1958` definition is used to compute *Lightness* $L$:

# In[2]:


colour.colorimetry.lightness_Glasser1958(10.08)


# > Note: Input *luminance* $Y$ is in domain [0, 100], output *Lightness* $L$ is in domain [0, 100].
# 
# The `colour.lightness` definition is implemented as a wrapper for various lightness computation methods:

# In[3]:


colour.lightness(10.08, method='Glasser 1958')


# In[4]:


from colour.plotting import *


# In[5]:


colour_style();


# In[6]:


# Plotting the "Glasser (1958)" "Lightness" function.
plot_single_lightness_function('Glasser 1958');


# ## Wyszecki (1963) Method

# Wyszecki (1963) recommended the following cube root function to compute *Lightness* $W$ as a function of the luminance factor $Y$ within the practically important range of $1.0\%<Y<98\%$: <a name="back_reference_3"></a><a href="#reference_3">[3]</a>
# 
# $$
# \begin{equation}
# W=25Y^{1/3}-17
# \end{equation}
# $$
# 
# The `colour.lightness_Wyszecki1963` definition is used to compute *Lightness* $W$:

# In[7]:


colour.colorimetry.lightness_Wyszecki1963(10.08)


# > Note: Input *luminance* $Y$ is in domain [0, 100], output *Lightness* $W$ is in domain [0, 100].
# 
# Using the `colour.lightness` wrapper definition:

# In[8]:


colour.lightness(10.08, method='Wyszecki 1963')


# In[9]:


# Plotting the "Wyszecki (1963)" "Lightness" function.
with colour.utilities.suppress_warnings():
    plot_single_lightness_function('Wyszecki 1963');


# ## CIE 1976 Method

# The *CIE $L^*a^*b^*$* approximately uniform colourspace defined in 1976 computes the *Lightness* $L^*$ quantity as follows: <a name="back_reference_4"></a><a href="#reference_4">[4]</a>
# 
# $$
# \begin{equation}
# L^*=\begin{cases}116\biggl(\cfrac{Y}{Y_n}\biggr)^{1/3}-16 & for\ \cfrac{Y}{Y_n}>\epsilon\\
# \kappa*\biggl(\cfrac{Y}{Y_n}\biggr) & for\ \cfrac{Y}{Y_n}<=\epsilon
# \end{cases}
# \end{equation}
# $$
# where $Y_n$ is the reference white *luminance*.
# with
# $$
# \begin{equation}
# \begin{aligned}
# \epsilon&\ =\begin{cases}0.008856 & Actual\ CIE\ Standard\\
# 216\ /\ 24389 & Intent\ of\ the\ CIE\ Standard
# \end{cases}\\
# \kappa&\ =\begin{cases}903.3 & Actual\ CIE\ Standard\\
# 24389\ /\ 27 & Intent\ of\ the\ CIE\ Standard
# \end{cases}
# \end{aligned}
# \end{equation}
# $$
# 
# The original $\epsilon$ and $\kappa$ constants values have been shown to exhibit discontinuity at the junction point of the two functions grafted together to create the *Lightness* $L^*$ function. <a name="back_reference_5"></a><a href="#reference_5">[5]</a>
# 
# [Colour](https://github.com/colour-science/colour/) uses the rational values instead of the decimal values for these constants.
# 
# > See Also: The [CIE $L^*a^*b^*$ Colourspace](../models/cie_lab.ipynb) notebook for in-depth informations about the *CIE $L^*a^*b^*$* colourspace.
# 
# The `colour.lightness_CIE1976` definition is used to compute *Lightness* $L^*$:

# In[10]:


colour.colorimetry.lightness_CIE1976(10.08)


# > Note: Input *luminance* $Y$ and $Y_n$ are in domain [0, 100], output *Lightness* $L^*$ is in domain [0, 100].
# 
# Using the `colour.lightness` wrapper definition:

# In[11]:


colour.lightness(10.08)


# In[12]:


colour.lightness(10.08, method='CIE 1976', Y_n=95)


# In[13]:


colour.lightness(10.08, method='Lstar1976', Y_n=95)


# In[14]:


# Plotting the "CIE 1976" "Lightness" function.
plot_single_lightness_function('CIE 1976');


# In[15]:


# Plotting multiple "Lightness" functions for comparison.
plot_multi_lightness_functions(['CIE 1976', 'Glasser 1958']);


# ## Fairchild and Wyble (2010) Method

# In[16]:


colour.colorimetry.lightness_Fairchild2010(10.08 / 100, 1.836)


# In[17]:


colour.lightness(10.08 / 100, method='Fairchild 2010', epsilon=1.836)


# In[18]:


# Plotting the "Fairchild and Wyble (2010)" "Lightness" function.
plot_single_lightness_function('Fairchild 2010');


# In[19]:


# Plotting multiple "Lightness" functions for comparison.
plot_multi_lightness_functions(['CIE 1976', 'Fairchild 2010']);


# ## Fairchild and Chen (2011) Method

# In[20]:


colour.colorimetry.lightness_Fairchild2011(10.08 / 100, 0.710)


# In[21]:


colour.lightness(10.08 / 100, method='Fairchild 2011', epsilon=0.710)


# In[22]:


# Plotting the "Fairchild and Chen (2011)" "Lightness" function.
plot_single_lightness_function('Fairchild 2011');


# In[23]:


# Plotting multiple "Lightness" functions for comparison.
plot_multi_lightness_functions(['CIE 1976', 'Fairchild 2011']);


# ## Bibliography

# 1. <a href="#back_reference_1">^<a> <a name="reference_1"></a>CIE. (n.d.). 117-680 lightness (of a related colour). Retrieved July 09, 2014, from http://eilv.cie.co.at/term/680
# 2. <a href="#back_reference_2">^<a> <a name="reference_2"></a>Glasser, L. G., McKinney, A. H., Reilly, C. D., & Schnelle, P. D. (1958). Cube-Root Color Coordinate System. J. Opt. Soc. Am., 48(10), 736–740. doi:10.1364/JOSA.48.000736
# 3. <a href="#back_reference_3">^<a> <a name="reference_3"></a>Wyszecki, G. (1963). Proposal for a New Color-Difference Formula. J. Opt. Soc. Am., 53(11), 1318–1319. doi:10.1364/JOSA.53.001318
# 4. <a href="#back_reference_4">^<a> <a name="reference_4"></a>Wyszecki, G., & Stiles, W. S. (2000). CIE 1976 (L\*u\*v\*)-Space and Color-Difference Formula. In *Color Science: Concepts and Methods, Quantitative Data and Formulae* (p. 167). Wiley. ISBN:978-0471399186
# 5. <a href="#back_reference_5">^<a> <a name="reference_5"></a>Lindbloom, B. (2003). A Continuity Study of the CIE L* Function. Retrieved February 24, 2014, from http://brucelindbloom.com/LContinuity.html