Coverage for models/rgb/itut_h_273.py: 19%

1"""

2 Recommendation ITU-T H.273 Code points for Video Signal Type Identification

3===========================================================================

4

5 Define standard video signal colour primaries, transfer functions, and matrix

6 coefficients used in deriving luma and chroma signals along with related

7 definitions:

8

9- :attr:`colour.COLOUR_PRIMARIES_ITUTH273`

10- :attr:`colour.TRANSFER_CHARACTERISTICS_ITUTH273`

11- :attr:`colour.MATRIX_COEFFICIENTS_ITUTH273`

12- :attr:`colour.models.describe_video_signal_colour_primaries`

13- :attr:`colour.models.describe_video_signal_transfer_characteristics`

14- :attr:`colour.models.describe_video_signal_matrix_coefficients`

15

16 These values were historically defined in

17:cite:`InternationalOrganizationforStandardization2013` then superseded and

18 duplicated by other standards such as

19:cite:`InternationalOrganizationforStandardization2020`,

20:cite:`InternationalOrganizationforStandardization2021` and

21:cite:`InternationalTelecommunicationUnion2021`. They are widely used to

22 define colour-related properties in video encoding and decoding software

23 libraries, including *FFmpeg*.

24

25 References

26----------

27- :cite:`EuropeanBroadcastingUnion1975` : European Broadcasting Union.

28 (1975). EBU Tech 3213 - EBU Standard for Chromaticity Tolerances for Studio

29 Monitors. https://tech.ebu.ch/docs/tech/tech3213.pdf

30- :cite:`FFmpegDevelopers2022` : FFmpeg Developers. (2022).

31 FFmpeg::AVColorPrimaries. https://github.com/FFmpeg/FFmpeg/\

32 blob/c469c3c3b18fbacd6ee0165573034d2a0408b83f/libavutil/pixfmt.h#L478

33- :cite:`FFmpegDevelopers2022a` : FFmpeg Developers. (2022).

34 FFmpeg::AVColorTransferCharacteristic. https://github.com/FFmpeg/FFmpeg/\

35 blob/c469c3c3b18fbacd6ee0165573034d2a0408b83f/libavutil/pixfmt.h#L503

36- :cite:`FFmpegDevelopers2022b` : FFmpeg Developers. (2022).

37 FFmpeg::AVColorSpace. https://github.com/FFmpeg/FFmpeg/\

38 blob/c469c3c3b18fbacd6ee0165573034d2a0408b83f/libavutil/pixfmt.h#L532

39- :cite:`InternationalOrganizationforStandardization2013` : International

40 Organization for Standardization. (2013). INTERNATIONAL STANDARD ISO/IEC

41 23001-8 - Information technology - MPEG systems technologies - Part 8:

42 Coding-independent code points.

43- :cite:`InternationalOrganizationforStandardization2020` : International

44 Organization for Standardization. (2020). INTERNATIONAL STANDARD ISO/IEC

45 14496-10 - Information technology - Coding of audio-visual objects - Part

46 10: Advanced video coding.

47- :cite:`InternationalOrganizationforStandardization2021` : International

48 Organization for Standardization. (2021). INTERNATIONAL STANDARD ISO/IEC

49 23091-2 - Information technology - Coding- independent code points -

50 Part 2: Video.

51- :cite:`InternationalTelecommunicationUnion2021` : International

52 Telecommunication Union. (2021). Recommendation ITU-T H.273 -

53 Coding-independent code points for video signal type identification.

54 https://www.itu.int/rec/T-REC-H.273-202107-I/en

55"""

56

57 from __future__ import annotations

58

59 import functools

60 import typing

61 from dataclasses import dataclass

62 from enum import IntEnum, auto

63

64 import numpy as np

65

66 if typing.TYPE_CHECKING:

67 from colour.hints import Any, ArrayLike, Callable, Dict, NDArrayFloat, NoReturn

68

69 from colour.models.rgb.datasets.dcdm_xyz import (

70 CCS_WHITEPOINT_DCDM_XYZ,

71 MATRIX_DCDM_XYZ_TO_XYZ,

72 MATRIX_XYZ_TO_DCDM_XYZ,

73 PRIMARIES_DCDM_XYZ,

74 WHITEPOINT_NAME_DCDM_XYZ,

75)

76 from colour.models.rgb.datasets.dci_p3 import (

77 CCS_WHITEPOINT_DCI_P3,

78 MATRIX_DCI_P3_TO_XYZ,

79 MATRIX_XYZ_TO_DCI_P3,

80 PRIMARIES_DCI_P3,

81 WHITEPOINT_NAME_DCI_P3,

82)

83 from colour.models.rgb.datasets.itur_bt_470 import (

84 CCS_WHITEPOINT_BT470_525,

85 CCS_WHITEPOINT_BT470_625,

86 MATRIX_BT470_525_TO_XYZ,

87 MATRIX_BT470_625_TO_XYZ,

88 MATRIX_XYZ_TO_BT470_525,

89 MATRIX_XYZ_TO_BT470_625,

90 PRIMARIES_BT470_525,

91 PRIMARIES_BT470_625,

92 WHITEPOINT_NAME_BT470_525,

93 WHITEPOINT_NAME_BT470_625,

94)

95 from colour.models.rgb.datasets.itur_bt_709 import (

96 CCS_WHITEPOINT_BT709,

97 MATRIX_BT709_TO_XYZ,

98 MATRIX_XYZ_TO_BT709,

99 PRIMARIES_BT709,

100 WHITEPOINT_NAME_BT709,

101)

102 from colour.models.rgb.datasets.itur_bt_2020 import (

103 CCS_WHITEPOINT_BT2020,

104 MATRIX_BT2020_TO_XYZ,

105 MATRIX_XYZ_TO_BT2020,

106 PRIMARIES_BT2020,

107 WHITEPOINT_NAME_BT2020,

108)

109 from colour.models.rgb.datasets.itut_h_273 import (

110 CCS_WHITEPOINT_H273_22_UNSPECIFIED,

111 CCS_WHITEPOINT_H273_GENERIC_FILM,

112 MATRIX_H273_22_UNSPECIFIED_RGB_TO_XYZ,

113 MATRIX_H273_GENERIC_FILM_RGB_TO_XYZ,

114 MATRIX_XYZ_TO_H273_22_UNSPECIFIED_RGB,

115 MATRIX_XYZ_TO_H273_GENERIC_FILM_RGB,

116 PRIMARIES_H273_22_UNSPECIFIED,

117 PRIMARIES_H273_GENERIC_FILM,

118 WHITEPOINT_NAME_H273_22_UNSPECIFIED,

119 WHITEPOINT_NAME_H273_GENERIC_FILM,

120)

121 from colour.models.rgb.datasets.p3_d65 import (

122 CCS_WHITEPOINT_P3_D65,

123 MATRIX_P3_D65_TO_XYZ,

124 MATRIX_XYZ_TO_P3_D65,

125 PRIMARIES_P3_D65,

126 WHITEPOINT_NAME_P3_D65,

127)

128 from colour.models.rgb.datasets.smpte_240m import (

129 CCS_WHITEPOINT_SMPTE_240M,

130 MATRIX_SMPTE_240M_TO_XYZ,

131 MATRIX_XYZ_TO_SMPTE_240M,

132 PRIMARIES_SMPTE_240M,

133 WHITEPOINT_NAME_SMPTE_240M,

134)

135 from colour.models.rgb.transfer_functions import (

136 eotf_inverse_H273_ST428_1,

137 eotf_inverse_ST2084,

138 gamma_function,

139 linear_function,

140 oetf_BT601,

141 oetf_BT709,

142 oetf_BT1361,

143 oetf_BT2020,

144 oetf_BT2100_HLG,

145 oetf_H273_IEC61966_2,

146 oetf_H273_Log,

147 oetf_H273_LogSqrt,

148 oetf_SMPTE240M,

149)

