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

# # Illuminants

# An illuminant is a radiation with a spectral distribution defined over the wavelength range that influences object colour perception. <a name="back_reference_1"></a><a href="#reference_1">[1]</a>
# 
# [Colour](https://github.com/colour-science/colour/) ships the following illuminant spectral distributions:

# In[1]:


import colour

print(sorted(colour.ILLUMINANTS_SDS.keys()))


# ## CIE Standard Illuminant A

# As per *CIE publication CIE S005/E-1998*: <a name="back_reference_2"></a><a href="#reference_2">[2]</a>
# 
# > [CIE Standard Illuminant A](http://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_A) is intended to represent typical, domestic, tungsten-filament lighting. Its spectral distribution is that of a Planckian radiator at a temperature of approximately 2856 K. *CIE Standard Illuminant A* should be used in all applications of colorimetry involving the use of incandescent lighting, unless there are specific reasons for using a different illuminant.
# 
# The *CIE Standard Illuminant A* has the following range and increments:

# In[2]:


colour.ILLUMINANTS_SDS['A'].shape


# In[3]:


from colour.plotting import *


# In[4]:


colour_style();


# In[5]:


plot_single_illuminant_sd('A');


# ## CIE Illuminant B

# The [CIE Illuminant B](http://en.wikipedia.org/wiki/Standard_illuminant#Illuminants_B_and_C) is a daylight simulator intended to represent direct noon sunlight with a *correlated colour temperature* of 4874 K.
# 
# The *CIE Illuminant B* has the following range and increments:

# In[6]:


colour.ILLUMINANTS_SDS['B'].shape


# In[7]:


plot_single_illuminant_sd('B');


# ## CIE Illuminant C

# The [CIE Illuminant C](http://en.wikipedia.org/wiki/Standard_illuminant#Illuminants_B_and_C) is also a daylight simulator but intended to represent average daylight with a *correlated colour temperature* of 6774 K.
# 
# The *CIE Illuminant B* and *CIE Illuminant C* are poor approximations of any common light source and deprecated in favor of *CIE Illuminant D Series*. Both are deficient in their spectral distribution in the ultraviolet region which is important for fluorescent materials.
# 
# As per *CIE 015:2004 Colorimetry, 3rd Edition*: <a name="back_reference_3"></a><a href="#reference_3">[3]</a>
# 
# > Illuminant C does not have the status of a CIE standard but its spectral distribution, tristimulus values and chromaticity coordinates are given in Table T.1 and Table T.3, as many practical measurement instruments and computations still use this illuminant.
# 
# The *CIE Illuminant C* has the following range and increments:

# In[8]:


colour.ILLUMINANTS_SDS['C'].shape


# In[9]:


plot_single_illuminant_sd('C');


# *CIE Standard Illuminant A*, *CIE Illuminant B*, and *CIE Illuminant C* spectral distributions are shown here altogether:

# In[10]:


plot_multi_illuminant_sds(['A', 'B', 'C']);


# In[11]:


# Plotting *CIE Standard Illuminant A*, *CIE Illuminant B*, and * CIE Illuminant C* with their normalised colours.
plot_multi_illuminant_sds(['A', 'B', 'C'],
                          use_sds_colours=True,
                          normalise_sds_colours=True);


# *CIE Standard Illuminant A*, *CIE Illuminant B*, and *CIE Illuminant C* chromaticity coordinates plotted against the [Planckian Locus](http://en.wikipedia.org/wiki/Planckian_locus) into the *CIE 1931 Chromaticity Diagram*:

# In[12]:


plot_planckian_locus_in_chromaticity_diagram_CIE1931(['A', 'B', 'C']);


# Notice how the isotemperature lines are not perpendicular to the *Planckian Locus*, the *CIE 1960 UCS Chromaticity Diagram* with perpendicular isotemperature lines is better suited for *correlated colour temperature* computations:

# In[13]:


with colour.utilities.suppress_warnings(python_warnings=True):
    plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(['A', 'B', 'C']);


# In[14]:


# Zooming into the *Planckian Locus*.
with colour.utilities.suppress_warnings(python_warnings=True):
    plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
        ['A', 'B', 'C'], bounding_box=[0.15, 0.35, 0.25, 0.45]);


# ##  CIE Illuminant D Series

