colour.colorimetry Package¶

Sub-Packages¶

colour.colorimetry.dataset Package

Module Contents¶

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

Bases: object

Defines the base object for spectral power distribution shape.

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

start¶

end¶

steps¶

__repr__()¶

__contains__()¶

__len__()¶

__eq__()¶

__ne__()¶

range()¶

Examples

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

__contains__(wavelength)

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

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

Warning

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

Notes

Reimplements the object.__contains__() method.

Examples

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

__eq__(shape)

Returns the spectral shape equality with given other spectral shape.

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

Notes

Reimplements the object.__eq__() method.

Examples

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

__iter__()¶

Returns a generator for the spectral power distribution data.

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

Notes

Reimplements the object.__iter__() method.

Examples

>>> shape = SpectralShape(0, 10, 1)
>>> for wavelength in shape: print(wavelength)
0
0
0
0
0
0
0
0
0
0
0

__len__()

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

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

Notes

Reimplements the object.__len__() method.

Examples

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

__ne__(shape)

Returns the spectral shape inequality with given other spectral shape.

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

Notes

Reimplements the object.__ne__() method.

Examples

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

__repr__()

Returns a formatted string representation.

Returns:	Formatted string representation.
Return type:	unicode

__str__()¶

Returns a nice formatted string representation.

Returns:	Nice formatted string representation.
Return type:	unicode

end

Property for self.__end private attribute.

Returns:	self.__end.
Return type:	numeric

range()

Returns an iterable range for the spectral power distribution shape.

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

Examples

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

start

Property for self.__start private attribute.

Returns:	self.__start.
Return type:	numeric

steps

Property for self.__steps private attribute.

Returns:	self.__steps.
Return type:	numeric

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

Bases: object

Defines the base object for spectral data computations.

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

name¶

data¶

title¶

wavelengths¶

values¶

items¶

shape¶

__getitem__()¶

__init__()¶

__setitem__()¶

__iter__()¶

__contains__()¶

__len__()¶

__eq__()¶

__ne__()¶

__add__()¶

__sub__()¶

__mul__()¶

__div__()¶

__truediv__()¶

__pow__()¶

get()¶

is_uniform()¶

extrapolate()¶

interpolate()¶

align()¶

zeros()¶

normalise()¶

clone()¶

Examples

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

__add__(x)

Implements support for spectral power distribution addition.

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

Notes

Reimplements the object.__add__() method.

Warning

The addition operation happens in place.

Examples

Adding a single numeric variable:

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

Adding an array_like variable:

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

Adding a SpectralPowerDistribution class variable:

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

__contains__(wavelength)

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

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

Warning

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

Notes

Reimplements the object.__contains__() method.

Examples

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

__div__(x)

Implements support for spectral power distribution division.

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

Notes

Reimplements the object.__div__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

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

Dividing an array_like variable:

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

Dividing a SpectralPowerDistribution class variable:

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

__eq__(spd)

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

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

Notes

Reimplements the object.__eq__() method.

Examples

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

__getitem__(wavelength)

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

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

See also

SpectralPowerDistribution.get()

Notes

Reimplements the object.__getitem__() method.

Examples

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

__hash__()¶

Returns the spectral power distribution hash value.

Returns:	Object hash.
Return type:	int

Notes

Reimplements the object.__hash__() method.

Warning

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

References

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

__iter__()

Returns a generator for the spectral power distribution data.

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

Notes

Reimplements the object.__iter__() method.

Examples

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

__len__()

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

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

Notes

Reimplements the object.__len__() method.

Examples

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

__mul__(x)

Implements support for spectral power distribution multiplication.

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

Notes

Reimplements the object.__mul__() method.

Warning

The multiplication operation happens in place.

Examples

Multiplying a single numeric variable:

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

Multiplying an array_like variable:

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

Multiplying a SpectralPowerDistribution class variable:

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

__ne__(spd)

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

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

Notes

Reimplements the object.__ne__() method.

Examples

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

__pow__(x)

Implements support for spectral power distribution exponentiation.

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

Notes

Reimplements the object.__pow__() method.

Warning

The power operation happens in place.

Examples

Exponentiation by a single numeric variable:

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

Exponentiation by an array_like variable:

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

Exponentiation by a SpectralPowerDistribution class variable:

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

__setitem__(wavelength, value)

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

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

Warning

value parameter is resized to match wavelength parameter size.

Notes

Reimplements the object.__setitem__() method.

Examples

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

__sub__(x)

Implements support for spectral power distribution subtraction.

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

Notes

Reimplements the object.__sub__() method.

Warning

The subtraction operation happens in place.

Examples

Subtracting a single numeric variable:

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

