Coverage for models/rgb/datasets/aces.py: 0%
38 statements
« prev ^ index » next coverage.py v7.11.0, created at 2025-11-16 22:49 +1300
1"""
2Academy Color Encoding System
3=============================
5Define the *Academy Color Encoding System* (ACES) related encodings:
7- :attr:`colour.models.RGB_COLOURSPACE_ACES2065_1`
8- :attr:`colour.models.RGB_COLOURSPACE_ACESCG`
9- :attr:`colour.models.RGB_COLOURSPACE_ACESCC`
10- :attr:`colour.models.RGB_COLOURSPACE_ACESCCT`
11- :attr:`colour.models.RGB_COLOURSPACE_ACESPROXY`
13References
14----------
15- :cite:`ASWFColorInteropForum2024` : ASWF Color Interop Forum. (2024). Color
16 Space Encodings for Texture Assets and CG Rendering.
17 https://docs.google.com/document/d/1IV3e_9gpTOS_EFYRv2YGDuhExa4wTaPYHW1HyV36qUU
18- :cite:`TheAcademyofMotionPictureArtsandSciences2014q` : The Academy of
19 Motion Picture Arts and Sciences, Science and Technology Council, & Academy
20 Color Encoding System (ACES) Project Subcommittee. (2014). Technical
21 Bulletin TB-2014-004 - Informative Notes on SMPTE ST 2065-1 - Academy Color
22 Encoding Specification (ACES) (pp. 1-40). Retrieved December 19, 2014, from
23 http://j.mp/TB-2014-004
24- :cite:`TheAcademyofMotionPictureArtsandSciences2014r` : The Academy of
25 Motion Picture Arts and Sciences, Science and Technology Council, & Academy
26 Color Encoding System (ACES) Project Subcommittee. (2014). Technical
27 Bulletin TB-2014-012 - Academy Color Encoding System Version 1.0 Component
28 Names (pp. 1-8). Retrieved December 19, 2014, from http://j.mp/TB-2014-012
29- :cite:`TheAcademyofMotionPictureArtsandSciences2014s` : The Academy of
30 Motion Picture Arts and Sciences, Science and Technology Council, & Academy
31 Color Encoding System (ACES) Project Subcommittee. (2013). Specification
32 S-2013-001 - ACESproxy, an int Log Encoding of ACES Image Data.
33 Retrieved December 19, 2014, from http://j.mp/S-2013-001
34- :cite:`TheAcademyofMotionPictureArtsandSciences2014t` : The Academy of
35 Motion Picture Arts and Sciences, Science and Technology Council, & Academy
36 Color Encoding System (ACES) Project Subcommittee. (2014). Specification
37 S-2014-003 - ACEScc, A Logarithmic Encoding of ACES Data for use within
38 Color Grading Systems (pp. 1-12). Retrieved December 19, 2014, from
39 http://j.mp/S-2014-003
40- :cite:`TheAcademyofMotionPictureArtsandSciences2015b` : The Academy of
41 Motion Picture Arts and Sciences, Science and Technology Council, & Academy
42 Color Encoding System (ACES) Project Subcommittee. (2015). Specification
43 S-2014-004 - ACEScg - A Working Space for CGI Render and Compositing
44 (pp. 1-9). Retrieved April 24, 2015, from http://j.mp/S-2014-004
45- :cite:`TheAcademyofMotionPictureArtsandSciences2016c` : The Academy of
46 Motion Picture Arts and Sciences, Science and Technology Council, & Academy
47 Color Encoding System (ACES) Project. (2016). Specification S-2016-001 -
48 ACEScct, A Quasi-Logarithmic Encoding of ACES Data for use within Color
49 Grading Systems. Retrieved October 10, 2016, from http://j.mp/S-2016-001
50- :cite:`TheAcademyofMotionPictureArtsandSciencese` : The Academy of Motion
51 Picture Arts and Sciences, Science and Technology Council, & Academy Color
52 Encoding System (ACES) Project Subcommittee. (n.d.). Academy Color Encoding
53 System. Retrieved February 24, 2014, from
54 http://www.oscars.org/science-technology/council/projects/aces.html
55"""
57from __future__ import annotations
59import typing
61import numpy as np
63from colour.colorimetry import CCS_ILLUMINANTS
65if typing.TYPE_CHECKING:
66 from colour.hints import NDArrayFloat
68from colour.models.rgb import (
69 RGB_Colourspace,
70 linear_function,
71 log_decoding_ACEScc,
72 log_decoding_ACEScct,
73 log_decoding_ACESproxy,
74 log_encoding_ACEScc,
75 log_encoding_ACEScct,
76 log_encoding_ACESproxy,
77 normalised_primary_matrix,
78)
80__author__ = "Colour Developers"
81__copyright__ = "Copyright 2013 Colour Developers"
82__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
83__maintainer__ = "Colour Developers"
84__email__ = "colour-developers@colour-science.org"
85__status__ = "Production"
87__all__ = [
88 "AP0",
89 "AP1",
90 "WHITEPOINT_NAME_ACES",
91 "CCS_WHITEPOINT_ACES",
92 "MATRIX_AP0_TO_XYZ",
93 "MATRIX_XYZ_TO_AP0",
94 "MATRIX_AP1_TO_XYZ",
95 "MATRIX_XYZ_TO_AP1",
96 "RGB_COLOURSPACE_ACES2065_1",
97 "RGB_COLOURSPACE_ACESCG",
98 "RGB_COLOURSPACE_ACESCC",
99 "RGB_COLOURSPACE_ACESCCT",
100 "RGB_COLOURSPACE_ACESPROXY",
101]
103AP0: NDArrayFloat = np.array(
104 [
105 [0.73470, 0.26530],
106 [0.00000, 1.00000],
107 [0.00010, -0.07700],
108 ]
109)
110"""*ACES Primaries 0* or *AP0* primaries."""
112AP1: NDArrayFloat = np.array(
113 [
114 [0.71300, 0.29300],
115 [0.16500, 0.83000],
116 [0.12800, 0.04400],
117 ]
118)
119"""
120*ACES Primaries 1* or *AP1* primaries (known as *ITU-R BT.2020+* primaries
121prior to *ACES* 1.0 release).
122"""
124WHITEPOINT_NAME_ACES: str = "ACES"
125"""*ACES2065-1* colourspace whitepoint name."""
127CCS_WHITEPOINT_ACES: NDArrayFloat = CCS_ILLUMINANTS[
128 "CIE 1931 2 Degree Standard Observer"
129][WHITEPOINT_NAME_ACES]
130"""*ACES2065-1* colourspace whitepoint chromaticity coordinates."""
132MATRIX_AP0_TO_XYZ: NDArrayFloat = np.array(
133 [
134 [0.9525523959, 0.0000000000, 0.0000936786],
135 [0.3439664498, 0.7281660966, -0.0721325464],
136 [0.0000000000, 0.0000000000, 1.0088251844],
137 ]
138)
139"""*ACES Primaries 0* to *CIE XYZ* tristimulus values matrix defined as per [2]."""
141MATRIX_XYZ_TO_AP0: NDArrayFloat = np.array(
142 [
143 [1.0498110175, 0.0000000000, -0.0000974845],
144 [-0.4959030231, 1.3733130458, 0.0982400361],
145 [0.0000000000, 0.0000000000, 0.9912520182],
146 ]
147)
148"""*CIE XYZ* tristimulus values to *ACES Primaries 0* matrix."""
150MATRIX_AP1_TO_XYZ: NDArrayFloat = normalised_primary_matrix(AP1, CCS_WHITEPOINT_ACES)
151"""*ACES Primaries 1* to *CIE XYZ* tristimulus values matrix."""
153MATRIX_XYZ_TO_AP1: NDArrayFloat = np.linalg.inv(MATRIX_AP1_TO_XYZ)
154"""*CIE XYZ* tristimulus values to *ACES Primaries 1* matrix."""
156RGB_COLOURSPACE_ACES2065_1: RGB_Colourspace = RGB_Colourspace(
157 "ACES2065-1",
158 AP0,
159 CCS_WHITEPOINT_ACES,
160 WHITEPOINT_NAME_ACES,
161 MATRIX_AP0_TO_XYZ,
162 MATRIX_XYZ_TO_AP0,
163 linear_function,
164 linear_function,
165)
166RGB_COLOURSPACE_ACES2065_1.__doc__ = """
167*ACES2065-1* colourspace, base encoding, used for exchange of full fidelity
168images and archiving.
170The *ACES2065-1* colourspace encoding has a very wide gamut that allows all
171colours to be represented with only positive values. It is the reference space
172of the *Academy Color Encoding System* (ACES). It is thoroughly documented in
173*SMPTE standard ST 2065-1*. It is a bit too wide a gamut to use as a rendering
174space, but it is an excellent space for storing textures in *OpenEXR* files, as
175documented in SMPTE ST 2065-4.
177References
178----------
179:cite:`ASWFColorInteropForum2024`
180:cite:`TheAcademyofMotionPictureArtsandSciences2014q`,
181:cite:`TheAcademyofMotionPictureArtsandSciences2014r`,
182:cite:`TheAcademyofMotionPictureArtsandSciencese`
183"""
185RGB_COLOURSPACE_ACESCG: RGB_Colourspace = RGB_Colourspace(
186 "ACEScg",
187 AP1,
188 CCS_WHITEPOINT_ACES,
189 WHITEPOINT_NAME_ACES,
190 MATRIX_AP1_TO_XYZ,
191 MATRIX_XYZ_TO_AP1,
192 linear_function,
193 linear_function,
194)
195RGB_COLOURSPACE_ACESCG.__doc__ = """
196*ACEScg* colourspace, a working space for paint/compositor applications that
197don't support ACES2065-1 or ACEScc.
199The ACEScg colourspace encoding has a wide gamut that has been shown to work
200well as the computational space for computer graphics rendering. It is thoroughly
201documented on the ACES website.
203References
204----------
205:cite:`ASWFColorInteropForum2024`
206:cite:`TheAcademyofMotionPictureArtsandSciences2014q`,
207:cite:`TheAcademyofMotionPictureArtsandSciences2014r`,
208:cite:`TheAcademyofMotionPictureArtsandSciences2015b`,
209:cite:`TheAcademyofMotionPictureArtsandSciencese`
210"""
212RGB_COLOURSPACE_ACESCC: RGB_Colourspace = RGB_Colourspace(
213 "ACEScc",
214 AP1,
215 CCS_WHITEPOINT_ACES,
216 WHITEPOINT_NAME_ACES,
217 MATRIX_AP1_TO_XYZ,
218 MATRIX_XYZ_TO_AP1,
219 log_encoding_ACEScc,
220 log_decoding_ACEScc,
221)
222RGB_COLOURSPACE_ACESCC.__doc__ = """
223*ACEScc* colourspace, a working space for color correctors, target for ASC-CDL
224values created on-set.
226References
227----------
228:cite:`TheAcademyofMotionPictureArtsandSciences2014q`,
229:cite:`TheAcademyofMotionPictureArtsandSciences2014r`,
230:cite:`TheAcademyofMotionPictureArtsandSciences2014t`,
231:cite:`TheAcademyofMotionPictureArtsandSciencese`
232"""
234RGB_COLOURSPACE_ACESCCT: RGB_Colourspace = RGB_Colourspace(
235 "ACEScct",
236 AP1,
237 CCS_WHITEPOINT_ACES,
238 WHITEPOINT_NAME_ACES,
239 MATRIX_AP1_TO_XYZ,
240 MATRIX_XYZ_TO_AP1,
241 log_encoding_ACEScct,
242 log_decoding_ACEScct,
243)
244RGB_COLOURSPACE_ACESCCT.__doc__ = """
245*ACEScct* colourspace, an alternative working space for colour correctors,
246intended to be transient and internal to software or hardware systems,
247and is specifically not intended for interchange or archiving.
249References
250----------
251:cite:`TheAcademyofMotionPictureArtsandSciences2014q`,
252:cite:`TheAcademyofMotionPictureArtsandSciences2014r`,
253:cite:`TheAcademyofMotionPictureArtsandSciences2016c`,
254:cite:`TheAcademyofMotionPictureArtsandSciencese`
255"""
257RGB_COLOURSPACE_ACESPROXY: RGB_Colourspace = RGB_Colourspace(
258 "ACESproxy",
259 AP1,
260 CCS_WHITEPOINT_ACES,
261 WHITEPOINT_NAME_ACES,
262 MATRIX_AP1_TO_XYZ,
263 MATRIX_XYZ_TO_AP1,
264 log_encoding_ACESproxy,
265 log_decoding_ACESproxy,
266)
267RGB_COLOURSPACE_ACESPROXY.__doc__ = """
268*ACESproxy* colourspace, a lightweight encoding for transmission over HD-SDI
269(or other production transmission schemes), onset look management. Not
270intended to be stored or used in production imagery or for final colour
271grading / mastering.
273References
274----------
275:cite:`TheAcademyofMotionPictureArtsandSciences2014q`,
276:cite:`TheAcademyofMotionPictureArtsandSciences2014r`,
277:cite:`TheAcademyofMotionPictureArtsandSciences2014s`,
278:cite:`TheAcademyofMotionPictureArtsandSciencese`
279"""