150 from colour.utilities import message_box, multiline_str

151 from colour.utilities.documentation import DocstringDict, is_documentation_building

152

153 __all__ = [

154 "COLOUR_PRIMARIES_ITUTH273",

155 "FFmpegConstantsColourPrimaries_ITUTH273",

156 "TRANSFER_CHARACTERISTICS_ITUTH273",

157 "FFmpegConstantsTransferCharacteristics_ITUTH273",

158 "MATRIX_COEFFICIENTS_ITUTH273",

159 "FFmpegConstantsMatrixCoefficients_ITUTH273",

160 "CCS_WHITEPOINTS_ITUTH273",

161 "WHITEPOINT_NAMES_ITUTH273",

162 "MATRICES_ITUTH273_RGB_TO_XYZ",

163 "MATRICES_XYZ_TO_ITUTH273_RGB",

164 "COLOUR_PRIMARIES_ISO23091_2",

165 "TRANSFER_CHARACTERISTICS_ISO23091_2",

166 "MATRIX_COEFFICIENTS_ISO23091_2",

167 "CCS_WHITEPOINTS_ISO23091_2",

168 "WHITEPOINT_NAMES_ISO23091_2",

169 "MATRICES_ISO23091_2_RGB_TO_XYZ",

170 "MATRICES_XYZ_TO_ISO23091_2_RGB",

171 "COLOUR_PRIMARIES_23001_8",

172 "TRANSFER_CHARACTERISTICS_23001_8",

173 "MATRIX_COEFFICIENTS_23001_8",

174 "CCS_WHITEPOINTS_23001_8",

175 "WHITEPOINT_NAMES_23001_8",

176 "MATRICES_23001_8_RGB_TO_XYZ",

177 "MATRICES_XYZ_TO_23001_8_RGB",

178 "COLOUR_PRIMARIES_ISO14496_10",

179 "TRANSFER_CHARACTERISTICS_ISO14496_10",

180 "MATRIX_COEFFICIENTS_ISO14496_10",

181 "CCS_WHITEPOINTS_ISO14496_10",

182 "WHITEPOINT_NAMES_ISO14496_10",

183 "MATRICES_ISO14496_10_RGB_TO_XYZ",

184 "MATRICES_XYZ_TO_ISO14496_10_RGB",

185 "describe_video_signal_colour_primaries",

186 "describe_video_signal_transfer_characteristics",

187 "describe_video_signal_matrix_coefficients",

188]

189

190

191 def _clipped_domain_function(

192 function: Callable, domain: list | tuple = (0, 1)

193) -> Callable:

194 """

195 Wrap specified function and produce a new callable clipping the input value

196 to the specified domain.

197

198 Parameters

199 ----------

200 function

201 Function to wrap.

202 domain

203 Domain to use for clipping.

204

205 Examples

206 --------

207 >>> linear_clipped = _clipped_domain_function(linear_function, (0.1, 0.9))

208 >>> linear_clipped(1) # doctest: +ELLIPSIS

209 0.9000000...

210 """

211

212 @functools.wraps(function)

213 def wrapped(x: ArrayLike, *args: Any, **kwargs: Any) -> Any:

214 """Wrap specified function."""

215

216 return function(np.clip(x, *domain), *args, **kwargs)

217

218 return wrapped

219

220

221 def _reserved(*args: Any) -> NoReturn: # noqa: ARG001

222 """

223 Indicate a reserved function by raising a runtime error.

224

225 Examples

226 --------

227 >>> try:

228 ... _reserved()

229 ... except RuntimeError:

230 ... pass

231 """

232

233 error = "Reserved; For future use by ITU-T | ISO/IEC."

234

235 raise RuntimeError(error)

236

237

238 def _unspecified(*args: Any) -> NoReturn: # noqa: ARG001

239 """

240 Indicate unspecified video signal characteristics by raising a runtime

241 error.

242

243 Raise a runtime error when called to signal that image characteristics

244 are unknown or determined by the application, as defined in ITU-T H.273

245 and related video signal type identification standards.

246

247 Examples

248 --------

249 >>> try:

250 ... _unspecified()

251 ... except RuntimeError:

252 ... pass

253 """

254

255 error = (

256 "Unspecified; Image characteristics are unknown or are determined by "

257 "the application."

258 )

259

260 raise RuntimeError(error)

261

262

263 COLOUR_PRIMARIES_ITUTH273: Dict[int, NDArrayFloat] = {

264 0: np.array("Reserved"),

265 # For future use by ITU-T | ISO/IEC.

266 #

267 1: PRIMARIES_BT709,

268 # Rec. ITU-R BT.709-6 Rec. ITU-R BT.1361-0 conventional colour gamut

269 # system and extended colour gamut system (historical) IEC 61966-2-1 sRGB

270 # or sYCC IEC 61966-2-4 Society of Motion Picture and Television Engineers

271 # (SMPTE) RP 177 (1993) Annex B.

272 #

273 2: np.array("Unspecified"),

274 # Image characteristics are unknown or are determined by the

275 # application.

276 #

277 3: np.array("Reserved"),

278 # For future use by ITU-T | ISO/IEC.

279 #

280 4: PRIMARIES_BT470_525,

281 # Rec. ITU-R BT.470-6 System M (historical) United States National

282 # Television System Committee 1953 Recommendation for transmission

283 # standards for color television United States Federal Communication

284 # Commission (2003) Title 47 Code of Federal Regulations 73.682 (a) (20).

285 #

286 5: PRIMARIES_BT470_625,

287 # 5: Rec. ITU-R BT.470-6 System B, G (historical) Rec. ITU-R BT.601-7 625

288 # Rec. ITU-R BT.1358-0 625 (historical) Rec. ITU-R BT.1700-0 625 PAL and

289 # 625 SECAM.

290 #

291 6: PRIMARIES_SMPTE_240M,

292 # 6: Rec. ITU-R BT.601-7 525 Rec. ITU-R BT.1358-1 525 or 625 (historical)

293 # Rec. ITU-R BT.1700-0 NTSC SMPTE ST 170 (2004) (functionally the same as

294 # the value 7).

295 #

296 7: PRIMARIES_SMPTE_240M,

297 # SMPTE ST 240 (1999) (functionally the same as the value 6).

298 #

299 8: PRIMARIES_H273_GENERIC_FILM,

300 # Generic film (colour filters using Illuminant C), Red: Wratten 25,

301 # Green: Wratten 58, Blue: Wratten 47.

302 #

303 9: PRIMARIES_BT2020,

304 # Rec. ITU-R BT.2020-2 Rec. ITU-R BT.2100-2.

305 #

306 10: PRIMARIES_DCDM_XYZ,

307 # SMPTE ST 428-1 (2019) (CIE 1931 XYZ as in ISO 11664-1).

308 #

309 11: PRIMARIES_DCI_P3,

310 # SMPTE RP 431-2 (2011).

311 #

312 12: PRIMARIES_P3_D65,

313 # SMPTE EG 432-1 (2010).

314 #

315 # 13-21:

316 # For future use by ITU-T | ISO/IEC.

317 #

318 22: PRIMARIES_H273_22_UNSPECIFIED,

319 # No corresponding industry specification identified.

320 #

321 23: np.array("Reserved"),

322 # 23-255:

323 # For future use by ITU-T | ISO/IEC.

324 #

325}

326 if is_documentation_building(): # pragma: no cover

327 COLOUR_PRIMARIES_ITUTH273 = DocstringDict(COLOUR_PRIMARIES_ITUTH273)

328 COLOUR_PRIMARIES_ITUTH273.__doc__ = """

329*ColourPrimaries* indicates the chromaticity coordinates of the source colour

330 primaries as specified in Table 3 of

331:cite:`InternationalOrganizationforStandardization2021` and

332:cite:`InternationalTelecommunicationUnion2021` in terms of the CIE 1931

333 definition of x and y, which shall be interpreted as specified by

334*ISO/ CIE 11664-1*.

335

336 References

337----------

338:cite:`InternationalOrganizationforStandardization2013`

339:cite:`InternationalOrganizationforStandardization2020`

340:cite:`InternationalOrganizationforStandardization2021`,

341:cite:`InternationalTelecommunicationUnion2021`

342"""

343

344

345 class FFmpegConstantsColourPrimaries_ITUTH273(IntEnum):

346 """

347 Define the constant names used by *FFmpeg* in the `AVColorPrimaries`

348 enum.

349

350 Notes

351 -----

352 - *AVCOL_PRI_JEDEC_P22* is equal to `AVCOL_PRI_EBU3213` in *FFmpeg*

353 but neither *Recommendation ITU-T H.273* (2021) nor

354 *ISO/IEC 23091-2* (2021) define the same primaries as

355 *EBU Tech 3213*, nor do they refer to it. *ColourPrimaries 22* in

356 both standards specifies the informative remark *No corresponding

357 industry specification identified*. However, *ISO/IEC 23001-8*

358 (2013) and *ISO/IEC 14497-10* (2020) specify the

359 *JEDEC P22 phosphors* and *EBU Tech. 3213-E (1975)* informative

360 remarks respectively while defining the same primaries and

361 whitepoint as the 2021 standards. This is likely an error in the

362 earlier standards that was discovered and corrected.

363

364 References

365 ----------

366 :cite:`FFmpegDevelopers2022`,

367 :cite:`InternationalOrganizationforStandardization2013`,

368 :cite:`InternationalOrganizationforStandardization2021`,

369 :cite:`InternationalOrganizationforStandardization2020`,

370 :cite:`InternationalTelecommunicationUnion2021`

371 """

372

373 AVCOL_PRI_RESERVED0 = 0

374 AVCOL_PRI_BT709 = 1

375 AVCOL_PRI_UNSPECIFIED = 2

376 AVCOL_PRI_RESERVED = 3

377 AVCOL_PRI_BT470M = 4

378 AVCOL_PRI_BT470BG = 5

379 AVCOL_PRI_SMPTE170M = 6

380 AVCOL_PRI_SMPTE240M = 7

381 AVCOL_PRI_FILM = 8

382 AVCOL_PRI_BT2020 = 9

383 AVCOL_PRI_SMPTE428 = 10

384 AVCOL_PRI_SMPTEST428_1 = AVCOL_PRI_SMPTE428

385 AVCOL_PRI_SMPTE431 = 11

386 AVCOL_PRI_SMPTE432 = 12

387 AVCOL_PRI_EBU3213 = 22

388 AVCOL_PRI_JEDEC_P22 = AVCOL_PRI_EBU3213

389 AVCOL_PRI_NB = auto()

390

391 RESERVED0 = AVCOL_PRI_RESERVED0

392 BT709 = AVCOL_PRI_BT709

393 UNSPECIFIED = AVCOL_PRI_UNSPECIFIED

394 RESERVED = AVCOL_PRI_RESERVED

395 BT470M = AVCOL_PRI_BT470M

396 BT470BG = AVCOL_PRI_BT470BG

397 SMPTE170M = AVCOL_PRI_SMPTE170M

398 SMPTE240M = AVCOL_PRI_SMPTE240M

399 FILM = AVCOL_PRI_FILM

400 BT2020 = AVCOL_PRI_BT2020

401 SMPTE428 = AVCOL_PRI_SMPTE428

402 SMPTEST428_1 = AVCOL_PRI_SMPTEST428_1

403 SMPTE431 = AVCOL_PRI_SMPTE431

404 SMPTE432 = AVCOL_PRI_SMPTE432

405 EBU3213 = AVCOL_PRI_EBU3213

406 JEDEC_P22 = AVCOL_PRI_JEDEC_P22

407 NB = AVCOL_PRI_NB

408

409

410 TRANSFER_CHARACTERISTICS_ITUTH273: Dict[int, Callable] = {

411 0: _reserved,

412 # For future use by ITU-T | ISO/IEC.

413 #

414 1: _clipped_domain_function(oetf_BT709),

415 # Rec. ITU-R BT.709-6 Rec. ITU-R BT.1361-0 conventional colour gamut

416 # system (historical) (functionally the same as the values 6, 14 and 15).

417 #

418 2: _unspecified,

419 # Image characteristics are unknown or are determined by the

420 # application.

421 #

422 3: _reserved,

423 # For future use by ITU-T | ISO/IEC.

424 #

425 4: _clipped_domain_function(functools.partial(gamma_function, exponent=1 / 2.2)),

426 # Assumed display gamma 2.2 Rec. ITU-R BT.470-6 System M (historical)

427 # United States National Television System Committee 1953 Recommendation

428 # for transmission standards for color television United States Federal

429 # Communications Commission (2003) Title 47 Code of Federal Regulations

430 # 73.682 (a) (20) Rec. ITU-R BT.1700-0 625 PAL and 625 SECAM.

431 #

432 5: _clipped_domain_function(functools.partial(gamma_function, exponent=1 / 2.8)),

433 # 5: Assumed display gamma 2.8 Rec. ITU-R BT.470-6 System B, G (historical).

434 #

435 6: _clipped_domain_function(oetf_BT601),

436 # Rec. ITU-R BT.601-7 525 or 625 Rec. ITU-R BT.1358-1 525 or 625

437 # (historical) Rec. ITU-R BT.1700-0 NTSC SMPTE ST 170 (2004) (functionally

438 # the same as the values 1, 14 and 15).

439 #

440 7: _clipped_domain_function(oetf_SMPTE240M),

441 # SMPTE ST 240 (1999).

442 #

443 8: _clipped_domain_function(linear_function),

444 # Linear transfer characteristics.

445 #

446 9: _clipped_domain_function(oetf_H273_Log),

447 # Logarithmic transfer characteristic (100:1 range).

448 #

449 10: _clipped_domain_function(oetf_H273_LogSqrt),

450 # Logarithmic transfer characteristic (100 * Sqrt( 10 ) : 1 range).

451 #

452 11: oetf_H273_IEC61966_2,

453 # IEC 61966-2-4.

454 #

455 12: _clipped_domain_function(oetf_BT1361, (-0.25, 1.33)),

456 # Rec. ITU-R BT.1361-0 extended colour gamut system (historical).

457 #

458 13: oetf_H273_IEC61966_2,

459 # IEC 61966-2-1 sRGB (with MatrixCoefficients equal to 0)

460 # IEC 61966-2-1 sYCC (with MatrixCoefficients equal to 5).

461 #

462 14: _clipped_domain_function(

463 functools.partial(oetf_BT2020, is_12_bits_system=False)

464 ),

465 # Rec. ITU-R BT.2020-2 (10-bit system) (functionally the same as the values

466 # 1, 6 and 15).

467 #

468 15: _clipped_domain_function(

469 functools.partial(oetf_BT2020, is_12_bits_system=True)

470 ),

471 # Rec. ITU-R BT.2020-2 (12-bit system) (functionally the same as the values

472 # 1, 6 and 14).

473 #

474 16: eotf_inverse_ST2084,

475 # SMPTE ST 2084 (2014) for 10-, 12-, 14- and 16-bit systems Rec.

476 # ITU-R BT.2100-2 perceptual quantization (PQ) system.

477 #

478 17: eotf_inverse_H273_ST428_1,

479 # SMPTE ST 428-1 (2019).

480 #

481 18: oetf_BT2100_HLG,

482 # ARIB STD-B67 (2015) Rec. ITU-R BT.2100-2 hybrid log-gamma (HLG) system.

483 #

484 19: _reserved,

485 # 19-255:

486 # For future use by ITU-T | ISO/IEC.

487 #

488}