# The [CIE Illuminant D Series](http://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_series_D) are intended to model natural daylight and should be used in all colorimetric computations requiring representative daylight. <a name="back_reference_2"></a><a href="#reference_2">[2]</a>
# 
# The *CIE Standard Illuminant D65* defines the spectral distribution representing a phase of daylight with a correlated colour temperature of approximately 6 500 K (called also "nominal correlated colour temperature of the daylight illuminant"). <a name="back_reference_4"></a><a href="#reference_4">[4]</a>
# 
# > Note: *CIE Standard Illuminant A* and *CIE Standard Illuminant D65* are the only illuminants considered as *standard* in the *CIE Colour System*. <a name="back_reference_4"></a><a href="#reference_4">[4]</a>
# 
# Relative spectral distributions of the following *CIE Illuminant D Series* are available:

# In[15]:


import re
sorted(filter(lambda x: re.match('D\d{2}', x), 
              colour.ILLUMINANTS_SDS.keys()))


# The spectral distribution $\lbrace S_D(\lambda)d\lambda\rbrace$ of a *CIE Illuminant D Series* is the result of the linear combination of a mean distribution $\lbrace S_0(\lambda)d\lambda\rbrace$ and two distributions $\lbrace S_1(\lambda)d\lambda\rbrace$ and $\lbrace S_2(\lambda)d\lambda\rbrace$ being the most important *eigen vectors* of the all daylight distributions: <a name="back_reference_5"></a><a href="#reference_5">[5]</a><a name="back_reference_6"></a><a href="#reference_6">[6]</a>
# 
# $$
# \begin{equation}
# S_D(\lambda)=S_0(\lambda)+M_1S_1(\lambda)+M_2S_2(\lambda)
# \end{equation}
# $$
# where
# $$
# \begin{equation}
# \begin{aligned}
# M_1&=\cfrac{-1.3515-1.7703x_d+5.9114y_d}{M}\\
# M_2&=\cfrac{0.0300-31.4424x_d+30.0717y_d}{M}\\
# M&=0.0241+0.2562x_d-0.7341y_d
# \end{aligned}
# \end{equation}
# $$
# 
# The *CIE Illuminant D Series* have the following range and increments:

# In[16]:


for key, value in sorted(colour.ILLUMINANTS_SDS.items()):
    if re.match('D\d{2}', key):
        print('{0}: {1}'.format(key, value.shape))


# In[17]:


# Plotting *CIE Illuminant D Series* S spectral distributions.
plot_multi_sds(sorted(colour.colorimetry.D_ILLUMINANTS_S_SDS.values(), key=lambda x: x.title), 
               title='CIE Illuminant D Series - S Distributions');


# In[18]:


# Plotting *CIE Illuminant D Series* into the *Planckian Locus*.
plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
    sorted(filter(lambda x: re.match('D\d{2}', x),
                  colour.ILLUMINANTS_SDS.keys())),
    bounding_box=[0.15, 0.35, 0.25, 0.45]);


# ## CIE Illuminant E

# The [CIE Illuminant E](http://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_E) is a theoretical reference equal energy radiator. All the wavelengths of its spectral distribution are weighted equally with a spectral of 100.0. *CIE Illuminant E* is not a *blackbody* so it doesn't have a colour temperature, but it can be approximated by a *CIE Illuminant D Series* with a correlated colour temperature of 5455 K (*CIE Illuminant D55* is the closest match).
# 
# The *CIE Illuminant E* has the following range and increments:

# In[19]:


colour.ILLUMINANTS_SDS['E'].shape


# In[20]:


plot_planckian_locus_in_chromaticity_diagram_CIE1960UCS(
    ['D55', 'E'], bounding_box=[0.15, 0.35, 0.25, 0.45]);


# In[21]:


plot_single_illuminant_sd('E');


# ## Illuminants F Series

# The [Illuminants F Series](http://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_series_F) are not *CIE Standard Illuminants*, but they have been compiled by the *CIE* for use as representative fluorescent lighting distributions for practical purposes.
# 
# The first 12, *FL1* to *FL12*, are in three different groups, *Normal*, *Broad-Band*, and *Three-Band*:
# 
# * *F1* to *F6* are *Normal* and consist of two *semi-broadband* emissions of antimony and manganese activations in calcium halophosphate phosphor.
# * *F7* to *F9* are *Broad-Band* full-spectrum light fluorescent lamps with multiple phosphors, and higher [colour rendering indexes](http://en.wikipedia.org/wiki/Color_rendering_index).
# * *F10* to *F12* are *Three-Band* illuminants consisting of three *Narrow-Band* emissions caused by ternary compositions of rare-earth phosphors.
# 
# *F2*, *F7* and *F11* are intended for use in preference to the others when the choice within each group is not critical.
# 
# The subsequent 15, *FL3.1* to *FL3.15*, are in five different groups: *Halophosphate*, *DeLuxe*, *Three-Band*, *Multi-Band*, and *D65 Simulator*:
# 
# * *FL3.1* to *FL3.3* form the *Halophosphate* group.
# * *FL3.4* to *FL3.6* form the *DeLuxe* group.
# * *FL3.7* to *FL3.11* form the *Three-Band* group.
# * *FL3.12* to *FL3.14* form the *Multi-Band* group.
# * *FL3.15* is the *D65 Simulator*.
# 
# The *Illuminants F Series* have the following range and increments:

