colour.models.rgb.rgb_colourspace Module

RGB Colourspace & Transformations

Defines the RGB_Colourspace class for the RGB colourspaces dataset from colour.models.dataset.aces_rgb, etc... and the following RGB colourspace transformations or helper definitions:

See also

RGB Colourspaces Jupyter Notebook

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

Bases: object

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

Colour science literature related to RGB colourspaces and encodings defines their dataset using different degree of precision or rounding. While instances where a whitepoint is being defined with a value different than its canonical agreed one are rare, it is however very common to have normalised primary matrices rounded at different decimals. This can yield large discrepancies in computations.

Such an occurrence is the V-Gamut colourspace white paper [1], that defines the V-Gamut to Rec. 709 conversion matrix as follows:

[[ 1.806576 -0.695697 -0.110879]
 [-0.170090  1.305955 -0.135865]
 [-0.025206 -0.154468  1.179674]]

Computing this matrix using Rec. 709 colourspace derived normalised primary matrix yields:

[[ 1.8065736 -0.6956981 -0.1108786]
 [-0.1700890  1.3059548 -0.1358648]
 [-0.0252057 -0.1544678  1.1796737]]

The latter matrix is almost equals with the former, however performing the same computation using IEC 61966-2-1:1999 sRGB colourspace normalised primary matrix introduces severe disparities:

[[ 1.8063853 -0.6956147 -0.1109453]
 [-0.1699311  1.3058387 -0.1358616]
 [-0.0251630 -0.1544899  1.1797117]]

In order to provide support for both literature defined dataset and accurate computations enabling transformations without loss of precision, the RGB_Colourspace class provides two sets of transformation matrices:

  • Instantiation transformation matrices
  • Derived transformation matrices

Upon instantiation, the RGB_Colourspace class stores the given RGB_to_XYZ_matrix and XYZ_to_RGB_matrix arguments and also computes their derived counterpart using the primaries and whitepoint arguments.

Whether the initialisation or derived matrices are used in subsequent computations is dependent on the RGB_Colourspace.use_derived_RGB_to_XYZ_matrix and RGB_Colourspace.use_derived_XYZ_to_RGB_matrix attributes values.

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.
  • use_derived_RGB_to_XYZ_matrix (bool, optional) – Whether to use the declaration time normalised primary matrix or to use a computed derived normalised primary matrix.
  • use_derived_XYZ_to_RGB_matrix (bool, optional) – Whether to use the declaration time normalised primary matrix or to use a computed derived inverse normalised primary matrix.
name
primaries
whitepoint
illuminant
RGB_to_XYZ_matrix
XYZ_to_RGB_matrix
encoding_cctf
decoding_cctf
use_derived_RGB_to_XYZ_matrix
use_derived_XYZ_to_RGB_matrix
use_derived_transformation_matrices()[source]

Notes

  • The normalised primary matrix defined by RGB_Colourspace.RGB_to_XYZ_matrix attribute is treated as the prime matrix from which the inverse will be calculated as required by the internal derivation mechanism. This behaviour has been chosen in accordance with literature where commonly a RGB colourspace is defined by its normalised primary matrix as it is directly computed from the chosen primaries and whitepoint.

References

[1]Panasonic. (2014). VARICAM V-Log/V-Gamut. Retrieved from http://pro-av.panasonic.net/en/varicam/common/pdf/VARICAM_V-Log_V-Gamut.pdf
[2]International Electrotechnical Commission. (1999). IEC 61966-2-1:1999 - Multimedia systems and equipment - Colour measurement and management - Part 2-1: Colour management - Default RGB colour space - sRGB, 51. Retrieved from https://webstore.iec.ch/publication/6169

Examples

