# colour Package¶

## Module Contents¶

### Colour¶

Colour is a Python colour science package implementing a comprehensive number of colour theory transformations and algorithms.

#### Subpackages¶

• algebra: Algebra utilities.
• appearance: Colour appearance models.
• characterisation: Colour fitting and camera characterisation.
• colorimetry: Core objects for colour computations.
• constants: CIE and CODATA constants.
• 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.
• optimal: Optimal colour stimuli computation.
• phenomenons: Computation of various optical phenomenons.
• plotting: Diagrams, plots, etc...
• quality: Colour quality computation.
• temperature: Colour temperature and correlated colour temperature computation.
• utilities: Various utilities and data structures.

Returns the chromatic adaptation matrix from given source and target CIE XYZ colourspace array_like variables.

Parameters: XYZ1 (array_like, (3,)) – CIE XYZ source array_like variable. XYZ2 (array_like, (3,)) – CIE XYZ target array_like variable. method (unicode, optional) – (‘XYZ Scaling’, ‘Bradford’, ‘Von Kries’, ‘Fairchild, ‘CAT02’), Chromatic adaptation method. Chromatic adaptation matrix. ndarray, (3, 3) KeyError – If chromatic adaptation method is not defined.

References

 [4] http://brucelindbloom.com/Eqn_ChromAdapt.html (Last accessed 24 February 2014)

Examples

>>> XYZ1 = np.array([1.09923822, 1.000, 0.35445412])
>>> XYZ2 = np.array([0.96907232, 1.000, 1.121792157])
array([[ 0.8714561..., -0.1320467...,  0.4039483...],
[-0.0963880...,  1.0490978...,  0.160403... ],
[ 0.0080207...,  0.0282636...,  3.0602319...]])


>>> XYZ1 = np.array([1.09923822, 1.000, 0.35445412])
>>> XYZ2 = np.array([0.96907232, 1.000, 1.121792157])
>>> method = 'Bradford'
>>> chromatic_adaptation_matrix(XYZ1, XYZ2, method)
array([[ 0.8518131..., -0.1134786...,  0.4124804...],
[-0.1277659...,  1.0928930...,  0.1341559...],
[ 0.0845323..., -0.1434969...,  3.3075309...]])

colour.steps(distribution)

Returns the steps of given distribution.

Parameters: distribution (array_like) – Distribution to retrieve the steps. Distribution steps. 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. Closest $$y$$ variable element. numeric

Examples

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

colour.to_ndarray(x, data_type=<type 'numpy.float64'>)

Converts given $$x$$ variable to ndarray.

Parameters: x (object) – Variable to convert. data_type (dtype) – ndarray data type. $$x$$ variable converted to ndarray. ndarray

Examples

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

colour.is_uniform(distribution)

Returns if given distribution is uniform.

Parameters: distribution (array_like) – Distribution to check for uniformity. Is distribution uniform. 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. $$x$$ variable iterability. 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. Is $$x$$ variable a number. bool

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. Is $$x$$ variable an integer. bool

Notes

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’]. Normalised $$x$$ variable. 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. Spherical coordinates vector (r, theta, phi). ndarray

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. Cartesian coordinates vector (x, y, z). ndarray

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. Cylindrical coordinates vector (z, theta, rho). ndarray

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. Cartesian coordinates vector (x, y, z). ndarray

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] http://stackoverflow.com/a/2745496/931625 (Last accessed 8 August 2014)

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. Extrapolated points value(s). float or ndarray
interpolator

Property for self.__interpolator private attribute.

Returns: self.__interpolator object
left

Property for self.__left private attribute.

Returns: self.__left numeric
method

Property for self.__method private attribute.

Returns: self.__method unicode
right

Property for self.__right private attribute.

Returns: self.__right 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.

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. Interpolated value(s). float or ndarray
x

Property for self.__x private attribute.

Returns: self.__x array_like
y

Property for self.__y private attribute.

Returns: self.__y 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.

The 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__()

Notes

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

References

 [2] Stephen Westland, Caterina Ripamonti, Vien Cheung, Computational Colour Science Using MATLAB, 2nd Edition, The Wiley-IS&T Series in Imaging Science and Technology, published July 2012, ISBN-13: 978-0-470-66569-5, page 33.

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. Interpolated value(s). numeric or ndarray
x

Property for self.__x private attribute.

Returns: self.__x array_like
y

Property for self.__y private attribute.

Returns: self.__y 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. Is identity matrix. 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


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. Regression statistics. ndarray, ({{mn, mn-1, ..., b}, {sum_of_squares_residual}}) ValueError – If $$y$$ and $$x$$ variables have incompatible dimensions.

References

 [2] http://en.wikipedia.org/wiki/Simple_linear_regression (Last accessed 24 May 2014)

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

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

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 Mark D. Fairchild 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. Hunt_Specification 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

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 Mark D. Fairchild 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. ATD (1995) colour vision model specification. 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

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

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. CIECAM02 colour appearance model specification. 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. XYZ – CIE XYZ colourspace matrix. 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

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 Mark D. Fairchild 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. LLAB(L:c) colour appearance model specification. 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.3680474..., C=0.0086506..., h=229.4635727..., s=0.0002314..., M=0.0183832..., HC=None, a=-0.0119478..., b=-0.0139711...)

class colour.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 Mark D. Fairchild 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,] 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. Nayatani (1995) colour appearance model specification. 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].
Raises: ValueError – If Luminance factor $$Y_o$$ is not greater or equal than 18%.

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

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 Mark D. Fairchild 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]. RLAB colour appearance model specification. 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. Fitting colour matrix. 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$$. Is wavelength $$\lambda$$ in the spectral shape. 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. Spectral shape equality. 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. generator

Notes

• Reimplements the object.__iter__() method.

Examples

>>> shape = SpectralShape(0, 10, 1)
>>> for wavelength in shape: print(wavelength)
0
1
2
3
4
5
6
7
8
9
10

__len__()

Returns the spectral shape wavelengths $$\lambda_n$$ count.

Returns: Spectral shape wavelengths $$\lambda_n$$ count. 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. Spectral shape inequality. 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. unicode
__str__()

Returns a nice formatted string representation.

Returns: Nice formatted string representation. unicode
end

Property for self.__end private attribute.

Returns: self.__end. numeric
range()

Returns an iterable range for the spectral power distribution shape.

Returns: Iterable range for the spectral power distribution shape ndarray 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. numeric
steps

Property for self.__steps private attribute.

Returns: self.__steps. numeric
class colour.SpectralPowerDistribution(name, data)

Bases: object

Defines the base object for spectral data computations.

Parameters: name (str or 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}$$}
name
data
wavelengths
values
items
shape
__getitem__()
__init__()
__setitem__()
__iter__()
__contains__()
__len__()
__eq__()
__ne__()
__sub__()
__mul__()
__div__()
__truediv__()
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)


Implements support for spectral power distribution addition.

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

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$$. Is wavelength $$\lambda$$ in the spectral power distribution. 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. Variable divided spectral power distribution. SpectralPowerDistribution

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. Spectral power distribution equality. 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. Wavelength $$\lambda$$ value. numeric

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. 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] http://stackoverflow.com/a/16162138/931625 (Last accessed 8 August 2014)
__iter__()

Returns a generator for the spectral power distribution data.

Returns: Spectral power distribution data generator. 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. 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. Variable multiplied spectral power distribution. SpectralPowerDistribution

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. Spectral power distribution inequality. 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

__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. Variable subtracted spectral power distribution. SpectralPowerDistribution

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. Variable divided spectral power distribution. SpectralPowerDistribution

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) – (‘Linear’, ‘Constant’), Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range. Aligned spectral power distribution. 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.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. 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. 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) – (‘Linear’, ‘Constant’), Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range. Extrapolated spectral power distribution. SpectralPowerDistribution

References

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. Wavelength $$\lambda$$ value. numeric

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) – (‘Sprague’, ‘Cubic Spline’, ‘Linear’), Enforce given interpolation method. Interpolated spectral power distribution. SpectralPowerDistribution RuntimeError – If the Sprague interpolation method is forced with a non-uniformly spaced independent variable. ValueError – If the interpolation method is not defined.

Notes

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 interpolator requires at least 6 wavelengths $$\lambda_n$$ for interpolation.

References

Examples

Uniform data is using Sprague 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. bool

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. generator
name

Property for self.__name private attribute.

Returns: self.__name. str or unicode
normalise(factor=1)

Normalises the spectral power distribution with given normalization factor.

Parameters: factor (numeric, optional) – Normalization factor Normalised spectral power distribution. 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. SpectralShape

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

values

Property for self.values attribute.

Returns: Spectral power distribution wavelengths $$\lambda_n$$ values. ndarray

Warning

SpectralPowerDistribution.values is read only.

wavelengths

Property for self.wavelengths attribute.

Returns: Spectral power distribution wavelengths $$\lambda_n$$. ndarray
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. Zeros filled spectral power distribution. 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, labels)

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 (str or unicode) – Tri-spectral power distribution name. data (dict) – Tri-spectral power distribution data. mapping (dict) – Tri-spectral power distribution attributes mapping. labels (dict) – Tri-spectral power distribution axis labels mapping.
name
mapping
data
labels
x
y
z
wavelengths
values
items
shape
__init__()
__getitem__()
__setitem__()
__iter__()
__contains__()
__len__()
__eq__()
__ne__()
__sub__()
__mul__()
__div__()
__truediv__()
get()
is_uniform()
extrapolate()
interpolate()
align()
zeros()
normalise()
clone()

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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)


Implements support for tri-spectral power distribution addition.

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

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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, mpg, lbl)
>>> 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$$. Is wavelength $$\lambda$$ in the tri-spectral power distribution. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. Variable divided tri-spectral power distribution. TriSpectralPowerDistribution

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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, mpg, lbl)
>>> 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. Tri-spectral power distribution equality. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mpg, lbl)
>>> tri_spd2 = TriSpectralPowerDistribution('Tri Spd', data2, mpg, lbl)
>>> tri_spd3 = TriSpectralPowerDistribution('Tri Spd', data1, mpg, lbl)
>>> 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. Wavelength $$\lambda$$ values. ndarray, (3,)

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> tri_spd[510]
array([ 49.67,  90.56,  12.43])

__hash__()

Returns the spectral power distribution hash value.

Returns: Object hash. int

Notes

• Reimplements the object.__hash__() method.

Warning

See SpectralPowerDistribution.__hash__() method warning section.

References

 [5] http://stackoverflow.com/a/16162138/931625 (Last accessed 8 August 2014)
__iter__()

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

Returns: Tri-spectral power distribution data generator. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. Variable multiplied tri-spectral power distribution. TriSpectralPowerDistribution

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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, mpg, lbl)
>>> 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. Tri-spectral power distribution inequality. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd1 = TriSpectralPowerDistribution('Tri Spd', data1, mpg, lbl)
>>> tri_spd2 = TriSpectralPowerDistribution('Tri Spd', data2, mpg, lbl)
>>> tri_spd3 = TriSpectralPowerDistribution('Tri Spd', data1, mpg, lbl)
>>> tri_spd1 != tri_spd2
True
>>> tri_spd1 != tri_spd3
False

