Debian Codegraph @

.cargo/vendor/image/src/metadata.rs

raw
1 //! Types describing image metadata
2 pub(crate) mod cicp;
3
4 use std::io::{Cursor, Read};
5
6 use byteorder_lite::{BigEndian, LittleEndian, ReadBytesExt, WriteBytesExt};
7
8 pub use self::cicp::{
9 Cicp, CicpColorPrimaries, CicpMatrixCoefficients, CicpTransferCharacteristics, CicpTransform,
10 CicpVideoFullRangeFlag,
11 };
12
13 /// Describes the transformations to be applied to the image.
14 /// Compatible with [Exif orientation](https://web.archive.org/web/20200412005226/https://www.impulseadventure.com/photo/exif-orientation.html).
15 ///
16 /// Orientation is specified in the file's metadata, and is often written by cameras.
17 ///
18 /// You can apply it to an image via [`DynamicImage::apply_orientation`](crate::DynamicImage::apply_orientation).
19 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
20 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
21 pub enum Orientation {
22 /// Do not perform any transformations.
23 NoTransforms,
24 /// Rotate by 90 degrees clockwise.
25 Rotate90,
26 /// Rotate by 180 degrees. Can be performed in-place.
27 Rotate180,
28 /// Rotate by 270 degrees clockwise. Equivalent to rotating by 90 degrees counter-clockwise.
29 Rotate270,
30 /// Flip horizontally. Can be performed in-place.
31 FlipHorizontal,
32 /// Flip vertically. Can be performed in-place.
33 FlipVertical,
34 /// Rotate by 90 degrees clockwise and flip horizontally.
35 Rotate90FlipH,
36 /// Rotate by 270 degrees clockwise and flip horizontally.
37 Rotate270FlipH,
38 }
39
40 impl Orientation {
41 /// Converts from [Exif orientation](https://web.archive.org/web/20200412005226/https://www.impulseadventure.com/photo/exif-orientation.html)
42 #[must_use]
43 pub fn from_exif(exif_orientation: u8) -> Option<Self> {
44 match exif_orientation {
45 1 => Some(Self::NoTransforms),
46 2 => Some(Self::FlipHorizontal),
47 3 => Some(Self::Rotate180),
48 4 => Some(Self::FlipVertical),
49 5 => Some(Self::Rotate90FlipH),
50 6 => Some(Self::Rotate90),
51 7 => Some(Self::Rotate270FlipH),
52 8 => Some(Self::Rotate270),
53 0 | 9.. => None,
54 }
55 }
56
57 /// Converts into [Exif orientation](https://web.archive.org/web/20200412005226/https://www.impulseadventure.com/photo/exif-orientation.html)
58 #[must_use]
59 pub fn to_exif(self) -> u8 {
60 match self {
61 Self::NoTransforms => 1,
62 Self::FlipHorizontal => 2,
63 Self::Rotate180 => 3,
64 Self::FlipVertical => 4,
65 Self::Rotate90FlipH => 5,
66 Self::Rotate90 => 6,
67 Self::Rotate270FlipH => 7,
68 Self::Rotate270 => 8,
69 }
70 }
71
72 /// Extracts the image orientation from a raw Exif chunk.
73 ///
74 /// You can obtain the Exif chunk using
75 /// [ImageDecoder::exif_metadata](crate::ImageDecoder::exif_metadata).
76 ///
77 /// It is more convenient to use [ImageDecoder::orientation](crate::ImageDecoder::orientation)
78 /// than to invoke this function.
79 /// Only use this function if you extract and process the Exif chunk separately.
80 #[must_use]
81 pub fn from_exif_chunk(chunk: &[u8]) -> Option<Self> {
82 Self::from_exif_chunk_inner(chunk).map(|res| res.0)
83 }
84
85 /// Extracts the image orientation from a raw Exif chunk and sets the orientation in the Exif chunk to `Orientation::NoTransforms`.
86 /// This is useful if you want to apply the orientation yourself, and then encode the image with the rest of the Exif chunk intact.
87 ///
88 /// If the orientation data is not cleared from the Exif chunk after you apply the orientation data yourself,
89 /// the image will end up being rotated once again by any software that correctly handles Exif, leading to an incorrect result.
90 ///
91 /// If the Exif value is present but invalid, `None` is returned and the Exif chunk is not modified.
92 #[must_use]
93 pub fn remove_from_exif_chunk(chunk: &mut [u8]) -> Option<Self> {
94 if let Some((orientation, offset, endian)) = Self::from_exif_chunk_inner(chunk) {
95 let mut writer = Cursor::new(chunk);
96 writer.set_position(offset);
97 let no_orientation: u16 = Self::NoTransforms.to_exif().into();
98 match endian {
99 ExifEndian::Big => writer.write_u16::<BigEndian>(no_orientation).unwrap(),
100 ExifEndian::Little => writer.write_u16::<LittleEndian>(no_orientation).unwrap(),
101 }
102 Some(orientation)
103 } else {
104 None
105 }
106 }
107
108 /// Returns the orientation, the offset in the Exif chunk where it was found, and Exif chunk endianness
109 #[must_use]
110 fn from_exif_chunk_inner(chunk: &[u8]) -> Option<(Self, u64, ExifEndian)> {
111 let mut reader = Cursor::new(chunk);
112
113 let mut magic = [0; 4];
114 reader.read_exact(&mut magic).ok()?;
115
116 match magic {
117 [0x49, 0x49, 42, 0] => {
118 return Self::locate_orientation_entry::<LittleEndian>(&mut reader)
119 .map(|(orient, offset)| (orient, offset, ExifEndian::Little));
120 }
121 [0x4d, 0x4d, 0, 42] => {
122 return Self::locate_orientation_entry::<BigEndian>(&mut reader)
123 .map(|(orient, offset)| (orient, offset, ExifEndian::Big));
124 }
125 _ => {}
126 }
127 None
128 }
129
130 /// Extracted into a helper function to be generic over endianness
131 fn locate_orientation_entry<B>(reader: &mut Cursor<&[u8]>) -> Option<(Self, u64)>
132 where
133 B: byteorder_lite::ByteOrder,
134 {
135 let ifd_offset = reader.read_u32::<B>().ok()?;
136 reader.set_position(u64::from(ifd_offset));
137 let entries = reader.read_u16::<B>().ok()?;
138 for _ in 0..entries {
139 let tag = reader.read_u16::<B>().ok()?;
140 let format = reader.read_u16::<B>().ok()?;
141 let count = reader.read_u32::<B>().ok()?;
142 let value = reader.read_u16::<B>().ok()?;
143 let _padding = reader.read_u16::<B>().ok()?;
144 if tag == 0x112 && format == 3 && count == 1 {
145 let offset = reader.position() - 4; // we've read 4 bytes (2 * u16) past the start of the value
146 let orientation = Self::from_exif(value.min(255) as u8);
147 return orientation.map(|orient| (orient, offset));
148 }
149 }
150 // If we reached this point without returning early, there was no orientation
151 None
152 }
153 }
154
155 #[derive(Debug, Copy, Clone)]
156 enum ExifEndian {
157 Big,
158 Little,
159 }
160
161 #[cfg(all(test, feature = "jpeg"))]
162 mod tests {
163 use crate::{codecs::jpeg::JpegDecoder, ImageDecoder as _};
164
165 // This brings all the items from the parent module into scope,
166 // so you can directly use `add` instead of `super::add`.
167 use super::*;
168
169 const TEST_IMAGE: &[u8] = include_bytes!("../tests/images/jpg/portrait_2.jpg");
170
171 #[test] // This attribute marks the function as a test function.
172 fn test_extraction_and_clearing() {
173 let reader = Cursor::new(TEST_IMAGE);
174 let mut decoder = JpegDecoder::new(reader).expect("Failed to decode test image");
175 let mut exif_chunk = decoder
176 .exif_metadata()
177 .expect("Failed to extract Exif chunk")
178 .expect("No Exif chunk found in test image");
179
180 let orientation = Orientation::from_exif_chunk(&exif_chunk)
181 .expect("Failed to extract orientation from Exif chunk");
182 assert_eq!(orientation, Orientation::FlipHorizontal);
183
184 let orientation = Orientation::remove_from_exif_chunk(&mut exif_chunk)
185 .expect("Failed to remove orientation from Exif chunk");
186 assert_eq!(orientation, Orientation::FlipHorizontal);
187 // Now that the orientation has been cleared, any subsequent extractions should return NoTransforms
188 let orientation = Orientation::from_exif_chunk(&exif_chunk)
189 .expect("Failed to extract orientation from Exif chunk after clearing it");
190 assert_eq!(orientation, Orientation::NoTransforms);
191 }
192 }