colour Package¶

Subpackages¶

• adaptation: Chromatic adaptation models and transformations.
• algebra: Algebra utilities.
• appearance: Colour appearance models.
• characterisation: Colour fitting and camera characterisation.
• colorimetry: Core objects for colour computations.
• constants: CIE and CODATA constants.
• corresponding: Corresponding colour chromaticities computations.
• difference: Colour difference computations.
• examples: Examples for the sub-packages.
• io: Input / output objects for reading and writing data.
• models: Colour models.
• notation: Colour notation systems.
• phenomenons: Computation of various optical phenomenons.
• plotting: Diagrams, figures, etc...
• quality: Colour quality computation.
• recovery: Reflectance recovery.
• temperature: Colour temperature and correlated colour temperature computation.
• utilities: Various utilities and data structures.
• volume: Colourspace volumes computation and optimal colour stimuli.

colour.chromatic_adaptation_matrix_VonKries(XYZ_w, XYZ_wr, transform=u'CAT02')¶

Computes the chromatic adaptation matrix from test viewing conditions to reference viewing conditions.

Parameters:	XYZ_w (array_like) – Test viewing condition CIE XYZ tristimulus values of whitepoint. XYZ_wr (array_like) – Reference viewing condition CIE XYZ tristimulus values of whitepoint. transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:	Chromatic adaptation matrix.
Return type:	ndarray
Raises:	KeyError – If chromatic adaptation method is not defined.

Examples

>>> XYZ_w = np.array([1.09846607, 1.00000000, 0.35582280])
>>> XYZ_wr = np.array([0.95042855, 1.00000000, 1.08890037])
>>> chromatic_adaptation_matrix_VonKries(XYZ_w, XYZ_wr)    
array([[ 0.8687653..., -0.1416539...,  0.3871961...],
       [-0.1030072...,  1.0584014...,  0.1538646...],
       [ 0.0078167...,  0.0267875...,  2.9608177...]])

Using Bradford method:

>>> XYZ_w = np.array([1.09846607, 1.00000000, 0.35582280])
>>> XYZ_wr = np.array([0.95042855, 1.00000000, 1.08890037])
>>> method = 'Bradford'
>>> chromatic_adaptation_matrix_VonKries(XYZ_w, XYZ_wr, method)    
array([[ 0.8446794..., -0.1179355...,  0.3948940...],
       [-0.1366408...,  1.1041236...,  0.1291981...],
       [ 0.0798671..., -0.1349315...,  3.1928829...]])

colour.chromatic_adaptation_VonKries(XYZ, XYZ_w, XYZ_wr, transform=u'CAT02')¶

Adapts given stimulus from test viewing conditions to reference viewing conditions.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of stimulus to adapt. XYZ_w (array_like) – Test viewing condition CIE XYZ tristimulus values of whitepoint. XYZ_wr (array_like) – Reference viewing condition CIE XYZ tristimulus values of whitepoint. transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:	CIE XYZ_c tristimulus values of the stimulus corresponding colour.
Return type:	ndarray

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_w = np.array([1.09846607, 1.00000000, 0.35582280])
>>> XYZ_wr = np.array([0.95042855, 1.00000000, 1.08890037])
>>> chromatic_adaptation_VonKries(XYZ, XYZ_w, XYZ_wr)  
array([ 0.0839746...,  0.1141321...,  0.2862554...])

Using Bradford method:

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_w = np.array([1.09846607, 1.00000000, 0.35582280])
>>> XYZ_wr = np.array([0.95042855, 1.00000000, 1.08890037])
>>> method = 'Bradford'
>>> chromatic_adaptation_VonKries(XYZ, XYZ_w, XYZ_wr, method)    
array([ 0.0854032...,  0.1140122...,  0.2972149...])

colour.chromatic_adaptation_Fairchild1990(XYZ_1, XYZ_n, XYZ_r, Y_n, discount_illuminant=False)¶

Adapts given stimulus CIE XYZ_1 tristimulus values from test viewing conditions to reference viewing conditions using Fairchild (1990) chromatic adaptation model.

Parameters:	XYZ_1 (array_like) – CIE XYZ_1 tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_n (array_like) – Test viewing condition CIE XYZ_n tristimulus values of whitepoint. XYZ_r (array_like) – Reference viewing condition CIE XYZ_r tristimulus values of whitepoint. Y_n (numeric or array_like) – Luminance \(Y_n\) of test adapting stimulus in \(cd/m^2\). discount_illuminant (bool, optional) – Truth value indicating if the illuminant should be discounted.
Returns:	Adapted CIE XYZ_2 tristimulus values of stimulus.
Return type:	ndarray

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ_1, CIE XYZ_n and CIE XYZ_r tristimulus values are in domain [0, 100].
• Output CIE XYZ_2 tristimulus values are in domain [0, 100].

Examples

>>> XYZ_1 = np.array([19.53, 23.07, 24.97])
>>> XYZ_n = np.array([111.15, 100.00, 35.20])
>>> XYZ_r = np.array([94.81, 100.00, 107.30])
>>> Y_n = 200
>>> chromatic_adaptation_Fairchild1990(XYZ_1, XYZ_n, XYZ_r, Y_n)    
array([ 23.3252634...,  23.3245581...,  76.1159375...])

class colour.CMCCAT2000_InductionFactors¶

Bases: colour.adaptation.cmccat2000.CMCCAT2000_InductionFactors

CMCCAT2000 chromatic adaptation model induction factors.

Parameters:	F (numeric or array_like) – \(F\) surround condition.

colour.CMCCAT2000_forward(XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, surround=CMCCAT2000_InductionFactors(F=1.0))¶

Adapts given stimulus CIE XYZ tristimulus values from test viewing conditions to reference viewing conditions using CMCCAT2000 forward chromatic adaptation model.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of the stimulus to adapt. XYZ_w (array_like) – Test viewing condition CIE XYZ tristimulus values of the whitepoint. XYZ_wr (array_like) – Reference viewing condition CIE XYZ tristimulus values of the whitepoint. L_A1 (numeric or array_like) – Luminance of test adapting field \(L_{A1}\) in \(cd/m^2\). L_A2 (numeric or array_like) – Luminance of reference adapting field \(L_{A2}\) in \(cd/m^2\). surround (CMCCAT2000_InductionFactors, optional) – Surround viewing conditions induction factors.
Returns:	CIE XYZ_c tristimulus values of the stimulus corresponding colour.
Return type:	ndarray

Warning

The input and output domains of that definition are non standard!

Notes

• Input CIE XYZ, CIE XYZ_w and CIE XYZ_wr tristimulus values are in domain [0, 100].
• Output CIE XYZ_c tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([22.48, 22.74, 8.54])
>>> XYZ_w = np.array([111.15, 100.00, 35.20])
>>> XYZ_wr = np.array([94.81, 100.00, 107.30])
>>> L_A1 = 200
>>> L_A2 = 200
>>> CMCCAT2000_forward(XYZ, XYZ_w, XYZ_wr, L_A1, L_A2)    
array([ 19.5269832...,  23.0683396...,  24.9717522...])

colour.CMCCAT2000_reverse(XYZ_c, XYZ_w, XYZ_wr, L_A1, L_A2, surround=CMCCAT2000_InductionFactors(F=1.0))¶

Adapts given stimulus corresponding colour CIE XYZ tristimulus values from reference viewing conditions to test viewing conditions using CMCCAT2000 reverse chromatic adaptation model.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of the stimulus to adapt. XYZ_w (array_like) – Test viewing condition CIE XYZ tristimulus values of the whitepoint. XYZ_wr (array_like) – Reference viewing condition CIE XYZ tristimulus values of the whitepoint. L_A1 (numeric or array_like) – Luminance of test adapting field \(L_{A1}\) in \(cd/m^2\). L_A2 (numeric or array_like) – Luminance of reference adapting field \(L_{A2}\) in \(cd/m^2\). surround (CMCCAT2000_InductionFactors, optional) – Surround viewing conditions induction factors.
Returns:	CIE XYZ_c tristimulus values of the adapted stimulus.
Return type:	ndarray

Warning

The input and output domains of that definition are non standard!

Notes

• Input CIE XYZ_c, CIE XYZ_w and CIE XYZ_wr tristimulus values are in domain [0, 100].
• Output CIE XYZ tristimulus values are in domain [0, 100].

Examples

>>> XYZ_c = np.array([19.53, 23.07, 24.97])
>>> XYZ_w = np.array([111.15, 100.00, 35.20])
>>> XYZ_wr = np.array([94.81, 100.00, 107.30])
>>> L_A1 = 200
>>> L_A2 = 200
>>> CMCCAT2000_reverse(XYZ_c, XYZ_w, XYZ_wr, L_A1, L_A2)    
array([ 22.4839876...,  22.7419485...,   8.5393392...])

colour.chromatic_adaptation_CMCCAT2000(XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, surround=CMCCAT2000_InductionFactors(F=1.0), method=u'Forward')¶

Adapts given stimulus CIE XYZ tristimulus values using given viewing conditions.

This definition is a convenient wrapper around CMCCAT2000_forward() and CMCCAT2000_reverse().

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of the stimulus to adapt. XYZ_w (array_like) – Source viewing condition CIE XYZ tristimulus values of the whitepoint. XYZ_wr (array_like) – Target viewing condition CIE XYZ tristimulus values of the whitepoint. L_A1 (numeric or array_like) – Luminance of test adapting field \(L_{A1}\) in \(cd/m^2\). L_A2 (numeric or array_like) – Luminance of reference adapting field \(L_{A2}\) in \(cd/m^2\). surround (CMCCAT2000_InductionFactors, optional) – Surround viewing conditions induction factors. method (unicode, optional) – {‘Forward’, ‘Reverse’} Chromatic adaptation method.
Returns:	Adapted stimulus CIE XYZ tristimulus values.
Return type:	ndarray

Warning

The input and output domains of that definition are non standard!

Notes

• Input CIE XYZ, CIE XYZ_w and CIE XYZ_wr tristimulus values are in domain [0, 100].
• Output CIE XYZ tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([22.48, 22.74, 8.54])
>>> XYZ_w = np.array([111.15, 100.00, 35.20])
>>> XYZ_wr = np.array([94.81, 100.00, 107.30])
>>> L_A1 = 200
>>> L_A2 = 200
>>> chromatic_adaptation_CMCCAT2000(XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, method='Forward')    
array([ 19.5269832...,  23.0683396...,  24.9717522...])

Using the CMCCAT2000 reverse model:

>>> XYZ = np.array([19.52698326, 23.06833960, 24.97175229])
>>> XYZ_w = np.array([111.15, 100.00, 35.20])
>>> XYZ_wr = np.array([94.81, 100.00, 107.30])
>>> L_A1 = 200
>>> L_A2 = 200
>>> chromatic_adaptation_CMCCAT2000(XYZ, XYZ_w, XYZ_wr, L_A1, L_A2, method='Reverse')    
array([ 22.48,  22.74,   8.54])

colour.chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2, n=1)¶

Adapts given stimulus CIE XYZ_1 tristimulus values from test viewing conditions to reference viewing conditions using CIE 1994 chromatic adaptation model.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. xy_o1 (array_like) – Chromaticity coordinates \(x_{o1}\) and \(y_{o1}\) of test illuminant and background. xy_o2 (array_like) – Chromaticity coordinates \(x_{o2}\) and \(y_{o2}\) of reference illuminant and background. Y_o (numeric) – Luminance factor \(Y_o\) of achromatic background as percentage in domain [18, 100]. E_o1 (numeric) – Test illuminance \(E_{o1}\) in \(cd/m^2\). E_o2 (numeric) – Reference illuminance \(E_{o2}\) in \(cd/m^2\). n (numeric, optional) – Noise component in fundamental primary system.
Returns:	Adapted CIE XYZ_2 tristimulus values of test stimulus.
Return type:	ndarray

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ_1 tristimulus values are in domain [0, 100].
• Output CIE XYZ_2 tristimulus values are in domain [0, 100].

Examples

>>> XYZ_1 = np.array([28.00, 21.26, 5.27])
>>> xy_o1 = np.array([0.4476, 0.4074])
>>> xy_o2 = np.array([0.3127, 0.3290])
>>> Y_o = 20
>>> E_o1 = 1000
>>> E_o2 = 1000
>>> chromatic_adaptation_CIE1994(XYZ_1, xy_o1, xy_o2, Y_o, E_o1, E_o2)    
array([ 24.0337952...,  21.1562121...,  17.6430119...])

colour.cartesian_to_spherical(vector)¶

Transforms given Cartesian coordinates vector to Spherical coordinates.

Parameters:	vector (array_like) – Cartesian coordinates vector (x, y, z) to transform.
Returns:	Spherical coordinates vector (r, theta, phi).
Return type:	ndarray

See also

spherical_to_cartesian(), cartesian_to_cylindrical(), cylindrical_to_cartesian()

Examples

>>> vector = np.array([3, 1, 6])
>>> cartesian_to_spherical(vector)  
array([ 6.7823299...,  1.0857465...,  0.3217505...])

colour.spherical_to_cartesian(vector)¶

Transforms given Spherical coordinates vector to Cartesian coordinates.

Parameters:	vector (array_like) – Spherical coordinates vector (r, theta, phi) to transform.
Returns:	Cartesian coordinates vector (x, y, z).
Return type:	ndarray

See also

cartesian_to_spherical(), cartesian_to_cylindrical(), cylindrical_to_cartesian()

Examples

>>> vector = np.array([6.78232998, 1.08574654, 0.32175055])
>>> spherical_to_cartesian(vector)  
array([ 3.        ,  0.9999999...,  6.        ])

colour.cartesian_to_cylindrical(vector)¶

Transforms given Cartesian coordinates vector to Cylindrical coordinates.

Parameters:	vector (array_like) – Cartesian coordinates vector (x, y, z) to transform.
Returns:	Cylindrical coordinates vector (z, theta, rho).
Return type:	ndarray

See also

cartesian_to_spherical(), spherical_to_cartesian(), cylindrical_to_cartesian()

Examples

>>> vector = np.array([3, 1, 6])
>>> cartesian_to_cylindrical(vector)  
array([ 6.        ,  0.3217505...,  3.1622776...])

colour.cylindrical_to_cartesian(vector)¶

Transforms given Cylindrical coordinates vector to Cartesian coordinates.

Parameters:	vector (array_like) – Cylindrical coordinates vector (z, theta, rho) to transform.
Returns:	Cartesian coordinates vector (x, y, z).
Return type:	ndarray

See also

cartesian_to_spherical(), spherical_to_cartesian(), cartesian_to_cylindrical()

Examples

>>> vector = np.array([6.00000000, 0.32175055, 3.16227766])
>>> cylindrical_to_cartesian(vector)  
array([ 3.        ,  0.9999999...,  6.        ])

class colour.Extrapolator1d(interpolator=None, method=u'Linear', left=None, right=None)¶

Bases: object

Extrapolates the 1-D function of given interpolator.

The Extrapolator1d acts as a wrapper around a given Colour or scipy interpolator class instance with compatible signature. Two extrapolation methods are available:

• Linear: Linearly extrapolates given points using the slope defined by the interpolator boundaries (xi[0], xi[1]) if x < xi[0] and (xi[-1], xi[-2]) if x > xi[-1].
• Constant: Extrapolates given points by assigning the interpolator boundaries values xi[0] if x < xi[0] and xi[-1] if x > xi[-1].

Specifying the left and right arguments takes precedence on the chosen extrapolation method and will assign the respective left and right values to the given points.

Parameters:	interpolator (object) – Interpolator object. method (unicode, optional) – {‘Linear’, ‘Constant’}, Extrapolation method. left (numeric, optional) – Value to return for x < xi[0]. right (numeric, optional) – Value to return for x > xi[-1].

__class__()¶

Notes

The interpolator must define x and y attributes.

References

[1]	sastanin. (n.d.). How to make scipy.interpolate give an extrapolated result beyond the input range? Retrieved August 08, 2014, from http://stackoverflow.com/a/2745496/931625

Examples

Extrapolating a single numeric variable:

>>> from colour.algebra import LinearInterpolator1d
>>> x = np.array([3, 4, 5])
>>> y = np.array([1, 2, 3])
>>> interpolator = LinearInterpolator1d(x, y)
>>> extrapolator = Extrapolator1d(interpolator)
>>> extrapolator(1)
-1.0

Extrapolating an array_like variable:

>>> extrapolator(np.array([6, 7 , 8]))
array([ 4.,  5.,  6.])

Using the Constant extrapolation method:

>>> x = np.array([3, 4, 5])
>>> y = np.array([1, 2, 3])
>>> interpolator = LinearInterpolator1d(x, y)
>>> extrapolator = Extrapolator1d(interpolator, method='Constant')
>>> extrapolator(np.array([0.1, 0.2, 8, 9]))
array([ 1.,  1.,  3.,  3.])

Using defined left boundary and Constant extrapolation method:

>>> x = np.array([3, 4, 5])
>>> y = np.array([1, 2, 3])
>>> interpolator = LinearInterpolator1d(x, y)
>>> extrapolator = Extrapolator1d(interpolator, method='Constant', left=0)
>>> extrapolator(np.array([0.1, 0.2, 8, 9]))
array([ 0.,  0.,  3.,  3.])

__call__(x)¶

Evaluates the Extrapolator1d at given point(s).

Parameters:	x (numeric or array_like) – Point(s) to evaluate the Extrapolator1d at.
Returns:	Extrapolated points value(s).
Return type:	float or ndarray

interpolator¶

Property for self.__interpolator private attribute.

Returns:	self.__interpolator
Return type:	object

left¶

Property for self.__left private attribute.

Returns:	self.__left
Return type:	numeric

method¶

Property for self.__method private attribute.

Returns:	self.__method
Return type:	unicode

right¶

Property for self.__right private attribute.

Returns:	self.__right
Return type:	numeric

class colour.LinearInterpolator1d(x=None, y=None)¶

Bases: object

Linearly interpolates a 1-D function.

Parameters:	x (ndarray) – Independent \(x\) variable values corresponding with \(y\) variable. y (ndarray) – Dependent and already known \(y\) variable values to interpolate.

__call__()¶

Notes

This class is a wrapper around numpy.interp definition.

See also

SpragueInterpolator

Examples

Interpolating a single numeric variable:

>>> y = np.array([5.9200,
...               9.3700,
...               10.8135,
...               4.5100,
...               69.5900,
...               27.8007,
...               86.0500])
>>> x = np.arange(len(y))
>>> f = LinearInterpolator1d(x, y)
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> f(0.5)  
7.64...

Interpolating an array_like variable:

>>> f([0.25, 0.75])
array([ 6.7825,  8.5075])

__call__(x)

Evaluates the interpolating polynomial at given point(s).

Parameters:	x (numeric or array_like) – Point(s) to evaluate the interpolant at.
Returns:	Interpolated value(s).
Return type:	float or ndarray

x¶

Property for self.__x private attribute.

Returns:	self.__x
Return type:	array_like

y¶

Property for self.__y private attribute.

Returns:	self.__y
Return type:	array_like

class colour.SplineInterpolator(*args, **kwargs)¶

Bases: scipy.interpolate.interpolate.interp1d

Interpolates a 1-D function using cubic spline interpolation.

Notes

This class is a wrapper around scipy.interpolate.interp1d class.

class colour.SpragueInterpolator(x=None, y=None)¶

Bases: object

Constructs a fifth-order polynomial that passes through \(y\) dependent variable.

Sprague (1880) method is recommended by the CIE for interpolating functions having a uniformly spaced independent variable.

Parameters:	x (array_like) – Independent \(x\) variable values corresponding with \(y\) variable. y (array_like) – Dependent and already known \(y\) variable values to interpolate.

__call__()¶

See also

LinearInterpolator1d

Notes

The minimum number \(k\) of data points required along the interpolation axis is \(k=6\).

References

[1]	CIE TC 1-38. (2005). 9.2.4 Method of interpolation for uniformly spaced independent variable. In CIE 167:2005 Recommended Practice for Tabulating Spectral Data for Use in Colour Computations (pp. 1–27). ISBN:978-3-901-90641-1

[2]	Westland, S., Ripamonti, C., & Cheung, V. (2012). Interpolation Methods. In Computational Colour Science Using MATLAB (2nd ed., pp. 29–37). ISBN:978-0-470-66569-5

Examples

Interpolating a single numeric variable:

>>> y = np.array([5.9200,
...               9.3700,
...               10.8135,
...               4.5100,
...               69.5900,
...               27.8007,
...               86.0500])
>>> x = np.arange(len(y))
>>> f = SpragueInterpolator(x, y)
>>> f(0.5)  
7.2185025...

Interpolating an array_like variable:

>>> f([0.25, 0.75])  
array([ 6.7295161...,  7.8140625...])

SPRAGUE_C_COEFFICIENTS = array([[ 884, -1960, 3033, -2648, 1080, -180], [ 508, -540, 488, -367, 144, -24], [ -24, 144, -367, 488, -540, 508], [ -180, 1080, -2648, 3033, -1960, 884]])¶

__call__(x)

Evaluates the interpolating polynomial at given point(s).

Parameters:	x (numeric or array_like) – Point(s) to evaluate the interpolant at.
Returns:	Interpolated value(s).
Return type:	numeric or ndarray

x¶

Property for self.__x private attribute.

Returns:	self.__x
Return type:	array_like

y¶

Property for self.__y private attribute.

Returns:	self.__y
Return type:	array_like

colour.is_identity(x, n=3)¶

Returns if given array_like variable \(x\) is an identity matrix.

Parameters:	x (array_like, (N)) – Variable \(x\) to test. n (int, optional) – Matrix dimension.
Returns:	Is identity matrix.
Return type:	bool

Examples

>>> is_identity(np.array([1, 0, 0, 0, 1, 0, 0, 0, 1]).reshape(3, 3))
True
>>> is_identity(np.array([1, 2, 0, 0, 1, 0, 0, 0, 1]).reshape(3, 3))
False

random_triplet_generator(size, limits=array([[0, 1],

[0, 1],

[0, 1]]), random_state=<mtrand.RandomState object at 0x2adc363d0a98>)

Returns a generator yielding random triplets.

Parameters:	size (integer) – Generator size. limits (array_like, (3, 2)) – Random values limits on each triplet axis. random_state (RandomState) – Mersenne Twister pseudo-random number generator.
Returns:	Random triplets generator.
Return type:	generator

Notes

The doctest is assuming that np.random.RandomState() definition will return the same sequence no matter which OS or Python version is used. There is however no formal promise about the prng sequence reproducibility of either Python or *Numpy implementations: Laurent. (2012). Reproducibility of python pseudo-random numbers across systems and versions? Retrieved January 20, 2015, from http://stackoverflow.com/questions/8786084/reproducibility-of-python-pseudo-random-numbers-across-systems-and-versions

Examples

>>> from pprint import pprint
>>> prng = np.random.RandomState(4)
>>> pprint(tuple(random_triplet_generator(10, random_state=prng)))    
(array([ 0.9670298...,  0.5472322...,  0.9726843...]),
 array([ 0.7148159...,  0.6977288...,  0.2160895...]),
 array([ 0.9762744...,  0.0062302...,  0.2529823...]),
 array([ 0.4347915...,  0.7793829...,  0.1976850...]),
 array([ 0.8629932...,  0.9834006...,  0.1638422...]),
 array([ 0.5973339...,  0.0089861...,  0.3865712...]),
 array([ 0.0441600...,  0.9566529...,  0.4361466...]),
 array([ 0.9489773...,  0.7863059...,  0.8662893...]),
 array([ 0.1731654...,  0.0749485...,  0.6007427...]),
 array([ 0.1679721...,  0.7333801...,  0.4084438...]))

class colour.Hunt_InductionFactors¶

Bases: colour.appearance.hunt.Hunt_InductionFactors

Hunt colour appearance model induction factors.

Parameters:

N_c (numeric or array_like) – Chromatic surround induction factor \(N_c\). N_b (numeric or array_like) – Brightness surround induction factor \(N_b\). N_cb (numeric or array_like, optional) – Chromatic background induction factor \(N_{cb}\), approximated using tristimulus values \(Y_w\) and \(Y_b\) of respectively the reference white and the background if not specified. N_bb (numeric or array_like, optional) – Brightness background induction factor \(N_{bb}\), approximated using tristimulus values \(Y_w\) and \(Y_b\) of respectively the reference white and the background if not specified.

class colour.Hunt_Specification¶

Bases: colour.appearance.hunt.Hunt_Specification

Defines the Hunt colour appearance model specification.

This specification has field names consistent with the remaining colour appearance models in colour.appearance but diverge from Fairchild (2013) reference.

Parameters:

J (numeric or array_like) – Correlate of Lightness \(J\). C (numeric or array_like) – Correlate of chroma \(C_94\). h (numeric or array_like) – Hue angle \(h_S\) in degrees. s (numeric or array_like) – Correlate of saturation \(s\). Q (numeric or array_like) – Correlate of brightness \(Q\). M (numeric or array_like) – Correlate of colourfulness \(M_94\). H (numeric or array_like) – Hue \(h\) quadrature \(H\). HC (numeric or array_like) – Hue \(h\) composition \(H_C\).

colour.XYZ_to_Hunt(XYZ, XYZ_w, XYZ_b, L_A, surround=Hunt_InductionFactors(N_c=1, N_b=75, N_cb=None, N_bb=None), L_AS=None, CCT_w=None, XYZ_p=None, p=None, S=None, S_W=None, helson_judd_effect=False, discount_illuminant=True)¶

Computes the Hunt colour appearance model correlates.

Parameters:

XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_w (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100]. XYZ_b (array_like) – CIE XYZ tristimulus values of background in domain [0, 100]. L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\). surround (Hunt_InductionFactors, optional) – Surround viewing conditions induction factors. L_AS (numeric or array_like, optional) – Scotopic luminance \(L_{AS}\) of the illuminant, approximated if not specified. CCT_w (numeric or array_like, optional) – Correlated color temperature \(T_{cp}\): of the illuminant, needed to approximate \(L_{AS}\). XYZ_p (array_like, optional) – CIE XYZ tristimulus values of proximal field in domain [0, 100], assumed to be equal to background if not specified. p (numeric or array_like, optional) – Simultaneous contrast / assimilation factor \(p\) with value in domain [-1, 0] when simultaneous contrast occurs and domain [0, 1] when assimilation occurs. S (numeric or array_like, optional) – Scotopic response \(S\) to the stimulus, approximated using tristimulus values \(Y\) of the stimulus if not specified. S_w (numeric or array_like, optional) – Scotopic response \(S_w\) for the reference white, approximated using the tristimulus values \(Y_w\) of the reference white if not specified. helson_judd_effect (bool, optional) – Truth value indicating whether the Helson-Judd effect should be accounted for. discount_illuminant (bool, optional) – Truth value indicating if the illuminant should be discounted.

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Input CIE XYZ_b tristimulus values are in domain [0, 100].
• Input CIE XYZ_w tristimulus values are in domain [0, 100].
• Input CIE XYZ_p tristimulus values are in domain [0, 100].

