# colour.utilities.array Module¶

## Array Utilities¶

Defines array utilities objects.

colour.utilities.array.as_numeric(a, type_=<type 'numpy.float64'>)[source]

Converts given $$a$$ variable to numeric. In the event where $$a$$ cannot be converted, it is passed as is.

Parameters: a (object) – Variable to convert. type (object) – Type to use for conversion. $$a$$ variable converted to numeric. ndarray

as_stack(), as_shape(), auto_axis()

Examples

>>> as_numeric(np.array([1]))
1.0
>>> as_numeric(np.arange(10))
array([ 0.,  1.,  2.,  3.,  4.,  5.,  6.,  7.,  8.,  9.])

colour.utilities.array.as_namedtuple(a, named_tuple)[source]

Converts given $$a$$ variable to given namedtuple class instance.

$$a$$ can be either a Numpy structured array, a namedtuple, a mapping, or an array_like object. The definition will attempt to convert it to given namedtuple.

Parameters: a (object) – Variable to convert. named_tuple (namedtuple) – namedtuple class. math:a variable converted to namedtuple. namedtuple

Examples

>>> from collections import namedtuple
>>> a_a = 1
>>> a_b = 2
>>> a_c = 3
>>> NamedTuple = namedtuple('NamedTuple', 'a b c')
>>> as_namedtuple(NamedTuple(a=1, b=2, c=3), NamedTuple)
NamedTuple(a=1, b=2, c=3)
>>> as_namedtuple({'a': a_a, 'b': a_b, 'c': a_c}, NamedTuple)
NamedTuple(a=1, b=2, c=3)
>>> as_namedtuple([a_a, a_b, a_c], NamedTuple)
NamedTuple(a=1, b=2, c=3)

colour.utilities.array.closest(a, b)[source]

Returns closest $$a$$ variable element to reference $$b$$ variable.

Parameters: a (array_like) – Variable to search for the closest element. b (numeric) – Reference variable. Closest $$a$$ variable element. numeric

Examples

>>> a = np.array([24.31357115,
...               63.62396289,
...               55.71528816,
...               62.70988028,
...               46.84480573,
...               25.40026416])
>>> closest(a, 63)
62.70988028

colour.utilities.array.normalise_maximum(a, axis=None, factor=1, clip=True)[source]

Normalises given array_like $$a$$ variable values by $$a$$ variable maximum value and optionally clip them between.

Parameters: a (array_like) – $$a$$ variable to normalise. axis (numeric, optional) – Normalization axis. factor (numeric, optional) – Normalization factor. clip (bool, optional) – Clip values between in domain [0, ‘factor’]. Maximum normalised $$a$$ variable. ndarray

Examples

>>> a = np.array([0.48222001, 0.31654775, 0.22070353])
>>> normalise_maximum(a)
array([ 1.        ,  0.6564384...,  0.4576822...])

colour.utilities.array.interval(distribution)[source]

Returns the interval size of given distribution.

Parameters: distribution (array_like) – Distribution to retrieve the interval. Distribution interval. ndarray

Examples

Uniformly spaced variable:

>>> y = np.array([1, 2, 3, 4, 5])
>>> interval(y)
array([1])


Non-uniformly spaced variable:

>>> y = np.array([1, 2, 3, 4, 8])
>>> interval(y)
array([1, 4])

colour.utilities.array.is_uniform(distribution)[source]

Returns if given distribution is uniform.

Parameters: distribution (array_like) – Distribution to check for uniformity. Is distribution uniform. bool

Examples

Uniformly spaced variable:

>>> a = np.array([1, 2, 3, 4, 5])
>>> is_uniform(a)
True


Non-uniformly spaced variable:

>>> a = np.array([1, 2, 3.1415, 4, 5])
>>> is_uniform(a)
False

colour.utilities.array.in_array(a, b, tolerance=2.2204460492503131e-16)[source]

Tests whether each element of an array is also present in a second array within given tolerance.

Parameters: a (array_like) – Array to test the elements from. b (array_like) – The values against which to test each value of array a. tolerance (numeric, optional) – Tolerance value. A boolean array with a shape describing whether an element of a is present in b within given tolerance. ndarray

References

 [1] Yorke, R. (2014). Python: Change format of np.array or allow tolerance in in1d function. Retrieved March 27, 2015, from http://stackoverflow.com/a/23521245/931625

Examples

>>> a = np.array([0.50, 0.60])
>>> b = np.linspace(0, 10, 101)
>>> np.in1d(a, b)
array([ True, False], dtype=bool)
>>> in_array(a, b)
array([ True,  True], dtype=bool)

