colour.algebra Package¶

Sub-Packages¶

Sub-Modules¶

Module Contents¶

colour.algebra.cartesian_to_spherical(vector)¶

Transforms given Cartesian coordinates vector to Spherical coordinates.

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

See also

spherical_to_cartesian(), cartesian_to_cylindrical(), cylindrical_to_cartesian()

Examples

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

colour.algebra.spherical_to_cartesian(vector)¶

Transforms given Spherical coordinates vector to Cartesian coordinates.

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

See also

cartesian_to_spherical(), cartesian_to_cylindrical(), cylindrical_to_cartesian()

Examples

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

colour.algebra.cartesian_to_cylindrical(vector)¶

Transforms given Cartesian coordinates vector to Cylindrical coordinates.

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

See also

cartesian_to_spherical(), spherical_to_cartesian(), cylindrical_to_cartesian()

Examples

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

colour.algebra.cylindrical_to_cartesian(vector)¶

Transforms given Cylindrical coordinates vector to Cartesian coordinates.

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

See also

cartesian_to_spherical(), spherical_to_cartesian(), cartesian_to_cylindrical()

Examples

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

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

Bases: object

Extrapolates the 1-D function of given interpolator.

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

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

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

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

__class__()¶

Notes

The interpolator must define x and y attributes.

References

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

Examples

Extrapolating a single numeric variable:

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

Extrapolating an array_like variable:

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

Using the Constant extrapolation method:

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

Using defined left boundary and Constant extrapolation method:

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

__call__(x)¶

Evaluates the Extrapolator1d at given point(s).

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

interpolator¶

Property for self.__interpolator private attribute.

Returns:	self.__interpolator
Return type:	object

left¶

Property for self.__left private attribute.

Returns:	self.__left
Return type:	numeric

method¶

Property for self.__method private attribute.

Returns:	self.__method
Return type:	unicode

right¶

Property for self.__right private attribute.

Returns:	self.__right
Return type:	numeric

class colour.algebra.LinearInterpolator(x=None, y=None)¶

Bases: object

Linearly interpolates a 1-D function.

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

__call__()¶

Notes

This class is a wrapper around numpy.interp definition.

See also

SpragueInterpolator

Examples

Interpolating a single numeric variable:

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

Interpolating an array_like variable:

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

__call__(x)

Evaluates the interpolating polynomial at given point(s).

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

x¶

Property for self.__x private attribute.

Returns:	self.__x
Return type:	array_like

y¶

Property for self.__y private attribute.

Returns:	self.__y
Return type:	array_like

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

Bases: object

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

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

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

__call__()¶

See also

LinearInterpolator

Notes

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

References

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

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

Examples

Interpolating a single numeric variable:

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

Interpolating an array_like variable:

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

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

__call__(x)

Evaluates the interpolating polynomial at given point(s).

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

x¶

Property for self.__x private attribute.

Returns:	self.__x
Return type:	array_like

y¶

Property for self.__y private attribute.

Returns:	self.__y
Return type:	array_like

class colour.algebra.CubicSplineInterpolator(*args, **kwargs)¶

Bases: scipy.interpolate.interpolate.interp1d

Interpolates a 1-D function using cubic spline interpolation.

Notes

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

class colour.algebra.PchipInterpolator(x, y, axis=0, extrapolate=None)¶

Bases: object

PCHIP 1-d monotonic cubic interpolation

x and y are arrays of values used to approximate some function f, with y = f(x). The interpolant uses monotonic cubic splines to find the value of new points. (PCHIP stands for Piecewise Cubic Hermite Interpolating Polynomial).

Parameters:

x (ndarray) – A 1-D array of monotonically increasing real values. x cannot include duplicate values (otherwise f is overspecified) y (ndarray) – A 1-D array of real values. y‘s length along the interpolation axis must be equal to the length of x. If N-D array, use axis parameter to select correct axis. axis (int, optional) – Axis in the y array corresponding to the x-coordinate values. extrapolate (bool, optional) – Whether to extrapolate to ouf-of-bounds points based on first and last intervals, or to return NaNs.

__call__()¶

derivative()¶

Notes

The first derivatives are guaranteed to be continuous, but the second derivatives may jump at x_k.

Preserves monotonicity in the interpolation data and does not overshoot if the data is not smooth.

Determines the derivatives at the points x_k, d_k, by using PCHIP algorithm:

Let m_k be the slope of the kth segment (between k and k+1) If m_k=0 or m_{k-1}=0 or sgn(m_k) != sgn(m_{k-1}) then d_k == 0 else use weighted harmonic mean:

w_1 = 2h_k + h_{k-1}, w_2 = h_k + 2h_{k-1} 1/d_k = 1/(w_1 + w_2)*(w_1 / m_k + w_2 / m_{k-1})

where h_k is the spacing between x_k and x_{k+1}.

__call__(x, der=0, extrapolate=None)

Evaluate the PCHIP interpolant or its derivative.

Parameters:	x (array-like) – Points to evaluate the interpolant at. der (int, optional) – Order of derivative to evaluate. Must be non-negative. extrapolate (bool, optional) – Whether to extrapolate to ouf-of-bounds points based on first and last intervals, or to return NaNs.
Returns:	y – Interpolated values. Shape is determined by replacing the interpolation axis in the original array with the shape of x.
Return type:	array-like

derivative(der=1)

Construct a piecewise polynomial representing the derivative.

Parameters:	der (int, optional) – Order of derivative to evaluate. (Default: 1) If negative, the antiderivative is returned.
Returns:	Piecewise polynomial of order k2 = k - der representing the derivative of this polynomial.

roots()¶

Return the roots of the interpolated function.

colour.algebra.is_identity(x, n=3)¶

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

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

Examples

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

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

[0, 1],

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

Returns a generator yielding random triplets.

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

Notes

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

Examples

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