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')¶

Returns the chromatic adaptation matrix from test viewing conditions CIE XYZ_w colourspace matrix to reference viewing conditions CIE XYZ_wr colourspace matrix.

Parameters:	XYZ_w (array_like, (3,)) – Test viewing condition CIE XYZ colourspace matrix. XYZ_wr (array_like, (3,)) – Reference viewing condition CIE XYZ colourspace matrix. 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, (3, 3)
Raises:	KeyError – If chromatic adaptation method is not defined.

Examples

>>> XYZ_w = np.array([1.09846607, 1., 0.3558228])
>>> XYZ_wr = np.array([0.95042855, 1., 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., 0.3558228])
>>> XYZ_wr = np.array([0.95042855, 1., 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 CIE XYZ colourspace stimulus from test viewing conditions CIE XYZ_w colourspace matrix to reference viewing conditions CIE XYZ_wr colourspace matrix. [6]_

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace stimulus to adapt. XYZ_w (array_like, (3,)) – Test viewing condition CIE XYZ colourspace whitepoint matrix. XYZ_wr (array_like, (3,)) – Reference viewing condition CIE XYZ colourspace whitepoint matrix. 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 colourspace matrix of the stimulus corresponding colour.
Return type:	ndarray, (3,)

Examples

>>> XYZ = np.array([0.07049534, 0.1008, 0.09558313])
>>> XYZ_w = np.array([1.09846607, 1., 0.3558228])
>>> XYZ_wr = np.array([0.95042855, 1., 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.1008, 0.09558313])
>>> XYZ_w = np.array([1.09846607, 1., 0.3558228])
>>> XYZ_wr = np.array([0.95042855, 1., 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 CIE XYZ_1 colourspace stimulus from test viewing conditions to reference viewing conditions using Fairchild (1990) chromatic adaptation model.

Parameters:	XYZ_1 (array_like, (3,)) – CIE XYZ_1 colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_n (array_like, (3,)) – Test viewing condition CIE XYZ_n colourspace whitepoint matrix. XYZ_r (array_like, (3,)) – Reference viewing condition CIE XYZ_r colourspace whitepoint matrix. Y_n (numeric) – 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 colourspace test stimulus.
Return type:	ndarray, (3,)

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ_1, CIE XYZ_n and CIE XYZ_r colourspace matrices are in domain [0, 100].
• Output CIE XYZ_2 colourspace matrix is 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) – \(F\) surround condition.

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

Adapts given CIE XYZ colourspace stimulus from test viewing conditions CIE XYZ_w colourspace matrix to reference viewing conditions CIE XYZ_wr colourspace matrix using CMCCAT2000 forward chromatic adaptation model.

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

Warning

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

Notes

• Input CIE XYZ, CIE XYZ_w and CIE XYZ_wr colourspace matrices are in domain [0, 100].
• Output CIE XYZ_c colourspace matrix is 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 CIE XYZ colourspace matrix of the stimulus corresponding colour from reference viewing conditions CIE XYZ_wr colourspace matrix to test viewing conditions CIE XYZ_w colourspace matrix using CMCCAT2000 reverse chromatic adaptation model.

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

Warning

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

Notes

• Input CIE XYZ_c, CIE XYZ_w and CIE XYZ_wr colourspace matrices are in domain [0, 100].
• Output CIE XYZ colourspace matrix is 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 CIE XYZ colourspace matrix using given viewing conditions.

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

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix to adapt. XYZ_w (array_like, (3,)) – Source viewing condition CIE XYZ colourspace whitepoint matrix. XYZ_wr (array_like, (3,)) – Target viewing condition CIE XYZ colourspace whitepoint matrix. L_A1 (numeric) – Luminance of test adapting field \(L_{A1}\) in \(cd/m^2\). L_A2 (numeric) – 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 CIE XYZ colourspace matrix.
Return type:	ndarray, (3,)

Warning

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

Notes

• Input CIE XYZ, CIE XYZ_w and CIE XYZ_wr colourspace matrices are in domain [0, 100].
• Output CIE XYZ colourspace matrix is 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.0683396, 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 CIE XYZ_1 colourspace stimulus from test viewing conditions to reference viewing conditions using CIE 1994 chromatic adaptation model.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. xy_o1 (array_like, (2,)) – Chromaticity coordinates \(x_{o1}\) and \(y_{o1}\) of test illuminant and background. xy_o2 (array_like, (2,)) – 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 colourspace test stimulus.
Return type:	ndarray, (3,)

Warning

The input domain of that definition is non standard!

Notes

• Input CIE XYZ_1 colourspace matrix is in domain [0, 100].
• Output CIE XYZ_2 colourspace matrix is in domain [0, 100].

Examples

>>> XYZ_1 = np.array([28.0, 21.26, 5.27])
>>> xy_o1 = (0.4476, 0.4074)
>>> xy_o2 = (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.steps(distribution)¶

Returns the steps of given distribution.

Parameters:	distribution (array_like) – Distribution to retrieve the steps.
Returns:	Distribution steps.
Return type:	tuple

Examples

Uniformly spaced variable:

>>> y = np.array([1, 2, 3, 4, 5])
>>> steps(y)
(1,)

Non-uniformly spaced variable:

>>> y = np.array([1, 2, 3, 4, 8])
>>> steps(y)
(1, 4)

colour.closest(y, x)¶

Returns closest \(y\) variable element to reference \(x\) variable.

Parameters:	y (array_like) – Variable to search for the closest element. x (numeric) – Reference variable.
Returns:	Closest \(y\) variable element.
Return type:	numeric

Examples

>>> y = np.array([24.31357115, 63.62396289, 55.71528816, 62.70988028, 46.84480573, 25.40026416])  
>>> closest(y, 63)
62.70988028

colour.as_array(x, shape=None, data_type=<type 'numpy.float64'>)¶

Converts given \(x\) variable to ndarray.

Parameters:	x (object) – Variable to convert. shape (tuple, optional) – ndarray shape. data_type (dtype, optional) – ndarray data type.
Returns:	\(x\) variable converted to ndarray.
Return type:	ndarray

Examples

>>> as_array(1)
array([ 1.])

colour.is_uniform(distribution)¶

Returns if given distribution is uniform.

Parameters:	distribution (array_like) – Distribution to check for uniformity.
Returns:	Is distribution uniform.
Return type:	bool

Examples

Uniformly spaced variable:

>>> y = np.array([1, 2, 3, 4, 5])
>>> is_uniform(y)
True

Non-uniformly spaced variable:

>>> y = np.array([1, 2, 3.1415, 4, 5])
>>> is_uniform(y)
False

colour.is_iterable(x)¶

Returns if given \(x\) variable is iterable.

Parameters:	x (object) – Variable to check the iterability.
Returns:	\(x\) variable iterability.
Return type:	bool

Examples

>>> is_iterable([1, 2, 3])
True
>>> is_iterable(1)
False

colour.is_numeric(x)¶

Returns if given \(x\) variable is a number.

Parameters:	x (object) – Variable to check.
Returns:	Is \(x\) variable a number.
Return type:	bool

See also

is_integer()

Examples

>>> is_numeric(1)
True
>>> is_numeric((1,))
False

colour.is_integer(x)¶

Returns if given \(x\) variable is an integer under given threshold.

Parameters:	x (object) – Variable to check.
Returns:	Is \(x\) variable an integer.
Return type:	bool

Notes

• The determination threshold is defined by the colour.algebra.common.INTEGER_THRESHOLD attribute.

See also

is_numeric()

Examples

>>> is_integer(1)
True
>>> is_integer(1.01)
False

colour.normalise(x, factor=1, clip=True)¶

Normalises given array_like \(x\) variable values and optionally clip them between.

Parameters:	x (array_like) – \(x\) variable to normalise. factor (numeric, optional) – Normalization factor clip (bool, optional) – Clip values between in domain [0, ‘factor’].
Returns:	Normalised \(x\) variable.
Return type:	ndarray

Examples

>>> x = np.array([0.48224885, 0.31651974, 0.22070513])
>>> normalise(x)  
array([ 1.        ,  0.6563411...,  0.4576581...])

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, 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 0x2b436c405930>)

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(list(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...])]

colour.linear_regression(y, x=None, additional_statistics=False)¶

Performs the statistics computation about the ideal trend line from given data using the least-squares method.

The equation of the line is \(y=b+mx\) or \(y=b+m1x1+m1x2+...+mnxn\) where the dependent variable \(y\) value is a function of the independent variable \(x\) values.

Parameters:	y (array_like) – Dependent and already known \(y\) variable values used to curve fit an ideal trend line. x (array_like, optional) – Independent \(x\) variable(s) values corresponding with \(y\) variable. additional_statistics (ndarray) – Output additional regression statistics, by default only the \(b\) variable and \(m\) coefficients are returned.
Returns:	Regression statistics.
Return type:	ndarray, ({{mn, mn-1, ..., b}, {sum_of_squares_residual}})
Raises:	ValueError – If \(y\) and \(x\) variables have incompatible dimensions.

References

[2]	Wikipedia. (n.d.). Simple linear regression. Retrieved May 24, 2014, from http://en.wikipedia.org/wiki/Simple_linear_regression

Examples

Linear regression with the dependent and already known \(y\) variable:

>>> y = np.array([1, 2, 1, 3, 2, 3, 3, 4, 4, 3])
>>> linear_regression(y)  
array([ 0.2909090...,  1.        ])

Linear regression with the dependent \(y\) variable and independent \(x\) variable:

>>> x1 = np.array([40, 45, 38, 50, 48, 55, 53, 55, 58, 40])
>>> linear_regression(y, x1)  
array([ 0.1225194..., -3.3054357...])

Multiple linear regression with the dependent \(y\) variable and multiple independent \(x_i\) variables:

>>> x2 = np.array([25, 20, 30, 30, 28, 30, 34, 36, 32, 34])
>>> linear_regression(y, tuple(zip(x1, x2)))  
array([ 0.0998002...,  0.0876257..., -4.8303807...])

Multiple linear regression with additional statistics:

>>> linear_regression(y, tuple(zip(x1, x2)), True)  
(array([ 0.0998002...,  0.0876257..., -4.8303807...]), array([ 2.1376249...]))

class colour.Hunt_InductionFactors¶

Bases: colour.appearance.hunt.Hunt_InductionFactors

Hunt colour appearance model induction factors.

Parameters:

N_c (numeric) – Chromatic surround induction factor \(N_c\). N_b (numeric) – Brightness surround induction factor \(N_b\). N_cb (numeric, 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, 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) – Correlate of Lightness \(J\). C (numeric) – Correlate of chroma \(C_94\). h (numeric) – Hue angle \(h_S\) in degrees. s (numeric) – Correlate of saturation \(s\). Q (numeric) – Correlate of brightness \(Q\). M (numeric) – Correlate of colourfulness \(M_94\). H (numeric) – Hue \(h\) quadrature \(H\). HC (numeric) – 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, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_w (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. XYZ_b (array_like, (3,)) – CIE XYZ colourspace matrix of background in domain [0, 100]. L_A (numeric) – Adapting field luminance \(L_A\) in \(cd/m^2\). surround (Hunt_InductionFactors, optional) – Surround viewing conditions induction factors. L_AS (numeric, optional) – Scotopic luminance \(L_{AS}\) of the illuminant, approximated if not specified. CCT_w (numeric, optional) – Correlated color temperature \(T_{cp}\): of the illuminant, needed to approximate \(L_{AS}\). XYZ_p (array_like, (3,), optional) – CIE XYZ colourspace matrix of proximal field in domain [0, 100], assumed to be equal to background if not specified. p (numeric, 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, optional) – Scotopic response \(S\) to the stimulus, approximated using tristimulus values \(Y\) of the stimulus if not specified. S_w (numeric, 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 colourspace matrix is in domain [0, 100].
• Input CIE XYZ_b colourspace matrix is in domain [0, 100].
• Input CIE XYZ_w colourspace matrix is in domain [0, 100].
• Input CIE XYZ_p colourspace matrix is 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) – Hue angle \(H\) in degrees. C (numeric) – 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) – Correlate of brightness \(Br\). A_1 (numeric) – First stage \(A_1\) response. T_1 (numeric) – First stage \(T_1\) response. D_1 (numeric) – First stage \(D_1\) response. A_2 (numeric) – Second stage \(A_2\) response. T_2 (numeric) – Second stage \(A_2\) response. D_2 (numeric) – 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, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_0 (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_0 (numeric) – Absolute adapting field luminance in \(cd/m^2\). k_1 (numeric) – Application specific weight \(k_1\). k_2 (numeric) – Application specific weight \(k_2\). sigma (numeric, 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 colourspace matrix is in domain [0, 100].
• Input CIE XYZ_0 colourspace matrix is 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) – Maximum degree of adaptation \(F\). c (numeric) – Exponential non linearity \(c\). N_c (numeric) – 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) – Correlate of Lightness \(J\). C (numeric) – Correlate of chroma \(C\). h (numeric) – Hue angle \(h\) in degrees. s (numeric) – Correlate of saturation \(s\). Q (numeric) – Correlate of brightness \(Q\). M (numeric) – Correlate of colourfulness \(M\). H (numeric) – Hue \(h\) quadrature \(H\). HC (numeric) – 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 colourspace matrix.

This is the forward implementation.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_w (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. L_A (numeric) – Adapting field luminance \(L_A\) in \(cd/m^2\). Y_b (numeric) – 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 colourspace matrix is in domain [0, 100].
• Input CIE XYZ_w colourspace matrix is 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=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 colourspace matrix.

This is the reverse implementation.

Parameters:	CIECAM02_Specification (CIECAM02_Specification) – CIECAM02 specification. XYZ_w (array_like) – CIE XYZ colourspace matrix of reference white. L_A (numeric) – Adapting field luminance \(L_A\) in \(cd/m^2\). Y_b (numeric) – 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 colourspace matrix.
Return type:	ndarray

Warning

The output domain of that definition is non standard!

Notes

• Input CIE XYZ_w colourspace matrix is in domain [0, 100].
• Output CIE XYZ colourspace matrix is in domain [0, 100].

Examples

>>> J = 41.731091132513917
>>> C = 0.1047077571711053
>>> h = 219.0484326582719
>>> 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) – Correlate of Lightness \(L_L\). C (numeric) – Correlate of chroma \(Ch_L\). h (numeric) – Hue angle \(h_L\) in degrees. s (numeric) – Correlate of saturation \(s_L\). M (numeric) – Correlate of colourfulness \(C_L\). HC (numeric) – Hue \(h\) composition \(H^C\). a (numeric) – Opponent signal \(A_L\). b (numeric) – 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, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_0 (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_b (numeric) – Luminance factor of the background in \(cd/m^2\). L (numeric) – 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 colourspace matrix is in domain [0, 100].
• Input CIE XYZ_0 colourspace matrix is in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20, 21.78])
>>> XYZ_0 = np.array([95.05, 100, 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.0, s=0.0002395..., M=0.0190185..., HC=None, a=-3.4936555..., 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) – Correlate of achromatic Lightness \(L_p^\star\). C (numeric) – Correlate of chroma \(C\). h (numeric) – Hue angle \(\theta\) in degrees. s (numeric) – Correlate of saturation \(S\). Q (numeric) – Correlate of brightness \(B_r\). M (numeric) – Correlate of colourfulness \(M\). H (numeric) – Hue \(h\) quadrature \(H\). HC (numeric) – Hue \(h\) composition \(H_C\). Lstar_N (numeric) – 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, (3,)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_n (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_o (numeric) – Luminance factor \(Y_o\) of achromatic background as percentage in domain [0.18, 1.0] E_o (numeric) – Illuminance \(E_o\) of the viewing field in lux. E_or (numeric) – Normalising illuminance \(E_{or}\) in lux usually in domain [1000, 3000] n (numeric, 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 colourspace matrix is in domain [0, 100].
• Input CIE XYZ_n colourspace matrix is in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20, 21.78])
>>> XYZ_n = np.array([95.05, 100, 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) – Correlate of Lightness \(L^R\). C (numeric) – Correlate of achromatic chroma \(C^R\). h (numeric) – Hue angle \(h^R\) in degrees. s (numeric) – Correlate of saturation \(s^R\). HC (numeric) – Hue \(h\) composition \(H^C\). a (numeric) – Red–green chromatic response \(a^R\). b (numeric) – 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, (3, n)) – CIE XYZ colourspace matrix of test sample / stimulus in domain [0, 100]. XYZ_n (array_like, (3,)) – CIE XYZ colourspace matrix of reference white in domain [0, 100]. Y_n (numeric) – Absolute adapting luminance in \(cd/m^2\). sigma (numeric, optional) – Relative luminance of the surround, see RLAB_VIEWING_CONDITIONS for reference. D (numeric, 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 colourspace matrix is in domain [0, 100].
• Input CIE XYZ_n colourspace matrix is in domain [0, 100].

Examples

>>> XYZ = np.array([19.01, 20, 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 \(m2\) colour matrix to \(m1\) colour matrix. The resulting colour matrix is calculated using multiple linear regression.

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

Parameters:	m1 (array_like, (3, n)) – Reference matrix the matrix \(m2\) will be colour fitted against. m2 (array_like, (3, n)) – Matrix to fit.
Returns:	Fitting colour matrix.
Return type:	ndarray, (3, 3)

Examples

>>> m1 = np.array([
...     [0.1722481, 0.0917066, 0.06416938],
...     [0.49189645, 0.2780205, 0.21923399],
...     [0.10999751, 0.18658946, 0.29938611],
...     [0.1166612, 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.4454523, 0.06028681],
...     [0.61632937, 0.32323906, 0.02437089],
...     [0.03016472, 0.06153243, 0.29014596],
...     [0.11103655, 0.30553067, 0.08149137],
...     [0.4116219, 0.05816656, 0.04845934],
...     [0.73339206, 0.53075188, 0.02475212],
...     [0.47347718, 0.08834792, 0.30310315],
...     [0., 0.25187016, 0.3506245],
...     [0.76809639, 0.7848624, 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.3911314, 0.25943419, 0.21266708],
...     [0.12824821, 0.1846357, 0.31508023],
...     [0.12028974, 0.13455659, 0.074084],
...     [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.122334, 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.2578786, 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.1042468, 0.10384975],
...     [0.04742204, 0.04772203, 0.04914226]])
>>> first_order_colour_fit(m1, m2)  
array([[ 1.4043128...,  0.0112806..., -0.2029710...],
       [-0.0998911...,  1.5012214..., -0.1856479...],
       [ 0.2248369..., -0.0767236...,  1.0496013...]])

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

Bases: object

Defines the base object for spectral power distribution shape.

Parameters:	start (numeric, optional) – Wavelengths \(\lambda_{i}\): range start in nm. end (numeric, optional) – Wavelengths \(\lambda_{i}\): range end in nm. steps (numeric, optional) – Wavelengths \(\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 the given wavelength \(\lambda\).

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

Notes

• Reimplements the object.__contains__() method.

Examples

>>> 0.5 in SpectralShape(0, 10, 0.1)
True
>>> 0.51 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 wavelengths \(\lambda_n\) count.

Returns:	Spectral shape wavelengths \(\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 the given wavelength \(\lambda\).

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

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

__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) – Wavelength \(\lambda\) to retrieve the value.
Returns:	Wavelength \(\lambda\) value.
Return type:	numeric

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]  
49.67...

__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) – Wavelength \(\lambda\) to set. value (numeric) – Value for wavelength \(\lambda\).

Notes

• Reimplements the object.__setitem__() method.

Examples

>>> spd = SpectralPowerDistribution('Spd', {})
>>> spd[510] = 49.6700
>>> spd.values
array([ 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]  
49.67...
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[700]  
88.1...

get(wavelength, default=None)

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

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

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)  
49.67...
>>> spd.get(511)  
None

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]  
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]  
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...>
>>> # Doctests ellipsis for Python 2.x compatibility.
>>> spd[515]  
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 the given wavelength \(\lambda\).

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

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

__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) – Wavelength \(\lambda\) to retrieve the values.
Returns:	Wavelength \(\lambda\) values.
Return type:	ndarray, (3,)

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])

