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.

is_caching_enabled()	Return whether Colour caching is enabled.
set_caching_enable(enable)	Set Colour caching enabled state.
caching_enable(enable)	Define a context manager and decorator temporarily setting Colour caching enabled state.
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_iterable(a)	Return whether given variable \(a\) is iterable.
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[, ...])	Validate whether given method exists in the given valid methods and optionally 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.DTYPE_INT_DEFAULT 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.DTYPE_FLOAT_DEFAULT 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.DTYPE_FLOAT_DEFAULT attribute.
ones(shape[, dtype, order])	Wrap np.ones() definition to create an array with the active numpy.dtype defined by the colour.constant.DTYPE_FLOAT_DEFAULT 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.DTYPE_FLOAT_DEFAULT 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.

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).
Structure(*args, **kwargs)	Define a dict-like object allowing to access key values using dot syntax.

Network

colour.utilities

TreeNode(*args, **kwargs)	Represent a basic node supporting the creation of basic node trees.
Port([name, value, description, node])	Define an object that can be added either as an input or output port, i.e., a pin, to a colour.utilities.PortNode class and connected to another input or output port.
PortNode(*args, **kwargs)	Define a node with support for input and output ports.
PortGraph(*args, **kwargs)	Define a node-graph for colour.utilities.PortNode class instances.

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

Requirements

colour.utilities

is_ctlrender_installed([raise_exception])	Return whether ctlrender 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_pydot_installed([raise_exception])	Return whether Pydot 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.

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.
as_bool(a)	Convert given string to bool.
suppress_warnings([colour_runtime_warnings, ...])	Define a context manager filtering Colour and also optionally overall Python warnings.
suppress_stdout()	Define a context manager and decorator temporarily suppressing standard output.
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

MixinLogging()	A mixin providing a convenient logging method.
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.