# colour.algebra Package¶

## Module Contents¶

colour.algebra.cartesian_to_spherical(a)[source]

Transforms given Cartesian coordinates array $$xyz$$ to Spherical coordinates array $$\rho\theta\phi$$ (radial distance, inclination or elevation and azimuth).

Parameters: a (array_like) – Cartesian coordinates array $$xyz$$ to transform. Spherical coordinates array $$\rho\theta\phi$$. ndarray

Examples

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

colour.algebra.spherical_to_cartesian(a)[source]

Transforms given Spherical coordinates array $$\rho\theta\phi$$ (radial distance, inclination or elevation and azimuth) to Cartesian coordinates array $$xyz$$.

Parameters: a (array_like) – Spherical coordinates array $$\rho\theta\phi$$ to transform. Cartesian coordinates array $$xyz$$. ndarray

Examples

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

colour.algebra.cartesian_to_polar(a)[source]

Transforms given Cartesian coordinates array $$xy$$ to Polar coordinates array $$\rho\phi$$ (radial coordinate, angular coordinate).

Parameters: a (array_like) – Cartesian coordinates array $$xy$$ to transform. Polar coordinates array $$\rho\phi$$. ndarray

Examples

>>> a = np.array([3, 1])
>>> cartesian_to_polar(a)
array([ 3.1622776...,  0.3217505...])

colour.algebra.polar_to_cartesian(a)[source]

Transforms given Polar coordinates array $$\rho\phi$$ (radial coordinate, angular coordinate) to Cartesian coordinates array $$xy$$.

Parameters: a (array_like) – Polar coordinates array $$\rho\phi$$ to transform. Cartesian coordinates array $$xy$$. ndarray

Examples

>>> a = np.array([3.16227766, 0.32175055])
>>> polar_to_cartesian(a)
array([ 3.        ,  0.9999999...])

colour.algebra.cartesian_to_cylindrical(a)[source]

Transforms given Cartesian coordinates array $$xyz$$ to Cylindrical coordinates array $$\rho\phi z$$ (azimuth, radial distance and height).

Parameters: a (array_like) – Cartesian coordinates array $$xyz$$ to transform. Cylindrical coordinates array $$\rho\phi z$$. ndarray

Examples

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

colour.algebra.cylindrical_to_cartesian(a)[source]

Transforms given Cylindrical coordinates array $$\rho\phi z$$ (azimuth, radial distance and height) to Cartesian coordinates array $$xyz$$.

Parameters: a (array_like) – Cylindrical coordinates array $$\rho\phi z$$ to transform. Cartesian coordinates array $$xyz$$. ndarray

Examples

>>> a = np.array([3.16227766, 0.32175055, 6.00000000])
>>> cylindrical_to_cartesian(a)
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.])

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
colour.algebra.normalise_vector(a)[source]

Normalises given vector $$a$$.

Parameters: a (array_like) – Vector $$a$$ to normalise. Normalised vector $$a$$. ndarray

Examples

>>> a = np.array([0.07049534, 0.10080000, 0.09558313])
>>> normalise_vector(a)
array([ 0.4525410...,  0.6470802...,  0.6135908...])

colour.algebra.euclidean_distance(a, b)[source]

Returns the euclidean distance between point arrays $$a$$ and $$b$$.

Parameters: a (array_like) – Point array $$a$$. b (array_like) – Point array $$b$$. Euclidean distance. numeric or ndarray

Examples

>>> a = np.array([100.00000000, 21.57210357, 272.22819350])
>>> b = np.array([100.00000000, 426.67945353, 72.39590835])
>>> euclidean_distance(a, b)
451.7133019...

colour.algebra.extend_line_segment(a, b, distance=1)[source]

Extends the line segment defined by point arrays $$a$$ and $$b$$ by given distance and return the new end point.

Parameters: a (array_like) – Point array $$a$$. b (array_like) – Point array $$b$$. distance (numeric, optional) – Distance to extend the line segment. New end point. ndarray

References

 [1] Saeedn. (n.d.). Extend a line segment a specific distance. Retrieved January 16, 2016, from http://stackoverflow.com/questions/7740507/extend-a-line-segment-a-specific-distance

Notes

• Input line segment points coordinates are 2d coordinates.

Examples