__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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. Variable subtracted tri-spectral power distribution. TriSpectralPowerDistribution

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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, mpg, lbl)
>>> 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. Variable divided tri-spectral power distribution. TriSpectralPowerDistribution

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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, mpg, lbl)
>>> 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) – (‘Linear’, ‘Constant’), Extrapolation method. left (numeric, optional) – Value to return for low extrapolation range. right (numeric, optional) – Value to return for high extrapolation range. Aligned tri-spectral power distribution. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. dict
extrapolate(shape, method=u'Constant', left=None, right=None)

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

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

References

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. Wavelength $$\lambda$$ values. numeric

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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.

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

Notes

Warning

See SpectralPowerDistribution.interpolate() method warning section.

References

Examples

Uniform data is using Sprague 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. bool

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. generator
labels

Property for self.__labels private attribute.

Returns: self.__labels. dict
mapping

Property for self.__mapping private attribute.

Returns: self.__mapping. dict
name

Property for self.__name private attribute.

Returns: self.__name. str or unicode
normalise(factor=1)

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

Parameters: factor (numeric, optional) – Normalization factor Normalised tri- spectral power distribution. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. SpectralShape

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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> tri_spd.shape
SpectralShape(510, 540, 10)

values

Property for self.values attribute.

Returns: Tri-spectral power distribution wavelengths $$\lambda_n$$ values. ndarray

Warning

TriSpectralPowerDistribution.values is read only.

wavelengths

Property for self.wavelengths attribute.

Returns: Tri-spectral power distribution wavelengths $$\lambda_n$$. ndarray
x

Property for self.x attribute.

Returns: Spectral power distribution for x axis. SpectralPowerDistribution

Warning

TriSpectralPowerDistribution.x is read only.

y

Property for self.y attribute.

Returns: Spectral power distribution for y axis. SpectralPowerDistribution

Warning

TriSpectralPowerDistribution.y is read only.

z

Property for self.z attribute.

Returns: Spectral power distribution for z axis. 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. Zeros filled tri-spectral power distribution. 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}
>>> mpg = lbl = {'x': 'x_bar', 'y': 'y_bar', 'z': 'z_bar'}
>>> tri_spd = TriSpectralPowerDistribution('Tri Spd', data, mpg, lbl)
>>> 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. Constant $$k$$ to filled spectral power distribution. 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, 830, 1)
>>> 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. Zeros filled spectral power distribution. SpectralPowerDistribution

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, 830, 1)
>>> 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. Ones filled spectral power distribution. SpectralPowerDistribution

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, 830, 1)
>>> 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$$. Blackbody spectral power distribution. 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...>


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

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$$. Radiance in watts per steradian per square metre. 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

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$$. Radiance in watts per steradian per square metre. numeric

Examples

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

class colour.LMS_ConeFundamentals(name, data)

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

Parameters: name (unicode) – LMS colour matching functions name. data (dict) – LMS colour matching functions.
l_bar
m_bar
s_bar
l_bar

Property for self.x attribute.

Returns: self.x SpectralPowerDistribution

Warning

LMS_ConeFundamentals.l_bar is read only.

m_bar

Property for self.y attribute.

Returns: self.y SpectralPowerDistribution

Warning

LMS_ConeFundamentals.m_bar is read only.

s_bar

Property for self.z attribute.

Returns: self.z SpectralPowerDistribution

Warning

LMS_ConeFundamentals.s_bar is read only.

class colour.RGB_ColourMatchingFunctions(name, data)

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.
r_bar
g_bar
b_bar
b_bar

Property for self.z attribute.

Returns: self.z SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.b_bar is read only.

g_bar

Property for self.y attribute.

Returns: self.y SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.g_bar is read only.

r_bar

Property for self.x attribute.

Returns: self.x SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.r_bar is read only.

class colour.XYZ_ColourMatchingFunctions(name, data)

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.
x_bar
y_bar
z_bar
x_bar

Property for self.x attribute.

Returns: self.x SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.x_bar is read only.

y_bar

Property for self.y attribute.

Returns: self.y SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.y_bar is read only.

z_bar

Property for self.z attribute.

Returns: self.z 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) – (‘Stearns 1988’,) Correction method. Spectral bandpass dependence corrected spectral power distribution. SpectralPowerDistribution
colour.bandpass_correction_stearns1988(spd)

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

References

 [1] Stephen Westland, Caterina Ripamonti, Vien Cheung, Computational Colour Science Using MATLAB, 2nd Edition, The Wiley-IS&T Series in Imaging Science and Technology, published July 2012, ISBN-13: 978-0-470-66569-5, page 38.
Parameters: spd (SpectralPowerDistribution) – Spectral power distribution. Spectral bandpass dependence corrected spectral power distribution. 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 & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, page 146.
 [2] http://www.brucelindbloom.com/Eqn_DIlluminant.html (Last accessed 5 April 2014)
Parameters: xy (array_like) – xy chromaticity coordinates. CIE Standard Illuminant D Series relative spectral power distribution. 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 0x102cf8fd0>, scotopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x102e061d0>)

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

Parameters: Lp (numeric) – Photopic luminance $$L_p$$. source (unicode) – (‘Blue Heavy’, ‘Red Heavy’), Light source colour temperature. method (unicode) – (‘MOVE’, ‘LRC’), Method to calculate the weighting factor. photopic_lef (SpectralPowerDistribution) – $$V(\lambda)$$ photopic luminous efficiency function. scotopic_lef (SpectralPowerDistribution) – $$V^\prime(\lambda)$$ scotopic luminous efficiency function. Mesopic luminous efficiency function $$V_m(\lambda)$$. 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 0x102cf8fd0>, scotopic_lef=<colour.colorimetry.spectrum.SpectralPowerDistribution object at 0x102e061d0>)

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) – (‘Blue Heavy’, ‘Red Heavy’), Light source colour temperature. method (unicode) – (‘MOVE’, ‘LRC’), Method to calculate the weighting factor. photopic_lef (SpectralPowerDistribution) – $$V(\lambda)$$ photopic luminous efficiency function. scotopic_lef (SpectralPowerDistribution) – $$V^\prime(\lambda)$$ scotopic luminous efficiency function. Mesopic weighting function factor. numeric 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) – (‘Glasser 1958’, ‘Wyszecki 1964’, ‘CIE 1976’), Computation method. **kwargs (**) – Keywords arguments. Lightness $$L^*$$. 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, Yn=100)
37.9856290...
>>> lightness(10.08, Yn=95)
38.9165987...
>>> lightness(10.08, method='Glasser 1958')
36.2505626...
>>> lightness(10.08, method='Wyszecki 1964')
37.0041149...