Returns:	Hunt colour appearance model specification.
Return type:	Hunt_Specification
Raises:	ValueError – If an illegal arguments combination is specified.

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_w = np.array([95.05, 100.00, 108.88])
>>> XYZ_b = np.array([95.05, 100.00, 108.88])
>>> L_A = 318.31
>>> surround = HUNT_VIEWING_CONDITIONS['Normal Scenes']
>>> CCT_w = 6504.0
>>> XYZ_to_Hunt(XYZ, XYZ_w, XYZ_b, L_A, surround, CCT_w=CCT_w)    
Hunt_Specification(J=30.0462678..., C=0.1210508..., h=269.2737594..., s=0.0199093..., Q=22.2097654..., M=0.1238964..., H=None, HC=None)

class colour.ATD95_Specification¶

Bases: colour.appearance.atd95.ATD95_Specification

Defines the ATD (1995) colour vision model specification.

This specification has field names consistent with the remaining colour appearance models in colour.appearance but diverge from Fairchild (2013) reference.

Notes

• This specification is the one used in the current model implementation.

Parameters:

h (numeric or array_like) – Hue angle \(H\) in degrees. C (numeric or array_like) – Correlate of saturation \(C\). Guth (1995) incorrectly uses the terms saturation and chroma interchangeably. However, \(C\) is here a measure of saturation rather than chroma since it is measured relative to the achromatic response for the stimulus rather than that of a similarly illuminated white. Q (numeric or array_like) – Correlate of brightness \(Br\). A_1 (numeric or array_like) – First stage \(A_1\) response. T_1 (numeric or array_like) – First stage \(T_1\) response. D_1 (numeric or array_like) – First stage \(D_1\) response. A_2 (numeric or array_like) – Second stage \(A_2\) response. T_2 (numeric or array_like) – Second stage \(A_2\) response. D_2 (numeric or array_like) – Second stage \(D_2\) response.

colour.XYZ_to_ATD95(XYZ, XYZ_0, Y_0, k_1, k_2, sigma=300)¶

Computes the ATD (1995) colour vision model correlates.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_0 (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100]. Y_0 (numeric or array_like) – Absolute adapting field luminance in \(cd/m^2\). k_1 (numeric or array_like) – Application specific weight \(k_1\). k_2 (numeric or array_like) – Application specific weight \(k_2\). sigma (numeric or array_like, optional) – Constant \(\sigma\) varied to predict different types of data.
Returns:	ATD (1995) colour vision model specification.
Return type:	ATD95_Specification

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Input CIE XYZ_0 tristimulus values are in domain [0, 100].
• For unrelated colors, there is only self-adaptation, and \(k_1\) is set to 1.0 while \(k_2\) is set to 0.0. For related colors such as typical colorimetric applications, \(k_1\) is set to 0.0 and \(k_2\) is set to a value between 15 and 50 (Guth, 1995).

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_0 = np.array([95.05, 100.00, 108.88])
>>> Y_0 = 318.31
>>> k_1 = 0.0
>>> k_2 = 50.0
>>> XYZ_to_ATD95(XYZ, XYZ_0, Y_0, k_1, k_2)  
ATD95_Specification(h=1.9089869..., C=1.2064060..., Q=0.1814003..., A_1=0.1787931... T_1=0.0286942..., D_1=0.0107584..., A_2=0.0192182..., T_2=0.0205377..., D_2=0.0107584...)

class colour.CIECAM02_InductionFactors¶

Bases: colour.appearance.ciecam02.CIECAM02_InductionFactors

CIECAM02 colour appearance model induction factors.

Parameters:	F (numeric or array_like) – Maximum degree of adaptation \(F\). c (numeric or array_like) – Exponential non linearity \(c\). N_c (numeric or array_like) – Chromatic induction factor \(N_c\).

class colour.CIECAM02_Specification¶

Bases: colour.appearance.ciecam02.CIECAM02_Specification

Defines the CIECAM02 colour appearance model specification.

Parameters:

J (numeric or array_like) – Correlate of Lightness \(J\). C (numeric or array_like) – Correlate of chroma \(C\). h (numeric or array_like) – Hue angle \(h\) in degrees. s (numeric or array_like) – Correlate of saturation \(s\). Q (numeric or array_like) – Correlate of brightness \(Q\). M (numeric or array_like) – Correlate of colourfulness \(M\). H (numeric or array_like) – Hue \(h\) quadrature \(H\). HC (numeric or array_like) – Hue \(h\) composition \(H^C\).

colour.XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b, surround=CIECAM02_InductionFactors(F=1, c=0.69, N_c=1), discount_illuminant=False)¶

Computes the CIECAM02 colour appearance model correlates from given CIE XYZ tristimulus values.

This is the forward implementation.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_w (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100]. L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\). Y_b (numeric or array_like) – Adapting field Y tristimulus value \(Y_b\). surround (CIECAM02_InductionFactors, optional) – Surround viewing conditions induction factors. discount_illuminant (bool, optional) – Truth value indicating if the illuminant should be discounted.
Returns:	CIECAM02 colour appearance model specification.
Return type:	CIECAM02_Specification

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Input CIE XYZ_w tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_w = np.array([95.05, 100.00, 108.88])
>>> L_A = 318.31
>>> Y_b = 20.0
>>> surround = CIECAM02_VIEWING_CONDITIONS['Average']
>>> XYZ_to_CIECAM02(XYZ, XYZ_w, L_A, Y_b, surround)  
CIECAM02_Specification(J=41.7310911..., C=0.1047077..., h=219.0484326..., s=2.3603053..., Q=195.3713259..., M=0.1088421..., H=array(278.0607358...), HC=None)

colour.CIECAM02_to_XYZ(J, C, h, XYZ_w, L_A, Y_b, surround=CIECAM02_InductionFactors(F=1, c=0.69, N_c=1), discount_illuminant=False)¶

Converts CIECAM02 specification to CIE XYZ tristimulus values.

This is the reverse implementation.

Parameters:	CIECAM02_Specification (CIECAM02_Specification) – CIECAM02 specification. XYZ_w (array_like) – CIE XYZ tristimulus values of reference white. L_A (numeric or array_like) – Adapting field luminance \(L_A\) in \(cd/m^2\). Y_b (numeric or array_like) – Adapting field Y tristimulus value \(Y_b\). surround (CIECAM02_Surround, optional) – Surround viewing conditions. discount_illuminant (bool, optional) – Discount the illuminant.
Returns:	XYZ – CIE XYZ tristimulus values.
Return type:	ndarray

Warning

The output domain of that definition is non standard!

Notes

• Input CIE XYZ_w tristimulus values are in domain [0, 100].
• Output CIE XYZ tristimulus values are in domain [0, 100].

Examples

>>> J = 41.731091132513917
>>> C = 0.1047077571711053
>>> h = 219.04843265827190
>>> XYZ_w = np.array([95.05, 100.00, 108.88])
>>> L_A = 318.31
>>> Y_b = 20.0
>>> CIECAM02_to_XYZ(J, C, h, XYZ_w, L_A, Y_b)  
array([ 19.01...,  20...  ,  21.78...])

class colour.LLAB_Specification¶

Bases: colour.appearance.llab.LLAB_Specification

Defines the LLAB(l:c) colour appearance model specification.

This specification has field names consistent with the remaining colour appearance models in colour.appearance but diverge from Fairchild (2013) reference.

Parameters:

J (numeric or array_like) – Correlate of Lightness \(L_L\). C (numeric or array_like) – Correlate of chroma \(Ch_L\). h (numeric or array_like) – Hue angle \(h_L\) in degrees. s (numeric or array_like) – Correlate of saturation \(s_L\). M (numeric or array_like) – Correlate of colourfulness \(C_L\). HC (numeric or array_like) – Hue \(h\) composition \(H^C\). a (numeric or array_like) – Opponent signal \(A_L\). b (numeric or array_like) – Opponent signal \(B_L\).

colour.XYZ_to_LLAB(XYZ, XYZ_0, Y_b, L, surround=LLAB_InductionFactors(D=1, F_S=3, F_L=1, F_C=1))¶

Computes the LLAB(l:c) colour appearance model correlates.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_0 (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100]. Y_b (numeric or array_like) – Luminance factor of the background in \(cd/m^2\). L (numeric or array_like) – Absolute luminance \(L\) of reference white in \(cd/m^2\). surround (LLAB_InductionFactors, optional) – Surround viewing conditions induction factors.
Returns:	LLAB(l:c) colour appearance model specification.
Return type:	LLAB_Specification

Warning

The output domain of that definition is non standard!

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Input CIE XYZ_0 tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_0 = np.array([95.05, 100.00, 108.88])
>>> Y_b = 20.0
>>> L = 318.31
>>> surround = LLAB_VIEWING_CONDITIONS['ref_average_4_minus']
>>> XYZ_to_LLAB(XYZ, XYZ_0, Y_b, L, surround)  
LLAB_Specification(J=37.3668650..., C=0.0089496..., h=270.0000000..., s=0.0002395..., M=0.0190185..., HC=None, a=1.4742890..., b=-0.0190185...)

class colour.Nayatani95_Specification¶

Bases: colour.appearance.nayatani95.Nayatani95_Specification

Defines the Nayatani (1995) colour appearance model specification.

This specification has field names consistent with the remaining colour appearance models in colour.appearance but diverge from Fairchild (2013) reference.

Parameters:

Lstar_P (numeric or array_like) – Correlate of achromatic Lightness \(L_p^\star\). C (numeric or array_like) – Correlate of chroma \(C\). h (numeric or array_like) – Hue angle \(\theta\) in degrees. s (numeric or array_like) – Correlate of saturation \(S\). Q (numeric or array_like) – Correlate of brightness \(B_r\). M (numeric or array_like) – Correlate of colourfulness \(M\). H (numeric or array_like) – Hue \(h\) quadrature \(H\). HC (numeric or array_like) – Hue \(h\) composition \(H_C\). Lstar_N (numeric or array_like) – Correlate of normalised achromatic Lightness \(L_n^\star\).

colour.XYZ_to_Nayatani95(XYZ, XYZ_n, Y_o, E_o, E_or, n=1)¶

Computes the Nayatani (1995) colour appearance model correlates.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_n (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100]. Y_o (numeric or array_like) – Luminance factor \(Y_o\) of achromatic background as percentage in domain [0.18, 1.0] E_o (numeric or array_like) – Illuminance \(E_o\) of the viewing field in lux. E_or (numeric or array_like) – Normalising illuminance \(E_{or}\) in lux usually in domain [1000, 3000] n (numeric or array_like, optional) – Noise term used in the non linear chromatic adaptation model.
Returns:	Nayatani (1995) colour appearance model specification.
Return type:	Nayatani95_Specification

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Input CIE XYZ_n tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_n = np.array([95.05, 100.00, 108.88])
>>> Y_o = 20.0
>>> E_o = 5000.0
>>> E_or = 1000.0
>>> XYZ_to_Nayatani95(XYZ, XYZ_n, Y_o, E_o, E_or)  
Nayatani95_Specification(Lstar_P=49.9998829..., C=0.0133550..., h=257.5232268..., s=0.0133550..., Q=62.6266734..., M=0.0167262..., H=None, HC=None, Lstar_N=50.0039154...)

class colour.RLAB_Specification¶

Bases: colour.appearance.rlab.RLAB_Specification

Defines the RLAB colour appearance model specification.

This specification has field names consistent with the remaining colour appearance models in colour.appearance but diverge from Fairchild (2013) reference.

Parameters:

J (numeric or array_like) – Correlate of Lightness \(L^R\). C (numeric or array_like) – Correlate of achromatic chroma \(C^R\). h (numeric or array_like) – Hue angle \(h^R\) in degrees. s (numeric or array_like) – Correlate of saturation \(s^R\). HC (numeric or array_like) – Hue \(h\) composition \(H^C\). a (numeric or array_like) – Red–green chromatic response \(a^R\). b (numeric or array_like) – Yellow–blue chromatic response \(b^R\).

colour.XYZ_to_RLAB(XYZ, XYZ_n, Y_n, sigma=0.4347826086956522, D=1)¶

Computes the RLAB model color appearance correlates.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of test sample / stimulus in domain [0, 100]. XYZ_n (array_like) – CIE XYZ tristimulus values of reference white in domain [0, 100]. Y_n (numeric or array_like) – Absolute adapting luminance in \(cd/m^2\). sigma (numeric or array_like, optional) – Relative luminance of the surround, see RLAB_VIEWING_CONDITIONS for reference. D (numeric or array_like, optional) – Discounting-the-Illuminant factor in domain [0, 1].
Returns:	RLAB colour appearance model specification.
Return type:	RLAB_Specification

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Input CIE XYZ_n tristimulus values are in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20.00, 21.78])
>>> XYZ_n = np.array([109.85, 100, 35.58])
>>> Y_n = 31.83
>>> sigma = RLAB_VIEWING_CONDITIONS['Average']
>>> D = RLAB_D_FACTOR['Hard Copy Images']
>>> XYZ_to_RLAB(XYZ, XYZ_n, Y_n, sigma, D)  
RLAB_Specification(J=49.8347069..., C=54.8700585..., h=286.4860208..., s=1.1010410..., HC=None, a=15.5711021..., b=-52.6142956...)

colour.first_order_colour_fit(m1, m2)¶

Performs a first order colour fit from given \(m1\) colour array to \(m2\) colour array. The resulting colour fitting matrix is computed using multiple linear regression.

The purpose of that object is for example the matching of two ColorChecker colour rendition charts together.

Parameters:	m1 (array_like, (3, n)) – Test array \(m1\) to fit onto array \(m2\). m2 (array_like, (3, n)) – Reference array the array \(m1\) will be colour fitted against.
Returns:	Colour fitting matrix.
Return type:	ndarray, (3, 3)

Examples

>>> m1 = np.array([
...     [0.17224810, 0.09170660, 0.06416938],
...     [0.49189645, 0.27802050, 0.21923399],
...     [0.10999751, 0.18658946, 0.29938611],
...     [0.11666120, 0.14327905, 0.05713804],
...     [0.18988879, 0.18227649, 0.36056247],
...     [0.12501329, 0.42223442, 0.37027445],
...     [0.64785606, 0.22396782, 0.03365194],
...     [0.06761093, 0.11076896, 0.39779139],
...     [0.49101797, 0.09448929, 0.11623839],
...     [0.11622386, 0.04425753, 0.14469986],
...     [0.36867946, 0.44545230, 0.06028681],
...     [0.61632937, 0.32323906, 0.02437089],
...     [0.03016472, 0.06153243, 0.29014596],
...     [0.11103655, 0.30553067, 0.08149137],
...     [0.41162190, 0.05816656, 0.04845934],
...     [0.73339206, 0.53075188, 0.02475212],
...     [0.47347718, 0.08834792, 0.30310315],
...     [0.00000000, 0.25187016, 0.35062450],
...     [0.76809639, 0.78486240, 0.77808297],
...     [0.53822392, 0.54307997, 0.54710883],
...     [0.35458526, 0.35318419, 0.35524431],
...     [0.17976704, 0.18000531, 0.17991488],
...     [0.09351417, 0.09510603, 0.09675027],
...     [0.03405071, 0.03295077, 0.03702047]])
>>> m2 = np.array([
...     [0.15579559, 0.09715755, 0.07514556],
...     [0.39113140, 0.25943419, 0.21266708],
...     [0.12824821, 0.18463570, 0.31508023],
...     [0.12028974, 0.13455659, 0.07408400],
...     [0.19368988, 0.21158946, 0.37955964],
...     [0.19957425, 0.36085439, 0.40678123],
...     [0.48896605, 0.20691688, 0.05816533],
...     [0.09775522, 0.16710693, 0.47147724],
...     [0.39358649, 0.12233400, 0.10526425],
...     [0.10780332, 0.07258529, 0.16151473],
...     [0.27502671, 0.34705454, 0.09728099],
...     [0.43980441, 0.26880559, 0.05430533],
...     [0.05887212, 0.11126272, 0.38552469],
...     [0.12705825, 0.25787860, 0.13566464],
...     [0.35612929, 0.07933258, 0.05118732],
...     [0.48131976, 0.42082843, 0.07120612],
...     [0.34665585, 0.15170714, 0.24969804],
...     [0.08261116, 0.24588716, 0.48707733],
...     [0.66054904, 0.65941137, 0.66376412],
...     [0.48051509, 0.47870296, 0.48230082],
...     [0.33045354, 0.32904184, 0.33228886],
...     [0.18001305, 0.17978567, 0.18004416],
...     [0.10283975, 0.10424680, 0.10384975],
...     [0.04742204, 0.04772203, 0.04914226]])
>>> first_order_colour_fit(m1, m2)  
array([[ 0.6982266...,  0.0307162...,  0.1621042...],
       [ 0.0689349...,  0.6757961...,  0.1643038...],
       [-0.0631495...,  0.0921247...,  0.9713415...]])

class colour.SpectralShape(start=None, end=None, steps=None)¶

Bases: object

Defines the base object for spectral power distribution shape.

Parameters:	start (numeric, optional) – Wavelength \(\lambda_{i}\) range start in nm. end (numeric, optional) – Wavelength \(\lambda_{i}\) range end in nm. steps (numeric, optional) – Wavelength \(\lambda_{i}\) range steps.

start¶

end¶

steps¶

__repr__()¶

__contains__()¶

__len__()¶

__eq__()¶

__ne__()¶

range()¶

Examples

>>> SpectralShape(360, 830, 1)
SpectralShape(360, 830, 1)

__contains__(wavelength)

Returns if the spectral shape contains given wavelength \(\lambda\).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\).
Returns:	Is wavelength \(\lambda\) contained in the spectral shape.
Return type:	bool

Warning

wavelength argument is tested to be contained in the spectral shape within the tolerance defined by colour.constants.common.EPSILON attribute value.

Notes

• Reimplements the object.__contains__() method.

Examples

>>> 0.5 in SpectralShape(0, 10, 0.1)
True
>>> 0.6 in SpectralShape(0, 10, 0.1)
True
>>> 0.51 in SpectralShape(0, 10, 0.1)
False
>>> np.array([0.5, 0.6]) in SpectralShape(0, 10, 0.1)
True
>>> np.array([0.51, 0.6]) in SpectralShape(0, 10, 0.1)
False

__eq__(shape)

Returns the spectral shape equality with given other spectral shape.

Parameters:	shape (SpectralShape) – Spectral shape to compare for equality.
Returns:	Spectral shape equality.
Return type:	bool

Notes

• Reimplements the object.__eq__() method.

Examples

>>> SpectralShape(0, 10, 0.1) == SpectralShape(0, 10, 0.1)
True
>>> SpectralShape(0, 10, 0.1) == SpectralShape(0, 10, 1)
False

__iter__()¶

Returns a generator for the spectral power distribution data.

Returns:	Spectral power distribution data generator.
Return type:	generator

Notes

• Reimplements the object.__iter__() method.

Examples

>>> shape = SpectralShape(0, 10, 1)
>>> for wavelength in shape: print(wavelength)
0.0
1.0
2.0
3.0
4.0
5.0
6.0
7.0
8.0
9.0
10.0

__len__()

Returns the spectral shape wavelength \(\lambda_n\) count.

Returns:	Spectral shape wavelength \(\lambda_n\) count.
Return type:	int

Notes

• Reimplements the object.__len__() method.

Examples

>>> len(SpectralShape(0, 10, 0.1))
101

__ne__(shape)

Returns the spectral shape inequality with given other spectral shape.

Parameters:	shape (SpectralShape) – Spectral shape to compare for inequality.
Returns:	Spectral shape inequality.
Return type:	bool

Notes

• Reimplements the object.__ne__() method.

Examples

>>> SpectralShape(0, 10, 0.1) != SpectralShape(0, 10, 0.1)
False
>>> SpectralShape(0, 10, 0.1) != SpectralShape(0, 10, 1)
True

__repr__()

Returns a formatted string representation.

Returns:	Formatted string representation.
Return type:	unicode

__str__()¶

Returns a nice formatted string representation.

Returns:	Nice formatted string representation.
Return type:	unicode

end

Property for self.__end private attribute.

Returns:	self.__end.
Return type:	numeric

range()

Returns an iterable range for the spectral power distribution shape.

Returns:	Iterable range for the spectral power distribution shape
Return type:	ndarray
Raises:	RuntimeError – If one of spectral shape start, end or steps attributes is not defined.

Examples

>>> SpectralShape(0, 10, 0.1).range()
array([  0. ,   0.1,   0.2,   0.3,   0.4,   0.5,   0.6,   0.7,   0.8,
         0.9,   1. ,   1.1,   1.2,   1.3,   1.4,   1.5,   1.6,   1.7,
         1.8,   1.9,   2. ,   2.1,   2.2,   2.3,   2.4,   2.5,   2.6,
         2.7,   2.8,   2.9,   3. ,   3.1,   3.2,   3.3,   3.4,   3.5,
         3.6,   3.7,   3.8,   3.9,   4. ,   4.1,   4.2,   4.3,   4.4,
         4.5,   4.6,   4.7,   4.8,   4.9,   5. ,   5.1,   5.2,   5.3,
         5.4,   5.5,   5.6,   5.7,   5.8,   5.9,   6. ,   6.1,   6.2,
         6.3,   6.4,   6.5,   6.6,   6.7,   6.8,   6.9,   7. ,   7.1,
         7.2,   7.3,   7.4,   7.5,   7.6,   7.7,   7.8,   7.9,   8. ,
         8.1,   8.2,   8.3,   8.4,   8.5,   8.6,   8.7,   8.8,   8.9,
         9. ,   9.1,   9.2,   9.3,   9.4,   9.5,   9.6,   9.7,   9.8,
         9.9,  10. ])

start

Property for self.__start private attribute.

Returns:	self.__start.
Return type:	numeric

steps

Property for self.__steps private attribute.

Returns:	self.__steps.
Return type:	numeric

class colour.SpectralPowerDistribution(name, data, title=None)¶

Bases: object

Defines the base object for spectral data computations.

Parameters:	name (unicode) – Spectral power distribution name. data (dict) – Spectral power distribution data in a dict as follows: {wavelength \(\lambda_{i}\): value, wavelength \(\lambda_{i+1}\), ..., wavelength \(\lambda_{i+n}\)} title (unicode, optional) – Spectral power distribution title for figures.

name¶

data¶

title¶

wavelengths¶

values¶

items¶

shape¶

__getitem__()¶

__init__()¶

__setitem__()¶

__iter__()¶

__contains__()¶

__len__()¶

__eq__()¶

__ne__()¶

__add__()¶

__sub__()¶

__mul__()¶

__div__()¶

__truediv__()¶

__pow__()¶

get()¶

is_uniform()¶

extrapolate()¶

interpolate()¶

align()¶

zeros()¶

normalise()¶

clone()¶

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.wavelengths
array([510, 520, 530, 540])
>>> spd.values
array([ 49.67,  69.59,  81.73,  88.19])
>>> spd.shape
SpectralShape(510, 540, 10)

__add__(x)

Implements support for spectral power distribution addition.

Parameters:	x (numeric or array_like or SpectralPowerDistribution) – Variable to add.
Returns:	Variable added spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.__sub__(), SpectralPowerDistribution.__mul__(), SpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__add__() method.

Warning

The addition operation happens in place.

Examples

Adding a single numeric variable:

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd + 10  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 59.67,  79.59,  91.73,  98.19])

Adding an array_like variable:

>>> spd + [1, 2, 3, 4]  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([  60.67,   81.59,   94.73,  102.19])

Adding a SpectralPowerDistribution class variable:

>>> spd_alternate = SpectralPowerDistribution('Spd', data)
>>> spd + spd_alternate  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 110.34,  151.18,  176.46,  190.38])

__contains__(wavelength)

Returns if the spectral power distribution contains given wavelength \(\lambda\).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\).
Returns:	Is wavelength \(\lambda\) contained in the spectral power distribution.
Return type:	bool

Warning

wavelength argument is tested to be contained in the spectral power distribution within the tolerance defined by colour.constants.common.EPSILON attribute value.

Notes

• Reimplements the object.__contains__() method.

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> 510 in spd
True
>>> np.array([510, 520]) in spd
True
>>> np.array([510, 520, 521]) in spd
False

__div__(x)

Implements support for spectral power distribution division.

Parameters:	x (numeric or array_like or SpectralPowerDistribution) – Variable to divide.
Returns:	Variable divided spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.__add__(), SpectralPowerDistribution.__sub__(), SpectralPowerDistribution.__mul__()

Notes

• Reimplements the object.__div__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd / 10  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 4.967,  6.959,  8.173,  8.819])

Dividing an array_like variable:

>>> spd / [1, 2, 3, 4]  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 4.967     ,  3.4795    ,  2.72433333,  2.20475   ])

Dividing a SpectralPowerDistribution class variable:

>>> spd_alternate = SpectralPowerDistribution('Spd', data)
>>> spd / spd_alternate  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values  
array([ 0.1       ,  0.05      ,  0.0333333...,  0.025     ])

__eq__(spd)

Returns the spectral power distribution equality with given other spectral power distribution.

Parameters:	spd (SpectralPowerDistribution) – Spectral power distribution to compare for equality.
Returns:	Spectral power distribution equality.
Return type:	bool

Notes

• Reimplements the object.__eq__() method.

Examples

>>> data1 = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> data2 = {510: 48.6700, 520: 69.5900, 530: 81.7300, 540: 88.1900}
>>> spd1 = SpectralPowerDistribution('Spd', data1)
>>> spd2 = SpectralPowerDistribution('Spd', data2)
>>> spd3 = SpectralPowerDistribution('Spd', data2)
>>> spd1 == spd2
False
>>> spd2 == spd3
True

__getitem__(wavelength)

Returns the value for given wavelength \(\lambda\).

Parameters:	wavelength (numeric, array_like or slice) – Wavelength \(\lambda\) to retrieve the value.
Returns:	Wavelength \(\lambda\) value.
Return type:	numeric or ndarray

See also

SpectralPowerDistribution.get()

Notes

• Reimplements the object.__getitem__() method.

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[510]  
array(49.67...)
>>> spd[np.array([510, 520])]
array([ 49.67,  69.59])
>>> spd[:]
array([ 49.67,  69.59,  81.73,  88.19])

__hash__()¶

Returns the spectral power distribution hash value.

Returns:	Object hash.
Return type:	int

Notes

• Reimplements the object.__hash__() method.

Warning

SpectralPowerDistribution class is mutable and should not be hashable. However, so that it can be used as a key in some data caches, we provide a __hash__ implementation, assuming that the underlying data will not change for those specific cases.

References

[1]	Hettinger, R. (n.d.). Python hashable dicts. Retrieved August 08, 2014, from http://stackoverflow.com/a/16162138/931625

__iter__()

Returns a generator for the spectral power distribution data.

Returns:	Spectral power distribution data generator.
Return type:	generator

Notes

• Reimplements the object.__iter__() method.

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> for wavelength, value in spd:
...     print((wavelength, value))  
(510, 49.6...)
(520, 69.5...)
(530, 81.7...)
(540, 88.1...)