Subtracting an array_like variable:

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

Subtracting a SpectralPowerDistribution class variable:

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

__truediv__(x)

Implements support for spectral power distribution division.

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

Notes

Reimplements the object.__div__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

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

Dividing an array_like variable:

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

Dividing a SpectralPowerDistribution class variable:

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

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

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

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

Examples

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

clone()

Clones the spectral power distribution.

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

Returns:	Cloned spectral power distribution.
Return type:	SpectralPowerDistribution

Examples

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

data

Property for self.__data private attribute.

Returns:	self.__data.
Return type:	dict

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

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

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

See also

SpectralPowerDistribution.align()

References

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

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

Examples

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

get(wavelength, default=nan)

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

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

Examples

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

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

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

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

See also

SpectralPowerDistribution.align()

Notes

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

Warning

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

References

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

Examples

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

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

Non uniform data is using Cubic Spline interpolation by default:

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

Enforcing Linear interpolation:

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

is_uniform()

Returns if the spectral power distribution has uniformly spaced data.

Returns:	Is uniform.
Return type:	bool

See also

SpectralPowerDistribution.shape()

Examples

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

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

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

items

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

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

name

Property for self.__name private attribute.

Returns:	self.__name.
Return type:	unicode

normalise(factor=1)

Normalises the spectral power distribution with given normalization factor.

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

Examples

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

shape

Property for self.shape attribute.

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

Returns:	Spectral power distribution shape.
Return type:	SpectralShape

See also

SpectralPowerDistribution.is_uniform

Notes

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

Warning

SpectralPowerDistribution.shape is read only.

Examples

Uniform spectral power distribution:

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

Non uniform spectral power distribution:

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

title

Property for self.__title private attribute.

Returns:	self.__title.
Return type:	unicode

values

Property for self.values attribute.

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

Warning

SpectralPowerDistribution.values is read only.

wavelengths

Property for self.wavelengths attribute.

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

Warning

SpectralPowerDistribution.wavelengths is read only.

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

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

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

Examples

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

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

Bases: object

Defines the base object for colour matching functions.

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

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

name¶

mapping¶

data¶

title¶

labels¶

x¶

y¶

z¶

wavelengths¶

values¶

items¶

shape¶

__init__()¶

__getitem__()¶

__setitem__()¶

__iter__()¶

__contains__()¶

__len__()¶

__eq__()¶

__ne__()¶

__add__()¶

__sub__()¶

__mul__()¶

__div__()¶

__truediv__()¶

get()¶

is_uniform()¶

extrapolate()¶

interpolate()¶

align()¶

zeros()¶

normalise()¶

clone()¶

Examples

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

__add__(x)

Implements support for tri-spectral power distribution addition.

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

Notes

Reimplements the object.__add__() method.

Warning

The addition operation happens in place.

Examples

Adding a single numeric variable:

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

Adding an array_like variable:

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

Adding a TriSpectralPowerDistribution class variable:

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

__contains__(wavelength)

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

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

Warning

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

Notes

Reimplements the object.__contains__() method.

Examples

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

__div__(x)

Implements support for tri-spectral power distribution division.

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

Notes

Reimplements the object.__mul__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

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

Dividing an array_like variable:

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

Dividing a TriSpectralPowerDistribution class variable:

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

__eq__(tri_spd)

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

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

Notes

Reimplements the object.__eq__() method.

Examples

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

__getitem__(wavelength)

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

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

See also

TriSpectralPowerDistribution.get()

Notes

Reimplements the object.__getitem__() method.

Examples

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

__hash__()¶

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

Returns:	Object hash.
Return type:	int

Notes

Reimplements the object.__hash__() method.

Warning

See SpectralPowerDistribution.__hash__() method warning section.

__iter__()

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

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

Notes

Reimplements the object.__iter__() method.

Examples

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

__len__()

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

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

Notes

Reimplements the object.__len__() method.

Examples

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

__mul__(x)

Implements support for tri-spectral power distribution multiplication.

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

Notes

Reimplements the object.__mul__() method.

Warning

The multiplication operation happens in place.

Examples

Multiplying a single numeric variable:

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

Multiplying an array_like variable:

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

Multiplying a TriSpectralPowerDistribution class variable:

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

__ne__(tri_spd)

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

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

Notes

Reimplements the object.__eq__() method.

Examples

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

__pow__(x)¶

Implements support for tri-spectral power distribution exponentiation.

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

Notes

Reimplements the object.__pow__() method.

Warning

The power operation happens in place.

Examples

Exponentiation by a single numeric variable:

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

Exponentiation by an array_like variable:

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

Exponentiation by a TriSpectralPowerDistribution class variable:

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

__setitem__(wavelength, value)

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

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

