Skip to main content

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}