__len__()

Returns the spectral power distribution wavelengths \(\lambda_n\) count.

Returns:	Spectral power distribution wavelengths \(\lambda_n\) count.
Return type:	int

Notes

• Reimplements the object.__len__() method.

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> len(spd)
4

__mul__(x)

Implements support for spectral power distribution multiplication.

Parameters:	x (numeric or array_like or SpectralPowerDistribution) – Variable to multiply.
Returns:	Variable multiplied spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.__add__(), SpectralPowerDistribution.__sub__(), SpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__mul__() method.

Warning

The multiplication operation happens in place.

Examples

Multiplying a single numeric variable:

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd * 10  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 496.7,  695.9,  817.3,  881.9])

Multiplying an array_like variable:

>>> spd * [1, 2, 3, 4]  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([  496.7,  1391.8,  2451.9,  3527.6])

Multiplying a SpectralPowerDistribution class variable:

>>> spd_alternate = SpectralPowerDistribution('Spd', data)
>>> spd * spd_alternate  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([  24671.089,   96855.362,  200393.787,  311099.044])

__ne__(spd)

Returns the spectral power distribution inequality with given other spectral power distribution.

Parameters:	spd (SpectralPowerDistribution) – Spectral power distribution to compare for inequality.
Returns:	Spectral power distribution inequality.
Return type:	bool

Notes

• Reimplements the object.__ne__() method.

Examples

>>> data1 = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> data2 = {510: 48.6700, 520: 69.5900, 530: 81.7300, 540: 88.1900}
>>> spd1 = SpectralPowerDistribution('Spd', data1)
>>> spd2 = SpectralPowerDistribution('Spd', data2)
>>> spd3 = SpectralPowerDistribution('Spd', data2)
>>> spd1 != spd2
True
>>> spd2 != spd3
False

__pow__(x)

Implements support for spectral power distribution exponentiation.

Parameters:	x (numeric or array_like or SpectralPowerDistribution) – Variable to exponentiate by.
Returns:	Spectral power distribution raised by power of x.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.__add__(), SpectralPowerDistribution.__sub__(), SpectralPowerDistribution.__mul__(), SpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__pow__() method.

Warning

The power operation happens in place.

Examples

Exponentiation by a single numeric variable:

>>> data = {510: 1.67, 520: 2.59, 530: 3.73, 540: 4.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd ** 2  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([  2.7889,   6.7081,  13.9129,  17.5561])

Exponentiation by an array_like variable:

>>> spd ** [1, 2, 3, 4]  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values  
array([  2.7889000...e+00,   4.4998605...e+01,   2.6931031...e+03,
         9.4997501...e+04])

Exponentiation by a SpectralPowerDistribution class variable:

>>> spd_alternate = SpectralPowerDistribution('Spd', data)
>>> spd ** spd_alternate  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values  
array([  5.5446356...e+00,   1.9133109...e+04,   6.2351033...e+12,
         7.1880990...e+20])

__setitem__(wavelength, value)

Sets the wavelength \(\lambda\) with given value.

Parameters:	wavelength (numeric, array_like or slice) – Wavelength \(\lambda\) to set. value (numeric or array_like) – Value for wavelength \(\lambda\).

Warning

value parameter is resized to match wavelength parameter size.

Notes

• Reimplements the object.__setitem__() method.

Examples

>>> spd = SpectralPowerDistribution('Spd', {})
>>> spd[510] = 49.67
>>> spd.values
array([ 49.67])
>>> spd[np.array([520, 530])] = np.array([69.59, 81.73])
>>> spd.values
array([ 49.67,  69.59,  81.73])
>>> spd[np.array([540, 550])] = 88.19
>>> spd.values
array([ 49.67,  69.59,  81.73,  88.19,  88.19])
>>> spd[:] = 49.67
>>> spd.values
array([ 49.67,  49.67,  49.67,  49.67,  49.67])

__sub__(x)

Implements support for spectral power distribution subtraction.

Parameters:	x (numeric or array_like or SpectralPowerDistribution) – Variable to subtract.
Returns:	Variable subtracted spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.__add__(), SpectralPowerDistribution.__mul__(), SpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__sub__() method.

Warning

The subtraction operation happens in place.

Examples

Subtracting a single numeric variable:

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd - 10  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 39.67,  59.59,  71.73,  78.19])

Subtracting an array_like variable:

>>> spd - [1, 2, 3, 4]  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 38.67,  57.59,  68.73,  74.19])

Subtracting a SpectralPowerDistribution class variable:

>>> spd_alternate = SpectralPowerDistribution('Spd', data)
>>> spd - spd_alternate  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([-11., -12., -13., -14.])

__truediv__(x)

Implements support for spectral power distribution division.

Parameters:	x (numeric or array_like or SpectralPowerDistribution) – Variable to divide.
Returns:	Variable divided spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.__add__(), SpectralPowerDistribution.__sub__(), SpectralPowerDistribution.__mul__()

Notes

• Reimplements the object.__div__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd / 10  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 4.967,  6.959,  8.173,  8.819])

Dividing an array_like variable:

>>> spd / [1, 2, 3, 4]  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([ 4.967     ,  3.4795    ,  2.72433333,  2.20475   ])

Dividing a SpectralPowerDistribution class variable:

>>> spd_alternate = SpectralPowerDistribution('Spd', data)
>>> spd / spd_alternate  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values  
array([ 0.1       ,  0.05      ,  0.0333333...,  0.025     ])

align(shape, method=u'Constant', left=None, right=None)

Aligns the spectral power distribution to given spectral shape: Interpolates first then extrapolates to fit the given range.

Parameters:	shape (SpectralShape) – Spectral shape used for alignment. method (unicode, optional) – {‘Constant’, ‘Linear’}, Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range.
Returns:	Aligned spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.extrapolate(), SpectralPowerDistribution.interpolate()

Examples

>>> data = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 86.26,
...     560: 77.18}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.align(SpectralShape(505, 565, 1))  
<...SpectralPowerDistribution object at 0x...>
>>> # Doctests skip for Python 2.x compatibility.
>>> spd.wavelengths  
array([505, 506, 507, 508, 509, 510, 511, 512, 513, 514, 515, 516, 517,
       518, 519, 520, 521, 522, 523, 524, 525, 526, 527, 528, 529, 530,
       531, 532, 533, 534, 535, 536, 537, 538, 539, 540, 541, 542, 543,
       544, 545, 546, 547, 548, 549, 550, 551, 552, 553, 554, 555, 556,
       557, 558, 559, 560, 561, 562, 563, 564, 565])
>>> spd.values  
array([ 49.67     ...,  49.67     ...,  49.67     ...,  49.67     ...,
        49.67     ...,  49.67     ...,  51.8341162...,  53.9856467...,
        56.1229464...,  58.2366197...,  60.3121800...,  62.3327095...,
        64.2815187...,  66.1448055...,  67.9143153...,  69.59     ...,
        71.1759958...,  72.6627938...,  74.0465756...,  75.3329710...,
        76.5339542...,  77.6647421...,  78.7406907...,  79.7741932...,
        80.7715767...,  81.73     ...,  82.6407518...,  83.507872 ...,
        84.3326333...,  85.109696 ...,  85.8292968...,  86.47944  ...,
        87.0480863...,  87.525344 ...,  87.9056578...,  88.19     ...,
        88.3858347...,  88.4975634...,  88.5258906...,  88.4696570...,
        88.3266460...,  88.0943906...,  87.7709802...,  87.3558672...,
        86.8506741...,  86.26     ...,  85.5911699...,  84.8503430...,
        84.0434801...,  83.1771110...,  82.2583874...,  81.2951360...,
        80.2959122...,  79.2700525...,  78.2277286...,  77.18     ...,
        77.18     ...,  77.18     ...,  77.18     ...,  77.18     ...,  77.18      ])

clone()

Clones the spectral power distribution.

Most of the SpectralPowerDistribution class operations are conducted in-place. The SpectralPowerDistribution.clone() method provides a convenient way to copy the spectral power distribution to a new object.

Returns:	Cloned spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> print(spd)  
<...SpectralPowerDistribution object at 0x...>
>>> spd_clone = spd.clone()
>>> print(spd_clone)  
<...SpectralPowerDistribution object at 0x...>

data

Property for self.__data private attribute.

Returns:	self.__data.
Return type:	dict

extrapolate(shape, method=u'Constant', left=None, right=None)

Extrapolates the spectral power distribution following CIE 15:2004 recommendation.

Parameters:	shape (SpectralShape) – Spectral shape used for extrapolation. method (unicode, optional) – {‘Constant’, ‘Linear’}, Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range.
Returns:	Extrapolated spectral power distribution.
Return type:	SpectralPowerDistribution

See also

SpectralPowerDistribution.align()

References

[2]	CIE TC 1-48. (2004). Extrapolation. In CIE 015:2004 Colorimetry, 3rd Edition (p. 24). ISBN:978-3-901-90633-6

[3]	CIE TC 1-38. (2005). EXTRAPOLATION. In CIE 167:2005 Recommended Practice for Tabulating Spectral Data for Use in Colour Computations (pp. 19–20). ISBN:978-3-901-90641-1

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.extrapolate(SpectralShape(400, 700)).shape
SpectralShape(400, 700, 10)
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[400]  
array(49.67...)
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[700]  
array(88.1...)

get(wavelength, default=nan)

Returns the value for given wavelength \(\lambda\).

Parameters:	wavelength (numeric or ndarray) – Wavelength \(\lambda\) to retrieve the value. default (nan or numeric, optional) – Wavelength \(\lambda\) default value.
Returns:	Wavelength \(\lambda\) value.
Return type:	numeric or ndarray

See also

SpectralPowerDistribution.__getitem__()

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd.get(510)  
array(49.67...)
>>> spd.get(511)
array(nan)
>>> spd.get(np.array([510, 520]))
array([ 49.67,  69.59])

interpolate(shape=SpectralShape(None, None, None), method=None)

Interpolates the spectral power distribution following CIE 167:2005 recommendations: the method developed by Sprague (1880) should be used for interpolating functions having a uniformly spaced independent variable and a Cubic Spline method for non-uniformly spaced independent variable.

Parameters:	shape (SpectralShape, optional) – Spectral shape used for interpolation. method (unicode, optional) – {None, ‘Sprague’, ‘Cubic Spline’, ‘Linear’}, Enforce given interpolation method.
Returns:	Interpolated spectral power distribution.
Return type:	SpectralPowerDistribution
Raises:	RuntimeError – If Sprague (1880) interpolation method is forced with a non-uniformly spaced independent variable. ValueError – If the interpolation method is not defined.

See also

SpectralPowerDistribution.align()

Notes

• Interpolation will be conducted over boundaries range, if you need to extend the range of the spectral power distribution use the SpectralPowerDistribution.extrapolate() or SpectralPowerDistribution.align() methods.
• Sprague (1880) interpolator cannot be used for interpolating functions having a non-uniformly spaced independent variable.

Warning

• If scipy is not unavailable the Cubic Spline method will fallback to legacy Linear interpolation.
• Linear interpolator requires at least 2 wavelengths \(\lambda_n\) for interpolation.
• Cubic Spline interpolator requires at least 3 wavelengths \(\lambda_n\) for interpolation.
• Sprague (1880) interpolator requires at least 6 wavelengths \(\lambda_n\) for interpolation.

References

[4]	CIE TC 1-38. (2005). 9. INTERPOLATION. In CIE 167:2005 Recommended Practice for Tabulating Spectral Data for Use in Colour Computations (pp. 14–19). ISBN:978-3-901-90641-1

Examples

Uniform data is using Sprague (1880) interpolation by default:

>>> data = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 86.26,
...     560: 77.18}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.interpolate(SpectralShape(steps=1))  
<...SpectralPowerDistribution object at 0x...>
>>> spd[515]  
array(60.3121800...)

Non uniform data is using Cubic Spline interpolation by default:

>>> data = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 86.26,
...     560: 77.18}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd[511] = 31.41
>>> spd.interpolate(SpectralShape(steps=1))  
<...SpectralPowerDistribution object at 0x...>
>>> spd[515]  
array(21.4792222...)

Enforcing Linear interpolation:

>>> data = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 86.26,
...     560: 77.18}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.interpolate(SpectralShape(steps=1), method='Linear')    
<...SpectralPowerDistribution object at 0x...>
>>> spd[515]  
array(59.63...)

is_uniform()

Returns if the spectral power distribution has uniformly spaced data.

Returns:	Is uniform.
Return type:	bool

See also

SpectralPowerDistribution.shape()

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.is_uniform()
True

Breaking the steps by introducing a new wavelength \(\lambda\) value:

>>> spd[511] = 3.1415
>>> spd.is_uniform()
False

items

Property for self.items attribute. This is a convenient attribute used to iterate over the spectral power distribution.

Returns:	Spectral power distribution data generator.
Return type:	generator

name

Property for self.__name private attribute.

Returns:	self.__name.
Return type:	unicode

normalise(factor=1)

Normalises the spectral power distribution with given normalization factor.

Parameters:	factor (numeric, optional) – Normalization factor
Returns:	Normalised spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.normalise()  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values  
array([ 0.5632157...,  0.7890917...,  0.9267490...,  1.        ])

shape

Property for self.shape attribute.

Returns the shape of the spectral power distribution in the form of a SpectralShape class instance.

Returns:	Spectral power distribution shape.
Return type:	SpectralShape

See also

SpectralPowerDistribution.is_uniform

Notes

• A non uniform spectral power distribution may will have multiple different steps, in that case SpectralPowerDistribution.shape returns the minimum steps size.

Warning

SpectralPowerDistribution.shape is read only.

Examples

Uniform spectral power distribution:

>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> SpectralPowerDistribution('Spd', data).shape
SpectralShape(510, 540, 10)

Non uniform spectral power distribution:

>>> data = {512.3: 49.67, 524.5: 69.59, 532.4: 81.73, 545.7: 88.19}
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> SpectralPowerDistribution('Spd', data).shape  
SpectralShape(512.3, 545.7, 7...)

title

Property for self.__title private attribute.

Returns:	self.__title.
Return type:	unicode

values

Property for self.values attribute.

Returns:	Spectral power distribution wavelengths \(\lambda_n\) values.
Return type:	ndarray

Warning

SpectralPowerDistribution.values is read only.

wavelengths

Property for self.wavelengths attribute.

Returns:	Spectral power distribution wavelengths \(\lambda_n\).
Return type:	ndarray

Warning

SpectralPowerDistribution.wavelengths is read only.

zeros(shape=SpectralShape(None, None, None))

Zeros fills the spectral power distribution: Missing values will be replaced with zeros to fit the defined range.

Parameters:	shape (SpectralShape, optional) – Spectral shape used for zeros fill.
Returns:	Zeros filled spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> data = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 86.26,
...     560: 77.18}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> spd.zeros(SpectralShape(505, 565, 1))  
<...SpectralPowerDistribution object at 0x...>
>>> spd.values
array([  0.  ,   0.  ,   0.  ,   0.  ,   0.  ,  49.67,   0.  ,   0.  ,
         0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,  69.59,
         0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,
         0.  ,  81.73,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,
         0.  ,   0.  ,   0.  ,  88.19,   0.  ,   0.  ,   0.  ,   0.  ,
         0.  ,   0.  ,   0.  ,   0.  ,   0.  ,  86.26,   0.  ,   0.  ,
         0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,   0.  ,  77.18,
         0.  ,   0.  ,   0.  ,   0.  ,   0.  ])

class colour.TriSpectralPowerDistribution(name, data, mapping, title=None, labels=None)¶

Bases: object

Defines the base object for colour matching functions.

A compound of three SpectralPowerDistribution is used to store the underlying axis data.

Parameters:	name (unicode) – Tri-spectral power distribution name. data (dict) – Tri-spectral power distribution data. mapping (dict) – Tri-spectral power distribution attributes mapping. title (unicode, optional) – Tri-spectral power distribution title for figures. labels (dict, optional) – Tri-spectral power distribution axis labels mapping for figures.

name¶

mapping¶

data¶

title¶

labels¶

x¶

y¶

z¶

wavelengths¶

values¶

items¶

shape¶

__init__()¶

__getitem__()¶

__setitem__()¶

__iter__()¶

__contains__()¶

__len__()¶

__eq__()¶

__ne__()¶

__add__()¶

__sub__()¶

__mul__()¶

__div__()¶

__truediv__()¶

get()¶

is_uniform()¶

extrapolate()¶

interpolate()¶

align()¶

zeros()¶

normalise()¶

clone()¶

See also

colour.colorimetry.cmfs.LMS_ConeFundamentals, colour.colorimetry.cmfs.RGB_ColourMatchingFunctions, colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.wavelengths
array([510, 520, 530, 540])
>>> tri_spd.values
array([[ 49.67,  90.56,  12.43],
       [ 69.59,  87.34,  23.15],
       [ 81.73,  45.76,  67.98],
       [ 88.19,  23.45,  90.28]])
>>> tri_spd.shape
SpectralShape(510, 540, 10)

__add__(x)

Implements support for tri-spectral power distribution addition.

Parameters:	x (numeric or array_like or TriSpectralPowerDistribution) – Variable to add.
Returns:	Variable added tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.__sub__(), TriSpectralPowerDistribution.__mul__(), TriSpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__add__() method.

Warning

The addition operation happens in place.

Examples

Adding a single numeric variable:

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd + 10  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[  59.67,  100.56,   22.43],
       [  79.59,   97.34,   33.15],
       [  91.73,   55.76,   77.98],
       [  98.19,   33.45,  100.28]])

Adding an array_like variable:

>>> tri_spd + [(1, 2, 3)] * 4  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[  60.67,  102.56,   25.43],
       [  80.59,   99.34,   36.15],
       [  92.73,   57.76,   80.98],
       [  99.19,   35.45,  103.28]])

Adding a TriSpectralPowerDistribution class variable:

>>> data1 = {'x_bar': z_bar, 'y_bar': x_bar, 'z_bar': y_bar}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd + tri_spd1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[  73.1 ,  152.23,  115.99],
       [ 103.74,  168.93,  123.49],
       [ 160.71,  139.49,  126.74],
       [ 189.47,  123.64,  126.73]])

__contains__(wavelength)

Returns if the tri-spectral power distribution contains given wavelength \(\lambda\).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\).
Returns:	Is wavelength \(\lambda\) contained in the tri-spectral power distribution.
Return type:	bool

Warning

wavelength argument is tested to be contained in the tri-spectral power distribution within the tolerance defined by colour.constants.common.EPSILON attribute value.

Notes

• Reimplements the object.__contains__() method.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> 510 in tri_spd
True
>>> np.array([510, 520]) in tri_spd
True
>>> np.array([510, 520, 521]) in tri_spd
False

__div__(x)

Implements support for tri-spectral power distribution division.

Parameters:	x (numeric or array_like or TriSpectralPowerDistribution) – Variable to divide.
Returns:	Variable divided tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.__add__(), TriSpectralPowerDistribution.__sub__(), TriSpectralPowerDistribution.__mul__()

Notes

• Reimplements the object.__mul__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd / 10  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[ 4.967,  9.056,  1.243],
       [ 6.959,  8.734,  2.315],
       [ 8.173,  4.576,  6.798],
       [ 8.819,  2.345,  9.028]])

Dividing an array_like variable:

>>> tri_spd / [(1, 2, 3)] * 4  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 19.868     ,  18.112     ,   1.6573333...],
       [ 27.836     ,  17.468     ,   3.0866666...],
       [ 32.692     ,   9.152     ,   9.064    ...],
       [ 35.276     ,   4.69      ,  12.0373333...]])

Dividing a TriSpectralPowerDistribution class variable:

>>> data1 = {'x_bar': z_bar, 'y_bar': x_bar, 'z_bar': y_bar}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd / tri_spd1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 1.5983909...,  0.3646466...,  0.0183009...],
       [ 1.2024190...,  0.2510130...,  0.0353408...],
       [ 0.4809061...,  0.1119784...,  0.1980769...],
       [ 0.3907399...,  0.0531806...,  0.5133191...]])

__eq__(tri_spd)

Returns the tri-spectral power distribution equality with given other tri-spectral power distribution.

Parameters:	spd (TriSpectralPowerDistribution) – Tri-spectral power distribution to compare for equality.
Returns:	Tri-spectral power distribution equality.
Return type:	bool

Notes

• Reimplements the object.__eq__() method.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data1 = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> data2 = {'x_bar': y_bar, 'y_bar': x_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd2 = TriSpectralPowerDistribution('Tri Spd', data2, mapping)
>>> tri_spd3 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd1 == tri_spd2
False
>>> tri_spd1 == tri_spd3
True

__getitem__(wavelength)

Returns the values for given wavelength \(\lambda\).

Parameters:	wavelength (numeric, array_like or slice) – Wavelength \(\lambda\) to retrieve the values.
Returns:	Wavelength \(\lambda\) values.
Return type:	ndarray

See also

TriSpectralPowerDistribution.get()

Notes

• Reimplements the object.__getitem__() method.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping  = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd[510]
array([ 49.67,  90.56,  12.43])
>>> tri_spd[np.array([510, 520])]
array([[ 49.67,  90.56,  12.43],
       [ 69.59,  87.34,  23.15]])
>>> tri_spd[:]
array([[ 49.67,  90.56,  12.43],
       [ 69.59,  87.34,  23.15],
       [ 81.73,  45.76,  67.98],
       [ 88.19,  23.45,  90.28]])

__hash__()¶

Returns the spectral power distribution hash value. [1]_

Returns:	Object hash.
Return type:	int

Notes

• Reimplements the object.__hash__() method.

Warning

See SpectralPowerDistribution.__hash__() method warning section.

__iter__()

Returns a generator for the tri-spectral power distribution data.

Returns:	Tri-spectral power distribution data generator.
Return type:	generator

Notes

• Reimplements the object.__iter__() method.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> for wavelength, value in tri_spd:
...     print((wavelength, value))
(510, array([ 49.67,  90.56,  12.43]))
(520, array([ 69.59,  87.34,  23.15]))
(530, array([ 81.73,  45.76,  67.98]))
(540, array([ 88.19,  23.45,  90.28]))

__len__()

Returns the tri-spectral power distribution wavelengths \(\lambda_n\) count.

Returns:	Tri-Spectral power distribution wavelengths \(\lambda_n\) count.
Return type:	int

Notes

• Reimplements the object.__len__() method.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> len(tri_spd)
4

__mul__(x)

Implements support for tri-spectral power distribution multiplication.

Parameters:	x (numeric or array_like or TriSpectralPowerDistribution) – Variable to multiply.
Returns:	Variable multiplied tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.__add__(), TriSpectralPowerDistribution.__sub__(), TriSpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__mul__() method.

Warning

The multiplication operation happens in place.

Examples

Multiplying a single numeric variable:

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd * 10  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[ 496.7,  905.6,  124.3],
       [ 695.9,  873.4,  231.5],
       [ 817.3,  457.6,  679.8],
       [ 881.9,  234.5,  902.8]])

Multiplying an array_like variable:

>>> tri_spd * [(1, 2, 3)] * 4  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[  1986.8,   7244.8,   1491.6],
       [  2783.6,   6987.2,   2778. ],
       [  3269.2,   3660.8,   8157.6],
       [  3527.6,   1876. ,  10833.6]])

Multiplying a TriSpectralPowerDistribution class variable:

>>> data1 = {'x_bar': z_bar, 'y_bar': x_bar, 'z_bar': y_bar}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd * tri_spd1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[  24695.924,  359849.216,  135079.296],
       [  64440.34 ,  486239.248,  242630.52 ],
       [ 222240.216,  299197.184,  373291.776],
       [ 318471.728,  165444.44 ,  254047.92 ]])

__ne__(tri_spd)

Returns the tri-spectral power distribution inequality with given other tri-spectral power distribution.

Parameters:	spd (TriSpectralPowerDistribution) – Tri-spectral power distribution to compare for inequality.
Returns:	Tri-spectral power distribution inequality.
Return type:	bool

Notes

• Reimplements the object.__eq__() method.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data1 = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> data2 = {'x_bar': y_bar, 'y_bar': x_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd2 = TriSpectralPowerDistribution('Tri Spd', data2, mapping)
>>> tri_spd3 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd1 != tri_spd2
True
>>> tri_spd1 != tri_spd3
False

__pow__(x)¶

Implements support for tri-spectral power distribution exponentiation.

Parameters:	x (numeric or array_like or TriSpectralPowerDistribution) – Variable to exponentiate by.
Returns:	TriSpectral power distribution raised by power of x.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.__add__(), TriSpectralPowerDistribution.__sub__(), TriSpectralPowerDistribution.__mul__(), TriSpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__pow__() method.

Warning

The power operation happens in place.

Examples

Exponentiation by a single numeric variable:

>>> x_bar = {510: 1.67, 520: 1.59, 530: 1.73, 540: 1.19}
>>> y_bar = {510: 1.56, 520: 1.34, 530: 1.76, 540: 1.45}
>>> z_bar = {510: 1.43, 520: 1.15, 530: 1.98, 540: 1.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd ** 1.1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 1.7578755...,  1.6309365...,  1.4820731...],
       [ 1.6654700...,  1.3797972...,  1.1661854...],
       [ 1.8274719...,  1.8623612...,  2.1199797...],
       [ 1.2108815...,  1.5048901...,  1.3119913...]])

Exponentiation by an array_like variable:

>>> tri_spd ** ([(1, 2, 3)] * 4)  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 1.7578755...,  2.6599539...,  3.2554342...],
       [ 1.6654700...,  1.9038404...,  1.5859988...],
       [ 1.8274719...,  3.4683895...,  9.5278547...],
       [ 1.2108815...,  2.2646943...,  2.2583585...]])

Exponentiation by a TriSpectralPowerDistribution class variable:

>>> data1 = {'x_bar': z_bar, 'y_bar': x_bar, 'z_bar': y_bar}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd ** tri_spd1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[  2.2404384...,   5.1231818...,   6.3047797...],
       [  1.7979075...,   2.7836369...,   1.8552645...],
       [  3.2996236...,   8.5984706...,  52.8483490...],
       [  1.2775271...,   2.6452177...,   3.2583647...]])

__setitem__(wavelength, value)

Sets the wavelength \(\lambda\) with given value.

Parameters:	wavelength (numeric, array_like or slice) – Wavelength \(\lambda\) to set. value (array_like) – Value for wavelength \(\lambda\).

Warning

value parameter is resized to match wavelength parameter size.

Notes

• Reimplements the object.__setitem__() method.

Examples

>>> x_bar = {}
>>> y_bar = {}
>>> z_bar = {}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd[510] = np.array([49.67, 49.67, 49.67])
>>> tri_spd.values
array([[ 49.67,  49.67,  49.67]])
>>> tri_spd[np.array([520, 530])] = np.array([[69.59, 69.59, 69.59],
...                                           [81.73, 81.73, 81.73]])
>>> tri_spd.values
array([[ 49.67,  49.67,  49.67],
       [ 69.59,  69.59,  69.59],
       [ 81.73,  81.73,  81.73]])