__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) – Wavelength \(\lambda\) to set. value (array_like) – Value for wavelength \(\lambda\).

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] = (49.6700, 49.6700, 49.6700)
>>> tri_spd.values
array([[ 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=None)

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

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

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[510]
array([ 49.67,  90.56,  12.43])
>>> tri_spd.get(511)  
None

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] = (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] = (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]
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]
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]
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(*args, **kwds)¶

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) – Wavelength in meters. temperature (numeric) – Temperature \(T[K]\) in kelvin degrees. 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:	Radiance in watts per steradian per square metre.
Return type:	numeric

Examples

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

colour.planck_law(*args, **kwds)¶

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) – Wavelength in meters. temperature (numeric) – Temperature \(T[K]\) in kelvin degrees. 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:	Radiance in watts per steradian per square metre.
Return type:	numeric

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

>>> D_illuminant_relative_spd((0.34567, 0.35850))  
<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 0x2b437a9a0f50>, scotopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2b437a9a9150>)¶

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 0x2b437a9a0f50>, scotopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2b437a9a9150>)¶

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

Parameters:	wavelength (numeric) – 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
Raises:	KeyError – If wavelength \(\lambda\) is not available in either luminous efficiency function.

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) – luminance \(Y\). method (unicode, optional) – {‘CIE 1976’, ‘Glasser 1958’, ‘Wyszecki 1963’}, Computation method. **kwargs (**) – Keywords arguments.
Returns:	Lightness \(L^*\).
Return type:	numeric

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)  
37.9856290...
>>> lightness(10.08, Y_n=100)  
37.9856290...
>>> lightness(10.08, Y_n=95)  
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) – luminance \(Y\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other Lightness computation objects.
Returns:	Lightness \(L\).
Return type:	numeric

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) – luminance \(Y\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other Lightness computation objects.
Returns:	Lightness \(W\).
Return type:	numeric

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) – luminance \(Y\). Y_n (numeric, optional) – White reference luminance \(Y_n\).
Returns:	Lightness \(L^*\).
Return type:	numeric

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)  
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) – 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

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)  
10.0800000...
>>> luminance(37.9856290977, Y_n=100)  
10.0800000...
>>> luminance(37.9856290977, Y_n=95)  
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) – Munsell value \(V\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other luminance computation objects.
Returns:	luminance \(R_Y\).
Return type:	numeric

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) – Munsell value \(V\). **kwargs (**, optional) – Unused parameter provided for signature compatibility with other luminance computation objects.
Returns:	luminance \(Y\).
Return type:	numeric

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) – Lightness \(L^*\) Yn (numeric) – White reference luminance \(Y_n\).
Returns:	luminance \(Y\).
Return type:	numeric

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)  
10.0800000...
>>> luminance_1976(37.9856290977, 95)  
9.5760000...

