colour.RGB_to_YCbCr

colour.RGB_to_YCbCr(RGB, K=array([ 0.2126, 0.0722]), in_bits=10, in_legal=False, in_int=False, out_bits=8, out_legal=True, out_int=False, **kwargs)[source]

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

Parameters:
  • RGB (array_like) – Input R’G’B’ array of floats or integer values.
  • K (array_like, optional) – Luma weighting coefficients of red and blue. See colour.YCBCR_WEIGHTS for presets. Default is (0.2126, 0.0722), the weightings for ITU-R BT.709.
  • in_bits (int, optional) – Bit depth for integer 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, optional) – Whether to treat the input values as legal range. Default is False.
  • in_int (bool, optional) – Whether to treat the input values as in_bits integer code values. Default is False.
  • out_bits (int, optional) – Bit depth for integer 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, optional) – Whether to return legal range values. Default is True.
  • out_int (bool, optional) – Whether to return values as out_bits integer code values. Default is False.
Other Parameters:
 
  • in_range (array_like, optional) – 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_like, optional) – 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.YCbCr_ranges() definition.
Returns:

Y’CbCr colour encoding array of integer or float values.
Return type:

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

  • 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 in range [0, 1] (in_bits is ignored) to a float Y’CbCr output array where Y’ is in range [16 / 255, 235 / 255] and Cb and Cr are in range [16 / 255, 240./255]. The float values are calculated based on an [0, 255] integer range, but no 8-bit quantisation or clamping are performed.

References

Examples

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

Matching 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 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 integer 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 ITU-T T.871 [InternationalTUnion11c]:

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

Note the use of 256 for the max Cb / Cr value, 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 integer code value to represent achromatic colours. This does however create the possibility of output integer codes with value of 256, which cannot be stored in 8-bit integer representation. Recommendation ITU-T T.871 specifies these should be clamped to 255.

These JFIF JPEG ranges are also obtained as follows:

>>> RGB_to_YCbCr(RGB, K=YCBCR_WEIGHTS['ITU-R BT.601'], in_bits=8,
...              in_int=True, out_legal=False, out_int=True)
array([ 36, 136, 175])