>>> tri_spd[np.array([540, 550])] = 88.19
>>> tri_spd.values
array([[ 49.67,  49.67,  49.67],
       [ 69.59,  69.59,  69.59],
       [ 81.73,  81.73,  81.73],
       [ 88.19,  88.19,  88.19],
       [ 88.19,  88.19,  88.19]])
>>> tri_spd[:] = 49.67
>>> tri_spd.values
array([[ 49.67,  49.67,  49.67],
       [ 49.67,  49.67,  49.67],
       [ 49.67,  49.67,  49.67],
       [ 49.67,  49.67,  49.67],
       [ 49.67,  49.67,  49.67]])

__sub__(x)

Implements support for tri-spectral power distribution subtraction.

Parameters:	x (numeric or array_like or TriSpectralPowerDistribution) – Variable to subtract.
Returns:	Variable subtracted tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.__add__(), TriSpectralPowerDistribution.__mul__(), TriSpectralPowerDistribution.__div__()

Notes

• Reimplements the object.__sub__() method.

Warning

The subtraction operation happens in place.

Examples

Subtracting a single numeric variable:

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd - 10  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[ 39.67,  80.56,   2.43],
       [ 59.59,  77.34,  13.15],
       [ 71.73,  35.76,  57.98],
       [ 78.19,  13.45,  80.28]])

Subtracting an array_like variable:

>>> tri_spd - [(1, 2, 3)] * 4  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[ 38.67,  78.56,  -0.57],
       [ 58.59,  75.34,  10.15],
       [ 70.73,  33.76,  54.98],
       [ 77.19,  11.45,  77.28]])

Subtracting a TriSpectralPowerDistribution class variable:

>>> data1 = {'x_bar': z_bar, 'y_bar': x_bar, 'z_bar': y_bar}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd - tri_spd1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[ 26.24,  28.89, -91.13],
       [ 35.44,   5.75, -77.19],
       [  2.75, -47.97,   9.22],
       [-13.09, -76.74,  53.83]])

__truediv__(x)

Implements support for tri-spectral power distribution division.

Parameters:	x (numeric or array_like or TriSpectralPowerDistribution) – Variable to divide.
Returns:	Variable divided tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.__add__(), TriSpectralPowerDistribution.__sub__(), TriSpectralPowerDistribution.__mul__()

Notes

• Reimplements the object.__mul__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd / 10  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[ 4.967,  9.056,  1.243],
       [ 6.959,  8.734,  2.315],
       [ 8.173,  4.576,  6.798],
       [ 8.819,  2.345,  9.028]])

Dividing an array_like variable:

>>> tri_spd / [(1, 2, 3)] * 4  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 19.868     ,  18.112     ,   1.6573333...],
       [ 27.836     ,  17.468     ,   3.0866666...],
       [ 32.692     ,   9.152     ,   9.064    ...],
       [ 35.276     ,   4.69      ,  12.0373333...]])

Dividing a TriSpectralPowerDistribution class variable:

>>> data1 = {'x_bar': z_bar, 'y_bar': x_bar, 'z_bar': y_bar}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mapping)
>>> tri_spd / tri_spd1  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 1.5983909...,  0.3646466...,  0.0183009...],
       [ 1.2024190...,  0.2510130...,  0.0353408...],
       [ 0.4809061...,  0.1119784...,  0.1980769...],
       [ 0.3907399...,  0.0531806...,  0.5133191...]])

align(shape, method=u'Constant', left=None, right=None)

Aligns the tri-spectral power distribution to given shape: Interpolates first then extrapolates to fit the given range.

Parameters:	shape (SpectralShape) – Spectral shape used for alignment. method (unicode, optional) – {‘Constant’, ‘Linear’}, Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range.
Returns:	Aligned tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.extrapolate(), TriSpectralPowerDistribution.interpolate()

Examples

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.align(SpectralShape(505, 565, 1))  
<...TriSpectralPowerDistribution object at 0x...>
>>> # Doctests skip for Python 2.x compatibility.
>>> tri_spd.wavelengths  
array([505, 506, 507, 508, 509, 510, 511, 512, 513, 514, 515, 516, 517,
       518, 519, 520, 521, 522, 523, 524, 525, 526, 527, 528, 529, 530,
       531, 532, 533, 534, 535, 536, 537, 538, 539, 540, 541, 542, 543,
       544, 545, 546, 547, 548, 549, 550, 551, 552, 553, 554, 555, 556,
       557, 558, 559, 560, 561, 562, 563, 564, 565])
>>> tri_spd.values  
array([[ 49.67     ...,  90.56     ...,  12.43     ...],
       [ 49.67     ...,  90.56     ...,  12.43     ...],
       [ 49.67     ...,  90.56     ...,  12.43     ...],
       [ 49.67     ...,  90.56     ...,  12.43     ...],
       [ 49.67     ...,  90.56     ...,  12.43     ...],
       [ 49.67     ...,  90.56     ...,  12.43     ...],
       [ 51.8325938...,  91.2994928...,  12.5377184...],
       [ 53.9841952...,  91.9502387...,  12.7233193...],
       [ 56.1205452...,  92.5395463...,  12.9651679...],
       [ 58.2315395...,  93.0150037...,  13.3123777...],
       [ 60.3033208...,  93.2716331...,  13.8605136...],
       [ 62.3203719...,  93.1790455...,  14.7272944...],
       [ 64.2676077...,  92.6085951...,  16.0282961...],
       [ 66.1324679...,  91.4605335...,  17.8526544...],
       [ 67.9070097...,  89.6911649...,  20.2387677...],
       [ 69.59     ...,  87.34     ...,  23.15     ...],
       [ 71.1837378...,  84.4868033...,  26.5150469...],
       [ 72.6800056...,  81.0666018...,  30.3964852...],
       [ 74.0753483...,  77.0766254...,  34.7958422...],
       [ 75.3740343...,  72.6153870...,  39.6178858...],
       [ 76.5856008...,  67.8490714...,  44.7026805...],
       [ 77.7223995...,  62.9779261...,  49.8576432...],
       [ 78.7971418...,  58.2026503...,  54.8895997...],
       [ 79.8204447...,  53.6907852...,  59.6368406...],
       [ 80.798376 ...,  49.5431036...,  64.0011777...],
       [ 81.73     ...,  45.76     ...,  67.98     ...],
       [ 82.6093606...,  42.2678534...,  71.6460893...],
       [ 83.439232 ...,  39.10608  ...,  74.976976 ...],
       [ 84.2220071...,  36.3063728...,  77.9450589...],
       [ 84.956896 ...,  33.85464  ...,  80.552    ...],
       [ 85.6410156...,  31.7051171...,  82.8203515...],
       [ 86.27048  ...,  29.79448  ...,  84.785184 ...],
       [ 86.8414901...,  28.0559565...,  86.4857131...],
       [ 87.351424 ...,  26.43344  ...,  87.956928 ...],
       [ 87.7999266...,  24.8956009...,  89.2212178...],
       [ 88.19     ...,  23.45     ...,  90.28     ...],
       [ 88.5265036...,  22.1424091...,  91.1039133...],
       [ 88.8090803...,  20.9945234...,  91.6538035...],
       [ 89.0393279...,  20.0021787...,  91.9333499...],
       [ 89.2222817...,  19.1473370...,  91.9858818...],
       [ 89.3652954...,  18.4028179...,  91.8811002...],
       [ 89.4769231...,  17.7370306...,  91.7018000...],
       [ 89.5657996...,  17.1187058...,  91.5305910...],
       [ 89.6395227...,  16.5216272...,  91.4366204...],
       [ 89.7035339...,  15.9293635...,  91.4622944...],
       [ 89.76     ...,  15.34     ...,  91.61     ...],
       [ 89.8094041...,  14.7659177...,  91.8528616...],
       [ 89.8578890...,  14.2129190...,  92.2091737...],
       [ 89.9096307...,  13.6795969...,  92.6929664...],
       [ 89.9652970...,  13.1613510...,  93.2988377...],
       [ 90.0232498...,  12.6519811...,  94.0078786...],
       [ 90.0807467...,  12.1452800...,  94.7935995...],
       [ 90.1351435...,  11.6366269...,  95.6278555...],
       [ 90.1850956...,  11.1245805...,  96.4867724...],
       [ 90.2317606...,  10.6124724...,  97.3566724...],
       [ 90.28     ...,  10.11     ...,  98.24     ...],
       [ 90.28     ...,  10.11     ...,  98.24     ...],
       [ 90.28     ...,  10.11     ...,  98.24     ...],
       [ 90.28     ...,  10.11     ...,  98.24     ...],
       [ 90.28     ...,  10.11     ...,  98.24     ...],
       [ 90.28     ...,  10.11     ...,  98.24     ...]])

clone()

Clones the tri-spectral power distribution.

Most of the TriSpectralPowerDistribution class operations are conducted in-place. The TriSpectralPowerDistribution.clone() method provides a convenient way to copy the tri-spectral power distribution to a new object.

Returns:	Cloned tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

Examples

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> print(tri_spd)  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd_clone = tri_spd.clone()
>>> print(tri_spd_clone)  
<...TriSpectralPowerDistribution object at 0x...>

data

Property for self.__data private attribute.

Returns:	self.__data.
Return type:	dict

extrapolate(shape, method=u'Constant', left=None, right=None)

Extrapolates the tri-spectral power distribution following CIE 15:2004 recommendation. [2]_ [3]_

Parameters:	shape (SpectralShape) – Spectral shape used for extrapolation. method (unicode, optional) – {‘Constant’, ‘Linear’}, Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range.
Returns:	Extrapolated tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.align()

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.extrapolate(SpectralShape(400, 700)).shape
SpectralShape(400, 700, 10)
>>> tri_spd[400]
array([ 49.67,  90.56,  12.43])
>>> tri_spd[700]
array([ 88.19,  23.45,  90.28])

get(wavelength, default=nan)

Returns the values for given wavelength \(\lambda\).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) to retrieve the values. default (nan, numeric or array_like, optional) – Wavelength \(\lambda\) default values.
Returns:	Wavelength \(\lambda\) values.
Return type:	numeric or array_like

See also

TriSpectralPowerDistribution.__getitem__()

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.get(510)
array([ 49.67,  90.56,  12.43])
>>> tri_spd.get(np.array([510, 520]))
array([[ 49.67,  90.56,  12.43],
       [ 69.59,  87.34,  23.15]])
>>> tri_spd.get(511)
array([ nan,  nan,  nan])
>>> tri_spd.get(np.array([510, 520]))
array([[ 49.67,  90.56,  12.43],
       [ 69.59,  87.34,  23.15]])

interpolate(shape=SpectralShape(None, None, None), method=None)

Interpolates the tri-spectral power distribution following CIE 167:2005 recommendations: the method developed by Sprague (1880) should be used for interpolating functions having a uniformly spaced independent variable and a Cubic Spline method for non-uniformly spaced independent variable. [4]_

Parameters:	shape (SpectralShape, optional) – Spectral shape used for interpolation. method (unicode, optional) – {None, ‘Sprague’, ‘Cubic Spline’, ‘Linear’}, Enforce given interpolation method.
Returns:	Interpolated tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

See also

TriSpectralPowerDistribution.align()

Notes

• See SpectralPowerDistribution.interpolate() method notes section.

Warning

See SpectralPowerDistribution.interpolate() method warning section.

Examples

Uniform data is using Sprague (1880) interpolation by default:

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.interpolate(SpectralShape(steps=1))  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd[515]
array([ 60.30332087,  93.27163315,  13.86051361])

Non uniform data is using Cubic Spline interpolation by default:

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd[511] = np.array([31.41, 95.27, 15.06])
>>> tri_spd.interpolate(SpectralShape(steps=1))  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd[515]
array([  21.47104053,  100.64300155,   18.8165196 ])

Enforcing Linear interpolation:

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.interpolate(SpectralShape(steps=1), method='Linear')    
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd[515]
array([ 59.63,  88.95,  17.79])

is_uniform()

Returns if the tri-spectral power distribution has uniformly spaced data.

Returns:	Is uniform.
Return type:	bool

See also

TriSpectralPowerDistribution.shape()

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.is_uniform()
True

Breaking the steps by introducing new wavelength \(\lambda\) values:

>>> tri_spd[511] = np.array([49.6700, 49.6700, 49.6700])
>>> tri_spd.is_uniform()
False

items

Property for self.items attribute. This is a convenient attribute used to iterate over the tri-spectral power distribution.

Returns:	Tri-spectral power distribution data generator.
Return type:	generator

labels

Property for self.__labels private attribute.

Returns:	self.__labels.
Return type:	dict

mapping

Property for self.__mapping private attribute.

Returns:	self.__mapping.
Return type:	dict

name

Property for self.__name private attribute.

Returns:	self.__name.
Return type:	unicode

normalise(factor=1)

Normalises the tri-spectral power distribution with given normalization factor.

Parameters:	factor (numeric, optional) – Normalization factor
Returns:	Normalised tri- spectral power distribution.
Return type:	TriSpectralPowerDistribution

Notes

• The implementation uses the maximum value for all axis.

Examples

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.normalise()  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values  
array([[ 0.5055985...,  0.9218241...,  0.1265268...],
       [ 0.7083672...,  0.8890472...,  0.2356473...],
       [ 0.8319421...,  0.4657980...,  0.6919788...],
       [ 0.8976995...,  0.2387011...,  0.9189739...],
       [ 0.9136807...,  0.1561482...,  0.9325122...],
       [ 0.9189739...,  0.1029112...,  1.       ...]])

shape

Property for self.shape attribute.

Returns the shape of the tri-spectral power distribution in the form of a SpectralShape class instance.

Returns:	Tri-spectral power distribution shape.
Return type:	SpectralShape

See also

SpectralPowerDistribution.is_uniform, TriSpectralPowerDistribution.is_uniform

Warning

TriSpectralPowerDistribution.shape is read only.

Examples

>>> x_bar = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> y_bar = {510: 90.56, 520: 87.34, 530: 45.76, 540: 23.45}
>>> z_bar = {510: 12.43, 520: 23.15, 530: 67.98, 540: 90.28}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.shape
SpectralShape(510, 540, 10)

title

Property for self.__title private attribute.

Returns:	self.__title.
Return type:	unicode

values

Property for self.values attribute.

Returns:	Tri-spectral power distribution wavelengths \(\lambda_n\) values.
Return type:	ndarray

Warning

TriSpectralPowerDistribution.values is read only.

wavelengths

Property for self.wavelengths attribute.

Returns:	Tri-spectral power distribution wavelengths \(\lambda_n\).
Return type:	ndarray

Warning

TriSpectralPowerDistribution.wavelengths is read only.

x

Property for self.x attribute.

Returns:	Spectral power distribution for x axis.
Return type:	SpectralPowerDistribution

Warning

TriSpectralPowerDistribution.x is read only.

y

Property for self.y attribute.

Returns:	Spectral power distribution for y axis.
Return type:	SpectralPowerDistribution

Warning

TriSpectralPowerDistribution.y is read only.

z

Property for self.z attribute.

Returns:	Spectral power distribution for z axis.
Return type:	SpectralPowerDistribution

Warning

TriSpectralPowerDistribution.z is read only.

zeros(shape=SpectralShape(None, None, None))

Zeros fills the tri-spectral power distribution: Missing values will be replaced with zeros to fit the defined range.

Parameters:	shape (SpectralShape, optional) – Spectral shape used for zeros fill.
Returns:	Zeros filled tri-spectral power distribution.
Return type:	TriSpectralPowerDistribution

Examples

>>> x_bar = {
...     510: 49.67,
...     520: 69.59,
...     530: 81.73,
...     540: 88.19,
...     550: 89.76,
...     560: 90.28}
>>> y_bar = {
...     510: 90.56,
...     520: 87.34,
...     530: 45.76,
...     540: 23.45,
...     550: 15.34,
...     560: 10.11}
>>> z_bar = {
...     510: 12.43,
...     520: 23.15,
...     530: 67.98,
...     540: 90.28,
...     550: 91.61,
...     560: 98.24}
>>> data = {'x_bar': x_bar, 'y_bar': y_bar, 'z_bar': z_bar}
>>> mapping = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mapping)
>>> tri_spd.zeros(SpectralShape(505, 565, 1))  
<...TriSpectralPowerDistribution object at 0x...>
>>> tri_spd.values
array([[  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [ 49.67,  90.56,  12.43],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [ 69.59,  87.34,  23.15],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [ 81.73,  45.76,  67.98],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [ 88.19,  23.45,  90.28],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [ 89.76,  15.34,  91.61],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [ 90.28,  10.11,  98.24],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ],
       [  0.  ,   0.  ,   0.  ]])

colour.constant_spd(k, shape=SpectralShape(360, 830, 1))¶

Returns a spectral power distribution of given spectral shape filled with constant \(k\) values.

Parameters:	k (numeric) – Constant \(k\) to fill the spectral power distribution with. shape (SpectralShape, optional) – Spectral shape used to create the spectral power distribution.
Returns:	Constant \(k\) to filled spectral power distribution.
Return type:	SpectralPowerDistribution

Notes

• By default, the spectral power distribution will use the shape given by DEFAULT_SPECTRAL_SHAPE attribute.

Examples

>>> spd = constant_spd(100)
>>> spd.shape
SpectralShape(360.0, 830.0, 1.0)
>>> spd[400]
array(100.0)

colour.zeros_spd(shape=SpectralShape(360, 830, 1))¶

Returns a spectral power distribution of given spectral shape filled with zeros.

Parameters:	shape (SpectralShape, optional) – Spectral shape used to create the spectral power distribution.
Returns:	Zeros filled spectral power distribution.
Return type:	SpectralPowerDistribution

See also

constant_spd()

Notes

• By default, the spectral power distribution will use the shape given by DEFAULT_SPECTRAL_SHAPE attribute.

Examples

>>> spd = zeros_spd()
>>> spd.shape
SpectralShape(360.0, 830.0, 1.0)
>>> spd[400]
array(0.0)

colour.ones_spd(shape=SpectralShape(360, 830, 1))¶

Returns a spectral power distribution of given spectral shape filled with ones.

Parameters:	shape (SpectralShape, optional) – Spectral shape used to create the spectral power distribution.
Returns:	Ones filled spectral power distribution.
Return type:	SpectralPowerDistribution

See also

constant_spd()

Notes

• By default, the spectral power distribution will use the shape given by DEFAULT_SPECTRAL_SHAPE attribute.

Examples

>>> spd = ones_spd()
>>> spd.shape
SpectralShape(360.0, 830.0, 1.0)
>>> spd[400]
array(1.0)

colour.blackbody_spd(temperature, shape=SpectralShape(360, 830, 1), c1=3.741771e-16, c2=0.014388, n=1)¶

Returns the spectral power distribution of the planckian radiator for given temperature \(T[K]\).

Parameters:	temperature (numeric) – Temperature \(T[K]\) in kelvin degrees. shape (SpectralShape, optional) – Spectral shape used to create the spectral power distribution of the planckian radiator. c1 (numeric, optional) – The official value of \(c1\) is provided by the Committee on Data for Science and Technology (CODATA), and is \(c1=3,741771x10.16\ W/m_2\) (Mohr and Taylor, 2000). c2 (numeric, optional) – Since \(T\) is measured on the International Temperature Scale, the value of \(c2\) used in colorimetry should follow that adopted in the current International Temperature Scale (ITS-90) (Preston-Thomas, 1990; Mielenz et aI., 1991), namely \(c2=1,4388x10.2\ m/K\). n (numeric, optional) – Medium index of refraction. For dry air at 15°C and 101 325 Pa, containing 0,03 percent by volume of carbon dioxide, it is approximately 1,00028 throughout the visible region although CIE 15:2004 recommends using \(n=1\).
Returns:	Blackbody spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> from colour import STANDARD_OBSERVERS_CMFS
>>> cmfs = STANDARD_OBSERVERS_CMFS.get('CIE 1931 2 Degree Standard Observer')  
>>> blackbody_spd(5000, cmfs.shape)  
<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x...>

colour.blackbody_spectral_radiance(wavelength, temperature, c1=3.741771e-16, c2=0.014388, n=1)¶

Returns the spectral radiance of a blackbody at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\).

Notes

The following form implementation is expressed in term of wavelength. The SI unit of radiance is watts per steradian per square metre.

References

[1]	CIE TC 1-48. (2004). APPENDIX E. INFORMATION ON THE USE OF PLANCK’S EQUATION FOR STANDARD AIR. In CIE 015:2004 Colorimetry, 3rd Edition (pp. 77–82). ISBN:978-3-901-90633-6

Parameters:	wavelength (numeric or array_like) – Wavelength in meters. temperature (numeric or array_like) – Temperature \(T[K]\) in kelvin degrees. c1 (numeric or array_like, optional) – The official value of \(c1\) is provided by the Committee on Data for Science and Technology (CODATA), and is \(c1=3,741771x10.16\ W/m_2\) (Mohr and Taylor, 2000). c2 (numeric or array_like, optional) – Since \(T\) is measured on the International Temperature Scale, the value of \(c2\) used in colorimetry should follow that adopted in the current International Temperature Scale (ITS-90) (Preston-Thomas, 1990; Mielenz et aI., 1991), namely \(c2=1,4388x10.2\ m/K\). n (numeric or array_like, optional) – Medium index of refraction. For dry air at 15°C and 101 325 Pa, containing 0,03 percent by volume of carbon dioxide, it is approximately 1,00028 throughout the visible region although CIE 15:2004 recommends using \(n=1\).
Returns:	Radiance in watts per steradian per square metre.
Return type:	numeric or ndarray

Examples

>>> # Doctests ellipsis for Python 2.x compatibility.
>>> planck_law(500 * 1e-9, 5500)  
20472701909806.5...

colour.planck_law(wavelength, temperature, c1=3.741771e-16, c2=0.014388, n=1)¶

Returns the spectral radiance of a blackbody at thermodynamic temperature \(T[K]\) in a medium having index of refraction \(n\).

Notes

The following form implementation is expressed in term of wavelength. The SI unit of radiance is watts per steradian per square metre.

References

[1]	CIE TC 1-48. (2004). APPENDIX E. INFORMATION ON THE USE OF PLANCK’S EQUATION FOR STANDARD AIR. In CIE 015:2004 Colorimetry, 3rd Edition (pp. 77–82). ISBN:978-3-901-90633-6

Parameters:	wavelength (numeric or array_like) – Wavelength in meters. temperature (numeric or array_like) – Temperature \(T[K]\) in kelvin degrees. c1 (numeric or array_like, optional) – The official value of \(c1\) is provided by the Committee on Data for Science and Technology (CODATA), and is \(c1=3,741771x10.16\ W/m_2\) (Mohr and Taylor, 2000). c2 (numeric or array_like, optional) – Since \(T\) is measured on the International Temperature Scale, the value of \(c2\) used in colorimetry should follow that adopted in the current International Temperature Scale (ITS-90) (Preston-Thomas, 1990; Mielenz et aI., 1991), namely \(c2=1,4388x10.2\ m/K\). n (numeric or array_like, optional) – Medium index of refraction. For dry air at 15°C and 101 325 Pa, containing 0,03 percent by volume of carbon dioxide, it is approximately 1,00028 throughout the visible region although CIE 15:2004 recommends using \(n=1\).
Returns:	Radiance in watts per steradian per square metre.
Return type:	numeric or ndarray

Examples

>>> # Doctests ellipsis for Python 2.x compatibility.
>>> planck_law(500 * 1e-9, 5500)  
20472701909806.5...

class colour.LMS_ConeFundamentals(name, data, title=None)¶

Bases: colour.colorimetry.spectrum.TriSpectralPowerDistribution

Implements support for the Stockman and Sharpe LMS cone fundamentals colour matching functions.

Parameters:	name (unicode) – LMS colour matching functions name. data (dict) – LMS colour matching functions. title (unicode, optional) – LMS colour matching functions title for figures.

l_bar¶

m_bar¶

s_bar¶

l_bar

Property for self.x attribute.

Returns:	self.x
Return type:	SpectralPowerDistribution

Warning

LMS_ConeFundamentals.l_bar is read only.

m_bar

Property for self.y attribute.

Returns:	self.y
Return type:	SpectralPowerDistribution

Warning

LMS_ConeFundamentals.m_bar is read only.

s_bar

Property for self.z attribute.

Returns:	self.z
Return type:	SpectralPowerDistribution

Warning

LMS_ConeFundamentals.s_bar is read only.

class colour.RGB_ColourMatchingFunctions(name, data, title=None)¶

Bases: colour.colorimetry.spectrum.TriSpectralPowerDistribution

Implements support for the CIE RGB colour matching functions.

Parameters:	name (unicode) – CIE RGB colour matching functions name. data (dict) – CIE RGB colour matching functions. title (unicode, optional) – CIE RGB colour matching functions title for figures.

r_bar¶

g_bar¶

b_bar¶

b_bar

Property for self.z attribute.

Returns:	self.z
Return type:	SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.b_bar is read only.

g_bar

Property for self.y attribute.

Returns:	self.y
Return type:	SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.g_bar is read only.

r_bar

Property for self.x attribute.

Returns:	self.x
Return type:	SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.r_bar is read only.

class colour.XYZ_ColourMatchingFunctions(name, data, title=None)¶

Bases: colour.colorimetry.spectrum.TriSpectralPowerDistribution

Implements support for the CIE Standard Observers XYZ colour matching functions.

Parameters:	name (unicode) – CIE Standard Observer XYZ colour matching functions name. data (dict) – CIE Standard Observer XYZ colour matching functions. title (unicode, optional) – CIE Standard Observer XYZ colour matching functions title for figures.

x_bar¶

y_bar¶

z_bar¶

x_bar

Property for self.x attribute.

Returns:	self.x
Return type:	SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.x_bar is read only.

y_bar

Property for self.y attribute.

Returns:	self.y
Return type:	SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.y_bar is read only.

z_bar

Property for self.z attribute.

Returns:	self.z
Return type:	SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.z_bar is read only.

colour.bandpass_correction(spd, method=u'Stearns 1988')¶

Implements spectral bandpass dependence correction on given spectral power distribution using given method.

Parameters:	spd (SpectralPowerDistribution) – Spectral power distribution. method (unicode, optional) – (‘Stearns 1988’,) Correction method.
Returns:	Spectral bandpass dependence corrected spectral power distribution.
Return type:	SpectralPowerDistribution

colour.bandpass_correction_Stearns1988(spd)¶

Implements spectral bandpass dependence correction on given spectral power distribution using Stearns and Stearns (1988)⁠⁠ method.

References

[1]	Westland, S., Ripamonti, C., & Cheung, V. (2012). Correction for Spectral Bandpass. In Computational Colour Science Using MATLAB (2nd ed., p. 38). ISBN:978-0-470-66569-5

[2]	Stearns, E. I., & Stearns, R. E. (1988). An example of a method for correcting radiance data for Bandpass error. Color Research & Application, 13(4), 257–259. doi:10.1002/col.5080130410