Warning

value parameter is resized to match wavelength parameter size.

Notes

Reimplements the object.__setitem__() method.

Examples

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

__sub__(x)

Implements support for tri-spectral power distribution subtraction.

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

Notes

Reimplements the object.__sub__() method.

Warning

The subtraction operation happens in place.

Examples

Subtracting a single numeric variable:

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

Subtracting an array_like variable:

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

Subtracting a TriSpectralPowerDistribution class variable:

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

__truediv__(x)

Implements support for tri-spectral power distribution division.

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

Notes

Reimplements the object.__mul__() method.

Warning

The division operation happens in place.

Examples

Dividing a single numeric variable:

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

Dividing an array_like variable:

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

Dividing a TriSpectralPowerDistribution class variable:

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

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

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

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

Examples

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

clone()

Clones the tri-spectral power distribution.

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

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

Examples

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

data

Property for self.__data private attribute.

Returns:	self.__data.
Return type:	dict

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

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

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

See also

TriSpectralPowerDistribution.align()

Examples

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

get(wavelength, default=nan)

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

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

Examples

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

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

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

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

See also

TriSpectralPowerDistribution.align()

Notes

See SpectralPowerDistribution.interpolate() method notes section.

Warning

See SpectralPowerDistribution.interpolate() method warning section.

Examples

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

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

Non uniform data is using Cubic Spline interpolation by default:

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

Enforcing Linear interpolation:

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

is_uniform()

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

Returns:	Is uniform.
Return type:	bool

See also

TriSpectralPowerDistribution.shape()

Examples

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

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

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

items

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

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

labels

Property for self.__labels private attribute.

Returns:	self.__labels.
Return type:	dict

mapping

Property for self.__mapping private attribute.

Returns:	self.__mapping.
Return type:	dict

name

Property for self.__name private attribute.

Returns:	self.__name.
Return type:	unicode

normalise(factor=1)

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

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

Notes

The implementation uses the maximum value for all axis.

Examples

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

shape

Property for self.shape attribute.

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

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

Warning

TriSpectralPowerDistribution.shape is read only.

Examples

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

title

Property for self.__title private attribute.

Returns:	self.__title.
Return type:	unicode

values

Property for self.values attribute.

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

Warning

TriSpectralPowerDistribution.values is read only.

wavelengths

Property for self.wavelengths attribute.

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

Warning

TriSpectralPowerDistribution.wavelengths is read only.

x

Property for self.x attribute.

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

Warning

TriSpectralPowerDistribution.x is read only.

y

Property for self.y attribute.

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

Warning

TriSpectralPowerDistribution.y is read only.

z

Property for self.z attribute.

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

Warning

TriSpectralPowerDistribution.z is read only.

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

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

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

Examples

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

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

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

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

Notes

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

Examples

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

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

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

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

See also

constant_spd()

Notes

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

Examples

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

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

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

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

See also

constant_spd()

Notes

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

Examples

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

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

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

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

Examples

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

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

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

Notes

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

References

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

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

Examples

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

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

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

Notes

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

References

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

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

Examples

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

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

Bases: colour.colorimetry.spectrum.TriSpectralPowerDistribution

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

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

l_bar¶

m_bar¶

s_bar¶

l_bar

Property for self.x attribute.

Returns:	self.x
Return type:	SpectralPowerDistribution

Warning

LMS_ConeFundamentals.l_bar is read only.

m_bar

Property for self.y attribute.

Returns:	self.y
Return type:	SpectralPowerDistribution

Warning

LMS_ConeFundamentals.m_bar is read only.

s_bar

Property for self.z attribute.

Returns:	self.z
Return type:	SpectralPowerDistribution

Warning

LMS_ConeFundamentals.s_bar is read only.

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

Bases: colour.colorimetry.spectrum.TriSpectralPowerDistribution

Implements support for the CIE RGB colour matching functions.

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

r_bar¶

g_bar¶

b_bar¶

b_bar

Property for self.z attribute.

Returns:	self.z
Return type:	SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.b_bar is read only.

g_bar

Property for self.y attribute.

Returns:	self.y
Return type:	SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.g_bar is read only.

r_bar

Property for self.x attribute.

Returns:	self.x
Return type:	SpectralPowerDistribution

Warning

RGB_ColourMatchingFunctions.r_bar is read only.

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

Bases: colour.colorimetry.spectrum.TriSpectralPowerDistribution

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

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

x_bar¶

y_bar¶

z_bar¶

x_bar

Property for self.x attribute.

Returns:	self.x
Return type:	SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.x_bar is read only.

y_bar

Property for self.y attribute.

Returns:	self.y
Return type:	SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.y_bar is read only.