colour.luminous_flux(spd, lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x2b437a9a0f50>, 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 0x2b437a9a0f50>)¶

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) – Wavelength \(\lambda\) in nm.
Returns:	Stockman & Sharpe 10 Degree Cone Fundamentals spectral tristimulus values.
Return type:	ndarray, (3,)
Raises:	KeyError – If wavelength \(\lambda\) is not available in the colour matching functions.

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) – Wavelength \(\lambda\) in nm.
Returns:	CIE 1931 2 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray, (3,)
Raises:	KeyError – If wavelength \(\lambda\) is not available in the colour matching functions.

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) – Wavelength \(\lambda\) in nm.
Returns:	CIE 1964 10 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray, (3,)
Raises:	KeyError – If wavelength \(\lambda\) is not available in the colour matching functions.

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) – Wavelength \(\lambda\) in nm.
Returns:	CIE 2012 2 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray, (3,)
Raises:	KeyError – If wavelength \(\lambda\) is not available in the colour matching functions.

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) – Wavelength \(\lambda\) in nm.
Returns:	CIE 2012 10 Degree Standard Observer spectral tristimulus values.
Return type:	ndarray, (3,)
Raises:	KeyError – If wavelength \(\lambda\) is not available in the colour matching functions.

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 0x2b436d3b77d0>, illuminant=None)¶

