pydicom.pixels.convert_color_space

pydicom.pixels.convert_color_space(arr: ndarray, current: str, desired: str, per_frame: bool = False, bit_depth: int | None = None) → ndarray[source]

Convert the image(s) in arr from one color space to another.

Changed in version 2.2: Added per_frame keyword parameter.

Changed in version 3.1: Added the bit_depth keyword parameter, as well as support for up to 16-bit input arrays and YBR_PARTIAL color spaces.

Note that conversion is only supported for YCbCr to RGB (or vice versa), not between different YCbCr color spaces.

Parameters:

  • arr (numpy.ndarray) – The image(s) as numpy.ndarray with shape (frames, rows, columns, 3) or (rows, columns, 3) and a ‘uint8’ or ‘uint16’ dtype. uint16 is only supported when converting to or from YBR_FULL or YBR_FULL_422. For subsampled YCbCr data, such as YBR_FULL_422, the subsampling must be removed prior to conversion.

  • current (str) – The current color space, should be a valid value for (0028,0004) Photometric Interpretation. One of 'RGB', 'YBR_FULL', 'YBR_FULL_422', 'YBR_PARTIAL_420', 'YBR_PARTIAL_422'.

  • desired (str) – The desired color space, should be a valid value for (0028,0004) Photometric Interpretation. One of 'RGB', 'YBR_FULL', 'YBR_FULL_422', 'YBR_PARTIAL_420', 'YBR_PARTIAL_422'.

  • per_frame (bool, optional) – If True and the input array contains multiple frames then process each frame individually and update arr in-place to reduce memory usage. Default False.

  • bit_depth (int, optional) – The bit-depth of the values in arr. Must be 8 for YBR_PARTIAL_420 and YBR_PARTIAL_422, or in the closed interval [1, 16] for YBR_FULL and YBR_FULL_422. Defaults to the maximum bit-depth of arr.

Returns:

The image(s) converted to the desired color space. If per_frame is False (the default) then a new ndarray will be returned, otherwise arr will be updated in-place.

Return type:

numpy.ndarray

References