>>> p = np.array([0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> whitepoint = np.array([0.32168, 0.33767])
>>> RGB_to_XYZ_matrix = np.identity(3)
>>> XYZ_to_RGB_matrix = np.identity(3)
>>> colourspace = RGB_Colourspace(
...     'RGB Colourspace',
...     p,
...     whitepoint,
...     'D60',
...     RGB_to_XYZ_matrix,
...     XYZ_to_RGB_matrix)
>>> colourspace.RGB_to_XYZ_matrix
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> colourspace.XYZ_to_RGB_matrix
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> colourspace.use_derived_transformation_matrices(True)
True
>>> colourspace.RGB_to_XYZ_matrix  
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]])
>>> colourspace.XYZ_to_RGB_matrix  
array([[  1.0498110...e+00,   0.0000000...e+00,  -9.7484540...e-05],
       [ -4.9590302...e-01,   1.3733130...e+00,   9.8240036...e-02],
       [  0.0000000...e+00,   0.0000000...e+00,   9.9125201...e-01]])
>>> colourspace.use_derived_RGB_to_XYZ_matrix = False
>>> colourspace.RGB_to_XYZ_matrix
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
>>> colourspace.use_derived_XYZ_to_RGB_matrix = False
>>> colourspace.XYZ_to_RGB_matrix
array([[ 1.,  0.,  0.],
       [ 0.,  1.,  0.],
       [ 0.,  0.,  1.]])
RGB_to_XYZ_matrix

Property for RGB_to_XYZ_matrix attribute.

Returns:RGB_to_XYZ_matrix.
Return type:array_like, (3, 3)
XYZ_to_RGB_matrix

Property for XYZ_to_RGB_matrix attribute.

Returns:XYZ_to_RGB_matrix.
Return type:array_like, (3, 3)
decoding_cctf

Property for self._decoding_cctf private attribute.

Returns:self._decoding_cctf.
Return type:callable
encoding_cctf

Property for self._encoding_cctf private attribute.

Returns:self._encoding_cctf.
Return type:callable
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)
use_derived_RGB_to_XYZ_matrix

Property for self._use_derived_RGB_to_XYZ_matrix private attribute.

Returns:self._use_derived_RGB_to_XYZ_matrix.
Return type:bool
use_derived_XYZ_to_RGB_matrix

Property for self._use_derived_XYZ_to_RGB_matrix private attribute.

Returns:self._use_derived_XYZ_to_RGB_matrix.
Return type:bool
use_derived_transformation_matrices(usage=True)[source]

Enables or disables usage of both derived transformations matrices, the normalised primary matrix and its inverse in subsequent computations.

Parameters:usage (bool, optional) – Whether to use the derived transformations matrices.
Returns:Definition success.
Return type:bool
whitepoint

Property for self._whitepoint private attribute.

Returns:self._whitepoint.
Return type:array_like
colour.models.rgb.rgb_colourspace.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_colourspace.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_colourspace.RGB_to_RGB_matrix(input_colourspace, output_colourspace, chromatic_adaptation_transform=u'CAT02')[source]

Computes the matrix \(M\) converting from given input RGB colourspace to output RGB colourspace using given chromatic adaptation method.

Parameters:
  • 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:

Conversion matrix \(M\).
Return type:

ndarray

Examples

>>> from colour import sRGB_COLOURSPACE, PROPHOTO_RGB_COLOURSPACE
>>> RGB = np.array([0.01103742, 0.12734226, 0.11632971])
>>> RGB_to_RGB_matrix(
...     sRGB_COLOURSPACE,
...     PROPHOTO_RGB_COLOURSPACE)  
array([[ 0.5288241...,  0.3340609...,  0.1373616...],
       [ 0.0975294...,  0.8790074...,  0.0233981...],
       [ 0.0163599...,  0.1066124...,  0.8772485...]])
colour.models.rgb.rgb_colourspace.RGB_to_RGB(RGB, input_colourspace, output_colourspace, chromatic_adaptation_transform=u'CAT02', apply_decoding_cctf=False, apply_encoding_cctf=False)[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.
  • apply_decoding_cctf (bool, optional) – Apply input colourspace decoding colour component transfer function / electro-optical transfer function.
  • apply_encoding_cctf (bool, optional) – Apply output colourspace encoding colour component transfer function / opto-electronic transfer function.
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.0643561...,  0.1157331...,  0.1158069...])