Coverage for colour/hints/__init__.py: 100%
111 statements
« prev ^ index » next coverage.py v7.11.0, created at 2025-11-15 19:01 +1300
1"""
2Annotation Type Hints
3=====================
5Define the annotation type hints, the module exposes many aliases from
6:mod:`typing` and :mod:`numpy.typing` to avoid having to handle multiple
7imports.
8"""
10from __future__ import annotations
12import re
13import typing
14from collections.abc import Generator, Iterable, Iterator, Mapping, Sequence
15from os import PathLike
16from types import ModuleType
17from typing import ( # noqa: UP035
18 Annotated,
19 Any,
20 Callable,
21 ClassVar,
22 Dict,
23 List,
24 Literal,
25 NewType,
26 NoReturn,
27 Protocol,
28 Set,
29 SupportsIndex,
30 TextIO,
31 Tuple,
32 Type,
33 TypeAlias,
34 TypedDict,
35 TypeVar,
36 cast,
37 overload,
38 runtime_checkable,
39)
41import numpy as np
42from numpy.typing import ArrayLike, NDArray
43from typing_extensions import Self
45__author__ = "Colour Developers"
46__copyright__ = "Copyright 2013 Colour Developers"
47__license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"
48__maintainer__ = "Colour Developers"
49__email__ = "colour-developers@colour-science.org"
50__status__ = "Production"
52__all__ = [
53 "Annotated",
54 "ArrayLike",
55 "NDArray",
56 "ModuleType",
57 "Any",
58 "Callable",
59 "ClassVar",
60 "Dict",
61 "Generator",
62 "Iterable",
63 "Iterator",
64 "List",
65 "Literal",
66 "Mapping",
67 "NoReturn",
68 "NewType",
69 "Protocol",
70 "Sequence",
71 "PathLike",
72 "Set",
73 "SupportsIndex",
74 "TextIO",
75 "Tuple",
76 "Type",
77 "TypeVar",
78 "TypedDict",
79 "cast",
80 "overload",
81 "runtime_checkable",
82 "Self",
83 "RegexFlag",
84 "DTypeInt",
85 "DTypeFloat",
86 "DTypeReal",
87 "DTypeComplex",
88 "DTypeBoolean",
89 "DType",
90 "Real",
91 "Dataclass",
92 "NDArrayInt",
93 "NDArrayFloat",
94 "NDArrayReal",
95 "NDArrayComplex",
96 "NDArrayBoolean",
97 "NDArrayStr",
98 "Domain1",
99 "Domain10",
100 "Domain100",
101 "Domain360",
102 "Domain100_100_360",
103 "Range1",
104 "Range10",
105 "Range100",
106 "Range360",
107 "Range100_100_360",
108 "ProtocolInterpolator",
109 "ProtocolExtrapolator",
110 "ProtocolLUTSequenceItem",
111 "LiteralWarning",
112 "LiteralChromaticAdaptationTransform",
113 "LiteralColourspaceModel",
114 "LiteralRGBColourspace",
115 "LiteralLogEncoding",
116 "LiteralLogDecoding",
117 "LiteralOETF",
118 "LiteralOETFInverse",
119 "LiteralEOTF",
120 "LiteralEOTFInverse",
121 "LiteralCCTFEncoding",
122 "LiteralCCTFDecoding",
123 "LiteralOOTF",
124 "LiteralOOTFInverse",
125 "LiteralLUTReadMethod",
126 "LiteralLUTWriteMethod",
127 "LiteralFontScaling",
128]
130RegexFlag = NewType("RegexFlag", re.RegexFlag)
132DTypeInt: TypeAlias = (
133 np.int8
134 | np.int16
135 | np.int32
136 | np.int64
137 | np.uint8
138 | np.uint16
139 | np.uint32
140 | np.uint64
141)
142DTypeFloat: TypeAlias = np.float16 | np.float32 | np.float64
143DTypeReal: TypeAlias = DTypeInt | DTypeFloat
144DTypeComplex: TypeAlias = np.complex64 | np.complex128
145DTypeBoolean: TypeAlias = np.bool_
146DType: TypeAlias = DTypeBoolean | DTypeReal | DTypeComplex
148Real: TypeAlias = int | float
150# TODO: Revisit to use Protocol.
151Dataclass: TypeAlias = Any
153NDArrayInt: TypeAlias = NDArray[DTypeInt]
154NDArrayFloat: TypeAlias = NDArray[DTypeFloat]
155NDArrayReal: TypeAlias = NDArray[DTypeInt | DTypeFloat]
156NDArrayComplex: TypeAlias = NDArray[DTypeComplex]
157NDArrayBoolean: TypeAlias = NDArray[DTypeBoolean]
158NDArrayStr: TypeAlias = NDArray[np.str_]
160# Domain-Range Scale Type Aliases
161Domain1: TypeAlias = Annotated[ArrayLike, 1]
162Domain10: TypeAlias = Annotated[ArrayLike, 10]
163Domain100: TypeAlias = Annotated[ArrayLike, 100]
164Domain360: TypeAlias = Annotated[ArrayLike, 360]
165Domain100_100_360: TypeAlias = Annotated[ArrayLike, (100, 100, 360)]
167Range1: TypeAlias = Annotated[NDArrayFloat, 1]
168Range10: TypeAlias = Annotated[NDArrayFloat, 10]
169Range100: TypeAlias = Annotated[NDArrayFloat, 100]
170Range360: TypeAlias = Annotated[NDArrayFloat, 360]
171Range100_100_360: TypeAlias = Annotated[NDArrayFloat, (100, 100, 360)]
174class ProtocolInterpolator(Protocol): # noqa: D101 # pragma: no cover
175 @property
176 def x(self) -> NDArray: # noqa: D102
177 ...
179 @x.setter
180 def x(self, value: ArrayLike, /) -> None: ...
182 @property
183 def y(self) -> NDArray: # noqa: D102
184 ...
186 @y.setter
187 def y(self, value: ArrayLike, /) -> None: ...
189 def __init__(self, *args: Any, **kwargs: Any) -> None: ... # pragma: no cover
191 def __call__(self, x: NDArrayFloat) -> NDArray: # noqa: D102
192 ... # pragma: no cover
195class ProtocolExtrapolator(Protocol): # noqa: D101 # pragma: no cover
196 @property
197 def interpolator(self) -> ProtocolInterpolator: # noqa: D102
198 ...
200 @interpolator.setter
201 def interpolator(self, value: ProtocolInterpolator, /) -> None: ...
203 def __init__(self, *args: Any, **kwargs: Any) -> None: ... # pragma: no cover
205 def __call__(self, x: NDArrayFloat) -> NDArray: # noqa: D102
206 ... # pragma: no cover
209@runtime_checkable
210class ProtocolLUTSequenceItem(Protocol): # noqa: D101 # pragma: no cover
211 def apply(self, RGB: ArrayLike, **kwargs: Any) -> NDArray: # noqa: D102
212 ... # pragma: no cover
215LiteralWarning = Literal["default", "error", "ignore", "always", "module", "once"]
217# NOTE: The following literals are automatically generated by the *invoke*
218# *literalise* task. Please do not edit this section manually!
220# LITERALISE::BEGIN
221LiteralChromaticAdaptationTransform = Literal[
222 "Bianco 2010",
223 "Bianco PC 2010",
224 "Bradford",
225 "CAT02",
226 "CAT02 Brill 2008",
227 "CAT16",
228 "CMCCAT2000",
229 "CMCCAT97",
230 "Fairchild",
231 "Sharp",
232 "Von Kries",
233 "XYZ Scaling",
234]
236LiteralColourspaceModel = Literal[
237 "CAM02LCD",
238 "CAM02SCD",
239 "CAM02UCS",
240 "CAM16LCD",
241 "CAM16SCD",
242 "CAM16UCS",
243 "CIE 1931",
244 "CIE 1960 UCS",
245 "CIE 1976 UCS",
246 "CIE Lab",
247 "CIE Luv",
248 "CIE UCS",
249 "CIE UVW",
250 "CIE XYZ",
251 "CIE xyY",
252 "DIN99",
253 "HCL",
254 "HSL",
255 "HSV",
256 "Hunter Lab",
257 "Hunter Rdab",
258 "ICaCb",
259 "ICtCp",
260 "IHLS",
261 "IPT",
262 "IPT Ragoo 2021",
263 "IgPgTg",
264 "Jzazbz",
265 "OSA UCS",
266 "Oklab",
267 "RGB",
268 "YCbCr",
269 "YCoCg",
270 "Yrg",
271 "hdr-CIELAB",
272 "hdr-IPT",
273]
275LiteralRGBColourspace = Literal[
276 "ACES2065-1",
277 "ACEScc",
278 "ACEScct",
279 "ACEScg",
280 "ACESproxy",
281 "ARRI Wide Gamut 3",
282 "ARRI Wide Gamut 4",
283 "Adobe RGB (1998)",
284 "Adobe Wide Gamut RGB",
285 "Apple RGB",
286 "Best RGB",
287 "Beta RGB",
288 "Blackmagic Wide Gamut",
289 "CIE RGB",
290 "Cinema Gamut",
291 "ColorMatch RGB",
292 "DCDM XYZ",
293 "DCI-P3",
294 "DCI-P3-P",
295 "DJI D-Gamut",
296 "DRAGONcolor",
297 "DRAGONcolor2",
298 "DaVinci Wide Gamut",
299 "Display P3",
300 "Don RGB 4",
301 "EBU Tech. 3213-E",
302 "ECI RGB v2",
303 "ERIMM RGB",
304 "Ekta Space PS 5",
305 "F-Gamut",
306 "FilmLight E-Gamut",
307 "ITU-R BT.2020",
308 "ITU-R BT.470 - 525",
309 "ITU-R BT.470 - 625",
310 "ITU-R BT.709",
311 "ITU-T H.273 - 22 Unspecified",
312 "ITU-T H.273 - Generic Film",
313 "Max RGB",
314 "N-Gamut",
315 "NTSC (1953)",
316 "NTSC (1987)",
317 "P3-D65",
318 "PLASA ANSI E1.54",
319 "Pal/Secam",
320 "ProPhoto RGB",
321 "Protune Native",
322 "REDWideGamutRGB",
323 "REDcolor",
324 "REDcolor2",
325 "REDcolor3",
326 "REDcolor4",
327 "RIMM RGB",
328 "ROMM RGB",
329 "Russell RGB",
330 "S-Gamut",
331 "S-Gamut3",
332 "S-Gamut3.Cine",
333 "SMPTE 240M",
334 "SMPTE C",
335 "Sharp RGB",
336 "V-Gamut",
337 "Venice S-Gamut3",
338 "Venice S-Gamut3.Cine",
339 "Xtreme RGB",
340 "aces",
341 "adobe1998",
342 "prophoto",
343 "sRGB",
344]
346LiteralLogEncoding = Literal[
347 "ACEScc",
348 "ACEScct",
349 "ACESproxy",
350 "ARRI LogC3",
351 "ARRI LogC4",
352 "Apple Log Profile",
353 "Canon Log",
354 "Canon Log 2",
355 "Canon Log 3",
356 "Cineon",
357 "D-Log",
358 "ERIMM RGB",
359 "F-Log",
360 "F-Log2",
361 "Filmic Pro 6",
362 "L-Log",
363 "Log2",
364 "Log3G10",
365 "Log3G12",
366 "Mi-Log",
367 "N-Log",
368 "PLog",
369 "Panalog",
370 "Protune",
371 "REDLog",
372 "REDLogFilm",
373 "S-Log",
374 "S-Log2",
375 "S-Log3",
376 "T-Log",
377 "V-Log",
378 "ViperLog",
379]
381LiteralLogDecoding = Literal[
382 "ACEScc",
383 "ACEScct",
384 "ACESproxy",
385 "ARRI LogC3",
386 "ARRI LogC4",
387 "Apple Log Profile",
388 "Canon Log",
389 "Canon Log 2",
390 "Canon Log 3",
391 "Cineon",
392 "D-Log",
393 "ERIMM RGB",
394 "F-Log",
395 "F-Log2",
396 "Filmic Pro 6",
397 "L-Log",
398 "Log2",
399 "Log3G10",
400 "Log3G12",
401 "Mi-Log",
402 "N-Log",
403 "PLog",
404 "Panalog",
405 "Protune",
406 "REDLog",
407 "REDLogFilm",
408 "S-Log",
409 "S-Log2",
410 "S-Log3",
411 "T-Log",
412 "V-Log",
413 "ViperLog",
414]
416LiteralOETF = Literal[
417 "ARIB STD-B67",
418 "Blackmagic Film Generation 5",
419 "DaVinci Intermediate",
420 "ITU-R BT.2020",
421 "ITU-R BT.2100 HLG",
422 "ITU-R BT.2100 PQ",
423 "ITU-R BT.601",
424 "ITU-R BT.709",
425 "ITU-T H.273 IEC 61966-2",
426 "ITU-T H.273 Log",
427 "ITU-T H.273 Log Sqrt",
428 "SMPTE 240M",
429]
431LiteralOETFInverse = Literal[
432 "ARIB STD-B67",
433 "Blackmagic Film Generation 5",
434 "DaVinci Intermediate",
435 "ITU-R BT.2020",
436 "ITU-R BT.2100 HLG",
437 "ITU-R BT.2100 PQ",
438 "ITU-R BT.601",
439 "ITU-R BT.709",
440 "ITU-T H.273 IEC 61966-2",
441 "ITU-T H.273 Log",
442 "ITU-T H.273 Log Sqrt",
443]
445LiteralEOTF = Literal[
446 "DCDM",
447 "DICOM GSDF",
448 "ITU-R BT.1886",
449 "ITU-R BT.2100 HLG",
450 "ITU-R BT.2100 PQ",
451 "ITU-T H.273 ST.428-1",
452 "SMPTE 240M",
453 "ST 2084",
454 "sRGB",
455]
457LiteralEOTFInverse = Literal[
458 "DCDM",
459 "DICOM GSDF",
460 "ITU-R BT.1886",
461 "ITU-R BT.2100 HLG",
462 "ITU-R BT.2100 PQ",
463 "ITU-T H.273 ST.428-1",
464 "ST 2084",
465 "sRGB",
466]
468LiteralCCTFEncoding = Literal[
469 "ACEScc",
470 "ACEScct",
471 "ACESproxy",
472 "ARIB STD-B67",
473 "ARRI LogC3",
474 "ARRI LogC4",
475 "Apple Log Profile",
476 "Blackmagic Film Generation 5",
477 "Canon Log",
478 "Canon Log 2",
479 "Canon Log 3",
480 "Cineon",
481 "D-Log",
482 "DCDM",
483 "DICOM GSDF",
484 "DaVinci Intermediate",
485 "ERIMM RGB",
486 "F-Log",
487 "F-Log2",
488 "Filmic Pro 6",
489 "Gamma 2.2",
490 "Gamma 2.4",
491 "Gamma 2.6",
492 "ITU-R BT.1886",
493 "ITU-R BT.2020",
494 "ITU-R BT.2100 HLG",
495 "ITU-R BT.2100 PQ",
496 "ITU-R BT.601",
497 "ITU-R BT.709",
498 "ITU-T H.273 IEC 61966-2",
499 "ITU-T H.273 Log",
500 "ITU-T H.273 Log Sqrt",
501 "ITU-T H.273 ST.428-1",
502 "L-Log",
503 "Log2",
504 "Log3G10",
505 "Log3G12",
506 "Mi-Log",
507 "N-Log",
508 "PLog",
509 "Panalog",
510 "ProPhoto RGB",
511 "Protune",
512 "REDLog",
513 "REDLogFilm",
514 "RIMM RGB",
515 "ROMM RGB",
516 "S-Log",
517 "S-Log2",
518 "S-Log3",
519 "SMPTE 240M",
520 "ST 2084",
521 "T-Log",
522 "V-Log",
523 "ViperLog",
524 "sRGB",
525]
527LiteralCCTFDecoding = Literal[
528 "ACEScc",
529 "ACEScct",
530 "ACESproxy",
531 "ARIB STD-B67",
532 "ARRI LogC3",
533 "ARRI LogC4",
534 "Apple Log Profile",
535 "Blackmagic Film Generation 5",
536 "Canon Log",
537 "Canon Log 2",
538 "Canon Log 3",
539 "Cineon",
540 "D-Log",
541 "DCDM",
542 "DICOM GSDF",
543 "DaVinci Intermediate",
544 "ERIMM RGB",
545 "F-Log",
546 "F-Log2",
547 "Filmic Pro 6",
548 "Gamma 2.2",
549 "Gamma 2.4",
550 "Gamma 2.6",
551 "ITU-R BT.1886",
552 "ITU-R BT.2020",
553 "ITU-R BT.2100 HLG",
554 "ITU-R BT.2100 PQ",
555 "ITU-R BT.601",
556 "ITU-R BT.709",
557 "ITU-T H.273 IEC 61966-2",
558 "ITU-T H.273 Log",
559 "ITU-T H.273 Log Sqrt",
560 "ITU-T H.273 ST.428-1",
561 "L-Log",
562 "Log2",
563 "Log3G10",
564 "Log3G12",
565 "Mi-Log",
566 "N-Log",
567 "PLog",
568 "Panalog",
569 "ProPhoto RGB",
570 "Protune",
571 "REDLog",
572 "REDLogFilm",
573 "RIMM RGB",
574 "ROMM RGB",
575 "S-Log",
576 "S-Log2",
577 "S-Log3",
578 "SMPTE 240M",
579 "ST 2084",
580 "T-Log",
581 "V-Log",
582 "ViperLog",
583 "sRGB",
584]
586LiteralOOTF = Literal["ITU-R BT.2100 HLG", "ITU-R BT.2100 PQ"]
588LiteralOOTFInverse = Literal["ITU-R BT.2100 HLG", "ITU-R BT.2100 PQ"]
590LiteralLUTReadMethod = Literal[
591 "Cinespace",
592 "Iridas Cube",
593 "Resolve Cube",
594 "Sony SPI1D",
595 "Sony SPI3D",
596 "Sony SPImtx",
597]
599LiteralLUTWriteMethod = Literal[
600 "Cinespace",
601 "Iridas Cube",
602 "Resolve Cube",
603 "Sony SPI1D",
604 "Sony SPI3D",
605 "Sony SPImtx",
606]
608LiteralDeltaEMethod = Literal[
609 "CAM02-LCD",
610 "CAM02-SCD",
611 "CAM02-UCS",
612 "CAM16-LCD",
613 "CAM16-SCD",
614 "CAM16-UCS",
615 "CIE 1976",
616 "CIE 1994",
617 "CIE 2000",
618 "CMC",
619 "DIN99",
620 "HyAB",
621 "HyCH",
622 "ITP",
623 "cie1976",
624 "cie1994",
625 "cie2000",
626]
628LiteralFontScaling = Literal[
629 "xx-small",
630 "x-small",
631 "small",
632 "medium",
633 "large",
634 "x-large",
635 "xx-large",
636 "larger",
637 "smaller",
638 "xx-small-colour-science",
639 "x-small-colour-science",
640 "small-colour-science",
641 "medium-colour-science",
642 "large-colour-science",
643 "x-large-colour-science",
644 "xx-large-colour-science",
645]
646# LITERALISE::END
649def arraylike(a: ArrayLike) -> NDArray: ...
652def number_or_arraylike(a: ArrayLike) -> NDArray: ...
655a: DTypeFloat = np.float64(1)
656b: float = 1
657c: float = 1
658d: ArrayLike = [c, c]
659e: ArrayLike = d
660s_a: Sequence[DTypeFloat] = [a, a]
661s_b: Sequence[float] = [b, b]
662s_c: Sequence[float] = [c, c]
664arraylike(a)
665arraylike(b)
666arraylike(c)
667arraylike(d)
668arraylike([d, d])
669arraylike(e)
670arraylike([e, e])
671arraylike(s_a)
672arraylike(s_b)
673arraylike(s_c)
675number_or_arraylike(a)
676number_or_arraylike(b)
677number_or_arraylike(c)
678number_or_arraylike(d)
679number_or_arraylike([d, d])
680number_or_arraylike(e)
681number_or_arraylike([e, e])
682number_or_arraylike(s_a)
683number_or_arraylike(s_b)
684number_or_arraylike(s_c)
686np.atleast_1d(a)
687np.atleast_1d(b)
688np.atleast_1d(c)
689np.atleast_1d(arraylike(d))
690np.atleast_1d(arraylike([d, d]))
691np.atleast_1d(arraylike(e))
692np.atleast_1d(arraylike([e, e]))
693np.atleast_1d(s_a)
694np.atleast_1d(s_b)
695np.atleast_1d(s_c)
697del a, b, c, d, e, s_a, s_b, s_c
699# ----------------------------------------------------------------------------#
700# --- API Changes and Deprecation Management ---#
701# ----------------------------------------------------------------------------#
702if not typing.TYPE_CHECKING:
703 DTypeFloating = DTypeFloat
704 DTypeInteger = DTypeInt
705 DTypeNumber = DTypeReal
706 Boolean = bool
707 Floating = float
708 Integer = int
709 Number = Real
710 FloatingOrArrayLike = ArrayLike
711 FloatingOrNDArray = NDArrayFloat