image-codecs: header-only PNG pixel model and WebP alpha probes (#778) (#2064)

png_probe::pixel_model reads width, height, bit depth, colour type and tRNS
presence from IHDR and the chunk headers before IDAT without inflating iCCP;
PixelModel::bytes_per_pixel and has_alpha give a caller's pixel size and alpha.
webp_probe::has_alpha reads the VP8X alpha flag, the VP8L alpha_is_used bit,
and treats plain VP8 as opaque. Differential tests compare against WordCraft's
png_chunks as an oracle.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Martin BallandClaude Opus 5.5 authored and GitHub committed 2026-11-17 14:27:53 -05:00
1 parent ea02182945
commit 1928693fbb
2 files changed
+277

No files matched your search

+223
View File
@@ -136,6 +136,93 @@ pub fn color_chunks(b: &[u8]) -> Option<ColorChunks> {
Some(result)
}
/// Most chunks [`pixel_model`] walks before the image data; each chunk is at least 12 bytes.
const MAX_PROBE_CHUNKS: usize = 1 << 16;
/// Pixel model of a PNG, from `IHDR` and the chunk headers before the first `IDAT`.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct PixelModel {
pub width: u32,
pub height: u32,
/// `IHDR` bit depth (1, 2, 4, 8 or 16).
pub bit_depth: u8,
/// `IHDR` colour type (0 grey, 2 RGB, 3 palette, 4 grey+alpha, 6 RGBA).
pub color_type: u8,
/// A `tRNS` chunk precedes the image data; it adds alpha to grey, RGB and palette images.
pub has_trns: bool,
}
impl PixelModel {
/// Channels of the decoded buffer (palette expands to RGB; `tRNS` adds an alpha channel).
pub fn channels(&self) -> u8 {
let base = match self.color_type {
0 => 1,
2 | 3 => 3,
4 => 2,
_ => 4,
};
base + u8::from(self.has_trns && matches!(self.color_type, 0 | 2 | 3))
}
/// Bytes per pixel of the buffer a decoder that expands sub-byte samples to 8 bits gives:
/// `channels * (2 if bit_depth == 16 else 1)`.
pub fn bytes_per_pixel(&self) -> u8 {
self.channels() * if self.bit_depth == 16 { 2 } else { 1 }
}
/// Whether the image has transparency (alpha colour type or `tRNS`).
pub fn has_alpha(&self) -> bool {
matches!(self.color_type, 4 | 6) || self.has_trns
}
}
/// Dimensions, bit depth, colour type and `tRNS` presence without inflating anything (an `iCCP`
/// profile is skipped, not decompressed). Walks at most 65,536 chunk headers and stops at `IDAT`;
/// `IEND` or the end of the input before `IDAT` is an error. Does not validate CRCs.
/// A caller gets its `(width, height, bytes_per_pixel, alpha)` as
/// `(m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha())`.
pub fn pixel_model(b: &[u8]) -> Result<PixelModel, CodecError> {
if !b.starts_with(b"\x89PNG\r\n\x1a\n") {
return Err(err("bad signature"));
}
let be32 = |p: usize| b.get(p..p.checked_add(4)?).and_then(|v| <[u8; 4]>::try_from(v).ok()).map(u32::from_be_bytes);
if be32(8) != Some(13) || b.get(12..16) != Some(b"IHDR") {
return Err(err("missing IHDR"));
}
let ihdr = b.get(16..29).ok_or_else(|| err("truncated IHDR"))?;
let (width, height) = (be32(16).unwrap_or(0), be32(20).unwrap_or(0));
let (bit_depth, color_type) = (ihdr[8], ihdr[9]);
if width == 0 || height == 0 || width > i32::MAX as u32 || height > i32::MAX as u32 {
return Err(err("dimensions out of range"));
}
let depth_ok = match color_type {
0 => matches!(bit_depth, 1 | 2 | 4 | 8 | 16),
3 => matches!(bit_depth, 1 | 2 | 4 | 8),
2 | 4 | 6 => matches!(bit_depth, 8 | 16),
_ => false,
};
if !depth_ok {
return Err(err("invalid IHDR"));
}
let mut has_trns = false;
let mut p = 8usize;
for _ in 0..MAX_PROBE_CHUNKS {
let len = be32(p).ok_or_else(|| err("truncated"))?;
let kind = p.checked_add(4).and_then(|k| b.get(k..k.checked_add(4)?)).ok_or_else(|| err("truncated"))?;
match kind {
b"IDAT" => return Ok(PixelModel { width, height, bit_depth, color_type, has_trns }),
b"IEND" => return Err(err("no image data")),
b"tRNS" => has_trns = true,
_ => {}
}
if len > i32::MAX as u32 {
return Err(err("chunk length out of range"));
}
p = p.checked_add(12).and_then(|q| q.checked_add(len as usize)).ok_or_else(|| err("truncated"))?;
}
Err(CodecError::LimitExceeded("PNG chunk count".into()))
}
#[cfg(test)]
mod tests {
use super::*;
@@ -187,4 +274,140 @@ mod tests {
assert!(!color.srgb);
assert!(color_chunks(b"not png").is_none());
}
/// WordCraft's `png_chunks` (crates/geom/src/picture.rs) as the differential oracle.
fn oracle(bytes: &[u8]) -> Option<(u32, u32, u64, bool)> {
let be = |at: usize| bytes.get(at..at.checked_add(4)?).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(u32::from_be_bytes);
if bytes.get(12..16) != Some(b"IHDR".as_slice()) {
return None;
}
let (width, height) = (be(16)?, be(20)?);
let (depth, color) = (*bytes.get(24)?, *bytes.get(25)?);
let mut trns = false;
let mut at = 8usize;
loop {
let len = usize::try_from(be(at)?).ok()?;
match bytes.get(at.checked_add(4)?..at.checked_add(8)?)? {
b"IDAT" => break,
b"IEND" => return None,
b"tRNS" => trns = true,
_ => {}
}
at = at.checked_add(12)?.checked_add(len)?;
}
let (channels, alpha) = match color {
0 => (1 + u64::from(trns), trns),
2 | 3 => (3 + u64::from(trns), trns),
4 => (2, true),
6 => (4, true),
_ => return None,
};
Some((width, height, channels * if depth == 16 { 2 } else { 1 }, alpha))
}
fn tuple(b: &[u8]) -> Option<(u32, u32, u64, bool)> {
pixel_model(b).ok().map(|m| (m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha()))
}
fn png_with(depth: u8, color: u8, before_idat: &[(&[u8; 4], Vec<u8>)]) -> Vec<u8> {
let mut bytes = b"\x89PNG\r\n\x1a\n".to_vec();
let mut ihdr = Vec::new();
ihdr.extend_from_slice(&5u32.to_be_bytes());
ihdr.extend_from_slice(&7u32.to_be_bytes());
ihdr.extend_from_slice(&[depth, color, 0, 0, 0]);
chunk(&mut bytes, b"IHDR", &ihdr);
for (k, d) in before_idat {
chunk(&mut bytes, k, d);
}
chunk(&mut bytes, b"IDAT", &[1, 2, 3]);
chunk(&mut bytes, b"IEND", &[]);
bytes
}
#[test]
fn pixel_model_matches_oracle_for_every_color_type_depth_and_trns() {
let valid: [(u8, &[u8]); 5] = [(0, &[1, 2, 4, 8, 16]), (2, &[8, 16]), (3, &[1, 2, 4, 8]), (4, &[8, 16]), (6, &[8, 16])];
for (color, depths) in valid {
for &depth in depths {
for trns in [false, true] {
let extra: Vec<(&[u8; 4], Vec<u8>)> = if trns { vec![(b"tRNS", vec![0, 0])] } else { vec![] };
let bytes = png_with(depth, color, &extra);
assert!(tuple(&bytes).is_some(), "color {color} depth {depth}");
assert_eq!(tuple(&bytes), oracle(&bytes), "color {color} depth {depth} trns {trns}");
}
}
}
}
#[test]
fn pixel_model_known_values() {
let m = pixel_model(&png_with(16, 2, &[(b"tRNS", vec![0; 6])])).unwrap();
assert_eq!((m.width, m.height, m.channels(), m.bytes_per_pixel(), m.has_alpha()), (5, 7, 4, 8, true));
let m = pixel_model(&png_with(4, 3, &[])).unwrap();
assert_eq!((m.bytes_per_pixel(), m.has_alpha()), (3, false));
}
#[test]
fn pixel_model_skips_a_huge_iccp_without_inflating() {
let junk = vec![0xAB; 20 << 20];
let bytes = png_with(8, 2, &[(b"iCCP", junk), (b"tRNS", vec![0; 6])]);
assert_eq!(tuple(&bytes), oracle(&bytes));
assert_eq!(tuple(&bytes), Some((5, 7, 4, true)));
}
#[test]
fn pixel_model_malformed_inputs_agree_with_oracle_and_never_panic() {
let full = png_with(8, 6, &[(b"tRNS", vec![0]), (b"gAMA", vec![0; 4])]);
for n in 0..=full.len() {
let cut = &full[..n];
let got = tuple(cut);
// an Err where the oracle answers can only be a stricter header check
if got.is_some() {
assert_eq!(got, oracle(cut), "prefix {n}");
}
}
assert!(pixel_model(&full[..33]).is_err());
// missing IHDR
let mut bad = full.clone();
bad[12..16].copy_from_slice(b"IHDX");
assert!(pixel_model(&bad).is_err() && oracle(&bad).is_none());
// chunk length overflow: a length past the input, then one past i32::MAX
for len in [u32::MAX, i32::MAX as u32, 0x7fff_fff0] {
let mut o = full.clone();
o[33..37].copy_from_slice(&len.to_be_bytes());
assert!(pixel_model(&o).is_err(), "len {len:#x}");
assert_eq!(tuple(&o), oracle(&o));
}
// IEND before IDAT, unknown colour type, zero size, bad signature
let mut iend = png_with(8, 2, &[]);
let at = iend.windows(4).position(|w| w == b"IDAT").unwrap();
iend[at..at + 4].copy_from_slice(b"IEND");
assert!(pixel_model(&iend).is_err() && oracle(&iend).is_none());
assert!(pixel_model(&png_with(8, 5, &[])).is_err());
let mut zero = png_with(8, 2, &[]);
zero[16..20].copy_from_slice(&0u32.to_be_bytes());
assert!(pixel_model(&zero).is_err());
assert!(pixel_model(b"not a png").is_err());
// deterministic pseudo-random corruption
let mut s = 0x9e37_79b9u32;
for _ in 0..2000 {
let mut f = full.clone();
for _ in 0..3 {
s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let i = (s >> 8) as usize % f.len();
f[i] = (s >> 24) as u8;
}
let _ = pixel_model(&f);
}
}
#[test]
fn pixel_model_many_tiny_chunks_and_the_chunk_cap() {
let many: Vec<(&[u8; 4], Vec<u8>)> = (0..10_000).map(|_| (b"tEXt", Vec::new())).chain([(b"tRNS", vec![0])]).collect();
let bytes = png_with(8, 0, &many);
assert_eq!(tuple(&bytes), oracle(&bytes));
assert_eq!(tuple(&bytes), Some((5, 7, 2, true)));
let over: Vec<(&[u8; 4], Vec<u8>)> = (0..MAX_PROBE_CHUNKS + 1).map(|_| (b"tEXt", Vec::new())).collect();
assert!(matches!(pixel_model(&png_with(8, 0, &over)), Err(CodecError::LimitExceeded(_))));
}
}
+54
View File
@@ -32,6 +32,25 @@ pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> {
Ok((w, h, orientation))
}
/// Whether a WebP carries transparency, from the first chunk only (nothing is decoded):
/// `VP8X` flag bit 0x10, `VP8L` `alpha_is_used`, plain `VP8` never.
pub fn has_alpha(bytes: &[u8]) -> Result<bool, CodecError> {
let err = |s: &str| CodecError::malformed(Format::WebP, s);
if bytes.get(..4) != Some(b"RIFF") || bytes.get(8..12) != Some(b"WEBP") {
return Err(err("bad signature"));
}
match bytes.get(12..16) {
Some(b"VP8X") => Ok(bytes.get(20).ok_or_else(|| err("truncated VP8X"))? & 0x10 != 0),
// 0x2f signature byte, then 14+14 size bits, then the alpha_is_used bit (bit 28)
Some(b"VP8L") => match bytes.get(20..25) {
Some([0x2f, a, b, c, d]) => Ok(u32::from_le_bytes([*a, *b, *c, *d]) >> 28 & 1 != 0),
_ => Err(err("bad VP8L header")),
},
Some(b"VP8 ") => Ok(false),
_ => Err(err("no image data")),
}
}
#[cfg(test)]
mod tests {
use super::*;
@@ -71,4 +90,39 @@ mod tests {
bytes.push(0);
assert!(header(&bytes).is_err());
}
#[test]
fn has_alpha_reads_vp8x_vp8l_and_plain_vp8() {
for (layout, want) in [(crate::ChannelLayout::Rgb, false), (crate::ChannelLayout::Rgba, true)] {
let n = layout.channels();
let image = crate::Image::from_u8(2, 3, layout, vec![42; 6 * n]).unwrap();
let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap();
assert_eq!(has_alpha(&bytes).unwrap(), want);
}
let riff = |chunk: &[u8; 4], body: &[u8]| {
let mut v = b"RIFF\0\0\0\0WEBP".to_vec();
v.extend_from_slice(chunk);
v.extend_from_slice(&(body.len() as u32).to_le_bytes());
v.extend_from_slice(body);
v
};
let mut x = [0u8; 10];
assert!(!has_alpha(&riff(b"VP8X", &x)).unwrap());
x[0] = 0x10;
assert!(has_alpha(&riff(b"VP8X", &x)).unwrap());
assert!(!has_alpha(&riff(b"VP8 ", &[0; 10])).unwrap());
assert!(has_alpha(&riff(b"VP8L", &[0x2f, 0, 0, 0, 0x10])).unwrap());
assert!(!has_alpha(&riff(b"VP8L", &[0x2f, 0, 0, 0, 0])).unwrap());
}
#[test]
fn has_alpha_rejects_malformed_prefixes() {
let full = [b"RIFF\0\0\0\0WEBPVP8X\x0a\0\0\0".as_slice(), &[0x10; 10]].concat();
for n in 0..20 {
assert!(has_alpha(&full[..n]).is_err(), "prefix {n}");
}
assert!(has_alpha(&full[..21]).is_ok());
assert!(has_alpha(b"RIFF\0\0\0\0WEBPVP8L\x05\0\0\0\x2e").is_err());
assert!(has_alpha(b"junk").is_err());
}
}