Parameters:	spd (SpectralPowerDistribution) – Spectral power distribution.
Returns:	Spectral bandpass dependence corrected spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> from colour import SpectralPowerDistribution
>>> data = {510: 49.67, 520: 69.59, 530: 81.73, 540: 88.19}
>>> spd = SpectralPowerDistribution('Spd', data)
>>> corrected_spd = bandpass_correction_Stearns1988(spd)
>>> corrected_spd.values  
array([ 48.01664   ,  70.3729688...,  82.0919506...,  88.72618   ])

colour.D_illuminant_relative_spd(xy)¶

Returns the relative spectral power distribution of given CIE Standard Illuminant D Series using given xy chromaticity coordinates.

References

[1]	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

[2]	Lindbloom, B. (2007). Spectral Power Distribution of a CIE D-Illuminant. Retrieved April 05, 2014, from http://www.brucelindbloom.com/Eqn_DIlluminant.html

Parameters:	xy (array_like) – xy chromaticity coordinates.
Returns:	CIE Standard Illuminant D Series relative spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> import numpy as np
>>> xy = np.array([0.34567, 0.35850])
>>> D_illuminant_relative_spd(xy)  
<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x...>

colour.mesopic_luminous_efficiency_function(Lp, source=u'Blue Heavy', method=u'MOVE', photopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc37ae3a90>, scotopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc37ae3c50>)¶

Returns the mesopic luminous efficiency function \(V_m(\lambda)\) for given photopic luminance \(L_p\).

Parameters:	Lp (numeric) – Photopic luminance \(L_p\). source (unicode, optional) – {‘Blue Heavy’, ‘Red Heavy’}, Light source colour temperature. method (unicode, optional) – {‘MOVE’, ‘LRC’}, Method to calculate the weighting factor. photopic_lef (SpectralPowerDistribution, optional) – \(V(\lambda)\) photopic luminous efficiency function. scotopic_lef (SpectralPowerDistribution, optional) – \(V^\prime(\lambda)\) scotopic luminous efficiency function.
Returns:	Mesopic luminous efficiency function \(V_m(\lambda)\).
Return type:	SpectralPowerDistribution

Examples

>>> mesopic_luminous_efficiency_function(0.2)  
<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x...>

colour.mesopic_weighting_function(wavelength, Lp, source=u'Blue Heavy', method=u'MOVE', photopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc37ae3a90>, scotopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc37ae3c50>)¶

Calculates the mesopic weighting function factor at given wavelength \(\lambda\) using the photopic luminance \(L_p\).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) to calculate the mesopic weighting function factor. Lp (numeric) – Photopic luminance \(L_p\). source (unicode, optional) – {‘Blue Heavy’, ‘Red Heavy’}, Light source colour temperature. method (unicode, optional) – {‘MOVE’, ‘LRC’}, Method to calculate the weighting factor. photopic_lef (SpectralPowerDistribution, optional) – \(V(\lambda)\) photopic luminous efficiency function. scotopic_lef (SpectralPowerDistribution, optional) – \(V^\prime(\lambda)\) scotopic luminous efficiency function.
Returns:	Mesopic weighting function factor.
Return type:	numeric or ndarray

Examples

>>> mesopic_weighting_function(500, 0.2)  
0.7052200...

colour.lightness(Y, method=u'CIE 1976', **kwargs)¶

Returns the Lightness \(L^*\) using given method.

Parameters:	Y (numeric or array_like) – luminance \(Y\). method (unicode, optional) – {‘CIE 1976’, ‘Glasser 1958’, ‘Wyszecki 1963’}, Computation method. **kwargs (**) – Keywords arguments.
Returns:	Lightness \(L^*\).
Return type:	numeric or array_like

Notes

• Input luminance \(Y\) and optional \(Y_n\) are in domain [0, 100].
• Output Lightness \(L^*\) is in domain [0, 100].

Examples

>>> lightness(10.08)  
array(37.9856290...)
>>> lightness(10.08, Y_n=100)  
array(37.9856290...)
>>> lightness(10.08, Y_n=95)  
array(38.9165987...)
>>> lightness(10.08, method='Glasser 1958')  
36.2505626...
>>> lightness(10.08, method='Wyszecki 1963')  
37.0041149...

colour.lightness_Glasser1958(Y, **kwargs)¶

Returns the Lightness \(L\) of given luminance \(Y\) using Glasser, Mckinney, Reilly and Schnelle (1958) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other Lightness computation objects.
Returns:	Lightness \(L\).
Return type:	numeric or array_like

Notes

• Input luminance \(Y\) is in domain [0, 100].
• Output Lightness \(L\) is in domain [0, 100].

References

[2]	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

Examples

>>> lightness_Glasser1958(10.08)  
36.2505626...

colour.lightness_Wyszecki1963(Y, **kwargs)¶

Returns the Lightness \(W\) of given luminance \(Y\) using Wyszecki (1963) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other Lightness computation objects.
Returns:	Lightness \(W\).
Return type:	numeric or array_like

Notes

• Input luminance \(Y\) is in domain [0, 100].
• Output Lightness \(W\) is in domain [0, 100].

References

[3]	Wyszecki, G. (1963). Proposal for a New Color-Difference Formula. J. Opt. Soc. Am., 53(11), 1318–1319. doi:10.1364/JOSA.53.001318

Examples

>>> lightness_Wyszecki1963(10.08)  
37.0041149...

colour.lightness_1976(Y, Y_n=100)¶

Returns the Lightness \(L^*\) of given luminance \(Y\) using given reference white luminance \(Y_n\) as per CIE Lab implementation.

Parameters:	Y (numeric or array_like) – luminance \(Y\). Y_n (numeric or array_like, optional) – White reference luminance \(Y_n\).
Returns:	Lightness \(L^*\).
Return type:	numeric or array_like

Notes

• Input luminance \(Y\) and \(Y_n\) are in domain [0, 100].
• Output Lightness \(L^*\) is in domain [0, 100].

References

[4]	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]	Lindbloom, B. (2003). A Continuity Study of the CIE L* Function. Retrieved February 24, 2014, from http://brucelindbloom.com/LContinuity.html

Examples

>>> lightness_1976(10.08)  
array(37.9856290...)

colour.luminance(LV, method=u'CIE 1976', **kwargs)¶

Returns the luminance \(Y\) of given Lightness \(L^*\) or given Munsell value \(V\).

Parameters:	LV (numeric or array_like) – Lightness \(L^*\) or Munsell value \(V\). method (unicode, optional) – {‘CIE 1976’, ‘Newhall 1943’, ‘ASTM D1535-08’} Computation method. **kwargs (**) – Keywords arguments.
Returns:	luminance \(Y\).
Return type:	numeric or array_like

Notes

• Input LV is in domain [0, 100] or [0, 10] and optional luminance \(Y_n\) is in domain [0, 100].
• Output luminance \(Y\) is in domain [0, 100].

Examples

>>> luminance(37.9856290977)  
array(10.0800000...)
>>> luminance(37.9856290977, Y_n=100)  
array(10.0800000...)
>>> luminance(37.9856290977, Y_n=95)  
array(9.5760000...)
>>> luminance(3.74629715382, method='Newhall 1943')  
10.4089874...
>>> luminance(3.74629715382, method='ASTM D1535-08')  
10.1488096...

colour.luminance_Newhall1943(V, **kwargs)¶

Returns the luminance \(R_Y\) of given Munsell value \(V\) using Sidney M. Newhall, Dorothy Nickerson, and Deane B. Judd (1943) method.

Parameters:	V (numeric or array_like) – Munsell value \(V\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other luminance computation objects.
Returns:	luminance \(R_Y\).
Return type:	numeric or array_like

Notes

• Input Munsell value \(V\) is in domain [0, 10].
• Output luminance \(R_Y\) is in domain [0, 100].

References

[1]	Newhall, S. M., Nickerson, D., & Judd, D. B. (1943). Final report of the OSA subcommittee on the spacing of the munsell colors. JOSA, 33(7), 385. doi:10.1364/JOSA.33.000385

Examples

>>> luminance_Newhall1943(3.74629715382)  
10.4089874...

colour.luminance_ASTMD153508(V, **kwargs)¶

Returns the luminance \(Y\) of given Munsell value \(V\) using ASTM D1535-08e1 (2008) method.

Parameters:	V (numeric or array_like) – Munsell value \(V\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other luminance computation objects.
Returns:	luminance \(Y\).
Return type:	numeric or array_like

Notes

• Input Munsell value \(V\) is in domain [0, 10].
• Output luminance \(Y\) is in domain [0, 100].

References

[4]	ASTM International. (n.d.). ASTM D1535-08e1 Standard Practice for Specifying Color by the Munsell System. doi:10.1520/D1535-08E01

Examples

>>> luminance_ASTMD153508(3.74629715382)  
10.1488096...

colour.luminance_1976(Lstar, Y_n=100)¶

Returns the luminance \(Y\) of given Lightness \(L^*\) with given reference white luminance \(Y_n\).

Parameters:	L (numeric or array_like) – Lightness \(L^*\) Yn (numeric or array_like) – White reference luminance \(Y_n\).
Returns:	luminance \(Y\).
Return type:	numeric or array_like

Notes

• Input Lightness \(L^*\) and reference white luminance \(Y_n\) are in domain [0, 100].
• Output luminance \(Y\) is in domain [0, 100].

References

[2]	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

[3]	Lindbloom, B. (2003). A Continuity Study of the CIE L* Function. Retrieved February 24, 2014, from http://brucelindbloom.com/LContinuity.html

Examples

>>> luminance_1976(37.9856290977)  
array(10.0800000...)
>>> luminance_1976(37.9856290977, 95)  
array(9.5760000...)

colour.luminous_flux(spd, lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc37ae3a90>, K_m=683)¶

Returns the luminous flux for given spectral power distribution using the given luminous efficiency function.

Parameters:	spd (SpectralPowerDistribution) – test spectral power distribution lef (SpectralPowerDistribution, optional) – \(V(\lambda)\) luminous efficiency function. K_m (numeric, optional) – \(lm\cdot W^{-1}\) maximum photopic luminous efficiency
Returns:	Luminous flux
Return type:	numeric

Examples

>>> from colour import LIGHT_SOURCES_RELATIVE_SPDS
>>> spd = LIGHT_SOURCES_RELATIVE_SPDS.get('Neodimium Incandescent')
>>> luminous_flux(spd)  
23807.6555273...

colour.luminous_efficacy(spd, lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc37ae3a90>)¶

Returns the luminous efficacy for given spectral power distribution using the given luminous efficiency function.

Parameters:	spd (SpectralPowerDistribution) – test spectral power distribution lef (SpectralPowerDistribution, optional) – \(V(\lambda)\) luminous efficiency function.
Returns:	Luminous efficacy
Return type:	numeric

Examples

>>> from colour import LIGHT_SOURCES_RELATIVE_SPDS
>>> spd = LIGHT_SOURCES_RELATIVE_SPDS.get('Neodimium Incandescent')
>>> luminous_efficacy(spd)  
0.1994393...

colour.RGB_10_degree_cmfs_to_LMS_10_degree_cmfs(wavelength)¶

Converts Stiles & Burch 1959 10 Degree RGB CMFs colour matching functions into the Stockman & Sharpe 10 Degree Cone Fundamentals spectral sensitivity functions.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in nm.
Returns:	Stockman & Sharpe 10 Degree Cone Fundamentals spectral tristimulus values.
Return type:	ndarray

Notes

• Data for the Stockman & Sharpe 10 Degree Cone Fundamentals already exists, this definition is intended for educational purpose.

References

[3]	CIE TC 1-36. (2006). CIE 170-1:2006 Fundamental Chromaticity Diagram with Physiological Axes - Part 1 (pp. 1–56). ISBN:978-3-901-90646-6

Examples

>>> RGB_10_degree_cmfs_to_LMS_10_degree_cmfs(700)  
array([ 0.0052860...,  0.0003252...,  0.        ])

colour.RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs(wavelength)¶

Converts Wright & Guild 1931 2 Degree RGB CMFs colour matching functions into the CIE 1931 2 Degree Standard Observer colour matching functions.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in nm.
Returns:	CIE 1931 2 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray

See also

colour.colorimetry.dataset.cmfs.RGB_CMFS

Notes

• Data for the CIE 1931 2 Degree Standard Observer already exists, this definition is intended for educational purpose.

References

[1]	Wyszecki, G., & Stiles, W. S. (2000). Table 1(3.3.3). In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 138–139). Wiley. ISBN:978-0471399186

Examples

>>> RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs(700)  
array([ 0.0113577...,  0.004102  ,  0.        ])

colour.RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs(wavelength)¶

Converts Stiles & Burch 1959 10 Degree RGB CMFs colour matching functions into the CIE 1964 10 Degree Standard Observer colour matching functions.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in nm.
Returns:	CIE 1964 10 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray

See also

colour.colorimetry.dataset.cmfs.RGB_CMFS

Notes

• Data for the CIE 1964 10 Degree Standard Observer already exists, this definition is intended for educational purpose.

References

[2]	Wyszecki, G., & Stiles, W. S. (2000). The CIE 1964 Standard Observer. In Color Science: Concepts and Methods, Quantitative Data and Formulae (p. 141). Wiley. ISBN:978-0471399186

Examples

>>> RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs(700)  
array([  9.6432150...e-03,   3.7526317...e-03,  -4.1078830...e-06])

colour.LMS_2_degree_cmfs_to_XYZ_2_degree_cmfs(wavelength)¶

Converts Stockman & Sharpe 2 Degree Cone Fundamentals colour matching functions into the CIE 2012 2 Degree Standard Observer colour matching functions.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in nm.
Returns:	CIE 2012 2 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray

Notes

• Data for the CIE 2012 2 Degree Standard Observer already exists, this definition is intended for educational purpose.

References

[4]	CVRL. (n.d.). CIE (2012) 2-deg XYZ “physiologically-relevant” colour matching functions. Retrieved June 25, 2014, from http://www.cvrl.org/database/text/cienewxyz/cie2012xyz2.htm

Examples

>>> LMS_2_degree_cmfs_to_XYZ_2_degree_cmfs(700)  
array([ 0.0109677...,  0.0041959...,  0.        ])

colour.LMS_10_degree_cmfs_to_XYZ_10_degree_cmfs(wavelength)¶

Converts Stockman & Sharpe 10 Degree Cone Fundamentals colour matching functions into the CIE 2012 10 Degree Standard Observer colour matching functions.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in nm.
Returns:	CIE 2012 10 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray

Notes

• Data for the CIE 2012 10 Degree Standard Observer already exists, this definition is intended for educational purpose.

References

[5]	CVRL. (n.d.). CIE (2012) 10-deg XYZ “physiologically-relevant” colour matching functions. Retrieved June 25, 2014, from http://www.cvrl.org/database/text/cienewxyz/cie2012xyz10.htm

Examples

>>> LMS_10_degree_cmfs_to_XYZ_10_degree_cmfs(700)  
array([ 0.0098162...,  0.0037761...,  0.        ])

colour.spectral_to_XYZ(spd, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2adc373cd290>, illuminant=None)¶

Converts given spectral power distribution to CIE XYZ tristimulus values using given colour matching functions and illuminant.

Parameters:	spd (SpectralPowerDistribution) – Spectral power distribution. cmfs (XYZ_ColourMatchingFunctions) – Standard observer colour matching functions. illuminant (SpectralPowerDistribution, optional) – Illuminant spectral power distribution.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray, (3,)

Warning

The output domain of that definition is non standard!

Notes

• Output CIE XYZ tristimulus values are in domain [0, 100].

References

[1]	Wyszecki, G., & Stiles, W. S. (2000). Integration Replace by Summation. In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 158–163). Wiley. ISBN:978-0471399186

Examples

>>> from colour import CMFS, ILLUMINANTS_RELATIVE_SPDS, SpectralPowerDistribution  
>>> cmfs = CMFS.get('CIE 1931 2 Degree Standard Observer')
>>> data = {380: 0.0600, 390: 0.0600}
>>> spd = SpectralPowerDistribution('Custom', data)
>>> illuminant = ILLUMINANTS_RELATIVE_SPDS.get('D50')
>>> spectral_to_XYZ(spd, cmfs, illuminant)  
array([  4.5764852...e-04,   1.2964866...e-05,   2.1615807...e-03])

colour.wavelength_to_XYZ(wavelength, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2adc373cd290>)¶

Converts given wavelength \(\lambda\) to CIE XYZ tristimulus values using given colour matching functions.

If the wavelength \(\lambda\) is not available in the colour matching function, its value will be calculated using CIE recommendations: The method developed by Sprague (1880) should be used for interpolating functions having a uniformly spaced independent variable and a Cubic Spline method for non-uniformly spaced independent variable.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in nm. cmfs (XYZ_ColourMatchingFunctions, optional) – Standard observer colour matching functions.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray
Raises:	ValueError – If wavelength \(\lambda\) is not contained in the colour matching functions domain.

Notes

• Output CIE XYZ tristimulus values are in domain [0, 1].
• If scipy is not unavailable the Cubic Spline method will fallback to legacy Linear interpolation.

Examples

>>> from colour import CMFS
>>> cmfs = CMFS.get('CIE 1931 2 Degree Standard Observer')
>>> wavelength_to_XYZ(480)  
array([ 0.09564  ,  0.13902  ,  0.812950...])

colour.whiteness(method=u'CIE 2004', **kwargs)¶

Returns the whiteness \(W\) using given method.

Parameters:	method (unicode, optional) – {‘CIE 2004’, ‘Berger 1959’, ‘Taube 1960’, ‘Stensby 1968’, ‘ASTM 313’, ‘Ganz 1979’, ‘CIE 2004’} Computation method. **kwargs (**) – Keywords arguments.
Returns:	whiteness \(W\).
Return type:	numeric or ndarray

Examples

>>> xy = np.array([0.3167, 0.3334])
>>> Y = 100
>>> xy_n = np.array([0.3139, 0.3311])
>>> whiteness(xy=xy, Y=Y, xy_n=xy_n)  
array([ 93.85...,  -1.305...])
>>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])
>>> XYZ_0 = np.array([94.80966767, 100.00000000, 107.30513595])
>>> method = 'Taube 1960'
>>> whiteness(XYZ=XYZ, XYZ_0=XYZ_0, method=method)  
91.4071738...

colour.whiteness_Berger1959(XYZ, XYZ_0)¶

Returns the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using Berger (1959) method. [2]_

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of sample. XYZ_0 (array_like) – CIE XYZ tristimulus values of reference white.
Returns:	Whiteness \(WI\).
Return type:	numeric or ndarray

Notes

• Input CIE XYZ and CIE XYZ_0 tristimulus values are in domain [0, 100].
• Whiteness \(WI\) values larger than 33.33 indicate a bluish white, and values smaller than 33.33 indicate a yellowish white.

Warning

The input domain of that definition is non standard!

Examples

>>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])
>>> XYZ_0 = np.array([94.80966767, 100.00000000, 107.30513595])
>>> whiteness_Berger1959(XYZ, XYZ_0)  
30.3638017...

colour.whiteness_Taube1960(XYZ, XYZ_0)¶

Returns the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using Taube (1960) method. [2]_

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of sample. XYZ_0 (array_like) – CIE XYZ tristimulus values of reference white.
Returns:	Whiteness \(WI\).
Return type:	numeric or ndarray

Notes

• Input CIE XYZ and CIE XYZ_0 tristimulus values are in domain [0, 100].
• Whiteness \(WI\) values larger than 100 indicate a bluish white, and values smaller than 100 indicate a yellowish white.

Examples

>>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])
>>> XYZ_0 = np.array([94.80966767, 100.00000000, 107.30513595])
>>> whiteness_Taube1960(XYZ, XYZ_0)  
91.4071738...

colour.whiteness_Stensby1968(Lab)¶

Returns the whiteness index \(WI\) of given sample CIE Lab colourspace array using Stensby (1968) method. [2]_

Parameters:	Lab (array_like) – CIE Lab colourspace array of sample.
Returns:	Whiteness \(WI\).
Return type:	numeric or ndarray

Notes

• Input CIE Lab colourspace array is in domain [0, 100].
• Whiteness \(WI\) values larger than 100 indicate a bluish white, and values smaller than 100 indicate a yellowish white.

Examples

>>> Lab = np.array([100.00000000, -2.46875131, -16.72486654])
>>> whiteness_Stensby1968(Lab)  
142.7683456...

colour.whiteness_ASTM313(XYZ)¶

Returns the whiteness index \(WI\) of given sample CIE XYZ tristimulus values using ASTM 313 method. [2]_

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values of sample.
Returns:	Whiteness \(WI\).
Return type:	numeric or ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].

Warning

The input domain of that definition is non standard!

Examples

>>> XYZ = np.array([95.00000000, 100.00000000, 105.00000000])
>>> whiteness_ASTM313(XYZ)  
55.7400000...

colour.whiteness_Ganz1979(xy, Y)¶

Returns the whiteness index \(W\) and tint \(T\) of given sample xy chromaticity coordinates using Ganz and Griesser (1979) method. [2]_

Parameters:	xy (array_like) – Chromaticity coordinates xy of sample. Y (numeric or array_like) – Tristimulus \(Y\) value of sample.
Returns:	Whiteness \(W\) and tint \(T\).
Return type:	ndarray

Notes

• Input tristimulus \(Y\) value is in domain [0, 100].
• The formula coefficients are valid for CIE Standard Illuminant D Series D65 and CIE 1964 10 Degree Standard Observer.
• Positive output tint \(T\) values indicate a greener tint while negative values indicate a redder tint.
• Whiteness differences of less than 5 Ganz units appear to be indistinguishable to the human eye.
• Tint differences of less than 0.5 Ganz units appear to be indistinguishable to the human eye.

Warning

The input domain of that definition is non standard!

Examples

>>> xy = np.array([0.3167, 0.3334])
>>> whiteness_Ganz1979(xy, 100)  
array([ 85.6003766...,   0.6789003...])

colour.whiteness_CIE2004(xy, Y, xy_n, observer=u'CIE 1931 2 Degree Standard Observer')¶

Returns the whiteness \(W\) or \(W_{10}\) and tint \(T\) or \(T_{10}\) of given sample xy chromaticity coordinates using CIE 2004 method.

Parameters:	xy (array_like) – Chromaticity coordinates xy of sample. Y (numeric or array_like) – Tristimulus \(Y\) value of sample. xy_n (array_like) – Chromaticity coordinates xy_n of perfect diffuser. observer (unicode, optional) – {‘CIE 1931 2 Degree Standard Observer’, ‘CIE 1964 10 Degree Standard Observer’} CIE Standard Observer used for computations, tint \(T\) or \(T_{10}\) value is dependent on viewing field angular subtense.
Returns:	Whiteness \(W\) or \(W_{10}\) and tint \(T\) or \(T_{10}\) of given sample.
Return type:	ndarray

Notes

• Input tristimulus \(Y\) value is in domain [0, 100].
• This method may be used only for samples whose values of \(W\) or \(W_{10}\) lie within the following limits: greater than 40 and less than 5Y - 280, or 5Y10 - 280.
• This method may be used only for samples whose values of \(T\) or \(T_{10}\) lie within the following limits: greater than -4 and less than +2.
• Output whiteness \(W\) or \(W_{10}\) values larger than 100 indicate a bluish white while values smaller than 100 indicate a yellowish white. [2]_
• Positive output tint \(T\) or \(T_{10}\) values indicate a greener tint while negative values indicate a redder tint.

Warning

The input domain of that definition is non standard!

References

[4]	CIE TC 1-48. (2004). The evaluation of whiteness. In CIE 015:2004 Colorimetry, 3rd Edition (p. 24). ISBN:978-3-901-90633-6

Examples

>>> xy = np.array([0.3167, 0.3334])
>>> xy_n = np.array([0.3139, 0.3311])
>>> whiteness_CIE2004(xy, 100, xy_n)  
array([ 93.85...,  -1.305...])

colour.delta_E(Lab1, Lab2, method=u'CMC', **kwargs)¶

Returns the Lightness \(L^*\) using given method.

Parameters:	Lab1 (array_like) – CIE Lab colourspace array 1. Lab2 (array_like) – CIE Lab colourspace array 2. method (unicode, optional) – {‘CMC’, ‘CIE 1976’, ‘CIE 1994’, ‘CIE 2000’} Computation method. **kwargs (**) – Keywords arguments.
Returns:	Colour difference \(\Delta E_{ab}\).
Return type:	numeric or ndarray

Examples

>>> Lab1 = np.array([100.00000000, 21.57210357, 272.22819350])
>>> Lab2 = np.array([100.00000000, 426.67945353, 72.39590835])
>>> delta_E(Lab1, Lab2)  
172.7047712...
>>> delta_E(Lab1, Lab2, method='CIE 1976')  
451.7133019...
>>> delta_E(Lab1, Lab2, method='CIE 1994')  
88.3355530...
>>> delta_E(Lab1, Lab2, method='CIE 1994', textiles=False)    
83.7792255...
>>> delta_E(Lab1, Lab2, method='CIE 2000')  
94.0356490...

colour.delta_E_CIE1976(Lab1, Lab2, **kwargs)¶

Returns the difference \(\Delta E_{ab}\) between two given CIE Lab colourspace arrays using CIE 1976 recommendation.

Parameters:	Lab1 (array_like) – CIE Lab colourspace array 1. Lab2 (array_like) – CIE Lab colourspace array 2. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other \(\Delta E_{ab}\) computation objects.
Returns:	Colour difference \(\Delta E_{ab}\).
Return type:	numeric or ndarray

References

[2]	Lindbloom, B. (2003). Delta E (CIE 1976). Retrieved February 24, 2014, from http://brucelindbloom.com/Eqn_DeltaE_CIE76.html

Examples

>>> Lab1 = np.array([100.00000000, 21.57210357, 272.22819350])
>>> Lab2 = np.array([100.00000000, 426.67945353, 72.39590835])
>>> delta_E_CIE1976(Lab1, Lab2)  
451.7133019...

colour.delta_E_CIE1994(Lab1, Lab2, textiles=True, **kwargs)¶

Returns the difference \(\Delta E_{ab}\) between two given CIE Lab colourspace arrays using CIE 1994 recommendation.

Parameters:	Lab1 (array_like) – CIE Lab colourspace array 1. Lab2 (array_like) – CIE Lab colourspace array 2. textiles (bool, optional) – Application specific weights. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other \(\Delta E_{ab}\) computation objects.
Returns:	Colour difference \(\Delta E_{ab}\).
Return type:	numeric or ndarray

References

[3]	Lindbloom, B. (2011). Delta E (CIE 1994). Retrieved February 24, 2014, from http://brucelindbloom.com/Eqn_DeltaE_CIE94.html

Examples

>>> Lab1 = np.array([100.00000000, 21.57210357, 272.22819350])
>>> Lab2 = np.array([100.00000000, 426.67945353, 72.39590835])
>>> delta_E_CIE1994(Lab1, Lab2)  
88.3355530...
>>> delta_E_CIE1994(Lab1, Lab2, textiles=False)  
83.7792255...

