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 RGB colourspace datasets from modules including colour.models.datasets.aces_rgb.

Colour science literature related to RGB colourspaces and encodings defines datasets using different degrees of precision or rounding. While instances where a whitepoint differs from its canonical agreed value are rare, normalised primary matrices are commonly rounded at different decimal places. This can yield large discrepancies in computations.

Such an occurrence is the V-Gamut colourspace white paper, which 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 equal to 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]]

To provide support for both literature-defined datasets 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 specified matrix_RGB_to_XYZ and matrix_XYZ_to_RGB arguments and also computes their derived counterparts using the primaries and whitepoint arguments.

Whether instantiation or derived matrices are used in subsequent computations depends on the colour.RGB_Colourspace.use_derived_matrix_RGB_to_XYZ and colour.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

name
primaries
whitepoint
whitepoint_name
matrix_RGB_to_XYZ
matrix_XYZ_to_RGB
cctf_encoding
cctf_decoding
use_derived_matrix_RGB_to_XYZ
use_derived_matrix_XYZ_to_RGB

Methods

__init__
__str__
__repr__
use_derived_transformation_matrices
chromatically_adapt
copy

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 for the RGB colourspace name.

Parameters:: value – Value to set the name with.
Returns:: RGB colourspace name.
Return type:: str

property primaries: NDArrayFloat#

Getter and setter for the RGB colourspace primaries.

Parameters:: value – Value to set the primaries with.
Returns:: RGB colourspace primaries.
Return type:: numpy.ndarray

property whitepoint: NDArrayFloat#

Getter and setter for the RGB colourspace whitepoint.

Parameters:: value – Value to set the whitepoint with.
Returns:: RGB colourspace whitepoint.
Return type:: numpy.ndarray

property whitepoint_name: str | None#

Getter and setter for the RGB colourspace whitepoint name.

Define or retrieve the name identifier for the reference illuminant (whitepoint) used by this RGB colourspace. This property allows tracking of standardized illuminant names such as ‘D65’, ‘D50’, or custom whitepoint identifiers.

Parameters:: value – Name identifier to set for the RGB colourspace whitepoint. Can be a standard illuminant name or custom identifier.
Returns:: RGB colourspace whitepoint name identifier. Returns None if no name has been specified.
Return type:: str or None

property matrix_RGB_to_XYZ: NDArrayFloat#

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

Parameters:: value – Transformation matrix from RGB colourspace to CIE XYZ tristimulus values.
Returns:: Transformation matrix from RGB colourspace to CIE XYZ tristimulus values.
Return type:: numpy.ndarray

__weakref__#: list of weak references to the object

property matrix_XYZ_to_RGB: NDArrayFloat#

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

Parameters:: value – Transformation matrix from CIE XYZ tristimulus values to the colourspace.
Returns:: Transformation matrix from CIE XYZ tristimulus values to the colourspace.
Return type:: numpy.ndarray

property cctf_encoding: Callable | None#

Getter and setter 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:: Callable or None

property cctf_decoding: Callable | None#

Getter and setter 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:: Callable or None

property use_derived_matrix_RGB_to_XYZ: bool#

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

Control whether the RGB to XYZ transformation uses the pre-computed normalised primary matrix from instantiation or derives it dynamically from the current primaries and whitepoint.

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:: bool

property use_derived_matrix_XYZ_to_RGB: bool#

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

Control whether the XYZ to RGB transformation uses the pre-computed inverse matrix from instantiation or derives it dynamically from the current primary matrix.

Parameters:: value – Whether to use the instantiation time inverse normalised primary matrix or to compute a derived inverse normalised primary matrix.
Returns:: Whether to use the instantiation time inverse normalised primary matrix or to compute a derived inverse normalised primary matrix.
Return type:: bool

__str__() → str[source]#

Generate a formatted string representation of the RGB colourspace.

Returns:: Formatted string representation displaying colourspace properties including primaries, whitepoint, encoding/decoding CCTFs, and normalised primary matrices.
Return type:: str

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 evaluable string representation of the RGB colourspace.

The representation includes all parameters needed to reconstruct the colourspace instance.

Returns:: Evaluable string representation.
Return type:: 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) → None[source]#

Enable or disable usage of both derived transformation matrices, the normalised primary matrix and its inverse in subsequent computations.

Parameters:: usage (bool) – Whether to use the derived transformation matrices.
Return type:: None

chromatically_adapt(whitepoint: ArrayLike, whitepoint_name: str | None = None, chromatic_adaptation_transform: LiteralChromaticAdaptationTransform | str = 'CAT02') → RGB_Colourspace[source]#

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

Parameters:

whitepoint (ArrayLike) – Reference illuminant / whitepoint \(xy\) chromaticity coordinates.
whitepoint_name (str | None) – Reference illuminant / whitepoint name.
chromatic_adaptation_transform (LiteralChromaticAdaptationTransform | str) – Chromatic adaptation transform.

Returns:

Chromatically adapted RGB colourspace.

Return type:

colour.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 '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]#

Create a deep copy of the RGB colourspace instance.

Generate an independent copy of this RGB colourspace with all attributes duplicated, including primaries, whitepoint, matrices, and transfer functions.

Returns:: Independent deep copy of the RGB colourspace instance.
Return type:: colour.RGB_Colourspace

colour.RGB_Colourspace#

This Page