colour.lightness_glasser1958(Y, **kwargs)

Returns the Lightness $$L^*$$ of given luminance $$Y$$ using Glasser et al. (1958) method.

Parameters: Y (numeric) – luminance $$Y$$. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other Lightness computation objects. Lightness $$L^*$$. numeric

Notes

• Input luminance $$Y$$ is in domain [0, 100].
• Output Lightness $$L^*$$ is in domain [0, 100].

References

 [1] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

Examples

>>> lightness_glasser1958(10.08)
36.2505626...

colour.lightness_wyszecki1964(Y, **kwargs)

Returns the Lightness $$W^*$$ of given luminance $$Y$$ using Wyszecki (1964) method.

Parameters: Y (numeric) – luminance $$Y$$. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other Lightness computation objects. Lightness $$W^*$$. numeric

Notes

• Input luminance $$Y$$ is in domain [0, 100].
• Output Lightness $$W^*$$ is in domain [0, 100].

References

 [1] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

Examples

>>> lightness_wyszecki1964(10.08)
37.0041149...

colour.lightness_1976(Y, Yn=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$$. Yn (numeric, optional) – White reference luminance $$Y_n$$. Lightness $$L^*$$. numeric

Notes

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

References

 [2] http://www.poynton.com/PDFs/GammaFAQ.pdf (Last accessed 12 April 2014)

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) – (‘Newhall 1943’, ‘CIE 1976’, ‘ASTM D1535-08’) Computation method. **kwargs (**) – Keywords arguments. luminance $$Y$$. 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, Yn=100)
10.0800000...
>>> luminance(37.9856290977, Yn=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 $$Y$$ of given Munsell value $$V$$ using Newhall, Nickerson, and Judd (1943) method.

Parameters: V (numeric) – Munsell value $$V$$. **kwargs (**, optional) – Unused parameter provided for signature compatibility with other luminance computation objects. luminance $$Y$$. numeric

Notes

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

References

 [1] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

Examples

>>> luminance_newhall1943(3.74629715382)
10.4089874...

colour.luminance_1976(L, Yn=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$$. luminance $$Y$$. numeric

Notes

• Input Lightness $$L^*$$ is in domain [0, 100].
• Output luminance $$Y$$ is in domain [0, 100].

References

 [2] http://www.poynton.com/PDFs/GammaFAQ.pdf (Last accessed 12 April 2014)

Examples

>>> luminance_1976(37.9856290977)
10.0800000...

colour.luminance_ASTM_D1535_08(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. luminance $$Y$$. numeric

Notes

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

References

Examples

>>> luminance_ASTM_D1535_08(3.74629715382)
10.1488096...

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. Stockman & Sharpe 10 Degree Cone Fundamentals spectral tristimulus values. ndarray, (3,) 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

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

Notes

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

References

 [1] Wyszecki & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, pages 138, 139.

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

Notes

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

References

 [2] Wyszecki & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, page 141.

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. CIE 2012 2 Degree Standard Observer spectral tristimulus values. ndarray, (3,) 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] http://www.cvrl.org/database/text/cienewxyz/cie2012xyz2.htm (Last accessed 25 June 2014)

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. CIE 2012 10 Degree Standard Observer spectral tristimulus values. ndarray, (3,) 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] http://www.cvrl.org/database/text/cienewxyz/cie2012xyz10.htm (Last accessed 25 June 2014)

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 0x102cf5c10>, 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. CIE XYZ colourspace matrix. 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 & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, page 158.

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. CIE XYZ colourspace matrix. ndarray, (3,) 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.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) – (‘CIE 1976’, ‘CIE 1994’, ‘CIE 2000’, ‘CMC’) Computation method. **kwargs (**) – Keywords arguments. Colour difference $$\Delta E_{ab}$$. 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_CIE_1976(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. Colour difference $$\Delta E_{ab}$$. numeric

References

 [2] http://brucelindbloom.com/Eqn_DeltaE_CIE76.html (Last accessed 24 February 2014)

Examples

>>> lab1 = np.array([100, 21.57210357, 272.2281935])
>>> lab2 = np.array([100, 426.67945353, 72.39590835])
>>> delta_E_CIE_1976(lab1, lab2)
451.7133019...

colour.delta_E_CIE_1994(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. Colour difference $$\Delta E_{ab}$$. numeric

References

 [3] http://brucelindbloom.com/Eqn_DeltaE_CIE94.html (Last accessed 24 February 2014)

Examples

>>> lab1 = np.array([100, 21.57210357, 272.2281935])
>>> lab2 = np.array([100, 426.67945353, 72.39590835])
>>> delta_E_CIE_1994(lab1, lab2)
88.3355530...
>>> delta_E_CIE_1994(lab1, lab2, textiles=False)
83.7792255...

colour.delta_E_CIE_2000(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. Colour difference $$\Delta E_{ab}$$. numeric

References

 [4] http://brucelindbloom.com/Eqn_DeltaE_CIE2000.html (Last accessed 24 February 2014)

Examples

>>> lab1 = np.array([100, 21.57210357, 272.2281935])
>>> lab2 = np.array([100, 426.67945353, 72.39590835])
>>> delta_E_CIE_2000(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. Colour difference $$\Delta E_{ab}$$. numeric

References

 [5] http://brucelindbloom.com/Eqn_DeltaE_CMC.html (Last accessed 24 February 2014)

Examples

>>> lab1 = np.array([100, 21.57210357, 272.2281935])
>>> lab2 = np.array([100, 426.67945353, 72.39590835])
>>> delta_E_CMC(lab1, lab2)
172.7047712...

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 ad dict of dict as follows:

{‘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. CSV file content. dict 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(sorted(spds_data.keys()))
['1',
'10',
'11',
'12',
'13',
'14',
'15',
'16',
'17',
'18',
'19',
'2',
'20',
'21',
'22',
'23',
'24',
'3',
'4',
'5',
'6',
'7',
'8',
'9']

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 a dict of colour.colorimetry.spectrum.TriSpectralPowerDistribution 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. colour.colorimetry.spectrum.TriSpectralPowerDistribution classes of given CSV file. dict

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(sorted(spds.items()))
[('1',
<...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...>),
('2',
<...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...>),
('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...>)]

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. Definition success. bool RuntimeError – If the given spectral power distributions have different shapes.
class colour.RGB_Colourspace(name, primaries, whitepoint, to_XYZ=None, to_RGB=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 (str or unicode) – RGB Colourspace name. primaries (array_like) – RGB Colourspace primaries. whitepoint (array_like) – RGB Colourspace whitepoint. to_XYZ (array_like) – Transformation matrix from colourspace to CIE XYZ colourspace. to_RGB (array_like) – Transformation matrix from CIE XYZ colourspace to colourspace. transfer_function (object) – RGB Colourspace transfer function from linear to colourspace. inverse_transfer_function (object) – RGB Colourspace inverse transfer function from colourspace to linear.
inverse_transfer_function

Property for self.__inverse_transfer_function private attribute.

Returns: self.__inverse_transfer_function. object
name

Property for self.__name private attribute.

Returns: self.__name. str or unicode
primaries

Property for self.__primaries private attribute.

Returns: self.__primaries. array_like, (3, 2)
to_RGB

Property for self.__to_RGB private attribute.

Returns: self.__to_RGB. array_like, (3, 3)
to_XYZ

Property for self.__to_XYZ private attribute.

Returns: self.__to_XYZ. array_like, (3, 3)
transfer_function

Property for self.__transfer_function private attribute.

Returns: self.__transfer_function. object
whitepoint

Property for self.__whitepoint private attribute.

Returns: self.__whitepoint. 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. Normalised primary matrix. ndarray, (3, 3)

References

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. Luminance equation. unicode

References

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. Luminance $$y$$. numeric

References

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_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. CIE xyY colourspace matrix. 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] http://www.brucelindbloom.com/Eqn_XYZ_to_xyY.html (Last accessed 24 February 2014)

Examples

>>> XYZ_to_xyY(np.array([0.1180583421, 0.1034, 0.0515089229]))
array([ 0.4325,  0.3788,  0.1034])

colour.xyY_to_XYZ(xyY)

Converts from CIE xyY colourspace to CIE XYZ colourspace.

Parameters: xyY (array_like, (3,)) – CIE xyY colourspace matrix. CIE XYZ colourspace matrix. 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] http://www.brucelindbloom.com/Eqn_xyY_to_XYZ.html (Last accessed 24 February 2014)

Examples

>>> xyY_to_XYZ(np.array([0.4325, 0.3788, 0.1034]))
array([ 0.1180583...,  0.1034    ,  0.0515089...])

colour.xy_to_XYZ(xy)

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

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

Notes

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

Examples

>>> xy_to_XYZ((0.25, 0.25))
array([ 1.,  1.,  2.])

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. xy chromaticity coordinates. tuple

Notes

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

Examples

>>> XYZ_to_xy(np.array([0.97137399, 1, 1.04462134]))
(0.3220741..., 0.3315655...)
>>> XYZ_to_xy((0.97137399, 1, 1.04462134))
(0.3220741..., 0.3315655...)

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. CIE Lab colourspace matrix. 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] http://www.brucelindbloom.com/Eqn_XYZ_to_Lab.html (Last accessed 24 February 2014)

Examples

>>> XYZ_to_Lab(np.array([0.92193107, 1, 1.03744246]))
array([ 100.        ,   -7.4178784...,  -15.8574210...])

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. CIE XYZ colourspace matrix. 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] http://www.brucelindbloom.com/Eqn_Lab_to_XYZ.html (Last accessed 24 February 2014)

Examples

>>> Lab = np.array([100, -7.41787844, -15.85742105])
>>> Lab_to_XYZ(Lab)
array([ 0.9219310...,  1.        ,  1.0374424...])

colour.Lab_to_LCHab(Lab)

Converts from CIE Lab colourspace to CIE LCHab colourspace.

Parameters: Lab (array_like, (3,)) – CIE Lab colourspace matrix. CIE LCHab colourspace matrix. ndarray, (3,)

Notes

• Lightness $$L^*$$ is in domain [0, 100].

References

 [4] http://www.brucelindbloom.com/Eqn_Lab_to_LCH.html (Last accessed 24 February 2014)

Examples

>>> Lab = np.array([100, -7.41787844, -15.85742105])
>>> Lab_to_LCHab(Lab)
array([ 100.        ,   17.5066479...,  244.9304684...])

colour.LCHab_to_Lab(LCHab)

Converts from CIE LCHab colourspace to CIE Lab colourspace.

Parameters: LCHab (array_like, (3,)) – CIE LCHab colourspace matrix. CIE Lab colourspace matrix. ndarray, (3,)

Notes

• Lightness $$L^*$$ is in domain [0, 100].

References

 [5] http://www.brucelindbloom.com/Eqn_LCH_to_Lab.html (Last accessed 24 February 2014)

Examples

>>> LCHab = np.array([100, 17.50664796, 244.93046842])
>>> LCHab_to_Lab(LCHab)
array([ 100.        ,   -7.4178784...,  -15.8574210...])

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. CIE Luv colourspace matrix. 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] http://brucelindbloom.com/Eqn_XYZ_to_Luv.html (Last accessed 24 February 2014)

Examples

>>> XYZ_to_Luv(np.array([0.92193107, 1, 1.03744246]))
array([ 100.        ,  -20.0430424...,  -19.8167603...])

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. CIE XYZ colourspace matrix. 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] http://brucelindbloom.com/Eqn_Luv_to_XYZ.html (Last accessed 24 February 2014)

Examples

>>> Luv = np.array([100, -20.04304247, -19.81676035])
>>> Luv_to_XYZ(Luv)
array([ 0.9219310...,  1.        ,  1.0374424...])

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

Returns the u”v” 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. u”v” chromaticity coordinates. tuple

Notes

• Input $$L^*$$ is in domain [0, 100].
• Output u”v” chromaticity coordinates are in domain [0, 1].

References

 [4] http://en.wikipedia.org/wiki/CIELUV#The_forward_transformation (Last accessed 24 February 2014)

Examples

>>> Luv = np.array([100, -20.04304247, -19.81676035])
>>> Luv_to_uv(Luv)
(0.1937414..., 0.4728316...)

colour.Luv_uv_to_xy(uv)

Returns the xy chromaticity coordinates from given CIE Luv colourspace u”v” chromaticity coordinates.

Parameters: uv (array_like) – CIE Luv u”v” chromaticity coordinates. xy chromaticity coordinates. tuple

Notes

• Input u”v” chromaticity coordinates are in domain [0, 1].
• Output xy is in domain [0, 1].

References

 [5] http://en.wikipedia.org/wiki/CIELUV#The_reverse_transformation (Last accessed 24 February 2014)

Examples

>>> uv = (0.2033733344733139, 0.3140500001549052)
>>> Luv_uv_to_xy(uv)
(0.2233388..., 0.1532803...)

colour.Luv_to_LCHuv(Luv)

Converts from CIE Luv colourspace to CIE LCHuv colourspace.

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

Notes

• $$L^*$$ is in domain [0, 100].

References

 [6] http://www.brucelindbloom.com/Eqn_Luv_to_LCH.html (Last accessed 24 February 2014)

Examples

>>> Luv = np.array([100, -20.04304247, -19.81676035])
>>> Luv_to_LCHuv(Luv)
array([ 100.        ,   28.1855910...,  224.6747382...])

colour.LCHuv_to_Luv(LCHuv)

Converts from CIE LCHuv colourspace to CIE Luv colourspace.

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

Notes

• $$L^*$$ is in domain [0, 100].

References

 [7] http://www.brucelindbloom.com/Eqn_LCH_to_Luv.html (Last accessed 24 February 2014)

Examples

>>> LCHuv = np.array([100, 28.18559104, 224.6747382])
>>> LCHuv_to_Luv(LCHuv)
array([ 100.        ,  -20.0430424...,  -19.8167603...])

colour.XYZ_to_UCS(XYZ)

Converts from CIE XYZ colourspace to CIE UCS colourspace.

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

Notes

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

References

 [2] http://en.wikipedia.org/wiki/CIE_1960_color_space#Relation_to_CIEXYZ (Last accessed 24 February 2014)

Examples

>>> XYZ = np.array([0.1180583421, 0.1034, 0.0515089229])
>>> XYZ_to_UCS(XYZ)
array([ 0.0787055...,  0.1034    ,  0.1218252...])

colour.UCS_to_XYZ(UVW)

Converts from CIE UCS colourspace to CIE XYZ colourspace.

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

Notes

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

References

 [3] http://en.wikipedia.org/wiki/CIE_1960_color_space#Relation_to_CIEXYZ (Last accessed 24 February 2014)

Examples

>>> UCS = np.array([0.07870556, 0.1034, 0.12182529])
>>> UCS_to_XYZ(UCS)
array([ 0.1180583...,  0.1034    ,  0.0515089...])

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. uv chromaticity coordinates. tuple

Notes

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

References

 [4] http://en.wikipedia.org/wiki/CIE_1960_color_space#Relation_to_CIEXYZ (Last accessed 24 February 2014)

Examples

>>> UCS = np.array([0.1180583421, 0.1034, 0.0515089229])
>>> UCS_to_uv(UCS)
(0.4324999..., 0.3788000...)

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. xy chromaticity coordinates. tuple

Notes

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

References

 [5] http://en.wikipedia.org/wiki/CIE_1960_color_space#Relation_to_CIEXYZ (Last accessed 24 February 2014)

Examples

>>> uv = (0.43249999995420696, 0.378800000065942)
>>> UCS_uv_to_xy(uv)
(0.7072386..., 0.4129510...)

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

Converts from CIE XYZ colourspace to CIE 1964 U*VW** colourspace.

Parameters: XYZ (array_like, (3,)) – CIE XYZ colourspace matrix. illuminant (array_like, optional) – Reference illuminant chromaticity coordinates. CIE 1964 U*VW** colourspace matrix. 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([11.80583421, 10.34, 5.15089229])
>>> XYZ_to_UVW(XYZ)
array([ 24.2543371...,   7.2205484...,  37.4645000...])

colour.XYZ_to_RGB(XYZ, illuminant_XYZ, illuminant_RGB, to_RGB, chromatic_adaptation_method=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. to_RGB (array_like, (3, 3)) – Normalised primary matrix. chromatic_adaptation_method (unicode, optional) – (‘XYZ Scaling’, ‘Bradford’, ‘Von Kries’, ‘Fairchild’, ‘CAT02’) Chromatic adaptation method. transfer_function (object, optional) – Transfer function. RGB colourspace matrix. 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.1151847498, 0.1008, 0.0508937252])
>>> illuminant_XYZ = (0.34567, 0.35850)
>>> illuminant_RGB = (0.31271, 0.32902)
>>> to_RGB = 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,
...     to_RGB,
array([ 0.1730350...,  0.0821103...,  0.0567249...])

colour.RGB_to_XYZ(RGB, illuminant_RGB, illuminant_XYZ, to_XYZ, chromatic_adaptation_method=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. to_XYZ (array_like, (3, 3)) – Normalised primary matrix. chromatic_adaptation_method (unicode, optional) – (‘XYZ Scaling’, ‘Bradford’, ‘Von Kries’, ‘Fairchild’, ‘CAT02’) Chromatic adaptation method. inverse_transfer_function (object, optional) – Inverse transfer function. CIE XYZ colourspace matrix. 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.17303501, 0.08211033, 0.05672498])
>>> illuminant_RGB = (0.31271, 0.32902)
>>> illuminant_XYZ = (0.34567, 0.35850)
>>> to_XYZ = 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,
...     to_XYZ,
array([ 0.1151847...,  0.1008    ,  0.0508937...])

