# colour.algebra Package¶

## Module Contents¶

colour.algebra.cartesian_to_spherical(vector)[source]

Transforms given Cartesian coordinates vector to Spherical coordinates.

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

Examples

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

colour.algebra.spherical_to_cartesian(vector)[source]

Transforms given Spherical coordinates vector to Cartesian coordinates.

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

Examples

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

colour.algebra.cartesian_to_cylindrical(vector)[source]

Transforms given Cartesian coordinates vector to Cylindrical coordinates.

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

Examples

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

colour.algebra.cylindrical_to_cartesian(vector)[source]

Transforms given Cylindrical coordinates vector to Cartesian coordinates.

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

Examples

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

class colour.algebra.Extrapolator(interpolator=None, method=u'Linear', left=None, right=None)[source]

Bases: object

Extrapolates the 1-D function of given interpolator.

The Extrapolator class 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 = Extrapolator(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 = Extrapolator(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 = Extrapolator(interpolator, method='Constant', left=0)
>>> extrapolator(np.array([0.1, 0.2, 8, 9]))
array([ 0.,  0.,  3.,  3.])

__call__(x)[source]

Evaluates the Extrapolator at given point(s).

Parameters: x (numeric or array_like) – Point(s) to evaluate the Extrapolator at. Extrapolated points value(s). float or ndarray
interpolator

Property for self.__interpolator private attribute.

Returns: self.__interpolator object
left

Property for self.__left private attribute.

Returns: self.__left numeric
method

Property for self.__method private attribute.

Returns: self.__method unicode
right

Property for self.__right private attribute.

Returns: self.__right numeric
class colour.algebra.LinearInterpolator(x=None, y=None)[source]

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__()[source]

Notes

This class is a wrapper around numpy.interp definition.

Examples

Interpolating a single numeric variable:

>>> y = np.array([5.9200,
...               9.3700,
...               10.8135,
...               4.5100,
...               69.5900,
...               27.8007,
...               86.0500])
>>> x = np.arange(len(y))
>>> f = 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)[source]

Evaluates the interpolating polynomial at given point(s).

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

Property for self.__x private attribute.

Returns: self.__x array_like
y

Property for self.__y private attribute.

Returns: self.__y array_like
class colour.algebra.SpragueInterpolator(x=None, y=None)[source]

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__()[source]

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

Evaluates the interpolating polynomial at given point(s).

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

Property for self.__x private attribute.

Returns: self.__x array_like
y

Property for self.__y private attribute.

Returns: self.__y array_like
colour.algebra.is_identity(x, n=3)[source]

Returns if given array_like variable $$x$$ is an identity matrix.

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

Examples

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

colour.algebra.random_triplet_generator(size, limits=array([[0, 1], [0, 1], [0, 1]]), random_state=<mtrand.RandomState object>)[source]

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. Random triplets generator. 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...]))