Converts given spectral power distribution to CIE XYZ colourspace 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 colourspace matrix.
Return type:	ndarray, (3,)

Warning

The output domain of that definition is non standard!

Notes

• Output CIE XYZ colourspace matrix is 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(*args, **kwds)¶

Converts given wavelength \(\lambda\) to CIE XYZ colourspace 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) – Wavelength \(\lambda\) in nm. cmfs (XYZ_ColourMatchingFunctions, optional) – Standard observer colour matching functions.
Returns:	CIE XYZ colourspace matrix.
Return type:	ndarray, (3,)
Raises:	ValueError – If wavelength \(\lambda\) is not in the colour matching functions domain.

Notes

• Output CIE XYZ colourspace matrix is 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

Examples

>>> xy = (0.3167, 0.3334)
>>> Y = 100
>>> xy_n = (0.3139, 0.3311)
>>> whiteness(xy=xy, Y=Y, xy_n=xy_n)  
(93.8500000..., -1.3049999...)
>>> XYZ = np.array([95., 100., 105.])
>>> XYZ_0 = np.array([94.80966767, 100., 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 colourspace matrix using Berger (1959) method. [2]_

Parameters:	XYZ (array_like) – CIE XYZ colourspace matrix of sample. XYZ_0 (array_like) – CIE XYZ colourspace matrix of reference white.
Returns:	Whiteness \(WI\).
Return type:	numeric

Notes

• Input CIE XYZ and CIE XYZ_0 colourspace matrices 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., 100., 105.])
>>> XYZ_0 = np.array([94.80966767, 100., 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 colourspace matrix using Taube (1960) method. [2]_

Parameters:	XYZ (array_like) – CIE XYZ colourspace matrix of sample. XYZ_0 (array_like) – CIE XYZ colourspace matrix of reference white.
Returns:	Whiteness \(WI\).
Return type:	numeric

Notes

• Input CIE XYZ and CIE XYZ_0 colourspace matrices 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., 100., 105.])
>>> XYZ_0 = np.array([94.80966767, 100., 107.30513595])
>>> whiteness_Taube1960(XYZ, XYZ_0)  
91.4071738...

