colour.models.rgb.ycbcr Module

Y’CbCr Colour Encoding

Defines the Y’CbCr colour encoding related transformations:

Notes

  • Y’CbCr is not an absolute colourspace.

References

[1]Wikipedia. (n.d.). YCbCr. Retrieved February 29, 2016, from https://en.wikipedia.org/wiki/YCbCr
[2]International Telecommunication Union. (2015). Recommendation ITU-R BT.709-6 - Parameter values for the HDTV standards for production and international programme exchange BT Series Broadcasting service (Vol. 5). Retrieved from https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.709-6-201506-I!!PDF-E.pdf
[3](1, 2, 3, 4) International Telecommunication Union. (2015). Recommendation ITU-R BT.2020 - Parameter values for ultra-high definition television systems for production and international programme exchange (Vol. 1). Retrieved from https://www.itu.int/dms_pubrec/itu-r/rec/bt/R-REC-BT.2020-2-201510-I!!PDF-E.pdf
[4]Society of Motion Picture and Television Engineers. (1999). ANSI/SMPTE 240M-1995 - Signal Parameters - 1125-Line High-Definition Production Systems, 1–7. Retrieved from http://car.france3.mars.free.fr/HD/INA- 26 jan 06/SMPTE normes et confs/s240m.pdf
[5]International Telecommunication Union. (2011). Recommendation ITU-T T.871 - Information technology – Digital compression and coding of continuous-tone still images: JPEG File Interchange Format (JFIF). Retrieved from https://www.itu.int/rec/dologin_pub.asp?lang=e&id=T-REC-T.871-201105-I!!PDF-E&type=items
colour.models.rgb.ycbcr.YCBCR_WEIGHTS = CaseInsensitiveMapping({u'Rec. 2020': (0.2627, 0.0593), u'SMPTE-240M': (0.2122, 0.0865), u'Rec. 709': (0.2126, 0.0722), u'Rec. 601': (0.299, 0.114)})

Luma weightings presets.

YCBCR_WEIGHTS : dict
{‘Rec. 601’, ‘Rec. 709’, ‘Rec. 2020’, ‘SMPTE-240M}
colour.models.rgb.ycbcr.RGB_range(bits, is_legal, is_int)[source]

” Returns the RGB range array for given bit depth, range legality and representation.

Parameters:
  • bits (int) – Bit depth of the RGB output ranges array.
  • is_legal (bool) – Whether the RGB output ranges array is legal.
  • is_int (bool) – Whether the RGB output ranges array represents integer code values.
Returns:

RGB ranges array.

Return type:

ndarray

Examples

>>> RGB_range(8, True, True)
array([ 16, 235])
>>> RGB_range(8, True, False)  
array([ 0.0627451...,  0.9215686...])
>>> RGB_range(10, False, False)
array([ 0.,  1.])
colour.models.rgb.ycbcr.YCbCr_ranges(bits, is_legal, is_int)[source]

” Returns the Y’CbCr colour encoding ranges array for given bit depth, range legality and representation.

Parameters:
  • bits (int) – Bit depth of the Y’CbCr colour encoding ranges array.
  • is_legal (bool) – Whether the Y’CbCr colour encoding ranges array is legal.
  • is_int (bool) – Whether the Y’CbCr colour encoding ranges array represents integer code values.
Returns:

Y’CbCr colour encoding ranges array.

Return type:

ndarray

Examples

