colour.utilities.xp_as_array

colour.utilities.xp_as_array(a: ArrayLike, *, dtype: Any = None, xp: ProtocolArrayNamespace | ModuleType | None = None, like: Any = None, copy: bool | None = None) → NDArray

Convert the specified variable \(a\) to the target namespace.

When the namespace is numpy, the original variable \(a\) is returned as a numpy.ndarray without unnecessary copying. For other namespaces, the variable \(a\) is converted via xp.asarray, optionally matching the device of a reference array like.

Parameters:

• a (ArrayLike) – Variable \(a\) to convert.

• dtype (Any) – Target dtype. When provided, the result is cast to this dtype. Accepts NumPy dtype objects (e.g. np.float64) which are mapped to the backend equivalent.

• xp (ProtocolArrayNamespace | ModuleType | None) – Array namespace module. If None, derived from a.

• like (Any) – Reference array whose device to match (for backends like PyTorch that support multiple devices).

• copy (bool | None) – When True, always return a fresh copy of the input even when no dtype change is needed (the Array API xp.asarray(a, copy=True) semantics). When None (default), copy only when necessary (dtype change, namespace promotion). The scalar-promotion cache is bypassed when copy=True.

Returns:

Variable \(a\) in the target namespace.

Return type:

object

Examples

>>> xp_as_array([1, 2, 3], xp=np)
array([1, 2, 3])
>>> xp_as_array([1, 2, 3], dtype=np.float64, xp=np)
array([1., 2., 3.])