colour.RGB_Colourspace

class colour.RGB_Colourspace(name, primaries, whitepoint, whitepoint_name=None, RGB_to_XYZ_matrix=None, XYZ_to_RGB_matrix=None, cctf_encoding=None, cctf_decoding=None, use_derived_RGB_to_XYZ_matrix=False, use_derived_XYZ_to_RGB_matrix=False)[source]

Bases: object

Implements support for the RGB colourspaces datasets from colour.models.datasets.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, that defines the V-Gamut to ITU-R BT.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 ITU-R BT.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 colour.RGB_Colourspace class provides two sets of transformation matrices:

  • Instantiation transformation matrices

  • Derived transformation matrices

Upon instantiation, the colour.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 colour.RGB_Colourspace.use_derived_RGB_to_XYZ_matrix and colour.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.

  • whitepoint_name (unicode, optional) – RGB colourspace whitepoint name.

  • 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.

  • cctf_encoding (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.

  • cctf_decoding (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 instantiation 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 instantiation time inverse normalised primary matrix or to use a computed derived inverse normalised primary matrix.

name
primaries
whitepoint
whitepoint_name
RGB_to_XYZ_matrix
XYZ_to_RGB_matrix
cctf_encoding
cctf_decoding
use_derived_RGB_to_XYZ_matrix
use_derived_XYZ_to_RGB_matrix
__str_\_
__repr_\_
use_derived_transformation_matrices()[source]
chromatically_adapt()[source]
copy()[source]

Notes

  • The normalised primary matrix defined by colour.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

[InternationalECommission99], [Panasonic14]

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, 'ACES',
...                               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.]])
property RGB_to_XYZ_matrix

Getter and setter property for the transformation matrix from colourspace to CIE XYZ tristimulus values.

Parameters

value (array_like) – Transformation matrix from colourspace to CIE XYZ tristimulus values.

Returns

Transformation matrix from colourspace to CIE XYZ tristimulus values.

Return type

array_like

property XYZ_to_RGB_matrix

Getter and setter property for the transformation matrix from CIE XYZ tristimulus values to colourspace.

Parameters

value (array_like) – Transformation matrix from CIE XYZ tristimulus values to colourspace.

Returns

Transformation matrix from CIE XYZ tristimulus values to colourspace.

Return type

array_like

property cctf_decoding

Getter and setter property for the decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF / EOCF).

Parameters

value (callable) – Decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF / EOCF).

Returns

Decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF / EOCF).

Return type

callable

property cctf_encoding

Getter and setter property for the encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF / OECF).

Parameters

value (callable) – Encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF / OECF).

Returns

Encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF / OECF).

Return type

callable

chromatically_adapt(whitepoint, whitepoint_name=None, chromatic_adaptation_transform='CAT02')[source]

Chromatically adapts the RGB colourspace primaries \(xy\) chromaticity coordinates from RGB colourspace whitepoint to reference whitepoint.

Parameters
  • whitepoint (array_like) – Reference illuminant / whitepoint \(xy\) chromaticity coordinates.

  • whitepoint_name (unicode, optional) – Reference illuminant / whitepoint name.

  • 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

Return type

Chromatically adapted RGB colourspace.

Examples

>>> p = np.array(
...     [0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700])
>>> w_t = np.array([0.32168, 0.33767])
>>> w_r = np.array([0.31270, 0.32900])
>>> colourspace = RGB_Colourspace('RGB Colourspace', p, w_t, 'D65')
>>> print(colourspace.chromatically_adapt(w_r, 'D50', 'Bradford'))
... 
RGB Colourspace - Chromatically Adapted to [ 0.3127  0.329 ]
------------------------------------------------------------

Primaries          : [[ 0.73485524  0.26422533]
                      [-0.00617091  1.01131496]
                      [ 0.01596756 -0.0642355 ]]
Whitepoint         : [ 0.3127  0.329 ]
Whitepoint Name    : D50
Encoding CCTF      : None
Decoding CCTF      : None
NPM                : None
NPM -1             : None
Derived NPM        : [[ 0.93827985 -0.00445145  0.01662752]
                      [ 0.33736889  0.72952157 -0.06689046]
                      [ 0.00117395 -0.00371071  1.09159451]]
Derived NPM -1     : [[ 1.06349549  0.00640891 -0.01580679]
                      [-0.49207413  1.36822341  0.09133709]
                      [-0.00281646  0.00464417  0.91641857]]
Use Derived NPM    : True
Use Derived NPM -1 : True
copy()[source]

Returns a copy of the RGB colourspace.

Returns

RGB colourspace copy.

Return type

RGB_Colourspace

property name

Getter and setter property for the name.

Parameters

value (unicode) – Value to set the name with.

Returns

RGB colourspace name.

Return type

unicode

property primaries

Getter and setter property for the primaries.

Parameters

value (array_like) – Value to set the primaries with.

Returns

RGB colourspace primaries.

Return type

array_like

property use_derived_RGB_to_XYZ_matrix

Getter and setter property for whether to use the instantiation time normalised primary matrix or to use a computed derived normalised primary matrix.

Parameters

value (bool) – Whether to use the instantiation time normalised primary matrix or to use a computed derived normalised primary matrix.

Returns

Whether to use the instantiation time normalised primary matrix or to use a computed derived normalised primary matrix.

Return type

bool

property use_derived_XYZ_to_RGB_matrix

Getter and setter property for Whether to use the instantiation time inverse normalised primary matrix or to use a computed derived inverse normalised primary matrix.

Parameters

value (bool) – Whether to use the instantiation time inverse normalised primary matrix or to use a computed derived inverse normalised primary matrix.

Returns

Whether to use the instantiation time inverse normalised primary matrix or to use a computed derived inverse normalised primary 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

property whitepoint

Getter and setter property for the whitepoint.

Parameters

value (array_like) – Value to set the whitepoint with.

Returns

RGB colourspace whitepoint.

Return type

array_like

property whitepoint_name

Getter and setter property for the whitepoint_name.

Parameters

value (unicode) – Value to set the whitepoint_name with.

Returns

RGB colourspace whitepoint name.

Return type

unicode