colour.delta_E_CIE2000(Lab1, Lab2, **kwargs)¶

Returns the difference \(\Delta E_{ab}\) between two given CIE Lab colourspace arrays using CIE 2000 recommendation.

Parameters:	Lab1 (array_like) – CIE Lab colourspace array 1. Lab2 (array_like) – CIE Lab colourspace array 2. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other \(\Delta E_{ab}\) computation objects.
Returns:	Colour difference \(\Delta E_{ab}\).
Return type:	numeric or ndarray

References

[4]	Lindbloom, B. (2009). Delta E (CIE 2000). Retrieved February 24, 2014, from http://brucelindbloom.com/Eqn_DeltaE_CIE2000.html

Examples

>>> Lab1 = np.array([100.00000000, 21.57210357, 272.22819350])
>>> Lab2 = np.array([100.00000000, 426.67945353, 72.39590835])
>>> delta_E_CIE2000(Lab1, Lab2)  
94.0356490...

colour.delta_E_CMC(Lab1, Lab2, l=2, c=1)¶

Returns the difference \(\Delta E_{ab}\) between two given CIE Lab colourspace arrays using Colour Measurement Committee recommendation.

The quasimetric has two parameters: Lightness (l) and chroma (c), allowing the users to weight the difference based on the ratio of l:c. Commonly used values are 2:1 for acceptability and 1:1 for the threshold of imperceptibility.

Parameters:	Lab1 (array_like) – CIE Lab colourspace array 1. Lab2 (array_like) – CIE Lab colourspace array 2. l (numeric, optional) – Lightness weighting factor. c (numeric, optional) – Chroma weighting factor.
Returns:	Colour difference \(\Delta E_{ab}\).
Return type:	numeric or ndarray

References

[5]	Lindbloom, B. (2009). Delta E (CMC). Retrieved February 24, 2014, from http://brucelindbloom.com/Eqn_DeltaE_CMC.html

Examples

>>> Lab1 = np.array([100.00000000, 21.57210357, 272.22819350])
>>> Lab2 = np.array([100.00000000, 426.67945353, 72.39590835])
>>> delta_E_CMC(Lab1, Lab2)  
172.7047712...

class colour.IES_TM2714_Spd(path=None, header=None, spectral_quantity=None, reflection_geometry=None, transmission_geometry=None, bandwidth_FWHM=None, bandwidth_corrected=None)¶

Bases: colour.colorimetry.spectrum.SpectralPowerDistribution

Defines a IES TM-27-14 spectral power distribution.

This class can read and write IES TM-27-14 spectral data XML files.

Parameters:

path (unicode, optional) – Spectral data XML file path. header (IES_TM2714_Header, optional) – IES TM-27-14 spectral power distribution header. spectral_quantity (unicode, optional) – {‘flux’, ‘absorptance’, ‘transmittance’, ‘reflectance’, ‘intensity’, ‘irradiance’, ‘radiance’, ‘exitance’, ‘R-Factor’, ‘T-Factor’, ‘relative’, ‘other’} Quantity of measurement for each element of the spectral data. reflection_geometry (unicode, optional) – {‘di:8’, ‘de:8’, ‘8:di’, ‘8:de’, ‘d:d’, ‘d:0’, ‘45a:0’, ‘45c:0’, ‘0:45a’, ‘45x:0’, ‘0:45x’, ‘other’} Spectral reflectance factors geometric conditions. transmission_geometry (unicode, optional) – {‘0:0’, ‘di:0’, ‘de:0’, ‘0:di’, ‘0:de’, ‘d:d’, ‘other’} Spectral transmittance factors geometric conditions. bandwidth_FWHM (numeric, optional) – Spectroradiometer full-width half-maximum bandwidth in nanometers. bandwidth_corrected (bool, optional) – Specifies if bandwidth correction has been applied to the measured data.

mapping¶

path¶

header¶

spectral_quantity¶

reflection_geometry¶

transmission_geometry¶

bandwidth_FWHM¶

bandwidth_corrected¶

read()¶

write()¶

Notes

Reflection Geometry

• di:8: Diffuse / eight-degree, specular component included.
• de:8: Diffuse / eight-degree, specular component excluded.
• 8:di: Eight-degree / diffuse, specular component included.
• 8:de: Eight-degree / diffuse, specular component excluded.
• d:d: Diffuse / diffuse.
• d:0: Alternative diffuse.
• 45a:0: Forty-five degree annular / normal.
• 45c:0: Forty-five degree circumferential / normal.
• 0:45a: Normal / forty-five degree annular.
• 45x:0: Forty-five degree directional / normal.
• 0:45x: Normal / forty-five degree directional.
• other: User-specified in comments.

Transmission Geometry

• 0:0: Normal / normal.
• di:0: Diffuse / normal, regular component included.
• de:0: Diffuse / normal, regular component excluded.
• 0:di: Normal / diffuse, regular component included.
• 0:de: Normal / diffuse, regular component excluded.
• d:d: Diffuse / diffuse.
• other: User-specified in comments.

Examples

>>> from os.path import dirname, join
>>> directory = join(dirname(__file__), 'tests', 'resources')
>>> spd = IES_TM2714_Spd(join(directory, 'Fluorescent.spdx'))
>>> spd.read()
True
>>> spd.header.manufacturer
'Unknown'
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[501.7]  
array(0.095...)

bandwidth_FWHM

Property for self.__bandwidth_FWHM private attribute.

Returns:	self.__bandwidth_FWHM.
Return type:	numeric

bandwidth_corrected

Property for self.__bandwidth_corrected private attribute.

Returns:	self.__bandwidth_corrected.
Return type:	bool

header

Property for self.__header private attribute.

Returns:	self.__header.
Return type:	IES_TM2714_Header

mapping

Property for self.mapping attribute.

Return type:	Structure

Warning

IES_TM2714_Spd.mapping is read only.

path

Property for self.__path private attribute.

Returns:	self.__path.
Return type:	unicode

read()

Reads and parses the spectral data XML file path.

Returns:	Definition success.
Return type:	bool

Examples

>>> from os.path import dirname, join
>>> directory = join(dirname(__file__), 'tests', 'resources')
>>> spd = IES_TM2714_Spd(join(directory, 'Fluorescent.spdx'))
>>> spd.read()
True
>>> spd.header.description
'Rare earth fluorescent lamp'
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[400]  
array(0.034...)

reflection_geometry

Property for self.__reflection_geometry private attribute.

Returns:	self.__reflection_geometry.
Return type:	unicode

spectral_quantity

Property for self.__spectral_quantity private attribute.

Returns:	self.__spectral_quantity.
Return type:	unicode

transmission_geometry

Property for self.__transmission_geometry private attribute.

Returns:	self.__transmission_geometry.
Return type:	unicode

write()

Write the spd spectral data to XML file path.

Returns:	Definition success.
Return type:	bool

Examples

>>> from os.path import dirname, join
>>> from shutil import rmtree
>>> from tempfile import mkdtemp
>>> directory = join(dirname(__file__), 'tests', 'resources')
>>> spd = IES_TM2714_Spd(join(directory, 'Fluorescent.spdx'))
>>> spd.read()
True
>>> temporary_directory = mkdtemp()
>>> spd.path = join(temporary_directory, 'Fluorescent.spdx')
>>> spd.write()
True
>>> rmtree(temporary_directory)

colour.read_image(path, bit_depth=u'float32')¶

Reads given image using OpenImageIO.

Parameters:	path (unicode) – Image path. bit_depth (unicode, optional) – {‘float32’, ‘uint8’, ‘uint16’, ‘float16’} Image bit_depth.
Returns:	Image as a ndarray.
Return type:	ndarray

Examples

>>> import os
>>> path = os.path.join('tests', 'resources', 'CMSTestPattern.exr')
>>> image = read_image_as_array(path)  

colour.write_image(image, path, bit_depth=u'float32')¶

Writes given image using OpenImageIO.

Parameters:	image (array_like) – Image data. path (unicode) – Image path. bit_depth (unicode, optional) – {‘float32’, ‘uint8’, ‘uint16’, ‘float16’} Image bit_depth.
Returns:	Definition success.
Return type:	bool

Examples

>>> import os
>>> path = os.path.join('tests', 'resources', 'CMSTestPattern.exr')
>>> image = read_image_as_array(path)  
>>> path = os.path.join('tests', 'resources', 'CMSTestPattern.png')
>>> write_image(image, path, 'uint8')  
True

colour.read_spectral_data_from_csv_file(path, delimiter=u', ', fields=None, default=0)¶

Reads the spectral data from given CSV file in the following form:

390, 4.15003E-04, 3.68349E-04, 9.54729E-03 395, 1.05192E-03, 9.58658E-04, 2.38250E-02 400, 2.40836E-03, 2.26991E-03, 5.66498E-02 ... 830, 9.74306E-07, 9.53411E-08, 0.00000

and returns it as an OrderedDict of dict as follows:

OrderedDict([ (‘field’, {‘wavelength’: ‘value’, ..., ‘wavelength’: ‘value’}), ..., (‘field’, {‘wavelength’: ‘value’, ..., ‘wavelength’: ‘value’})])

Parameters:	path (unicode) – Absolute CSV file path. delimiter (unicode, optional) – CSV file content delimiter. fields (array_like, optional) – CSV file spectral data fields names. If no value is provided the first line of the file will be used as spectral data fields names. default (numeric, optional) – Default value for fields row with missing value.
Returns:	CSV file content.
Return type:	OrderedDict
Raises:	RuntimeError – If the CSV spectral data file doesn’t define the appropriate fields.

Notes

• A CSV spectral data file should define at least define two fields: one for the wavelengths and one for the associated values of one spectral power distribution.
• If no value is provided for the fields names, the first line of the file will be used as spectral data fields names.

Examples

>>> import os
>>> from pprint import pprint
>>> csv_file = os.path.join(
...     os.path.dirname(__file__),
...     'tests',
...     'resources',
...     'colorchecker_n_ohta.csv')
>>> spds_data = read_spectral_data_from_csv_file(csv_file)
>>> pprint(list(spds_data.keys()))
['1',
 '2',
 '3',
 '4',
 '5',
 '6',
 '7',
 '8',
 '9',
 '10',
 '11',
 '12',
 '13',
 '14',
 '15',
 '16',
 '17',
 '18',
 '19',
 '20',
 '21',
 '22',
 '23',
 '24']

colour.read_spds_from_csv_file(path, delimiter=u', ', fields=None, default=0)¶

Reads the spectral data from given CSV file and return its content as an OrderedDict of colour.colorimetry.spectrum.SpectralPowerDistribution classes.

Parameters:	path (unicode) – Absolute CSV file path. delimiter (unicode, optional) – CSV file content delimiter. fields (array_like, optional) – CSV file spectral data fields names. If no value is provided the first line of the file will be used for as spectral data fields names. default (numeric) – Default value for fields row with missing value.
Returns:	colour.colorimetry.spectrum.SpectralPowerDistribution classes of given CSV file.
Return type:	OrderedDict

Examples

>>> import os
>>> from pprint import pprint
>>> csv_file = os.path.join(
...     os.path.dirname(__file__),
...     'tests',
...     'resources',
...     'colorchecker_n_ohta.csv')
>>> spds = read_spds_from_csv_file(csv_file)
>>> pprint(tuple(spds.items()))  
(('1',
  <...SpectralPowerDistribution object at 0x...>),
 ('2',
  <...SpectralPowerDistribution object at 0x...>),
 ('3',
  <...SpectralPowerDistribution object at 0x...>),
 ('4',
  <...SpectralPowerDistribution object at 0x...>),
 ('5',
  <...SpectralPowerDistribution object at 0x...>),
 ('6',
  <...SpectralPowerDistribution object at 0x...>),
 ('7',
  <...SpectralPowerDistribution object at 0x...>),
 ('8',
  <...SpectralPowerDistribution object at 0x...>),
 ('9',
  <...SpectralPowerDistribution object at 0x...>),
 ('10',
  <...SpectralPowerDistribution object at 0x...>),
 ('11',
  <...SpectralPowerDistribution object at 0x...>),
 ('12',
  <...SpectralPowerDistribution object at 0x...>),
 ('13',
  <...SpectralPowerDistribution object at 0x...>),
 ('14',
  <...SpectralPowerDistribution object at 0x...>),
 ('15',
  <...SpectralPowerDistribution object at 0x...>),
 ('16',
  <...SpectralPowerDistribution object at 0x...>),
 ('17',
  <...SpectralPowerDistribution object at 0x...>),
 ('18',
  <...SpectralPowerDistribution object at 0x...>),
 ('19',
  <...SpectralPowerDistribution object at 0x...>),
 ('20',
  <...SpectralPowerDistribution object at 0x...>),
 ('21',
  <...SpectralPowerDistribution object at 0x...>),
 ('22',
  <...SpectralPowerDistribution object at 0x...>),
 ('23',
  <...SpectralPowerDistribution object at 0x...>),
 ('24',
  <...SpectralPowerDistribution object at 0x...>))

colour.write_spds_to_csv_file(spds, path, delimiter=u', ', fields=None)¶

Writes the given spectral power distributions to given CSV file.

Parameters:	spds (dict) – Spectral power distributions to write. path (unicode) – Absolute CSV file path. delimiter (unicode, optional) – CSV file content delimiter. fields (array_like, optional) – CSV file spectral data fields names. If no value is provided the order of fields will be the one defined by the sorted spectral power distributions dict.
Returns:	Definition success.
Return type:	bool
Raises:	RuntimeError – If the given spectral power distributions have different shapes.

colour.read_spds_from_xrite_file(path)¶

Reads the spectral data from given X-Rite file and returns it as an OrderedDict of colour.colorimetry.spectrum.SpectralPowerDistribution classes.

Parameters:	path (unicode) – Absolute X-Rite file path.
Returns:	colour.colorimetry.spectrum.SpectralPowerDistribution classes of given X-Rite file.
Return type:	OrderedDict

Notes

• This parser is minimalistic and absolutely not bullet proof.

Examples

>>> import os
>>> from pprint import pprint
>>> xrite_file = os.path.join(
...     os.path.dirname(__file__),
...     'tests',
...     'resources',
...     'xrite_digital_colour_checker.txt')
>>> spds_data = read_spds_from_xrite_file(xrite_file)
>>> pprint(list(spds_data.keys()))  
['X1', 'X2', 'X3', 'X4', 'X5', 'X6', 'X7', 'X8', 'X9', 'X10']

colour.XYZ_to_xyY(XYZ, illuminant=(0.34567, 0.3585))¶

Converts from CIE XYZ tristimulus values to CIE xyY colourspace and reference illuminant.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	CIE xyY colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].
• Output CIE xyY colourspace array is in domain [0, 1].

References

[2]	Lindbloom, B. (2003). XYZ to xyY. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_XYZ_to_xyY.html

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_to_xyY(XYZ)  
array([ 0.2641477...,  0.3777000...,  0.1008    ])

colour.xyY_to_XYZ(xyY)¶

Converts from CIE xyY colourspace to CIE XYZ tristimulus values.

Parameters:	xyY (array_like) – CIE xyY colourspace array.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input CIE xyY colourspace array is in domain [0, 1].
• Output CIE XYZ tristimulus values are in domain [0, 1].

References

[3]	Lindbloom, B. (2009). xyY to XYZ. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_xyY_to_XYZ.html

Examples

>>> xyY = np.array([0.26414772, 0.37770001, 0.10080000])
>>> xyY_to_XYZ(xyY)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.xy_to_XYZ(xy)¶

Returns the CIE XYZ tristimulus values from given xy chromaticity coordinates.

Parameters:	xy (array_like) – xy chromaticity coordinates.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input xy chromaticity coordinates are in domain [0, 1].
• Output CIE XYZ tristimulus values are in domain [0, 1].

Examples

>>> xy = np.array([0.26414772236966133, 0.37770000704815188])
>>> xy_to_XYZ(xy)  
array([ 0.6993585...,  1.        ,  0.9482453...])

colour.XYZ_to_xy(XYZ, illuminant=(0.34567, 0.3585))¶

Returns the xy chromaticity coordinates from given CIE XYZ tristimulus values.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	xy chromaticity coordinates.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].
• Output xy chromaticity coordinates are in domain [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_to_xy(XYZ)  
array([ 0.2641477...,  0.3777000...])

class colour.RGB_Colourspace(name, primaries, whitepoint, illuminant=None, RGB_to_XYZ_matrix=None, XYZ_to_RGB_matrix=None, transfer_function=None, inverse_transfer_function=None)¶

Bases: object

Implements support for the RGB colourspaces dataset from colour.models.dataset.aces_rgb, etc....

Parameters:

name (unicode) – RGB colourspace name. primaries (array_like) – RGB colourspace primaries. whitepoint (array_like) – RGB colourspace whitepoint. illuminant (unicode, optional) – RGB colourspace whitepoint name as illuminant. RGB_to_XYZ_matrix (array_like, optional) – Transformation matrix from colourspace to CIE XYZ tristimulus values. XYZ_to_RGB_matrix (array_like, optional) – Transformation matrix from CIE XYZ tristimulus values to colourspace. transfer_function (object, optional) – RGB colourspace opto-electronic conversion function from linear to colourspace. inverse_transfer_function (object, optional) – RGB colourspace inverse opto-electronic conversion function from colourspace to linear.

RGB_to_XYZ_matrix¶

Property for self.__to_XYZ private attribute.

Returns:	self.__to_XYZ.
Return type:	array_like, (3, 3)

XYZ_to_RGB_matrix¶

Property for self.__to_RGB private attribute.

Returns:	self.__to_RGB.
Return type:	array_like, (3, 3)

illuminant¶

Property for self.__illuminant private attribute.

Returns:	self.__illuminant.
Return type:	unicode

inverse_transfer_function¶

Property for self.__inverse_transfer_function private attribute.

Returns:	self.__inverse_transfer_function.
Return type:	object

name¶

Property for self.__name private attribute.

Returns:	self.__name.
Return type:	unicode

primaries¶

Property for self.__primaries private attribute.

Returns:	self.__primaries.
Return type:	array_like, (3, 2)

transfer_function¶

Property for self.__transfer_function private attribute.

Returns:	self.__transfer_function.
Return type:	object

whitepoint¶

Property for self.__whitepoint private attribute.

Returns:	self.__whitepoint.
Return type:	array_like

colour.normalised_primary_matrix(primaries, whitepoint)¶

Returns the normalised primary matrix using given primaries and whitepoint.

Parameters:	primaries (array_like, (3, 2)) – Primaries chromaticity coordinates. whitepoint (array_like) – Illuminant / whitepoint chromaticity coordinates.
Returns:	Normalised primary matrix.
Return type:	ndarray, (3, 3)

Examples

>>> pms = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> normalised_primary_matrix(pms, whitepoint)  
array([[  9.5255239...e-01,   0.0000000...e+00,   9.3678631...e-05],
       [  3.4396645...e-01,   7.2816609...e-01,  -7.2132546...e-02],
       [  0.0000000...e+00,   0.0000000...e+00,   1.0088251...e+00]])

colour.primaries_whitepoint(npm)¶

Returns primaries and whitepoint using given normalised primary matrix.

Parameters:	npm (array_like, (3, 3)) – Normalised primary matrix.
Returns:	Primaries and whitepoint.
Return type:	tuple

References

[2]	Trieu, T. (2015). Private Discussion with Mansencal, T.

Examples

>>> npm = np.array([[9.52552396e-01, 0.00000000e+00, 9.36786317e-05],
...                 [3.43966450e-01, 7.28166097e-01, -7.21325464e-02],
...                 [0.00000000e+00, 0.00000000e+00, 1.00882518e+00]])
>>> p, w = primaries_whitepoint(npm)
>>> p  
array([[  7.3470000...e-01,   2.6530000...e-01],
       [  0.0000000...e+00,   1.0000000...e+00],
       [  1.0000000...e-04,  -7.7000000...e-02]])
>>> w 
array([ 0.32168,  0.33767])

colour.RGB_luminance_equation(primaries, whitepoint)¶

Returns the luminance equation from given primaries and whitepoint.

Parameters:	primaries (array_like, (3, 2)) – Primaries chromaticity coordinates. whitepoint (array_like) – Illuminant / whitepoint chromaticity coordinates.
Returns:	Luminance equation.
Return type:	unicode

Examples

>>> pms = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> # Doctests skip for Python 2.x compatibility.
>>> RGB_luminance_equation(pms, whitepoint)  
'Y = 0.3439664...(R) + 0.7281660...(G) + -0.0721325...(B)'

colour.RGB_luminance(RGB, primaries, whitepoint)¶

Returns the luminance \(Y\) of given RGB components from given primaries and whitepoint.

Parameters:	RGB (array_like) – RGB chromaticity coordinate matrix. primaries (array_like, (3, 2)) – Primaries chromaticity coordinate matrix. whitepoint (array_like) – Illuminant / whitepoint chromaticity coordinates.
Returns:	Luminance \(Y\).
Return type:	numeric or ndarray

Examples

>>> RGB = np.array([40.6, 4.2, 67.4])
>>> pms = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> RGB_luminance(RGB, pms, whitepoint)  
12.1616018...

colour.XYZ_to_Lab(XYZ, illuminant=(0.34567, 0.3585))¶

Converts from CIE XYZ tristimulus values to CIE Lab colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	CIE Lab colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].
• Input illuminant chromaticity coordinates are in domain [0, 1].
• Output Lightness \(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.10080000, 0.09558313])
>>> XYZ_to_Lab(XYZ)  
array([ 37.9856291..., -23.6230288...,  -4.4141703...])

colour.Lab_to_XYZ(Lab, illuminant=(0.34567, 0.3585))¶

Converts from CIE Lab colourspace to CIE XYZ tristimulus values.

Parameters:	Lab (array_like) – CIE Lab colourspace array. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input Lightness \(L^*\) is in domain [0, 100].
• Input illuminant chromaticity coordinates are in domain [0, 1].
• Output CIE XYZ tristimulus values are 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.98562910, -23.62302887, -4.41417036])
>>> Lab_to_XYZ(Lab)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.Lab_to_LCHab(Lab)¶

Converts from CIE Lab colourspace to CIE LCHab colourspace.

Parameters:	Lab (array_like) – CIE Lab colourspace array.
Returns:	CIE LCHab colourspace array.
Return type:	ndarray

Notes

• Lightness \(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.98562910, -23.62302887, -4.41417036])
>>> Lab_to_LCHab(Lab)  
array([  37.9856291...,   24.0319036...,  190.5841597...])

colour.LCHab_to_Lab(LCHab)¶

Converts from CIE LCHab colourspace to CIE Lab colourspace.

Parameters:	LCHab (array_like) – CIE LCHab colourspace array.
Returns:	CIE Lab colourspace array.
Return type:	ndarray

Notes

• Lightness \(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.98562910, 24.03190365, 190.58415972])
>>> LCHab_to_Lab(LCHab)  
array([ 37.9856291..., -23.6230288...,  -4.4141703...])

colour.XYZ_to_Luv(XYZ, illuminant=(0.34567, 0.3585))¶

Converts from CIE XYZ tristimulus values to CIE Luv colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	CIE Luv colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].
• Input illuminant chromaticity coordinates are in domain [0, 1].
• Output \(L^*\) is in domain [0, 100].

References

[2]	Lindbloom, B. (2003). XYZ to Luv. Retrieved February 24, 2014, from http://brucelindbloom.com/Eqn_XYZ_to_Luv.html

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_to_Luv(XYZ)  
array([ 37.9856291..., -28.7922944...,  -1.3558195...])

colour.Luv_to_XYZ(Luv, illuminant=(0.34567, 0.3585))¶

Converts from CIE Luv colourspace to CIE XYZ tristimulus values.

Parameters:	Luv (array_like) – CIE Luv colourspace array. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input \(L^*\) is in domain [0, 100].
• Input illuminant chromaticity coordinates are in domain [0, 1].
• Output CIE XYZ tristimulus values are in domain [0, 1].

References

[3]	Lindbloom, B. (2003). Luv to XYZ. Retrieved February 24, 2014, from http://brucelindbloom.com/Eqn_Luv_to_XYZ.html

Examples

>>> Luv = np.array([37.98562910, -28.79229446, -1.35581950])
>>> Luv_to_XYZ(Luv)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.Luv_to_uv(Luv, illuminant=(0.34567, 0.3585))¶

Returns the \(uv^p\) chromaticity coordinates from given CIE Luv colourspace array.

Parameters:	Luv (array_like) – CIE Luv colourspace array. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	\(uv^p\) chromaticity coordinates.
Return type:	ndarray

Notes

• Input \(L^*\) is in domain [0, 100].
• Output \(uv^p\) chromaticity coordinates are in domain [0, 1].

References

[4]	Wikipedia. (n.d.). The forward transformation. Retrieved February 24, 2014, from http://en.wikipedia.org/wiki/CIELUV#The_forward_transformation

Examples

>>> Luv = np.array([37.98562910, -28.79229446, -1.35581950])
>>> Luv_to_uv(Luv)  
array([ 0.1508531...,  0.4853297...])

colour.Luv_uv_to_xy(uv)¶

Returns the xy chromaticity coordinates from given CIE Luv colourspace \(uv^p\) chromaticity coordinates.

Parameters:	uv (array_like) – CIE Luv u”v” chromaticity coordinates.
Returns:	xy chromaticity coordinates.
Return type:	ndarray

Notes

• Input \(uv^p\) chromaticity coordinates are in domain [0, 1].
• Output xy is in domain [0, 1].

References

[5]	Wikipedia. (n.d.). The reverse transformation. Retrieved from http://en.wikipedia.org/wiki/CIELUV#The_reverse_transformation

Examples

>>> uv = np.array([0.15085309882985695, 0.48532970854318019])
>>> Luv_uv_to_xy(uv)  
array([ 0.2641477...,  0.3777000...])

colour.Luv_to_LCHuv(Luv)¶

Converts from CIE Luv colourspace to CIE LCHuv colourspace.

Parameters:	Luv (array_like) – CIE Luv colourspace array.
Returns:	CIE LCHuv colourspace array.
Return type:	ndarray

Notes

• \(L^*\) is in domain [0, 100].

References

[6]	Lindbloom, B. (2003). Luv to LCH(uv). Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_Luv_to_LCH.html

Examples

>>> Luv = np.array([37.98562910, -28.79229446, -1.35581950])
>>> Luv_to_LCHuv(Luv)  
array([  37.9856291...,   28.8241993...,  182.6960474...])

colour.LCHuv_to_Luv(LCHuv)¶

Converts from CIE LCHuv colourspace to CIE Luv colourspace.

Parameters:	LCHuv (array_like) – CIE LCHuv colourspace array.
Returns:	CIE Luv colourspace array.
Return type:	ndarray

Notes

• \(L^*\) is in domain [0, 100].

References

[7]	Lindbloom, B. (2006). LCH(uv) to Luv. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_LCH_to_Luv.html

Examples

>>> LCHuv = np.array([37.98562910, 28.82419933, 182.69604747])
>>> LCHuv_to_Luv(LCHuv)  
array([ 37.9856291..., -28.7922944...,  -1.3558195...])

colour.XYZ_to_UCS(XYZ)¶

Converts from CIE XYZ tristimulus values to CIE UCS colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values.
Returns:	CIE UCS colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].
• Output CIE UCS colourspace array is in domain [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_to_UCS(XYZ)  
array([ 0.0469968...,  0.1008    ,  0.1637439...])

colour.UCS_to_XYZ(UVW)¶

Converts from CIE UCS colourspace to CIE XYZ tristimulus values.

Parameters:	UVW (array_like) – CIE UCS colourspace array.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input CIE UCS colourspace array is in domain [0, 1].
• Output CIE XYZ tristimulus values are in domain [0, 1].

Examples

>>> UVW = np.array([0.04699689, 0.10080000, 0.16374390])
>>> UCS_to_XYZ(UVW)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.UCS_to_uv(UVW)¶

Returns the uv chromaticity coordinates from given CIE UCS colourspace array.

Parameters:	UVW (array_like) – CIE UCS colourspace array.
Returns:	uv chromaticity coordinates.
Return type:	ndarray

Notes

• Input CIE UCS colourspace array is in domain [0, 1].
• Output uv chromaticity coordinates are in domain [0, 1].

Examples

>>> UCS = np.array([0.04699689, 0.10080000, 0.16374390])
>>> UCS_to_uv(UCS)  
array([ 0.1508530...,  0.3235531...])

colour.UCS_uv_to_xy(uv)¶

Returns the xy chromaticity coordinates from given CIE UCS colourspace uv chromaticity coordinates.

Parameters:	uv (array_like) – CIE UCS uv chromaticity coordinates.
Returns:	xy chromaticity coordinates.
Return type:	ndarray

Notes

• Input uv chromaticity coordinates are in domain [0, 1].
• Output xy chromaticity coordinates are in domain [0, 1].

Examples

>>> uv = np.array([0.15085308732766581, 0.3235531372954405])
>>> UCS_uv_to_xy(uv)  
array([ 0.2641477...,  0.3777000...])

colour.XYZ_to_UVW(XYZ, illuminant=(0.34567, 0.3585))¶

Converts from CIE XYZ tristimulus values to CIE 1964 U*V*W* colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	CIE 1964 U*V*W* colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 100].
• Output CIE UVW colourspace array is in domain [0, 100].

Warning

The input / output domains of that definition are non standard!

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313]) * 100
>>> XYZ_to_UVW(XYZ)  
array([-28.0483277...,  -0.8805242...,  37.0041149...])

colour.XYZ_to_IPT(XYZ)¶

Converts from CIE XYZ tristimulus values to IPT colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values.
Returns:	IPT colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values needs to be adapted for CIE Standard Illuminant D Series D65.

Examples

>>> XYZ = np.array([0.96907232, 1, 1.12179215])
>>> XYZ_to_IPT(XYZ)  
array([ 1.0030082...,  0.0190691..., -0.0136929...])

colour.IPT_to_XYZ(IPT)¶

Converts from IPT colourspace to CIE XYZ tristimulus values.

Parameters:	IPT (array_like) – IPT colourspace array.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Examples

>>> IPT = np.array([1.00300825, 0.01906918, -0.01369292])
>>> IPT_to_XYZ(IPT)  
array([ 0.9690723...,  1.        ,  1.1217921...])

colour.IPT_hue_angle(IPT)¶

Computes the hue angle from IPT colourspace.

Parameters:	IPT (array_like) – IPT colourspace array.
Returns:	Hue angle.
Return type:	numeric or ndarray

Examples

>>> IPT = np.array([0.96907232, 1, 1.12179215])
>>> IPT_hue_angle(IPT)  
0.8427358...

colour.linear_to_log(value, method=u'Cineon', **kwargs)¶

Converts from linear to log using given method.

Parameters:	value (numeric or array_like) – Value. method (unicode, optional) – {‘Cineon’, ‘Panalog’, ‘ViperLog’, ‘PLog’, ‘C-Log’, ‘ACEScc’, ‘ALEXA Log C’, ‘REDLogFilm’, ‘DCI-P3’, ‘S-Log’, ‘S-Log2’, ‘S-Log3’, ‘V-Log’}, Computation method. **kwargs (**) – Keywords arguments.
Returns:	Log value.
Return type:	numeric or ndarray

Examples

>>> linear_to_log(0.18)  
0.4573196...
>>> linear_to_log(0.18, method='ACEScc')  
array(0.4135884...)
>>> linear_to_log(0.18, method='PLog', log_reference=400)   
0.3910068...
>>> linear_to_log(0.18, method='S-Log')  
0.3599878...

colour.log_to_linear(value, method=u'Cineon', **kwargs)¶

Converts from log to linear using given method.

Parameters:	value (numeric or array_like) – Value. method (unicode, optional) – {‘Cineon’, ‘Panalog’, ‘ViperLog’, ‘PLog’, ‘C-Log’, ‘ACEScc’, ‘ALEXA Log C’, ‘DCI-P3’, ‘REDLogFilm’, ‘S-Log’, ‘S-Log2’, ‘S-Log3’, ‘V-Log’}, Computation method. **kwargs (**) – Keywords arguments.
Returns:	Log value.
Return type:	numeric or ndarray

Examples

>>> log_to_linear(0.45731961308541841)  
0.18...
>>> log_to_linear(0.41358840249244228, method='ACEScc')   
array(0.18...)
>>> log_to_linear(0.39100684261974583, method='PLog', log_reference=400)   
0.1...
>>> log_to_linear(0.35998784642215442, method='S-Log')   
0.1799999...

colour.linear_to_cineon(value, black_offset=0.0107977516232771, **kwargs)¶

Defines the linear to Cineon conversion function.

Parameters:	value (numeric or array_like) – Linear value. black_offset (numeric or array_like) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Cineon value.
Return type:	numeric or ndarray

Examples

>>> linear_to_cineon(0.18)  
0.4573196...

colour.cineon_to_linear(value, black_offset=0.0107977516232771, **kwargs)¶

Defines the Cineon to linear conversion function.

Parameters:	value (numeric or array_like) – Cineon value. black_offset (numeric or array_like) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> cineon_to_linear(0.45731961308541841)  
0.18...

colour.linear_to_panalog(value, black_offset=0.04077184461038074, **kwargs)¶

Defines the linear to Panalog conversion function.

Parameters:	value (numeric or array_like) – Linear value. black_offset (numeric or array_like) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Panalog value.
Return type:	numeric or ndarray

Examples

>>> linear_to_panalog(0.18)  
0.3745767...

colour.panalog_to_linear(value, black_offset=0.04077184461038074, **kwargs)¶

Defines the Panalog to linear conversion function.

Parameters:	value (numeric or array_like) – Panalog value. black_offset (numeric or array_like) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> panalog_to_linear(0.37457679138229816)  
0.1...

colour.linear_to_red_log_film(value, black_offset=0.009955040995908344, **kwargs)¶

Defines the linear to REDLogFilm conversion function.

Parameters:	value (numeric or array_like) – Linear value. black_offset (numeric or array_like) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	REDLogFilm value.
Return type:	numeric or ndarray

Examples

>>> linear_to_red_log_film(0.18)  
0.6376218...

colour.red_log_film_to_linear(value, black_offset=0.009955040995908344, **kwargs)¶

Defines the REDLogFilm to linear conversion function.

Parameters:	value (numeric or array_like) – REDLogFilm value. black_offset (numeric or array_like) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> red_log_film_to_linear(0.63762184598817484)  
0.1...

colour.linear_to_viper_log(value, **kwargs)¶

Defines the linear to ViperLog conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	ViperLog value.
Return type:	numeric or ndarray

Examples

>>> linear_to_viper_log(0.18)  
0.6360080...

colour.viper_log_to_linear(value, **kwargs)¶

Defines the ViperLog to linear conversion function.

Parameters:	value (numeric or array_like) – ViperLog value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> viper_log_to_linear(0.63600806701041346)  
0.1799999...

colour.linear_to_pivoted_log(value, log_reference=445, linear_reference=0.18, negative_gamma=0.6, density_per_code_value=0.002)¶

Defines the linear to Josh Pines style pivoted log conversion function.

Parameters:	value (numeric or array_like) – Linear value. log_reference (numeric or array_like) – Log reference. linear_reference (numeric or array_like) – Linear reference. negative_gamma (numeric or array_like) – Negative gamma. density_per_code_value (numeric or array_like) – Density per code value.
Returns:	Josh Pines style pivoted log value.
Return type:	numeric or ndarray

Examples

>>> linear_to_pivoted_log(0.18)  
0.4349951...

colour.pivoted_log_to_linear(value, log_reference=445, linear_reference=0.18, negative_gamma=0.6, density_per_code_value=0.002)¶

Defines the Josh Pines style pivoted log to linear conversion function.

Parameters:	value (numeric or array_like) – Josh Pines style pivoted log value. log_reference (numeric or array_like) – Log reference. linear_reference (numeric or array_like) – Linear reference. negative_gamma (numeric or array_like) – Negative gamma. density_per_code_value (numeric or array_like) – Density per code value.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> pivoted_log_to_linear(0.43499511241446726)  
0.1...

colour.linear_to_c_log(value, **kwargs)¶

Defines the linear to Canon Log conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Canon Log value.
Return type:	numeric or ndarray

References

[2]	Thorpe, L. (2012). CANON-LOG TRANSFER CHARACTERISTIC. Retrieved from http://downloads.canon.com/CDLC/Canon-Log_Transfer_Characteristic_6-20-2012.pdf

Examples

>>> linear_to_c_log(0.20) * 100  
32.7953896...

colour.c_log_to_linear(value, **kwargs)¶

Defines the Canon Log to linear conversion function. [2]_

Parameters:	value (numeric or array_like) – Canon Log value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> c_log_to_linear(32.795389693580908 / 100)  
0.19999999...

colour.linear_to_aces_cc(value, **kwargs)¶

Defines the linear to ACEScc conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	ACEScc value.
Return type:	numeric or ndarray

Examples

>>> linear_to_aces_cc(0.18)  
array(0.4135884...)

colour.aces_cc_to_linear(value, **kwargs)¶

Defines the ACEScc to linear conversion function.

Parameters:	value (numeric or array_like) – ACEScc value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> aces_cc_to_linear(0.41358840249244228)  
array(0.1800000...)

colour.linear_to_alexa_log_c(value, **kwargs)¶

Defines the linear to ALEXA Log C conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	ALEXA Log C value.
Return type:	numeric or ndarray

Examples

>>> linear_to_alexa_log_c(0.18)  
array(0.3910068...)

colour.alexa_log_c_to_linear(value, **kwargs)¶

Defines the ALEXA Log C to linear conversion function.

Parameters:	value (numeric or array_like) – ALEXA Log C value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> alexa_log_c_to_linear(0.39100683203408376)  
array(0.1800000...)

colour.linear_to_s_log(value, **kwargs)¶

Defines the linear to S-Log conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	S-Log value.
Return type:	numeric or ndarray

Examples

>>> linear_to_s_log(0.18)  
0.3599878...

colour.linear_to_dci_p3_log(value, **kwargs)¶

Defines the linear to DCI-P3 conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	DCI-P3 value.
Return type:	numeric or ndarray

Examples

>>> linear_to_dci_p3_log(0.18)  
461.9922059...

colour.dci_p3_log_to_linear(value, **kwargs)¶

Defines the DCI-P3 to linear conversion function.

Parameters:	value (numeric or array_like) – DCI-P3 value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> dci_p3_log_to_linear(461.99220597484737)  
0.1800000...

colour.s_log_to_linear(value, **kwargs)¶

Defines the S-Log to linear conversion function.

Parameters:	value (numeric or array_like) – S-Log value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> s_log_to_linear(0.35998784642215442)  
0.1...

colour.linear_to_s_log2(value, **kwargs)¶

Defines the linear to S-Log2 conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	S-Log2 value.
Return type:	numeric or ndarray

Examples

>>> linear_to_s_log2(0.18)  
0.3849708...

colour.s_log2_to_linear(value, **kwargs)¶

Defines the S-Log2 to linear conversion function.

Parameters:	value (numeric or array_like) – S-Log2 value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> s_log2_to_linear(0.38497081592867027)  
0.1...

colour.linear_to_s_log3(value, **kwargs)¶

Defines the linear to S-Log3 conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	S-Log3 value.
Return type:	numeric or ndarray

Examples

>>> linear_to_s_log3(0.18)  
array(0.4105571...)

colour.s_log3_to_linear(value, **kwargs)¶

Defines the S-Log3 to linear conversion function.

Parameters:	value (numeric or array_like) – S-Log3 value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> s_log3_to_linear(0.41055718475073316)  
array(0.1...)

colour.linear_to_v_log(value, **kwargs)¶

Defines the linear to V-Log conversion function.

Parameters:	value (numeric or array_like) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	V-Log value.
Return type:	numeric or ndarray

Examples

>>> linear_to_v_log(0.18)  
array(0.4233114...)

colour.v_log_to_linear(value, **kwargs)¶

Defines the V-Log to linear conversion function.

Parameters:	value (numeric or array_like) – V-Log value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric or ndarray

Examples

>>> v_log_to_linear(0.42331144876013616)  
array(0.1...)

colour.XYZ_to_RGB(XYZ, illuminant_XYZ, illuminant_RGB, XYZ_to_RGB_matrix, chromatic_adaptation_transform=u'CAT02', transfer_function=None)¶