colour.whiteness_Stensby1968(Lab)¶

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

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

Notes

• Input CIE Lab colourspace matrix 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

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

colour.whiteness_ASTM313(XYZ)¶

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

Parameters:	XYZ (array_like) – CIE XYZ colourspace matrix of sample.
Returns:	Whiteness \(WI\).
Return type:	numeric

Notes

• Input CIE XYZ colourspace matrix is in domain [0, 100].

Warning

The input domain of that definition is non standard!

Examples

>>> XYZ = np.array([95., 100., 105.])
>>> 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 (tuple) – Chromaticity coordinates xy of sample. Y (numeric) – Tristimulus \(Y\) value of sample.
Returns:	Whiteness \(W\) and tint \(T\).
Return type:	tuple

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

>>> whiteness_Ganz1979((0.3167, 0.3334), 100.)  
(85.6003766..., 0.6789002...)

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 (tuple) – Chromaticity coordinates xy of sample. Y (numeric) – Tristimulus \(Y\) value of sample. xy_n (tuple) – 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:	tuple

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_n = (0.3139, 0.3311)
>>> whiteness_CIE2004((0.3167, 0.3334), 100., xy_n)  
(93.8500000..., -1.3049999...)

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

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

Parameters:	Lab1 (array_like, (3,)) – CIE Lab array_like colour 1. Lab2 (array_like, (3,)) – CIE Lab array_like colour 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

Examples

>>> Lab1 = np.array([100, 21.57210357, 272.2281935])
>>> Lab2 = np.array([100, 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 array_like colours using CIE 1976 recommendation.

Parameters:	Lab1 (array_like, (3,)) – CIE Lab array_like colour 1. Lab2 (array_like, (3,)) – CIE Lab array_like colour 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

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, 21.57210357, 272.2281935])
>>> Lab2 = np.array([100, 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 array_like colours using CIE 1994 recommendation.

Parameters:	Lab1 (array_like, (3,)) – CIE Lab array_like colour 1. Lab2 (array_like, (3,)) – CIE Lab array_like colour 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

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, 21.57210357, 272.2281935])
>>> Lab2 = np.array([100, 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 array_like colours using CIE 2000 recommendation.

Parameters:	Lab1 (array_like, (3,)) – CIE Lab array_like colour 1. Lab2 (array_like, (3,)) – CIE Lab array_like colour 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

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, 21.57210357, 272.2281935])
>>> Lab2 = np.array([100, 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 array_like colours 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, (3,)) – CIE Lab array_like colour 1. Lab2 (array_like, (3,)) – CIE Lab array_like colour 2. l (numeric, optional) – Lightness weighting factor. c (numeric, optional) – Chroma weighting factor.
Returns:	Colour difference \(\Delta E_{ab}\).
Return type:	numeric

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, 21.57210357, 272.2281935])
>>> Lab2 = np.array([100, 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'
>>> spd[501.7]  
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'
>>> spd[400]  
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_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(list(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 colourspace to CIE xyY colourspace and reference illuminant.

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

Notes

• Input CIE XYZ colourspace matrix is in domain [0, 1].
• Output CIE xyY colourspace matrix 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.1008, 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 colourspace.

Parameters:	xyY (array_like, (3,)) – CIE xyY colourspace matrix.
Returns:	CIE XYZ colourspace matrix.
Return type:	ndarray, (3,)

Notes

• Input CIE xyY colourspace matrix is in domain [0, 1].
• Output CIE XYZ colourspace matrix is 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.1008])
>>> xyY_to_XYZ(xyY)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])

