otf_pixels_core/
orientation.rs

1//! [`Orientation`] — how a stored image must be turned to display upright.
2//!
3//! Cameras write pixels in sensor order and record the way the device was held
4//! as metadata rather than rotating the pixels: EXIF's `Orientation` tag in
5//! JPEG, TIFF, PNG and WebP, and the `irot`/`imir` properties in HEIF/AVIF.
6//! Decoders report it here; applying it is a pipeline decision (`auto_orient`,
7//! SPEC §Safety and limits), so a decoder never rotates its own output.
8
9/// One of the eight orientations the EXIF/TIFF `Orientation` tag (274) can
10/// name.
11///
12/// Each variant describes the transform that makes the stored image upright.
13/// All eight are a clockwise quarter-turn rotation followed, optionally, by a
14/// horizontal mirror, which is the form [`Orientation::clockwise_turns`] and
15/// [`Orientation::mirrored`] expose and [`Orientation::from_parts`] builds
16/// from. HEIF's rotate-then-mirror properties reduce to the same form.
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
18pub enum Orientation {
19    /// EXIF 1: already upright.
20    #[default]
21    Normal,
22    /// EXIF 2: mirror left to right.
23    FlipHorizontal,
24    /// EXIF 3: rotate 180 degrees.
25    Rotate180,
26    /// EXIF 4: mirror top to bottom.
27    FlipVertical,
28    /// EXIF 5: mirror across the top-left to bottom-right diagonal.
29    Transpose,
30    /// EXIF 6: rotate 90 degrees clockwise.
31    Rotate90,
32    /// EXIF 7: mirror across the top-right to bottom-left diagonal.
33    Transverse,
34    /// EXIF 8: rotate 270 degrees clockwise, i.e. 90 anticlockwise.
35    Rotate270,
36}
37
38impl Orientation {
39    /// The orientation an EXIF `Orientation` value names, or `None` for a value
40    /// outside 1–8.
41    #[must_use]
42    pub const fn from_exif(value: u16) -> Option<Self> {
43        Some(match value {
44            1 => Self::Normal,
45            2 => Self::FlipHorizontal,
46            3 => Self::Rotate180,
47            4 => Self::FlipVertical,
48            5 => Self::Transpose,
49            6 => Self::Rotate90,
50            7 => Self::Transverse,
51            8 => Self::Rotate270,
52            _ => return None,
53        })
54    }
55
56    /// The EXIF `Orientation` value, 1–8.
57    #[must_use]
58    pub const fn exif(self) -> u8 {
59        match self {
60            Self::Normal => 1,
61            Self::FlipHorizontal => 2,
62            Self::Rotate180 => 3,
63            Self::FlipVertical => 4,
64            Self::Transpose => 5,
65            Self::Rotate90 => 6,
66            Self::Transverse => 7,
67            Self::Rotate270 => 8,
68        }
69    }
70
71    /// Rotate `turns` quarter turns clockwise (taken modulo 4), then mirror
72    /// left to right if `mirrored`.
73    #[must_use]
74    pub const fn from_parts(turns: u8, mirrored: bool) -> Self {
75        match (turns % 4, mirrored) {
76            (0, false) => Self::Normal,
77            (0, true) => Self::FlipHorizontal,
78            (1, false) => Self::Rotate90,
79            // Transpose sends (x, y) to (y, x): a clockwise quarter turn sends
80            // it to (h - 1 - y, x), and the mirror then undoes the reflection.
81            (1, true) => Self::Transpose,
82            (2, false) => Self::Rotate180,
83            // A half turn mirrors both axes; mirroring left to right again
84            // leaves only the vertical one.
85            (2, true) => Self::FlipVertical,
86            (3, false) => Self::Rotate270,
87            _ => Self::Transverse,
88        }
89    }
90
91    /// Clockwise quarter turns to apply first, 0–3.
92    #[must_use]
93    pub const fn clockwise_turns(self) -> u8 {
94        match self {
95            Self::Normal | Self::FlipHorizontal => 0,
96            Self::Rotate90 | Self::Transpose => 1,
97            Self::Rotate180 | Self::FlipVertical => 2,
98            Self::Rotate270 | Self::Transverse => 3,
99        }
100    }
101
102    /// Whether a left-to-right mirror follows the rotation.
103    #[must_use]
104    pub const fn mirrored(self) -> bool {
105        matches!(
106            self,
107            Self::FlipHorizontal | Self::FlipVertical | Self::Transpose | Self::Transverse
108        )
109    }
110
111    /// Whether displaying upright exchanges width and height.
112    #[must_use]
113    pub const fn transposes(self) -> bool {
114        self.clockwise_turns() % 2 == 1
115    }
116
117    /// Read the `Orientation` tag from an EXIF block.
118    ///
119    /// `exif` is the TIFF structure EXIF is made of, optionally behind the
120    /// `Exif\0\0` identifier a JPEG APP1 segment carries. PNG's `eXIf` and
121    /// WebP's `EXIF` chunk are specified without the identifier, but writers
122    /// that copy it across from a JPEG are common, so both are accepted.
123    ///
124    /// A missing tag, an out-of-range value or a malformed block all yield
125    /// `None` rather than an error: broken metadata is not a broken image,
126    /// and refusing to decode a photograph over it would be the wrong trade.
127    #[must_use]
128    pub fn from_exif_block(exif: &[u8]) -> Option<Self> {
129        let tiff = exif.strip_prefix(b"Exif\0\0").unwrap_or(exif);
130
131        let big_endian = match tiff.get(..2)? {
132            b"MM" => true,
133            b"II" => false,
134            _ => return None,
135        };
136        let short = |at: usize| -> Option<u16> {
137            let bytes = [*tiff.get(at)?, *tiff.get(at.checked_add(1)?)?];
138            Some(if big_endian {
139                u16::from_be_bytes(bytes)
140            } else {
141                u16::from_le_bytes(bytes)
142            })
143        };
144        let long = |at: usize| -> Option<u32> {
145            let bytes = tiff.get(at..at.checked_add(4)?)?;
146            let bytes = [
147                *bytes.first()?,
148                *bytes.get(1)?,
149                *bytes.get(2)?,
150                *bytes.get(3)?,
151            ];
152            Some(if big_endian {
153                u32::from_be_bytes(bytes)
154            } else {
155                u32::from_le_bytes(bytes)
156            })
157        };
158
159        if short(2)? != 42 {
160            return None;
161        }
162        let ifd = usize::try_from(long(4)?).ok()?;
163        let entries = short(ifd)?;
164        for entry in 0..usize::from(entries) {
165            let at = ifd.checked_add(2)?.checked_add(entry.checked_mul(12)?)?;
166            // 0x0112 is Orientation; a SHORT, so its single value sits in the
167            // first two bytes of the value field rather than at an offset.
168            if short(at)? == 0x0112 {
169                return Self::from_exif(short(at.checked_add(8)?)?);
170            }
171        }
172        None
173    }
174
175    /// Set the Orientation tag of the EXIF block `exif` to this orientation,
176    /// in place, returning whether the block had one to set.
177    ///
178    /// `exif` is TIFF-structured, with or without the `Exif\0\0`
179    /// identifier. Only IFD0's existing tag is rewritten: nothing is added,
180    /// and a malformed block is left alone. This is how a copied block is
181    /// kept truthful once the pixels it describes have been turned upright.
182    pub fn write_to_exif_block(self, exif: &mut [u8]) -> bool {
183        let start = if exif.starts_with(b"Exif\0\0") { 6 } else { 0 };
184        let Some(tiff) = exif.get_mut(start..) else {
185            return false;
186        };
187        let Some(at) = orientation_entry(tiff) else {
188            return false;
189        };
190        let big_endian = tiff.first() == Some(&b'M');
191        let value = u16::from(self.exif());
192        let bytes = if big_endian {
193            value.to_be_bytes()
194        } else {
195            value.to_le_bytes()
196        };
197        match tiff.get_mut(at + 8..at + 10) {
198            Some(slot) => {
199                slot.copy_from_slice(&bytes);
200                true
201            }
202            None => false,
203        }
204    }
205}
206
207/// Where IFD0's Orientation entry starts in TIFF-structured `tiff`.
208fn orientation_entry(tiff: &[u8]) -> Option<usize> {
209    let big_endian = match tiff.get(..2)? {
210        b"MM" => true,
211        b"II" => false,
212        _ => return None,
213    };
214    let short = |at: usize| -> Option<u16> {
215        let bytes = [*tiff.get(at)?, *tiff.get(at.checked_add(1)?)?];
216        Some(if big_endian {
217            u16::from_be_bytes(bytes)
218        } else {
219            u16::from_le_bytes(bytes)
220        })
221    };
222    let long = |at: usize| -> Option<u32> {
223        let b = tiff.get(at..at.checked_add(4)?)?;
224        let bytes = [*b.first()?, *b.get(1)?, *b.get(2)?, *b.get(3)?];
225        Some(if big_endian {
226            u32::from_be_bytes(bytes)
227        } else {
228            u32::from_le_bytes(bytes)
229        })
230    };
231    if short(2)? != 42 {
232        return None;
233    }
234    let ifd = usize::try_from(long(4)?).ok()?;
235    for entry in 0..usize::from(short(ifd)?) {
236        let at = ifd.checked_add(2)?.checked_add(entry.checked_mul(12)?)?;
237        if short(at)? == 0x0112 {
238            tiff.get(at..at.checked_add(12)?)?;
239            return Some(at);
240        }
241    }
242    None
243}
244
245#[cfg(test)]
246#[allow(
247    clippy::unwrap_used,
248    clippy::indexing_slicing,
249    reason = "tests assert on known-good values"
250)]
251mod tests {
252    use super::*;
253
254    const ALL: [Orientation; 8] = [
255        Orientation::Normal,
256        Orientation::FlipHorizontal,
257        Orientation::Rotate180,
258        Orientation::FlipVertical,
259        Orientation::Transpose,
260        Orientation::Rotate90,
261        Orientation::Transverse,
262        Orientation::Rotate270,
263    ];
264
265    /// Apply `orientation` to a `w` x `h` grid of distinct values by the
266    /// parts decomposition, one primitive at a time.
267    fn by_parts(orientation: Orientation, w: usize, h: usize) -> (Vec<usize>, usize, usize) {
268        let mut grid: Vec<usize> = (0..w * h).collect();
269        let (mut w, mut h) = (w, h);
270        for _ in 0..orientation.clockwise_turns() {
271            // Clockwise: output (x, y) comes from input (y, h - 1 - x).
272            let mut turned = vec![0; w * h];
273            for y in 0..w {
274                for x in 0..h {
275                    turned[y * h + x] = grid[(h - 1 - x) * w + y];
276                }
277            }
278            grid = turned;
279            (w, h) = (h, w);
280        }
281        if orientation.mirrored() {
282            for row in grid.chunks_mut(w) {
283                row.reverse();
284            }
285        }
286        (grid, w, h)
287    }
288
289    /// The same, from the EXIF definitions directly: where the stored image's
290    /// 0th row and 0th column end up (TIFF 6.0 / EXIF 2.3 §4.6.4).
291    fn by_definition(orientation: Orientation, w: usize, h: usize) -> (Vec<usize>, usize, usize) {
292        let (ow, oh) = if orientation.transposes() {
293            (h, w)
294        } else {
295            (w, h)
296        };
297        let mut grid = vec![0; w * h];
298        for y in 0..oh {
299            for x in 0..ow {
300                let (sx, sy) = match orientation {
301                    Orientation::Normal => (x, y),
302                    Orientation::FlipHorizontal => (w - 1 - x, y),
303                    Orientation::Rotate180 => (w - 1 - x, h - 1 - y),
304                    Orientation::FlipVertical => (x, h - 1 - y),
305                    Orientation::Transpose => (y, x),
306                    Orientation::Rotate90 => (y, h - 1 - x),
307                    Orientation::Transverse => (w - 1 - y, h - 1 - x),
308                    Orientation::Rotate270 => (w - 1 - y, x),
309                };
310                grid[y * ow + x] = sy * w + sx;
311            }
312        }
313        (grid, ow, oh)
314    }
315
316    #[test]
317    fn the_parts_decomposition_matches_the_exif_definitions() {
318        for orientation in ALL {
319            assert_eq!(
320                by_parts(orientation, 3, 2),
321                by_definition(orientation, 3, 2),
322                "{orientation:?}"
323            );
324        }
325    }
326
327    #[test]
328    fn parts_and_exif_values_round_trip() {
329        for orientation in ALL {
330            assert_eq!(
331                Orientation::from_parts(orientation.clockwise_turns(), orientation.mirrored()),
332                orientation
333            );
334            assert_eq!(
335                Orientation::from_exif(u16::from(orientation.exif())),
336                Some(orientation)
337            );
338        }
339        assert_eq!(Orientation::from_parts(5, false), Orientation::Rotate90);
340        assert_eq!(Orientation::from_exif(0), None);
341        assert_eq!(Orientation::from_exif(9), None);
342    }
343
344    #[test]
345    fn exif_orientation_is_read_from_both_byte_orders() {
346        // Little-endian: II, 42, IFD at 8, one entry, tag 0x0112, SHORT, 1, 6.
347        let little = b"Exif\0\0II*\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x06\0\0\0";
348        assert_eq!(
349            Orientation::from_exif_block(little),
350            Some(Orientation::Rotate90)
351        );
352
353        let big = b"Exif\0\0MM\0*\0\0\0\x08\0\x01\x01\x12\0\x03\0\0\0\x01\0\x03\0\0";
354        assert_eq!(
355            Orientation::from_exif_block(big),
356            Some(Orientation::Rotate180)
357        );
358    }
359
360    #[test]
361    fn the_exif_identifier_is_optional() {
362        let bare = b"II*\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x08\0\0\0";
363        assert_eq!(
364            Orientation::from_exif_block(bare),
365            Some(Orientation::Rotate270)
366        );
367    }
368
369    #[test]
370    fn the_orientation_tag_is_rewritten_in_place() {
371        let mut little =
372            b"Exif\0\0II*\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x06\0\0\0".to_vec();
373        assert!(Orientation::Normal.write_to_exif_block(&mut little));
374        assert_eq!(
375            Orientation::from_exif_block(&little),
376            Some(Orientation::Normal)
377        );
378        let mut big = b"MM\0*\0\0\0\x08\0\x01\x01\x12\0\x03\0\0\0\x01\0\x03\0\0".to_vec();
379        assert!(Orientation::Rotate90.write_to_exif_block(&mut big));
380        assert_eq!(
381            Orientation::from_exif_block(&big),
382            Some(Orientation::Rotate90)
383        );
384        // Nothing to rewrite in a block without the tag, or a broken one.
385        let mut untagged = b"II*\0\x08\0\0\0\x01\0\x10\x01\x03\0\x01\0\0\0\x06\0\0\0".to_vec();
386        let before = untagged.clone();
387        assert!(!Orientation::Normal.write_to_exif_block(&mut untagged));
388        assert_eq!(untagged, before);
389        assert!(!Orientation::Normal.write_to_exif_block(&mut b"II*\0\xff\0\0\0".to_vec()));
390    }
391
392    #[test]
393    fn broken_exif_yields_no_orientation_rather_than_an_error() {
394        assert_eq!(
395            Orientation::from_exif_block(b"Exif\0\0XX*\0\x08\0\0\0"),
396            None
397        );
398        assert_eq!(Orientation::from_exif_block(b"Exif\0\0II*\0"), None);
399        assert_eq!(Orientation::from_exif_block(b"not exif at all"), None);
400        assert_eq!(Orientation::from_exif_block(b""), None);
401        // An IFD offset pointing far past the end.
402        assert_eq!(Orientation::from_exif_block(b"II*\0\xff\xff\xff\xff"), None);
403        // An entry count promising more entries than the block holds.
404        assert_eq!(
405            Orientation::from_exif_block(b"II*\0\x08\0\0\0\xff\xff"),
406            None
407        );
408        // An out-of-range orientation is metadata we decline to trust.
409        let bogus = b"Exif\0\0II*\0\x08\0\0\0\x01\0\x12\x01\x03\0\x01\0\0\0\x09\0\0\0";
410        assert_eq!(Orientation::from_exif_block(bogus), None);
411    }
412
413    #[test]
414    fn a_block_without_the_tag_has_no_orientation() {
415        // One entry, tag 0x0100 (ImageWidth).
416        let other = b"II*\0\x08\0\0\0\x01\0\x00\x01\x03\0\x01\0\0\0\x06\0\0\0";
417        assert_eq!(Orientation::from_exif_block(other), None);
418    }
419}
otf_pixels_core/orientation.rs

otf_pixels_core/
orientation.rs