Converts from CIE XYZ tristimulus values to given RGB colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values illuminant_XYZ (array_like) – CIE XYZ tristimulus values illuminant xy chromaticity coordinates. illuminant_RGB (array_like) – RGB colourspace illuminant xy chromaticity coordinates. XYZ_to_RGB_matrix (array_like) – Normalised primary matrix. chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform. transfer_function (object, optional) – Transfer function.
Returns:	RGB colourspace array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].
• Input illuminant_XYZ xy chromaticity coordinates are in domain [0, 1].
• Input illuminant_RGB xy chromaticity coordinates are in domain [0, 1].
• Output RGB colourspace array is in domain [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> illuminant_XYZ = np.array([0.34567, 0.35850])
>>> illuminant_RGB = np.array([0.31271, 0.32902])
>>> chromatic_adaptation_transform = 'Bradford'
>>> XYZ_to_RGB_matrix = np.array([
...     [3.24100326, -1.53739899, -0.49861587],
...     [-0.96922426, 1.87592999, 0.04155422],
...     [0.05563942, -0.20401120, 1.05714897]])
>>> XYZ_to_RGB(
...     XYZ,
...     illuminant_XYZ,
...     illuminant_RGB,
...     XYZ_to_RGB_matrix,
...     chromatic_adaptation_transform)  
array([ 0.0110360...,  0.1273446...,  0.1163103...])

colour.RGB_to_XYZ(RGB, illuminant_RGB, illuminant_XYZ, RGB_to_XYZ_matrix, chromatic_adaptation_transform=u'CAT02', inverse_transfer_function=None)¶

Converts from given RGB colourspace to CIE XYZ tristimulus values.

Parameters:	RGB (array_like) – RGB colourspace array. illuminant_RGB (array_like) – RGB colourspace illuminant chromaticity coordinates. illuminant_XYZ (array_like) – CIE XYZ tristimulus values illuminant chromaticity coordinates. RGB_to_XYZ_matrix (array_like) – Normalised primary matrix. chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform. inverse_transfer_function (object, optional) – Inverse transfer function.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input RGB colourspace array is in domain [0, 1].
• Input illuminant_RGB xy chromaticity coordinates are in domain [0, 1].
• Input illuminant_XYZ xy chromaticity coordinates are in domain [0, 1].
• Output CIE XYZ tristimulus values are in domain [0, 1].

Examples

>>> RGB = np.array([0.01103604, 0.12734466, 0.11631037])
>>> illuminant_RGB = np.array([0.31271, 0.32902])
>>> illuminant_XYZ = np.array([0.34567, 0.35850])
>>> chromatic_adaptation_transform = 'Bradford'
>>> RGB_to_XYZ_matrix = np.array([
...     [0.41238656, 0.35759149, 0.18045049],
...     [0.21263682, 0.71518298, 0.07218020],
...     [0.01933062, 0.11919716, 0.95037259]])
>>> RGB_to_XYZ(
...     RGB,
...     illuminant_RGB,
...     illuminant_XYZ,
...     RGB_to_XYZ_matrix,
...     chromatic_adaptation_transform)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.RGB_to_RGB(RGB, input_colourspace, output_colourspace, chromatic_adaptation_transform=u'CAT02')¶

Converts from given input RGB colourspace to output RGB colourspace using given chromatic adaptation method.

Parameters:

RGB (array_like) – RGB colourspace array. input_colourspace (RGB_Colourspace) – RGB input colourspace. output_colourspace (RGB_Colourspace) – RGB output colourspace. chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform. ndarray – RGB colourspace array.

Notes

• RGB colourspace arrays are in domain [0, 1].

Examples

>>> from colour import sRGB_COLOURSPACE, PROPHOTO_RGB_COLOURSPACE
>>> RGB = np.array([0.01103604, 0.12734466, 0.11631037])
>>> RGB_to_RGB(
...     RGB,
...     sRGB_COLOURSPACE,
...     PROPHOTO_RGB_COLOURSPACE)  
array([ 0.0643338...,  0.1157362...,  0.1157614...])

colour.XYZ_to_sRGB(XYZ, illuminant=(0.31271, 0.32902), chromatic_adaptation_transform=u'CAT02', transfer_function=True)¶

Converts from CIE XYZ tristimulus values to sRGB colourspace.

Parameters:	XYZ (array_like) – CIE XYZ tristimulus values. illuminant (array_like, optional) – Source illuminant chromaticity coordinates. chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform. transfer_function (bool, optional) – Apply sRGB transfer function.
Returns:	sRGB colour array.
Return type:	ndarray

Notes

• Input CIE XYZ tristimulus values are in domain [0, 1].

Examples

>>> import numpy as np
>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_to_sRGB(XYZ)  
array([ 0.1750135...,  0.3881879...,  0.3216195...])

colour.sRGB_to_XYZ(RGB, illuminant=(0.31271, 0.32902), chromatic_adaptation_method=u'CAT02', inverse_transfer_function=True)¶

Converts from sRGB colourspace to CIE XYZ tristimulus values.

Parameters:	RGB (array_like) – sRGB colourspace array. illuminant (array_like, optional) – Source illuminant chromaticity coordinates. chromatic_adaptation_method (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation method. inverse_transfer_function (bool, optional) – Apply sRGB inverse transfer function.
Returns:	CIE XYZ tristimulus values.
Return type:	ndarray

Notes

• Input RGB colourspace array is in domain [0, 1].

Examples

>>> import numpy as np
>>> RGB = np.array([0.17501358, 0.38818795, 0.32161955])
>>> sRGB_to_XYZ(RGB)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.spectral_to_aces_relative_exposure_values(spd, illuminant=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2adc373cdbd0>)¶

Converts given spectral power distribution to ACES2065-1 colourspace relative exposure values.

Parameters:	spd (SpectralPowerDistribution) – Spectral power distribution. illuminant (SpectralPowerDistribution, optional) – Illuminant spectral power distribution.
Returns:	ACES2065-1 colourspace relative exposure values array.
Return type:	ndarray, (3,)

Notes

• Output ACES2065-1 colourspace relative exposure values array is in domain [0, 1].

See also

colour.colorimetry.tristimulus.spectral_to_XYZ()

References

Examples

>>> from colour import COLOURCHECKERS_SPDS
>>> spd = COLOURCHECKERS_SPDS['ColorChecker N Ohta']['dark skin']
>>> spectral_to_aces_relative_exposure_values(spd)  
array([ 0.1187697...,  0.0870866...,  0.0589442...])

colour.corresponding_chromaticities_prediction_CIE1994(experiment=1, **kwargs)¶

Returns the corresponding chromaticities prediction for CIE 1994 chromatic adaptation model.

Parameters:	experiment (integer, optional) – {1, 2, 3, 4, 6, 8, 9, 11, 12} Breneman (1987) experiment number. **kwargs (**) – Keywords arguments.
Returns:	Corresponding chromaticities prediction.
Return type:	tuple

Examples

>>> from pprint import pprint
>>> pr = corresponding_chromaticities_prediction_CIE1994(2)
>>> pr = [(p.uvp_m, p.uvp_p) for p in pr]
>>> pprint(pr)  
[((0.207, 0.486), (0.21339093279517196, 0.49397945742298016)),
 ((0.449, 0.511), (0.4450345313098153, 0.5120939085633327)),
 ((0.263, 0.505), (0.26932620724691858, 0.50832124608390727)),
 ((0.322, 0.545), (0.33085939370840811, 0.54439408389253441)),
 ((0.316, 0.537), (0.3225195584183046, 0.53778269440789594)),
 ((0.265, 0.553), (0.2709737181087471, 0.5513666373694861)),
 ((0.221, 0.538), (0.22807869730753863, 0.53515923458385406)),
 ((0.135, 0.532), (0.14394366662060523, 0.53035769204585748)),
 ((0.145, 0.472), (0.15007438031976222, 0.48428958620888679)),
 ((0.163, 0.331), (0.15599555781959967, 0.37723798698131394)),
 ((0.176, 0.431), (0.18063180902005657, 0.45184759430042898)),
 ((0.244, 0.349), (0.24544456656434688, 0.40180048388092021))]

colour.corresponding_chromaticities_prediction_CMCCAT2000(experiment=1, **kwargs)¶

Returns the corresponding chromaticities prediction for CMCCAT2000 chromatic adaptation model.

Parameters:	experiment (integer, optional) – {1, 2, 3, 4, 6, 8, 9, 11, 12} Breneman (1987) experiment number. **kwargs (**) – Keywords arguments.
Returns:	Corresponding chromaticities prediction.
Return type:	tuple

Examples

>>> from pprint import pprint
>>> pr = corresponding_chromaticities_prediction_CMCCAT2000(2)
>>> pr = [(p.uvp_m, p.uvp_p) for p in pr]
>>> pprint(pr)  
[((0.207, 0.486), (0.20832101929657834, 0.47271680534693694)),
 ((0.449, 0.511), (0.44592707020371486, 0.50777351504395707)),
 ((0.263, 0.505), (0.26402624712986333, 0.4955361681706304)),
 ((0.322, 0.545), (0.33168840090358015, 0.54315801981008516)),
 ((0.316, 0.537), (0.32226245779851387, 0.53576245377085929)),
 ((0.265, 0.553), (0.27107058097430181, 0.5501997842556422)),
 ((0.221, 0.538), (0.22618269421847523, 0.52947407170848704)),
 ((0.135, 0.532), (0.14396930475660724, 0.51909841743126817)),
 ((0.145, 0.472), (0.14948357434418671, 0.45567605010224305)),
 ((0.163, 0.331), (0.15631720730028753, 0.31641514460738623)),
 ((0.176, 0.431), (0.17631993066748047, 0.41275893424542082)),
 ((0.244, 0.349), (0.22876382018951744, 0.3499324084859976))]

colour.corresponding_chromaticities_prediction_Fairchild1990(experiment=1, **kwargs)¶

Returns the corresponding chromaticities prediction for Fairchild (1990) chromatic adaptation model.

Parameters:	experiment (integer, optional) – {1, 2, 3, 4, 6, 8, 9, 11, 12} Breneman (1987) experiment number. **kwargs (**) – Keywords arguments.
Returns:	Corresponding chromaticities prediction.
Return type:	tuple

Examples

>>> from pprint import pprint
>>> pr = corresponding_chromaticities_prediction_Fairchild1990(2)
>>> pr = [(p.uvp_m, p.uvp_p) for p in pr]
>>> pprint(pr)  
[((0.207, 0.486), (0.2089528677990308, 0.47240345174230519)),
 ((0.449, 0.511), (0.43756528098582792, 0.51210303139041924)),
 ((0.263, 0.505), (0.26213623665658092, 0.49725385033264224)),
 ((0.322, 0.545), (0.3235312762825191, 0.54756652922585702)),
 ((0.316, 0.537), (0.3151390992740366, 0.53983332031574016)),
 ((0.265, 0.553), (0.26347459238415272, 0.55443357809543037)),
 ((0.221, 0.538), (0.22115956537655593, 0.53244703908294599)),
 ((0.135, 0.532), (0.13969494108553854, 0.52072342107668024)),
 ((0.145, 0.472), (0.1512288710743511, 0.45330415352961834)),
 ((0.163, 0.331), (0.17156913711903982, 0.30262647410866889)),
 ((0.176, 0.431), (0.18257922398137369, 0.40778921192793854)),
 ((0.244, 0.349), (0.24189049501108895, 0.34134012046930529))]

colour.corresponding_chromaticities_prediction_VonKries(experiment=1, transform=u'CAT02')¶

Returns the corresponding chromaticities prediction for Von Kries chromatic adaptation model using given transform.

Parameters:	experiment (integer, optional) – {1, 2, 3, 4, 6, 8, 9, 11, 12} Breneman (1987) experiment number. transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:	Corresponding chromaticities prediction.
Return type:	tuple

Examples

>>> from pprint import pprint
>>> pr = corresponding_chromaticities_prediction_VonKries(2, 'Bradford')
>>> pr = [(p.uvp_m, p.uvp_p) for p in pr]
>>> pprint(pr)  
[((0.207, 0.486), (0.20820148430638033, 0.47229226819364528)),
 ((0.449, 0.511), (0.44891022948064191, 0.50716028901449561)),
 ((0.263, 0.505), (0.26435459360846608, 0.49596314494922683)),
 ((0.322, 0.545), (0.33487309037107632, 0.54712207251983425)),
 ((0.316, 0.537), (0.32487581236911361, 0.53905899356457776)),
 ((0.265, 0.553), (0.27331050571632376, 0.55550280647813977)),
 ((0.221, 0.538), (0.22714800102072819, 0.53313179748041983)),
 ((0.135, 0.532), (0.14427303768336433, 0.52268044497913713)),
 ((0.145, 0.472), (0.14987451889726533, 0.45507852741116867)),
 ((0.163, 0.331), (0.15649757464732098, 0.31487959772753954)),
 ((0.176, 0.431), (0.17605936460371163, 0.41037722722471409)),
 ((0.244, 0.349), (0.22598059059292835, 0.34652914678030416))]

colour.scattering_cross_section(wavelength, CO2_concentration=300, temperature=288.15, avogadro_constant=6.02214179e+23, n_s=<function air_refraction_index_Bodhaine1999 at 0x2adc48ef56e0>, F_air=<function F_air_Bodhaine1999 at 0x2adc48ef59b0>)¶

Returns the scattering cross section per molecule \(\sigma\) of dry air as function of wavelength \(\lambda\) in centimeters (cm) using given \(CO_2\) concentration in parts per million (ppm) and temperature \(T[K]\) in kelvin degrees following Van de Hulst (1957) method.

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in centimeters (cm). CO2_concentration (numeric or array_like, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric or array_like, optional) – Air temperature \(T[K]\) in kelvin degrees. avogadro_constant (numeric or array_like, optional) – Avogadro‘s number (molecules \(mol^{-1}\)). n_s (object) – Air refraction index \(n_s\) computation method. F_air (object) – \((6+3_p)/(6-7_p)\), the depolarisation term \(F(air)\) or King Factor computation method.
Returns:	Scattering cross section per molecule \(\sigma\) of dry air.
Return type:	numeric or ndarray

Warning

Unlike most objects of colour.phenomenons.rayleigh module, colour.phenomenons.rayleigh.scattering_cross_section() expects wavelength \(\lambda\) to be expressed in centimeters (cm).

Examples

>>> scattering_cross_section(555 * 10e-8)  
4.6613309...e-27

colour.rayleigh_optical_depth(wavelength, CO2_concentration=300, temperature=288.15, pressure=101325, latitude=0, altitude=0, avogadro_constant=6.02214179e+23, n_s=<function air_refraction_index_Bodhaine1999 at 0x2adc48ef56e0>, F_air=<function F_air_Bodhaine1999 at 0x2adc48ef59b0>)¶

Returns the rayleigh optical depth \(T_r(\lambda)\) as function of wavelength \(\lambda\) in centimeters (cm).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in centimeters (cm). CO2_concentration (numeric or array_like, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric or array_like, optional) – Air temperature \(T[K]\) in kelvin degrees. pressure (numeric or array_like) – Surface pressure \(P\) of the measurement site. latitude (numeric or array_like, optional) – Latitude of the site in degrees. altitude (numeric or array_like, optional) – Altitude of the site in meters. avogadro_constant (numeric or array_like, optional) – Avogadro‘s number (molecules \(mol^{-1}\)). n_s (object) – Air refraction index \(n_s\) computation method. F_air (object) – \((6+3_p)/(6-7_p)\), the depolarisation term \(F(air)\) or King Factor computation method.
Returns:	Rayleigh optical depth \(T_r(\lambda)\).
Return type:	numeric or ndarray

Warning

Unlike most objects of colour.phenomenons.rayleigh module, colour.phenomenons.rayleigh.rayleigh_optical_depth() expects wavelength \(\lambda\) to be expressed in centimeters (cm).

Examples

>>> rayleigh_optical_depth(555 * 10e-8)  
0.1004070...

colour.rayleigh_scattering(wavelength, CO2_concentration=300, temperature=288.15, pressure=101325, latitude=0, altitude=0, avogadro_constant=6.02214179e+23, n_s=<function air_refraction_index_Bodhaine1999 at 0x2adc48ef56e0>, F_air=<function F_air_Bodhaine1999 at 0x2adc48ef59b0>)¶

Returns the rayleigh optical depth \(T_r(\lambda)\) as function of wavelength \(\lambda\) in centimeters (cm).

Parameters:	wavelength (numeric or array_like) – Wavelength \(\lambda\) in centimeters (cm). CO2_concentration (numeric or array_like, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric or array_like, optional) – Air temperature \(T[K]\) in kelvin degrees. pressure (numeric or array_like) – Surface pressure \(P\) of the measurement site. latitude (numeric or array_like, optional) – Latitude of the site in degrees. altitude (numeric or array_like, optional) – Altitude of the site in meters. avogadro_constant (numeric or array_like, optional) – Avogadro‘s number (molecules \(mol^{-1}\)). n_s (object) – Air refraction index \(n_s\) computation method. F_air (object) – \((6+3_p)/(6-7_p)\), the depolarisation term \(F(air)\) or King Factor computation method.
Returns:	Rayleigh optical depth \(T_r(\lambda)\).
Return type:	numeric or ndarray

Warning

Unlike most objects of colour.phenomenons.rayleigh module, colour.phenomenons.rayleigh.rayleigh_optical_depth() expects wavelength \(\lambda\) to be expressed in centimeters (cm).

Examples

>>> rayleigh_optical_depth(555 * 10e-8)  
0.1004070...

colour.rayleigh_scattering_spd(shape=SpectralShape(360, 830, 1), CO2_concentration=300, temperature=288.15, pressure=101325, latitude=0, altitude=0, avogadro_constant=6.02214179e+23, n_s=<function air_refraction_index_Bodhaine1999 at 0x2adc48ef56e0>, F_air=<function F_air_Bodhaine1999 at 0x2adc48ef59b0>)¶

Returns the rayleigh spectral power distribution for given spectral shape.

Parameters:	shape (SpectralShape, optional) – Spectral shape used to create the rayleigh scattering spectral power distribution. CO2_concentration (numeric or array_like, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric or array_like, optional) – Air temperature \(T[K]\) in kelvin degrees. pressure (numeric or array_like) – Surface pressure \(P\) of the measurement site. latitude (numeric or array_like, optional) – Latitude of the site in degrees. altitude (numeric or array_like, optional) – Altitude of the site in meters. avogadro_constant (numeric or array_like, optional) – Avogadro‘s number (molecules \(mol^{-1}\)). n_s (object) – Air refraction index \(n_s\) computation method. F_air (object) – \((6+3_p)/(6-7_p)\), the depolarisation term \(F(air)\) or King Factor computation method.
Returns:	Rayleigh optical depth spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> rayleigh_scattering_spd()  
<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x...>

colour.munsell_value(Y, method=u'ASTM D1535-08')¶

Returns the Munsell value \(V\) of given luminance \(Y\) using given method.

Parameters:	Y (numeric or array_like) – luminance \(Y\). method (unicode, optional) – {‘ASTM D1535-08’, ‘Priest 1920’, ‘Munsell 1933’, ‘Moon 1943’, ‘Saunderson 1944’, ‘Ladd 1955’, ‘McCamy 1987’} Computation method.
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

• Input Y is in domain [0, 100].
• Output V is in domain [0, 10].

Examples

>>> munsell_value(10.08)  
3.7344764...
>>> munsell_value(10.08, method='Priest 1920')  
3.1749015...
>>> munsell_value(10.08, method='Munsell 1933')  
3.7918355...
>>> munsell_value(10.08, method='Moon 1943')  
3.7462971...
>>> munsell_value(10.08, method='Saunderson 1944')  
3.6865080...
>>> munsell_value(10.08, method='Ladd 1955')  
3.6952862...
>>> munsell_value(10.08, method='McCamy 1987')  
array(3.7347235...)

colour.munsell_value_Priest1920(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using ⁠⁠⁠⁠⁠Priest, Gibson and MacNicholas (1920) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

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)  
3.1749015...

colour.munsell_value_Munsell1933(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using ⁠Munsell, Sloan and Godlove (1933) method. [3]_

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

• Input Y is in domain [0, 100].
• Output V is in domain [0, 10].

Examples

>>> munsell_value_Munsell1933(10.08)  
3.7918355...

colour.munsell_value_Moon1943(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using Moon and Spencer (1943) method. [3]_

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

• Input Y is in domain [0, 100].
• Output V is in domain [0, 10].

Examples

>>> munsell_value_Moon1943(10.08)  
3.7462971...

colour.munsell_value_Saunderson1944(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using Saunderson and Milner (1944) method. [3]_

Parameters:	Y (numeric) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric

Notes

• Input Y is in domain [0, 100].
• Output V is in domain [0, 10].

Examples

>>> munsell_value_Saunderson1944(10.08)  
3.6865080...

colour.munsell_value_Ladd1955(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using Ladd and Pinney (1955) method. [3]_

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

• Input Y is in domain [0, 100].
• Output V is in domain [0, 10].

Examples

>>> munsell_value_Ladd1955(10.08)  
3.6952862...

colour.munsell_value_McCamy1987(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using McCamy (1987) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

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)  
array(3.7347235...)

colour.munsell_value_ASTMD153508(Y)¶

Returns the Munsell value \(V\) of given luminance \(Y\) using a reverse lookup table from ASTM D1535-08e1 (2008) method.

Parameters:	Y (numeric or array_like) – luminance \(Y\)
Returns:	Munsell value \(V\).
Return type:	numeric or ndarray

Notes

• Input Y is in domain [0, 100].
• Output V is in domain [0, 10].

Examples

>>> munsell_value_ASTMD153508(10.1488096782)  
3.7462971...

colour.munsell_colour_to_xyY(munsell_colour)¶

Converts given Munsell colour to CIE xyY colourspace.

Parameters:	munsell_colour (unicode) – Munsell colour.
Returns:	CIE xyY colourspace array.
Return type:	ndarray, (3,)

Notes

• Output CIE xyY colourspace array is in domain [0, 1].

Examples

>>> munsell_colour_to_xyY('4.2YR 8.1/5.3')  
array([ 0.3873694...,  0.3575165...,  0.59362   ])
>>> munsell_colour_to_xyY('N8.9')  
array([ 0.31006  ,  0.31616  ,  0.746134...])

colour.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 array. hue_decimals (int) – Hue formatting decimals. value_decimals (int) – Value formatting decimals. chroma_decimals (int) – Chroma formatting decimals.
Returns:	Munsell colour.
Return type:	unicode

Notes

• Input CIE xyY colourspace array is in domain [0, 1].

Examples

>>> xyY = np.array([0.38736945, 0.35751656, 0.59362000])
>>> # Doctests skip for Python 2.x compatibility.
>>> xyY_to_munsell_colour(xyY)  
'4.2YR 8.1/5.3'

class colour.CRI_Specification¶

Bases: colour.quality.cri.CRI_Specification

Defines the colour rendering index colour quality specification.

Parameters:	Q_a (numeric) – Colour rendering index \(Q_a\). Q_as (dict) – Individual colour rendering indexes data for each sample. colorimetry_data (tuple) – Colorimetry data for the test and reference computations.

colour.colour_rendering_index(spd_test, additional_data=False)¶

Returns the colour rendering index \(Q_a\) of given spectral power distribution.

Parameters:	spd_test (SpectralPowerDistribution) – Test spectral power distribution. additional_data (bool, optional) – Output additional data.
Returns:	Colour rendering index.
Return type:	numeric or CRI_Specification

Examples

>>> from colour import ILLUMINANTS_RELATIVE_SPDS
>>> spd = ILLUMINANTS_RELATIVE_SPDS.get('F2')
>>> colour_rendering_index(spd)  
64.1507331...

class colour.CQS_Specification¶

Bases: colour.quality.cqs.CQS_Specification

Defines the CQS colour quality specification.

Parameters:

Q_a (numeric) – Colour quality scale \(Q_a\). Q_f (numeric) – Colour fidelity scale \(Q_f\) intended to evaluate the fidelity of object colour appearances (compared to the reference illuminant of the same correlated colour temperature and illuminance). Q_p (numeric) – Colour preference scale \(Q_p\) similar to colour quality scale \(Q_a\) but placing additional weight on preference of object colour appearance. This metric is based on the notion that increases in chroma are generally preferred and should be rewarded. Q_g (numeric) – Gamut area scale \(Q_g\) representing the relative gamut formed by the (\(a^*\), \(b^*\)) coordinates of the 15 samples illuminated by the test light source in the CIE LAB object colourspace. Q_d (numeric) – Relative gamut area scale \(Q_d\). Q_as (dict) – Individual CQS data for each sample. colorimetry_data (tuple) – Colorimetry data for the test and reference computations.

colour.colour_quality_scale(spd_test, additional_data=False)¶

Returns the colour quality scale of given spectral power distribution.

Parameters:	spd_test (SpectralPowerDistribution) – Test spectral power distribution. additional_data (bool, optional) – Output additional data.
Returns:	Color quality scale.
Return type:	numeric or CQS_Specification

Examples

>>> from colour import ILLUMINANTS_RELATIVE_SPDS
>>> spd = ILLUMINANTS_RELATIVE_SPDS.get('F2')
>>> colour_quality_scale(spd)  
64.6860580...

colour.RGB_to_spectral_Smits1999(RGB)¶

Recovers the spectral power distribution of given RGB colourspace array using Smits (1999) method.

Parameters:	RGB (array_like, (3,)) – RGB colourspace array.
Returns:	Recovered spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

>>> RGB = np.array([0.02144962, 0.13154603, 0.09287601])
>>> RGB_to_spectral_Smits1999(RGB)  
<...SpectralPowerDistribution object at 0x...>

colour.CCT_to_uv(CCT, D_uv=0, method=u'Ohno 2013', **kwargs)¶

Returns the CIE UCS colourspace uv chromaticity coordinates from given correlated colour temperature \(T_{cp}\) and \(\Delta_{uv}\) using given method.

Parameters:	CCT (numeric) – Correlated colour temperature \(T_{cp}\). D_uv (numeric) – \(\Delta_{uv}\). method (unicode, optional) – 2013’, ‘Robertson 1968’} ({‘Ohno) – Computation method. **kwargs (**) – Keywords arguments.
Returns:	CIE UCS colourspace uv chromaticity coordinates.
Return type:	ndarray
Raises:	ValueError – If the computation method is not defined.

Examples

>>> from colour import STANDARD_OBSERVERS_CMFS
>>> cmfs = 'CIE 1931 2 Degree Standard Observer'
>>> cmfs = STANDARD_OBSERVERS_CMFS.get(cmfs)
>>> CCT = 6507.4342201047066
>>> D_uv = 0.003223690901512735
>>> CCT_to_uv(CCT, D_uv, cmfs=cmfs)  
array([ 0.1978003...,  0.3122005...])

colour.CCT_to_uv_Ohno2013(CCT, D_uv=0, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2adc373cd290>)¶

Returns the CIE UCS colourspace uv chromaticity coordinates from given correlated colour temperature \(T_{cp}\), \(\Delta_{uv}\) and colour matching functions using Ohno (2013) method.

Parameters:	CCT (numeric) – Correlated colour temperature \(T_{cp}\). D_uv (numeric, optional) – \(\Delta_{uv}\). cmfs (XYZ_ColourMatchingFunctions, optional) – Standard observer colour matching functions.
Returns:	CIE UCS colourspace uv chromaticity coordinates.
Return type:	ndarray

References

[4]	Ohno, Y. (2014). Practical Use and Calculation of CCT and Duv. LEUKOS, 10(1), 47–55. doi:10.1080/15502724.2014.839020

Examples

>>> from colour import STANDARD_OBSERVERS_CMFS
>>> cmfs = 'CIE 1931 2 Degree Standard Observer'
>>> cmfs = STANDARD_OBSERVERS_CMFS.get(cmfs)
>>> CCT = 6507.4342201047066
>>> D_uv = 0.003223690901512735
>>> CCT_to_uv_Ohno2013(CCT, D_uv, cmfs)  
array([ 0.1978003...,  0.3122005...])

colour.CCT_to_uv_Robertson1968(CCT, D_uv=0)¶

Returns the CIE UCS colourspace uv chromaticity coordinates from given correlated colour temperature \(T_{cp}\) and \(\Delta_{uv}\) using Roberston (1968) method.

Parameters:	CCT (numeric) – Correlated colour temperature \(T_{cp}\). D_uv (numeric) – \(\Delta_{uv}\).
Returns:	CIE UCS colourspace uv chromaticity coordinates.
Return type:	ndarray

References

[7]	Wyszecki, G., & Stiles, W. S. (2000). DISTRIBUTION TEMPERATURE, COLOR TEMPERATURE, AND CORRELATED COLOR TEMPERATURE. In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 224–229). Wiley. ISBN:978-0471399186

[8]	Adobe Systems. (2013). Adobe DNG Software Development Kit (SDK) - 1.3.0.0 - dng_sdk_1_3/dng_sdk/source/dng_temperature.cpp:: dng_temperature::xy_coord. Retrieved from https://www.adobe.com/support/downloads/dng/dng_sdk.html

Examples

>>> CCT = 6500.0081378199056
>>> D_uv = 0.0083333312442250979
>>> CCT_to_uv_Robertson1968(CCT, D_uv)  
array([ 0.1937413...,  0.3152210...])

colour.uv_to_CCT(uv, method=u'Ohno 2013', **kwargs)¶

Returns the correlated colour temperature \(T_{cp}\) and \(\Delta_{uv}\) from given CIE UCS colourspace uv chromaticity coordinates using given method.

Parameters:	uv (array_like) – CIE UCS colourspace uv chromaticity coordinates. method (unicode, optional) – {‘Ohno 2013’, ‘Robertson 1968’} Computation method. **kwargs (**) – Keywords arguments.
Returns:	Correlated colour temperature \(T_{cp}\), \(\Delta_{uv}\).
Return type:	ndarray
Raises:	ValueError – If the computation method is not defined.

Examples

>>> from colour import STANDARD_OBSERVERS_CMFS
>>> cmfs = 'CIE 1931 2 Degree Standard Observer'
>>> cmfs = STANDARD_OBSERVERS_CMFS.get(cmfs)
>>> uv = np.array([0.1978, 0.3122])
>>> uv_to_CCT(uv, cmfs=cmfs)  
array([  6.5075470...e+03,   3.2236908...e-03])

colour.uv_to_CCT_Ohno2013(uv, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2adc373cd290>, start=1000, end=100000, count=10, iterations=6)¶

Returns the correlated colour temperature \(T_{cp}\) and \(\Delta_{uv}\) from given CIE UCS colourspace uv chromaticity coordinates, colour matching functions and temperature range using Ohno (2013) method.

The iterations parameter defines the calculations precision: The higher its value, the more planckian tables will be generated through cascade expansion in order to converge to the exact solution.

Parameters:	uv (array_like) – CIE UCS colourspace uv chromaticity coordinates. cmfs (XYZ_ColourMatchingFunctions, optional) – Standard observer colour matching functions. start (numeric, optional) – Temperature range start in kelvins. end (numeric, optional) – Temperature range end in kelvins. count (int, optional) – Temperatures count in the planckian tables. iterations (int, optional) – Number of planckian tables to generate.
Returns:	Correlated colour temperature \(T_{cp}\), \(\Delta_{uv}\).
Return type:	ndarray

References

[3]	Ohno, Y. (2014). Practical Use and Calculation of CCT and Duv. LEUKOS, 10(1), 47–55. doi:10.1080/15502724.2014.839020

Examples

>>> from colour import STANDARD_OBSERVERS_CMFS
>>> cmfs = 'CIE 1931 2 Degree Standard Observer'
>>> cmfs = STANDARD_OBSERVERS_CMFS.get(cmfs)
>>> uv = np.array([0.1978, 0.3122])
>>> uv_to_CCT_Ohno2013(uv, cmfs)  
array([  6.5075470...e+03,   3.2236908...e-03])

colour.uv_to_CCT_Robertson1968(uv)¶

Returns the correlated colour temperature \(T_{cp}\) and \(\Delta_{uv}\) from given CIE UCS colourspace uv chromaticity coordinates using Roberston (1968) method.

Parameters:	uv (array_like) – CIE UCS colourspace uv chromaticity coordinates.
Returns:	Correlated colour temperature \(T_{cp}\), \(\Delta_{uv}\).
Return type:	ndarray

References

[5]	Wyszecki, G., & Stiles, W. S. (2000). DISTRIBUTION TEMPERATURE, COLOR TEMPERATURE, AND CORRELATED COLOR TEMPERATURE. In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 224–229). Wiley. ISBN:978-0471399186

[6]	Adobe Systems. (2013). Adobe DNG Software Development Kit (SDK) - 1.3.0.0 - dng_sdk_1_3/dng_sdk/source/dng_temperature.cpp:: dng_temperature::Set_xy_coord. Retrieved from https://www.adobe.com/support/downloads/dng/dng_sdk.html

Examples

>>> uv = np.array([0.19374137599822966, 0.31522104394059397])
>>> uv_to_CCT_Robertson1968(uv)  
array([  6.5000162...e+03,   8.3333289...e-03])

colour.CCT_to_xy(CCT, method=u'Kang 2002')¶

Returns the CIE XYZ tristimulus values xy chromaticity coordinates from given correlated colour temperature \(T_{cp}\) using given method.

Parameters:	CCT (numeric or array_like) – Correlated colour temperature \(T_{cp}\). method (unicode, optional) – {‘Kang 2002’, ‘CIE Illuminant D Series’} Computation method.
Returns:	xy chromaticity coordinates.
Return type:	ndarray

colour.CCT_to_xy_Kang2002(CCT)¶

Returns the CIE XYZ tristimulus values xy chromaticity coordinates from given correlated colour temperature \(T_{cp}\) using Kang et al. (2002) method.

Parameters:	CCT (numeric or array_like) – Correlated colour temperature \(T_{cp}\).
Returns:	xy chromaticity coordinates.
Return type:	ndarray
Raises:	ValueError – If the correlated colour temperature is not in appropriate domain.

References

[11]	Kang, B., Moon, O., Hong, C., Lee, H., Cho, B., & Kim, Y. (2002). Design of advanced color: Temperature control system for HDTV applications. Journal of the Korean …, 41(6), 865–871. Retrieved from http://cat.inist.fr/?aModele=afficheN&cpsidt=14448733

Examples

>>> CCT_to_xy_Kang2002(6504.38938305)  
array([ 0.313426...,  0.3235959...])

colour.CCT_to_xy_CIE_D(CCT)¶

Converts from the correlated colour temperature \(T_{cp}\) of a CIE Illuminant D Series to the chromaticity of that CIE Illuminant D Series illuminant.

Parameters:	CCT (numeric or array_like) – Correlated colour temperature \(T_{cp}\).
Returns:	xy chromaticity coordinates.
Return type:	ndarray
Raises:	ValueError – If the correlated colour temperature is not in appropriate domain.

References

[12]	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

Examples

>>> CCT_to_xy_CIE_D(6504.38938305)  
array([ 0.3127077...,  0.3291128...])

colour.xy_to_CCT(xy, method=u'McCamy 1992', **kwargs)¶

Returns the correlated colour temperature \(T_{cp}\) from given CIE XYZ tristimulus values xy chromaticity coordinates using given method.

Parameters:	xy (array_like) – xy chromaticity coordinates. method (unicode, optional) – {‘McCamy 1992’, ‘Hernandez 1999’} Computation method. **kwargs (**) – Keywords arguments.
Returns:	Correlated colour temperature \(T_{cp}\).
Return type:	numeric or ndarray

colour.xy_to_CCT_McCamy1992(xy)¶

Returns the correlated colour temperature \(T_{cp}\) from given CIE XYZ tristimulus values xy chromaticity coordinates using McCamy (1992) method.

Parameters:	xy (array_like) – xy chromaticity coordinates.
Returns:	Correlated colour temperature \(T_{cp}\).
Return type:	numeric or ndarray

References

[9]	Wikipedia. (n.d.). Approximation. Retrieved June 28, 2014, from http://en.wikipedia.org/wiki/Color_temperature#Approximation

Examples

>>> xy = np.array([0.31271, 0.32902])
>>> xy_to_CCT_McCamy1992(xy)  
6504.3893830...

colour.xy_to_CCT_Hernandez1999(xy)¶

Returns the correlated colour temperature \(T_{cp}\) from given CIE XYZ tristimulus values xy chromaticity coordinates using Hernandez-Andres, Lee and Romero (1999) method.

Parameters:	xy (array_like) – xy chromaticity coordinates.
Returns:	Correlated colour temperature \(T_{cp}\).
Return type:	numeric

References

[10]	Hernández-Andrés, J., Lee, R. L., & Romero, J. (1999). Calculating correlated color temperatures across the entire gamut of daylight and skylight chromaticities. Applied Optics, 38(27), 5703–5709. doi:10.1364/AO.38.005703

Examples

>>> xy = np.array([0.31271, 0.32902])
>>> xy_to_CCT_Hernandez1999(xy)  
array(6500.0421533...)

colour.is_within_macadam_limits(xyY, illuminant, tolerance=None)¶

Returns if given CIE xyY colourspace array is within MacAdam limits of given illuminant.

Parameters:	xyY (array_like) – CIE xyY colourspace array. illuminant (unicode) – Illuminant. tolerance (numeric, optional) – Tolerance allowed in the inside-triangle check.
Returns:	Is within MacAdam limits.
Return type:	bool

Notes

• Input CIE xyY colourspace array is in domain [0, 1].
• This definition requires scipy to be installed.

Examples

>>> is_within_macadam_limits(np.array([0.3205, 0.4131, 0.51]), 'A')
array(True, dtype=bool)
>>> a = np.array([[0.3205, 0.4131, 0.51],
...               [0.0005, 0.0031, 0.001]])
>>> is_within_macadam_limits(a, 'A')
array([ True, False], dtype=bool)

colour.RGB_colourspace_limits(colourspace, illuminant=(0.34567, 0.3585))¶

Computes given RGB colourspace volume limits in Lab colourspace.

Parameters:	colourspace (RGB_Colourspace) – RGB colourspace to compute the volume of. illuminant_Lab (array_like, optional) – Lab colourspace illuminant chromaticity coordinates.
Returns:	RGB colourspace volume limits.
Return type:	ndarray

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> RGB_colourspace_limits(sRGB)    
array([[   0...        ,  100...        ],
       [ -79.2263741...,   94.6657491...],
       [-114.7846271...,   96.7135199...]])

RGB_colourspace_volume_MonteCarlo(colourspace, samples=10000000.0, limits=array([[ 0, 100],

[-150, 150],

[-150, 150]]), illuminant_Lab=(0.34567, 0.3585), chromatic_adaptation_method=u'CAT02', random_generator=<function random_triplet_generator at 0x2adc441cdc80>, random_state=None, processes=None)

Performs given RGB colourspace volume computation using Monte Carlo method and multiprocessing.

Parameters:	colourspace (RGB_Colourspace) – RGB colourspace to compute the volume of. samples (numeric, optional) – Samples count. limits (array_like, optional) – Lab colourspace volume. illuminant_Lab (array_like, optional) – Lab colourspace illuminant chromaticity coordinates. chromatic_adaptation_method (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild, ‘CMCCAT97’, ‘CMCCAT2000’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation method. random_generator (generator, optional) – Random triplet generator providing the random samples within the Lab colourspace volume. random_state (RandomState, optional) – Mersenne Twister pseudo-random number generator to use in the random number generator. processes (integer, optional) – Processes count, default to multiprocessing.cpu_count() definition.
Returns:	RGB colourspace volume.
Return type:	float

Notes

The doctest is assuming that np.random.RandomState() definition will return the same sequence no matter which OS or Python version is used. There is however no formal promise about the prng sequence reproducibility of either Python or *Numpy implementations: Laurent. (2012). Reproducibility of python pseudo-random numbers across systems and versions? Retrieved January 20, 2015, from http://stackoverflow.com/questions/8786084/reproducibility-of-python-pseudo-random-numbers-across-systems-and-versions

Examples

>>> from colour import sRGB_COLOURSPACE as sRGB
>>> prng = np.random.RandomState(2)
>>> processes = 1
>>> RGB_colourspace_volume_MonteCarlo(sRGB, 10e3, random_state=prng, processes=processes)    
859...