colour.models.rgb Package

Sub-Packages

Module Contents

class colour.models.rgb.RGB_Colourspace(name, primaries, whitepoint, illuminant=None, RGB_to_XYZ_matrix=None, XYZ_to_RGB_matrix=None, encoding_cctf=None, decoding_cctf=None)[source]

Bases: object

Implements support for the RGB colourspaces dataset from colour.models.dataset.aces_rgb, etc....

Parameters:
  • name (unicode) – RGB colourspace name.
  • primaries (array_like) – RGB colourspace primaries.
  • whitepoint (array_like) – RGB colourspace whitepoint.
  • illuminant (unicode, optional) – RGB colourspace whitepoint name as illuminant.
  • RGB_to_XYZ_matrix (array_like, optional) – Transformation matrix from colourspace to CIE XYZ tristimulus values.
  • XYZ_to_RGB_matrix (array_like, optional) – Transformation matrix from CIE XYZ tristimulus values to colourspace.
  • encoding_cctf (object, optional) – Encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF / OECF) that maps estimated tristimulus values in a scene to \(R'G'B'\) video component signal value.
  • decoding_cctf (object, optional) – Decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF / EOCF) that maps an \(R'G'B'\) video component signal value to tristimulus values at the display.
name
primaries
whitepoint
illuminant
RGB_to_XYZ_matrix
XYZ_to_RGB_matrix
encoding_cctf
decoding_cctf
RGB_to_XYZ_matrix

Property for self._to_XYZ private attribute.

Returns:self._to_XYZ.
Return type:array_like, (3, 3)
XYZ_to_RGB_matrix

Property for self._to_RGB private attribute.

Returns:self._to_RGB.
Return type:array_like, (3, 3)
decoding_cctf

Property for self._decoding_cctf private attribute.

Returns:self._decoding_cctf.
Return type:object
encoding_cctf

Property for self._encoding_cctf private attribute.

Returns:self._encoding_cctf.
Return type:object
illuminant

Property for self._illuminant private attribute.

Returns:self._illuminant.
Return type:unicode
name

Property for self._name private attribute.

Returns:self._name.
Return type:unicode
primaries

Property for self._primaries private attribute.

Returns:self._primaries.
Return type:array_like, (3, 2)
whitepoint

Property for self._whitepoint private attribute.

Returns:self._whitepoint.
Return type:array_like
colour.models.rgb.XYZ_to_RGB(XYZ, illuminant_XYZ, illuminant_RGB, XYZ_to_RGB_matrix, chromatic_adaptation_transform=u'CAT02', encoding_cctf=None)[source]

Converts from CIE XYZ tristimulus values to given RGB colourspace.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values.
  • illuminant_XYZ (array_like) – CIE XYZ tristimulus values illuminant xy chromaticity coordinates or CIE xyY colourspace array.
  • illuminant_RGB (array_like) – RGB colourspace illuminant xy chromaticity coordinates or CIE xyY colourspace array.
  • XYZ_to_RGB_matrix (array_like) – Normalised primary matrix.
  • chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
  • encoding_cctf (object, optional) – Encoding colour component transfer function (Encoding CCTF) or opto-electronic transfer function (OETF / OECF).
Returns:

RGB colourspace array.
Return type:

ndarray

Notes

  • Input CIE XYZ tristimulus values are in domain [0, 1].
  • Input illuminant_XYZ xy chromaticity coordinates or CIE xyY colourspace array are in domain [0, \(\infty\)].
  • Input illuminant_RGB xy chromaticity coordinates or CIE xyY colourspace array are in domain [0, \(\infty\)].
  • Output RGB colourspace array is in range [0, 1].

Examples

>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> illuminant_XYZ = np.array([0.34570, 0.35850])
>>> illuminant_RGB = np.array([0.31270, 0.32900])
>>> chromatic_adaptation_transform = 'Bradford'
>>> XYZ_to_RGB_matrix = np.array([
...     [3.24062548, -1.53720797, -0.49862860],
...     [-0.96893071, 1.87575606, 0.04151752],
...     [0.05571012, -0.20402105, 1.05699594]])
>>> XYZ_to_RGB(
...     XYZ,
...     illuminant_XYZ,
...     illuminant_RGB,
...     XYZ_to_RGB_matrix,
...     chromatic_adaptation_transform)  
array([ 0.0110015...,  0.1273504...,  0.1163271...])
colour.models.rgb.RGB_to_XYZ(RGB, illuminant_RGB, illuminant_XYZ, RGB_to_XYZ_matrix, chromatic_adaptation_transform=u'CAT02', decoding_cctf=None)[source]

Converts from given RGB colourspace to CIE XYZ tristimulus values.

Parameters:
  • RGB (array_like) – RGB colourspace array.
  • illuminant_RGB (array_like) – RGB colourspace illuminant chromaticity coordinates or CIE xyY colourspace array.
  • illuminant_XYZ (array_like) – CIE XYZ tristimulus values illuminant chromaticity coordinates or CIE xyY colourspace array.
  • RGB_to_XYZ_matrix (array_like) – Normalised primary matrix.
  • chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
  • decoding_cctf (object, optional) – Decoding colour component transfer function (Decoding CCTF) or electro-optical transfer function (EOTF / EOCF).
Returns:

CIE XYZ tristimulus values.
Return type:

ndarray

Notes

  • Input RGB colourspace array is in domain [0, 1].
  • Input illuminant_RGB xy chromaticity coordinates or CIE xyY colourspace array are in domain [0, \(\infty\)].
  • Input illuminant_XYZ xy chromaticity coordinates or CIE xyY colourspace array are in domain [0, \(\infty\)].
  • Output CIE XYZ tristimulus values are in range [0, 1].

Examples

>>> RGB = np.array([0.01100154,  0.12735048,  0.11632713])
>>> illuminant_RGB = np.array([0.31270, 0.32900])
>>> illuminant_XYZ = np.array([0.34570, 0.35850])
>>> chromatic_adaptation_transform = 'Bradford'
>>> RGB_to_XYZ_matrix = np.array([
...     [0.41240000, 0.35760000, 0.18050000],
...     [0.21260000, 0.71520000, 0.07220000],
...     [0.01930000, 0.11920000, 0.95050000]])
>>> RGB_to_XYZ(
...     RGB,
...     illuminant_RGB,
...     illuminant_XYZ,
...     RGB_to_XYZ_matrix,
...     chromatic_adaptation_transform)  
array([ 0.0704953...,  0.1008    ,  0.0955831...])
colour.models.rgb.RGB_to_RGB(RGB, input_colourspace, output_colourspace, chromatic_adaptation_transform=u'CAT02')[source]

Converts from given input RGB colourspace to output RGB colourspace using given chromatic adaptation method.

Parameters:
  • RGB (array_like) – RGB colourspace array.
  • input_colourspace (RGB_Colourspace) – RGB input colourspace.
  • output_colourspace (RGB_Colourspace) – RGB output colourspace.
  • chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:

RGB colourspace array.
Return type:

ndarray

Notes

  • Input / output RGB colourspace arrays are in domain / range [0, 1].
  • Input / output RGB colourspace arrays are assumed to be representing linear light values.

Examples

>>> from colour import sRGB_COLOURSPACE, PROPHOTO_RGB_COLOURSPACE
>>> RGB = np.array([0.01103742, 0.12734226, 0.11632971])
>>> RGB_to_RGB(
...     RGB,
...     sRGB_COLOURSPACE,
...     PROPHOTO_RGB_COLOURSPACE)  
array([ 0.0643538...,  0.1157289...,  0.1158038...])
colour.models.rgb.normalised_primary_matrix(primaries, whitepoint)[source]

Returns the normalised primary matrix using given primaries and whitepoint \(xy\) chromaticity coordinates.

Parameters:
  • primaries (array_like, (3, 2)) – Primaries \(xy\) chromaticity coordinates.
  • whitepoint (array_like) – Illuminant / whitepoint \(xy\) chromaticity coordinates.
Returns:

Normalised primary matrix.
Return type:

ndarray, (3, 3)

Examples

>>> p = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> normalised_primary_matrix(p, whitepoint)  
array([[  9.5255239...e-01,   0.0000000...e+00,   9.3678631...e-05],
       [  3.4396645...e-01,   7.2816609...e-01,  -7.2132546...e-02],
       [  0.0000000...e+00,   0.0000000...e+00,   1.0088251...e+00]])
colour.models.rgb.chromatically_adapted_primaries(primaries, whitepoint_t, whitepoint_r, chromatic_adaptation_transform=u'CAT02')[source]

Chromatically adapts given primaries \(xy\) chromaticity coordinates from test whitepoint_t to reference whitepoint_r.

Parameters:
  • primaries (array_like, (3, 2)) – Primaries \(xy\) chromaticity coordinates.
  • whitepoint_t (array_like) – Test illuminant / whitepoint \(xy\) chromaticity coordinates.
  • whitepoint_r (array_like) – Reference illuminant / whitepoint \(xy\) chromaticity coordinates.
  • chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
Returns:

Chromatically adapted primaries \(xy\) chromaticity coordinates.
Return type:

ndarray

Examples

>>> p = np.array([0.64, 0.33, 0.30, 0.60, 0.15, 0.06])
>>> whitepoint_t = np.array([0.31270, 0.32900])
>>> whitepoint_r = np.array([0.34570, 0.35850])
>>> chromatic_adaptation_transform = 'Bradford'
>>> chromatically_adapted_primaries(  
...     p,
...     whitepoint_t,
...     whitepoint_r,
...     chromatic_adaptation_transform)
array([[ 0.6484414...,  0.3308533...],
       [ 0.3211951...,  0.5978443...],
       [ 0.1558932...,  0.0660492...]])
colour.models.rgb.primaries_whitepoint(npm)[source]

Returns the primaries and whitepoint \(xy\) chromaticity coordinates using given normalised primary matrix.

Parameters:npm (array_like, (3, 3)) – Normalised primary matrix.
Returns:Primaries and whitepoint \(xy\) chromaticity coordinates.
Return type:tuple

References

[2]Trieu, T. (2015). Private Discussion with Mansencal, T.

Examples

>>> npm = np.array([[9.52552396e-01, 0.00000000e+00, 9.36786317e-05],
...                 [3.43966450e-01, 7.28166097e-01, -7.21325464e-02],
...                 [0.00000000e+00, 0.00000000e+00, 1.00882518e+00]])
>>> p, w = primaries_whitepoint(npm)
>>> p  
array([[  7.3470000...e-01,   2.6530000...e-01],
       [  0.0000000...e+00,   1.0000000...e+00],
       [  1.0000000...e-04,  -7.7000000...e-02]])
>>> w 
array([ 0.32168,  0.33767])
colour.models.rgb.RGB_luminance_equation(primaries, whitepoint)[source]

Returns the luminance equation from given primaries and whitepoint.

Parameters:
  • primaries (array_like, (3, 2)) – Primaries chromaticity coordinates.
  • whitepoint (array_like) – Illuminant / whitepoint chromaticity coordinates.
Returns:

Luminance equation.
Return type:

unicode

Examples

>>> p = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> # Doctests skip for Python 2.x compatibility.
>>> RGB_luminance_equation(p, whitepoint)  
'Y = 0.3439664...(R) + 0.7281660...(G) + -0.0721325...(B)'
colour.models.rgb.RGB_luminance(RGB, primaries, whitepoint)[source]

Returns the luminance \(Y\) of given RGB components from given primaries and whitepoint.

Parameters:
  • RGB (array_like) – RGB chromaticity coordinate matrix.
  • primaries (array_like, (3, 2)) – Primaries chromaticity coordinate matrix.
  • whitepoint (array_like) – Illuminant / whitepoint chromaticity coordinates.
Returns:

Luminance \(Y\).
Return type:

numeric or ndarray

Examples

>>> RGB = np.array([40.6, 4.2, 67.4])
>>> p = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> RGB_luminance(RGB, p, whitepoint)  
12.1616018...
colour.models.rgb.log_encoding_ACESproxy(ACESproxy_l, bit_depth=u'10 Bit')[source]

Defines the ACESproxy colourspace log encoding curve / opto-electronic transfer function.

Parameters:
  • ACESproxy_l (numeric or array_like) – ACESproxyLin linear value.
  • bit_depth (unicode, optional) – {‘10 Bit’, ‘12 Bit’}, ACESproxy bit depth.
Returns:

ACESproxy non-linear value.
Return type:

numeric or ndarray

Examples

>>> log_encoding_ACESproxy(0.18)
426
colour.models.rgb.log_decoding_ACESproxy(ACESproxy, bit_depth=u'10 Bit')[source]

Defines the ACESproxy colourspace log decoding curve / electro-optical transfer function.

Parameters:
  • ACESproxy (numeric or array_like) – ACESproxy non-linear value.
  • bit_depth (unicode, optional) – {‘10 Bit’, ‘12 Bit’}, ACESproxy bit depth.
Returns:

ACESproxyLin linear value.
Return type:

numeric or ndarray

Examples

>>> log_decoding_ACESproxy(426)  
0.1792444...
colour.models.rgb.log_encoding_ACEScc(ACEScc_l)[source]

Defines the ACEScc colourspace log encoding / opto-electronic transfer function.

Parameters:ACEScc_l (numeric or array_like) – ACESccLin linear value.
Returns:ACEScc non-linear value.
Return type:numeric or ndarray

Examples

>>> log_encoding_ACEScc(0.18)  
0.4135884...
colour.models.rgb.log_decoding_ACEScc(ACEScc)[source]

Defines the ACEScc colourspace log decoding / electro-optical transfer function.

Parameters:ACEScc (numeric or array_like) – ACEScc non-linear value.
Returns:ACESccLin linear value.
Return type:numeric or ndarray

Examples

>>> log_decoding_ACEScc(0.413588402492442)  
0.1799999...
colour.models.rgb.log_encoding_ALEXALogC(x, firmware=u'SUP 3.x', method=u'Linear Scene Exposure Factor', EI=800)[source]

Defines the ALEXA Log C log encoding curve / opto-electronic transfer function.

Parameters:
  • x (numeric or array_like) – Linear data \(x\).
  • firmware (unicode, optional) – {‘SUP 3.x’, ‘SUP 2.x’}, Alexa firmware version.
  • method (unicode, optional) – {‘Linear Scene Exposure Factor’, ‘Normalised Sensor Signal’}, Conversion method.
  • EI (int, optional) – Ei.
Returns:

ALEXA Log C encoded data \(t\).
Return type:

numeric or ndarray

Examples

>>> log_encoding_ALEXALogC(0.18)  
0.3910068...
colour.models.rgb.log_decoding_ALEXALogC(t, firmware=u'SUP 3.x', method=u'Linear Scene Exposure Factor', EI=800)[source]

Defines the ALEXA Log C log decoding curve / electro-optical transfer function.

Parameters:
  • t (numeric or array_like) – ALEXA Log C encoded data \(t\).
  • firmware (unicode, optional) – {‘SUP 3.x’, ‘SUP 2.x’}, Alexa firmware version.
  • method (unicode, optional) – {‘Linear Scene Exposure Factor’, ‘Normalised Sensor Signal’}, Conversion method.
  • EI (int, optional) – Ei.
Returns:

Linear data \(x\).
Return type:

numeric or ndarray

Examples

>>> log_decoding_ALEXALogC(0.391006832034084)  
0.18...
colour.models.rgb.oetf_BT709(L)[source]

Defines Recommendation ITU-R BT.709-6 opto-electronic transfer function (OETF / OECF).

Parameters:L (numeric or array_like) – Luminance \(L\) of the image.
Returns:Corresponding electrical signal \(V\).
Return type:numeric or ndarray

Examples

>>> oetf_BT709(0.18)  
0.4090077...
colour.models.rgb.eotf_BT709(V)[source]

Defines Recommendation ITU-R BT.709-6 electro-optical transfer function (EOTF / EOCF).

Parameters:V (numeric or array_like) – Electrical signal \(V\).
Returns:Corresponding luminance \(L\) of the image.
Return type:numeric or ndarray

Warning

Recommendation ITU-R BT.709-6 doesn’t specify an electro-optical transfer function. This definition is used for symmetry in unit tests and other computations but should not be used as an EOTF.

Examples

>>> eotf_BT709(0.409007728864150)  
0.1...
colour.models.rgb.oetf_BT1886(L, L_B=64, L_W=940)[source]

Defines Recommendation ITU-R BT.1886 opto-electrical transfer function (OETF / OECF).

Parameters:
  • L (numeric or array_like) – Screen luminance in \(cd/m^2\).
  • L_B (numeric, optional) – Screen luminance for black.
  • L_W (numeric, optional) – Screen luminance for white.
Returns:

Input video signal level (normalized, black at \(V = 0\), to white at \(V = 1\).
Return type:

numeric or ndarray

Warning

Recommendation ITU-R BT.1886 doesn’t specify an opto-electrical transfer function. This definition is used for symmetry in unit tests and other computations but should not be used as an OETF.

Examples

>>> oetf_BT1886(277.98159179331145)  
0.4090077...
colour.models.rgb.eotf_BT1886(V, L_B=64, L_W=940)[source]

Defines Recommendation ITU-R BT.1886 electro-optical transfer function (EOTF / EOCF).

Parameters:
  • V (numeric or array_like) – Input video signal level (normalized, black at \(V = 0\), to white at \(V = 1\). For content mastered per Recommendation ITU-R BT.709, 10-bit digital code values \(D\) map into values of \(V\) per the following equation: \(V = (D–64)/876\)
  • L_B (numeric, optional) – Screen luminance for black.
  • L_W (numeric, optional) – Screen luminance for white.
Returns:

Screen luminance in \(cd/m^2\).
Return type:

numeric or ndarray

Examples

>>> eotf_BT1886(0.409007728864150)  
277.9815917...
colour.models.rgb.oetf_BT2020(E, is_12_bits_system=False)[source]

Defines Recommendation ITU-R BT.2020 opto-electrical transfer function (OETF / OECF).

Parameters:
  • E (numeric or array_like) – Voltage \(E\) normalized by the reference white level and proportional to the implicit light intensity that would be detected with a reference camera colour channel R, G, B.
  • is_12_bits_system (bool) – BT.709 alpha and beta constants are used if system is not 12-bit.
Returns:

Resulting non-linear signal \(E'\).
Return type:

numeric or ndarray

Examples

>>> oetf_BT2020(0.18)  
0.4090077...
colour.models.rgb.eotf_BT2020(E_p, is_12_bits_system=False)[source]

Defines Recommendation ITU-R BT.2020 electro-optical transfer function (EOTF / EOCF).

Parameters:
  • E_p (numeric or array_like) – Non-linear signal \(E'\).
  • is_12_bits_system (bool) – BT.709 alpha and beta constants are used if system is not 12-bit.
Returns:

Resulting voltage \(E\).
Return type:

numeric or ndarray

Examples

>>> eotf_BT2020(0.705515089922121)  
0.4999999...
colour.models.rgb.log_encoding_CanonLog(x)[source]

Defines the Canon Log log encoding curve / opto-electronic transfer function.

Parameters:x (numeric or array_like) – Linear data \(x\).
Returns:Non-linear data \(y\).
Return type:numeric or ndarray

Examples

>>> log_encoding_CanonLog(0.20) * 100  
32.7953896...
colour.models.rgb.log_decoding_CanonLog(y)[source]

Defines the Canon Log log decoding curve / electro-optical transfer function.

Parameters:y (numeric or array_like) – Non-linear data \(y\).
Returns:Linear data \(x\).
Return type:numeric or ndarray

Examples

>>> log_decoding_CanonLog(32.795389693580908 / 100)  
0.19999999...
colour.models.rgb.log_encoding_Cineon(x, black_offset=0.0107977516232771)[source]

Defines the Cineon log encoding curve / opto-electronic transfer function.

Parameters:
  • x (numeric or array_like) – Linear data \(x\).
  • black_offset (numeric or array_like) – Black offset.
Returns:

Non-linear data \(y\).
Return type:

numeric or ndarray

Examples

>>> log_encoding_Cineon(0.18)  
0.4573196...
colour.models.rgb.log_decoding_Cineon(y, black_offset=0.0107977516232771)[source]

Defines the Cineon log decoding curve / electro-optical transfer function.

Parameters:
  • y (numeric or array_like) – Non-linear data \(y\).
  • black_offset (numeric or array_like) – Black offset.
Returns:

Linear data \(x\).
Return type:

numeric or ndarray

Examples

>>> log_decoding_Cineon(0.457319613085418)  
0.1799999...
colour.models.rgb.oetf_DCIP3(XYZ)[source]

Defines the DCI-P3 colourspace opto-electronic transfer function (OETF / OECF).

Parameters:XYZ (numeric or array_like) – CIE XYZ tristimulus values.
Returns:Non-linear CIE XYZ’ tristimulus values.
Return type:numeric or ndarray

Examples

>>> oetf_DCIP3(0.18)  
461.9922059...
colour.models.rgb.eotf_DCIP3(XYZ_p)[source]

Defines the DCI-P3 colourspace electro-optical transfer function (EOTF / EOCF).

Parameters:XYZ_p (numeric or array_like) – Non-linear CIE XYZ’ tristimulus values.
Returns:CIE XYZ tristimulus values.
Return type:numeric or ndarray

Examples

>>> eotf_DCIP3(461.99220597484737)  
0.18...
colour.models.rgb.gamma_function(a, exponent=1.0)[source]

Defines a typical gamma encoding / decoding function.

Parameters:
  • a (numeric or array_like) – Array to encode / decode.
  • exponent (numeric, optional) – Encoding / decoding exponent.
Returns:

Encoded / decoded array.
Return type:

numeric or ndarray

Examples

>>> gamma_function(0.18, 2.2)  
0.0229932...
colour.models.rgb.linear_function(a)[source]

Defines a typical linear encoding / decoding function, essentially a pass-through function.

Parameters:a (numeric or array_like) – Array to encode / decode.
Returns:Encoded / decoded array.
Return type:numeric or ndarray

Examples

>>> linear_function(0.18)
0.18
colour.models.rgb.log_encoding_Panalog(x, black_offset=0.04077184461038074)[source]

Defines the Panalog log encoding curve / opto-electronic transfer function.

Parameters:
  • x (numeric or array_like) – Linear data \(x\).
  • black_offset (numeric or array_like) – Black offset.
Returns:

Non-linear data \(y\).
Return type:

numeric or ndarray

Warning

These are estimations known to be close enough, the actual log encoding curves are not published.

Examples

>>> log_encoding_Panalog(0.18)  
0.3745767...
colour.models.rgb.log_decoding_Panalog(y, black_offset=0.04077184461038074)[source]

Defines the Panalog log decoding curve / electro-optical transfer function.

Parameters:
  • y (numeric or array_like) – Non-linear data \(y\).
  • black_offset (numeric or array_like) – Black offset.
Returns:

Linear data \(x\).
Return type:

numeric or ndarray

Warning

These are estimations known to be close enough, the actual log encoding curves are not published.

Examples

>>> log_decoding_Panalog(0.374576791382298)  
0.1...
colour.models.rgb.log_encoding_VLog(L_in)[source]

Defines the Panasonic V-Log log encoding curve / opto-electronic transfer function.

Parameters:L_in (numeric or array_like) – Linear reflection data :math`L_{in}`.
Returns:Non-linear data \(V_{out}\).
Return type:numeric or ndarray

Examples

>>> log_encoding_VLog(0.18)  
0.4233114...
colour.models.rgb.log_decoding_VLog(V_out)[source]

Defines the Panasonic V-Log log decoding curve / electro-optical transfer function.

Parameters:V_out (numeric or array_like) – Non-linear data \(V_{out}\).
Returns:Linear reflection data :math`L_{in}`.
Return type:numeric or ndarray

Examples

>>> log_decoding_VLog(0.423311448760136)  
0.1799999...
colour.models.rgb.log_encoding_PivotedLog(x, log_reference=445, linear_reference=0.18, negative_gamma=0.6, density_per_code_value=0.002)[source]

Defines the Josh Pines style Pivoted Log log encoding curve / opto-electronic transfer function.

Parameters:
  • x (numeric or array_like) – Linear data \(x\).
  • log_reference (numeric or array_like) – Log reference.
  • linear_reference (numeric or array_like) – Linear reference.
  • negative_gamma (numeric or array_like) – Negative gamma.
  • density_per_code_value (numeric or array_like) – Density per code value.
Returns:

Non-linear data \(y\).
Return type:

numeric or ndarray

Examples

>>> log_encoding_PivotedLog(0.18)  
0.4349951...
colour.models.rgb.log_decoding_PivotedLog(y, log_reference=445, linear_reference=0.18, negative_gamma=0.6, density_per_code_value=0.002)[source]

Defines the Josh Pines style Pivoted Log log decoding curve / electro-optical transfer function.

Parameters:
  • y (numeric or array_like) – Non-linear data \(y\).
  • log_reference (numeric or array_like) – Log reference.
  • linear_reference (numeric or array_like) – Linear reference.
  • negative_gamma (numeric or array_like) – Negative gamma.
  • density_per_code_value (numeric or array_like) – Density per code value.
Returns:

Linear data \(x\).
Return type:

numeric or ndarray

Examples

>>> log_decoding_PivotedLog(0.434995112414467)  
0.1...
colour.models.rgb.log_encoding_REDLog(x, black_offset=0.009955040995908344)[source]

Defines the REDLog log encoding curve / opto-electronic transfer function.

Parameters:
  • x (numeric or array_like) – Linear data \(x\).
  • black_offset (numeric or array_like) – Black offset.
Returns:

Non-linear data \(y\).
Return type:

numeric or ndarray

Examples

>>> log_encoding_REDLog(0.18)  
0.6376218...
colour.models.rgb.log_decoding_REDLog(y, black_offset=0.009955040995908344)[source]

Defines the REDLog log decoding curve / electro-optical transfer function.

Parameters:
  • y (numeric or array_like) – Non-linear data \(y\).
  • black_offset (numeric or array_like) – Black offset.
Returns:

Linear data \(x\).
Return type:

numeric or ndarray

Examples

>>> log_decoding_REDLog(0.637621845988175)  
0.1...
colour.models.rgb.oetf_ROMMRGB(X)[source]

Defines the ROMM RGB encoding opto-electronic transfer function (OETF / OECF).

Parameters:X (numeric or array_like) – Linear data \(X_{ROMM}\).
Returns:Non-linear data \(X'_{ROMM}\).
Return type:numeric or ndarray

Examples

>>> oetf_ROMMRGB(0.18)  
0.3857114...
colour.models.rgb.eotf_ROMMRGB(X_p)[source]

Defines the ROMM RGB encoding electro-optical transfer function (EOTF / EOCF).

Parameters:X_p (numeric or array_like) – Non-linear data \(X'_{ROMM}\).
Returns:Linear data \(X_{ROMM}\).
Return type:numeric or ndarray

Examples

>>> eotf_ROMMRGB(0.3857114247511376) 
0.1...
colour.models.rgb.oetf_ProPhotoRGB(X)

Defines the ROMM RGB encoding opto-electronic transfer function (OETF / OECF).

Parameters:X (numeric or array_like) – Linear data \(X_{ROMM}\).
Returns:Non-linear data \(X'_{ROMM}\).
Return type:numeric or ndarray

Examples

>>> oetf_ROMMRGB(0.18)  
0.3857114...
colour.models.rgb.eotf_ProPhotoRGB(X_p)

Defines the ROMM RGB encoding electro-optical transfer function (EOTF / EOCF).

Parameters:X_p (numeric or array_like) – Non-linear data \(X'_{ROMM}\).
Returns:Linear data \(X_{ROMM}\).
Return type:numeric or ndarray

Examples

>>> eotf_ROMMRGB(0.3857114247511376) 
0.1...
colour.models.rgb.oetf_RIMMRGB(X, I_max=255, E_clip=2.0)[source]

Defines the RIMM RGB encoding opto-electronic transfer function (OETF / OECF).

RIMM RGB encoding non-linearity is based on that specified by Recommendation ITU-R BT.709-6.

Parameters:
  • X (numeric or array_like) – Linear data \(X_{RIMM}\).
  • I_max (numeric, optional) – Maximum code value: 255, 4095, and 650535 for respectively 8-bit, 12-bit and 16-bit per channel.
  • E_clip (numeric, optional) – Maximum exposure level.
Returns:

Non-linear data \(X'_{RIMM}\).
Return type:

numeric or ndarray

Examples

>>> oetf_RIMMRGB(0.18)  
74.3768017...
colour.models.rgb.eotf_RIMMRGB(X_p, I_max=255, E_clip=2.0)[source]

Defines the RIMM RGB encoding electro-optical transfer function (EOTF / EOCF).

Parameters:
  • X_p (numeric or array_like) – Non-linear data \(X'_{RIMM}\).
  • I_max (numeric, optional) – Maximum code value: 255, 4095, and 650535 for respectively 8-bit, 12-bit and 16-bit per channel.
  • E_clip (numeric, optional) – Maximum exposure level.
Returns:

Linear data \(X_{RIMM}\).
Return type:

numeric or ndarray

Examples

>>> eotf_RIMMRGB(74.37680178131521)  
0.1...
colour.models.rgb.log_encoding_ERIMMRGB(X, I_max=255, E_min=0.001, E_clip=316.2)[source]

Defines the ERIMM RGB log encoding curve / opto-electronic transfer function (OETF / OECF).

Parameters:
  • X (numeric or array_like) – Linear data \(X_{ERIMM}\).
  • I_max (numeric, optional) – Maximum code value: 255, 4095, and 650535 for respectively 8-bit, 12-bit and 16-bit per channel.
  • E_min (numeric, optional) – Minimum exposure limit.
  • E_clip (numeric, optional) – Maximum exposure limit.
Returns:

Non-linear data \(X'_{ERIMM}\).
Return type:

numeric or ndarray

Examples

>>> log_encoding_ERIMMRGB(0.18)  
104.5633593...
colour.models.rgb.log_decoding_ERIMMRGB(X_p, I_max=255, E_min=0.001, E_clip=316.2)[source]

Defines the ERIMM RGB log decoding curve / electro-optical transfer function (EOTF / EOCF).

Parameters:
  • X_p (numeric or array_like) – Non-linear data \(X'_{ERIMM}\).
  • I_max (numeric, optional) – Maximum code value: 255, 4095, and 650535 for respectively 8-bit, 12-bit and 16-bit per channel.
  • E_min (numeric, optional) – Minimum exposure limit.
  • E_clip (numeric, optional) – Maximum exposure limit.
Returns:

Linear data \(X_{ERIMM}\).
Return type:

numeric or ndarray

Examples

>>> log_decoding_ERIMMRGB(104.56335932049294) 
0.1...
colour.models.rgb.log_encoding_SLog(t)[source]

Defines the Sony S-Log log encoding curve / opto-electronic transfer function.

Parameters:t (numeric or array_like) – Input light level \(t\) to a camera.
Returns:Camera output code \(y\).
Return type:numeric or ndarray

Examples

>>> log_encoding_SLog(0.18)  
0.3599878...
colour.models.rgb.log_decoding_SLog(y)[source]

Defines the Sony S-Log log decoding curve / electro-optical transfer function.

Parameters:y (numeric or array_like) – Camera output code \(y\).
Returns:Input light level \(t\) to a camera.
Return type:numeric or ndarray

Examples

>>> log_decoding_SLog(0.359987846422154)  
0.1...
colour.models.rgb.log_encoding_SLog2(t)[source]

Defines the Sony S-Log2 log encoding curve / opto-electronic transfer function.

Parameters:t (numeric or array_like) – Input light level \(t\) to a camera.
Returns:Camera output code \(y\).
Return type:numeric or ndarray

Examples

>>> log_encoding_SLog2(0.18)  
0.3849708...
colour.models.rgb.log_decoding_SLog2(y)[source]

Defines the Sony S-Log2 log decoding curve / electro-optical transfer function.

Parameters:y (numeric or array_like) – Camera output code \(y\).
Returns:Input light level \(t\) to a camera.
Return type:numeric or ndarray

Examples

>>> log_decoding_SLog2(0.384970815928670)  
0.1...
colour.models.rgb.log_encoding_SLog3(t)[source]

Defines the Sony S-Log3 log encoding curve / opto-electronic transfer function.

Parameters:t (numeric or array_like) – Input light level \(t\) to a camera.
Returns:Camera output code \(y\).
Return type:numeric or ndarray

Examples

>>> log_encoding_SLog3(0.18)  
0.4105571...
colour.models.rgb.log_decoding_SLog3(y)[source]

Defines the Sony S-Log3 log decoding curve / electro-optical transfer function.

Parameters:y (numeric or array_like) – Camera output code \(y\).
Returns:Input light level \(t\) to a camera.
Return type:numeric or ndarray

Examples

>>> log_decoding_SLog3(0.410557184750733)  
0.1...
colour.models.rgb.oetf_sRGB(L)[source]

Defines the sRGB colourspace opto-electronic transfer function (OETF / OECF).

Parameters:L (numeric or array_like) – Luminance \(L\) of the image.
Returns:Corresponding electrical signal \(V\).
Return type:numeric or ndarray

Examples

>>> oetf_sRGB(0.18)  
0.4613561...
colour.models.rgb.eotf_sRGB(V)[source]

Defines the sRGB colourspace electro-optical transfer function (EOTF / EOCF).

Parameters:V (numeric or array_like) – Electrical signal \(V\)..
Returns:Corresponding luminance \(L\) of the image.
Return type:numeric or ndarray

Examples

>>> eotf_sRGB(0.461356129500442)  
0.1...
colour.models.rgb.oetf_ST2084(C, L_p=10000)[source]

Defines SMPTE ST 2084:2014 optimised perceptual opto-electronic transfer function (OETF / OECF).

Parameters:
  • C (numeric or array_like) – Target optical output \(C\) in \(cd/m^2\) of the ideal reference display.
  • L_p (numeric, optional) – Display peak luminance \(cd/m^2\).
Returns:

Color value abbreviated as \(N\), normalized to the range [0, 1], that is directly proportional to the encoded signal representation, and which is not directly proportional to the optical output of a display device.
Return type:

numeric or ndarray

Examples

>>> oetf_ST2084(0.18)  
0.0794209...
colour.models.rgb.eotf_ST2084(N, L_p=10000)[source]

Defines SMPTE ST 2084:2014 optimised perceptual electro-optical transfer function (EOTF / EOCF).

This perceptual quantizer (PQ) has been modeled by Dolby Laboratories using Barten (1999) contrast sensitivity function.

Parameters:
  • N (numeric or array_like) – Color value abbreviated as \(N\), normalized to the range [0, 1], that is directly proportional to the encoded signal representation, and which is not directly proportional to the optical output of a display device.
  • L_p (numeric, optional) – Display peak luminance \(cd/m^2\).
Returns:

Target optical output \(C\) in \(cd/m^2\) of the ideal reference display.
Return type:

numeric or ndarray

Examples

>>> eotf_ST2084(0.079420969944927)  
0.1...
colour.models.rgb.log_decoding_ViperLog(y)[source]

Defines the Viper Log log decoding curve / electro-optical transfer function.

Parameters:y (numeric or array_like) – Non-linear data \(y\).
Returns:Linear data \(x\).
Return type:numeric or ndarray

Examples

>>> log_decoding_ViperLog(0.636008067010413)  
0.1799999...
colour.models.rgb.log_decoding_ViperLog(y)[source]

Defines the Viper Log log decoding curve / electro-optical transfer function.

Parameters:y (numeric or array_like) – Non-linear data \(y\).
Returns:Linear data \(x\).
Return type:numeric or ndarray

Examples

>>> log_decoding_ViperLog(0.636008067010413)  
0.1799999...
colour.models.rgb.log_encoding_curve(value, curve='Cineon', **kwargs)[source]

Encodes linear-light values to \(R'G'B'\) video component signal value using given log curve.

Parameters:
  • value (numeric or array_like) – Value.
  • curve (unicode, optional) – {‘Cineon’, ‘Panalog’, ‘ViperLog’, ‘PLog’, ‘Canon Log’, ‘ACEScc’, ‘ACESproxy’, ‘ALEXA Log C’, ‘REDLog’, ‘REDLogFilm’, ‘S-Log’, ‘S-Log2’, ‘S-Log3’, ‘V-Log’}, Computation curve.
  • **kwargs (dict, optional) – Keywords arguments.
Returns:

Log value.
Return type:

numeric or ndarray

Examples

>>> log_encoding_curve(0.18)  
0.4573196...
>>> log_encoding_curve(0.18, curve='ACEScc')  
0.4135884...
>>> log_encoding_curve(  
...     0.18, curve='PLog', log_reference=400)
0.3910068...
>>> log_encoding_curve(0.18, curve='S-Log')  
0.3599878...
colour.models.rgb.log_decoding_curve(value, curve='Cineon', **kwargs)[source]

Decodes \(R'G'B'\) video component signal value to linear-light values using given log curve.

Parameters:
  • value (numeric or array_like) – Value.
  • curve (unicode, optional) – {‘Cineon’, ‘Panalog’, ‘ViperLog’, ‘PLog’, ‘Canon Log’, ‘ACEScc’, ‘ACESproxy’, ‘ALEXA Log C’, ‘REDLog’, ‘REDLogFilm’, ‘S-Log’, ‘S-Log2’, ‘S-Log3’, ‘V-Log’}, Computation curve.
  • **kwargs (dict, optional) – Keywords arguments.
Returns:

Log value.
Return type:

numeric or ndarray

Examples

>>> log_decoding_curve(0.457319613085418)  
0.1...
>>> log_decoding_curve(  
...     0.413588402492442, curve='ACEScc')
0.1...
>>> log_decoding_curve(  
...     0.391006842619746, curve='PLog', log_reference=400)
0.1...
>>> log_decoding_curve(  
...     0.359987846422154, curve='S-Log')
0.1...
colour.models.rgb.oetf(value, function='sRGB', **kwargs)[source]

Encodes estimated tristimulus values in a scene to \(R'G'B'\) video component signal value using given opto-electronic transfer function (OETF / OECF).

Parameters:
  • value (numeric or array_like) – Value.
  • function (unicode, optional) – {‘sRGB’, ‘BT.1886’, ‘BT.2020’, ‘BT.709’, ‘DCI-P3’, ‘ProPhoto RGB’, ‘ST 2084’}, Computation function.
  • **kwargs (dict, optional) – Keywords arguments.
Returns:

\(R'G'B'\) video component signal value.
Return type:

numeric or ndarray

Examples

>>> oetf(0.18)  
0.4613561...
>>> oetf(0.18, function='BT.2020')  
0.4090077...
>>> oetf(  
...     0.18, function='ST 2084', L_p=1000)
0.1820115...
colour.models.rgb.eotf(value, function='sRGB', **kwargs)[source]

Decodes \(R'G'B'\) video component signal value to tristimulus values at the display using given electro-optical transfer function (EOTF / EOCF).

Parameters:
  • value (numeric or array_like) – Value.
  • function (unicode, optional) – {‘sRGB’, ‘BT.1886’, ‘BT.2020’, ‘BT.709’, ‘DCI-P3’, ‘ProPhoto RGB’, ‘ST 2084’}, Computation function.
  • **kwargs (dict, optional) – Keywords arguments.
Returns:

Tristimulus values at the display.
Return type:

numeric or ndarray

Examples

>>> eotf(0.461356129500442)  
0.1...
>>> eotf(0.409007728864150,
...     function='BT.2020')  
0.1...
>>> eotf(  
...     0.182011532850008, function='ST 2084', L_p=1000)
0.1...
colour.models.rgb.XYZ_to_sRGB(XYZ, illuminant=(0.3127, 0.329), chromatic_adaptation_transform=u'CAT02', apply_encoding_cctf=True)[source]

Converts from CIE XYZ tristimulus values to sRGB colourspace.

Parameters:
  • XYZ (array_like) – CIE XYZ tristimulus values.
  • illuminant (array_like, optional) – Source illuminant chromaticity coordinates.
  • chromatic_adaptation_transform (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation transform.
  • apply_encoding_cctf (bool, optional) – Apply sRGB encoding colour component transfer function / opto-electronic transfer function.
Returns:

sRGB colour array.
Return type:

ndarray

Notes

  • Input CIE XYZ tristimulus values are in domain [0, 1].

Examples

>>> import numpy as np
>>> XYZ = np.array([0.07049534, 0.10080000, 0.09558313])
>>> XYZ_to_sRGB(XYZ)  
array([ 0.1749817...,  0.3881874...,  0.3215997...])
colour.models.rgb.sRGB_to_XYZ(RGB, illuminant=(0.3127, 0.329), chromatic_adaptation_method=u'CAT02', apply_decoding_cctf=True)[source]

Converts from sRGB colourspace to CIE XYZ tristimulus values.

Parameters:
  • RGB (array_like) – sRGB colourspace array.
  • illuminant (array_like, optional) – Source illuminant chromaticity coordinates.
  • chromatic_adaptation_method (unicode, optional) – {‘CAT02’, ‘XYZ Scaling’, ‘Von Kries’, ‘Bradford’, ‘Sharp’, ‘Fairchild’, ‘CMCCAT97’, ‘CMCCAT2000’, ‘CAT02_BRILL_CAT’, ‘Bianco’, ‘Bianco PC’}, Chromatic adaptation method.
  • apply_decoding_cctf (bool, optional) – Apply sRGB decoding colour component transfer function / electro-optical transfer function.
Returns:

CIE XYZ tristimulus values.
Return type:

ndarray

Notes

  • Input RGB colourspace array is in domain [0, 1].

Examples

>>> import numpy as np
>>> RGB = np.array([0.17498172, 0.38818743, 0.32159978])
>>> sRGB_to_XYZ(RGB)  
array([ 0.0704953...,  0.1008...,  0.0955831...])
colour.models.rgb.spectral_to_aces_relative_exposure_values(spd, illuminant=SpectralPowerDistribution( 'D60', {300.0: 0.029370758174923, 310.0: 2.619241317964963, 320.0: 15.71689061312826, 330.0: 28.774580263919134, 340.0: 31.86483993666198, 350.0: 36.3774264446741, 360.0: 38.68311546316286, 370.0: 42.717548461834966, 380.0: 41.45494057963752, 390.0: 46.60531924327943, 400.0: 72.27859383884864, 410.0: 80.44059999279465, 420.0: 82.91502693894319, 430.0: 77.67626397731756, 440.0: 95.68127430379398, 450.0: 107.95482086750596, 460.0: 109.55918680507406, 470.0: 107.75814070682792, 480.0: 109.6714042353418, 490.0: 103.70787331005091, 500.0: 105.23219857523205, 510.0: 104.42766692185435, 520.0: 102.52293357805246, 530.0: 106.05267087904782, 540.0: 103.31515403458198, 550.0: 103.53859891732658, 560.0: 100.0, 570.0: 96.7514214188669, 580.0: 96.71282250154032, 590.0: 89.92147908442617, 600.0: 91.99979329504407, 610.0: 92.09870955067275, 620.0: 90.64600269701035, 630.0: 86.52648272486029, 640.0: 87.57918623550152, 650.0: 83.97614003583296, 660.0: 84.72407422805772, 670.0: 87.49349084772983, 680.0: 83.48307015694974, 690.0: 74.17245111876663, 700.0: 76.62038531099138, 710.0: 79.05184907375583, 720.0: 65.47137071741646, 730.0: 74.10607902725252, 740.0: 79.5271204277263, 750.0: 67.30716277162384, 760.0: 49.273538206159095, 770.0: 70.89241211789025, 780.0: 67.16399622630497, 790.0: 68.17137071741647, 800.0: 62.9898086167058, 810.0: 54.990892361077115, 820.0: 60.82560067091317, 830.0: 63.89349586226156}))[source]

Converts given spectral power distribution to ACES2065-1 colourspace relative exposure values.

Parameters:
  • spd (SpectralPowerDistribution) – Spectral power distribution.
  • illuminant (SpectralPowerDistribution, optional) – Illuminant spectral power distribution.
Returns:

ACES2065-1 colourspace relative exposure values array.
Return type:

ndarray, (3,)

Notes

  • Output ACES2065-1 colourspace relative exposure values array is in range [0, 1].

See also

colour.colorimetry.tristimulus.spectral_to_XYZ()

References

Examples

>>> from colour import COLOURCHECKERS_SPDS
>>> spd = COLOURCHECKERS_SPDS['ColorChecker N Ohta']['dark skin']
>>> spectral_to_aces_relative_exposure_values(spd)  
array([ 0.1187697...,  0.0870866...,  0.0589442...])
colour.models.rgb.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_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.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.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...])