colour.utilities.array.tstack(a)[source]

Stacks arrays in sequence along the last axis (tail).

Rebuilds arrays divided by tsplit().

Parameters: a (array_like) – Array to perform the stacking. ndarray

Examples

>>> a = 0
>>> tstack((a, a, a))
array([0, 0, 0])
>>> a = np.arange(0, 6)
>>> tstack((a, a, a))
array([[0, 0, 0],
[1, 1, 1],
[2, 2, 2],
[3, 3, 3],
[4, 4, 4],
[5, 5, 5]])
>>> a = np.reshape(a, (1, 6))
>>> tstack((a, a, a))
array([[[0, 0, 0],
[1, 1, 1],
[2, 2, 2],
[3, 3, 3],
[4, 4, 4],
[5, 5, 5]]])
>>> a = np.reshape(a, (1, 1, 6))
>>> tstack((a, a, a))
array([[[[0, 0, 0],
[1, 1, 1],
[2, 2, 2],
[3, 3, 3],
[4, 4, 4],
[5, 5, 5]]]])

colour.utilities.array.tsplit(a)[source]

Splits arrays in sequence along the last axis (tail).

Parameters: a (array_like) – Array to perform the splitting. ndarray

Examples

>>> a = np.array([0, 0, 0])
>>> tsplit(a)
array([0, 0, 0])
>>> a = np.array([[0, 0, 0],
...               [1, 1, 1],
...               [2, 2, 2],
...               [3, 3, 3],
...               [4, 4, 4],
...               [5, 5, 5]])
>>> tsplit(a)
array([[0, 1, 2, 3, 4, 5],
[0, 1, 2, 3, 4, 5],
[0, 1, 2, 3, 4, 5]])
>>> a = np.array([[[0, 0, 0],
...                [1, 1, 1],
...                [2, 2, 2],
...                [3, 3, 3],
...                [4, 4, 4],
...                [5, 5, 5]]])
>>> tsplit(a)
array([[[0, 1, 2, 3, 4, 5]],

[[0, 1, 2, 3, 4, 5]],

[[0, 1, 2, 3, 4, 5]]])

colour.utilities.array.row_as_diagonal(a)[source]

Returns the per row diagonal matrices of the given array.

Parameters: a (array_like) – Array to perform the diagonal matrices computation. ndarray

References

 [1] Castro, S. (2014). Numpy: Fastest way of computing diagonal for each row of a 2d array. Retrieved August 22, 2014, from http://stackoverflow.com/questions/26511401/numpy-fastest-way-of-computing-diagonal-for-each-row-of-a-2d-array/26517247#26517247

Examples

>>> a = np.array([[0.25891593, 0.07299478, 0.36586996],
...               [0.30851087, 0.37131459, 0.16274825],
...               [0.71061831, 0.67718718, 0.09562581],
...               [0.71588836, 0.76772047, 0.15476079],
...               [0.92985142, 0.22263399, 0.88027331]])
>>> row_as_diagonal(a)
array([[[ 0.25891593,  0.        ,  0.        ],
[ 0.        ,  0.07299478,  0.        ],
[ 0.        ,  0.        ,  0.36586996]],

[[ 0.30851087,  0.        ,  0.        ],
[ 0.        ,  0.37131459,  0.        ],
[ 0.        ,  0.        ,  0.16274825]],

[[ 0.71061831,  0.        ,  0.        ],
[ 0.        ,  0.67718718,  0.        ],
[ 0.        ,  0.        ,  0.09562581]],

[[ 0.71588836,  0.        ,  0.        ],
[ 0.        ,  0.76772047,  0.        ],
[ 0.        ,  0.        ,  0.15476079]],

[[ 0.92985142,  0.        ,  0.        ],
[ 0.        ,  0.22263399,  0.        ],
[ 0.        ,  0.        ,  0.88027331]]])

colour.utilities.array.dot_vector(m, v)[source]

Convenient wrapper around np.einsum() with the following subscripts: ‘...ij,...j->...i’.

It performs the dot product of two arrays where m parameter is expected to be an array of 3x3 matrices and parameter v an array of vectors.

Parameters: m (array_like) – Array of 3x3 matrices. v (array_like) – Array of vectors. ndarray

Examples

