Coverage for colour/models/rgb/datasets/color_interop_forum.py: 100%
71 statements
« prev ^ index » next coverage.py v7.11.0, created at 2025-11-15 19:01 +1300
1"""
2Color Interop Forum - Recommendation
3====================================
5Define the *Color Interop Forum* (CIF) recommendation *RGB* colourspaces:
7- :attr:`colour.models.RGB_COLOURSPACE_LIN_REC709_SCENE`
8- :attr:`colour.models.RGB_COLOURSPACE_LIN_P3D65_SCENE`
9- :attr:`colour.models.RGB_COLOURSPACE_LIN_REC2020_SCENE`
10- :attr:`colour.models.RGB_COLOURSPACE_LIN_ADOBERGB_SCENE`
11- :attr:`colour.models.RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE`
12- :attr:`colour.models.RGB_COLOURSPACE_SRGB_REC709_SCENE`
13- :attr:`colour.models.RGB_COLOURSPACE_G22_REC709_SCENE`
14- :attr:`colour.models.RGB_COLOURSPACE_G18_REC709_SCENE`
15- :attr:`colour.models.RGB_COLOURSPACE_SRGB_AP1_SCENE`
16- :attr:`colour.models.RGB_COLOURSPACE_G22_AP1_SCENE`
17- :attr:`colour.models.RGB_COLOURSPACE_SRGB_P3D65_SCENE`
18- :attr:`colour.models.RGB_COLOURSPACE_G22_ADOBERGB_SCENE`
19- :attr:`colour.models.RGB_COLOURSPACES_TEXTURE_ASSETS_AND_CG_RENDERING_CIF`
21References
22----------
23- :cite:`ASWFColorInteropForum2024` : ASWF Color Interop Forum. (2024). Color
24 Space Encodings for Texture Assets and CG Rendering.
25 https://docs.google.com/document/d/1IV3e_9gpTOS_EFYRv2YGDuhExa4wTaPYHW1HyV36qUU
26"""
28from __future__ import annotations
30from functools import partial
32import numpy as np
34from colour.colorimetry import CCS_ILLUMINANTS
35from colour.models.rgb import (
36 RGB_Colourspace,
37 eotf_inverse_sRGB,
38 eotf_sRGB,
39 gamma_function,
40 linear_function,
41)
42from colour.models.rgb.datasets import (
43 RGB_COLOURSPACE_ACES2065_1,
44 RGB_COLOURSPACE_ACESCG,
45 RGB_COLOURSPACE_ADOBE_RGB1998,
46 RGB_COLOURSPACE_BT709,
47 RGB_COLOURSPACE_BT2020,
48 RGB_COLOURSPACE_DISPLAY_P3,
49 RGB_COLOURSPACE_P3_D65,
50)
51from colour.utilities import LazyCanonicalMapping
53__author__ = "Colour Developers"
54__copyright__ = "Copyright 2013 Colour Developers"
55__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
56__maintainer__ = "Colour Developers"
57__email__ = "colour-developers@colour-science.org"
58__status__ = "Production"
60__all__ = [
61 "RGB_COLOURSPACE_LIN_REC709_SCENE",
62 "RGB_COLOURSPACE_LIN_P3D65_SCENE",
63 "RGB_COLOURSPACE_LIN_REC2020_SCENE",
64 "RGB_COLOURSPACE_LIN_ADOBERGB_SCENE",
65 "RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE",
66 "RGB_COLOURSPACE_SRGB_REC709_SCENE",
67 "RGB_COLOURSPACE_G22_REC709_SCENE",
68 "RGB_COLOURSPACE_G18_REC709_SCENE",
69 "RGB_COLOURSPACE_SRGB_AP1_SCENE",
70 "RGB_COLOURSPACE_G22_AP1_SCENE",
71 "RGB_COLOURSPACE_SRGB_P3D65_SCENE",
72 "RGB_COLOURSPACE_G22_ADOBERGB_SCENE",
73 "RGB_COLOURSPACES_TEXTURE_ASSETS_AND_CG_RENDERING_CIF",
74]
76RGB_COLOURSPACE_LIN_REC709_SCENE: RGB_Colourspace = RGB_COLOURSPACE_BT709.copy()
77RGB_COLOURSPACE_LIN_REC709_SCENE.cctf_encoding = linear_function
78RGB_COLOURSPACE_LIN_REC709_SCENE.cctf_decoding = linear_function
79RGB_COLOURSPACE_LIN_REC709_SCENE.name = "Linear Rec.709 (sRGB)"
80RGB_COLOURSPACE_LIN_REC709_SCENE.__doc__ = """
81*Linear Rec.709 (sRGB)* colourspace.
83Still one of the most commonly used computer graphics (CG) rendering space.
84However, it is a small gamut which means it is not possible to represent
85certain colourful objects with only positive RGB values. This poses challenges
86for rendering since negative values cause computational problems. It is
87recommended that the industry move to wider gamut colourspaces such as *ACEScg*
88for rendering.
90References
91----------
92:cite:`ASWFColorInteropForum2024`
93"""
95RGB_COLOURSPACE_LIN_P3D65_SCENE: RGB_Colourspace = RGB_COLOURSPACE_P3_D65.copy()
96RGB_COLOURSPACE_LIN_P3D65_SCENE.cctf_encoding = linear_function
97RGB_COLOURSPACE_LIN_P3D65_SCENE.cctf_decoding = linear_function
98RGB_COLOURSPACE_LIN_P3D65_SCENE.name = "Linear P3-D65"
99RGB_COLOURSPACE_LIN_P3D65_SCENE.__doc__ = """
100*Linear P3-D65* colourspace.
102Not as good a rendering space as *ACEScg*, but better than *Linear Rec.709*
103since it has a larger gamut. It may be easier for artists to use than *ACEScg*
104since most modern monitors are able to show almost all of the *DCI-P3* gamut,
105which is not true for *ACEScg*.
107References
108----------
109:cite:`ASWFColorInteropForum2024`
110"""
112RGB_COLOURSPACE_LIN_REC2020_SCENE: RGB_Colourspace = RGB_COLOURSPACE_BT2020.copy()
113RGB_COLOURSPACE_LIN_REC2020_SCENE.cctf_encoding = linear_function
114RGB_COLOURSPACE_LIN_REC2020_SCENE.cctf_decoding = linear_function
115RGB_COLOURSPACE_LIN_REC2020_SCENE.name = "Linear Rec.2020"
116RGB_COLOURSPACE_LIN_REC2020_SCENE.__doc__ = """
117*Linear Rec.2020* colourspace.
119Its gamut is very similar to *ACEScg* and thus makes a good rendering
120colourspace, though it is not often used for that purpose. The primaries are
121on the spectrum locus and therefore most monitors are unable to display the
122entire gamut.
124References
125----------
126:cite:`ASWFColorInteropForum2024`
127"""
129RGB_COLOURSPACE_LIN_ADOBERGB_SCENE: RGB_Colourspace = (
130 RGB_COLOURSPACE_ADOBE_RGB1998.copy()
131)
132RGB_COLOURSPACE_LIN_ADOBERGB_SCENE.cctf_encoding = linear_function
133RGB_COLOURSPACE_LIN_ADOBERGB_SCENE.cctf_decoding = linear_function
134RGB_COLOURSPACE_LIN_ADOBERGB_SCENE.name = "Linear AdobeRGB"
135RGB_COLOURSPACE_LIN_ADOBERGB_SCENE.__doc__ = """
136*Linear AdobeRGB* colourspace.
138References
139----------
140:cite:`ASWFColorInteropForum2024`
141"""
143RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE: RGB_Colourspace = RGB_Colourspace(
144 "CIE XYZ-D65 - Scene-referred",
145 np.array(
146 [
147 [1.0, 0.0],
148 [0.0, 1.0],
149 [0.0, 0.0],
150 ]
151 ),
152 CCS_ILLUMINANTS["CIE 1931 2 Degree Standard Observer"]["E"],
153 "E",
154 cctf_encoding=linear_function,
155 cctf_decoding=linear_function,
156 use_derived_matrix_RGB_to_XYZ=True,
157 use_derived_matrix_XYZ_to_RGB=True,
158)
159RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE.__doc__ = """
160*CIE XYZ-D65 - Scene-referred* colourspace.
162This colourspace is not recommended for storing images. It is provided because
163there are many situations in computer graphics where the goal is to simulate
164some natural phenomena that are described by models or data that involves
165*CIE* colorimetry such as physical sky models, daylight or blackbody curves,
166spectral material models, diffraction effects, etc. When such data is used,
167this colourspace provides a bridge to convert it into one of the other
168colourspace encodings.
170References
171----------
172:cite:`ASWFColorInteropForum2024`
173"""
175RGB_COLOURSPACE_SRGB_REC709_SCENE: RGB_Colourspace = RGB_COLOURSPACE_BT709.copy()
176RGB_COLOURSPACE_SRGB_REC709_SCENE.cctf_encoding = eotf_inverse_sRGB
177RGB_COLOURSPACE_SRGB_REC709_SCENE.cctf_decoding = eotf_sRGB
178RGB_COLOURSPACE_SRGB_REC709_SCENE.name = "sRGB Encoded Rec.709 (sRGB)"
179RGB_COLOURSPACE_SRGB_REC709_SCENE.__doc__ = """
180*sRGB Encoded Rec.709 (sRGB)* colourspace.
182References
183----------
184:cite:`ASWFColorInteropForum2024`
185"""
187RGB_COLOURSPACE_G22_REC709_SCENE: RGB_Colourspace = RGB_COLOURSPACE_BT709.copy()
188RGB_COLOURSPACE_G22_REC709_SCENE.cctf_encoding = partial(
189 gamma_function, exponent=1 / 2.2
190)
191RGB_COLOURSPACE_G22_REC709_SCENE.cctf_decoding = partial(gamma_function, exponent=2.2)
192RGB_COLOURSPACE_G22_REC709_SCENE.name = "Gamma 2.2 Encoded Rec.709"
193RGB_COLOURSPACE_G22_REC709_SCENE.__doc__ = """
194*Gamma 2.2 Encoded Rec.709* colourspace.
196References
197----------
198:cite:`ASWFColorInteropForum2024`
199"""
201RGB_COLOURSPACE_G18_REC709_SCENE: RGB_Colourspace = RGB_COLOURSPACE_BT709.copy()
202RGB_COLOURSPACE_G18_REC709_SCENE.cctf_encoding = partial(
203 gamma_function, exponent=1 / 1.8
204)
205RGB_COLOURSPACE_G18_REC709_SCENE.cctf_decoding = partial(gamma_function, exponent=1.8)
206RGB_COLOURSPACE_G18_REC709_SCENE.name = "Gamma 1.8 Encoded Rec.709"
207RGB_COLOURSPACE_G18_REC709_SCENE.__doc__ = """
208*Gamma 1.8 Encoded Rec.709* colourspace.
210References
211----------
212:cite:`ASWFColorInteropForum2024`
213"""
215RGB_COLOURSPACE_SRGB_AP1_SCENE: RGB_Colourspace = RGB_COLOURSPACE_ACESCG.copy()
216RGB_COLOURSPACE_SRGB_AP1_SCENE.cctf_encoding = eotf_inverse_sRGB
217RGB_COLOURSPACE_SRGB_AP1_SCENE.cctf_decoding = eotf_sRGB
218RGB_COLOURSPACE_SRGB_AP1_SCENE.name = "sRGB Encoded AP1"
219RGB_COLOURSPACE_SRGB_AP1_SCENE.__doc__ = """
220*sRGB Encoded AP1* colourspace.
222This colourspace is used in game engines that implement texture decoding on the
223GPU using the sRGB piece-wise transfer function and when the working
224colourspace is *ACEScg*.
226References
227----------
228:cite:`ASWFColorInteropForum2024`
229"""
231RGB_COLOURSPACE_G22_AP1_SCENE: RGB_Colourspace = RGB_COLOURSPACE_ACESCG.copy()
232RGB_COLOURSPACE_G22_AP1_SCENE.cctf_encoding = partial(gamma_function, exponent=1 / 2.2)
233RGB_COLOURSPACE_G22_AP1_SCENE.cctf_decoding = partial(gamma_function, exponent=2.2)
234RGB_COLOURSPACE_G22_AP1_SCENE.name = "Gamma 2.2 Encoded AP1"
235RGB_COLOURSPACE_G22_AP1_SCENE.__doc__ = """
236*Gamma 2.2 Encoded AP1* colourspace.
238References
239----------
240:cite:`ASWFColorInteropForum2024`
241"""
243RGB_COLOURSPACE_SRGB_P3D65_SCENE: RGB_Colourspace = RGB_COLOURSPACE_DISPLAY_P3.copy()
244RGB_COLOURSPACE_SRGB_P3D65_SCENE.name = "sRGB Encoded P3-D65"
245RGB_COLOURSPACE_SRGB_P3D65_SCENE.__doc__ = """
246*sRGB Encoded P3-D65* colourspace.
248References
249----------
250:cite:`ASWFColorInteropForum2024`
251"""
253RGB_COLOURSPACE_G22_ADOBERGB_SCENE: RGB_Colourspace = (
254 RGB_COLOURSPACE_ADOBE_RGB1998.copy()
255)
256RGB_COLOURSPACE_G22_ADOBERGB_SCENE.cctf_encoding = partial(
257 gamma_function, exponent=1 / 2.2
258)
259RGB_COLOURSPACE_G22_ADOBERGB_SCENE.cctf_decoding = partial(gamma_function, exponent=2.2)
260RGB_COLOURSPACE_G22_ADOBERGB_SCENE.name = "Gamma 2.2 Encoded AdobeRGB"
261RGB_COLOURSPACE_G22_ADOBERGB_SCENE.__doc__ = """
262*Gamma 2.2 Encoded AdobeRGB* colourspace.
264References
265----------
266:cite:`ASWFColorInteropForum2024`
267"""
269RGB_COLOURSPACES_TEXTURE_ASSETS_AND_CG_RENDERING_CIF: LazyCanonicalMapping = LazyCanonicalMapping( # noqa: E501
270 {
271 "ACEScg": RGB_COLOURSPACE_ACESCG,
272 "ACES2065-1": RGB_COLOURSPACE_ACES2065_1,
273 RGB_COLOURSPACE_LIN_REC709_SCENE.name: RGB_COLOURSPACE_LIN_REC709_SCENE,
274 RGB_COLOURSPACE_LIN_P3D65_SCENE.name: RGB_COLOURSPACE_LIN_P3D65_SCENE,
275 RGB_COLOURSPACE_LIN_REC2020_SCENE.name: RGB_COLOURSPACE_LIN_REC2020_SCENE,
276 RGB_COLOURSPACE_LIN_ADOBERGB_SCENE.name: RGB_COLOURSPACE_LIN_ADOBERGB_SCENE,
277 RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE.name: RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE,
278 RGB_COLOURSPACE_SRGB_REC709_SCENE.name: RGB_COLOURSPACE_SRGB_REC709_SCENE,
279 RGB_COLOURSPACE_G22_REC709_SCENE.name: RGB_COLOURSPACE_G22_REC709_SCENE,
280 RGB_COLOURSPACE_G18_REC709_SCENE.name: RGB_COLOURSPACE_G18_REC709_SCENE,
281 RGB_COLOURSPACE_SRGB_AP1_SCENE.name: RGB_COLOURSPACE_SRGB_AP1_SCENE,
282 RGB_COLOURSPACE_G22_AP1_SCENE.name: RGB_COLOURSPACE_G22_AP1_SCENE,
283 RGB_COLOURSPACE_SRGB_P3D65_SCENE.name: RGB_COLOURSPACE_SRGB_P3D65_SCENE,
284 RGB_COLOURSPACE_G22_ADOBERGB_SCENE.name: RGB_COLOURSPACE_G22_ADOBERGB_SCENE,
285 # Compact Names
286 "lin_ap1_scene": RGB_COLOURSPACE_ACESCG,
287 "lin_ap0_scene": RGB_COLOURSPACE_ACES2065_1,
288 "lin_rec709_scene": RGB_COLOURSPACE_LIN_REC709_SCENE,
289 "lin_p3d65_scene": RGB_COLOURSPACE_LIN_P3D65_SCENE,
290 "lin_rec2020_scene": RGB_COLOURSPACE_LIN_REC2020_SCENE,
291 "lin_adobergb_scene": RGB_COLOURSPACE_LIN_ADOBERGB_SCENE,
292 "lin_ciexyzd65_scene": RGB_COLOURSPACE_LIN_CIEXYZD65_SCENE,
293 "srgb_rec709_scene": RGB_COLOURSPACE_SRGB_REC709_SCENE,
294 "g22_rec709_scene": RGB_COLOURSPACE_G22_REC709_SCENE,
295 "g18_rec709_scene": RGB_COLOURSPACE_G18_REC709_SCENE,
296 "srgb_ap1_scene": RGB_COLOURSPACE_SRGB_AP1_SCENE,
297 "g22_ap1_scene": RGB_COLOURSPACE_G22_AP1_SCENE,
298 "srgb_p3d65_scene": RGB_COLOURSPACE_SRGB_P3D65_SCENE,
299 "g22_adobergb_scene": RGB_COLOURSPACE_G22_ADOBERGB_SCENE,
300 }
301)
302RGB_COLOURSPACES_TEXTURE_ASSETS_AND_CG_RENDERING_CIF.__doc__ = """
303*RGB* colourspace encodings for texture assets and computer graphics (CG)
304rendering.
306References
307----------
308:cite:`ASWFColorInteropForum2024`
309"""