>>> a = np.array([0.95694934, 0.13720932])
>>> b = np.array([0.28382835, 0.60608318])
>>> extend_line_segment(a, b)
array([-0.5367248...,  1.1776534...])

class colour.algebra.LineSegmentsIntersections_Specification[source]

Defines the specification for intersection of line segments $$l_1$$ and $$l_2$$ returned by intersect_line_segments() definition.

Parameters: xy (array_like) – Array of $$l_1$$ and $$l_2$$ line segments intersections coordinates. Non existing segments intersections coordinates are set with np.nan. intersect (array_like) – Array of bool indicating if line segments $$l_1$$ and $$l_2$$ intersect. parallel (array_like) – Array of bool indicating if line segments $$l_1$$ and $$l_2$$ are parallel. coincident (array_like) – Array of bool indicating if line segments $$l_1$$ and $$l_2$$ are coincident.

Create new instance of LineSegmentsIntersections_Specification(xy, intersect, parallel, coincident)

colour.algebra.intersect_line_segments(l_1, l_2)[source]

Computes $$l_1$$ line segments intersections with $$l_2$$ line segments.

Parameters: l_1 (array_like) – $$l_1$$ line segments array, each row is a line segment such as ($$x_1$$, $$y_1$$, $$x_2$$, $$y_2$$) where ($$x_1$$, $$y_1$$) and ($$x_2$$, $$y_2$$) are respectively the start and end points of $$l_1$$ line segments. l_2 (array_like) – $$l_2$$ line segments array, each row is a line segment such as ($$x_3$$, $$y_3$$, $$x_4$$, $$y_4$$) where ($$x_3$$, $$y_3$$) and ($$x_4$$, $$y_4$$) are respectively the start and end points of $$l_2$$ line segments. Line segments intersections specification. LineSegmentsIntersections_Specification

References

 [2] Bourke, P. (n.d.). Intersection point of two line segments in 2 dimensions. Retrieved January 15, 2016, from http://paulbourke.net/geometry/pointlineplane/
 [3] Erdem, U. M. (n.d.). Fast Line Segment Intersection. Retrieved January 15, 2016, from http://www.mathworks.com/matlabcentral/fileexchange/27205-fast-line-segment-intersection

Notes

• Input line segments points coordinates are 2d coordinates.

Examples

>>> l_1 = np.array([[[0.15416284, 0.7400497],
...                  [0.26331502, 0.53373939]],
...                 [[0.01457496, 0.91874701],
...                  [0.90071485, 0.03342143]]])
>>> l_2 = np.array([[[0.95694934, 0.13720932],
...                  [0.28382835, 0.60608318]],
...                 [[0.94422514, 0.85273554],
...                  [0.00225923, 0.52122603]],
...                 [[0.55203763, 0.48537741],
...                  [0.76813415, 0.16071675]]])
>>> s = intersect_line_segments(l_1, l_2)
>>> s.xy
array([[[        nan,         nan],
[ 0.2279184...,  0.6006430...],
[        nan,         nan]],

[[ 0.4281451...,  0.5055568...],
[ 0.3056055...,  0.6279838...],
[ 0.7578749...,  0.1761301...]]])
>>> s.intersect
array([[False,  True, False],
[ True,  True,  True]], dtype=bool)
>>> s.parallel
array([[False, False, False],
[False, False, False]], dtype=bool)
>>> s.coincident
array([[False, False, False],
[False, False, False]], dtype=bool)

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

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]])
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.lagrange_coefficients(r, n=4)[source]

Computes the Lagrange Coefficients at given point $$r$$ for degree $$n$$.

Parameters: r (numeric) – Point to get the Lagrange Coefficients at. n (int, optional) – Degree of the Lagrange Coefficients being calculated. ndarray

References

 [4] Fairman, H. S. (1985). The calculation of weight factors for tristimulus integration. Color Research & Application, 10(4), 199–203. doi:10.1002/col.5080100407
 [5] Wikipedia. (n.d.). Lagrange polynomial - Definition. Retrieved January 20, 2016, from https://en.wikipedia.org/wiki/Lagrange_polynomial#Definition

Examples

>>> lagrange_coefficients(0.1)
array([ 0.8265,  0.2755, -0.1305,  0.0285])

colour.algebra.is_identity(a, n=3)[source]

Returns if $$a$$ array is an identity matrix.

Parameters: a (array_like, (N)) – Variable $$a$$ 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

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