>>> YCbCr_ranges(8, True, True)
array([ 16, 235,  16, 240])
>>> YCbCr_ranges(8, True, False)  
array([ 0.0627451...,  0.9215686...,  0.0627451...,  0.9411764...])
>>> YCbCr_ranges(10, False, False)
array([ 0. ,  1. , -0.5,  0.5])
colour.models.rgb.ycbcr.RGB_to_YCbCr(RGB, K=(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 :attr: YCBCR_WEIGHTS for presets. Default is (0.2126, 0.0722), the weightings for Rec. 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.
  • **kwargs (dict, optional) – {‘in_range’, ‘out_range’} Keyword arguments to override the calculated ranges such as {'in_range' : array_like (RGB_min, RGB_max), 'out_range' : array_like (Y_min, Y_max, C_min, C_max)}.
Returns:

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

Return type:

ndarray

Warning

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

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.

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 [5]:

>>> RGB = np.array([102, 0, 51])
>>> RGB_to_YCbCr(
...     RGB,
...     K=YCBCR_WEIGHTS['Rec. 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['Rec. 601'],
...     in_bits=8,
...     in_int=True,
...     out_legal=False,
...     out_int=True)
array([ 36, 136, 175])
colour.models.rgb.ycbcr.YCbCr_to_RGB(YCbCr, K=(0.2126, 0.0722), in_bits=8, in_legal=True, in_int=False, out_bits=10, out_legal=False, out_int=False, **kwargs)[source]

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

Parameters:
  • YCbCr (array_like) – Input Y’CbCr colour encoding array of integer or float values.
  • K (array_like, optional) – Luma weighting coefficients of red and blue. See :attr: YCBCR_WEIGHTS for presets. Default is (0.2126, 0.0722), the weightings for Rec. 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.
  • **kwargs (dict, optional) – {‘in_range’, ‘out_range’} Keyword arguments to override the calculated ranges such as {'in_range' : array_like (Y_min, Y_max, C_min, C_max), 'out_range' : array_like (RGB_min, RGB_max)}.
Returns:

R’G’B’ array of integer or float values.

Return type:

ndarray

Warning

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

Examples

>>> YCbCr = np.array([502, 512, 512])
>>> YCbCr_to_RGB(
...     YCbCr,
...     in_bits=10,
...     in_legal=True,
...     in_int=True)
array([ 0.5,  0.5,  0.5])
colour.models.rgb.ycbcr.RGB_to_YcCbcCrc(RGB, out_bits=10, out_legal=True, out_int=False, is_12_bits_system=False, **kwargs)[source]

Converts an array of RGB linear values to the corresponding Yc’Cbc’Crc’ colour encoding values array.

Parameters:
  • RGB (array_like) – Input RGB array of linear float values.
  • 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 10.
  • 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.
  • is_12_bits_system (bool, optional) – Recommendation ITU-R BT.2020 OETF (OECF) adopts different parameters for 10 and 12 bit systems. Default is False.
  • **kwargs (dict, optional) – {‘out_range’} Keyword arguments to override the calculated ranges such as {'out_range' : array_like (Y_min, Y_max, C_min, C_max)}
Returns:

Yc’Cbc’Crc’ colour encoding array of integer or float values.

Return type:

ndarray

Warning

This definition is specifically for usage with Recommendation ITU-R BT.2020 [3] when adopting the constant luminance implementation.

Examples

>>> RGB = np.array([0.18, 0.18, 0.18])
>>> RGB_to_YcCbcCrc(
...     RGB,
...     out_legal=True,
...     out_bits=10,
...     out_int=True,
...     is_12_bits_system=False)
array([422, 512, 512])
colour.models.rgb.ycbcr.YcCbcCrc_to_RGB(YcCbcCrc, in_bits=10, in_legal=True, in_int=False, is_12_bits_system=False, **kwargs)[source]

Converts an array of Yc’Cbc’Crc’ colour encoding values to the corresponding RGB array of linear values.

Parameters:
  • YcCbcCrc (array_like) – Input Yc’Cbc’Crc’ colour encoding array of linear float values.
  • 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.
  • is_12_bits_system (bool, optional) – Recommendation ITU-R BT.2020 EOTF (EOCF) adopts different parameters for 10 and 12 bit systems. Default is False.
  • **kwargs (dict, optional) – {‘in_range’} Keyword arguments to override the calculated ranges such as {'in_range' : array_like (Y_min, Y_max, C_min, C_max)}
Returns:

RGB array of linear float values.

Return type:

ndarray

Warning

This definition is specifically for usage with Recommendation ITU-R BT.2020 [3] when adopting the constant luminance implementation.

Examples

>>> YcCbcCrc = np.array([1689, 2048, 2048])
>>> YcCbcCrc_to_RGB(  
...     YcCbcCrc,
...     in_legal=True,
...     in_bits=12,
...     in_int=True,
...     is_12_bits_system=True)
array([ 0.1800903...,  0.1800903...,  0.1800903...])