colour.RGB_Colourspace#
- class colour.RGB_Colourspace(name: str, primaries: ArrayLike, whitepoint: ArrayLike, whitepoint_name: str | None = None, matrix_RGB_to_XYZ: ArrayLike | None = None, matrix_XYZ_to_RGB: ArrayLike | None = None, cctf_encoding: Callable | None = None, cctf_decoding: Callable | None = None, use_derived_matrix_RGB_to_XYZ: bool = False, use_derived_matrix_XYZ_to_RGB: bool = False)[source]#
Bases:
object
Implement 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 from 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 givenmatrix_RGB_to_XYZ
andmatrix_XYZ_to_RGB
arguments and also computes their derived counterpart using theprimaries
andwhitepoint
arguments.Whether the initialisation or derived matrices are used in subsequent computations is dependent on the
colour.RGB_Colourspace.use_derived_matrix_RGB_to_XYZ
andcolour.RGB_Colourspace.use_derived_matrix_XYZ_to_RGB
attribute values.- Parameters:
name (str) – RGB colourspace name.
primaries (ArrayLike) – RGB colourspace primaries.
whitepoint (ArrayLike) – RGB colourspace whitepoint.
whitepoint_name (str | None) – RGB colourspace whitepoint name.
matrix_RGB_to_XYZ (ArrayLike | None) – Transformation matrix from colourspace to CIE XYZ tristimulus values.
matrix_XYZ_to_RGB (ArrayLike | None) – Transformation matrix from CIE XYZ tristimulus values to colourspace.
cctf_encoding (Callable | None) – Encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF) that maps estimated tristimulus values in a scene to \(R'G'B'\) video component signal value.
cctf_decoding (Callable | None) – Decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF) that maps an \(R'G'B'\) video component signal value to tristimulus values at the display.
use_derived_matrix_RGB_to_XYZ (bool) – Whether to use the instantiation time normalised primary matrix or to use a computed derived normalised primary matrix.
use_derived_matrix_XYZ_to_RGB (bool) – Whether to use the instantiation time inverse normalised primary matrix or to use a computed derived inverse normalised primary matrix.
Attributes
Methods
Notes
The normalised primary matrix defined by
colour.RGB_Colourspace.matrix_RGB_to_XYZ
property 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]) >>> matrix_RGB_to_XYZ = np.identity(3) >>> matrix_XYZ_to_RGB = np.identity(3) >>> colourspace = RGB_Colourspace( ... "RGB Colourspace", ... p, ... whitepoint, ... "ACES", ... matrix_RGB_to_XYZ, ... matrix_XYZ_to_RGB, ... ) >>> colourspace.matrix_RGB_to_XYZ array([[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]]) >>> colourspace.matrix_XYZ_to_RGB array([[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]]) >>> colourspace.use_derived_transformation_matrices(True) >>> colourspace.matrix_RGB_to_XYZ 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.matrix_XYZ_to_RGB 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_matrix_RGB_to_XYZ = False >>> colourspace.matrix_RGB_to_XYZ array([[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]]) >>> colourspace.use_derived_matrix_XYZ_to_RGB = False >>> colourspace.matrix_XYZ_to_RGB array([[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]])
- __init__(name: str, primaries: ArrayLike, whitepoint: ArrayLike, whitepoint_name: str | None = None, matrix_RGB_to_XYZ: ArrayLike | None = None, matrix_XYZ_to_RGB: ArrayLike | None = None, cctf_encoding: Callable | None = None, cctf_decoding: Callable | None = None, use_derived_matrix_RGB_to_XYZ: bool = False, use_derived_matrix_XYZ_to_RGB: bool = False) None [source]#
- Parameters:
name (str) –
primaries (ArrayLike) –
whitepoint (ArrayLike) –
whitepoint_name (str | None) –
matrix_RGB_to_XYZ (ArrayLike | None) –
matrix_XYZ_to_RGB (ArrayLike | None) –
cctf_encoding (Callable | None) –
cctf_decoding (Callable | None) –
use_derived_matrix_RGB_to_XYZ (bool) –
use_derived_matrix_XYZ_to_RGB (bool) –
- Return type:
None
- property name: str#
Getter and setter property for the name.
- Parameters:
value – Value to set the name with.
- Returns:
RGB colourspace name.
- Return type:
- property primaries: NDArrayFloat#
Getter and setter property for the primaries.
- Parameters:
value – Value to set the primaries with.
- Returns:
RGB colourspace primaries.
- Return type:
- property whitepoint: NDArrayFloat#
Getter and setter property for the whitepoint.
- Parameters:
value – Value to set the whitepoint with.
- Returns:
RGB colourspace whitepoint.
- Return type:
- property matrix_RGB_to_XYZ: NDArrayFloat#
Getter and setter property for the transformation matrix from colourspace to CIE XYZ tristimulus values.
- Parameters:
value – Transformation matrix from colourspace to CIE XYZ tristimulus values.
- Returns:
Transformation matrix from colourspace to CIE XYZ tristimulus values.
- Return type:
- __weakref__#
list of weak references to the object (if defined)
- property matrix_XYZ_to_RGB: NDArrayFloat#
Getter and setter property for the transformation matrix from CIE XYZ tristimulus values to colourspace.
- Parameters:
value – Transformation matrix from CIE XYZ tristimulus values to colourspace.
- Returns:
Transformation matrix from CIE XYZ tristimulus values to colourspace.
- Return type:
- property cctf_encoding: Callable | None#
Getter and setter property for the encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF).
- Parameters:
value – Encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF).
- Returns:
Encoding colour component transfer function (Encoding CCTF) / opto-electronic transfer function (OETF).
- Return type:
None
or Callable
- property cctf_decoding: Callable | None#
Getter and setter property for the decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF).
- Parameters:
value – Decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF).
- Returns:
Decoding colour component transfer function (Decoding CCTF) / electro-optical transfer function (EOTF).
- Return type:
None
or Callable
- property use_derived_matrix_RGB_to_XYZ: bool#
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 – 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:
- property use_derived_matrix_XYZ_to_RGB: bool#
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 – 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:
- __str__() str [source]#
Return a formatted string representation of the RGB colourspace.
- Returns:
Formatted string representation.
- Return type:
Examples
>>> p = np.array( ... [0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700] ... ) >>> whitepoint = np.array([0.32168, 0.33767]) >>> matrix_RGB_to_XYZ = np.identity(3) >>> matrix_XYZ_to_RGB = np.identity(3) >>> cctf_encoding = lambda x: x >>> cctf_decoding = lambda x: x >>> print( ... RGB_Colourspace( ... "RGB Colourspace", ... p, ... whitepoint, ... "ACES", ... matrix_RGB_to_XYZ, ... matrix_XYZ_to_RGB, ... cctf_encoding, ... cctf_decoding, ... ) ... ) ... RGB Colourspace --------------- Primaries : [[ 7.34700000e-01 2.65300000e-01] [ 0.00000000e+00 1.00000000e+00] [ 1.00000000e-04 -7.70000000e-02]] Whitepoint : [ 0.32168 0.33767] Whitepoint Name : ACES Encoding CCTF : <function <lambda> at 0x...> Decoding CCTF : <function <lambda> at 0x...> NPM : [[ 1. 0. 0.] [ 0. 1. 0.] [ 0. 0. 1.]] NPM -1 : [[ 1. 0. 0.] [ 0. 1. 0.] [ 0. 0. 1.]] Derived NPM : [[ 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]] Derived NPM -1 : [[ 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]] Use Derived NPM : False Use Derived NPM -1 : False
- __repr__() str [source]#
Return an (almost) evaluable string representation of the RGB colourspace.
- Returns:
(Almost) evaluable string representation.
- Return type:
class`str`
Examples
>>> from colour.models import linear_function >>> p = np.array( ... [0.73470, 0.26530, 0.00000, 1.00000, 0.00010, -0.07700] ... ) >>> whitepoint = np.array([0.32168, 0.33767]) >>> matrix_RGB_to_XYZ = np.identity(3) >>> matrix_XYZ_to_RGB = np.identity(3) >>> RGB_Colourspace( ... "RGB Colourspace", ... p, ... whitepoint, ... "ACES", ... matrix_RGB_to_XYZ, ... matrix_XYZ_to_RGB, ... linear_function, ... linear_function, ... ) ... RGB_Colourspace('RGB Colourspace', [[ 7.34700000e-01, 2.65300000e-01], [ 0.00000000e+00, 1.00000000e+00], [ 1.00000000e-04, -7.70000000e-02]], [ 0.32168, 0.33767], 'ACES', [[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]], [[ 1., 0., 0.], [ 0., 1., 0.], [ 0., 0., 1.]], linear_function, linear_function, False, False)
- use_derived_transformation_matrices(usage: bool = True)[source]#
Enable or disables usage of both derived transformations matrices, the normalised primary matrix and its inverse in subsequent computations.
- Parameters:
usage (bool) – Whether to use the derived transformations matrices.
- chromatically_adapt(whitepoint: ArrayLike, whitepoint_name: str | None = None, chromatic_adaptation_transform: Literal['Bianco 2010', 'Bianco PC 2010', 'Bradford', 'CAT02 Brill 2008', 'CAT02', 'CAT16', 'CMCCAT2000', 'CMCCAT97', 'Fairchild', 'Sharp', 'Von Kries', 'XYZ Scaling'] | str = 'CAT02') RGB_Colourspace [source]#
Chromatically adapt the RGB colourspace primaries \(xy\) chromaticity coordinates from RGB colourspace whitepoint to reference
whitepoint
.- Parameters:
whitepoint (ArrayLike) – Reference illuminant / whitepoint \(xy\) chromaticity coordinates.
whitepoint_name (str | None) – Reference illuminant / whitepoint name.
chromatic_adaptation_transform (Literal['Bianco 2010', 'Bianco PC 2010', 'Bradford', 'CAT02 Brill 2008', 'CAT02', 'CAT16', 'CMCCAT2000', 'CMCCAT97', 'Fairchild', 'Sharp', 'Von Kries', 'XYZ Scaling'] | str) – Chromatic adaptation transform.
- Returns:
Chromatically adapted RGB colourspace.
- Return type:
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 'D50' ------------------------------------------------ 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() RGB_Colourspace [source]#
Return a copy of the RGB colourspace.
- Returns:
RGB colourspace copy.
- Return type: