colour.utilities Package¶
Sub-Modules¶
Module Contents¶
-
colour.utilities.
handle_numpy_errors
(**kwargs)[source]¶ Decorator for handling Numpy errors.
Other Parameters: **kwargs (dict, optional) – Keywords arguments. Returns: Return type: object References
[1] Kienzle, P., Patel, N., & Krycka, J. (2011). refl1d.numpyerrors - Refl1D v0.6.19 documentation. Retrieved January 30, 2015, from http://www.reflectometry.org/danse/docs/refl1d/_modules/refl1d/numpyerrors.html Examples
>>> import numpy >>> @handle_numpy_errors(all='ignore') ... def f(): ... 1 / numpy.zeros(3) >>> f()
-
colour.utilities.
ignore_numpy_errors
(function)¶ Wrapper for given function.
-
colour.utilities.
raise_numpy_errors
(function)¶ Wrapper for given function.
-
colour.utilities.
print_numpy_errors
(function)¶ Wrapper for given function.
-
colour.utilities.
warn_numpy_errors
(function)¶ Wrapper for given function.
-
colour.utilities.
ignore_python_warnings
(function)[source]¶ Decorator for ignoring Python warnings.
Parameters: function (object) – Function to decorate. Returns: Return type: object Examples
>>> @ignore_python_warnings ... def f(): ... warnings.warn('This is an ignored warning!') >>> f()
-
colour.utilities.
batch
(iterable, k=3)[source]¶ Returns a batch generator from given iterable.
Parameters: - iterable (iterable) – Iterable to create batches from.
- k (integer) – Batches size.
Returns: Is string_like variable.
Return type: Examples
>>> batch(tuple(range(10))) <generator object batch at 0x...>
-
colour.utilities.
is_openimageio_installed
(raise_exception=False)[source]¶ Returns if OpenImageIO is installed and available.
Parameters: raise_exception (bool) – Raise exception if OpenImageIO is unavailable. Returns: Is OpenImageIO installed. Return type: bool Raises: ImportError
– If OpenImageIO is not installed.
-
colour.utilities.
is_iterable
(a)[source]¶ Returns if given \(a\) variable is iterable.
Parameters: a (object) – Variable to check the iterability. Returns: \(a\) variable iterability. Return type: bool Examples
>>> is_iterable([1, 2, 3]) True >>> is_iterable(1) False
-
colour.utilities.
is_string
(a)[source]¶ Returns if given \(a\) variable is a string like variable.
Parameters: a (object) – Data to test. Returns: Is \(a\) variable a string like variable. Return type: bool Examples
>>> is_string('I`m a string!') True >>> is_string(['I`m a string!']) False
-
colour.utilities.
is_numeric
(a)[source]¶ Returns if given \(a\) variable is a number.
Parameters: a (object) – Variable to check. Returns: Is \(a\) variable a number. Return type: bool See also
Examples
>>> is_numeric(1) True >>> is_numeric((1,)) False
-
colour.utilities.
is_integer
(a)[source]¶ Returns if given \(a\) variable is an integer under given threshold.
Parameters: a (object) – Variable to check. Returns: Is \(a\) variable an integer. Return type: bool Notes
- The determination threshold is defined by the
colour.algebra.common.INTEGER_THRESHOLD
attribute.
See also
Examples
>>> is_integer(1) True >>> is_integer(1.01) False
- The determination threshold is defined by the
-
colour.utilities.
filter_kwargs
(function, **kwargs)[source]¶ Filters keyword arguments incompatible with the given function signature.
Parameters: function (callable) – Callable to filter the incompatible keyword arguments. Other Parameters: **kwargs (dict, optional) – Keywords arguments. Returns: Filtered keyword arguments. Return type: dict Examples
>>> def fn_a(a): ... return a >>> def fn_b(a, b=0): ... return a, b >>> def fn_c(a, b=0, c=0): ... return a, b, c >>> fn_a(1, **filter_kwargs(fn_a, b=2, c=3)) 1 >>> fn_b(1, **filter_kwargs(fn_b, b=2, c=3)) (1, 2) >>> fn_c(1, **filter_kwargs(fn_c, b=2, c=3)) (1, 2, 3)
-
colour.utilities.
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: Returns: \(a\) variable converted to numeric.
Return type: ndarray
See also
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.
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.
Returns: math:a variable converted to namedtuple.
Return type: 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.
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.
Returns: Closest \(a\) variable element.
Return type: numeric
Examples
>>> a = np.array([24.31357115, ... 63.62396289, ... 55.71528816, ... 62.70988028, ... 46.84480573, ... 25.40026416]) >>> closest(a, 63) 62.70988028
-
colour.utilities.
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’].
Returns: Maximum normalised \(a\) variable.
Return type: ndarray
Examples
>>> a = np.array([0.48222001, 0.31654775, 0.22070353]) >>> normalise_maximum(a) array([ 1. , 0.6564384..., 0.4576822...])
-
colour.utilities.
interval
(distribution)[source]¶ Returns the interval size of given distribution.
Parameters: distribution (array_like) – Distribution to retrieve the interval. Returns: Distribution interval. Return type: 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.
is_uniform
(distribution)[source]¶ Returns if given distribution is uniform.
Parameters: distribution (array_like) – Distribution to check for uniformity. Returns: Is distribution uniform. Return type: 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.
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.
Returns: A boolean array with a shape describing whether an element of a is present in b within given tolerance.
Return type: 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.
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. Returns: Return type: ndarray See also
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.
tsplit
(a)[source]¶ Splits arrays in sequence along the last axis (tail).
Parameters: a (array_like) – Array to perform the splitting. Returns: Return type: ndarray See also
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.
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. Returns: Return type: 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.
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.
Returns: Return type: ndarray
See also
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.
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.
Returns: Return type: ndarray
See also
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.
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.
Returns: Oriented array.
Return type: 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.
centroid
(a)[source]¶ Computes the centroid indexes of given \(a\) array.
Parameters: a (array_like) – \(a\) array to compute the centroid indexes. Returns: \(a\) array centroid indexes. Return type: ndarray Examples
>>> a = np.tile(np.arange(0, 5), (5, 1)) >>> centroid(a) array([2, 3])
-
colour.utilities.
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.
Returns: Return type: 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.])
-
class
colour.utilities.
ArbitraryPrecisionMapping
(data=None, key_decimals=0, **kwargs)[source]¶ Bases:
_abcoll.MutableMapping
Implements a mutable mapping / dict like object where numeric keys are stored with an arbitrary precision.
Parameters: Other Parameters: **kwargs (dict, optional) – Key / Value pairs to store into the mapping at initialisation.
-
key_decimals
¶
Examples
>>> data1 = {0.1999999998: 'Nemo', 0.2000000000: 'John'} >>> apm1 = ArbitraryPrecisionMapping(data1, key_decimals=10) >>> # Doctests skip for Python 2.x compatibility. >>> tuple(apm1.keys()) (0.1999999998, 0.2) >>> apm2 = ArbitraryPrecisionMapping(data1, key_decimals=7) >>> # Doctests skip for Python 2.x compatibility. >>> tuple(apm2.keys()) (0.2,)
-
data
¶ Property for self.data attribute.
Returns: ArbitraryPrecisionMapping
data structure.Return type: dict Warning
ArbitraryPrecisionMapping.data
is read only.
-
key_decimals
Property for self._key_decimals private attribute.
Returns: self._key_decimals. Return type: unicode
-
-
class
colour.utilities.
Lookup
[source]¶ Bases:
dict
Extends dict type to provide a lookup by value(s).
References
[2] Mansencal, T. (n.d.). Lookup. Retrieved from https://github.com/KelSolaar/Foundations/blob/develop/foundations/data_structures.py Examples
>>> person = Lookup(first_name='Doe', last_name='John', gender='male') >>> person.first_key_from_value('Doe') 'first_name' >>> persons = Lookup(John='Doe', Jane='Doe', Luke='Skywalker') >>> sorted(persons.keys_from_value('Doe')) ['Jane', 'John']
-
class
colour.utilities.
Structure
(*args, **kwargs)[source]¶ Bases:
dict
Defines an object similar to C/C++ structured type.
Other Parameters: - *args (list, optional) – Arguments.
- **kwargs (dict, optional) – Key / Value pairs.
References
[1] Mansencal, T. (n.d.). Structure. Retrieved from https://github.com/KelSolaar/Foundations/blob/develop/foundations/data_structures.py Examples
>>> person = Structure(first_name='Doe', last_name='John', gender='male') >>> # Doctests skip for Python 2.x compatibility. >>> person.first_name 'Doe' >>> sorted(person.keys()) ['first_name', 'gender', 'last_name'] >>> # Doctests skip for Python 2.x compatibility. >>> person['gender'] 'male'
-
update
(*args, **kwargs)[source] Updates both keys and sibling attributes.
Other Parameters: - *args (list, optional) – Arguments.
- **kwargs (dict, optional) – Keywords arguments.
Notes
- Reimplements the
dict.update()
method.
-
class
colour.utilities.
CaseInsensitiveMapping
(data=None, **kwargs)[source]¶ Bases:
_abcoll.MutableMapping
Implements a case-insensitive mutable mapping / dict object.
Allows values retrieving from keys while ignoring the key case. The keys are expected to be unicode or string-like objects supporting the
str.lower()
method.Parameters: data (dict) – dict of data to store into the mapping at initialisation. Other Parameters: **kwargs (dict, optional) – Key / Value pairs to store into the mapping at initialisation. Warning
The keys are expected to be unicode or string-like objects.
References
[3] Reitz, K. (n.d.). CaseInsensitiveDict. Retrieved from https://github.com/kennethreitz/requests/blob/v1.2.3/requests/structures.py#L37 Examples
>>> methods = CaseInsensitiveMapping({'McCamy': 1, 'Hernandez': 2}) >>> methods['mccamy'] 1
-
copy
()[source] Returns a copy of the mapping.
Returns: Mapping copy. Return type: CaseInsensitiveMapping Notes
- The
CaseInsensitiveMapping
class copy returned is a simple copy not a deepcopy.
- The
-
data
¶ Property for self.data attribute.
Returns: ArbitraryPrecisionMapping
data structure.Return type: dict Warning
ArbitraryPrecisionMapping.data
is read only.
-
lower_items
()[source] Iterates over the lower items names.
Returns: Lower item names. Return type: generator
-
-
exception
colour.utilities.
ColourWarning
[source]¶ Bases:
exceptions.Warning
This is the base class of Colour warnings. It is a subclass of Warning.
-
colour.utilities.
message_box
(message, width=79, padding=3)[source]¶ Prints a message inside a box.
Parameters: - message (unicode) – Message to print.
- width (int, optional) – Message box width.
- padding (unicode) – Padding on each sides of the message.
Returns: Definition success.
Return type: Examples
>>> message = ('Lorem ipsum dolor sit amet, consectetur adipiscing elit, ' ... 'sed do eiusmod tempor incididunt ut labore et dolore magna ' ... 'aliqua.') >>> message_box(message, width=75) =========================================================================== * * * Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do * * eiusmod tempor incididunt ut labore et dolore magna aliqua. * * * =========================================================================== True >>> message_box(message, width=60) ============================================================ * * * Lorem ipsum dolor sit amet, consectetur adipiscing * * elit, sed do eiusmod tempor incididunt ut labore et * * dolore magna aliqua. * * * ============================================================ True >>> message_box(message, width=75, padding=16) =========================================================================== * * * Lorem ipsum dolor sit amet, consectetur * * adipiscing elit, sed do eiusmod tempor * * incididunt ut labore et dolore magna * * aliqua. * * * =========================================================================== True
-
colour.utilities.
warning
(*args, **kwargs)[source]¶ Issues a warning.
Other Parameters: - *args (list, optional) – Arguments.
- **kwargs (dict, optional) – Keywords arguments.
Returns: Definition success.
Return type: Examples
>>> warning('This is a warning!') /Users/.../colour/utilities/verbose.py:132: UserWarning: This is a warning!
-
colour.utilities.
filter_warnings
(state=True, colour_warnings_only=True)[source]¶ Filters Colour and also optionally overall Python warnings.
Parameters: Returns: Definition success.
Return type: Examples
# Filtering Colour only warnings: >>> filter_warnings() True
# Filtering Colour and also Python warnings: >>> filter_warnings(colour_warnings_only=False) True