Utilities

Callback Management

colour

colour.utilities

Callback(name, function)	Define a callback.
MixinCallback()	A mixin providing support for callbacks.

Common

colour

domain_range_scale(scale)	Define context manager and decorator temporarily setting Colour domain-range scale.
get_domain_range_scale()	Return the current Colour domain-range scale.
set_domain_range_scale([scale])	Set the current Colour domain-range scale.

colour.utilities

CacheRegistry()

A registry for mapping-based caches.

CACHE_REGISTRY	A registry for mapping-based caches.
handle_numpy_errors(**kwargs)	Decorate a function to handle Numpy errors.
ignore_numpy_errors(function)	Wrap given function wrapper.
raise_numpy_errors(function)	Wrap given function wrapper.
print_numpy_errors(function)	Wrap given function wrapper.
warn_numpy_errors(function)	Wrap given function wrapper.
ignore_python_warnings(function)	Decorate a function to ignore Python warnings.
attest(condition[, message])	Provide the assert statement functionality without being disabled by optimised Python execution.
batch(sequence[, k])	Return a batch generator from given sequence.
disable_multiprocessing()	Define a context manager and decorator to temporarily disabling Colour multiprocessing state.
multiprocessing_pool(*args, **kwargs)	Define a context manager providing a multiprocessing pool.
is_ctlrender_installed([raise_exception])	Return whether ctlrender is installed and available.
is_graphviz_installed([raise_exception])	Return whether Graphviz is installed and available.
is_matplotlib_installed([raise_exception])	Return whether Matplotlib is installed and available.
is_networkx_installed([raise_exception])	Return whether NetworkX is installed and available.
is_opencolorio_installed([raise_exception])	Return whether OpenColorIO is installed and available.
is_openimageio_installed([raise_exception])	Return whether OpenImageIO is installed and available.
is_pandas_installed([raise_exception])	Return whether Pandas is installed and available.
is_tqdm_installed([raise_exception])	Return whether tqdm is installed and available.
is_trimesh_installed([raise_exception])	Return whether Trimesh is installed and available.
is_xxhash_installed([raise_exception])	Return whether xxhash is installed and available.
required(*requirements)	Decorate a function to check whether various ancillary package requirements are satisfied.
is_iterable(a)	Return whether given variable \(a\) is iterable.
is_string(a)	Return whether given variable \(a\) is a str-like variable.
is_numeric(a)	Return whether given variable \(a\) is a Real-like variable.
is_integer(a)	Return whether given variable \(a\) is an numpy.integer-like variable under given threshold.
is_sibling(element, mapping)	Return whether given element type is present in given mapping types.
filter_kwargs(function, **kwargs)	Filter keyword arguments incompatible with the given function signature.
filter_mapping(mapping, names)	Filter given mapping with given names.
first_item(a)	Return the first item of given iterable.
copy_definition(definition[, name])	Copy a definition using the same code, globals, defaults, closure, and name.
validate_method(method, valid_methods[, message])	Validate whether given method exists in the given valid methods and returns the method lower cased.
optional(value, default)	Handle optional argument value by providing a default value.
slugify(object_[, allow_unicode])	Generate a SEO friendly and human-readable slug from given object.
int_digest(args[, seed])	Generate an integer digest for given argument using xxhash if available or falling back to hash() if not.

Array

colour.utilities

MixinDataclassFields()	A mixin providing fields introspection for the dataclass-like class fields.
MixinDataclassIterable()	A mixin providing iteration capabilities over the dataclass-like class fields.
MixinDataclassArray()	A mixin providing conversion methods for dataclass-like class conversion to numpy.ndarray class.
MixinDataclassArithmetic()	A mixin providing mathematical operations for dataclass-like class.

