Utilities

Callback Management

colour

colour.utilities

Callback(name, function)	Represent a named callback with its associated callable function.
MixinCallback()	Provide callback support for attribute changes in classes.

Common

colour

domain_range_scale(scale)	Define a context manager and decorator to temporarily set the Colour domain-range scale.
get_domain_range_scale()	Return the current Colour domain-range scale.
get_domain_range_scale_metadata(function)	Extract domain-range scale metadata from function type hints.
set_domain_range_scale([scale])	Set the current Colour domain-range scale.

colour.utilities

CacheRegistry()

Provide a registry for managing mapping-based caches.

attest(condition[, message])	Provide the assert statement functionality without being disabled by optimised Python execution.
batch(sequence[, k])	Generate batches from the specified sequence.
CACHE_REGISTRY	Provide a registry for managing mapping-based caches.
caching_enable(enable)	Define a context manager and decorator to temporarily set the Colour caching enabled state.
copy_definition(definition[, name])	Copy a definition using the same code, globals, defaults, closure, and name.
disable_multiprocessing()	Define a context manager and decorator to temporarily disable Colour multiprocessing state.
filter_kwargs(function, **kwargs)	Filter keyword arguments incompatible with the specified function signature.
filter_mapping(mapping, names)	Filter the specified mapping with specified names.
first_item(a)	Return the first item from the specified iterable.
handle_numpy_errors(**kwargs)	Handle Numpy errors through function decoration.
ignore_numpy_errors(function)	Wrap specified function wrapper.
ignore_python_warnings(function)	Decorate a function to ignore Python warnings.
int_digest	xxh3_64_intdigest
is_caching_enabled()	Determine whether Colour caching is enabled.
is_integer(a)	Determine whether the specified variable \(a\) is an numpy.integer-like variable under the specified threshold.
is_iterable(a)	Determine whether the specified variable \(a\) is iterable.
is_numeric(a)	Determine whether the specified variable \(a\) is a Real-like variable.
is_sibling(element, mapping)	Determine whether the type of the specified element is present in the specified mapping types.
multiprocessing_pool(*args, **kwargs)	Provide a context manager for a multiprocessing pool.
optional(value, default)	Return the specified value or a default if the value is None.
print_numpy_errors(function)	Wrap specified function wrapper.
raise_numpy_errors(function)	Wrap specified function wrapper.
set_caching_enable(enable)	Set the Colour caching enabled state.
slugify(object_[, allow_unicode])	Generate a SEO friendly and human-readable slug from the specified object.
hash_sha256(filename[, chunk_size])	Compute the SHA-256 hash of given file.
validate_method(method, valid_methods[, ...])	Validate whether the specified method exists in the specified valid methods and optionally return the method lower cased.
warn_numpy_errors(function)	Wrap specified function wrapper.

Array

colour.utilities

MixinDataclassArithmetic()	Provide mathematical operations for dataclass-like classes.
MixinDataclassArray()	Provide conversion methods for dataclass-like classes to numpy.ndarray objects.
MixinDataclassFields()	Provide fields introspection for dataclass-like classes.
MixinDataclassIterable()	Provide iteration capabilities over dataclass-like classes.