colour.RGB_to_RGB(RGB, input_colourspace, output_colourspace, chromatic_adaptation_method=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_method (unicode, optional) – (‘XYZ Scaling’, ‘Bradford’, ‘Von Kries’, ‘Fairchild’, ‘CAT02’) Chromatic adaptation method. (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.35521588, 0.41, 0.24177934])
>>> RGB_to_RGB(
...     RGB,
...     sRGB_COLOURSPACE,
...     PROPHOTO_RGB_COLOURSPACE)
array([ 0.3579334...,  0.4007138...,  0.2615704...])

colour.XYZ_to_sRGB(XYZ, illuminant=(0.31271, 0.32902), chromatic_adaptation_method=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_method (unicode, optional) – (‘XYZ Scaling’, ‘Bradford’, ‘Von Kries’, ‘Fairchild’, ‘CAT02’) Chromatic adaptation method. transfer_function (bool, optional) – Apply sRGB transfer function. sRGB colour matrix. ndarray, (3,)

Notes

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

Examples

>>> XYZ = np.array([0.1180583421, 0.1034, 0.0515089229])
>>> XYZ_to_sRGB(XYZ)
array([ 0.4822488...,  0.3165197...,  0.2207051...])

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

Converts given spectral power distribution to ACES RGB colourspace relative exposure values.

Parameters: spd (SpectralPowerDistribution) – Spectral power distribution. illuminant (SpectralPowerDistribution, optional) – Illuminant spectral power distribution. ACES RGB colourspace relative exposure values matrix. ndarray, (3,)

Notes

• Output ACES RGB colourspace relative exposure values matrix is in domain [0, 1].

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


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. Is within MacAdam limits. 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.scattering_cross_section(wavelength, CO2_concentration=300, temperature=288.15, avogadro_constant=6.02214179e+23, n_s=<function air_refraction_index_bodhaine1999 at 0x102e5e500>, F_air=<function F_air_bodhaine1999 at 0x102e5e7d0>)

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. Scattering cross section per molecule $$\sigma$$ of dry air. 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 0x102e5e500>, F_air=<function F_air_bodhaine1999 at 0x102e5e7d0>)

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. Rayleigh optical depth $$T_r(\lambda)$$. 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 0x102e5e500>, F_air=<function F_air_bodhaine1999 at 0x102e5e7d0>)

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. Rayleigh optical depth $$T_r(\lambda)$$. 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 0x102e5e500>, F_air=<function F_air_bodhaine1999 at 0x102e5e7d0>)

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. Rayleigh optical depth spectral power distribution. 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) – (‘Priest 1920’, ‘Munsell 1933’, ‘Moon 1943’, ‘Saunderson 1944’, ‘Ladd 1955’, ‘McCamy 1987’, ‘ASTM D1535-08’) Computation method. Munsell value $$V$$. 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 et al. (1920) method.