# In[22]:


for key, value in sorted(colour.ILLUMINANTS_SDS.items()):
    if re.match('F\d{1,2}|FL3\.\d{1,2}', key):
        print('{0}: {1}'.format(key, value.shape))


# In[23]:


# Plotting the *Normal* group of fluorescent illuminants.
plot_multi_illuminant_sds(['FL1', 'FL2', 'FL3', 'FL4', 'FL5', 'FL6']);


# In[24]:


# Plotting the *Broad-Band* group of fluorescent illuminants.
plot_multi_illuminant_sds(['FL7', 'FL8', 'FL9']);


# In[25]:


# Plotting the *Three-Band* group of fluorescent illuminants.
plot_multi_illuminant_sds(['FL10', 'FL11', 'FL12']);


# In[26]:


# Plotting the *Halophosphate* group of fluorescent illuminants.
plot_multi_illuminant_sds(['FL3.1', 'FL3.2', 'FL3.3']);


# In[27]:


# Plotting the *DeLuxe* group of fluorescent illuminants.
plot_multi_illuminant_sds(['FL3.4', 'FL3.5', 'FL3.6']);


# In[28]:


# Plotting the *Three-Band* group of fluorescent illuminants.
plot_multi_illuminant_sds(
    ['FL3.7', 'FL3.8', 'FL3.9', 'FL3.10', 'FL3.11']);


# In[29]:


# Plotting the *Multi-Band* group of fluorescent illuminants.
plot_multi_illuminant_sds(['FL3.12', 'FL3.13', 'FL3.14']);


# In[30]:


# Plotting *D65 Simulator* fluorescent illuminant against *CIE Standard Illuminant D65*.
plot_multi_illuminant_sds(['FL3.15', 'D65']);


# ## High Pressure Discharge Lamps

# The [High pressure discharge lamps](http://en.wikipedia.org/wiki/Gas-discharge_lamp) are artificial light sources generating light by sending an electrical discharge through an ionized gas.
# 
# * *HP1* is a standard high pressure sodium lamp.
# * *HP2* is a colour enhanced high pressure sodium lamp.
# * *HP3* to *HP5* are three types of high pressure metal halide lamps.
# 
# The *High pressure discharge lamps* have the following range and increments:

# In[31]:


for key, value in sorted(colour.ILLUMINANTS_SDS.items()):
    if re.match('HP\d', key):
        print('{0}: {1}'.format(key, value.shape))


# In[32]:


# Plotting all *high pressure discharge* lamps.
plot_multi_illuminant_sds(
    sorted(filter(lambda x: re.match('HP\d', x), 
                  colour.ILLUMINANTS_SDS.keys())));


# ## Chromaticity Coordinates

# For convenience purpose the chromaticity coordinates of the provided illuminants are given for the *CIE 1931 2° Standard Observer* and *CIE 1964 10° Standard Observer*:

# In[33]:


sorted(colour.ILLUMINANTS['CIE 1931 2 Degree Standard Observer'].items())


# > Note: `'cie_2_1931'` is defined as a convenient alias for `'CIE 1931 2 Degree Standard Observer'`:

# In[34]:


sorted(colour.ILLUMINANTS['cie_2_1931'])


# In[35]:


sorted(colour.ILLUMINANTS['CIE 1964 10 Degree Standard Observer'].items())


# > Note: `'cie_10_1964'` is defined as a convenient alias for `'CIE 1964 10 Degree Standard Observer'`:

# In[36]:


sorted(colour.ILLUMINANTS['cie_10_1964'])


# They are either coming from published sources or have been calculated using the `colour.sd_to_XYZ` and `colour.XYZ_to_xy` definitions:

# In[37]:


