codecs: share image metadata framing and sniffing (#4556)

* codecs: share image metadata framing and sniffing

* codecs: cover BigTIFF and JPEG-LS shared routing parity

* codecs: add unit tests for BMFF probe precedence and sniff fallback
This commit is contained in:
Dylan M. Taylor
2026-11-19 20:36:49 -05:00
committed by GitHub
parent 7c7965989b
commit 8539efc832
2 changed files with 112 additions and 113 deletions
+10 -94
View File
@@ -77,46 +77,21 @@ pub enum ChromaSubsampling {
S420,
}
const XMP_NS: &[u8] = b"http://ns.adobe.com/xap/1.0/\0";
/// The APP segments [`encode_jpeg`] writes for `meta` (marker byte, payload): JFIF density, EXIF,
/// XMP and the ICC profile in chunks, in that order.
pub(crate) fn jpeg_app_segments(meta: &EncodeMeta) -> Result<Vec<(u8, Vec<u8>)>> {
let mut segs: Vec<(u8, Vec<u8>)> = Vec::new();
let ppi = meta.ppi.filter(|p| *p > 0).map_or([0u8, 0, 1, 0, 1], |p| {
let [hi, lo] = p.to_be_bytes();
[1, hi, lo, hi, lo]
});
segs.push((0xE0, [&b"JFIF\0\x01\x02"[..], &ppi, &[0, 0]].concat()));
if let Some(exif) = meta.exif {
if exif.len() > 65_527 {
return Err(Error::Encode("EXIF larger than one APP1 segment (64 KiB)".into()));
}
segs.push((0xE1, [&b"Exif\0\0"[..], exif].concat()));
}
if let Some(xmp) = meta.xmp {
segs.push((0xE1, xmp_segment(xmp)?));
}
if let Some(icc) = meta.icc {
// ICC.1 Annex B.4: "ICC_PROFILE\0", 1-based chunk number, chunk count
let chunks: Vec<&[u8]> = icc.chunks(65_519).collect();
if chunks.len() > 255 {
return Err(Error::Encode("ICC profile too large for JPEG".into()));
}
for (i, c) in chunks.iter().enumerate() {
segs.push((0xE2, [&b"ICC_PROFILE\0"[..], &[i as u8 + 1, chunks.len() as u8], c].concat()));
}
}
Ok(segs)
craft_image_codecs::raw_metadata::jpeg_segments(craft_image_codecs::raw_metadata::JpegMetadata {
exif: meta.exif,
xmp: meta.xmp,
icc: meta.icc,
ppi: meta.ppi,
})
.map_err(|e| Error::Encode(e.to_string()))
}
/// An APP1 XMP payload (namespace + packet), refusing packets larger than one segment.
pub(crate) fn xmp_segment(xmp: &str) -> Result<Vec<u8>> {
let seg = [XMP_NS, xmp.as_bytes()].concat();
if seg.len() > 65_533 {
return Err(Error::Encode("XMP larger than one APP1 segment (extended XMP not supported)".into()));
}
Ok(seg)
craft_image_codecs::raw_metadata::jpeg_xmp(xmp).map_err(|e| Error::Encode(e.to_string()))
}
/// Encode baseline JPEG (8-bit; alpha is dropped). `quality` 1..=100.
@@ -174,29 +149,11 @@ pub fn encode_png(img: &EncodeImage, meta: &EncodeMeta) -> Result<Vec<u8>> {
let ic_opts = craft_image_codecs::EncodeOptions { png_compression: craft_image_codecs::PngCompression::Fast, ..Default::default() };
let mut out = craft_image_codecs::encode(&ic_img, craft_image_codecs::Format::Png, &ic_opts).map_err(|e| Error::Encode(e.to_string()))?;
if let Some(exif) = meta.exif {
replace_png_exif_chunk(&mut out, exif);
craft_image_codecs::raw_metadata::replace_png_exif(&mut out, exif).map_err(|e| Error::Encode(e.to_string()))?;
}
Ok(out)
}
/// Replace the `eXIf` chunk in an encoded PNG so caller-supplied EXIF (including non-1
/// orientation tags) is preserved verbatim.
fn replace_png_exif_chunk(png: &mut Vec<u8>, exif: &[u8]) {
let mut p = 8usize;
while let Some(len_bytes) = png.get(p..p + 4) {
let len = u32::from_be_bytes([len_bytes[0], len_bytes[1], len_bytes[2], len_bytes[3]]) as usize;
let end = p.saturating_add(12).saturating_add(len);
if end > png.len() {
break;
}
if png.get(p + 4..p + 8) == Some(b"eXIf") {
png.splice(p..end, png_chunk(*b"eXIf", exif));
return;
}
p = end;
}
}
/// TIFF compression.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
pub enum TiffCompression {
@@ -251,36 +208,11 @@ pub fn encode_webp_lossless(img: &EncodeImage, meta: &EncodeMeta) -> Result<Vec<
let ic_opts = craft_image_codecs::EncodeOptions { webp_lossless: true, ..Default::default() };
let mut out = craft_image_codecs::encode(&ic_img, craft_image_codecs::Format::WebP, &ic_opts).map_err(|e| Error::Encode(e.to_string()))?;
if let Some(exif) = meta.exif {
replace_webp_exif_chunk(&mut out, exif);
craft_image_codecs::raw_metadata::replace_webp_exif(&mut out, exif).map_err(|e| Error::Encode(e.to_string()))?;
}
Ok(out)
}
/// Replace the `EXIF` RIFF chunk payload in a WebP file so caller-supplied EXIF (including
/// non-1 orientation tags) is preserved verbatim.
fn replace_webp_exif_chunk(webp: &mut Vec<u8>, exif: &[u8]) {
let mut p = 12usize;
while let Some(h) = webp.get(p..p.saturating_add(8)) {
let size = u32::from_le_bytes([h[4], h[5], h[6], h[7]]) as usize;
let end = p.saturating_add(8).saturating_add(size);
let padded_end = end.saturating_add(size & 1);
if &h[0..4] == b"EXIF" && padded_end <= webp.len() {
let mut replacement = Vec::with_capacity(8 + exif.len() + (exif.len() & 1));
replacement.extend_from_slice(b"EXIF");
replacement.extend_from_slice(&(exif.len() as u32).to_le_bytes());
replacement.extend_from_slice(exif);
if exif.len() & 1 == 1 {
replacement.push(0);
}
webp.splice(p..padded_end, replacement);
let riff_size = (webp.len().saturating_sub(8)) as u32;
webp[4..8].copy_from_slice(&riff_size.to_le_bytes());
return;
}
p = padded_end;
}
}
/// Encode AVIF (sRGB, 4:4:4, 10-bit AV1) with `ravif` (rav1e). 8-bit samples are widened by the
/// encoder; 16-bit samples keep 10 bits of precision (BT.601 full-range YCbCr computed here).
/// `quality` 1..=100, `speed` 1 (slow) ..= 10. EXIF is embedded; ICC is not supported by the muxer
@@ -410,22 +342,6 @@ pub fn encode_png_pq(width: u32, height: u32, rgb: &[f32], meta: &EncodeMeta) ->
craft_image_codecs::encode_png_pq(&image, &options).map_err(|e| Error::Encode(e.to_string()))
}
fn png_chunk(kind: [u8; 4], data: &[u8]) -> Vec<u8> {
let mut out = Vec::with_capacity(12 + data.len());
out.extend_from_slice(&(data.len() as u32).to_be_bytes());
out.extend_from_slice(&kind);
out.extend_from_slice(data);
let mut crc = 0xFFFF_FFFFu32;
for &b in &out[4..] {
crc ^= u32::from(b);
for _ in 0..8 {
crc = if crc & 1 != 0 { (crc >> 1) ^ 0xEDB8_8320 } else { crc >> 1 };
}
}
out.extend_from_slice(&(!crc).to_be_bytes());
out
}
#[cfg(test)]
mod hlg_tests {
use super::*;
+102 -19
View File
@@ -95,21 +95,6 @@ pub fn sniff(b: &[u8]) -> Option<Format> {
if b.len() < 4 {
return None;
}
if b.starts_with(&[0xFF, 0xD8, 0xFF]) {
return Some(Format::Jpeg);
}
if b.starts_with(b"\x89PNG\r\n\x1a\n") {
return Some(Format::Png);
}
if b.starts_with(b"GIF87a") || b.starts_with(b"GIF89a") {
return Some(Format::Gif);
}
if b.len() >= 12 && &b[0..4] == b"RIFF" && &b[8..12] == b"WEBP" {
return Some(Format::WebP);
}
if b.starts_with(&[0xFF, 0x0A]) || b.starts_with(&[0, 0, 0, 0x0C, b'J', b'X', b'L', b' ', 0x0D, 0x0A, 0x87, 0x0A]) {
return Some(Format::Jxl);
}
if b.starts_with(b"8BPS") && b.len() >= 6 && matches!(u16::from_be_bytes([b[4], b[5]]), 1 | 2) {
return Some(Format::Psd);
}
@@ -129,13 +114,18 @@ pub fn sniff(b: &[u8]) -> Option<Format> {
if b.starts_with(b"II*\0") || b.starts_with(b"MM\0*") {
return Some(if craft_image_codecs::legacy_tiff_raw_hint(b) { Format::RawTiffLike } else { Format::Tiff });
}
if b.starts_with(b"II+\0") || b.starts_with(b"MM\0+") {
return Some(Format::Tiff);
}
if craft_image_codecs::bmp_probe::is_supported_header(b) {
return Some(Format::Bmp);
}
None
match craft_image_codecs::detect(b) {
Some(craft_image_codecs::Format::Jpeg | craft_image_codecs::Format::JpegLs) => Some(Format::Jpeg),
Some(craft_image_codecs::Format::Png) => Some(Format::Png),
Some(craft_image_codecs::Format::Gif) => Some(Format::Gif),
Some(craft_image_codecs::Format::WebP) => Some(Format::WebP),
Some(craft_image_codecs::Format::Jxl) => Some(Format::Jxl),
Some(craft_image_codecs::Format::Tiff) => Some(Format::Tiff),
_ => None,
}
}
fn sniff_bmff(b: &[u8]) -> Option<Format> {
@@ -277,6 +267,14 @@ mod tests {
assert_eq!(sniff(b""), None);
}
#[test]
fn shared_detection_keeps_bigtiff_and_jpeg_ls_routing() {
for header in [b"II+\0".as_slice(), b"MM\0+".as_slice()] {
assert_eq!(sniff(header), Some(Format::Tiff));
}
assert_eq!(sniff(&[0xff, 0xd8, 0xff, 0xf7, 0, 2]), Some(Format::Jpeg));
}
#[test]
fn dng_detected() {
// II*, IFD at 8 with a single DNGVersion entry.
@@ -323,4 +321,89 @@ mod tests {
raw[38..42].copy_from_slice(b"TEST");
assert_eq!(sniff(&raw), Some(Format::Tiff));
}
fn ftyp_box(size: Option<u32>, major: &[u8; 4], compatible: &[&[u8; 4]]) -> Vec<u8> {
let box_len = size.unwrap_or((16 + compatible.len() * 4) as u32);
let mut b = Vec::with_capacity(16 + compatible.len() * 4);
b.extend_from_slice(&box_len.to_be_bytes());
b.extend_from_slice(b"ftyp");
b.extend_from_slice(major);
b.extend_from_slice(&0_u32.to_be_bytes());
for brand in compatible {
b.extend_from_slice(*brand);
}
b
}
#[test]
fn bmff_probe_precedence_cr3_jxl_avif_heif() {
// CR3 (`crx `) wins over JXL, AVIF, and HEIF regardless of brand position.
assert_eq!(sniff(&ftyp_box(None, b"crx ", &[b"jxl ", b"avif", b"heic", b"mif1"])), Some(Format::RawOther));
assert_eq!(sniff(&ftyp_box(None, b"mif1", &[b"heic", b"avif", b"jxl ", b"crx "])), Some(Format::RawOther));
assert_eq!(sniff(&ftyp_box(None, b"avif", &[b"crx "])), Some(Format::RawOther));
// JXL (`jxl `) wins over AVIF and HEIF regardless of brand position.
assert_eq!(sniff(&ftyp_box(None, b"jxl ", &[b"avif", b"avis", b"heic", b"mif1"])), Some(Format::Jxl));
assert_eq!(sniff(&ftyp_box(None, b"avif", &[b"jxl "])), Some(Format::Jxl));
assert_eq!(sniff(&ftyp_box(None, b"mif1", &[b"jxl "])), Some(Format::Jxl));
// AVIF (`avif` / `avis`) wins over all HEIF brands regardless of brand position.
let heif_brands: [&[u8; 4]; 10] = [b"heic", b"heix", b"hevc", b"hevx", b"heim", b"heis", b"hevm", b"hevs", b"mif1", b"msf1"];
for heif in heif_brands {
assert_eq!(sniff(&ftyp_box(None, b"avif", &[heif])), Some(Format::Avif));
assert_eq!(sniff(&ftyp_box(None, b"avis", &[heif])), Some(Format::Avif));
assert_eq!(sniff(&ftyp_box(None, heif, &[b"avif"])), Some(Format::Avif));
assert_eq!(sniff(&ftyp_box(None, heif, &[b"avis"])), Some(Format::Avif));
// Without higher-precedence brands, every HEIF brand sniffs as Heif (major or compatible).
assert_eq!(sniff(&ftyp_box(None, heif, &[b"miaf"])), Some(Format::Heif));
assert_eq!(sniff(&ftyp_box(None, b"isom", &[heif])), Some(Format::Heif));
}
// Unrecognised BMFF brands return None rather than falling through.
assert_eq!(sniff(&ftyp_box(None, b"isom", &[b"iso2", b"mp41"])), None);
}
#[test]
fn bmff_ftyp_box_bounds_and_truncation() {
// Box size stops compatible-brand scanning at the ftyp boundary.
let bounded = ftyp_box(Some(16), b"heic", &[b"crx ", b"avif"]);
assert_eq!(sniff(&bounded), Some(Format::Heif));
// Box sizes smaller than 12 clamp to 12: major brand is still read, trailing bytes are not.
for small in [0_u32, 8, 11] {
let clamped = ftyp_box(Some(small), b"avif", &[b"crx "]);
assert_eq!(sniff(&clamped), Some(Format::Avif));
}
// Declared box size larger than the buffer still scans available compatible brands.
let truncated_with_compat = ftyp_box(Some(64), b"mif1", &[b"avif"]);
assert_eq!(sniff(&truncated_with_compat), Some(Format::Avif));
// Truncated before the 12-byte ftyp major brand returns None.
let too_short = ftyp_box(None, b"heic", &[]);
assert_eq!(sniff(&too_short[..11]), None);
}
#[test]
fn jxl_and_detector_fallback_sniffing() {
// JXL ISO-BMFF signature box (`JXL ` box, not `ftyp`) falls through to shared detector.
let mut jxl_container = b"\x00\x00\x00\x0CJXL \r\n\x87\n".to_vec();
assert_eq!(sniff(&jxl_container), Some(Format::Jxl));
jxl_container.extend_from_slice(&ftyp_box(None, b"jxl ", &[b"jxl "]));
assert_eq!(sniff(&jxl_container), Some(Format::Jxl));
// Bare JXL codestream and standalone `ftypjxl ` box both sniff as Jxl.
assert_eq!(sniff(&[0xFF, 0x0A, 0x00, 0x00]), Some(Format::Jxl));
assert_eq!(sniff(&ftyp_box(None, b"jxl ", &[])), Some(Format::Jxl));
// Shared detector fallback for standard raster containers and non-raw TIFF.
assert_eq!(sniff(b"\xFF\xD8\xFF\xE0\0\x10JFIF"), Some(Format::Jpeg));
assert_eq!(sniff(b"\x89PNG\r\n\x1a\n\0\0\0\rIHDR"), Some(Format::Png));
assert_eq!(sniff(b"GIF87a\x01\0\x01\0\0\0\0"), Some(Format::Gif));
assert_eq!(sniff(b"RIFF\x10\0\0\0WEBPVP8 "), Some(Format::WebP));
assert_eq!(sniff(b"II*\0\x08\0\0\0\0\0"), Some(Format::Tiff));
assert_eq!(sniff(b"MM\0*\0\0\0\x08\0\0"), Some(Format::Tiff));
assert_eq!(sniff(b"unknown-header"), None);
}
}