colour.xy_to_XYZ(xy)¶

Returns the CIE XYZ colourspace matrix from given xy chromaticity coordinates.

Parameters:	xy (array_like) – xy chromaticity coordinates.
Returns:	CIE XYZ colourspace matrix.
Return type:	ndarray, (3,)

Notes

• Input xy chromaticity coordinates are in domain [0, 1].
• Output CIE XYZ colourspace matrix is in domain [0, 1].

Examples

>>> xy = (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 colourspace matrix.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates.
Returns:	xy chromaticity coordinates.
Return type:	tuple

Notes

• Input CIE XYZ colourspace matrix is in domain [0, 1].
• Output xy chromaticity coordinates are in domain [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.1008, 0.09558313])
>>> XYZ_to_xy(XYZ)  
(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 colourspace. XYZ_to_RGB_matrix (array_like, optional) – Transformation matrix from CIE XYZ colourspace 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 matrices.

Parameters:	primaries (array_like) – Primaries chromaticity coordinate matrix, (3, 2). 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 = (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.RGB_luminance_equation(primaries, whitepoint)¶

Returns the luminance equation from given primaries and whitepoint matrices.

Parameters:	primaries (array_like, (3, 2)) – Primaries chromaticity coordinate matrix. 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 = (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 matrices.

Parameters:	RGB (array_like, (3,)) – 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

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 = (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 colourspace to CIE Lab colourspace.

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

Notes

• Input CIE XYZ is 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.1008, 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 colourspace.

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

Notes

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

References

[3]	Lindbloom, B. (2008). Lab to XYZ. Retrieved February 24, 2014, from http://www.brucelindbloom.com/Eqn_Lab_to_XYZ.html

Examples

>>> Lab = np.array([37.9856291, -23.62302887, -4.41417036])
>>> Lab_to_XYZ(Lab)  
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, (3,)) – CIE Lab colourspace matrix.
Returns:	CIE LCHab colourspace matrix.
Return type:	ndarray, (3,)

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.9856291, -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, (3,)) – CIE LCHab colourspace matrix.
Returns:	CIE Lab colourspace matrix.
Return type:	ndarray, (3,)

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.9856291, 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 colourspace to CIE Luv colourspace.

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

Notes

• Input CIE XYZ colourspace matrix is 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.1008, 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 colourspace.

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

Notes

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

References

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

Examples

>>> Luv = np.array([37.9856291, -28.79229446, -1.3558195])
>>> 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 matrix.

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

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.9856291, -28.79229446, -1.3558195])
>>> Luv_to_uv(Luv)  
(0.1508530..., 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:	tuple

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 = (0.15085309882985695, 0.48532970854318019)
>>> Luv_uv_to_xy(uv)  
(0.2641477..., 0.3777000...)

colour.Luv_to_LCHuv(Luv)¶

Converts from CIE Luv colourspace to CIE LCHuv colourspace.

Parameters:	Luv (array_like, (3,)) – CIE Luv colourspace matrix.
Returns:	CIE LCHuv colourspace matrix.
Return type:	ndarray, (3,)

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.9856291, -28.79229446, -1.3558195])
>>> 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, (3,)) – CIE LCHuv colourspace matrix.
Returns:	CIE Luv colourspace matrix.
Return type:	ndarray, (3,)

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.9856291, 28.82419933, 182.69604747])
>>> LCHuv_to_Luv(LCHuv)  
array([ 37.9856291..., -28.7922944...,  -1.3558195...])

colour.XYZ_to_UCS(XYZ)¶

Converts from CIE XYZ colourspace to CIE UCS colourspace.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix.
Returns:	CIE UCS colourspace matrix.
Return type:	ndarray, (3,)

Notes

• Input CIE XYZ colourspace matrix is in domain [0, 1].
• Output CIE UCS colourspace matrix is in domain [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.1008, 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 colourspace.

Parameters:	UVW (array_like, (3,)) – CIE UCS colourspace matrix.
Returns:	CIE XYZ colourspace matrix.
Return type:	ndarray, (3,)

Notes

• Input CIE UCS colourspace matrix is in domain [0, 1].
• Output CIE XYZ colourspace matrix is in domain [0, 1].

Examples

>>> UVW = np.array([0.04699689, 0.1008, 0.1637439])
>>> 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 matrix.

Parameters:	UVW (array_like, (3,)) – CIE UCS colourspace matrix.
Returns:	uv chromaticity coordinates.
Return type:	tuple

Notes

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

Examples

>>> UCS = np.array([0.04699689, 0.1008, 0.1637439])
>>> UCS_to_uv(UCS)  
(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:	tuple

Notes

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

Examples

>>> uv = (0.15085308732766581, 0.3235531372954405)
>>> UCS_uv_to_xy(uv)  
(0.2641477..., 0.3777000...)

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

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

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

Notes

• Input CIE XYZ colourspace matrix is in domain [0, 100].
• Output CIE UVW colourspace matrix is in domain [0, 100].

Warning

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

Examples

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

colour.XYZ_to_IPT(XYZ)¶

Converts from CIE XYZ colourspace to IPT colourspace. [1]_

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix.
Returns:	IPT colourspace matrix.
Return type:	ndarray, (3,)

Notes

• Input CIE XYZ colourspace matrix 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 colourspace. [1]_

Parameters:	IPT (array_like, (3,)) – IPT colourspace matrix.
Returns:	CIE XYZ colourspace matrix.
Return type:	ndarray, (3,)

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

Parameters:	IPT (array_like, (3,)) – IPT colourspace matrix.
Returns:	Hue angle.
Return type:	numeric

Examples

>>> IPT_hue_angle(([0.96907232, 1, 1.12179215]))  
0.8427358...

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

Converts from linear to log using given method.

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

Examples

>>> linear_to_log(0.18)  
0.4573196...
>>> linear_to_log(0.18, method='ACEScc')  
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) – Value. method (unicode, optional) – {‘Cineon’, ‘Panalog’, ‘REDLog’, ‘ViperLog’, ‘PLog’, ‘C-Log’, ‘ACEScc’, ‘ALEXA Log C’, ‘DCI-P3’, ‘S-Log’, ‘S-Log2’, ‘S-Log3’}, Computation method. **kwargs (**) – Keywords arguments.
Returns:	Log value.
Return type:	numeric

Examples

>>> log_to_linear(0.45731961308541841)  
0.18...
>>> log_to_linear(0.41358840249244228, method='ACEScc')   
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) – Linear value. black_offset (numeric) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Cineon value.
Return type:	numeric

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) – Cineon value. black_offset (numeric) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric

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) – Linear value. black_offset (numeric) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Panalog value.
Return type:	numeric

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) – Panalog value. black_offset (numeric) – Black offset. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric

Examples

>>> panalog_to_linear(0.37457679138229816)  
0.1...

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

Defines the linear to REDLog conversion function.

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

Examples

>>> linear_to_red_log(0.18)  
0.6376218...

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

Defines the REDLog to linear conversion function.

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

Examples

>>> red_log_to_linear(0.63762184598817484)  
0.1...

colour.linear_to_viper_log(value, **kwargs)¶

Defines the linear to ViperLog conversion function.

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

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) – ViperLog value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric

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) – Linear value. log_reference (numeric) – Log reference. linear_reference (numeric) – Linear reference. negative_gamma (numeric) – Negative gamma. density_per_code_value (numeric) – Density per code value.
Returns:	Josh Pines style pivoted log value.
Return type:	numeric

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) – Josh Pines style pivoted log value. log_reference (numeric) – Log reference. linear_reference (numeric) – Linear reference. negative_gamma (numeric) – Negative gamma. density_per_code_value (numeric) – Density per code value.
Returns:	Linear value.
Return type:	numeric

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) – Linear value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Canon Log value.
Return type:	numeric

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) – Canon Log value. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other linear / log conversion objects.
Returns:	Linear value.
Return type:	numeric

Examples

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

colour.linear_to_aces_cc(x, **kwargs)¶

colour.aces_cc_to_linear(x, **kwargs)¶

colour.linear_to_alexa_log_c(x, **kwargs)¶

colour.alexa_log_c_to_linear(x, **kwargs)¶

colour.linear_to_s_log(x, **kwargs)¶

colour.linear_to_dci_p3_log(x, **kwargs)¶

colour.dci_p3_log_to_linear(x, **kwargs)¶

colour.s_log_to_linear(x, **kwargs)¶

colour.linear_to_s_log2(x, **kwargs)¶

colour.s_log2_to_linear(x, **kwargs)¶

colour.linear_to_s_log3(x, **kwargs)¶

colour.s_log3_to_linear(x, **kwargs)¶

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 colourspace to RGB colourspace using given CIE XYZ colourspace matrix, illuminants, chromatic adaptation method, normalised primary matrix and transfer function.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix. illuminant_XYZ (array_like) – CIE XYZ colourspace illuminant xy chromaticity coordinates. illuminant_RGB (array_like) – RGB colourspace illuminant xy chromaticity coordinates. XYZ_to_RGB_matrix (array_like, (3, 3)) – 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 matrix.
Return type:	ndarray, (3,)

Notes