489 if is_documentation_building(): # pragma: no cover

490 TRANSFER_CHARACTERISTICS_ITUTH273 = DocstringDict(TRANSFER_CHARACTERISTICS_ITUTH273)

491 TRANSFER_CHARACTERISTICS_ITUTH273.__doc__ = """

492*TransferCharacteristics*, as specified in Table 3 of

493:cite:`InternationalOrganizationforStandardization2021` and

494:cite:`InternationalTelecommunicationUnion2021`, either indicates the reference

495 opto-electronic transfer characteristic function of the source picture as a

496 function of a source input linear optical intensity input Lc with a nominal

497 real-valued range of 0 to 1 or indicates the inverse of the reference

498 electro-optical transfer characteristic function as a function of an output

499 linear optical intensity Lo with a nominal real-valued range of 0 to 1.

500

501 Notes

502-----

503- For simplicity, no clipping is implemented for *TransferCharacteristics 13*

504 as it is a function of whether the context is *sRGB* or *sYCC*.

505- For TransferCharacteristics equal to 18, the equations specified in Table 3 are

506 normalized for a source input linear optical intensity Lc with a nominal

507 real-valued range of 0 to 1. An alternative scaling that is mathematically

508 equivalent is used in ARIB STD-B67 (2015) with the source input linear

509 optical intensity having a nominal real-valued range of 0 to 12.

510

511 References

512----------

513:cite:`InternationalOrganizationforStandardization2013`

514:cite:`InternationalOrganizationforStandardization2020`

515:cite:`InternationalOrganizationforStandardization2021`,

516:cite:`InternationalTelecommunicationUnion2021`

517"""

518

519

520 class FFmpegConstantsTransferCharacteristics_ITUTH273(IntEnum):

521 """

522 Define the constant names used by *FFmpeg* in the

523 `AVColorTransferCharacteristic` enum for transfer characteristics as

524 specified in ITU-T H.273.

525

526 References

527 ----------

528 :cite:`FFmpegDevelopers2022a`,

529 :cite:`InternationalOrganizationforStandardization2013`,

530 :cite:`InternationalOrganizationforStandardization2021`,

531 :cite:`InternationalOrganizationforStandardization2020`,

532 :cite:`InternationalTelecommunicationUnion2021`

533 """

534

535 AVCOL_TRC_RESERVED0 = 0

536 AVCOL_TRC_BT709 = 1

537 AVCOL_TRC_UNSPECIFIED = 2

538 AVCOL_TRC_RESERVED = 3

539 AVCOL_TRC_GAMMA22 = 4

540 AVCOL_TRC_GAMMA28 = 5

541 AVCOL_TRC_SMPTE170M = 6

542 AVCOL_TRC_SMPTE240M = 7

543 AVCOL_TRC_LINEAR = 8

544 AVCOL_TRC_LOG = 9

545 AVCOL_TRC_LOG_SQRT = 10

546 AVCOL_TRC_IEC61966_2_4 = 11

547 AVCOL_TRC_BT1361_ECG = 12

548 AVCOL_TRC_IEC61966_2_1 = 13

549 AVCOL_TRC_BT2020_10 = 14

550 AVCOL_TRC_BT2020_12 = 15

551 AVCOL_TRC_SMPTE2084 = 16

552 AVCOL_TRC_SMPTEST2084 = AVCOL_TRC_SMPTE2084

553 AVCOL_TRC_SMPTE428 = 17

554 AVCOL_TRC_SMPTEST428_1 = AVCOL_TRC_SMPTE428

555 AVCOL_TRC_ARIB_STD_B67 = 18

556 AVCOL_TRC_NB = auto()

557

558 RESERVED0 = AVCOL_TRC_RESERVED0

559 BT709 = AVCOL_TRC_BT709

560 UNSPECIFIED = AVCOL_TRC_UNSPECIFIED

561 RESERVED = AVCOL_TRC_RESERVED

562 GAMMA22 = AVCOL_TRC_GAMMA22

563 GAMMA28 = AVCOL_TRC_GAMMA28

564 SMPTE170M = AVCOL_TRC_SMPTE170M

565 SMPTE240M = AVCOL_TRC_SMPTE240M

566 LINEAR = AVCOL_TRC_LINEAR

567 LOG = AVCOL_TRC_LOG

568 LOG_SQRT = AVCOL_TRC_LOG_SQRT

569 IEC61966_2_4 = AVCOL_TRC_IEC61966_2_4

570 BT1361_ECG = AVCOL_TRC_BT1361_ECG

571 IEC61966_2_1 = AVCOL_TRC_IEC61966_2_1

572 BT2020_10 = AVCOL_TRC_BT2020_10

573 BT2020_12 = AVCOL_TRC_BT2020_12

574 SMPTE2084 = AVCOL_TRC_SMPTE2084

575 SMPTEST2084 = AVCOL_TRC_SMPTEST2084

576 SMPTE428 = AVCOL_TRC_SMPTE428

577 SMPTEST428_1 = AVCOL_TRC_SMPTEST428_1

578 ARIB_STD_B67 = AVCOL_TRC_ARIB_STD_B67

579 NB = AVCOL_TRC_NB

580

581

582 MATRIX_COEFFICIENTS_ITUTH273: Dict[int, NDArrayFloat] = {

583 0: np.array("Identity"),

584 # The identity matrix. Typically used for GBR (often referred to as RGB);

585 # however, may also be used for YZX (often referred to as XYZ);

586 # IEC 61966-2-1 sRGB SMPTE ST 428-1 (2019) See equations 41 to 43.

587 #

588 1: np.array([0.2126, 0.0722]),

589 # Rec. ITU-R BT.709-6 Rec. ITU-R BT.1361-0 conventional colour gamut system

590 # and extended colour gamut system (historical) IEC 61966-2-4 xvYCC709

591 # SMPTE RP 177 (1993) Annex B See equations 38 to 40.

592 #

593 2: np.array("Unspecified"),

594 # Image characteristics are unknown or are determined by the application.

595 #

596 3: np.array("Reserved"),

597 # For future use by ITU-T | ISO/IEC.

598 #

599 4: np.array([0.30, 0.11]),

600 # United States Federal Communications Commission (2003) Title 47 Code of

601 # Federal Regulations 73.682 (a) (20) See equations 38 to 40.

602 #

603 5: np.array([0.299, 0.114]),

604 # Rec. ITU-R BT.470-6 System B, G (historical) Rec. ITU-R BT.601-7 625

605 # Rec. ITU-R BT.1358-0 625 (historical) Rec. ITU-R BT.1700-0 625 PAL and

606 # 625 SECAM IEC 61966-2-1 sYCC IEC 61966-2-4 xvYCC601 (functionally the

607 # same as the value 6) See equations 38 to 40.

608 #

609 6: np.array([0.299, 0.114]),

610 # Rec. ITU-R BT.601-7 525 Rec. ITU-R BT.1358-1 525 or 625 (historical)

611 # Rec. ITU-R BT.1700-0 NTSC SMPTE ST 170 (2004) (functionally the same as

612 # the value 5) See equations 38 to 40.

613 #

614 7: np.array([0.212, 0.087]),

615 # SMPTE ST 240 (1999) See equations 38 to 40.

616 #

617 8: np.array("YCgCo"),

618 # See equations 44 to 58.

619 #

620 9: np.array([0.2627, 0.0593]),

621 # Rec. ITU-R BT.2020-2 (non-constant luminance) Rec. ITU-R BT.2100-2

622 # Y'CbCr See equations 38 to 40.

623 #

624 10: np.array([0.2627, 0.0593]),

625 # Rec. ITU-R BT.2020-2 (constant luminance) See equations 59 to 68.

626 #

627 11: np.array("Y'D'ZD'X"),

628 # SMPTE ST 2085 (2015) See equations 69 to 71.

629 #

630 12: np.array("See equations 32 to 37"),

631 # Chromaticity-derived non-constant luminance system See equations 38 to 40.

632 #

633 13: np.array("See equations 32 to 37"),

634 # Chromaticity-derived constant luminance system See equations 59 to 68.

635 #

636 14: np.array("ICTCP"),

637 # Rec. ITU-R BT.2100-2 ICTCP See equations 72 to 74 for

638 # TransferCharacteristics value 16 (PQ) See equations 75 to 77 for

639 # TransferCharacteristics value 18 (HLG).

640 #

641 15: np.array("Reserved"),

642 # 15-255:

643 # For future use by ITU-T | ISO/IEC.

644 #

645}

