Skip to main content

webpkit_cli/format/
png.rs

1//! PNG input/output via the `png` crate, normalized to RGBA8.
2//!
3//! Reading expands palette / low-bit grayscale and strips 16-bit down to 8-bit,
4//! then converts grayscale / grayscale-alpha / RGB up to RGBA8 so the codec
5//! always sees a uniform buffer. ICC / Exif / XMP metadata is bridged to and
6//! from the WebP `VP8X` container.
7
8use std::borrow::Cow;
9
10use png::{BitDepth, ColorType, Info, Transformations, text_metadata::ITXtChunk};
11use webpkit::lossless::{Dimensions, Image, Metadata, PixelLayout};
12
13use crate::{error::CliError, format::to_rgba8};
14
15/// The iTXt keyword under which XMP travels in a PNG.
16const XMP_KEYWORD: &str = "XML:com.adobe.xmp";
17
18/// Decode a PNG file into an RGBA8 [`Image`], carrying any ICC/Exif/XMP metadata.
19///
20/// # Errors
21///
22/// [`CliError::Format`] if the bytes are not a decodable PNG.
23pub fn read(bytes: &[u8]) -> Result<Image, CliError> {
24    // png 0.18 requires the reader to be `Read + Seek`; `&[u8]` is only `Read`.
25    let mut decoder = png::Decoder::new(std::io::Cursor::new(bytes));
26    decoder.set_transformations(Transformations::EXPAND | Transformations::STRIP_16);
27    let mut reader = decoder
28        .read_info()
29        .map_err(|err| CliError::Format(format!("invalid PNG: {err}")))?;
30    let metadata = extract_metadata(reader.info(), bytes);
31    // png 0.18 returns `None` when the buffer size would overflow `usize`.
32    let buf_size = reader
33        .output_buffer_size()
34        .ok_or_else(|| CliError::Format("PNG output buffer size overflow".to_owned()))?;
35    let mut buf = vec![0_u8; buf_size];
36    let info = reader
37        .next_frame(&mut buf)
38        .map_err(|err| CliError::Format(format!("invalid PNG: {err}")))?;
39    buf.truncate(info.buffer_size());
40
41    if info.bit_depth != BitDepth::Eight {
42        return Err(CliError::Format(format!(
43            "unsupported PNG bit depth {:?} (expected 8-bit after normalization)",
44            info.bit_depth,
45        )));
46    }
47    let rgba = expand_to_rgba8(&buf, info.color_type)?;
48    let dims = Dimensions::new(info.width, info.height)?;
49    let has_alpha = rgba.chunks_exact(4).any(|px| px[3] != 0xff);
50    Ok(Image::from_parts(
51        dims,
52        PixelLayout::Rgba8,
53        rgba,
54        has_alpha,
55        metadata,
56    ))
57}
58
59/// Scan raw PNG chunks for an `eXIf` chunk's payload.
60///
61/// The `png` crate writes `eXIf` but its decoder does not surface it, so this
62/// recovers Exif for the PNG-to-WebP path.
63fn find_exif_chunk(png: &[u8]) -> Option<Vec<u8>> {
64    let mut pos = 8; // skip the 8-byte PNG signature
65    while pos + 8 <= png.len() {
66        let len = u32::from_be_bytes(png[pos..pos + 4].try_into().ok()?) as usize;
67        let kind = &png[pos + 4..pos + 8];
68        let data_start = pos + 8;
69        let data_end = data_start.checked_add(len)?;
70        if data_end.checked_add(4)? > png.len() || kind == b"IEND" {
71            break;
72        }
73        if kind == b"eXIf" {
74            return Some(png[data_start..data_end].to_vec());
75        }
76        pos = data_end + 4; // skip the 4-byte CRC
77    }
78    None
79}
80
81/// Encode an [`Image`] as an 8-bit RGBA PNG file, embedding `metadata`.
82///
83/// # Errors
84///
85/// [`CliError::Format`] if PNG encoding fails.
86pub fn write(image: &Image, metadata: &Metadata) -> Result<Vec<u8>, CliError> {
87    let rgba = to_rgba8(image);
88    let mut info = Info::with_size(image.width(), image.height());
89    info.color_type = ColorType::Rgba;
90    info.bit_depth = BitDepth::Eight;
91    if let Some(icc) = &metadata.icc_profile {
92        info.icc_profile = Some(Cow::Borrowed(icc));
93    }
94    if let Some(exif) = &metadata.exif {
95        info.exif_metadata = Some(Cow::Borrowed(exif));
96    }
97    if let Some(xmp) = &metadata.xmp {
98        let text = String::from_utf8_lossy(xmp).into_owned();
99        info.utf8_text.push(ITXtChunk::new(XMP_KEYWORD, text));
100    }
101
102    let mut out = Vec::new();
103    {
104        let encoder = png::Encoder::with_info(&mut out, info)
105            .map_err(|err| CliError::Format(format!("PNG encode failed: {err}")))?;
106        let mut writer = encoder
107            .write_header()
108            .map_err(|err| CliError::Format(format!("PNG encode failed: {err}")))?;
109        writer
110            .write_image_data(&rgba)
111            .map_err(|err| CliError::Format(format!("PNG encode failed: {err}")))?;
112    }
113    Ok(out)
114}
115
116/// Pull ICC / Exif / XMP out of a decoded PNG's [`Info`] (plus the raw bytes,
117/// for the `eXIf` chunk the `png` decoder skips).
118fn extract_metadata(info: &Info<'_>, png: &[u8]) -> Metadata {
119    let xmp = info.utf8_text.iter().find_map(|chunk| {
120        (chunk.keyword == XMP_KEYWORD)
121            .then(|| chunk.get_text().ok())
122            .flatten()
123            .map(String::into_bytes)
124    });
125    let exif = info
126        .exif_metadata
127        .as_ref()
128        .map(|exif| exif.to_vec())
129        .or_else(|| find_exif_chunk(png));
130    Metadata {
131        icc_profile: info.icc_profile.as_ref().map(|icc| icc.to_vec()),
132        exif,
133        xmp,
134    }
135}
136
137/// Expand an 8-bit PNG frame of any color type to RGBA8.
138fn expand_to_rgba8(buf: &[u8], color: ColorType) -> Result<Vec<u8>, CliError> {
139    let rgba = match color {
140        ColorType::Rgba => buf.to_vec(),
141        ColorType::Rgb => buf
142            .chunks_exact(3)
143            .flat_map(|px| [px[0], px[1], px[2], 0xff])
144            .collect(),
145        ColorType::Grayscale => buf.iter().flat_map(|&g| [g, g, g, 0xff]).collect(),
146        ColorType::GrayscaleAlpha => buf
147            .chunks_exact(2)
148            .flat_map(|px| [px[0], px[0], px[0], px[1]])
149            .collect(),
150        ColorType::Indexed => {
151            return Err(CliError::Format(
152                "indexed PNG was not expanded to a direct color type".to_owned(),
153            ));
154        },
155    };
156    Ok(rgba)
157}
158
159#[cfg(test)]
160mod tests {
161    use webpkit::lossless::{Dimensions, Image, Metadata, PixelLayout};
162
163    use super::{read, write};
164
165    fn image_2x2() -> Image {
166        Image::from_parts(
167            Dimensions::new(2, 2).unwrap(),
168            PixelLayout::Rgba8,
169            (0..16).collect(),
170            true,
171            Metadata::none(),
172        )
173    }
174
175    #[test]
176    fn pixels_round_trip() {
177        let png = write(&image_2x2(), &Metadata::none()).unwrap();
178        let back = read(&png).unwrap();
179        assert_eq!(back.width(), 2);
180        assert_eq!(back.as_bytes(), (0..16).collect::<Vec<u8>>());
181    }
182
183    #[test]
184    fn metadata_round_trips_through_png_chunks() {
185        let meta = Metadata {
186            icc_profile: Some(b"a fake icc profile".to_vec()),
187            exif: Some(b"MM\x00*exif-bytes".to_vec()),
188            xmp: Some(b"<x:xmpmeta/>".to_vec()),
189        };
190        let png = write(&image_2x2(), &meta).unwrap();
191        let back = read(&png).unwrap();
192        assert_eq!(back.metadata().icc_profile, meta.icc_profile);
193        assert_eq!(back.metadata().exif, meta.exif);
194        assert_eq!(back.metadata().xmp, meta.xmp);
195    }
196}