as_array(a[, dtype])	Convert the specified variable \(a\) to numpy.ndarray using the specified numpy.dtype.
as_complex_array(a[, dtype])	Convert the specified variable \(a\) to numpy.ndarray using the specified complex numpy.dtype.
as_float(-> DTypeFloat  -> NDArrayFloat)	Convert the specified variable \(a\) to numpy.floating using the specified numpy.dtype.
as_float_array(a[, dtype])	Convert the specified variable \(a\) to numpy.ndarray using the specified floating-point numpy.dtype.
as_float_scalar(a[, dtype])	Convert the specified variable \(a\) to numpy.floating using the specified numpy.dtype.
as_int(-> DTypeInt  -> NDArrayInt)	Convert the specified variable \(a\) to numpy.integer using the specified numpy.dtype.
as_int_array(a[, dtype])	Convert the specified variable \(a\) to numpy.ndarray using the specified integer numpy.dtype.
as_int_scalar(a[, dtype])	Convert the specified variable \(a\) to numpy.integer using the specified numpy.dtype.
centroid(a)	Return the centroid indexes of the specified array \(a\).
closest(a, b)	Return the closest array \(a\) elements to reference array \(b\) elements.
closest_indexes(a, b)	Return the closest element indexes from array \(a\) to reference array \(b\) elements.
fill_nan(a[, method, default])	Fill the NaN values in the specified array \(a\) using the specified method.
format_array_as_row(a[, decimals, separator])	Format the specified array \(a\) as a row.
from_range_1(a[, scale_factor, dtype])	Scale the specified array \(a\) from range '1'.
from_range_10(a[, scale_factor, dtype])	Scale the specified array \(a\) from range '10', used by the Munsell Renotation System.
from_range_100(a[, scale_factor, dtype])	Scale the specified array \(a\) from range '100'.
from_range_degrees(a[, scale_factor, dtype])	Scale the specified array \(a\) from degrees range.
from_range_int(a[, bit_depth, dtype])	Scale the specified array \(a\) from integer range.
full(shape, fill_value[, dtype, order])	Create an array of the specified value with the active dtype.
has_only_nan(a)	Return whether the specified array \(a\) contains only NaN values.
in_array(a, b[, tolerance])	Determine whether each element of array \(a\) is present in array \(b\) within the specified tolerance.
index_along_last_axis(a, indexes)	Reduce the dimension of array \(a\) by one, using an array of indexes to select elements from the last axis.
interval(distribution[, unique])	Return the interval size of the specified distribution.
is_ndarray_copy_enabled()	Determine whether Colour numpy.ndarray copy is enabled.
is_uniform(distribution)	Determine whether the specified distribution is uniform.
ndarray_copy(a)	Return a numpy.ndarray copy if the relevant Colour state is enabled.
ndarray_copy_enable(enable)	Define a context manager and decorator to temporarily set the Colour numpy.ndarray copy enabled state.
ndarray_write(a)	Define a context manager that temporarily sets the specified array \(a\) to writeable for operations, then restores it to read-only.
ones(shape[, dtype, order])	Create an array of ones with the active dtype.
orient(a[, orientation])	Orient the specified array \(a\) using the specified orientation.
row_as_diagonal(a)	Return the rows of the specified array \(a\) as diagonal matrices.
set_default_float_dtype([dtype])	Set the Colour default numpy.floating precision by setting colour.constant.DTYPE_FLOAT_DEFAULT attribute with the specified numpy.dtype wherever the attribute is imported.
set_default_int_dtype([dtype])	Set the Colour default numpy.integer precision by setting colour.constant.DTYPE_INT_DEFAULT attribute with the specified numpy.dtype wherever the attribute is imported.
set_ndarray_copy_enable(enable)	Set the Colour numpy.ndarray copy enabled state.
to_domain_1(a[, scale_factor, dtype])	Scale the specified array \(a\) to domain '1'.
to_domain_10(a[, scale_factor, dtype])	Scale the specified array \(a\) to domain '10', used by the Munsell Renotation System.
to_domain_100(a[, scale_factor, dtype])	Scale the specified array \(a\) to domain '100'.
to_domain_degrees(a[, scale_factor, dtype])	Scale the specified array \(a\) to degrees domain.
to_domain_int(a[, bit_depth, dtype])	Scale the specified array \(a\) to integer domain.
tsplit(a[, dtype])	Split the specified stacked array \(a\) along the last axis (tail) to produce an array of arrays.
tstack(a[, dtype])	Stack the specified array of arrays \(a\) along the last axis (tail) to produce a stacked array.
zeros(shape[, dtype, order])	Create an array of zeros with the active dtype.

Data Structures

colour.utilities

CanonicalMapping([data])	Represent a delimiter and case-insensitive dict-like object supporting both slug keys (SEO-friendly, human-readable versions with delimiters) and canonical keys (slugified keys without delimiters).
LazyCanonicalMapping([data])	Represent a lazy delimiter and case-insensitive dict-like object inheriting from colour.utilities.CanonicalMapping.
Lookup	Represent a dict-like object that provides lookup functionality by value(s).
Structure(*args, **kwargs)	Represent a dict-like structure that enables access to key values through dot notation syntax.

Network

colour.utilities

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

Metrics

colour.utilities

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

Requirements

colour.utilities

is_ctlrender_installed([raise_exception])	Determine whether ctlrender is installed and available.
is_imageio_installed([raise_exception])	Determine whether Imageio is installed and available.
is_matplotlib_installed([raise_exception])	Determine whether Matplotlib is installed and available.
is_networkx_installed([raise_exception])	Determine whether NetworkX is installed and available.
is_opencolorio_installed([raise_exception])	Determine whether OpenColorIO is installed and available.
is_openimageio_installed([raise_exception])	Determine whether OpenImageIO is installed and available.
is_pandas_installed([raise_exception])	Determine whether Pandas is installed and available.
is_pydot_installed([raise_exception])	Determine whether Pydot is installed and available.
is_tqdm_installed([raise_exception])	Determine whether tqdm is installed and available.
is_trimesh_installed([raise_exception])	Determine whether Trimesh is installed and available.
is_xxhash_installed([raise_exception])	Determine whether xxhash is installed and available.
required(*requirements)	Check whether specified ancillary package requirements are satisfied and decorate the function accordingly.

Verbose

colour.utilities

as_bool(a)	Convert the specified string to a boolean value.
describe_environment([runtime_packages, ...])	Describe the Colour runtime environment, including interpreter details and package versions.
filter_warnings([colour_runtime_warnings, ...])	Filter Colour and optionally overall Python warnings.
message_box(message[, width, padding, ...])	Print a message inside a formatted box.
multiline_repr(object_, attributes[, ...])	Generate an evaluable string representation of the specified object.
multiline_str(object_, attributes[, ...])	Generate a formatted multi-line string representation of the specified object.
numpy_print_options(*args, **kwargs)	Implement a context manager for temporarily modifying NumPy array print options.
show_warning(message, category, filename, lineno)	Display a warning message with enhanced formatting that enables traceback printing.
suppress_stdout()	Define a context manager and decorator to temporarily suppress standard output.
suppress_warnings([colour_runtime_warnings, ...])	Suppress Colour and optionally overall Python warnings within a context.
warning(*args, **kwargs)	Issue a warning.

Ancillary Objects

colour.utilities

ColourRuntimeWarning	Define the base class for Colour runtime warnings.
ColourUsageWarning	Define the base class for Colour usage warnings.
ColourWarning	Define the base class for Colour warnings.
MixinLogging()	Provide logging capabilities through mixin inheritance.