646 if is_documentation_building(): # pragma: no cover

647 MATRIX_COEFFICIENTS_ITUTH273 = DocstringDict(MATRIX_COEFFICIENTS_ITUTH273)

648 MATRIX_COEFFICIENTS_ITUTH273.__doc__ = """

649*MatrixCoefficients* describes the matrix coefficients used in deriving luma

650 and chroma signals from the green, blue and red or X, Y and Z primaries, as

651 specified in Table 4 and equations 11 to 77 of

652:cite:`InternationalOrganizationforStandardization2021` and

653:cite:`InternationalTelecommunicationUnion2021`.

654

655 Notes

656-----

657- See :attr:`colour.WEIGHTS_YCBCR` attribute and the

658 :func:`colour.matrix_YCbCr`, :func:`colour.offset_YCbCr`,

659 :func:`colour.RGB_to_YCbCr`, :func:`colour.YCbCr_to_RGB`,

660 :func:`colour.RGB_to_YcCbcCrc`, :func:`colour.YcCbcCrc_to_RGB` definitions

661 for an implementation.

662

663 References

664----------

665:cite:`InternationalOrganizationforStandardization2013`

666:cite:`InternationalOrganizationforStandardization2020`

667:cite:`InternationalOrganizationforStandardization2021`,

668:cite:`InternationalTelecommunicationUnion2021`

669"""

670

671

672 class FFmpegConstantsMatrixCoefficients_ITUTH273(IntEnum):

673 """

674 Define the constant names used by *FFmpeg* in the `AVColorSpace` enum.

675

676 References

677 ----------

678 :cite:`FFmpegDevelopers2022b`,

679 :cite:`InternationalOrganizationforStandardization2013`,

680 :cite:`InternationalOrganizationforStandardization2021`,

681 :cite:`InternationalOrganizationforStandardization2020`,

682 :cite:`InternationalTelecommunicationUnion2021`

683 """

684

685 AVCOL_SPC_RGB = 0

686 AVCOL_SPC_BT709 = 1

687 AVCOL_SPC_UNSPECIFIED = 2

688 AVCOL_SPC_RESERVED = 3

689 AVCOL_SPC_FCC = 4

690 AVCOL_SPC_BT470BG = 5

691 AVCOL_SPC_SMPTE170M = 6

692 AVCOL_SPC_SMPTE240M = 7

693 AVCOL_SPC_YCGCO = 8

694 AVCOL_SPC_YCOCG = AVCOL_SPC_YCGCO

695 AVCOL_SPC_BT2020_NCL = 9

696 AVCOL_SPC_BT2020_CL = 10

697 AVCOL_SPC_SMPTE2085 = 11

698 AVCOL_SPC_CHROMA_DERIVED_NCL = 12

699 AVCOL_SPC_CHROMA_DERIVED_CL = 13

700 AVCOL_SPC_ICTCP = 14

701 AVCOL_SPC_NB = auto()

702

703 RGB = AVCOL_SPC_RGB

704 BT709 = AVCOL_SPC_BT709

705 UNSPECIFIED = AVCOL_SPC_UNSPECIFIED

706 RESERVED = AVCOL_SPC_RESERVED

707 FCC = AVCOL_SPC_FCC

708 BT470BG = AVCOL_SPC_BT470BG

709 SMPTE170M = AVCOL_SPC_SMPTE170M

710 SMPTE240M = AVCOL_SPC_SMPTE240M

711 YCGCO = AVCOL_SPC_YCGCO

712 YCOCG = AVCOL_SPC_YCOCG

713 BT2020_NCL = AVCOL_SPC_BT2020_NCL

714 BT2020_CL = AVCOL_SPC_BT2020_CL

715 SMPTE2085 = AVCOL_SPC_SMPTE2085

716 CHROMA_DERIVED_NCL = AVCOL_SPC_CHROMA_DERIVED_NCL

717 CHROMA_DERIVED_CL = AVCOL_SPC_CHROMA_DERIVED_CL

718 ICTCP = AVCOL_SPC_ICTCP

719 NB = AVCOL_SPC_NB

720

721

722 CCS_WHITEPOINTS_ITUTH273: Dict[int, NDArrayFloat] = {

723 0: np.array("Reserved"),

724 1: CCS_WHITEPOINT_BT709,

725 2: np.array("Unspecified"),

726 3: np.array("Reserved"),

727 4: np.around(CCS_WHITEPOINT_BT470_525, 3),

728 5: CCS_WHITEPOINT_BT470_625,

729 6: CCS_WHITEPOINT_SMPTE_240M,

730 7: CCS_WHITEPOINT_SMPTE_240M,

731 8: CCS_WHITEPOINT_H273_GENERIC_FILM,

732 9: CCS_WHITEPOINT_BT2020,

733 10: CCS_WHITEPOINT_DCDM_XYZ,

734 11: CCS_WHITEPOINT_DCI_P3,

735 12: CCS_WHITEPOINT_P3_D65,

736 22: CCS_WHITEPOINT_H273_22_UNSPECIFIED,

737 23: np.array("Reserved"),

738}

739 if is_documentation_building(): # pragma: no cover

740 CCS_WHITEPOINTS_ITUTH273 = DocstringDict(CCS_WHITEPOINTS_ITUTH273)

741 CCS_WHITEPOINTS_ITUTH273.__doc__ = """

742 Chromaticity coordinates of the whitepoints associated with the source colour

743 primaries as specified in Table 3 of

744:cite:`InternationalOrganizationforStandardization2021` and

745:cite:`InternationalTelecommunicationUnion2021` in terms of the CIE 1931

746 definition of x and y, which shall be interpreted as specified by

747*ISO/ CIE 11664-1*.

748

749 References

750----------

751:cite:`InternationalOrganizationforStandardization2013`

752:cite:`InternationalOrganizationforStandardization2020`

753:cite:`InternationalOrganizationforStandardization2021`,

754:cite:`InternationalTelecommunicationUnion2021`

755

756 Notes

757-----

758- :cite:`InternationalTelecommunicationUnion2021` defines

759 *CIE Illuminant C* as [0.310, 0.316], while *Colour* definition has a

760 slightly higher precision.

761"""

762

763