Parameters: Y (numeric) – luminance $$Y$$. Munsell value $$V$$. numeric

Notes

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

References

 [14] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

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.

Parameters: Y (numeric) – luminance $$Y$$. Munsell value $$V$$. numeric

Notes

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

References

 [15] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

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.

Parameters: Y (numeric) – luminance $$Y$$. Munsell value $$V$$. numeric

Notes

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

References

 [16] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

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.

Parameters: Y (numeric) – luminance $$Y$$. Munsell value $$V$$. numeric

Notes

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

References

 [17] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

Examples

>>> munsell_value_saunderson1944(10.08)
3.6865080...


Returns the Munsell value $$V$$ of given luminance $$Y$$ using Ladd and Pinney (1955) method.

Parameters: Y (numeric) – luminance $$Y$$. Munsell value $$V$$. numeric

Notes

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

References

 [18] http://en.wikipedia.org/wiki/Lightness (Last accessed 13 April 2014)

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$$. Munsell value $$V$$. numeric

Notes

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

References

Examples

>>> munsell_value_mccamy1987(10.08)
3.7347235...

colour.munsell_value_ASTM_D1535_08(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$$ Munsell value $$V$$.. numeric

Notes

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

Examples

>>> munsell_value_ASTM_D1535_08(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. CIE xyY colourspace matrix. 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. Munsell colour. 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'


Returns the colour rendering index of given spectral power distribution.

Parameters: test_spd (SpectralPowerDistribution) – Test spectral power distribution. additional_data (bool, optional) – Output additional data. Colour rendering index, Tsc data. numeric or (numeric, dict)

Examples

>>> from colour import ILLUMINANTS_RELATIVE_SPDS
>>> spd = ILLUMINANTS_RELATIVE_SPDS.get('F2')
>>> colour_rendering_index(spd)
64.1507331...

colour.CCT_to_uv(CCT, Duv=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}$$. Duv (numeric) – $$\Delta_{uv}$$. method (unicode) – (‘Ohno 2013’, ‘Robertson 1968’) Computation method. **kwargs (**) – Keywords arguments. CIE UCS colourspace uv chromaticity coordinates. tuple 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
>>> Duv = 0.003223690901512735
>>> CCT_to_uv(CCT, Duv, cmfs=cmfs)
(0.1978003..., 0.3122005...)

colour.CCT_to_uv_ohno2013(CCT, Duv=0, cmfs=<colour.colorimetry.cmfs.XYZ_ColourMatchingFunctions object at 0x102cf5c10>)

Returns the CIE UCS colourspace uv chromaticity coordinates from given correlated colour temperature $$T_{cp}$$, $$\Delta_{uv}$$ and colour matching functions using Yoshi Ohno (2013) method.

Parameters: CCT (numeric) – Correlated colour temperature $$T_{cp}$$. Duv (numeric, optional) – $$\Delta_{uv}$$. cmfs (XYZ_ColourMatchingFunctions, optional) – Standard observer colour matching functions. CIE UCS colourspace uv chromaticity coordinates. tuple

References

 [3] Yoshi Ohno, Practical Use and Calculation of CCT and Duv

Examples

>>> from colour import STANDARD_OBSERVERS_CMFS
>>> cmfs = 'CIE 1931 2 Degree Standard Observer'
>>> cmfs = STANDARD_OBSERVERS_CMFS.get(cmfs)
>>> CCT = 6507.4342201047066
>>> Duv = 0.003223690901512735
>>> CCT_to_uv_ohno2013(CCT, Duv, cmfs)
(0.1978003..., 0.3122005...)

colour.CCT_to_uv_robertson1968(CCT, Duv=0)

Returns the CIE UCS colourspace uv chromaticity coordinates from given correlated colour temperature $$T_{cp}$$ and $$\Delta_{uv}$$ using Robertson (1968) method.

Parameters: CCT (numeric) – Correlated colour temperature $$T_{cp}$$. Duv (numeric) – $$\Delta_{uv}$$. CIE UCS colourspace uv chromaticity coordinates. tuple

References

 [6] Wyszecki & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, page 227.
 [7] Adobe DNG SDK 1.3.0.0: dng_sdk_1_3/dng_sdk/source/dng_temperature.cpp: dng_temperature::xy_coord.

Examples

>>> CCT = 6500.0081378199056
>>> Duv = 0.0083333312442250979
>>> CCT_to_uv_robertson1968(CCT, Duv)
(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) – (‘Ohno 2013’, ‘Robertson 1968’) Computation method. **kwargs (**) – Keywords arguments. Correlated colour temperature $$T_{cp}$$, $$\Delta_{uv}$$. tuple 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 0x102cf5c10>, 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 Yoshi 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. Correlated colour temperature $$T_{cp}$$, $$\Delta_{uv}$$. tuple

References

 [2] Yoshi Ohno, Practical Use and Calculation of CCT and Duv

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 Robertson (1968) method.

Parameters: uv (array_like) – CIE UCS colourspace uv chromaticity coordinates. Correlated colour temperature $$T_{cp}$$, $$\Delta_{uv}$$. tuple

References

 [4] Wyszecki & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, page 227.
 [5] Adobe DNG SDK 1.3.0.0: dng_sdk_1_3/dng_sdk/source/dng_temperature.cpp: dng_temperature::Set_xy_coord.

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 (‘Kang 2002’, ‘CIE Illuminant D Series’)) – Computation method. xy chromaticity coordinates. tuple
colour.CCT_to_xy_kang2002(CCT)

Returns the CIE XYZ colourspace xy chromaticity coordinates from given correlated colour temperature $$T_{cp}$$ using Kang, Moon, Hong, Lee, Cho and Kim (2002) method.

Parameters: CCT (numeric) – Correlated colour temperature $$T_{cp}$$. xy chromaticity coordinates. tuple ValueError – If the correlated colour temperature is not in appropriate domain.

References

Examples

>>> CCT_to_xy_kang2002(6504.38938305)
(0.3134259..., 0.3235959...)

colour.CCT_to_xy_illuminant_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.

Parameters: CCT (numeric) – Correlated colour temperature $$T_{cp}$$. xy chromaticity coordinates. tuple ValueError – If the correlated colour temperature is not in appropriate domain.

References

 [11] Wyszecki & Stiles, Color Science - Concepts and Methods Data and Formulae - Second Edition, Wiley Classics Library Edition, published 2000, ISBN-10: 0-471-39918-3, page 145.

Examples

>>> CCT_to_xy_illuminant_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 (‘McCamy 1992’, ‘Hernandez 1999’)) – Computation method. **kwargs (**) – Keywords arguments. Correlated colour temperature $$T_{cp}$$. 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. Correlated colour temperature $$T_{cp}$$. numeric

References

 [8] http://en.wikipedia.org/wiki/Color_temperature#Approximation (Last accessed 28 June 2014)

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 & Romero (1999) method.

Parameters: xy (array_like) – xy chromaticity coordinates. Correlated colour temperature $$T_{cp}$$. numeric

References

Examples

>>> xy_to_CCT_hernandez1999((0.31271, 0.32902))
6500.0421533...