cmfs=colour.STANDARD_OBSERVERS_CMFS.get('CIE 1931 2 Degree Standard Observer')
for illuminant, sd in sorted(colour.ILLUMINANTS_SDS.items()):
    print(illuminant, colour.XYZ_to_xy(colour.sd_to_XYZ(sd, cmfs)))


# ## HunterLab Dataset

# For usage with *Hunter L,a,b* and *Hunter Rd,a,b* colour scales and practises, [Colour](https://github.com/colour-science/colour/) defines the following illuminants tristimulus values and chromaticity coefficients for the *CIE 1931 2° Standard Observer* and *CIE 1964 10° Standard Observer*:

# In[38]:


sorted(colour.HUNTERLAB_ILLUMINANTS['CIE 1931 2 Degree Standard Observer'].items())


# In[39]:


sorted(colour.HUNTERLAB_ILLUMINANTS['CIE 1964 10 Degree Standard Observer'].items())


# > Note: `'cie_2_1931'` and `'cie_10_1964'` aliases are also valid for the HunterLab dataset.

# ## Bibliography

# 1. <a href="#back_reference_1">^<a> <a name="reference_1"></a>CIE. (n.d.). 17-554 illuminant. Retrieved June 26, 2014, from http://eilv.cie.co.at/term/554
# 2. <a href="#back_reference_2">^<a> <a name="reference_2"></a>CIE. (n.d.). CIE Colorimetry - Part 2: Standard Illuminants for Colorimetry. Retrieved from http://www.cie.co.at/index.php/index.php?i_ca_id=484
# 3. <a href="#back_reference_3">^<a> <a name="reference_3"></a>CIE TC 1-48. (2004). CIE 015:2004 Colorimetry, 3rd Edition. CIE 015:2004 Colorimetry, 3rd Edition (pp. 1–82). ISBN:978-3-901-90633-6
# 4. <a href="#back_reference_4">^<a> <a name="reference_4"></a>CIE. (n.d.). CIE Colorimetry - Part 2: Standard Illuminants for Colorimetry. Retrieved June 23, 2014, from http://www.cie.co.at/index.php/index.php?i_ca_id=484
# 5. <a href="#back_reference_5">^<a> <a name="reference_5"></a>Wyszecki, G., & Stiles, W. S. (2000). CIE Method of Calculating D-Illuminants. In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 145–146). Wiley. ISBN:978-0471399186
# 6. <a href="#back_reference_6">^<a> <a name="reference_6"></a>Lindbloom, B. (2007). Spectral Distribution of a CIE D-Illuminant. Retrieved April 05, 2014, from http://www.brucelindbloom.com/Eqn_DIlluminant.html

# ## Dataset

# 1. *CIE Standard Illuminant A*: CIE. (n.d.). CIE Spectral Data. Retrieved from http://files.cie.co.at/204.xls
# 2. *CIE Illuminant B*: Hunt, R. W. G., & Pointer, M. R. (2011). Appendix 5: Spectral Distributions of Illuminants. In Measuring Colour (pp. 355–378). John Wiley & Sons, Ltd. doi:10.1002/9781119975595.app5
# 3. *CIE Illuminant C*: CIE. (n.d.). CIE 15:2004 Tables Data. Retrieved from https://law.resource.org/pub/us/cfr/ibr/003/cie.15.2004.tables.xls
# 4. *CIE Illuminant D Series*: CIE. (n.d.). CIE 15:2004 Tables Data. Retrieved from https://law.resource.org/pub/us/cfr/ibr/003/cie.15.2004.tables.xls
# 5. *CIE Illuminant E*: Computed with [colour](https://github.com/colour-science/colour/)
# 6. *Illuminants F Series*: CIE. (n.d.). CIE 15:2004 Tables Data. Retrieved from https://law.resource.org/pub/us/cfr/ibr/003/cie.15.2004.tables.xls
# 7. *High Pressure Discharge Lamps*: CIE. (n.d.). CIE 15:2004 Tables Data. Retrieved from https://law.resource.org/pub/us/cfr/ibr/003/cie.15.2004.tables.xls
# 8. Chromaticity Coordinates: Wikipedia. (n.d.). White points of standard illuminants. Retrieved February 24, 2014, from http://en.wikipedia.org/wiki/Standard_illuminant#White_points_of_standard_illuminants
# 9. HunterLab Dataset: HunterLab. (2008). Hunter L,a,b Color Scale. Retrieved from http://www.hunterlab.se/wp-content/uploads/2012/11/Hunter-L-a-b.pdf