colour.read_image#

colour.read_image(path: str | PathLike, bit_depth: Literal['uint8', 'uint16', 'float16', 'float32', 'float64', 'float128'] = 'float32', method: Literal['Imageio', 'OpenImageIO'] | str = 'OpenImageIO', **kwargs: Any) → NDArrayReal[source]#

Read image data from the specified path.

Load and optionally convert image data from various formats, supporting multiple bit-depth conversions and backend libraries for flexible image I/O operations in colour science workflows.

Parameters:

  • path (str | PathLike) – Path to the image file.

  • bit_depth (Literal['uint8', 'uint16', 'float16', 'float32', 'float64', 'float128']) – Target bit-depth for the returned image data. For the Imageio method, image data is converted using colour.io.convert_bit_depth() after reading. For the OpenImageIO method, bit-depth conversion is handled by the library with this parameter controlling only the final data type.

  • method (Literal['Imageio', 'OpenImageIO'] | str) – Image reading backend library. Defaults to OpenImageIO with automatic fallback to Imageio if unavailable.

  • additional_data – {colour.io.read_image_OpenImageIO()}, Whether to return additional metadata with the image data.

  • kwargs (Any)

Returns:

Image data as a NumPy array with the specified bit-depth.

Return type:

numpy.ndarray

Notes

  • If the specified method is OpenImageIO but the library is not available, reading will be performed by Imageio.

  • If the specified method is Imageio, kwargs is passed directly to the wrapped definition.

  • For convenience, single channel images are squeezed to 2D arrays.

Examples

>>> import os
>>> import colour
>>> path = os.path.join(
...     colour.__path__[0],
...     "io",
...     "tests",
...     "resources",
...     "CMS_Test_Pattern.exr",
... )
>>> image = read_image(path)
>>> image.shape
(1267, 1274, 3)
>>> image.dtype
dtype('float32')
On this page

This Page