gamut_color/cicp.rs
1//! CICP (ITU-T H.273 / ISO/IEC 23091-2) code points shared by the AVIF `colr` (nclx) box and the
2//! AV1 sequence header `color_config` (AV1 §5.5.2 / §6.4.2).
3//!
4//! Each enum is `#[repr(u16)]` with discriminants equal to the spec code points, so
5//! [`MatrixCoefficients::code_point`] (and the siblings) is just the discriminant. M0 uses
6//! `MatrixCoefficients::Identity`, `ColourPrimaries::Bt709`, `TransferCharacteristics::Srgb`, and
7//! `ColorRange::Full`; the remaining named values are included for M2/M4 extension.
8//!
9//! Naming follows each identifier's source spec: the H.273 types keep the spec's British
10//! spelling ([`ColourPrimaries`], as published), while AV1-derived names use the AV1 spec's
11//! American spelling ([`ColorRange`], after `color_range`).
12
13/// Matrix coefficients (CICP `MatrixCoefficients`). `Identity` (0) carries RGB directly with no
14/// colour transform and requires 4:4:4 — the basis for lossless RGB AVIF.
15///
16/// `#[non_exhaustive]`: H.273 defines further code points, added here as milestones need them.
17#[repr(u16)]
18#[non_exhaustive]
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
20pub enum MatrixCoefficients {
21 /// Identity (RGB / "GBR"); no luma–chroma transform. Requires 4:4:4. (Code point 0.)
22 Identity = 0,
23 /// BT.709 — KR=0.2126, KB=0.0722. (Code point 1.)
24 Bt709 = 1,
25 /// Unspecified. (Code point 2.)
26 Unspecified = 2,
27 /// BT.601 / SMPTE 170M — KR=0.299, KB=0.114. (Code point 6; BT.470 System B,G is
28 /// point 5, with identical coefficients.)
29 Bt601 = 6,
30 /// YCgCo. (Code point 8.)
31 YCgCo = 8,
32 /// BT.2020 non-constant luminance. (Code point 9.)
33 Bt2020Ncl = 9,
34}
35
36impl MatrixCoefficients {
37 /// The CICP code point.
38 #[must_use]
39 pub fn code_point(self) -> u16 {
40 self as u16
41 }
42
43 /// The [`MatrixCoefficients`] for `code_point`, or `None` for any point not modeled here (a
44 /// later minor release may turn a `None` into `Some`). The inverse of
45 /// [`MatrixCoefficients::code_point`], for typing a value parsed from a `colr` box or AV1
46 /// header.
47 #[must_use]
48 pub fn from_code_point(code_point: u16) -> Option<Self> {
49 match code_point {
50 0 => Some(MatrixCoefficients::Identity),
51 1 => Some(MatrixCoefficients::Bt709),
52 2 => Some(MatrixCoefficients::Unspecified),
53 6 => Some(MatrixCoefficients::Bt601),
54 8 => Some(MatrixCoefficients::YCgCo),
55 9 => Some(MatrixCoefficients::Bt2020Ncl),
56 _ => None,
57 }
58 }
59}
60
61/// Colour primaries (CICP `ColourPrimaries`).
62///
63/// `#[non_exhaustive]`: H.273 defines further code points, added here as milestones need them.
64#[doc(alias = "ColorPrimaries")]
65#[repr(u16)]
66#[non_exhaustive]
67#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
68pub enum ColourPrimaries {
69 /// BT.709 (also sRGB primaries). (Code point 1.)
70 Bt709 = 1,
71 /// Unspecified. (Code point 2.)
72 Unspecified = 2,
73 /// BT.601 625-line / BT.470 System B,G. (Code point 5.)
74 Bt601Pal = 5,
75 /// SMPTE 170M (BT.601 525-line). (Code point 6.)
76 Smpte170m = 6,
77 /// BT.2020 / BT.2100. (Code point 9.)
78 Bt2020 = 9,
79 /// SMPTE EG 432-1 (Display P3). (Code point 12.)
80 DisplayP3 = 12,
81}
82
83impl ColourPrimaries {
84 /// The CICP code point.
85 #[must_use]
86 pub fn code_point(self) -> u16 {
87 self as u16
88 }
89
90 /// The [`ColourPrimaries`] for `code_point`, or `None` for any point not modeled here (a
91 /// later minor release may turn a `None` into `Some`). The inverse of
92 /// [`ColourPrimaries::code_point`].
93 #[must_use]
94 pub fn from_code_point(code_point: u16) -> Option<Self> {
95 match code_point {
96 1 => Some(ColourPrimaries::Bt709),
97 2 => Some(ColourPrimaries::Unspecified),
98 5 => Some(ColourPrimaries::Bt601Pal),
99 6 => Some(ColourPrimaries::Smpte170m),
100 9 => Some(ColourPrimaries::Bt2020),
101 12 => Some(ColourPrimaries::DisplayP3),
102 _ => None,
103 }
104 }
105}
106
107/// Transfer characteristics (CICP `TransferCharacteristics`).
108///
109/// `#[non_exhaustive]`: H.273 defines further code points, added here as milestones need them.
110#[repr(u16)]
111#[non_exhaustive]
112#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
113pub enum TransferCharacteristics {
114 /// BT.709. (Code point 1.)
115 Bt709 = 1,
116 /// Unspecified. (Code point 2.)
117 Unspecified = 2,
118 /// Linear — the identity transfer, `V = Lc`. (Code point 8.)
119 Linear = 8,
120 /// sRGB / IEC 61966-2-1. (Code point 13.)
121 Srgb = 13,
122 /// BT.2020 10-bit. (Code point 14.)
123 Bt2020_10 = 14,
124 /// SMPTE ST 2084 (PQ). (Code point 16.)
125 Pq = 16,
126 /// ARIB STD-B67 (HLG). (Code point 18.)
127 Hlg = 18,
128}
129
130impl TransferCharacteristics {
131 /// The CICP code point.
132 #[must_use]
133 pub fn code_point(self) -> u16 {
134 self as u16
135 }
136
137 /// The [`TransferCharacteristics`] for `code_point`, or `None` for any point not modeled here
138 /// (a later minor release may turn a `None` into `Some`). The inverse of
139 /// [`TransferCharacteristics::code_point`].
140 #[must_use]
141 pub fn from_code_point(code_point: u16) -> Option<Self> {
142 match code_point {
143 1 => Some(TransferCharacteristics::Bt709),
144 2 => Some(TransferCharacteristics::Unspecified),
145 8 => Some(TransferCharacteristics::Linear),
146 13 => Some(TransferCharacteristics::Srgb),
147 14 => Some(TransferCharacteristics::Bt2020_10),
148 16 => Some(TransferCharacteristics::Pq),
149 18 => Some(TransferCharacteristics::Hlg),
150 _ => None,
151 }
152 }
153}
154
155/// Sample value range (CICP `VideoFullRangeFlag`; AV1 `color_range`).
156///
157/// Besides signalling the range in a `colr` / AV1 header, this is the range selector for the
158/// RGB ↔ YCbCr conversions in [`crate::ycbcr`] — so one type carries the choice end to end.
159///
160/// Deliberately exhaustive (unlike the code-point enums): the flag is a spec-complete single bit,
161/// so consumers can match it exhaustively forever.
162#[repr(u8)]
163#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
164pub enum ColorRange {
165 /// Studio / limited range (e.g. luma 16–235 for 8-bit). (Flag 0.)
166 Limited = 0,
167 /// Full range (0–255 for 8-bit). (Flag 1.)
168 Full = 1,
169}
170
171impl ColorRange {
172 /// The `color_range` / `full_range_flag` value.
173 #[must_use]
174 pub fn flag(self) -> u8 {
175 self as u8
176 }
177
178 /// The [`ColorRange`] for `flag` (0 or 1), or `None` for any other value. The inverse of
179 /// [`ColorRange::flag`].
180 #[must_use]
181 pub fn from_flag(flag: u8) -> Option<Self> {
182 match flag {
183 0 => Some(ColorRange::Limited),
184 1 => Some(ColorRange::Full),
185 _ => None,
186 }
187 }
188}
189
190#[cfg(test)]
191mod tests {
192 use super::*;
193
194 #[test]
195 fn code_points_match_spec() {
196 assert_eq!(MatrixCoefficients::Identity.code_point(), 0);
197 assert_eq!(MatrixCoefficients::Bt709.code_point(), 1);
198 assert_eq!(ColourPrimaries::Bt709.code_point(), 1);
199 // A second, non-1 primaries value pins `self as u16` (a constant `1` would pass on Bt709
200 // alone).
201 assert_eq!(ColourPrimaries::Bt2020.code_point(), 9);
202 assert_eq!(ColourPrimaries::DisplayP3.code_point(), 12);
203 assert_eq!(TransferCharacteristics::Linear.code_point(), 8);
204 assert_eq!(TransferCharacteristics::Srgb.code_point(), 13);
205 assert_eq!(TransferCharacteristics::Pq.code_point(), 16);
206 assert_eq!(ColorRange::Full.flag(), 1);
207 assert_eq!(ColorRange::Limited.flag(), 0);
208 }
209
210 #[test]
211 fn code_point_inverses_round_trip() {
212 use ColourPrimaries as Cp;
213 use MatrixCoefficients as Mc;
214 use TransferCharacteristics as Tc;
215 for mc in [
216 Mc::Identity,
217 Mc::Bt709,
218 Mc::Unspecified,
219 Mc::Bt601,
220 Mc::YCgCo,
221 Mc::Bt2020Ncl,
222 ] {
223 assert_eq!(Mc::from_code_point(mc.code_point()), Some(mc));
224 }
225 for cp in [
226 Cp::Bt709,
227 Cp::Unspecified,
228 Cp::Bt601Pal,
229 Cp::Smpte170m,
230 Cp::Bt2020,
231 Cp::DisplayP3,
232 ] {
233 assert_eq!(Cp::from_code_point(cp.code_point()), Some(cp));
234 }
235 for tc in [
236 Tc::Bt709,
237 Tc::Unspecified,
238 Tc::Linear,
239 Tc::Srgb,
240 Tc::Bt2020_10,
241 Tc::Pq,
242 Tc::Hlg,
243 ] {
244 assert_eq!(Tc::from_code_point(tc.code_point()), Some(tc));
245 }
246 for range in [ColorRange::Limited, ColorRange::Full] {
247 assert_eq!(ColorRange::from_flag(range.flag()), Some(range));
248 }
249 // Unmodeled points map to None (3 = "reserved" / not modeled in every table).
250 assert_eq!(Mc::from_code_point(3), None);
251 assert_eq!(Cp::from_code_point(3), None);
252 assert_eq!(Tc::from_code_point(3), None);
253 assert_eq!(ColorRange::from_flag(2), None);
254 }
255}