as_array(a[, dtype])	Convert given variable \(a\) to numpy.ndarray using given numpy.dtype.
as_int(a[, dtype])	Attempt to convert given variable \(a\) to numpy.integer using given numpy.dtype.
as_float(a[, dtype])	Attempt to convert given variable \(a\) to numpy.floating using given numpy.dtype.
as_int_array(a[, dtype])	Convert given variable \(a\) to numpy.ndarray using given numpy.dtype.
as_float_array(a[, dtype])	Convert given variable \(a\) to numpy.ndarray using given numpy.dtype.
as_int_scalar(a[, dtype])	Convert given \(a\) variable to numpy.integer using given numpy.dtype.
as_float_scalar(a[, dtype])	Convert given \(a\) variable to numpy.floating using given numpy.dtype.
set_default_int_dtype([dtype])	Set Colour default numpy.integer precision by setting colour.constant.DEFAULT_INT_DTYPE attribute with given numpy.dtype wherever the attribute is imported.
set_default_float_dtype([dtype])	Set Colour default numpy.floating precision by setting colour.constant.DEFAULT_FLOAT_DTYPE attribute with given numpy.dtype wherever the attribute is imported.
to_domain_1(a[, scale_factor, dtype])	Scale given array \(a\) to domain '1'.
to_domain_10(a[, scale_factor, dtype])	Scale given array \(a\) to domain '10', used by Munsell Renotation System.
to_domain_100(a[, scale_factor, dtype])	Scale given array \(a\) to domain '100'.
to_domain_degrees(a[, scale_factor, dtype])	Scale given array \(a\) to degrees domain.
to_domain_int(a[, bit_depth, dtype])	Scale given array \(a\) to int domain.
from_range_1(a[, scale_factor, dtype])	Scale given array \(a\) from range '1'.
from_range_10(a[, scale_factor, dtype])	Scale given array \(a\) from range '10', used by Munsell Renotation System.
from_range_100(a[, scale_factor, dtype])	Scale given array \(a\) from range '100'.
from_range_degrees(a[, scale_factor, dtype])	Scale given array \(a\) from degrees range.
from_range_int(a[, bit_depth, dtype])	Scale given array \(a\) from int range.
is_ndarray_copy_enabled()	Return whether Colour numpy.ndarray copy is enabled: Various API objects return a copy of their internal numpy.ndarray for safety purposes but this can be a slow operation impacting performance.
set_ndarray_copy_enable(enable)	Set Colour numpy.ndarray copy enabled state.
ndarray_copy_enable(enable)	Define a context manager and decorator temporarily setting Colour numpy.ndarray copy enabled state.
ndarray_copy(a)	Return a numpy.ndarray copy if the relevant Colour state is enabled: Various API objects return a copy of their internal numpy.ndarray for safety purposes but this can be a slow operation impacting performance.
closest_indexes(a, b)	Return the array \(a\) closest element indexes to the reference array \(b\) elements.
closest(a, b)	Return the closest array \(a\) elements to the reference array \(b\) elements.
interval(distribution[, unique])	Return the interval size of given distribution.
is_uniform(distribution)	Return whether given distribution is uniform.
has_only_nan(a)	Return whether given array \(a\) contains only NaN values.
in_array(a, b[, tolerance])	Return whether each element of the array \(a\) is also present in the array \(b\) within given tolerance.
tstack(a[, dtype])	Stack given array of arrays \(a\) along the last axis (tail) to produce a stacked array.
tsplit(a[, dtype])	Split given stacked array \(a\) along the last axis (tail) to produce an array of arrays.
row_as_diagonal(a)	Return the rows of given array \(a\) as diagonal matrices.
orient(a[, orientation])	Orient given array \(a\) according to given orientation.
centroid(a)	Return the centroid indexes of given array \(a\).
fill_nan(a[, method, default])	Fill given array \(a\) NaN values according to given method.
ndarray_write(a)	Define a context manager setting given array \(a\) writeable to operate one and then read-only.
zeros(shape[, dtype, order])	Wrap np.zeros() definition to create an array with the active numpy.dtype defined by the colour.constant.DEFAULT_FLOAT_DTYPE attribute.
ones(shape[, dtype, order])	Wrap np.ones() definition to create an array with the active numpy.dtype defined by the colour.constant.DEFAULT_FLOAT_DTYPE attribute.
full(shape, fill_value[, dtype, order])	Wrap np.full() definition to create an array with the active type defined by the:attr:colour.constant.DEFAULT_FLOAT_DTYPE attribute.
index_along_last_axis(a, indexes)	Reduce the dimension of array \(a\) by one, by using an array of indexes to pick elements off the last axis.
format_array_as_row(a[, decimals, separator])	Format given array \(a\) as a row.

Metrics

colour.utilities

metric_mse(a, b[, axis])	Compute the mean squared error (MSE) or mean squared deviation (MSD) between given variables \(a\) and \(b\).
metric_psnr(a, b[, max_a, axis])	Compute the peak signal-to-noise ratio (PSNR) between given variables \(a\) and \(b\).

Data Structures

colour.utilities

CanonicalMapping([data])	Implement a delimiter and case-insensitive dict-like object with support for slugs, i.e. SEO friendly and human-readable version of the keys but also canonical keys, i.e. slugified keys without delimiters.
LazyCanonicalMapping([data])	Implement a lazy delimiter and case-insensitive dict-like object inheriting from colour.utilities.CanonicalMapping class.
Lookup	Extend dict type to provide a lookup by value(s).
Node(*args, **kwargs)	Represent a basic node supporting the creation of basic node trees.
Structure(*args, **kwargs)	Define a dict-like object allowing to access key values using dot syntax.

Verbose

colour.utilities

message_box(message[, width, padding, ...])	Print a message inside a box.
show_warning(message, category, filename, lineno)	Alternative warnings.showwarning() definition that allows traceback printing.
warning(*args, **kwargs)	Issue a warning.
filter_warnings([colour_runtime_warnings, ...])	Filter Colour and also optionally overall Python warnings.
suppress_warnings([colour_runtime_warnings, ...])	Define a context manager filtering Colour and also optionally overall Python warnings.
numpy_print_options(*args, **kwargs)	Define a context manager implementing context changes to Numpy print behaviour.
describe_environment([runtime_packages, ...])	Describe Colour running environment, i.e. interpreter, runtime and development packages.
multiline_str(object_, attributes[, ...])	Return a formatted string representation of the given object.
multiline_repr(object_, attributes[, ...])	Return an (almost) evaluable string representation of the given object.

Ancillary Objects

colour.utilities

ColourWarning	Define the base class of Colour warnings.
ColourUsageWarning	Define the base class of Colour usage warnings.
ColourRuntimeWarning	Define the base class of Colour runtime warnings.