• Input CIE XYZ colourspace matrix is 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 matrix is in domain [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.1008, 0.09558313])
>>> illuminant_XYZ = (0.34567, 0.35850)
>>> illuminant_RGB = (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.2040112, 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 RGB colourspace to CIE XYZ colourspace using given RGB colourspace matrix, illuminants, chromatic adaptation method, normalised primary matrix and transfer function.

Parameters:	RGB (array_like, (3,)) – RGB colourspace matrix. illuminant_RGB (array_like) – RGB colourspace illuminant chromaticity coordinates. illuminant_XYZ (array_like) – CIE XYZ colourspace illuminant chromaticity coordinates. RGB_to_XYZ_matrix (array_like, (3, 3)) – 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 colourspace matrix.
Return type:	ndarray, (3,)

Notes

• Input RGB colourspace matrix 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 colourspace matrix is in domain [0, 1].

Examples

>>> RGB = np.array([0.01103604, 0.12734466, 0.11631037])
>>> illuminant_RGB = (0.31271, 0.32902)
>>> illuminant_XYZ = (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.0721802],
...     [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, (3,)) – RGB colourspace matrix. 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. (3,) (ndarray,) – RGB colourspace matrix.

Notes

• RGB colourspace matrices 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 colourspace to sRGB colourspace.

Parameters:	XYZ (array_like, (3,)) – CIE XYZ colourspace matrix. 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 matrix.
Return type:	ndarray, (3,)

Notes

• Input CIE XYZ colourspace matrix is in domain [0, 1].

Examples

>>> import numpy as np
>>> XYZ = np.array([0.07049534, 0.1008, 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 colourspace.

Parameters:	RGB (array_like, (3,)) – sRGB colourspace matrix. 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 colour matrix.
Return type:	ndarray, (3,)

Notes

• Input RGB colourspace matrix 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 0x2b436d42a0d0>)¶

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 matrix.
Return type:	ndarray, (3,)

Notes

• Output ACES2065-1 colourspace relative exposure values matrix 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_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.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.scattering_cross_section(wavelength, CO2_concentration=300, temperature=288.15, avogadro_constant=6.02214179e+23, n_s=<function air_refraction_index_Bodhaine1999 at 0x2b436dc47140>, F_air=<function F_air_Bodhaine1999 at 0x2b436dc47410>)¶

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) – Wavelength \(\lambda\) in centimeters (cm). CO2_concentration (numeric, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric, optional) – Air temperature \(T[K]\) in kelvin degrees. avogadro_constant (numeric, 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

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 0x2b436dc47140>, F_air=<function F_air_Bodhaine1999 at 0x2b436dc47410>)¶

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

Parameters:	wavelength (numeric) – Wavelength \(\lambda\) in centimeters (cm). CO2_concentration (numeric, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric, optional) – Air temperature \(T[K]\) in kelvin degrees. pressure (numeric) – Surface pressure \(P\) of the measurement site. latitude (numeric, optional) – Latitude of the site in degrees. altitude (numeric, optional) – Altitude of the site in meters. avogadro_constant (numeric, 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

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 0x2b436dc47140>, F_air=<function F_air_Bodhaine1999 at 0x2b436dc47410>)¶

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

Parameters:	wavelength (numeric) – Wavelength \(\lambda\) in centimeters (cm). CO2_concentration (numeric, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric, optional) – Air temperature \(T[K]\) in kelvin degrees. pressure (numeric) – Surface pressure \(P\) of the measurement site. latitude (numeric, optional) – Latitude of the site in degrees. altitude (numeric, optional) – Altitude of the site in meters. avogadro_constant (numeric, 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

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 0x2b436dc47140>, F_air=<function F_air_Bodhaine1999 at 0x2b436dc47410>)¶

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, optional) – \(CO_2\) concentration in parts per million (ppm). temperature (numeric, optional) – Air temperature \(T[K]\) in kelvin degrees. pressure (numeric) – Surface pressure \(P\) of the measurement site. latitude (numeric, optional) – Latitude of the site in degrees. altitude (numeric, optional) – Altitude of the site in meters. avogadro_constant (numeric, 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) – 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

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')  
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) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric

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) – 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_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) – 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_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) – 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_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) – luminance \(Y\).
Returns:	Munsell value \(V\).
Return type:	numeric

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)  
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) – 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_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 matrix.
Return type:	ndarray, (3,)

Notes

• Output CIE xyY colourspace matrix 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 matrix. 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 matrix is in domain [0, 1].

Examples

>>> xyY = np.array([0.38736945, 0.35751656, 0.59362])
>>> # 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 matrix using Smits (1999) method.

Parameters:	RGB (array_like, (3,)) – RGB colourspace matrix.
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:	tuple
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)  
(0.1978003..., 0.3122005...)

colour.CCT_to_uv_Ohno2013(CCT, D_uv=0, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2b436d3b77d0>)¶

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:	tuple

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)  
(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:	tuple

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)  
(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:	tuple
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_to_CCT((0.1978, 0.3122), cmfs=cmfs)  
(6507.5470349..., 0.0032236...)

colour.uv_to_CCT_Ohno2013(uv, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x2b436d3b77d0>, 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:	tuple

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_to_CCT_Ohno2013((0.1978, 0.3122), cmfs)  
(6507.5470349..., 0.0032236...)

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:	tuple

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 = (0.19374137599822966, 0.31522104394059397)
>>> uv_to_CCT_Robertson1968(uv)  
(6500.0162879..., 0.0083333...)

colour.CCT_to_xy(CCT, method=u'Kang 2002')¶

Returns the CIE XYZ colourspace xy chromaticity coordinates from given correlated colour temperature \(T_{cp}\) using given method.

Parameters:	CCT (numeric) – Correlated colour temperature \(T_{cp}\). method (unicode, optional) – {‘Kang 2002’, ‘CIE Illuminant D Series’} Computation method.
Returns:	xy chromaticity coordinates.
Return type:	tuple

colour.CCT_to_xy_Kang2002(CCT)¶

Returns the CIE XYZ colourspace xy chromaticity coordinates from given correlated colour temperature \(T_{cp}\) using Kang et al. (2002) method.

Parameters:	CCT (numeric) – Correlated colour temperature \(T_{cp}\).
Returns:	xy chromaticity coordinates.
Return type:	tuple
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)  
(0.3134259..., 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) – Correlated colour temperature \(T_{cp}\).
Returns:	xy chromaticity coordinates.
Return type:	tuple
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)  
(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 colourspace 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

colour.xy_to_CCT_McCamy1992(xy)¶

Returns the correlated colour temperature \(T_{cp}\) from given CIE XYZ colourspace xy chromaticity coordinates using McCamy (1992) method.

Parameters:	xy (array_like) – xy chromaticity coordinates.
Returns:	Correlated colour temperature \(T_{cp}\).
Return type:	numeric

References

[9]	Wikipedia. (n.d.). Approximation. Retrieved June 28, 2014, from http://en.wikipedia.org/wiki/Color_temperature#Approximation

Examples

>>> xy_to_CCT_McCamy1992((0.31271, 0.32902))  
6504.3893830...

colour.xy_to_CCT_Hernandez1999(xy)¶

Returns the correlated colour temperature \(T_{cp}\) from given CIE XYZ colourspace 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_to_CCT_Hernandez1999((0.31271, 0.32902))  
6500.0421533...

colour.is_within_macadam_limits(xyY, illuminant)¶

Returns if given CIE xyY colourspace matrix is within MacAdam limits of given illuminant.

Parameters:	xyY (array_like, (3,)) – CIE xyY colourspace matrix. illuminant (unicode) – Illuminant.
Returns:	Is within MacAdam limits.
Return type:	bool

Notes

• Input CIE xyY colourspace matrix is in domain [0, 1].
• This definition requires scipy to be installed.

Examples

>>> is_within_macadam_limits((0.3205, 0.4131, 0.51), 'A')
True
>>> is_within_macadam_limits((0.0005, 0.0031, 0.001), 'A')
False

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 0x2b437a204500>, 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...