z_bar

Property for self.z attribute.

Returns:	self.z
Return type:	SpectralPowerDistribution

Warning

XYZ_ColourMatchingFunctions.z_bar is read only.

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

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

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

colour.colorimetry.bandpass_correction_Stearns1988(spd)¶

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

References

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

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

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

Examples

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

colour.colorimetry.D_illuminant_relative_spd(xy)¶

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

References

[1]	Wyszecki, G., & Stiles, W. S. (2000). CIE Method of Calculating D-Illuminants. In Color Science: Concepts and Methods, Quantitative Data and Formulae (pp. 145–146). Wiley. ISBN:978-0471399186

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

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

Examples

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

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

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

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

Examples

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

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

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

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

Examples

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

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

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

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

Notes

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

Examples

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

colour.colorimetry.lightness_Glasser1958(Y, **kwargs)¶

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

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

Notes

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

References

[2]	Glasser, L. G., McKinney, A. H., Reilly, C. D., & Schnelle, P. D. (1958). Cube-Root Color Coordinate System. J. Opt. Soc. Am., 48(10), 736–740. doi:10.1364/JOSA.48.000736

Examples

>>> lightness_Glasser1958(10.08)  
36.2505626...

colour.colorimetry.lightness_Wyszecki1963(Y, **kwargs)¶

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

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

Notes

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

References

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

Examples

>>> lightness_Wyszecki1963(10.08)  
37.0041149...

colour.colorimetry.lightness_1976(Y, Y_n=100)¶

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

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

Notes

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

References

[4]	Wyszecki, G., & Stiles, W. S. (2000). CIE 1976 (Luv*)-Space and Color-Difference Formula. In Color Science: Concepts and Methods, Quantitative Data and Formulae (p. 167). Wiley. ISBN:978-0471399186

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

Examples

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

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

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

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

Notes

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

Examples

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

colour.colorimetry.luminance_Newhall1943(V, **kwargs)¶

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

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

Notes

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

References

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

Examples

>>> luminance_Newhall1943(3.74629715382)  
10.4089874...

colour.colorimetry.luminance_ASTMD153508(V, **kwargs)¶

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

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

Notes

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

References

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

Examples

>>> luminance_ASTMD153508(3.74629715382)  
10.1488096...

colour.colorimetry.luminance_1976(Lstar, Y_n=100)¶

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

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

Notes

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

References

[2]	Wyszecki, G., & Stiles, W. S. (2000). CIE 1976 (Luv*)-Space and Color-Difference Formula. In Color Science: Concepts and Methods, Quantitative Data and Formulae (p. 167). Wiley. ISBN:978-0471399186

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

Examples

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

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

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

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

Examples

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

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

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

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

Examples

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

colour.colorimetry.RGB_10_degree_cmfs_to_LMS_10_degree_cmfs(wavelength)¶

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

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

Notes

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

References

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

Examples

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

colour.colorimetry.RGB_2_degree_cmfs_to_XYZ_2_degree_cmfs(wavelength)¶

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

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

Notes

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

References

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

Examples

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

colour.colorimetry.RGB_10_degree_cmfs_to_XYZ_10_degree_cmfs(wavelength)¶

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

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

Notes

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

References

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

Examples

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

colour.colorimetry.LMS_2_degree_cmfs_to_XYZ_2_degree_cmfs(wavelength)¶

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

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

Notes

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

References

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

Examples

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

colour.colorimetry.LMS_10_degree_cmfs_to_XYZ_10_degree_cmfs(wavelength)¶

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

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

Notes

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

References

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

Examples

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

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

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

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

Warning

The output domain of that definition is non standard!

Notes

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

References

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

Examples

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

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

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

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

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

Notes

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

Examples

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

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

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

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

Examples

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

colour.colorimetry.whiteness_Berger1959(XYZ, XYZ_0)¶

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

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

Notes

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

Warning

The input domain of that definition is non standard!

Examples

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

colour.colorimetry.whiteness_Taube1960(XYZ, XYZ_0)¶

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

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

Notes

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

Examples

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

colour.colorimetry.whiteness_Stensby1968(Lab)¶

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

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

Notes

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

Examples

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

colour.colorimetry.whiteness_ASTM313(XYZ)¶

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

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

Notes

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

Warning

The input domain of that definition is non standard!

Examples

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

colour.colorimetry.whiteness_Ganz1979(xy, Y)¶

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

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

Notes

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

Warning

The input domain of that definition is non standard!

Examples

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

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

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

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

Notes

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

Warning

The input domain of that definition is non standard!

References

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

Examples

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

colour.colorimetry Package¶

Sub-Packages¶

Sub-Modules¶

Module Contents¶