colour.RGB_to_YCbCr#

colour.RGB_to_YCbCr(RGB: ArrayLike, K: NDArrayFloat = WEIGHTS_YCBCR['ITU-R BT.709'], in_bits: int = 10, in_legal: bool = False, in_int: bool = False, out_bits: int = 8, out_legal: bool = True, out_int: bool = False, clamp_int: bool = True, **kwargs: Any) → NDArrayReal[source]#

Convert an array of R’G’B’ values to the corresponding Y’CbCr colour encoding values array.

Parameters:

  • RGB (ArrayLike) – Input R’G’B’ array of floats or int values.

  • K (NDArrayFloat) – Luma weighting coefficients of red and blue. See colour.WEIGHTS_YCBCR for presets. Default is (0.2126, 0.0722), the weightings for ITU-R BT.709.

  • in_bits (int) – Bit-depth for int input, or used in the calculation of the denominator for legal range float values, i.e., 8-bit means the float value for legal white is 235 / 255. Default is 10.

  • in_legal (bool) – Whether to treat the input values as legal range. Default is False.

  • in_int (bool) – Whether to treat the input values as in_bits int code values. Default is False.

  • out_bits (int) – Bit-depth for int output, or used in the calculation of the denominator for legal range float values, i.e., 8-bit means the float value for legal white is 235 / 255. Ignored if out_legal and out_int are both False. Default is 8.

  • out_legal (bool) – Whether to return legal range values. Default is True.

  • out_int (bool) – Whether to return values as out_bits int code values. Default is False.

  • clamp_int (bool) – Whether to clamp int output to allowable range for out_bits. Default is True.

  • in_range – Array overriding the computed range such as in_range = (RGB_min, RGB_max). If in_range is undefined, RGB_min and RGB_max will be computed using colour.CV_range() definition.

  • out_range – Array overriding the computed range such as out_range = (Y_min, Y_max, C_min, C_max)`. If ``out_range`` is undefined, *Y_min, Y_max, C_min and C_max will be computed using colour.models.rgb.ycbcr.ranges_YCbCr() definition.

  • kwargs (Any)

Returns:

Y’CbCr colour encoding array of int or float values.

Return type:

numpy.ndarray

Warning

For Recommendation ITU-R BT.2020, colour.RGB_to_YCbCr() definition is only applicable to the non-constant luminance implementation. colour.RGB_to_YcCbcCrc() definition should be used for the constant luminance case as per [InternationalTUnion15a].

Notes

Domain *

Scale - Reference

Scale - 1

RGB

[0, 1]

[0, 1]

Range *

Scale - Reference

Scale - 1

YCbCr

[0, 1]

[0, 1]

* This definition has input and output int switches, thus the domain-range scale information is only given for the floating point mode.

  • The default arguments, **{'in_bits': 10, 'in_legal': False, 'in_int': False, 'out_bits': 8, 'out_legal': True, 'out_int': False} transform a float R’G’B’ input array normalised to domain [0, 1] (in_bits is ignored) to a float Y’CbCr output array where Y’ is normalised to range [16 / 255, 235 / 255] and Cb and Cr are normalised to range [16 / 255, 240./255]. The float values are calculated based on an [0, 255] int range, but no 8-bit quantisation or clamping are performed.

References

[InternationalTUnion11c], [InternationalTUnion15b], [SocietyoMPaTEngineers99], [Wikipedia04e]

Examples

>>> RGB = np.array([1.0, 1.0, 1.0])
>>> RGB_to_YCbCr(RGB)  
array([ 0.9215686...,  0.5019607...,  0.5019607...])

Matching the float output of The Foundry Nuke’s Colorspace node set to YCbCr:

>>> RGB_to_YCbCr(RGB, out_range=(16 / 255, 235 / 255, 15.5 / 255, 239.5 / 255))
... 
array([ 0.9215686...,  0.5       ,  0.5       ])

Matching the float output of The Foundry Nuke’s Colorspace node set to YPbPr:

>>> RGB_to_YCbCr(RGB, out_legal=False, out_int=False)
... 
array([ 1.,  0.,  0.])

Creating int code values as per standard 10-bit SDI:

>>> RGB_to_YCbCr(RGB, out_legal=True, out_bits=10, out_int=True)
... 
array([940, 512, 512]...)

For JFIF JPEG conversion as per Recommendation ITU-T T.871

>>> RGB = np.array([102, 0, 51])
>>> RGB_to_YCbCr(
...     RGB,
...     K=WEIGHTS_YCBCR["ITU-R BT.601"],
...     in_range=(0, 255),
...     out_range=(0, 255, 0.5, 255.5),
...     out_int=True,
... )
... 
array([ 36, 136, 175]...)

Note the use of [0.5, 255.5] for the Cb / Cr range, which is required so that the Cb and Cr output is centered about 128. Using 255 centres it about 127.5, meaning that there is no int code value to represent achromatic colours. This does however create the possibility of output int codes with value of 256, which cannot be stored in 8-bit int representation. Recommendation ITU-T T.871 specifies these should be clamped to 255, which is applied with the default clamp_int=True.

These JFIF JPEG ranges are also obtained as follows:

>>> RGB_to_YCbCr(
...     RGB,
...     K=WEIGHTS_YCBCR["ITU-R BT.601"],
...     in_bits=8,
...     in_int=True,
...     out_legal=False,
...     out_int=True,
... )
... 
array([ 36, 136, 175]...)
On this page
Show Source