764 WHITEPOINT_NAMES_ITUTH273: Dict[int, str] = {

765 0: "Reserved",

766 1: WHITEPOINT_NAME_BT709,

767 2: "Unspecified",

768 3: "Reserved",

769 4: WHITEPOINT_NAME_BT470_525,

770 5: WHITEPOINT_NAME_BT470_625,

771 6: WHITEPOINT_NAME_SMPTE_240M,

772 7: WHITEPOINT_NAME_SMPTE_240M,

773 8: WHITEPOINT_NAME_H273_GENERIC_FILM,

774 9: WHITEPOINT_NAME_BT2020,

775 10: WHITEPOINT_NAME_DCDM_XYZ,

776 11: WHITEPOINT_NAME_DCI_P3,

777 12: WHITEPOINT_NAME_P3_D65,

778 22: WHITEPOINT_NAME_H273_22_UNSPECIFIED,

779 23: "Reserved",

780}

781 if is_documentation_building(): # pragma: no cover

782 WHITEPOINT_NAMES_ITUTH273 = DocstringDict(WHITEPOINT_NAMES_ITUTH273)

783 WHITEPOINT_NAMES_ITUTH273.__doc__ = """

784 Whitepoint names associated with the source colour primaries as specified in

785 Table 3 of :cite:`InternationalOrganizationforStandardization2021` and

786:cite:`InternationalTelecommunicationUnion2021`.

787

788 References

789----------

790:cite:`InternationalOrganizationforStandardization2013`

791:cite:`InternationalOrganizationforStandardization2020`

792:cite:`InternationalOrganizationforStandardization2021`,

793:cite:`InternationalTelecommunicationUnion2021`

794"""

795

796

797 MATRICES_ITUTH273_RGB_TO_XYZ = {

798 0: np.array("Reserved"),

799 1: MATRIX_BT709_TO_XYZ,

800 2: np.array("Unspecified"),

801 3: np.array("Reserved"),

802 4: MATRIX_BT470_525_TO_XYZ,

803 5: MATRIX_BT470_625_TO_XYZ,

804 6: MATRIX_SMPTE_240M_TO_XYZ,

805 7: MATRIX_SMPTE_240M_TO_XYZ,

806 8: MATRIX_H273_GENERIC_FILM_RGB_TO_XYZ,

807 9: MATRIX_BT2020_TO_XYZ,

808 10: MATRIX_DCDM_XYZ_TO_XYZ,

809 11: MATRIX_DCI_P3_TO_XYZ,

810 12: MATRIX_P3_D65_TO_XYZ,

811 22: MATRIX_H273_22_UNSPECIFIED_RGB_TO_XYZ,

812 23: np.array("Reserved"),

813}

814 if is_documentation_building(): # pragma: no cover

815 MATRICES_ITUTH273_RGB_TO_XYZ = DocstringDict(MATRICES_ITUTH273_RGB_TO_XYZ)

816 MATRICES_ITUTH273_RGB_TO_XYZ.__doc__ = """

817*RGB* to *CIE XYZ* tristimulus values matrices associated with the source

818 colour primaries as specified in Table 3 of

819:cite:`InternationalOrganizationforStandardization2021` and

820:cite:`InternationalTelecommunicationUnion2021`.

821

822 References

823----------

824:cite:`InternationalOrganizationforStandardization2013`

825:cite:`InternationalOrganizationforStandardization2020`

826:cite:`InternationalOrganizationforStandardization2021`,

827:cite:`InternationalTelecommunicationUnion2021`

828"""

829

830 MATRICES_XYZ_TO_ITUTH273_RGB = {

831 0: np.array("Reserved"),

832 1: MATRIX_XYZ_TO_BT709,

833 2: np.array("Unspecified"),

834 3: np.array("Reserved"),

835 4: MATRIX_XYZ_TO_BT470_525,

836 5: MATRIX_XYZ_TO_BT470_625,

837 6: MATRIX_XYZ_TO_SMPTE_240M,

838 7: MATRIX_XYZ_TO_SMPTE_240M,

839 8: MATRIX_XYZ_TO_H273_GENERIC_FILM_RGB,

840 9: MATRIX_XYZ_TO_BT2020,

841 10: MATRIX_XYZ_TO_DCDM_XYZ,

842 11: MATRIX_XYZ_TO_DCI_P3,

843 12: MATRIX_XYZ_TO_P3_D65,

844 22: MATRIX_XYZ_TO_H273_22_UNSPECIFIED_RGB,

845 23: np.array("Reserved"),

846}

847 if is_documentation_building(): # pragma: no cover

848 MATRICES_XYZ_TO_ITUTH273_RGB = DocstringDict(MATRICES_XYZ_TO_ITUTH273_RGB)

849 MATRICES_XYZ_TO_ITUTH273_RGB.__doc__ = """

850*CIE XYZ* tristimulus values to *RGB* matrices associated with the source

851 colour primaries as specified in Table 3 of

852:cite:`InternationalOrganizationforStandardization2021` and

853:cite:`InternationalTelecommunicationUnion2021`.

854

855 References

856----------

857:cite:`InternationalOrganizationforStandardization2013`

858:cite:`InternationalOrganizationforStandardization2020`

859:cite:`InternationalOrganizationforStandardization2021`,

860:cite:`InternationalTelecommunicationUnion2021`

861"""

862

863

864# Aliases for *ISO/IEC 23091-2* (2021).

865#

866# Verified to be functionally identical to *Recommendation ITU-T H.273* for

867# the values defined here.

868 COLOUR_PRIMARIES_ISO23091_2 = COLOUR_PRIMARIES_ITUTH273

869 TRANSFER_CHARACTERISTICS_ISO23091_2 = TRANSFER_CHARACTERISTICS_ITUTH273

870 MATRIX_COEFFICIENTS_ISO23091_2 = MATRIX_COEFFICIENTS_ITUTH273

871 CCS_WHITEPOINTS_ISO23091_2 = CCS_WHITEPOINTS_ITUTH273

872 WHITEPOINT_NAMES_ISO23091_2 = WHITEPOINT_NAMES_ITUTH273

873 MATRICES_ISO23091_2_RGB_TO_XYZ = MATRICES_ITUTH273_RGB_TO_XYZ

874 MATRICES_XYZ_TO_ISO23091_2_RGB = MATRICES_XYZ_TO_ITUTH273_RGB

875

876# Aliases for *ISO/IEC 23001-8* (2013).

877#

878# Verified to be functionally identical to *Recommendation ITU-T H.273* for

879# the values defined here except for the note regarding *EBU Tech 3213* and

880# *ColourPrimaries 22*.

881 COLOUR_PRIMARIES_23001_8 = COLOUR_PRIMARIES_ITUTH273

882 TRANSFER_CHARACTERISTICS_23001_8 = TRANSFER_CHARACTERISTICS_ITUTH273

883 MATRIX_COEFFICIENTS_23001_8 = MATRIX_COEFFICIENTS_ITUTH273

884 CCS_WHITEPOINTS_23001_8 = CCS_WHITEPOINTS_ITUTH273

885 WHITEPOINT_NAMES_23001_8 = WHITEPOINT_NAMES_ITUTH273

886 MATRICES_23001_8_RGB_TO_XYZ = MATRICES_ITUTH273_RGB_TO_XYZ

887 MATRICES_XYZ_TO_23001_8_RGB = MATRICES_XYZ_TO_ITUTH273_RGB

888

889# Aliases for *ISO/IEC 14496-10* (2020).

890#

891# Verified to be functionally identical to *Recommendation ITU-T H.273* for

892# the values defined here except for the note regarding *EBU Tech 3213* and

893# *ColourPrimaries 22*.

