colour.algebra Package¶

Sub-Packages¶

colour.algebra.coordinates Package
- Sub-Modules
  - colour.algebra.coordinates.transformations Module
    - Coordinates System Transformations
- Module Contents

Sub-Modules¶

Module Contents¶

colour.algebra.cartesian_to_spherical(a)[source]¶

Transforms given Cartesian coordinates array to Spherical coordinates.

Parameters:	a (array_like) – Cartesian coordinates array (x, y, z) to transform.
Returns:	Spherical coordinates array (r, theta, phi).
Return type:	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 to Cartesian coordinates.

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

Examples

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

colour.algebra.cartesian_to_cylindrical(a)[source]¶

Transforms given Cartesian coordinates array to Cylindrical coordinates.

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

Examples

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

colour.algebra.cylindrical_to_cartesian(a)[source]¶

Transforms given Cylindrical coordinates array to Cartesian coordinates.

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

Examples

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

__call__(x)[source]¶

Evaluates the Extrapolator at given point(s).

Parameters:	x (numeric or array_like) – Point(s) to evaluate the Extrapolator 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

colour.algebra.normalise_vector(a)[source]¶

Normalises given vector \(a\).

Parameters:	a (array_like) – Vector \(a\) to normalise.
Returns:	Normalised vector \(a\).
Return type:	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\).
Returns:	Euclidean distance.
Return type:	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.
Returns:	New end point.
Return type:	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]¶

Bases: colour.algebra.geometry.LineSegmentsIntersections_Specification

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.

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.
Returns:	Line segments intersections specification.
Return type:	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.

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

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

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

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

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.
Returns:
Return type:	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.
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

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