>>> m = np.array([[0.7328, 0.4296, -0.1624],
...               [-0.7036, 1.6975, 0.0061],
...               [0.0030, 0.0136, 0.9834]])
>>> m = np.reshape(np.tile(m, (6, 1)), (6, 3, 3))
>>> v = np.array([0.07049534, 0.10080000, 0.09558313])
>>> v = np.tile(v, (6, 1))
>>> dot_vector(m, v)
array([[ 0.0794399...,  0.1220905...,  0.0955788...],
[ 0.0794399...,  0.1220905...,  0.0955788...],
[ 0.0794399...,  0.1220905...,  0.0955788...],
[ 0.0794399...,  0.1220905...,  0.0955788...],
[ 0.0794399...,  0.1220905...,  0.0955788...],
[ 0.0794399...,  0.1220905...,  0.0955788...]])

colour.utilities.array.dot_matrix(a, b)[source]

Convenient wrapper around np.einsum() with the following subscripts: ‘...ij,...jk->...ik’.

It performs the dot product of two arrays where a parameter is expected to be an array of 3x3 matrices and parameter b another array of of 3x3 matrices.

Parameters: a (array_like) – Array of 3x3 matrices. b (array_like) – Array of 3x3 matrices. ndarray

Examples

>>> a = np.array([[0.7328, 0.4296, -0.1624],
...               [-0.7036, 1.6975, 0.0061],
...               [0.0030, 0.0136, 0.9834]])
>>> a = np.reshape(np.tile(a, (6, 1)), (6, 3, 3))
>>> b = a
>>> dot_matrix(a, b)
array([[[ 0.2342420...,  1.0418482..., -0.2760903...],
[-1.7099407...,  2.5793226...,  0.1306181...],
[-0.0044203...,  0.0377490...,  0.9666713...]],

[[ 0.2342420...,  1.0418482..., -0.2760903...],
[-1.7099407...,  2.5793226...,  0.1306181...],
[-0.0044203...,  0.0377490...,  0.9666713...]],

[[ 0.2342420...,  1.0418482..., -0.2760903...],
[-1.7099407...,  2.5793226...,  0.1306181...],
[-0.0044203...,  0.0377490...,  0.9666713...]],

[[ 0.2342420...,  1.0418482..., -0.2760903...],
[-1.7099407...,  2.5793226...,  0.1306181...],
[-0.0044203...,  0.0377490...,  0.9666713...]],

[[ 0.2342420...,  1.0418482..., -0.2760903...],
[-1.7099407...,  2.5793226...,  0.1306181...],
[-0.0044203...,  0.0377490...,  0.9666713...]],

[[ 0.2342420...,  1.0418482..., -0.2760903...],
[-1.7099407...,  2.5793226...,  0.1306181...],
[-0.0044203...,  0.0377490...,  0.9666713...]]])

colour.utilities.array.orient(a, orientation)[source]

Orient given array accordingly to given orientation value.

Parameters: a (array_like) – Array to perform the orientation onto. orientation (unicode, optional) – {‘Flip’, ‘Flop’, ‘90 CW’, ‘90 CCW’, ‘180’} Orientation to perform. Oriented array. ndarray

Examples

>>> a = np.tile(np.arange(5), (5, 1))
>>> a
array([[0, 1, 2, 3, 4],
[0, 1, 2, 3, 4],
[0, 1, 2, 3, 4],
[0, 1, 2, 3, 4],
[0, 1, 2, 3, 4]])
>>> orient(a, '90 CW')
array([[0, 0, 0, 0, 0],
[1, 1, 1, 1, 1],
[2, 2, 2, 2, 2],
[3, 3, 3, 3, 3],
[4, 4, 4, 4, 4]])
>>> orient(a, 'Flip')
array([[4, 3, 2, 1, 0],
[4, 3, 2, 1, 0],
[4, 3, 2, 1, 0],
[4, 3, 2, 1, 0],
[4, 3, 2, 1, 0]])

colour.utilities.array.centroid(a)[source]

Computes the centroid indexes of given $$a$$ array.

Parameters: a (array_like) – $$a$$ array to compute the centroid indexes. $$a$$ array centroid indexes. ndarray

Examples

>>> a = np.tile(np.arange(0, 5), (5, 1))
>>> centroid(a)
array([2, 3])

colour.utilities.array.linear_conversion(a, old_range, new_range)[source]

Performs a simple linear conversion of given array between the old and new ranges.

Parameters: a (array_like) – Array to perform the linear conversion onto. old_range (array_like) – Old range. new_range (array_like) – New range. ndarray

Examples

>>> a = np.linspace(0, 1, 10)
>>> linear_conversion(a, np.array([0, 1]), np.array([1, 10]))
array([  1.,   2.,   3.,   4.,   5.,   6.,   7.,   8.,   9.,  10.])