894 COLOUR_PRIMARIES_ISO14496_10 = COLOUR_PRIMARIES_ITUTH273

895 TRANSFER_CHARACTERISTICS_ISO14496_10 = TRANSFER_CHARACTERISTICS_ITUTH273

896 MATRIX_COEFFICIENTS_ISO14496_10 = MATRIX_COEFFICIENTS_ITUTH273

897 CCS_WHITEPOINTS_ISO14496_10 = CCS_WHITEPOINTS_ITUTH273

898 WHITEPOINT_NAMES_ISO14496_10 = WHITEPOINT_NAMES_ITUTH273

899 MATRICES_ISO14496_10_RGB_TO_XYZ = MATRICES_ITUTH273_RGB_TO_XYZ

900 MATRICES_XYZ_TO_ISO14496_10_RGB = MATRICES_XYZ_TO_ITUTH273_RGB

901

902

903 def describe_video_signal_colour_primaries(

904 code_point: int, print_description: bool = True, **kwargs: Any

905) -> str:

906 """

907 Describe the specified video signal colour primaries code point.

908

909 Parameters

910 ----------

911 code_point

912 Video signal colour primaries code point to describe from

913 :attr:`colour.COLOUR_PRIMARIES_ITUTH273` attribute.

914 print_description

915 Whether to print the description.

916

917 Other Parameters

918 ----------------

919 padding

920 {:func:`colour.utilities.message_box`},

921 Padding on each side of the message.

922 print_callable

923 {:func:`colour.utilities.message_box`},

924 Callable used to print the message box.

925 width

926 {:func:`colour.utilities.message_box`},

927 Message box width.

928

929 Returns

930 -------

931 str

932 Video signal colour primaries code point description.

933

934 References

935 ----------

936 :cite:`FFmpegDevelopers2022`,

937 :cite:`InternationalOrganizationforStandardization2013`,

938 :cite:`InternationalOrganizationforStandardization2021`,

939 :cite:`InternationalOrganizationforStandardization2020`,

940 :cite:`InternationalTelecommunicationUnion2021`

941

942 Examples

943 --------

944 >>> description = describe_video_signal_colour_primaries(1, width=75)

945 ===========================================================================

946 * *

947 * Colour Primaries: 1 *

948 * ------------------- *

949 * *

950 * Primaries : [[ 0.64 0.33] *

951 * [ 0.3 0.6 ] *

952 * [ 0.15 0.06]] *

953 * Whitepoint : [ 0.3127 0.329 ] *

954 * Whitepoint Name : D65 *

955 * NPM : [[ 0.4123908 0.35758434 0.18048079] *

956 * [ 0.21263901 0.71516868 0.07219232] *

957 * [ 0.01933082 0.11919478 0.95053215]] *

958 * NPM -1 : [[ 3.24096994 -1.53738318 -0.49861076] *

959 * [-0.96924364 1.8759675 0.04155506] *

960 * [ 0.05563008 -0.20397696 1.05697151]] *

961 * FFmpeg Constants : ['AVCOL_PRI_BT709', 'BT709'] *

962 * *

963 ===========================================================================

964 >>> description = describe_video_signal_colour_primaries(2, width=75)

965 ===========================================================================

966 * *

967 * Colour Primaries: 2 *

968 * ------------------- *

969 * *

970 * Primaries : Unspecified *

971 * Whitepoint : Unspecified *

972 * Whitepoint Name : Unspecified *

973 * NPM : Unspecified *

974 * NPM -1 : Unspecified *

975 * FFmpeg Constants : ['AVCOL_PRI_UNSPECIFIED', 'UNSPECIFIED'] *

976 * *

977 ===========================================================================

978 >>> description = describe_video_signal_colour_primaries(

979 ... FFmpegConstantsColourPrimaries_ITUTH273.JEDEC_P22, width=75

980 ... )

981 ===========================================================================

982 * *

983 * Colour Primaries: 22 *

984 * -------------------- *

985 * *

986 * Primaries : [[ 0.63 0.34 ] *

987 * [ 0.295 0.605] *

988 * [ 0.155 0.077]] *

989 * Whitepoint : [ 0.3127 0.329 ] *

990 * Whitepoint Name : D65 *

991 * NPM : [[ 0.42942013 0.3277917 0.1932441 ] *

992 * [ 0.23175055 0.67225077 0.09599868] *

993 * [ 0.02044858 0.11111583 0.95749334]] *

994 * NPM -1 : [[ 3.13288278 -1.44707454 -0.48720324] *

995 * [-1.08850877 2.01538781 0.01762239] *

996 * [ 0.05941301 -0.20297883 1.05275352]] *

997 * FFmpeg Constants : ['AVCOL_PRI_EBU3213', 'AVCOL_PRI_JEDEC_P22', *

998 * 'EBU3213', 'JEDEC_P22'] *

999 * *

1000 ===========================================================================

1001 """

1002

1003 @dataclass

1004 class SpecificationColourPrimaries:

1005 """Specification for video signal colour primaries code point."""

1006

1007 code_point: int

1008 primaries: NDArrayFloat

1009 whitepoint: NDArrayFloat

1010 whitepoint_name: str

1011 matrix_RGB_to_XYZ: NDArrayFloat

1012 matrix_XYZ_to_RGB: NDArrayFloat

1013 ffmpeg_constants: list

1014

1015 members = FFmpegConstantsColourPrimaries_ITUTH273.__members__.items()

1016 ffmpeg_constants = [

1017 name

1018 for name, member in members

1019 if member.name.startswith("AVCOL_PRI_") and member.value == code_point

1020 ]

1021

1022 description = SpecificationColourPrimaries(

1023 code_point,

1024 COLOUR_PRIMARIES_ITUTH273[code_point],

1025 CCS_WHITEPOINTS_ITUTH273[code_point],

1026 WHITEPOINT_NAMES_ITUTH273[code_point],

1027 MATRICES_ITUTH273_RGB_TO_XYZ[code_point],

1028 MATRICES_XYZ_TO_ITUTH273_RGB[code_point],

1029 ffmpeg_constants,

1030 )

1031

1032 message = multiline_str(

1033 description,

1034 [

1035 {

1036 "name": "code_point",

1037 "section": True,

1038 "formatter": lambda x: f"Colour Primaries: {x}",

1039 },

1040 {"line_break": True},

1041 {"name": "primaries", "label": "Primaries"},

1042 {"name": "whitepoint", "label": "Whitepoint"},

1043 {"name": "whitepoint_name", "label": "Whitepoint Name"},

1044 {"name": "matrix_RGB_to_XYZ", "label": "NPM"},

1045 {"name": "matrix_XYZ_to_RGB", "label": "NPM -1"},

1046 {"name": "ffmpeg_constants", "label": "FFmpeg Constants"},

1047 ],

1048 )

1049

1050 if print_description:

1051 message_box(

1052 message,

1053 **kwargs,

1054 )

1055

1056 return message

1057

1058

1059 def describe_video_signal_transfer_characteristics(

1060 code_point: int, print_description: bool = True, **kwargs: Any

1061) -> str:

1062 """

1063 Describe the specified video signal transfer characteristics code point.

1064

1065 Parameters

1066 ----------

1067 code_point

1068 Video signal transfer characteristics code point to describe from

1069 :attr:`colour.TRANSFER_CHARACTERISTICS_ITUTH273` attribute.

1070 print_description

1071 Whether to print the description.

1072

1073 Other Parameters

1074 ----------------

1075 padding

1076 {:func:`colour.utilities.message_box`},

1077 Padding on each side of the message.

1078 print_callable

1079 {:func:`colour.utilities.message_box`},

1080 Callable used to print the message box.

1081 width

1082 {:func:`colour.utilities.message_box`},

1083 Message box width.

1084

1085 Returns

1086 -------

1087 str

1088 Video signal transfer characteristics code point description.

1089

1090 References

1091 ----------

1092 :cite:`FFmpegDevelopers2022a`,

1093 :cite:`InternationalOrganizationforStandardization2013`,

1094 :cite:`InternationalOrganizationforStandardization2021`,

1095 :cite:`InternationalOrganizationforStandardization2020`,

1096 :cite:`InternationalTelecommunicationUnion2021`

1097

1098 Examples

1099 --------

1100 >>> description = describe_video_signal_transfer_characteristics(1, width=75)

1101 ... # doctest: +ELLIPSIS

1102 ===========================================================================

1103 * *

1104 * Transfer Characteristics: 1 *

1105 * --------------------------- *

1106 * *

1107 * Function : <function oetf_BT709 at 0x...>...*

1108 * FFmpeg Constants : ['AVCOL_TRC_BT709', 'BT709'] *

1109 * *

1110 ===========================================================================

1111 >>> description = describe_video_signal_transfer_characteristics(2, width=75)

1112 ... # doctest: +ELLIPSIS

1113 ===========================================================================

1114 * *

1115 * Transfer Characteristics: 2 *

1116 * --------------------------- *

1117 * *

1118 * Function : <function _unspecified at 0x...>...*

1119 * FFmpeg Constants : ['AVCOL_TRC_UNSPECIFIED', 'UNSPECIFIED'] *

1120 * *

1121 ===========================================================================

1122 >>> description = describe_video_signal_transfer_characteristics(

1123 ... FFmpegConstantsTransferCharacteristics_ITUTH273.SMPTE428, width=75

1124 ... )

1125 ... # doctest: +ELLIPSIS

1126 ===========================================================================

1127 * *

1128 * Transfer Characteristics: 17 *

1129 * ---------------------------- *

1130 * *

1131 * Function : <function eotf_inverse_H273_ST428_1 at *

1132 * 0x...>...*

1133 * FFmpeg Constants : ['AVCOL_TRC_SMPTE428', 'AVCOL_TRC_SMPTEST428_1', *

1134 * 'SMPTE428', 'SMPTEST428_1'] *

1135 * *

1136 ===========================================================================

1137 """

1138

1139 @dataclass

1140 class SpecificationTransferCharacteristics:

1141 """Specification for video signal transfer characteristics code point."""

1142

1143 code_point: int

1144 function: Callable

1145 ffmpeg_constants: list

1146

1147 members = FFmpegConstantsTransferCharacteristics_ITUTH273.__members__.items()

1148 ffmpeg_constants = [

1149 name

1150 for name, member in members

1151 if member.name.startswith("AVCOL_TRC_") and member.value == code_point

1152 ]

1153

1154 description = SpecificationTransferCharacteristics(

1155 code_point,

1156 TRANSFER_CHARACTERISTICS_ITUTH273[code_point],

1157 ffmpeg_constants,

1158 )

1159

1160 message = multiline_str(

1161 description,

1162 [

1163 {

1164 "name": "code_point",

1165 "section": True,

1166 "formatter": lambda x: f"Transfer Characteristics: {x}",

1167 },

1168 {"line_break": True},

1169 {"name": "function", "label": "Function"},

1170 {"name": "ffmpeg_constants", "label": "FFmpeg Constants"},

1171 ],

1172 )

1173

1174 if print_description:

1175 message_box(

1176 message,

1177 **kwargs,

1178 )

1179

1180 return message

1181

1182

1183 def describe_video_signal_matrix_coefficients(

1184 code_point: int, print_description: bool = True, **kwargs: Any

1185) -> str:

1186 """

1187 Describe the specified video signal matrix coefficients code point.

1188

1189 Parameters

1190 ----------

1191 code_point

1192 Video signal matrix coefficients code point to describe from the

1193 :attr:`colour.MATRIX_COEFFICIENTS_ITUTH273` attribute.

1194 print_description

1195 Whether to print the description.

1196

1197 Other Parameters

1198 ----------------

1199 padding

1200 {:func:`colour.utilities.message_box`},

1201 Padding on each side of the message.

1202 print_callable

1203 {:func:`colour.utilities.message_box`},

1204 Callable used to print the message box.

1205 width

1206 {:func:`colour.utilities.message_box`},

1207 Message box width.

1208

1209 Returns

1210 -------

1211 str

1212 Video signal matrix coefficients code point description.

1213

1214 References

1215 ----------

1216 :cite:`FFmpegDevelopers2022b`,

1217 :cite:`InternationalOrganizationforStandardization2013`,

1218 :cite:`InternationalOrganizationforStandardization2021`,

1219 :cite:`InternationalOrganizationforStandardization2020`,

1220 :cite:`InternationalTelecommunicationUnion2021`

1221

1222 Examples

1223 --------

1224 >>> description = describe_video_signal_matrix_coefficients(1, width=75)

1225 ===========================================================================

1226 * *

1227 * Matrix Coefficients: 1 *

1228 * ---------------------- *

1229 * *

1230 * Matrix Coefficients : [ 0.2126 0.0722] *

1231 * FFmpeg Constants : ['AVCOL_SPC_BT709', 'BT709'] *

1232 * *

1233 ===========================================================================

1234 >>> description = describe_video_signal_matrix_coefficients(2, width=75)

1235 ===========================================================================

1236 * *

1237 * Matrix Coefficients: 2 *

1238 * ---------------------- *

1239 * *

1240 * Matrix Coefficients : Unspecified *

1241 * FFmpeg Constants : ['AVCOL_SPC_UNSPECIFIED', 'UNSPECIFIED'] *

1242 * *

1243 ===========================================================================

1244 >>> description = describe_video_signal_matrix_coefficients(

1245 ... FFmpegConstantsMatrixCoefficients_ITUTH273.ICTCP, width=75

1246 ... )

1247 ... # doctest: +ELLIPSIS

1248 ===========================================================================

1249 * *

1250 * Matrix Coefficients: 14 *

1251 * ----------------------- *

1252 * *

1253 * Matrix Coefficients : ICTCP *

1254 * FFmpeg Constants : ['AVCOL_SPC_ICTCP', 'ICTCP'] *

1255 * *

1256 ===========================================================================

1257 """

1258

1259 @dataclass

1260 class SpecificationMatrixCoefficients:

1261 """Specification for video signal matrix coefficients code point."""

1262

1263 code_point: int

1264 matrix_coefficients: NDArrayFloat

1265 ffmpeg_constants: list

1266

1267 members = FFmpegConstantsMatrixCoefficients_ITUTH273.__members__.items()

1268 ffmpeg_constants = [

1269 name

1270 for name, member in members

1271 if member.name.startswith("AVCOL_SPC_") and member.value == code_point

1272 ]

1273

1274 description = SpecificationMatrixCoefficients(

1275 code_point,

1276 MATRIX_COEFFICIENTS_ITUTH273[code_point],

1277 ffmpeg_constants,

1278 )

1279

1280 message = multiline_str(

1281 description,

1282 [

1283 {

1284 "name": "code_point",

1285 "section": True,

1286 "formatter": lambda x: f"Matrix Coefficients: {x}",

1287 },

1288 {"line_break": True},

1289 {

1290 "name": "matrix_coefficients",

1291 "label": "Matrix Coefficients",

1292 },

1293 {"name": "ffmpeg_constants", "label": "FFmpeg Constants"},

1294 ],

1295 )

1296

1297 if print_description:

1298 message_box(

1299 message,

1300 **kwargs,

1301 )

1302

1303 return message