From ff61266d6337abc59285dd3a6369b23ef0b445a0 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 12:38:57 +0100 Subject: [PATCH 01/13] craft-audio: QOA (Quite OK Audio) decoder and encoder Adds the qoa module behind the qoa, qoa-decode and qoa-encode features: whole .qoa files, 16-bit, 1 to 8 channels. Streaming files are unsupported. An ffmpeg oracle test checks that ffmpeg decodes our files to exactly the samples our decoder returns. Closes #1541 --- crates/audio/Cargo.toml | 8 + crates/audio/src/lib.rs | 5 +- crates/audio/src/qoa.rs | 411 +++++++++++++++++++++++++++++++ crates/audio/tests/qoa_oracle.rs | 67 +++++ 4 files changed, 490 insertions(+), 1 deletion(-) create mode 100644 crates/audio/src/qoa.rs create mode 100644 crates/audio/tests/qoa_oracle.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index c411a0357..645246130 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -38,6 +38,10 @@ aac-decode = ["craft-media/bitstream"] # The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`. aac-encode = ["craft-media/bitstream", "craft-media/isobmff"] opus-decode = [] +# QOA (Quite OK Audio) files: decoder and encoder in the `qoa` module, each on its own. +qoa = ["qoa-decode", "qoa-encode"] +qoa-decode = [] +qoa-encode = [] opus-encode = [] ac3-decode = ["craft-media/bitstream"] mpa-decode = ["craft-media/bitstream"] @@ -84,6 +88,10 @@ required-features = ["decode", "lossless-encode", "peaks"] name = "codecs" required-features = ["decode", "encode"] +[[test]] +name = "qoa_oracle" +required-features = ["qoa"] + [[example]] name = "info" required-features = ["decode"] diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..d825b4a78 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -27,7 +27,8 @@ //! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`, //! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and //! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] -//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder). +//! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-encode`: the packet encoder), [`qoa`] +//! (`qoa-decode`, `qoa-encode`: whole QOA files). //! //! The shared types below build with no features. @@ -49,6 +50,8 @@ pub mod opus; mod pcm; #[cfg(feature = "peaks")] pub mod peaks; +#[cfg(any(feature = "qoa-decode", feature = "qoa-encode"))] +pub mod qoa; #[cfg(feature = "decode-native")] mod read; #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))] diff --git a/crates/audio/src/qoa.rs b/crates/audio/src/qoa.rs new file mode 100644 index 000000000..a04430137 --- /dev/null +++ b/crates/audio/src/qoa.rs @@ -0,0 +1,411 @@ +//! QOA ("Quite OK Audio"): a decoder (feature `qoa-decode`) and an encoder (feature `qoa-encode`) +//! for whole `.qoa` files, 16-bit, 1 to 8 channels. +//! +//! Written from the published QOA specification (qoaformat.org). A file is an 8-byte header (the +//! magic `qoaf` and the number of samples per channel) followed by frames of up to 5120 samples +//! per channel. Each frame starts with its channel count, sample rate, sample count and size, then +//! the state of one 4-tap sign-sign LMS predictor per channel, then 64-bit slices of 20 samples: +//! a 4-bit scale factor and twenty 3-bit quantised residuals, the channels interleaved slice by +//! slice. +//! +//! Streaming files (a sample count of 0 in the header) are not supported. +//! Samples are `i16`, one `Vec` per channel. + +#[cfg(feature = "qoa-decode")] +const MAX_FRAME_SAMPLES: usize = 5120; +const SLICE_SAMPLES: usize = 20; +const LMS_LEN: usize = 4; +const MAGIC: &[u8; 4] = b"qoaf"; +/// The most channels a file may have. +pub const MAX_CHANNELS: usize = 8; + +/// `dequant[scale factor][quantised residual]`: `round(round((sf + 1)^2.75) * [0.75, -0.75, 2.5, +/// -2.5, 4.5, -4.5, 7, -7])`. +const DEQUANT: [[i32; 8]; 16] = [ + [1, -1, 3, -3, 5, -5, 7, -7], + [5, -5, 18, -18, 32, -32, 49, -49], + [16, -16, 53, -53, 95, -95, 147, -147], + [34, -34, 113, -113, 203, -203, 315, -315], + [63, -63, 210, -210, 378, -378, 588, -588], + [104, -104, 345, -345, 621, -621, 966, -966], + [158, -158, 528, -528, 950, -950, 1477, -1477], + [228, -228, 760, -760, 1368, -1368, 2128, -2128], + [316, -316, 1053, -1053, 1895, -1895, 2947, -2947], + [422, -422, 1405, -1405, 2529, -2529, 3934, -3934], + [548, -548, 1828, -1828, 3290, -3290, 5117, -5117], + [696, -696, 2320, -2320, 4176, -4176, 6496, -6496], + [868, -868, 2893, -2893, 5207, -5207, 8099, -8099], + [1064, -1064, 3548, -3548, 6386, -6386, 9933, -9933], + [1286, -1286, 4288, -4288, 7718, -7718, 12005, -12005], + [1536, -1536, 5120, -5120, 9216, -9216, 14336, -14336], +]; + +/// What went wrong reading or writing a QOA file. +#[non_exhaustive] +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + /// The input is not a QOA file, or is damaged or truncated. + #[error("malformed QOA: {0}")] + Malformed(&'static str), + /// A valid file this module does not handle (a streaming file). + #[error("unsupported QOA: {0}")] + Unsupported(&'static str), + /// The samples or settings given to the encoder cannot be written as QOA. + #[error("QOA cannot encode: {0}")] + InvalidInput(&'static str), +} + +/// A decoded file. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Audio { + /// Sample rate in Hz (1 to 16 777 215). + pub sample_rate: u32, + /// One `Vec` of samples per channel, all the same length. + pub channels: Vec>, +} + +/// The predictor: the last four samples and four weights. +#[derive(Clone, Copy)] +struct Lms { + history: [i32; LMS_LEN], + weights: [i32; LMS_LEN], +} + +impl Lms { + fn new() -> Self { + Lms { history: [0; LMS_LEN], weights: [0, 0, -(1 << 13), 1 << 14] } + } + + fn predict(&self) -> i32 { + let mut p = 0i32; + for i in 0..LMS_LEN { + p = p.wrapping_add(self.weights[i].wrapping_mul(self.history[i])); + } + p >> 13 + } + + fn update(&mut self, sample: i32, residual: i32) { + let delta = residual >> 4; + for i in 0..LMS_LEN { + self.weights[i] += if self.history[i] < 0 { -delta } else { delta }; + } + self.history.copy_within(1.., 0); + self.history[LMS_LEN - 1] = sample; + } +} + +fn clamp16(v: i32) -> i32 { + v.clamp(-32768, 32767) +} + +#[cfg(feature = "qoa-decode")] +mod decode { + use super::{Audio, DEQUANT, Error, LMS_LEN, Lms, MAGIC, MAX_CHANNELS, MAX_FRAME_SAMPLES, SLICE_SAMPLES, clamp16}; + + fn be16(b: &[u8], i: usize) -> u16 { + u16::from_be_bytes([b[i], b[i + 1]]) + } + + /// Decode a whole `.qoa` file. + /// + /// The declared length is checked against the input before anything is allocated: a slice of + /// 8 bytes holds at most 20 samples, so a file cannot declare more samples than that. + pub fn decode(bytes: &[u8]) -> Result { + if bytes.len() < 8 || &bytes[..4] != MAGIC { + return Err(Error::Malformed("missing the qoaf magic")); + } + let total = u32::from_be_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]) as usize; + if total == 0 { + return Err(Error::Unsupported("streaming files (a sample count of 0)")); + } + if bytes.len() < 16 { + return Err(Error::Malformed("truncated frame header")); + } + let channels = usize::from(bytes[8]); + let sample_rate = u32::from_be_bytes([0, bytes[9], bytes[10], bytes[11]]); + if channels == 0 || channels > MAX_CHANNELS || sample_rate == 0 { + return Err(Error::Malformed("bad channel count or sample rate")); + } + // 8 bytes (20 samples) per channel at the very least, plus the frame headers. + let room = (bytes.len() - 8) / (8 * channels) * SLICE_SAMPLES; + if total > room { + return Err(Error::Malformed("the file is too short for its declared length")); + } + let mut out: Vec> = Vec::new(); + for _ in 0..channels { + let mut v = Vec::new(); + v.try_reserve_exact(total).map_err(|_| Error::Malformed("too many samples"))?; + out.push(v); + } + let mut pos = 8; + let mut done = 0usize; + while done < total { + let head = bytes.get(pos..pos + 8).ok_or(Error::Malformed("truncated frame header"))?; + let rate = u32::from_be_bytes([0, head[1], head[2], head[3]]); + if usize::from(head[0]) != channels || rate != sample_rate { + return Err(Error::Malformed("the channel count or sample rate changes between frames")); + } + let samples = usize::from(be16(head, 4)); + let size = usize::from(be16(head, 6)); + let slices = samples.div_ceil(SLICE_SAMPLES); + if samples == 0 || samples > MAX_FRAME_SAMPLES || samples > total - done { + return Err(Error::Malformed("bad frame sample count")); + } + if size != 8 + 16 * channels + 8 * slices * channels { + return Err(Error::Malformed("frame size does not match its sample count")); + } + let frame = bytes.get(pos..pos + size).ok_or(Error::Malformed("truncated frame"))?; + let mut lms = [Lms::new(); MAX_CHANNELS]; + for (c, state) in lms.iter_mut().take(channels).enumerate() { + let at = 8 + c * 16; + for i in 0..LMS_LEN { + state.history[i] = i32::from(be16(frame, at + 2 * i) as i16); + state.weights[i] = i32::from(be16(frame, at + 8 + 2 * i) as i16); + } + } + let mut at = 8 + 16 * channels; + for s in 0..slices { + let n = (samples - s * SLICE_SAMPLES).min(SLICE_SAMPLES); + for (c, state) in lms.iter_mut().take(channels).enumerate() { + let mut slice = u64::from_be_bytes([ + frame[at], + frame[at + 1], + frame[at + 2], + frame[at + 3], + frame[at + 4], + frame[at + 5], + frame[at + 6], + frame[at + 7], + ]); + at += 8; + let table = &DEQUANT[(slice >> 60) as usize & 15]; + for _ in 0..n { + let dequantised = table[(slice >> 57) as usize & 7]; + slice <<= 3; + let sample = clamp16(state.predict() + dequantised); + out[c].push(sample as i16); + state.update(sample, dequantised); + } + } + } + pos += size; + done += samples; + } + Ok(Audio { sample_rate, channels: out }) + } +} +#[cfg(feature = "qoa-decode")] +pub use decode::decode; + +#[cfg(feature = "qoa-encode")] +mod encode { + use super::{DEQUANT, Error, Lms, MAGIC, MAX_CHANNELS, SLICE_SAMPLES, clamp16}; + + /// The quantised residual (0..8) whose dequantised value is nearest `residual`. + fn quantise(table: &[i32; 8], residual: i32) -> usize { + let mut best = 0; + let mut best_err = i64::MAX; + for (q, &d) in table.iter().enumerate() { + let e = i64::from(residual - d).pow(2); + if e < best_err { + best = q; + best_err = e; + } + } + best + } + + /// Encode one slice of one channel with every scale factor and keep the one with the least + /// squared error. Returns the 64-bit slice; `lms` is advanced to the chosen result. + fn encode_slice(lms: &mut Lms, samples: &[i16]) -> u64 { + let mut best: Option<(i64, u64, Lms)> = None; + for (sf, table) in DEQUANT.iter().enumerate() { + let mut trial = *lms; + let mut slice = sf as u64; + let mut err = 0i64; + for k in 0..SLICE_SAMPLES { + let mut q = 0; + if let Some(&s) = samples.get(k) { + let predicted = trial.predict(); + q = quantise(table, i32::from(s) - predicted); + let sample = clamp16(predicted + table[q]); + err += i64::from(i32::from(s) - sample).pow(2); + trial.update(sample, table[q]); + } + slice = slice << 3 | q as u64; + } + // 4 + 60 bits are in `slice`; the scale factor belongs on top. + let slice = slice & ((1 << 60) - 1) | (sf as u64) << 60; + if best.as_ref().is_none_or(|b| err < b.0) { + best = Some((err, slice, trial)); + } + } + match best { + Some((_, slice, state)) => { + *lms = state; + slice + } + None => 0, + } + } + + /// Encode `channels` (one `Vec` of samples per channel, all the same length) as a `.qoa` file. + pub fn encode(sample_rate: u32, channels: &[Vec]) -> Result, Error> { + let n = channels.len(); + if n == 0 || n > MAX_CHANNELS { + return Err(Error::InvalidInput("QOA stores 1 to 8 channels")); + } + if sample_rate == 0 || sample_rate > 0x00ff_ffff { + return Err(Error::InvalidInput("the sample rate must be 1 to 16777215 Hz")); + } + let total = channels[0].len(); + if channels.iter().any(|c| c.len() != total) { + return Err(Error::InvalidInput("the channels differ in length")); + } + let total32 = u32::try_from(total).map_err(|_| Error::InvalidInput("too many samples"))?; + if total == 0 { + return Err(Error::InvalidInput("QOA cannot store an empty file")); + } + let mut out = Vec::with_capacity(8 + total * n / 2); + out.extend_from_slice(MAGIC); + out.extend_from_slice(&total32.to_be_bytes()); + let mut lms = [Lms::new(); MAX_CHANNELS]; + let mut start = 0; + while start < total { + let len = (total - start).min(5120); + let slices = len.div_ceil(SLICE_SAMPLES); + let size = 8 + 16 * n + 8 * slices * n; + out.push(n as u8); + out.extend_from_slice(&sample_rate.to_be_bytes()[1..]); + out.extend_from_slice(&(len as u16).to_be_bytes()); + out.extend_from_slice(&(size as u16).to_be_bytes()); + // The state a frame starts from is written as 16-bit values, so the predictor + // continues from exactly what a decoder reads. + for state in lms.iter_mut().take(n) { + for v in state.history.iter_mut().chain(state.weights.iter_mut()) { + *v = i32::from(*v as i16); + out.extend_from_slice(&(*v as i16).to_be_bytes()); + } + } + for s in 0..slices { + let from = start + s * SLICE_SAMPLES; + let to = (from + SLICE_SAMPLES).min(start + len); + for (c, state) in lms.iter_mut().take(n).enumerate() { + out.extend_from_slice(&encode_slice(state, &channels[c][from..to]).to_be_bytes()); + } + } + start += len; + } + Ok(out) + } +} +#[cfg(feature = "qoa-encode")] +pub use encode::encode; + +#[cfg(all(test, feature = "qoa-decode", feature = "qoa-encode"))] +mod tests { + use super::*; + + fn tone(frames: usize, ch: usize) -> Vec> { + (0..ch) + .map(|c| (0..frames).map(|i| (((i as f64) * (0.03 + 0.01 * c as f64)).sin() * 12000.0 + ((i * 7919) % 200) as f64) as i16).collect()) + .collect() + } + + fn snr(a: &[i16], b: &[i16]) -> f64 { + let (mut s, mut e) = (0f64, 0f64); + for (&x, &y) in a.iter().zip(b) { + s += f64::from(x).powi(2); + e += (f64::from(x) - f64::from(y)).powi(2); + } + 10.0 * (s / e.max(1.0)).log10() + } + + #[test] + fn dequant_table_matches_its_formula() { + for (sf, row) in DEQUANT.iter().enumerate() { + let scale = ((sf as f64 + 1.0).powf(2.75)).round(); + for (q, base) in [0.75, -0.75, 2.5, -2.5, 4.5, -4.5, 7.0, -7.0].into_iter().enumerate() { + assert_eq!(f64::from(row[q]), (scale * base).round(), "sf {sf} q {q}"); + } + } + } + + #[test] + fn round_trips_with_a_good_signal_to_noise_ratio() { + for (frames, ch) in [(1, 1), (19, 2), (20, 1), (21, 2), (5120, 1), (5121, 2), (12_345, 8)] { + let src = tone(frames, ch); + let bytes = encode(44_100, &src).unwrap(); + let back = decode(&bytes).unwrap(); + assert_eq!((back.sample_rate, back.channels.len(), back.channels[0].len()), (44_100, ch, frames)); + if frames > 1000 { + for (c, (a, b)) in src.iter().zip(&back.channels).enumerate() { + assert!(snr(a, b) > 25.0, "{frames}x{ch} channel {c}"); + } + } + } + } + + #[test] + fn silence_and_full_scale_extremes_survive() { + let silent = vec![vec![0i16; 3000]]; + // No residual value is zero, so silence decodes to a tiny residue, never exactly 0. + let quiet = decode(&encode(8000, &silent).unwrap()).unwrap(); + assert!(quiet.channels[0].iter().all(|&s| s.abs() <= 2), "silence stays within 2 LSB"); + let square: Vec = (0..4000).map(|i| if (i / 50) % 2 == 0 { i16::MAX } else { i16::MIN }).collect(); + let back = decode(&encode(48_000, std::slice::from_ref(&square)).unwrap()).unwrap(); + assert_eq!(back.channels[0].len(), square.len()); + } + + #[test] + fn the_file_has_the_documented_layout() { + let bytes = encode(48_000, &tone(100, 2)).unwrap(); + assert_eq!(&bytes[..4], b"qoaf"); + assert_eq!(u32::from_be_bytes(bytes[4..8].try_into().unwrap()), 100); + assert_eq!(bytes[8], 2); + assert_eq!(&bytes[9..12], &48_000u32.to_be_bytes()[1..]); + assert_eq!(u16::from_be_bytes([bytes[12], bytes[13]]), 100); + // 8 header + 2 channels * 16 state + 5 slices * 2 channels * 8 + assert_eq!(usize::from(u16::from_be_bytes([bytes[14], bytes[15]])), 8 + 32 + 80); + assert_eq!(bytes.len(), 8 + 8 + 32 + 80); + // The first frame starts from the specified predictor state. + assert_eq!(&bytes[16 + 8..16 + 16], &[0, 0, 0, 0, 0xe0, 0, 0x40, 0]); + } + + #[test] + fn invalid_input_to_the_encoder_is_refused() { + assert!(encode(44_100, &[]).is_err()); + assert!(encode(0, &[vec![0; 10]]).is_err()); + assert!(encode(1 << 24, &[vec![0; 10]]).is_err()); + assert!(encode(44_100, &[vec![0; 10], vec![0; 9]]).is_err()); + assert!(encode(44_100, &[vec![]]).is_err()); + assert!(encode(44_100, &vec![vec![0; 10]; 9]).is_err()); + } + + #[test] + fn hostile_input_is_an_error_not_a_panic() { + let good = encode(44_100, &tone(6000, 2)).unwrap(); + for len in 0..good.len().min(600) { + let _ = decode(&good[..len]); + } + assert!(decode(&good[..good.len() - 1]).is_err()); + // A header that declares more samples than the bytes can hold. + let mut huge = good.clone(); + huge[4..8].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&huge).is_err()); + // A streaming file, and a frame whose size field lies. + let mut streaming = good.clone(); + streaming[4..8].fill(0); + assert_eq!(decode(&streaming), Err(Error::Unsupported("streaming files (a sample count of 0)"))); + let mut lying = good.clone(); + lying[14] ^= 1; + assert!(decode(&lying).is_err()); + let mut zero_rate = good.clone(); + zero_rate[9..12].fill(0); + assert!(decode(&zero_rate).is_err()); + let mut changed = good; + let second = 8 + usize::from(u16::from_be_bytes([changed[14], changed[15]])); + changed[second] = 1; + assert!(decode(&changed).is_err()); + } +} diff --git a/crates/audio/tests/qoa_oracle.rs b/crates/audio/tests/qoa_oracle.rs new file mode 100644 index 000000000..cf0ed8c37 --- /dev/null +++ b/crates/audio/tests/qoa_oracle.rs @@ -0,0 +1,67 @@ +//! QOA against ffmpeg's decoder as the reference (oracle; skipped when ffmpeg is absent, a failure +//! with `CRAFT_MEDIA_REQUIRE_ORACLES=1`): ffmpeg decodes the files our encoder writes to exactly +//! the samples our decoder returns for them, over several sizes (partial slices, partial frames, +//! several frames), channel counts and rates. + +use craft_audio::qoa::{decode, encode}; +use std::process::Command; + +fn signal(channels: usize, frames: usize) -> Vec> { + let mut seed = 0x2545_F491u32; + (0..channels) + .map(|c| { + (0..frames) + .map(|i| { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + let tone = ((i as f64) * (0.02 + 0.013 * c as f64)).sin() * 9000.0; + // Tones, noise bursts, silence and full-scale peaks. + match (i / 700) % 4 { + 0 => tone as i16, + 1 => (tone + f64::from(seed % 6000) - 3000.0) as i16, + 2 => 0, + _ => { + if i % 2 == 0 { + i16::MAX + } else { + i16::MIN + } + } + } + }) + .collect() + }) + .collect() +} + +#[test] +fn ffmpeg_decodes_our_files_to_the_same_samples() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("qoa"); + for (rate, channels, frames) in + [(44_100u32, 1usize, 1usize), (8_000, 1, 19), (48_000, 2, 5_121), (22_050, 2, 12_345), (96_000, 1, 20_000), (44_100, 4, 6_000)] + { + let src = signal(channels, frames); + let bytes = encode(rate, &src).expect("encode"); + let ours = decode(&bytes).expect("decode"); + let file = dir.join(format!("ours_{rate}_{channels}_{frames}.qoa")); + std::fs::write(&file, &bytes).expect("write fixture"); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-y", "-i"]) + .arg(&file) + .args(["-f", "s16le", "-acodec", "pcm_s16le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg failed on {}: {}", file.display(), String::from_utf8_lossy(&out.stderr)); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + let mut interleaved = Vec::with_capacity(frames * channels); + for i in 0..frames { + for c in 0..channels { + interleaved.push(ours.channels[c][i]); + } + } + assert_eq!(theirs.len(), interleaved.len(), "{rate} Hz, {channels} ch, {frames} frames: sample count"); + assert!(theirs == interleaved, "{rate} Hz, {channels} ch, {frames} frames: samples differ"); + } +} From 3ce92b332db8fa1f8d33214d299e88096263c007 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 12:53:20 +0100 Subject: [PATCH 02/13] craft-image-codecs: JPEG-LS (ITU-T T.87) reader and writer Adds Format::JpegLs: lossless and near-lossless gray and RGB, 2 to 16 bits. Reads scans that code one component each; writes lossless 8- and 16-bit gray and RGB. Line- and sample-interleaved scans, mapping tables and colour transforms are reported as unsupported. Closes #1558 --- Cargo.lock | 1 + crates/image-codecs/Cargo.toml | 1 + crates/image-codecs/README.md | 1 + crates/image-codecs/src/codecs.rs | 1 + crates/image-codecs/src/codecs/jpegls.rs | 870 ++++++++++++++++++ crates/image-codecs/src/format.rs | 14 +- crates/image-codecs/src/lib.rs | 4 +- crates/image-codecs/tests/it/detect_caps.rs | 16 + crates/image-codecs/tests/it/jpegls_oracle.rs | 103 +++ crates/image-codecs/tests/it/main.rs | 1 + 10 files changed, 1009 insertions(+), 3 deletions(-) create mode 100644 crates/image-codecs/src/codecs/jpegls.rs create mode 100644 crates/image-codecs/tests/it/jpegls_oracle.rs diff --git a/Cargo.lock b/Cargo.lock index 9a600099d..55ab615b8 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1919,6 +1919,7 @@ dependencies = [ "avif-serialize", "craft-heif", "craft-jpeg", + "craft-media-testkit", "craft-metadata", "exr", "flate2", diff --git a/crates/image-codecs/Cargo.toml b/crates/image-codecs/Cargo.toml index dc920f14b..5281fe2cf 100644 --- a/crates/image-codecs/Cargo.toml +++ b/crates/image-codecs/Cargo.toml @@ -46,6 +46,7 @@ exr = { version = "1.73", default-features = false, features = ["rayon"] } proptest = { workspace = true } image = { version = "0.25", default-features = false, features = ["png", "jpeg", "tiff"] } sha2 = { version = "0.10", default-features = false, features = ["std"] } +craft-media-testkit = { workspace = true } [target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies] jxl-oxide = { version = "=0.12.6", default-features = false, features = ["rayon"] } diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 6e9e11617..a67be77c5 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -56,6 +56,7 @@ craft-image-codecs = { git = "https://github.com/storytold/craft-libs", rev = "< | Cineon | yes | yes | U16 (10-bit code values read and written exactly through U16) | Gray, RGB | no | no | no | no | no | no | no | built in | | DICOM | yes | **no** | U8, U16 | Gray, RGB | no | no | no | no | no | no | n/a | built in | | Amiga IFF (ILBM/PBM) | yes | yes (24-bit ILBM) | U8 | RGB, RGBA | yes (1-bit mask plane on write) | no | no | no | no | no | no | built in | +| JPEG-LS (`.jls`) | yes (any NEAR; one scan per component) | yes (lossless) | U8, U16 | Gray, RGB | no | no | no | no | no | no | no | built in | | AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` | | HEIF/HEIC | with feature `heif` | **no** | U8, U16 (10/12-bit decodes to U16) | RGB, RGBA | yes (auxiliary alpha) | yes (`colr` prof) | yes | yes | no | no | n/a | `heic-rs` | diff --git a/crates/image-codecs/src/codecs.rs b/crates/image-codecs/src/codecs.rs index 0288ae22b..af91aa536 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -13,6 +13,7 @@ pub(crate) mod heif; pub(crate) mod iff; pub(crate) mod jp2; pub(crate) mod jpeg; +pub(crate) mod jpegls; pub(crate) mod jxl; pub(crate) mod pcx; pub(crate) mod png; diff --git a/crates/image-codecs/src/codecs/jpegls.rs b/crates/image-codecs/src/codecs/jpegls.rs new file mode 100644 index 000000000..b405e71ed --- /dev/null +++ b/crates/image-codecs/src/codecs/jpegls.rs @@ -0,0 +1,870 @@ +//! JPEG-LS (ITU-T T.87 | ISO/IEC 14495-1, "LOCO-I"): lossless and near-lossless gray and RGB +//! images, 2 to 16 bits per sample. +//! +//! Read: baseline JPEG-LS with the default or `LSE`-preset coding parameters, any `NEAR`, and +//! scans that code one component each (`ILV` 0), which is also how this module writes. Line- and +//! sample-interleaved scans, colour transforms and mapping tables are reported as unsupported. +//! Write: lossless (`NEAR` 0), 8 or 16 bits, gray or RGB, one scan per component. +//! +//! Samples of 9 to 15 bits are scaled to 16 bits on read (the top bits are repeated into the low +//! ones), so a decoded image always spans the full range of its sample type. + +use crate::error::CodecError; +use crate::fidelity::Plan; +use crate::format::Format; +use crate::image::{ChannelLayout, Image, SampleType}; +use crate::options::Limits; + +const F: Format = Format::JpegLs; +const SOF55: u8 = 0xF7; +const LSE: u8 = 0xF8; +const RESET_DEFAULT: i32 = 64; +const MIN_C: i32 = -128; +const MAX_C: i32 = 127; +/// `J[RUNindex]`: the log2 of the run length a run-index step codes. +const J: [u32; 32] = [0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 9, 10, 11, 12, 13, 14, 15]; +/// Context slots: the regular contexts (365 of the 405 slots the index below can reach), then the two +/// run-interruption contexts. +const RI_BASE: usize = 405; +const CONTEXTS: usize = RI_BASE + 2; + +fn bad(reason: impl std::fmt::Display) -> CodecError { + CodecError::malformed(F, reason) +} + +/// Whether `b` is a JPEG-LS file: an SOI followed by marker segments up to an SOF55 frame header. +pub(crate) fn looks_like_jpegls(b: &[u8]) -> bool { + if !b.starts_with(&[0xFF, 0xD8]) { + return false; + } + let mut pos = 2; + for _ in 0..64 { + let (Some(&0xFF), Some(&marker)) = (b.get(pos), b.get(pos + 1)) else { return false }; + match marker { + SOF55 => return true, + 0xDA | 0xD9 => return false, + 0xC0..=0xCF | 0xDB..=0xDF => return false, + 0x01 | 0xD0..=0xD7 | 0xFF => pos += if marker == 0xFF { 1 } else { 2 }, + _ => { + let Some(len) = b.get(pos + 2..pos + 4).map(|l| usize::from(u16::from_be_bytes([l[0], l[1]]))) else { return false }; + pos += 2 + len; + } + } + } + false +} + +/// The coding parameters of one scan, derived as T.87 section C.2 specifies. +#[derive(Clone, Copy)] +struct Params { + maxval: i32, + near: i32, + range: i32, + qbpp: u32, + limit: u32, + t1: i32, + t2: i32, + t3: i32, + reset: i32, +} + +fn ceil_log2(v: i32) -> u32 { + let mut n = 0; + while (1i64 << n) < i64::from(v) { + n += 1; + } + n +} + +impl Params { + /// `preset` holds the `LSE` values (`maxval`, `t1`, `t2`, `t3`, `reset`), 0 where absent. + fn new(precision: u32, near: i32, preset: [i32; 5]) -> Result { + let default_max = (1i32 << precision) - 1; + let maxval = if preset[0] == 0 { default_max } else { preset[0] }; + if maxval < 1 || maxval > default_max || near < 0 || near > (maxval / 2).min(255) { + return Err(bad("invalid MAXVAL or NEAR")); + } + let clamp = |v: i32, lo: i32, hi: i32| if v > hi || v < lo { lo } else { v }; + let (d1, d2, d3) = if maxval >= 128 { + let factor = (maxval.min(4095) + 128) / 256; + let t1 = clamp(factor + 2 + 3 * near, near + 1, maxval); + let t2 = clamp(factor * 4 + 3 + 5 * near, t1, maxval); + let t3 = clamp(factor * 17 + 4 + 7 * near, t2, maxval); + (t1, t2, t3) + } else { + let factor = 256 / (maxval + 1); + let t1 = clamp((3 / factor + 3 * near).max(2), near + 1, maxval); + let t2 = clamp((7 / factor + 5 * near).max(3), t1, maxval); + let t3 = clamp((21 / factor + 7 * near).max(4), t2, maxval); + (t1, t2, t3) + }; + let t1 = if preset[1] == 0 { d1 } else { preset[1] }; + let t2 = if preset[2] == 0 { d2 } else { preset[2] }; + let t3 = if preset[3] == 0 { d3 } else { preset[3] }; + let reset = if preset[4] == 0 { RESET_DEFAULT } else { preset[4] }; + if !(near < t1 && t1 <= t2 && t2 <= t3 && t3 <= maxval) || !(3..=255).contains(&reset) { + return Err(bad("invalid threshold or RESET preset")); + } + let range = (maxval + 2 * near) / (2 * near + 1) + 1; + let bpp = ceil_log2(maxval + 1).max(2); + Ok(Params { maxval, near, range, qbpp: ceil_log2(range), limit: 2 * (bpp + bpp.max(8)), t1, t2, t3, reset }) + } +} + +/// Adaptive state of one scan: contexts, bias and the run index. +struct State { + a: [i32; CONTEXTS], + b: [i32; CONTEXTS], + c: [i32; CONTEXTS], + n: [i32; CONTEXTS], + nn: [i32; 2], + run_index: usize, +} + +impl State { + fn new(p: &Params) -> State { + let a0 = ((p.range + 32) / 64).max(2); + State { a: [a0; CONTEXTS], b: [0; CONTEXTS], c: [0; CONTEXTS], n: [1; CONTEXTS], nn: [0; 2], run_index: 0 } + } +} + +fn quantise_gradient(d: i32, p: &Params) -> i32 { + if d <= -p.t3 { + -4 + } else if d <= -p.t2 { + -3 + } else if d <= -p.t1 { + -2 + } else if d < -p.near { + -1 + } else if d <= p.near { + 0 + } else if d < p.t1 { + 1 + } else if d < p.t2 { + 2 + } else if d < p.t3 { + 3 + } else { + 4 + } +} + +fn predict(ra: i32, rb: i32, rc: i32) -> i32 { + if rc >= ra.max(rb) { + ra.min(rb) + } else if rc <= ra.min(rb) { + ra.max(rb) + } else { + ra + rb - rc + } +} + +/// The error quantised for `NEAR` and reduced into the modulo range, as the encoder codes it. +fn reduce(mut e: i32, p: &Params) -> i32 { + if p.near > 0 { + e = if e > 0 { (e + p.near) / (2 * p.near + 1) } else { -(p.near - e) / (2 * p.near + 1) }; + } + if e < 0 { + e += p.range; + } + if e >= (p.range + 1) / 2 { + e -= p.range; + } + e +} + +/// The reconstructed sample for a decoded (sign-adjusted) error. +fn reconstruct(px: i32, sign: i32, e: i32, p: &Params) -> i32 { + let mut r = px + sign * e * (2 * p.near + 1); + if r < -p.near { + r += p.range * (2 * p.near + 1); + } else if r > p.maxval + p.near { + r -= p.range * (2 * p.near + 1); + } + r.clamp(0, p.maxval) +} + +fn golomb_k(n: i32, a: i32) -> u32 { + let mut k = 0; + while (i64::from(n) << k) < i64::from(a) { + k += 1; + } + k +} + +/// Bits of the entropy-coded segment, with T.87's stuffing: after an `0xFF` byte the next byte +/// carries only 7 bits. +struct BitReader<'a> { + data: &'a [u8], + pos: usize, + cur: u32, + left: u32, + prev_ff: bool, +} + +impl<'a> BitReader<'a> { + fn new(data: &'a [u8]) -> Self { + BitReader { data, pos: 0, cur: 0, left: 0, prev_ff: false } + } + + fn bit(&mut self) -> Result { + if self.left == 0 { + let byte = *self.data.get(self.pos).ok_or_else(|| bad("the entropy-coded data ends early"))?; + self.pos += 1; + if self.prev_ff { + if byte & 0x80 != 0 { + return Err(bad("a marker inside entropy-coded data")); + } + self.cur = u32::from(byte); + self.left = 7; + } else { + self.cur = u32::from(byte); + self.left = 8; + } + self.prev_ff = byte == 0xFF; + } + self.left -= 1; + Ok((self.cur >> self.left) & 1) + } + + fn bits(&mut self, n: u32) -> Result { + let mut v = 0; + for _ in 0..n { + v = v << 1 | self.bit()?; + } + Ok(v) + } + + /// A limited-length Golomb code: the mapped error. + fn golomb(&mut self, k: u32, limit: u32, qbpp: u32) -> Result { + let max_zeros = limit.checked_sub(qbpp + 1).ok_or_else(|| bad("invalid LIMIT"))?; + let mut zeros = 0; + while self.bit()? == 0 { + zeros += 1; + if zeros > max_zeros { + return Err(bad("a Golomb code is longer than LIMIT")); + } + } + let v = if zeros < max_zeros { (zeros << k) + self.bits(k)? } else { self.bits(qbpp)? + 1 }; + i32::try_from(v).map_err(|_| bad("mapped error out of range")) + } +} + +/// Decode one component scan of `w` x `h` samples into `out` (row-major). +fn decode_scan(data: &[u8], w: usize, h: usize, p: &Params, out: &mut [u16]) -> Result<(), CodecError> { + let mut r = BitReader::new(data); + let mut st = State::new(p); + let mut prev = vec![0i32; w + 2]; + let mut cur = vec![0i32; w + 2]; + for y in 0..h { + // Ra at the first sample is Rb; the slot at index 0 is Rc there, left over from the line above. + cur[0] = prev[1]; + if y > 0 { + prev[w + 1] = prev[w]; + } + let mut x = 0usize; + while x < w { + let (ra, rb, rc, rd) = (cur[x], prev[x + 1], prev[x], if y == 0 { 0 } else { prev[x + 2] }); + let (q1, q2, q3) = (quantise_gradient(rd - rb, p), quantise_gradient(rb - rc, p), quantise_gradient(rc - ra, p)); + if q1 == 0 && q2 == 0 && q3 == 0 { + x = decode_run(&mut r, &mut st, p, &prev, &mut cur, ra, x, w)?; + continue; + } + let (sign, q1, q2, q3) = if q1 < 0 || (q1 == 0 && (q2 < 0 || (q2 == 0 && q3 < 0))) { (-1, -q1, -q2, -q3) } else { (1, q1, q2, q3) }; + let q = (q1 * 81 + (q2 + 4) * 9 + (q3 + 4)) as usize; + let k = golomb_k(st.n[q], st.a[q]); + let m = r.golomb(k, p.limit, p.qbpp)?; + let swap = p.near == 0 && k == 0 && 2 * st.b[q] <= -st.n[q]; + let e = if swap { + if m & 1 == 1 { (m - 1) >> 1 } else { -(m >> 1) - 1 } + } else if m & 1 == 0 { + m >> 1 + } else { + -((m + 1) >> 1) + }; + let px = (predict(ra, rb, rc) + sign * st.c[q]).clamp(0, p.maxval); + let rx = reconstruct(px, sign, e, p); + update_regular(&mut st, q, e, p); + cur[x + 1] = rx; + x += 1; + } + let row = &mut out[y * w..(y + 1) * w]; + for (o, &v) in row.iter_mut().zip(&cur[1..=w]) { + *o = v as u16; + } + // The line just decoded becomes the line above; its slot 0 is the Rc of the next line's first sample. + std::mem::swap(&mut prev, &mut cur); + } + Ok(()) +} + +fn update_regular(st: &mut State, q: usize, e: i32, p: &Params) { + st.b[q] += e * (2 * p.near + 1); + st.a[q] += e.abs(); + if st.n[q] == p.reset { + st.a[q] >>= 1; + st.b[q] = if st.b[q] >= 0 { st.b[q] >> 1 } else { -((1 - st.b[q]) >> 1) }; + st.n[q] >>= 1; + } + st.n[q] += 1; + if st.b[q] <= -st.n[q] { + if st.c[q] > MIN_C { + st.c[q] -= 1; + } + st.b[q] += st.n[q]; + if st.b[q] <= -st.n[q] { + st.b[q] = -st.n[q] + 1; + } + } else if st.b[q] > 0 { + if st.c[q] < MAX_C { + st.c[q] += 1; + } + st.b[q] -= st.n[q]; + if st.b[q] > 0 { + st.b[q] = 0; + } + } +} + +/// Run-interruption variables update shared by both directions. +fn update_run(st: &mut State, q: usize, e: i32, em: i32, ri_type: i32, p: &Params) { + let i = q - RI_BASE; + if e < 0 { + st.nn[i] += 1; + } + st.a[q] += (em + 1 - ri_type) >> 1; + if st.n[q] == p.reset { + st.a[q] >>= 1; + st.n[q] >>= 1; + st.nn[i] >>= 1; + } + st.n[q] += 1; +} + +/// The run-interruption Golomb parameter and the mapping flag of an error. +fn run_k(st: &State, q: usize, ri_type: i32) -> u32 { + let temp = if ri_type == 1 { st.a[q] + (st.n[q] >> 1) } else { st.a[q] }; + golomb_k(st.n[q], temp) +} + +#[allow(clippy::too_many_arguments)] +fn decode_run( + r: &mut BitReader, + st: &mut State, + p: &Params, + prev: &[i32], + cur: &mut [i32], + ra: i32, + x: usize, + w: usize, +) -> Result { + let remaining = w - x; + let mut run = 0usize; + while r.bit()? == 1 { + let step = 1usize << J[st.run_index]; + let count = step.min(remaining - run); + run += count; + if count == step && st.run_index < 31 { + st.run_index += 1; + } + if run == remaining { + break; + } + } + if run < remaining { + let rest = r.bits(J[st.run_index])? as usize; + run += rest; + if run > remaining { + return Err(bad("a run passes the end of the line")); + } + } + for v in &mut cur[x + 1..x + 1 + run] { + *v = ra; + } + if run == remaining { + return Ok(w); + } + // The sample that ended the run: its own Rb, the sample above it. + let rb = prev[x + run + 1]; + let ri_type = i32::from((ra - rb).abs() <= p.near); + let q = RI_BASE + ri_type as usize; + let k = run_k(st, q, ri_type); + let limit = p.limit - J[st.run_index] - 1; + let em = r.golomb(k, limit, p.qbpp)?; + let tmp = em + ri_type; + let cond = k == 0 && 2 * st.nn[ri_type as usize] < st.n[q]; + let map = tmp & 1; + let mag = (tmp + map) / 2; + let e = if (cond && map == 1) || (!cond && map == 0) { mag } else { -mag }; + let (px, sign) = if ri_type == 1 { (ra, 1) } else { (rb, if ra > rb { -1 } else { 1 }) }; + // The decoder holds the sign-adjusted error; the sign flips the reconstruction. + let rx = reconstruct(px, sign, e, p); + update_run(st, q, e, em, ri_type, p); + if st.run_index > 0 { + st.run_index -= 1; + } + cur[x + run + 1] = rx; + Ok(x + run + 1) +} + +// ---- encoder ---- + +struct BitWriter { + out: Vec, + cur: u32, + used: u32, + cap: u32, +} + +impl BitWriter { + fn new() -> Self { + BitWriter { out: Vec::new(), cur: 0, used: 0, cap: 8 } + } + + fn put(&mut self, value: u32, n: u32) { + for i in (0..n).rev() { + // A run of more than 32 zero bits (a long escape code) has no bits of `value` to shift out. + let bit = if i < 32 { (value >> i) & 1 } else { 0 }; + self.cur = self.cur << 1 | bit; + self.used += 1; + if self.used == self.cap { + let byte = self.cur as u8; + self.out.push(byte); + self.cap = if byte == 0xFF { 7 } else { 8 }; + self.cur = 0; + self.used = 0; + } + } + } + + /// Pad the last byte with zero bits; a closing 0xFF is followed by a zero byte. + fn finish(mut self) -> Vec { + if self.used > 0 { + let pad = self.cap - self.used; + self.put(0, pad); + } + if self.out.last() == Some(&0xFF) { + self.out.push(0); + } + self.out + } + + fn golomb(&mut self, m: i32, k: u32, limit: u32, qbpp: u32) { + let m = m as u32; + let max_zeros = limit - qbpp - 1; + let q = m >> k; + if q < max_zeros { + self.put(0, q); + self.put(1, 1); + self.put(m & ((1 << k) - 1), k); + } else { + self.put(0, max_zeros); + self.put(1, 1); + self.put(m - 1, qbpp); + } + } +} + +fn encode_scan(plane: &[u16], w: usize, h: usize, p: &Params) -> Vec { + let mut wr = BitWriter::new(); + let mut st = State::new(p); + let mut prev = vec![0i32; w + 2]; + let mut cur = vec![0i32; w + 2]; + for y in 0..h { + cur[0] = prev[1]; + if y > 0 { + prev[w + 1] = prev[w]; + } + let line = &plane[y * w..(y + 1) * w]; + let mut x = 0usize; + while x < w { + let (ra, rb, rc, rd) = (cur[x], prev[x + 1], prev[x], if y == 0 { 0 } else { prev[x + 2] }); + let ix = i32::from(line[x]); + let (q1, q2, q3) = (quantise_gradient(rd - rb, p), quantise_gradient(rb - rc, p), quantise_gradient(rc - ra, p)); + if q1 == 0 && q2 == 0 && q3 == 0 { + x = encode_run(&mut wr, &mut st, p, line, &prev, &mut cur, ra, x); + continue; + } + let (sign, q1, q2, q3) = if q1 < 0 || (q1 == 0 && (q2 < 0 || (q2 == 0 && q3 < 0))) { (-1, -q1, -q2, -q3) } else { (1, q1, q2, q3) }; + let q = (q1 * 81 + (q2 + 4) * 9 + (q3 + 4)) as usize; + let px = (predict(ra, rb, rc) + sign * st.c[q]).clamp(0, p.maxval); + let e = reduce(sign * (ix - px), p); + let k = golomb_k(st.n[q], st.a[q]); + let swap = p.near == 0 && k == 0 && 2 * st.b[q] <= -st.n[q]; + let m = if swap { + if e >= 0 { 2 * e + 1 } else { -2 * (e + 1) } + } else if e >= 0 { + 2 * e + } else { + -2 * e - 1 + }; + wr.golomb(m, k, p.limit, p.qbpp); + cur[x + 1] = reconstruct(px, sign, e, p); + update_regular(&mut st, q, e, p); + x += 1; + } + std::mem::swap(&mut prev, &mut cur); + } + wr.finish() +} + +#[allow(clippy::too_many_arguments)] +fn encode_run(wr: &mut BitWriter, st: &mut State, p: &Params, line: &[u16], prev: &[i32], cur: &mut [i32], ra: i32, x: usize) -> usize { + let w = line.len(); + let mut run = 0usize; + while x + run < w && (i32::from(line[x + run]) - ra).abs() <= p.near { + cur[x + run + 1] = ra; + run += 1; + } + let mut count = run; + while count >= 1usize << J[st.run_index] { + wr.put(1, 1); + count -= 1usize << J[st.run_index]; + if st.run_index < 31 { + st.run_index += 1; + } + } + if x + run == w { + if count > 0 { + wr.put(1, 1); + } + return w; + } + wr.put(0, 1); + wr.put(count as u32, J[st.run_index]); + let ix = i32::from(line[x + run]); + let rb = prev[x + run + 1]; + let ri_type = i32::from((ra - rb).abs() <= p.near); + let q = RI_BASE + ri_type as usize; + let (px, sign) = if ri_type == 1 { (ra, 1) } else { (rb, if ra > rb { -1 } else { 1 }) }; + let e = reduce(sign * (ix - px), p); + let k = run_k(st, q, ri_type); + let n_neg = st.nn[ri_type as usize]; + let map = i32::from((k == 0 && e > 0 && 2 * n_neg < st.n[q]) || (e < 0 && 2 * n_neg >= st.n[q]) || (e < 0 && k != 0)); + let em = 2 * e.abs() - ri_type - map; + wr.golomb(em, k, p.limit - J[st.run_index] - 1, p.qbpp); + cur[x + run + 1] = reconstruct(px, sign, e, p); + update_run(st, q, e, em, ri_type, p); + if st.run_index > 0 { + st.run_index -= 1; + } + x + run + 1 +} + +/// Writes a lossless JPEG-LS file: 8 or 16 bits, gray or RGB, one scan per component. +pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { + let enc = |msg: String| CodecError::encode(F, msg); + let img = src.converted(plan.layout, plan.sample); + let nc = match img.layout() { + ChannelLayout::Gray => 1, + ChannelLayout::Rgb => 3, + l => return Err(enc(format!("no JPEG-LS layout for {l:?}"))), + }; + let precision: u32 = match img.sample_type() { + SampleType::U8 => 8, + SampleType::U16 => 16, + s => return Err(enc(format!("JPEG-LS stores 8 or 16 bits per sample, not {s:?}"))), + }; + let (w, h) = img.dimensions(); + let (Ok(w16), Ok(h16)) = (u16::try_from(w), u16::try_from(h)) else { + return Err(enc(format!("dimensions exceed 65535x65535: {w}x{h}"))); + }; + let (wu, hu) = (w as usize, h as usize); + let data = img.data(); + if data.len() != wu * hu * nc * (precision as usize / 8) { + return Err(enc("the image has the wrong number of samples".into())); + } + let params = Params::new(precision, 0, [0; 5]).map_err(|_| enc("invalid coding parameters".into()))?; + let mut out = vec![0xFF, 0xD8, 0xFF, SOF55]; + out.extend_from_slice(&((8 + 3 * nc) as u16).to_be_bytes()); + out.push(precision as u8); + out.extend_from_slice(&h16.to_be_bytes()); + out.extend_from_slice(&w16.to_be_bytes()); + out.push(nc as u8); + for c in 0..nc { + out.extend_from_slice(&[c as u8 + 1, 0x11, 0]); + } + let mut plane = vec![0u16; wu * hu]; + for c in 0..nc { + for (i, v) in plane.iter_mut().enumerate() { + let at = i * nc + c; + *v = if precision == 8 { u16::from(data[at]) } else { u16::from_ne_bytes([data[2 * at], data[2 * at + 1]]) }; + } + out.extend_from_slice(&[0xFF, 0xDA, 0, 8, 1, c as u8 + 1, 0, 0, 0, 0]); + out.extend_from_slice(&encode_scan(&plane, wu, hu, ¶ms)); + } + out.extend_from_slice(&[0xFF, 0xD9]); + Ok(out) +} + +struct Frame { + precision: u32, + width: usize, + height: usize, + components: Vec, +} + +fn be16(b: &[u8], i: usize) -> Result { + b.get(i..i + 2).map(|s| usize::from(u16::from_be_bytes([s[0], s[1]]))).ok_or_else(|| bad("truncated header")) +} + +pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { + if !looks_like_jpegls(b) { + return Err(bad("not a JPEG-LS file")); + } + let mut pos = 2; + let mut frame: Option = None; + let mut preset = [0i32; 5]; + let mut planes: Vec> = Vec::new(); + let mut scans_done = 0; + loop { + // Find the next marker. + while b.get(pos) != Some(&0xFF) { + if pos >= b.len() { + return finish(frame, planes, scans_done); + } + pos += 1; + } + while b.get(pos + 1) == Some(&0xFF) { + pos += 1; + } + let Some(&marker) = b.get(pos + 1) else { return finish(frame, planes, scans_done) }; + if marker == 0xD9 { + return finish(frame, planes, scans_done); + } + if marker == 0x00 || (0xD0..=0xD7).contains(&marker) || marker == 0x01 { + pos += 2; + continue; + } + let len = be16(b, pos + 2)?; + let seg = b.get(pos + 4..pos + 2 + len).ok_or_else(|| bad("truncated marker segment"))?; + match marker { + SOF55 => { + if frame.is_some() || seg.len() < 6 { + return Err(bad("bad or repeated frame header")); + } + let (precision, height, width, nf) = (u32::from(seg[0]), be16(seg, 1)?, be16(seg, 3)?, usize::from(seg[5])); + if !(2..=16).contains(&precision) || width == 0 || height == 0 || !matches!(nf, 1 | 3) || seg.len() < 6 + 3 * nf { + return Err(bad("unsupported frame header")); + } + if height == 0 { + return Err(CodecError::unsupported(F, "a frame height set later by a DNL marker")); + } + let layout = if nf == 1 { ChannelLayout::Gray } else { ChannelLayout::Rgb }; + let sample = if precision <= 8 { SampleType::U8 } else { SampleType::U16 }; + limits.check(width as u32, height as u32, layout, sample)?; + let components = (0..nf).map(|i| seg[6 + 3 * i]).collect(); + frame = Some(Frame { precision, width, height, components }); + } + LSE => { + if seg.first() == Some(&1) && seg.len() >= 11 { + for (i, p) in preset.iter_mut().enumerate() { + *p = be16(seg, 1 + 2 * i)? as i32; + } + } else if seg.first() != Some(&1) { + return Err(CodecError::unsupported(F, "mapping tables and colour transforms (LSE)")); + } + } + 0xDA => { + let f = frame.as_ref().ok_or_else(|| bad("a scan before the frame header"))?; + let ns = usize::from(*seg.first().ok_or_else(|| bad("empty scan header"))?); + if seg.len() < 1 + 2 * ns + 3 || ns != 1 { + return Err(CodecError::unsupported(F, "interleaved scans (ILV 1 and 2)")); + } + let (cs, tm, near, ilv) = (seg[1], seg[2], i32::from(seg[3]), seg[4]); + if tm != 0 { + return Err(CodecError::unsupported(F, "mapping tables")); + } + if ilv != 0 && f.components.len() > 1 { + return Err(CodecError::unsupported(F, "interleaved scans (ILV 1 and 2)")); + } + if seg[5] & 0x0f != 0 { + return Err(CodecError::unsupported(F, "a point transform")); + } + let idx = f.components.iter().position(|&c| c == cs).ok_or_else(|| bad("a scan names an unknown component"))?; + if planes.len() <= idx { + planes.resize(f.components.len(), Vec::new()); + } + if !planes[idx].is_empty() { + return Err(bad("a component is coded twice")); + } + let params = Params::new(f.precision, near, preset)?; + let start = pos + 2 + len; + // The scan ends at the next real marker: an 0xFF followed by a byte with its top bit set. + let mut end = start; + while end < b.len() { + if b[end] == 0xFF && b.get(end + 1).is_none_or(|&n| n & 0x80 != 0) { + break; + } + end += 1; + } + let mut samples = Vec::new(); + samples.try_reserve_exact(f.width * f.height).map_err(|_| bad("pixel buffer is too large"))?; + samples.resize(f.width * f.height, 0u16); + decode_scan(&b[start..end], f.width, f.height, ¶ms, &mut samples)?; + planes[idx] = samples; + scans_done += 1; + pos = end; + continue; + } + _ => {} + } + pos += 2 + len; + } +} + +fn finish(frame: Option, planes: Vec>, scans: usize) -> Result { + let f = frame.ok_or_else(|| bad("no frame header"))?; + if scans != f.components.len() || planes.iter().any(Vec::is_empty) || planes.len() != f.components.len() { + return Err(bad("the file ends before every component is coded")); + } + let (w, h, nc) = (f.width, f.height, f.components.len()); + let layout = if nc == 1 { ChannelLayout::Gray } else { ChannelLayout::Rgb }; + let p = f.precision; + let scale = |v: u16| -> u16 { + if p == 16 { + v + } else { + let v = u32::from(v); + ((v << (16 - p)) | (v >> (2 * p).saturating_sub(16).min(15))) as u16 + } + }; + if p <= 8 { + let to8 = |v: u16| -> u8 { if p == 8 { v as u8 } else { (scale(v) >> 8) as u8 } }; + let mut data = Vec::with_capacity(w * h * nc); + for i in 0..w * h { + for plane in &planes { + data.push(to8(plane[i])); + } + } + Image::from_u8(w as u32, h as u32, layout, data) + } else { + let mut data = Vec::with_capacity(w * h * nc); + for i in 0..w * h { + for plane in &planes { + data.push(scale(plane[i])); + } + } + Image::from_u16(w as u32, h as u32, layout, &data) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn noise_u16(n: usize, seed: &mut u32, mask: u32) -> Vec { + (0..n) + .map(|_| { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + (*seed & mask) as u16 + }) + .collect() + } + + fn image(w: u32, h: u32, layout: ChannelLayout, wide: bool, kind: u8) -> Image { + let n = w as usize * h as usize * layout.channels(); + let mut seed = 0x1234_5679u32; + let samples: Vec = match kind { + 0 => noise_u16(n, &mut seed, if wide { 0xFFFF } else { 0xFF }), + 1 => vec![if wide { 40_000 } else { 100 }; n], + _ => (0..n).map(|i| if wide { ((i / 3) * 37 % 65_536) as u16 } else { ((i / 3) % 251) as u16 }).collect(), + }; + if wide { + Image::from_u16(w, h, layout, &samples).unwrap() + } else { + Image::from_u8(w, h, layout, samples.iter().map(|&v| v as u8).collect()).unwrap() + } + } + + fn plan(img: &Image) -> Plan { + Plan { layout: img.layout(), sample: img.sample_type() } + } + + #[test] + fn round_trips_noise_flat_and_smooth_images() { + for layout in [ChannelLayout::Gray, ChannelLayout::Rgb] { + for wide in [false, true] { + for kind in 0..3 { + // Widths around the run-length steps, and single-pixel dimensions. + for (w, h) in [(1, 1), (1, 9), (2, 3), (7, 5), (33, 4), (300, 3), (1025, 2)] { + let img = image(w, h, layout, wide, kind); + let bytes = encode(&img, plan(&img)).unwrap(); + assert!(looks_like_jpegls(&bytes)); + let back = decode(&bytes, &Limits::default()).unwrap_or_else(|e| panic!("{layout:?} wide={wide} kind={kind} {w}x{h}: {e}")); + assert_eq!(back.data(), img.data(), "{layout:?} wide={wide} kind={kind} {w}x{h}"); + } + } + } + } + } + + #[test] + fn default_parameters_follow_the_standard() { + let p = Params::new(8, 0, [0; 5]).unwrap(); + assert_eq!((p.maxval, p.range, p.qbpp, p.limit, p.t1, p.t2, p.t3, p.reset), (255, 256, 8, 32, 3, 7, 21, 64)); + let p = Params::new(16, 0, [0; 5]).unwrap(); + assert_eq!((p.maxval, p.range, p.qbpp, p.limit, p.t1, p.t2, p.t3), (65535, 65536, 16, 64, 18, 67, 276)); + let p = Params::new(8, 3, [0; 5]).unwrap(); + assert_eq!((p.range, p.t1), (38, 12)); // RANGE = floor((255 + 2 * 3) / 7) + 1 + assert!(Params::new(8, 200, [0; 5]).is_err()); + } + + #[test] + fn detection_tells_jpeg_ls_from_jpeg() { + let img = image(4, 4, ChannelLayout::Gray, false, 0); + let ls = encode(&img, plan(&img)).unwrap(); + assert!(looks_like_jpegls(&ls)); + // A baseline JPEG starts SOI, APP0 / DQT, ... SOF0: not JPEG-LS. + assert!(!looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xE0, 0, 4, 0, 0, 0xFF, 0xC0, 0, 11])); + assert!(!looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11])); + // SOF55 after an application segment still is. + assert!(looks_like_jpegls(&[0xFF, 0xD8, 0xFF, 0xE8, 0, 4, 0, 0, 0xFF, 0xF7, 0, 11])); + assert!(!looks_like_jpegls(&[0xFF, 0xD8])); + } + + #[test] + fn interleaved_scans_and_tables_are_unsupported() { + let img = image(8, 4, ChannelLayout::Rgb, false, 2); + let good = encode(&img, plan(&img)).unwrap(); + // The scan header body is Ns, Cs, Tm, NEAR, ILV, point transform, after the marker and length. + let sos = good.windows(2).position(|w| w == [0xFF, 0xDA]).unwrap() + 4; + let mut line = good.clone(); + line[sos + 4] = 1; + assert!(matches!(decode(&line, &Limits::default()), Err(CodecError::Unsupported { .. }))); + let mut mapped = good.clone(); + mapped[sos + 2] = 1; + assert!(matches!(decode(&mapped, &Limits::default()), Err(CodecError::Unsupported { .. }))); + let mut transform = good; + transform[sos + 5] = 1; + assert!(matches!(decode(&transform, &Limits::default()), Err(CodecError::Unsupported { .. }))); + } + + #[test] + fn hostile_input_is_an_error_not_a_panic() { + for (w, h, layout, wide) in [(23, 9, ChannelLayout::Gray, false), (11, 7, ChannelLayout::Rgb, true)] { + let img = image(w, h, layout, wide, 0); + let good = encode(&img, plan(&img)).unwrap(); + for len in 0..good.len() { + let _ = decode(&good[..len], &Limits::default()); + } + // Flip every bit of the entropy-coded data and of the headers, one at a time. + for i in 0..good.len() { + for bit in 0..8 { + let mut c = good.clone(); + c[i] ^= 1 << bit; + let _ = decode(&c, &Limits::default()); + } + } + } + // A huge frame is stopped by the limits or the length check before any allocation. + let img = image(4, 4, ChannelLayout::Gray, false, 0); + let mut huge = encode(&img, plan(&img)).unwrap(); + let sof = huge.windows(2).position(|w| w == [0xFF, 0xF7]).unwrap(); + huge[sof + 5..sof + 9].copy_from_slice(&[0xFF, 0xFF, 0xFF, 0xFF]); + assert!(decode(&huge, &Limits::default()).is_err()); + } +} diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index ecaf945cd..810c1ad48 100644 --- a/crates/image-codecs/src/format.rs +++ b/crates/image-codecs/src/format.rs @@ -44,6 +44,8 @@ pub enum Format { Iff, /// JPEG 2000 (JP2 container or raw J2K codestream): read-only; see [`ASYMMETRIC_EXCEPTIONS`]. Jp2, + /// JPEG-LS (`.jls`): lossless and near-lossless gray and RGB. + JpegLs, } /// What a format can hold **and** what this crate reads/writes for it. @@ -113,7 +115,7 @@ const TIFF_LAYOUTS: &[ChannelLayout] = &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L:: impl Format { /// Every format known to the crate (enabled or not). - pub const ALL: [Format; 24] = [ + pub const ALL: [Format; 25] = [ Format::Png, Format::Jpeg, Format::Jp2, @@ -138,6 +140,7 @@ impl Format { Format::Cineon, Format::Dicom, Format::Iff, + Format::JpegLs, ]; pub fn caps(self) -> FormatCaps { @@ -176,6 +179,7 @@ impl Format { Format::Dicom => "DICOM", Format::Iff => "Amiga IFF", Format::Jp2 => "JPEG 2000", + Format::JpegLs => "JPEG-LS", } } @@ -207,6 +211,7 @@ impl Format { Format::Dicom => &["dcm", "dicom", "dc3"], Format::Iff => &["iff", "lbm", "ilbm"], Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"], + Format::JpegLs => &["jls"], } } @@ -236,13 +241,14 @@ impl Format { Format::Dicom => "application/dicom", Format::Iff => "image/x-iff", Format::Jp2 => "image/jp2", + Format::JpegLs => "image/jls", } } /// Maximum encodable dimensions, if the format has a hard limit. pub fn max_dimensions(self) -> Option<(u32, u32)> { match self { - Format::Jpeg | Format::Gif | Format::Iff => Some((65535, 65535)), + Format::Jpeg | Format::Gif | Format::Iff | Format::JpegLs => Some((65535, 65535)), Format::WebP => Some((16384, 16384)), Format::Ico => Some((256, 256)), _ => None, @@ -310,6 +316,7 @@ pub fn caps(format: Format) -> FormatCaps { Format::Cineon => FormatCaps { depths: &[S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Dicom => FormatCaps { read: true, write: false, depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Iff => FormatCaps { depths: &[S::U8], layouts: &[L::Rgb, L::Rgba], alpha: true, ..base }, + Format::JpegLs => FormatCaps { depths: &[S::U8, S::U16], layouts: &[L::Gray, L::Rgb], alpha: false, ..base }, Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base }, } } @@ -321,6 +328,9 @@ pub fn detect(bytes: &[u8]) -> Option { if b.starts_with(b"\x89PNG\r\n\x1a\n") { return Some(Format::Png); } + if crate::codecs::jpegls::looks_like_jpegls(b) { + return Some(Format::JpegLs); + } if b.starts_with(&[0xFF, 0xD8, 0xFF]) { return Some(Format::Jpeg); } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 21130e392..b60691e83 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -62,7 +62,7 @@ pub use crate::resolution::{exif_resolution, export_exif, export_xmp, photoshop_ pub use crate::source_settings::{WebpEncoding, jpeg_quality, webp_encoding}; pub use half::f16; -use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jxl, pcx, png, pnm, tiff, via_image, webp, xpm}; +use crate::codecs::{dds, dicom, dpx, exr, fits, heif, iff, jp2, jpeg, jpegls, jxl, pcx, png, pnm, tiff, via_image, webp, xpm}; /// Detect the format and decode with default [`Limits`]. pub fn decode(bytes: &[u8]) -> Result { @@ -101,6 +101,7 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res Format::Cineon => dpx::decode_cineon(bytes, l), Format::Dicom => dicom::decode(bytes, l), Format::Iff => iff::decode(bytes, l), + Format::JpegLs => jpegls::decode(bytes, l), Format::OpenExr => exr::decode(bytes, l), Format::Heif => heif::decode(bytes, l, opts.keep_orientation), Format::Jp2 => jp2::decode(bytes, l), @@ -457,6 +458,7 @@ pub fn encode(image: &Image, format: Format, opts: &EncodeOptions) -> Result dpx::encode_cineon(image, plan), Format::Dicom => Err(CodecError::unsupported(format, "DICOM is import-only; save as TIFF or PNG instead")), Format::Iff => iff::encode(image, plan), + Format::JpegLs => jpegls::encode(image, plan), Format::OpenExr => exr::encode(image, plan, opts), Format::Heif => Err(CodecError::unsupported(format, "encoding is not available in this build")), Format::Jp2 => Err(CodecError::unsupported(format, "JPEG 2000 is import-only; save as PNG or TIFF instead")), diff --git a/crates/image-codecs/tests/it/detect_caps.rs b/crates/image-codecs/tests/it/detect_caps.rs index 640772c83..390eaa41f 100644 --- a/crates/image-codecs/tests/it/detect_caps.rs +++ b/crates/image-codecs/tests/it/detect_caps.rs @@ -62,6 +62,7 @@ fn default_build_formats_all_symmetric() { Format::Dpx, Format::Cineon, Format::Iff, + Format::JpegLs, ]; for f in expected { assert!(caps(f).read && caps(f).write, "{f:?}"); @@ -218,6 +219,21 @@ fn detect_magic_iff() { assert_eq!(detect(b"FORM\0\0\0\x14AIFF"), None); assert!(decode_as(Format::Iff, b"FORM\0\0\0\x14ILBM").is_err()); } +#[test] +fn detect_magic_jpeg_ls() { + use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode}; + let img = Image::from_u8(5, 3, ChannelLayout::Gray, (0..15).collect()).unwrap(); + let bytes = encode(&img, Format::JpegLs, &EncodeOptions::default()).unwrap(); + assert_eq!(detect(&bytes), Some(Format::JpegLs)); + assert_eq!(from_extension("scan.JLS"), Some(Format::JpegLs)); + assert_eq!(decode(&bytes).unwrap().data(), img.data()); + assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::JpegLs)); + assert_eq!(Format::JpegLs.max_dimensions(), Some((65535, 65535))); + // Plain JPEG still is JPEG: SOI, then a baseline frame header. + assert_eq!(detect(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 11]), Some(Format::Jpeg)); + assert!(decode_as(Format::JpegLs, &[0xFF, 0xD8, 0xFF, 0xF7]).is_err()); +} + #[test] fn detect_magic_avif() { assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif)); diff --git a/crates/image-codecs/tests/it/jpegls_oracle.rs b/crates/image-codecs/tests/it/jpegls_oracle.rs new file mode 100644 index 000000000..aa98609a1 --- /dev/null +++ b/crates/image-codecs/tests/it/jpegls_oracle.rs @@ -0,0 +1,103 @@ +//! JPEG-LS against ffmpeg as the reference (oracle; skipped when ffmpeg is absent, a failure with +//! `CRAFT_MEDIA_REQUIRE_ORACLES=1`): +//! - files ffmpeg's encoder writes (8- and 16-bit gray: smooth, noisy and flat images, which +//! exercise the regular, run and escape-coded paths) decode to the pixels ffmpeg decodes; +//! - files our encoder writes (gray 8 and 16 bits, RGB 8 bits) decode in ffmpeg to our pixels (ffmpeg +//! cannot decode 16-bit RGB JPEG-LS, so that case is only round-tripped through our own decoder); +//! - ffmpeg writes RGB line-interleaved, which is reported as unsupported. + +use craft_image_codecs::{ChannelLayout, CodecError, EncodeOptions, Format, Image, SampleType, decode, encode}; +use std::path::Path; +use std::process::Command; + +const W: u32 = 66; +const H: u32 = 40; + +fn run(ffmpeg: &Path, args: &[&str]) -> Vec { + let out = Command::new(ffmpeg).args(["-v", "error", "-y"]).args(args).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); + out.stdout +} + +/// `(name, lavfi source)`: smooth, noisy and flat pictures of W x H. +fn sources() -> Vec<(&'static str, String)> { + let s = format!("{W}x{H}"); + vec![ + ("testsrc", format!("testsrc2=size={s}:rate=1")), + ("noise", format!("nullsrc=size={s}:rate=1,geq=lum='random(1)*255':cb=128:cr=128")), + ("flat", format!("color=c=0x336699:size={s}:rate=1")), + ("gradient", format!("gradients=size={s}:rate=1:seed=7")), + ] +} + +#[test] +fn ffmpeg_files_decode_to_ffmpegs_pixels() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("jpegls"); + for (name, src) in sources() { + for (fmt, ext_bits) in [("gray", 8), ("gray16le", 16)] { + let file = dir.join(format!("ffmpeg_{name}_{ext_bits}.jls")); + let f = file.to_str().expect("path"); + run(&ffmpeg, &["-f", "lavfi", "-i", &src, "-frames:v", "1", "-pix_fmt", fmt, f]); + let theirs = run(&ffmpeg, &["-i", f, "-f", "rawvideo", "-pix_fmt", fmt, "-"]); + let ours = decode(&std::fs::read(&file).expect("read")).unwrap_or_else(|e| panic!("{name} {fmt}: {e}")); + assert_eq!((ours.width(), ours.height(), ours.layout()), (W, H, ChannelLayout::Gray), "{name} {fmt}"); + let want_sample = if ext_bits == 8 { SampleType::U8 } else { SampleType::U16 }; + assert_eq!(ours.sample_type(), want_sample); + let ours_bytes: Vec = if ext_bits == 8 { + ours.data().to_vec() + } else { + ours.data().as_chunks::<2>().0.iter().flat_map(|b| u16::from_ne_bytes(*b).to_le_bytes()).collect() + }; + assert!(ours_bytes == theirs, "{name} {fmt}: pixels differ from ffmpeg's decode"); + } + } +} + +#[test] +fn ffmpegs_rgb_is_line_interleaved_and_unsupported() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("jpegls"); + let file = dir.join("ffmpeg_rgb.jls"); + run( + &ffmpeg, + &["-f", "lavfi", "-i", &format!("testsrc2=size={W}x{H}:rate=1"), "-frames:v", "1", "-pix_fmt", "rgb24", file.to_str().expect("path")], + ); + assert!(matches!(decode(&std::fs::read(&file).expect("read")), Err(CodecError::Unsupported { .. }))); +} + +#[test] +fn ffmpeg_decodes_our_files_to_our_pixels() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("jpegls"); + for (name, src) in sources() { + for (layout, fmt8, fmt16) in [(ChannelLayout::Gray, "gray", "gray16le"), (ChannelLayout::Rgb, "rgb24", "rgb48le")] { + for bits in [8, 16] { + let fmt = if bits == 8 { fmt8 } else { fmt16 }; + // Source pixels from ffmpeg, so the test image is realistic. + let raw = run(&ffmpeg, &["-f", "lavfi", "-i", &src, "-frames:v", "1", "-pix_fmt", fmt, "-f", "rawvideo", "-"]); + let img = if bits == 8 { + Image::from_u8(W, H, layout, raw).expect("image") + } else { + let samples: Vec = raw.as_chunks::<2>().0.iter().map(|b| u16::from_le_bytes(*b)).collect(); + Image::from_u16(W, H, layout, &samples).expect("image") + }; + let bytes = encode(&img, Format::JpegLs, &EncodeOptions::default()).expect("encode"); + assert_eq!(decode(&bytes).expect("our own file decodes").data(), img.data(), "{name} {fmt}: round trip"); + let file = dir.join(format!("ours_{name}_{fmt}.jls")); + std::fs::write(&file, &bytes).expect("write"); + // ffmpeg's decoder does not implement 16-bit colour ("Not yet implemented"). + if layout == ChannelLayout::Rgb && bits == 16 { + continue; + } + let theirs = run(&ffmpeg, &["-i", file.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", fmt, "-"]); + let ours_bytes: Vec = if bits == 8 { + img.data().to_vec() + } else { + img.data().as_chunks::<2>().0.iter().flat_map(|b| u16::from_ne_bytes(*b).to_le_bytes()).collect() + }; + assert!(theirs == ours_bytes, "{name} {fmt}: ffmpeg decodes our file to other pixels"); + } + } + } +} diff --git a/crates/image-codecs/tests/it/main.rs b/crates/image-codecs/tests/it/main.rs index f465a0cbb..4eda74a26 100644 --- a/crates/image-codecs/tests/it/main.rs +++ b/crates/image-codecs/tests/it/main.rs @@ -14,6 +14,7 @@ mod exr_stream; mod fidelity; mod gif_frames; mod heif; +mod jpegls_oracle; mod limits; mod malformed; mod metadata; From 5ab7a6035c0ff409cc743978b17d73f414b58524 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 13:06:49 +0100 Subject: [PATCH 03/13] craft-video: FFV1 lossless video, version 3 range-coder decoder and encoder Adds the ffv1 feature (RFC 9043): YCbCr (any 2^n subsampling, gray, optional transparency) and RGB through the JPEG 2000 reversible colour transform, 8 to 16 bits, any slice raster, slice and configuration record CRCs. Not covered yet: the Golomb-Rice coder, versions 0 and 1, inter frames. Part of #1509 --- crates/video/Cargo.toml | 6 + crates/video/src/ffv1/README.md | 52 ++ crates/video/src/ffv1/mod.rs | 929 ++++++++++++++++++++++++++++++++ crates/video/src/ffv1/rc.rs | 229 ++++++++ crates/video/src/lib.rs | 4 + crates/video/tests/ffv1.rs | 304 +++++++++++ 6 files changed, 1524 insertions(+) create mode 100644 crates/video/src/ffv1/README.md create mode 100644 crates/video/src/ffv1/mod.rs create mode 100644 crates/video/src/ffv1/rc.rs create mode 100644 crates/video/tests/ffv1.rs diff --git a/crates/video/Cargo.toml b/crates/video/Cargo.toml index c3ebfd722..dae21e5b1 100644 --- a/crates/video/Cargo.toml +++ b/crates/video/Cargo.toml @@ -34,6 +34,8 @@ mpeg2-encode = ["mpeg2-decode"] # MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder. mpeg4 = ["mpeg4-encode"] mpeg4-encode = ["craft-media/bitstream"] +# FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder. +ffv1 = [] # Apple ProRes (SMPTE RDD 36): decoder and encoder. prores = ["craft-media/bitstream"] # H.264 / AVC: decoder and encoder; `h264-decode` or `h264-encode` for one of them. @@ -143,6 +145,10 @@ required-features = ["mpeg4-encode"] name = "mpeg2" required-features = ["mpeg2-decode"] +[[test]] +name = "ffv1" +required-features = ["ffv1"] + [[test]] name = "prores" required-features = ["prores"] diff --git a/crates/video/src/ffv1/README.md b/crates/video/src/ffv1/README.md new file mode 100644 index 000000000..90312dbe5 --- /dev/null +++ b/crates/video/src/ffv1/README.md @@ -0,0 +1,52 @@ +# FFV1 + +Clean-room FFV1 lossless video codec, written from RFC 9043. Feature `ffv1`. + +## What is supported + +| | Decoder | Encoder | +|---|---|---| +| Version | 3 (the one with a configuration record) | 3 | +| Coder | range coder, default or custom state transition table | range coder, default table | +| Colour | YCbCr (any 2^n chroma subsampling, gray, optional transparency), RGB through the JPEG 2000 reversible colour transform (optional transparency) | the same, RGB up to 15 bits | +| Depth | 8 to 16 bits per sample | 8 to 16 bits (RGB 8 to 15) | +| Slices | any raster whose boundaries are multiples of the chroma subsampling | the same | +| Frames | keyframes | keyframes only (`intra` 1) | +| Error detection | slice and configuration record CRCs, checked | written | + +Not supported, and reported as `Error::Unsupported`: the Golomb-Rice coder (`coder_type` 0), +versions 0 and 1 (parameters inside each keyframe, no configuration record), inter frames +(`keyframe` 0), and slice rasters whose boundaries fall inside a chroma sample. + +## Using it + +The configuration record goes in the container (Matroska `CodecPrivate`, the AVI `strf` +extension, an MP4 `glbl` box); each frame is one packet. + +```text +let enc = Encoder::new(&template_frame, EncoderConfig::default())?; +let config = enc.config_record(); +let packet = enc.encode(&frame)?; + +let dec = Decoder::new(&config, width, height)?; +let frame = dec.decode(&packet)?; +``` + +## Notes on the format + +- The Parameters in the configuration record are range coded with the *default* state transition + table. A custom table (`coder_type` 2) applies to the slices only. +- Each Quantization Table starts from fresh states; a Quantization Table Set is five of them. +- A slice is one range-coded stream: for the first slice the `keyframe` bit, then the slice header, + then the samples. Cb and Cr share one set of context states; transparency has its own. +- The context is the sum of five quantised differences. With the default tables this encoder + writes 15125 contexts; FFmpeg refuses tables that multiply to more than 32768, so the encoder + stays below that although the RFC's limit (on half the product) is looser. +- The encoder ends a stream with the top of its final range, so bytes after it (a CRC in the + configuration record) cannot change what decodes. + +## Verification + +`tests/ffv1.rs`: round trips over every shape, hostile input (every truncation and bit flip), +and ffmpeg as the oracle in both directions (skipped without ffmpeg, a failure with +`CRAFT_MEDIA_REQUIRE_ORACLES=1`). diff --git a/crates/video/src/ffv1/mod.rs b/crates/video/src/ffv1/mod.rs new file mode 100644 index 000000000..4df60f9a1 --- /dev/null +++ b/crates/video/src/ffv1/mod.rs @@ -0,0 +1,929 @@ +//! FFV1 lossless video codec (RFC 9043): version 3, range coder, intra-only, YCbCr and RGB (JPEG 2000 +//! RCT), 8 to 16 bits per sample, any number of slices. +//! +//! - [`Decoder`]: built from the *configuration record* a container stores (Matroska `CodecPrivate`, +//! AVI `strf` extension, MP4 `glbl`) and the frame size; [`Decoder::decode`] turns one packet into a +//! [`Frame`]. Slice CRCs are checked. +//! - [`Encoder`]: [`Encoder::config_record`] gives the bytes for the container, [`Encoder::encode`] +//! one packet per frame; every frame is a keyframe. +//! +//! Not supported (reported as [`Error::Unsupported`]): the Golomb-Rice coder (`coder_type` 0), +//! versions 0 and 1 (no configuration record, parameters in every keyframe), inter frames +//! (`intra` 0 with `keyframe` 0), and slice rasters whose boundaries are not multiples of the +//! chroma subsampling. See `src/ffv1/README.md`. +//! +//! Implemented from RFC 9043. Frames are planar `u16`: for YCbCr, `[Y, Cb, Cr]` (plus an optional +//! transparency plane); for RGB, `[R, G, B]` (plus transparency), all at full size. + +mod rc; + +use crate::budget::{DECODE_MEMORY_BUDGET, PictureShape}; +use rc::{Decoder as Rac, Encoder as RacEnc, Transitions}; + +const CONTEXT_SIZE: usize = 32; +const MAX_CONTEXT_INPUTS: usize = 5; +const MAX_CONTEXTS: u64 = 32768; + +/// Codec errors. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The data ends early or its sizes do not add up. + #[error("truncated FFV1 data")] + Truncated, + /// The data is not valid FFV1. + #[error("invalid FFV1 data: {0}")] + Invalid(&'static str), + /// Valid FFV1 that this module does not decode. + #[error("unsupported FFV1 feature: {0}")] + Unsupported(&'static str), + /// A slice or the configuration record failed its CRC. + #[error("FFV1 CRC mismatch in {0}")] + Crc(&'static str), + /// The encoder was given a frame or settings it cannot encode. + #[error("invalid encoder input: {0}")] + Input(String), +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The colour space coded (RFC 9043 table 8). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Colorspace { + /// YCbCr, coded plane by plane without a pixel transform. + YCbCr, + /// RGB through the JPEG 2000 reversible colour transform, coded line by line. + Rgb, +} + +/// One frame of planar samples. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Frame { + /// Width in pixels. + pub width: u32, + /// Height in pixels. + pub height: u32, + /// Colour space of the planes. + pub colorspace: Colorspace, + /// Bits per sample, 8 to 16. + pub bit_depth: u8, + /// log2 of the horizontal and vertical chroma subsampling (YCbCr only; 0, 0 is 4:4:4). + pub chroma_shift: (u8, u8), + /// The planes, in the order the module doc gives. + pub planes: Vec>, +} + +impl Frame { + /// Whether the planes are Y, Cb, Cr (or R, G, B) rather than Y (gray) alone, or with transparency. + fn plane_count_ok(&self) -> bool { + matches!(self.planes.len(), 1..=4) + } + + fn dims(&self, plane: usize, chroma_planes: bool) -> (usize, usize) { + plane_dims(self.width as usize, self.height as usize, self.colorspace, self.chroma_shift, plane, chroma_planes) + } +} + +/// `(width, height)` of plane `p` for a full frame (or a slice) of `w` x `h`. +fn plane_dims(w: usize, h: usize, cs: Colorspace, shift: (u8, u8), p: usize, chroma_planes: bool) -> (usize, usize) { + if cs == Colorspace::YCbCr && chroma_planes && (p == 1 || p == 2) { (w.div_ceil(1 << shift.0), h.div_ceil(1 << shift.1)) } else { (w, h) } +} + +/// One Quantization Table Set (section 4.1). +#[derive(Clone)] +struct QuantSet { + tables: Vec<[i32; 256]>, + context_count: usize, +} + +/// The parsed "Parameters" of a stream. +#[derive(Clone)] +struct Params { + coder_type: u32, + transitions: Transitions, + colorspace: Colorspace, + bits: u32, + chroma_planes: bool, + shift: (u8, u8), + extra_plane: bool, + num_h: u32, + num_v: u32, + sets: Vec, + initial_states: Vec>>, + ec: bool, + intra: bool, +} + +impl Params { + fn plane_count(&self) -> usize { + 1 + if self.chroma_planes { 2 } else { 0 } + usize::from(self.extra_plane) + } + + /// Quantization Table Set index slot of plane `p` (section 3.6). + fn qset_slot(&self, p: usize) -> usize { + match p { + 0 => 0, + 1 | 2 if self.chroma_planes => 1, + _ => 2, + } + } +} + +fn crc32(data: &[u8]) -> u32 { + // The IEEE polynomial 0x04C11DB7, initial value 0, no reflection, no final inversion. + let mut crc = 0u32; + for &b in data { + crc ^= u32::from(b) << 24; + for _ in 0..8 { + crc = if crc & 0x8000_0000 != 0 { crc << 1 ^ 0x04C1_1DB7 } else { crc << 1 }; + } + } + crc +} + +// ---- Parameters ---- + +fn read_quant_set(rac: &mut Rac, t: &Transitions) -> Result { + let mut scale: u64 = 1; + let mut tables = Vec::with_capacity(MAX_CONTEXT_INPUTS); + for _ in 0..MAX_CONTEXT_INPUTS { + let mut table = [0i32; 256]; + // Each quantization table starts from fresh states. + let mut state = [128u8; CONTEXT_SIZE]; + let mut v: i64 = 0; + let mut k = 0usize; + while k < 128 { + let len = rac.symbol(&mut state, false, t) as usize + 1; + if k + len > 128 { + return Err(Error::Invalid("quantization table run passes its half")); + } + for _ in 0..len { + table[k] = i32::try_from(scale as i64 * v).map_err(|_| Error::Invalid("quantization table overflows"))?; + k += 1; + } + v += 1; + } + for k in 1..128 { + table[256 - k] = -table[k]; + } + table[128] = -table[127]; + tables.push(table); + scale = scale.checked_mul(2 * v as u64 - 1).filter(|&s| s <= 2 * MAX_CONTEXTS).ok_or(Error::Invalid("too many contexts"))?; + } + let context_count = scale.div_ceil(2); + if context_count > MAX_CONTEXTS { + return Err(Error::Invalid("too many contexts")); + } + Ok(QuantSet { tables, context_count: context_count as usize }) +} + +fn parse_params(rac: &mut Rac) -> Result { + let mut state = [128u8; CONTEXT_SIZE]; + // Until the custom table is known, the default table decodes the fields before it. + let t0 = Transitions::default_table(); + let version = rac.symbol(&mut state, false, &t0); + if version != 3 { + return Err(Error::Unsupported("only FFV1 version 3 has a configuration record; versions 0 and 1 are not supported")); + } + let _micro = rac.symbol(&mut state, false, &t0); + let coder_type = rac.symbol(&mut state, false, &t0) as u32; + let mut delta = [0i32; 256]; + if coder_type > 1 { + for d in delta.iter_mut().skip(1) { + *d = rac.symbol(&mut state, true, &t0); + } + } + let transitions = Transitions::new(&delta); + if coder_type == 0 { + return Err(Error::Unsupported("the Golomb-Rice coder (coder_type 0)")); + } + if coder_type > 2 { + return Err(Error::Invalid("unknown coder_type")); + } + let colorspace = match rac.symbol(&mut state, false, &t0) { + 0 => Colorspace::YCbCr, + 1 => Colorspace::Rgb, + _ => return Err(Error::Unsupported("colorspace_type")), + }; + let bits = rac.symbol(&mut state, false, &t0) as u32; + let bits = if bits == 0 { 8 } else { bits }; + let chroma_planes = rac.bit(&mut state[0], &t0); + let (h, v) = (rac.symbol(&mut state, false, &t0), rac.symbol(&mut state, false, &t0)); + let extra_plane = rac.bit(&mut state[0], &t0); + let num_h = rac.symbol(&mut state, false, &t0) as u32 + 1; + let num_v = rac.symbol(&mut state, false, &t0) as u32 + 1; + let set_count = rac.symbol(&mut state, false, &t0); + if !(8..=16).contains(&bits) || h > 3 || v > 3 || h < 0 || v < 0 || num_h > 1024 || num_v > 1024 || !(1..=8).contains(&set_count) { + return Err(Error::Invalid("parameter out of range")); + } + if colorspace == Colorspace::Rgb && (!chroma_planes || h != 0 || v != 0) { + return Err(Error::Unsupported("RGB with chroma_planes 0 or subsampling")); + } + let mut sets = Vec::new(); + for _ in 0..set_count { + // The Parameters are range coded with the default table; the custom one is for the slices. + sets.push(read_quant_set(rac, &t0)?); + } + let mut initial_states = Vec::new(); + for set in &sets { + if rac.bit(&mut state[0], &t0) { + let mut all = Vec::with_capacity(set.context_count); + let mut prev = [128u8; CONTEXT_SIZE]; + for _ in 0..set.context_count { + let mut cur = [0u8; CONTEXT_SIZE]; + for k in 0..CONTEXT_SIZE { + let d = rac.symbol(&mut state, true, &t0); + cur[k] = (i32::from(prev[k]) + d) as u8; + } + prev = cur; + all.push(cur); + } + initial_states.push(Some(all)); + } else { + initial_states.push(None); + } + } + let ec = rac.symbol(&mut state, false, &t0) != 0; + let intra = rac.symbol(&mut state, false, &t0) != 0; + Ok(Params { + coder_type, + transitions, + colorspace, + bits, + chroma_planes, + shift: (h as u8, v as u8), + extra_plane, + num_h, + num_v, + sets, + initial_states, + ec, + intra, + }) +} + +/// The default quantisation tables of this encoder: 11 levels for the two gradients next to the +/// sample and 5 for the other three, which makes 15125 contexts (FFmpeg refuses more than 32768). +fn default_quant_set() -> QuantSet { + // |difference| thresholds: the first |d| of each level above 0 (levels 0..=5 and 0..=2). + let first_of_level: [&[usize]; MAX_CONTEXT_INPUTS] = [&[1, 2, 4, 8, 16], &[1, 2, 4, 8, 16], &[1, 3], &[1, 3], &[1, 3]]; + let mut scale: i32 = 1; + let mut tables = Vec::new(); + let mut counts = [0usize; MAX_CONTEXT_INPUTS]; + for (j, firsts) in first_of_level.iter().enumerate() { + let mut table = [0i32; 256]; + for (k, slot) in table.iter_mut().take(128).enumerate() { + let level = firsts.iter().filter(|&&f| k >= f).count() as i32; + *slot = scale * level; + } + for k in 1..128 { + table[256 - k] = -table[k]; + } + table[128] = -table[127]; + counts[j] = firsts.len() + 1; + scale *= 2 * counts[j] as i32 - 1; + tables.push(table); + } + QuantSet { tables, context_count: (scale as usize).div_ceil(2) } +} + +/// Run lengths (`len - 1` per step) that describe the first half of a table, as written to the stream. +fn quant_runs(table: &[i32; 256]) -> Vec { + let mut runs = Vec::new(); + let mut k = 0usize; + while k < 128 { + let start = k; + while k < 128 && table[k] == table[start] { + k += 1; + } + runs.push((k - start) as i32 - 1); + } + runs +} + +fn write_params(enc: &mut RacEnc, p: &Params) { + let t = Transitions::default_table(); + let mut state = [128u8; CONTEXT_SIZE]; + enc.symbol(&mut state, 3, false, &t); // version + enc.symbol(&mut state, 4, false, &t); // micro_version: first stable variant + enc.symbol(&mut state, p.coder_type as i32, false, &t); + enc.symbol(&mut state, if p.colorspace == Colorspace::YCbCr { 0 } else { 1 }, false, &t); + enc.symbol(&mut state, p.bits as i32, false, &t); + enc.bit(p.chroma_planes, &mut state[0], &t); + enc.symbol(&mut state, i32::from(p.shift.0), false, &t); + enc.symbol(&mut state, i32::from(p.shift.1), false, &t); + enc.bit(p.extra_plane, &mut state[0], &t); + enc.symbol(&mut state, p.num_h as i32 - 1, false, &t); + enc.symbol(&mut state, p.num_v as i32 - 1, false, &t); + enc.symbol(&mut state, p.sets.len() as i32, false, &t); + for set in &p.sets { + for table in &set.tables { + let mut qstate = [128u8; CONTEXT_SIZE]; + for run in quant_runs(table) { + enc.symbol(&mut qstate, run, false, &t); + } + } + } + for _ in &p.sets { + enc.bit(false, &mut state[0], &t); // states_coded + } + enc.symbol(&mut state, i32::from(p.ec), false, &t); + enc.symbol(&mut state, i32::from(p.intra), false, &t); +} + +// ---- slices ---- + +/// A slice's place in the frame, in pixels. +#[derive(Clone, Copy)] +struct SliceRect { + x: usize, + y: usize, + w: usize, + h: usize, +} + +fn slice_rect(p: &Params, width: usize, height: usize, sx: usize, sy: usize, sw: usize, sh: usize) -> Result { + let (nh, nv) = (p.num_h as usize, p.num_v as usize); + if sx + sw > nh || sy + sh > nv || sw == 0 || sh == 0 { + return Err(Error::Invalid("slice outside the slice raster")); + } + let x0 = sx * width / nh; + let x1 = (sx + sw) * width / nh; + let y0 = sy * height / nv; + let y1 = (sy + sh) * height / nv; + if x1 <= x0 || y1 <= y0 { + return Err(Error::Invalid("empty slice")); + } + Ok(SliceRect { x: x0, y: y0, w: x1 - x0, h: y1 - y0 }) +} + +/// The samples of one plane of a slice with the border of RFC 9043 section 3.1 around them: two +/// columns to the left, one to the right, two rows above. +struct Border { + buf: Vec, + stride: usize, + w: usize, +} + +impl Border { + fn new(w: usize, h: usize) -> Border { + let stride = w + 3; + Border { buf: vec![0; stride * (h + 2)], stride, w } + } + + fn at(&self, x: usize, y: usize) -> usize { + (y + 2) * self.stride + x + 2 + } + + /// Set up the left border of row `y` (the column left of it repeats the row above's first sample). + fn start_row(&mut self, y: usize) { + let row = (y + 2) * self.stride; + self.buf[row] = 0; + self.buf[row + 1] = if y > 0 { self.buf[(y + 1) * self.stride + 2] } else { 0 }; + } + + /// The right border of row `y` repeats its last sample. + fn end_row(&mut self, y: usize) { + let row = (y + 2) * self.stride; + self.buf[row + self.w + 2] = self.buf[row + self.w + 1]; + } + + /// `(context, predictor)` for sample `(x, y)`; `context` is signed (section 3.5). + fn context(&self, x: usize, y: usize, tables: &[[i32; 256]], sixteen_bit_ycbcr: bool) -> (i32, i32) { + let i = self.at(x, y); + let (b, s) = (&self.buf, self.stride); + let (l, ll, t, tl, tr, tt) = (b[i - 1], b[i - 2], b[i - s], b[i - s - 1], b[i - s + 1], b[i - 2 * s]); + let ctx = tables[0][((l - tl) & 255) as usize] + + tables[1][((tl - t) & 255) as usize] + + tables[2][((t - tr) & 255) as usize] + + tables[3][((ll - l) & 255) as usize] + + tables[4][((tt - t) & 255) as usize]; + let (pl, pt, ptl) = if sixteen_bit_ycbcr { + let s16 = |v: i32| if v >= 32768 { v - 65536 } else { v }; + (s16(l), s16(t), s16(tl)) + } else { + (l, t, tl) + }; + (ctx, median(pl, pt, pl + pt - ptl)) + } +} + +fn median(a: i32, b: i32, c: i32) -> i32 { + a.max(b).min(a.min(b).max(c)) +} + +/// The reversible colour transform bits: a plane's samples have `bits + 1` bits. +fn rct_swapped(p: &Params) -> bool { + p.colorspace == Colorspace::Rgb && (9..=15).contains(&p.bits) && !p.extra_plane +} + +fn coded_bits(p: &Params) -> u32 { + if p.colorspace == Colorspace::Rgb { p.bits + 1 } else { p.bits } +} + +/// One plane's samples inside a slice, and which class of states codes them. +struct PlaneCoder { + border: Border, + slot: usize, +} + +/// The adaptive states of one plane class: Y, Cb and Cr together, then transparency (section 3.6). +struct ClassStates { + set: usize, + states: Vec<[u8; CONTEXT_SIZE]>, +} + +fn make_coders(p: &Params, rect: SliceRect, set_idx: &[usize]) -> Result<(Vec, Vec)> { + let mut planes = Vec::new(); + for pl in 0..p.plane_count() { + let (w, h) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + planes.push(PlaneCoder { border: Border::new(w, h), slot: p.qset_slot(pl) }); + } + let mut classes = Vec::new(); + for slot in 0..=planes.iter().map(|c| c.slot).max().unwrap_or(0) { + let set = *set_idx.get(slot).ok_or(Error::Invalid("missing quant table set index"))?; + let q = p.sets.get(set).ok_or(Error::Invalid("quant table set index out of range"))?; + let states = match p.initial_states.get(set) { + Some(Some(init)) => init.clone(), + _ => vec![[128u8; CONTEXT_SIZE]; q.context_count], + }; + classes.push(ClassStates { set, states }); + } + Ok((planes, classes)) +} + +/// The number of Quantization Table Set indexes in a slice header (section 4.6.5, version 3). +fn set_index_count(p: &Params) -> usize { + 2 + usize::from(p.extra_plane) +} + +fn check_frame_size(p: &Params, w: u32, h: u32) -> Result<()> { + if w == 0 || h == 0 { + return Err(Error::Invalid("empty frame")); + } + let shape = PictureShape { + width: u64::from(w), + height: u64::from(h), + shift_x: u32::from(p.shift.0.min(1)), + shift_y: u32::from(p.shift.1.min(1)), + chroma_planes: if p.chroma_planes { 2 } else { 0 }, + bytes_per_sample: 2, + }; + // The decoded planes and, while a slice decodes, its bordered `i32` copy (2 x the samples at most). + if !shape.fits(5, DECODE_MEMORY_BUDGET) { + return Err(Error::Unsupported("frame size above the memory budget")); + } + if p.shift.0 > 1 || p.shift.1 > 1 { + // Subsampling beyond 2:1 is legal FFV1 (e.g. 4:1:1) but the budget model above is for 2:1. + let extra = (w as u64).checked_mul(h as u64).ok_or(Error::Invalid("frame too large"))?; + if extra > 1 << 28 { + return Err(Error::Unsupported("frame size above the memory budget")); + } + } + Ok(()) +} + +/// A decoder for one stream. +pub struct Decoder { + params: Params, + width: u32, + height: u32, +} + +impl Decoder { + /// Build a decoder from the container's configuration record and the frame size. + pub fn new(config_record: &[u8], width: u32, height: u32) -> Result { + if config_record.len() < 5 { + return Err(Error::Truncated); + } + let (body, _crc) = config_record.split_at(config_record.len() - 4); + if crc32(config_record) != 0 { + return Err(Error::Crc("the configuration record")); + } + let mut rac = Rac::new(body); + let params = parse_params(&mut rac)?; + if rac.consumed() > body.len() + 2 { + return Err(Error::Truncated); + } + check_frame_size(¶ms, width, height)?; + Ok(Decoder { params, width, height }) + } + + /// Decode one frame (a packet from the container). + pub fn decode(&self, packet: &[u8]) -> Result { + let p = &self.params; + let (w, h) = (self.width as usize, self.height as usize); + let planes = p.plane_count(); + let mut frame = Frame { + width: self.width, + height: self.height, + colorspace: p.colorspace, + bit_depth: p.bits as u8, + chroma_shift: if p.chroma_planes { p.shift } else { (0, 0) }, + planes: Vec::with_capacity(planes), + }; + for pl in 0..planes { + let (pw, ph) = plane_dims(w, h, p.colorspace, p.shift, pl, p.chroma_planes); + let mut v = Vec::new(); + v.try_reserve_exact(pw * ph).map_err(|_| Error::Unsupported("frame size above the memory budget"))?; + v.resize(pw * ph, 0u16); + frame.planes.push(v); + } + // Slices are found from the end of the packet through their footers (section 4.9). + let trailer = if p.ec { 8 } else { 3 }; + let slice_count = p.num_h as usize * p.num_v as usize; + let mut end = packet.len(); + let mut spans = Vec::with_capacity(slice_count); + for _ in 0..slice_count { + if end < trailer { + return Err(Error::Truncated); + } + let f = end - trailer; + let size = usize::from(packet[f]) << 16 | usize::from(packet[f + 1]) << 8 | usize::from(packet[f + 2]); + let start = f.checked_sub(size).ok_or(Error::Truncated)?; + spans.push((start, end)); + end = start; + } + spans.reverse(); + for (n, &(start, stop)) in spans.iter().enumerate() { + let slice = &packet[start..stop]; + if p.ec && crc32(slice) != 0 { + return Err(Error::Crc("a slice")); + } + self.decode_slice(slice, n == 0, &mut frame)?; + } + Ok(frame) + } + + fn decode_slice(&self, slice: &[u8], first: bool, frame: &mut Frame) -> Result<()> { + let p = &self.params; + let t = &p.transitions; + let data = &slice[..slice.len() - if p.ec { 8 } else { 3 }]; + let mut rac = Rac::new(data); + // The keyframe flag is the first symbol of the first slice. + // The whole slice, header included, is coded with the stream's state transition table. + let t0 = t; + if first { + let mut ks = 128u8; + if !rac.bit(&mut ks, t0) { + return Err(Error::Unsupported("inter frames (keyframe 0)")); + } + } + let mut hs = [128u8; CONTEXT_SIZE]; + let sx = rac.symbol(&mut hs, false, t0) as usize; + let sy = rac.symbol(&mut hs, false, t0) as usize; + let sw = rac.symbol(&mut hs, false, t0) as usize + 1; + let sh = rac.symbol(&mut hs, false, t0) as usize + 1; + let set_idx: Vec = (0..set_index_count(p)).map(|_| rac.symbol(&mut hs, false, t0).max(0) as usize).collect(); + let _picture_structure = rac.symbol(&mut hs, false, t0); + let _sar = (rac.symbol(&mut hs, false, t0), rac.symbol(&mut hs, false, t0)); + let rect = slice_rect(p, self.width as usize, self.height as usize, sx, sy, sw, sh)?; + let (sx_mask, sy_mask) = ((1usize << p.shift.0) - 1, (1usize << p.shift.1) - 1); + if p.colorspace == Colorspace::YCbCr && p.chroma_planes && (rect.x & sx_mask != 0 || rect.y & sy_mask != 0) { + return Err(Error::Unsupported("slice boundaries that are not multiples of the chroma subsampling")); + } + let (mut coders, mut classes) = make_coders(p, rect, &set_idx)?; + let bits = coded_bits(p); + let mask = (1i32 << bits) - 1; + let sixteen = p.colorspace == Colorspace::YCbCr && p.bits == 16; + let read = |rac: &mut Rac, c: &mut PlaneCoder, cls: &mut ClassStates, x: usize, y: usize| -> i32 { + let q = &p.sets[cls.set]; + let (ctx, pred) = c.border.context(x, y, &q.tables, sixteen); + let (idx, neg) = if ctx < 0 { ((-ctx) as usize, true) } else { (ctx as usize, false) }; + let mut d = rac.symbol(&mut cls.states[idx.min(q.context_count - 1)], true, t); + if neg { + d = -d; + } + let v = (pred + d) & mask; + let at = c.border.at(x, y); + c.border.buf[at] = v; + v + }; + match p.colorspace { + Colorspace::YCbCr => { + for (pl, c) in coders.iter_mut().enumerate() { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + for y in 0..ph { + c.border.start_row(y); + for x in 0..pw { + read(&mut rac, c, &mut classes[c.slot], x, y); + } + c.border.end_row(y); + } + } + } + Colorspace::Rgb => { + for y in 0..rect.h { + for c in coders.iter_mut() { + c.border.start_row(y); + for x in 0..rect.w { + read(&mut rac, c, &mut classes[c.slot], x, y); + } + c.border.end_row(y); + } + } + } + } + self.store(&coders, rect, frame); + Ok(()) + } + + /// Copy a decoded slice into the frame, undoing the colour transform for RGB. + fn store(&self, coders: &[PlaneCoder], rect: SliceRect, frame: &mut Frame) { + let p = &self.params; + if p.colorspace == Colorspace::YCbCr { + for (pl, c) in coders.iter().enumerate() { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + let (fw, _) = plane_dims(self.width as usize, self.height as usize, p.colorspace, p.shift, pl, p.chroma_planes); + let (ox, oy) = if p.chroma_planes && (pl == 1 || pl == 2) { (rect.x >> p.shift.0, rect.y >> p.shift.1) } else { (rect.x, rect.y) }; + for y in 0..ph { + for x in 0..pw { + frame.planes[pl][(oy + y) * fw + ox + x] = c.border.buf[c.border.at(x, y)] as u16; + } + } + } + return; + } + let swapped = rct_swapped(p); + let off = 1i32 << p.bits; + let fw = self.width as usize; + for y in 0..rect.h { + for x in 0..rect.w { + let get = |i: usize| coders[i].border.buf[coders[i].border.at(x, y)]; + let (yy, cb, cr) = (get(0), get(1) - off, get(2) - off); + let (r, g, b); + if swapped { + let bb = yy - ((cb + cr) >> 2); + r = cr + bb; + g = cb + bb; + b = bb; + } else { + let gg = yy - ((cb + cr) >> 2); + r = cr + gg; + g = gg; + b = cb + gg; + } + let at = (rect.y + y) * fw + rect.x + x; + frame.planes[0][at] = r as u16; + frame.planes[1][at] = g as u16; + frame.planes[2][at] = b as u16; + if coders.len() > 3 { + frame.planes[3][at] = get(3) as u16; + } + } + } + } +} + +/// Encoder settings. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct EncoderConfig { + /// Slices across the frame. + pub slices_h: u32, + /// Slices down the frame. + pub slices_v: u32, + /// Write a CRC in every slice (error detection). + pub slice_crc: bool, +} + +impl Default for EncoderConfig { + fn default() -> Self { + EncoderConfig { slices_h: 1, slices_v: 1, slice_crc: true } + } +} + +/// An encoder for frames of one fixed format. +pub struct Encoder { + params: Params, + width: u32, + height: u32, +} + +impl Encoder { + /// An encoder for frames shaped like `template` (its samples are not used). + pub fn new(template: &Frame, cfg: EncoderConfig) -> Result { + if !template.plane_count_ok() || template.width == 0 || template.height == 0 { + return Err(Error::Input("a frame has 1 to 4 planes and a nonzero size".into())); + } + if !(8..=16).contains(&template.bit_depth) { + return Err(Error::Input("bit depth must be 8 to 16".into())); + } + if cfg.slices_h == 0 + || cfg.slices_v == 0 + || cfg.slices_h > 1024 + || cfg.slices_v > 1024 + || cfg.slices_h > template.width + || cfg.slices_v > template.height + { + return Err(Error::Input("invalid slice raster".into())); + } + let n = template.planes.len(); + let (chroma_planes, extra_plane) = match (template.colorspace, n) { + (Colorspace::YCbCr, 1) => (false, false), + (Colorspace::YCbCr, 2) => (false, true), + (Colorspace::YCbCr, 3) => (true, false), + (Colorspace::YCbCr, _) => (true, true), + (Colorspace::Rgb, 3) => (true, false), + (Colorspace::Rgb, 4) => (true, true), + (Colorspace::Rgb, _) => return Err(Error::Input("RGB frames have 3 or 4 planes".into())), + }; + let shift = if template.colorspace == Colorspace::YCbCr && chroma_planes { template.chroma_shift } else { (0, 0) }; + if shift.0 > 3 || shift.1 > 3 { + return Err(Error::Input("chroma subsampling above 8:1".into())); + } + if template.colorspace == Colorspace::Rgb && template.bit_depth > 15 { + return Err(Error::Input("RGB above 15 bits needs 17-bit coded samples".into())); + } + let params = Params { + coder_type: 1, + transitions: Transitions::default_table(), + colorspace: template.colorspace, + bits: u32::from(template.bit_depth), + chroma_planes, + shift, + extra_plane, + num_h: cfg.slices_h, + num_v: cfg.slices_v, + sets: vec![default_quant_set()], + initial_states: vec![None], + ec: cfg.slice_crc, + intra: true, + }; + // Every slice boundary must be a multiple of the chroma subsampling, so the decoder accepts it. + for i in 0..=cfg.slices_h as usize { + if params.chroma_planes && (i * template.width as usize / cfg.slices_h as usize) & ((1 << shift.0) - 1) != 0 && i != cfg.slices_h as usize + { + return Err(Error::Input("slice boundaries must be multiples of the chroma subsampling".into())); + } + } + for i in 0..cfg.slices_v as usize { + if params.chroma_planes && (i * template.height as usize / cfg.slices_v as usize) & ((1 << shift.1) - 1) != 0 { + return Err(Error::Input("slice boundaries must be multiples of the chroma subsampling".into())); + } + } + Ok(Encoder { params, width: template.width, height: template.height }) + } + + /// The configuration record for the container (`CodecPrivate` and the like). + pub fn config_record(&self) -> Vec { + let mut enc = RacEnc::new(); + write_params(&mut enc, &self.params); + let mut out = enc.finish(); + let crc = crc32(&out); + out.extend_from_slice(&crc.to_be_bytes()); + out + } + + /// Encode one frame as a keyframe packet. + pub fn encode(&self, frame: &Frame) -> Result> { + let p = &self.params; + if frame.width != self.width || frame.height != self.height || frame.colorspace != p.colorspace || u32::from(frame.bit_depth) != p.bits { + return Err(Error::Input("the frame does not match the encoder's format".into())); + } + if frame.planes.len() != p.plane_count() { + return Err(Error::Input("the frame has the wrong number of planes".into())); + } + let shift = if p.chroma_planes { p.shift } else { (0, 0) }; + if p.colorspace == Colorspace::YCbCr && p.chroma_planes && frame.chroma_shift != shift { + return Err(Error::Input("the chroma subsampling does not match".into())); + } + for (pl, plane) in frame.planes.iter().enumerate() { + let (w, h) = frame.dims(pl, p.chroma_planes); + if plane.len() != w * h { + return Err(Error::Input(format!("plane {pl} has {} samples, expected {}", plane.len(), w * h))); + } + if plane.iter().any(|&v| u32::from(v) >> p.bits != 0) { + return Err(Error::Input(format!("plane {pl} has a sample above {} bits", p.bits))); + } + } + let mut out = Vec::new(); + for sy in 0..p.num_v as usize { + for sx in 0..p.num_h as usize { + let rect = slice_rect(p, self.width as usize, self.height as usize, sx, sy, 1, 1)?; + let mut slice = self.encode_slice(frame, rect, sx, sy, out.is_empty())?; + let size = slice.len(); + slice.extend_from_slice(&(size as u32).to_be_bytes()[1..]); + if p.ec { + slice.push(0); // error_status + let crc = crc32(&slice); + slice.extend_from_slice(&crc.to_be_bytes()); + } + out.extend_from_slice(&slice); + } + } + Ok(out) + } + + fn encode_slice(&self, frame: &Frame, rect: SliceRect, sx: usize, sy: usize, first: bool) -> Result> { + let p = &self.params; + let t = &p.transitions; + let t0 = t; + let mut rac = RacEnc::new(); + if first { + let mut ks = 128u8; + rac.bit(true, &mut ks, t0); + } + let mut hs = [128u8; CONTEXT_SIZE]; + for v in [sx as i32, sy as i32, 0, 0] { + rac.symbol(&mut hs, v, false, t0); + } + let set_idx = vec![0usize; set_index_count(p)]; + for &s in &set_idx { + rac.symbol(&mut hs, s as i32, false, t0); + } + for v in [0, 0, 0] { + rac.symbol(&mut hs, v, false, t0); // picture_structure, sar_num, sar_den + } + let (mut coders, mut classes) = make_coders(p, rect, &set_idx)?; + let bits = coded_bits(p); + let half = 1i32 << (bits - 1); + let mask = (1i32 << bits) - 1; + let sixteen = p.colorspace == Colorspace::YCbCr && p.bits == 16; + // The samples to code, one bordered plane's worth per coder. + let values = self.slice_values(frame, rect); + let write = |rac: &mut RacEnc, c: &mut PlaneCoder, cls: &mut ClassStates, x: usize, y: usize, sample: i32| { + let q = &p.sets[cls.set]; + let (ctx, pred) = c.border.context(x, y, &q.tables, sixteen); + let mut d = ((sample - pred + half) & mask) - half; + let (idx, neg) = if ctx < 0 { ((-ctx) as usize, true) } else { (ctx as usize, false) }; + if neg { + d = -d; + } + rac.symbol(&mut cls.states[idx.min(q.context_count - 1)], d, true, t); + let at = c.border.at(x, y); + c.border.buf[at] = sample; + }; + match p.colorspace { + Colorspace::YCbCr => { + for (pl, c) in coders.iter_mut().enumerate() { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + for y in 0..ph { + c.border.start_row(y); + for x in 0..pw { + write(&mut rac, c, &mut classes[c.slot], x, y, values[pl][y * pw + x]); + } + c.border.end_row(y); + } + } + } + Colorspace::Rgb => { + for y in 0..rect.h { + for (pl, c) in coders.iter_mut().enumerate() { + c.border.start_row(y); + for x in 0..rect.w { + write(&mut rac, c, &mut classes[c.slot], x, y, values[pl][y * rect.w + x]); + } + c.border.end_row(y); + } + } + } + } + Ok(rac.finish()) + } + + /// The slice's samples per coded plane (after the colour transform for RGB). + fn slice_values(&self, frame: &Frame, rect: SliceRect) -> Vec> { + let p = &self.params; + let fw = self.width as usize; + if p.colorspace == Colorspace::YCbCr { + return (0..p.plane_count()) + .map(|pl| { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + let (full_w, _) = plane_dims(fw, self.height as usize, p.colorspace, p.shift, pl, p.chroma_planes); + let (ox, oy) = + if p.chroma_planes && (pl == 1 || pl == 2) { (rect.x >> p.shift.0, rect.y >> p.shift.1) } else { (rect.x, rect.y) }; + let mut v = Vec::with_capacity(pw * ph); + for y in 0..ph { + for x in 0..pw { + v.push(i32::from(frame.planes[pl][(oy + y) * full_w + ox + x])); + } + } + v + }) + .collect(); + } + let swapped = rct_swapped(p); + let off = 1i32 << p.bits; + let mut planes = vec![Vec::with_capacity(rect.w * rect.h); p.plane_count()]; + for y in 0..rect.h { + for x in 0..rect.w { + let at = (rect.y + y) * fw + rect.x + x; + let (r, g, b) = (i32::from(frame.planes[0][at]), i32::from(frame.planes[1][at]), i32::from(frame.planes[2][at])); + let (yy, cb, cr) = if swapped { + let (cb, cr) = (g - b, r - b); + (b + ((cb + cr) >> 2), cb, cr) + } else { + let (cb, cr) = (b - g, r - g); + (g + ((cb + cr) >> 2), cb, cr) + }; + planes[0].push(yy); + planes[1].push(cb + off); + planes[2].push(cr + off); + if p.extra_plane { + planes[3].push(i32::from(frame.planes[3][at])); + } + } + } + planes + } +} diff --git a/crates/video/src/ffv1/rc.rs b/crates/video/src/ffv1/rc.rs new file mode 100644 index 000000000..fa2a16ee4 --- /dev/null +++ b/crates/video/src/ffv1/rc.rs @@ -0,0 +1,229 @@ +//! The FFV1 range coder (RFC 9043 section 3.8.1): binary decisions with adaptive 8-bit states, +//! and the signed/unsigned integer coding built on them. + +/// RFC 9043 Figure 24: the default state transition table for a coded 1. +const DEFAULT_ONE_STATE: [u8; 256] = [ + 0, 0, 0, 0, 0, 0, 0, 0, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, + 49, 50, 51, 52, 53, 54, 55, 56, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 75, 76, 77, 78, 79, 80, 81, 82, + 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, + 114, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 133, 134, 135, 136, 137, 138, 139, 140, + 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, + 169, 170, 171, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 190, 191, 192, 194, 194, 195, + 196, 197, 198, 199, 200, 201, 202, 202, 204, 205, 206, 207, 208, 209, 209, 210, 211, 212, 213, 215, 215, 216, 217, 218, 219, 220, 220, 222, 223, + 224, 225, 226, 227, 227, 229, 229, 230, 231, 232, 234, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 248, 0, 0, 0, + 0, 0, 0, 0, +]; + +/// The state machine: the next state after a coded 0 or 1. +#[derive(Clone)] +pub(crate) struct Transitions { + one: [u8; 256], + zero: [u8; 256], +} + +impl Transitions { + /// The default table plus `delta` (`state_transition_delta`, indexed 1 to 255). + pub(crate) fn new(delta: &[i32; 256]) -> Transitions { + let mut one = [0u8; 256]; + for (i, o) in one.iter_mut().enumerate() { + *o = (i32::from(DEFAULT_ONE_STATE[i]) + delta[i]) as u8; + } + let mut zero = [0u8; 256]; + for i in 1..256 { + zero[i] = (256 - i32::from(one[256 - i])) as u8; + } + Transitions { one, zero } + } + + pub(crate) fn default_table() -> Transitions { + Transitions::new(&[0; 256]) + } +} + +/// Reads binary decisions from `data`; bytes past its end read as 0 (the "Closed" mode of 3.8.1.1.1). +pub(crate) struct Decoder<'a> { + data: &'a [u8], + pos: usize, + low: u32, + range: u32, +} + +impl<'a> Decoder<'a> { + pub(crate) fn new(data: &'a [u8]) -> Decoder<'a> { + let b0 = u32::from(data.first().copied().unwrap_or(0)); + let b1 = u32::from(data.get(1).copied().unwrap_or(0)); + let mut low = b0 << 8 | b1; + let range = 0xFF00; + if low >= range { + low = range; + } + Decoder { data, pos: 2, low, range } + } + + /// Bytes the coder has read so far. + pub(crate) fn consumed(&self) -> usize { + self.pos + } + + fn refill(&mut self) { + if self.range < 256 { + self.range <<= 8; + self.low <<= 8; + self.low += u32::from(self.data.get(self.pos).copied().unwrap_or(0)); + self.pos += 1; + } + } + + pub(crate) fn bit(&mut self, state: &mut u8, t: &Transitions) -> bool { + let off = (self.range * u32::from(*state)) >> 8; + self.range -= off; + if self.low < self.range { + *state = t.zero[usize::from(*state)]; + self.refill(); + false + } else { + self.low -= self.range; + *state = t.one[usize::from(*state)]; + self.range = off; + self.refill(); + true + } + } + + /// RFC 9043 Figure 21: `get_symbol`. + pub(crate) fn symbol(&mut self, state: &mut [u8; 32], signed: bool, t: &Transitions) -> i32 { + if self.bit(&mut state[0], t) { + return 0; + } + let mut e = 0usize; + while self.bit(&mut state[1 + e.min(9)], t) { + e += 1; + if e > 24 { + // No valid stream codes a magnitude this large; stop instead of spinning on garbage. + return 0; + } + } + let mut a = 1i32; + for i in (0..e).rev() { + a = a * 2 + i32::from(self.bit(&mut state[22 + i.min(9)], t)); + } + if signed && self.bit(&mut state[11 + e.min(10)], t) { -a } else { a } + } +} + +/// Writes binary decisions; the inverse of [`Decoder`]. +pub(crate) struct Encoder { + out: Vec, + low: u32, + range: u32, +} + +impl Encoder { + pub(crate) fn new() -> Encoder { + Encoder { out: Vec::new(), low: 0, range: 0xFF00 } + } + + fn shift(&mut self) { + while self.range < 256 { + // Bits 15..8 of `low` are final once a carry (bit 16) is added to the bytes before them. + let carry = self.low >> 16; + let byte = ((self.low >> 8) & 0xFF) as u8; + if carry != 0 { + for b in self.out.iter_mut().rev() { + let (v, over) = b.overflowing_add(1); + *b = v; + if !over { + break; + } + } + } + self.out.push(byte); + self.low = (self.low & 0xFF) << 8; + self.range <<= 8; + } + } + + pub(crate) fn bit(&mut self, bit: bool, state: &mut u8, t: &Transitions) { + let off = (self.range * u32::from(*state)) >> 8; + if bit { + self.low += self.range - off; + self.range = off; + *state = t.one[usize::from(*state)]; + } else { + self.range -= off; + *state = t.zero[usize::from(*state)]; + } + self.shift(); + } + + pub(crate) fn symbol(&mut self, state: &mut [u8; 32], v: i32, signed: bool, t: &Transitions) { + if v == 0 { + self.bit(true, &mut state[0], t); + return; + } + self.bit(false, &mut state[0], t); + let a = v.unsigned_abs(); + let e = (31 - a.leading_zeros()) as usize; + for i in 0..e { + self.bit(true, &mut state[1 + i.min(9)], t); + } + self.bit(false, &mut state[1 + e.min(9)], t); + for i in (0..e).rev() { + self.bit((a >> i) & 1 == 1, &mut state[22 + i.min(9)], t); + } + if signed { + self.bit(v < 0, &mut state[11 + e.min(10)], t); + } + } + + /// Finish the stream with the two bytes of the *top* of the final range: whatever bytes follow + /// (zeros, or a CRC in a container's configuration record) still decode inside the range. + pub(crate) fn finish(mut self) -> Vec { + self.low += self.range - 1; + let carry = self.low >> 16; + if carry != 0 { + for b in self.out.iter_mut().rev() { + let (v, over) = b.overflowing_add(1); + *b = v; + if !over { + break; + } + } + } + self.out.push(((self.low >> 8) & 0xFF) as u8); + self.out.push((self.low & 0xFF) as u8); + self.out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn symbols_round_trip_through_the_range_coder() { + let t = Transitions::default_table(); + let values: Vec = (0..4000).map(|i| ((i * 7919) % 2001) - 1000).chain([0, 0, 0, 65535, -65535, 1, -1]).collect(); + let mut enc = Encoder::new(); + let mut st = [128u8; 32]; + for &v in &values { + enc.symbol(&mut st, v, true, &t); + } + let bytes = enc.finish(); + let mut dec = Decoder::new(&bytes); + let mut st = [128u8; 32]; + for &v in &values { + assert_eq!(dec.symbol(&mut st, true, &t), v); + } + } + + #[test] + fn transition_tables_follow_the_rfc() { + let t = Transitions::default_table(); + assert_eq!(t.one[8], 20); + assert_eq!(t.one[247], 248); + // zero_state_i = 256 - one_state_(256 - i) + assert_eq!(t.zero[128], (256 - i32::from(t.one[128])) as u8); + assert_eq!(t.zero[1], (256 - i32::from(t.one[255])) as u8); + } +} diff --git a/crates/video/src/lib.rs b/crates/video/src/lib.rs index 0d8625bbd..8202a93f8 100644 --- a/crates/video/src/lib.rs +++ b/crates/video/src/lib.rs @@ -10,6 +10,7 @@ //! | `vp8` | [`vp8`] | VP8 (RFC 6386): decoder (`vp8-decode`) and key-frame encoder (`vp8-encode`) | //! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P/B encoder (`mpeg2-encode`) | //! | `mpeg4` | [`mpeg4`] | MPEG-4 Part 2 video (ISO/IEC 14496-2, Xvid/DivX): Simple profile encoder (`mpeg4-encode`) | +//! | `ffv1` | [`ffv1`] | FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder | //! | `prores` | [`prores`] | Apple ProRes (SMPTE RDD 36): decoder and encoder | //! | `h264` | [`h264`] | ITU-T H.264 / AVC: decoder (`h264-decode`) and encoder (`h264-encode`) | //! | `hevc` | [`hevc`] | ITU-T H.265 / HEVC: decoder (`hevc-decode`) and encoder (`hevc-encode`) | @@ -41,6 +42,9 @@ pub mod mpeg2; #[cfg(feature = "mpeg4-encode")] pub mod mpeg4; +#[cfg(feature = "ffv1")] +pub mod ffv1; + #[cfg(feature = "prores")] pub mod prores; diff --git a/crates/video/tests/ffv1.rs b/crates/video/tests/ffv1.rs new file mode 100644 index 000000000..1d5c73c0b --- /dev/null +++ b/crates/video/tests/ffv1.rs @@ -0,0 +1,304 @@ +//! FFV1 tests: round trips, hostile input, and ffmpeg as the reference (oracle; skipped when ffmpeg +//! is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). +//! +//! - Our packets, in an AVI with our configuration record, decode in ffmpeg to our source pixels. +//! - ffmpeg's FFV1 files (version 3, range coder, several pixel formats and slice counts) decode +//! with our decoder to ffmpeg's pixels. + +use craft_media::avi::{AviWriter, MuxOptions, StreamSpec, VideoSpec}; +use craft_video::ffv1::{Colorspace, Decoder, Encoder, EncoderConfig, Error, Frame}; +use std::path::Path; +use std::process::Command; + +fn noise(seed: &mut u32, mask: u32) -> u16 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + (*seed & mask) as u16 +} + +/// A frame of smooth gradients, noise bursts and flat areas. +fn frame(w: u32, h: u32, cs: Colorspace, bits: u8, shift: (u8, u8), planes: usize) -> Frame { + let max = (1u32 << bits) - 1; + let mut seed = 0x9E37_79B9u32; + let mut ps = Vec::new(); + for p in 0..planes { + let (pw, ph) = if cs == Colorspace::YCbCr && (p == 1 || p == 2) && planes >= 3 { + ((w as usize).div_ceil(1 << shift.0), (h as usize).div_ceil(1 << shift.1)) + } else { + (w as usize, h as usize) + }; + let mut v = Vec::with_capacity(pw * ph); + for y in 0..ph { + for x in 0..pw { + let s = match (y / 11 + p) % 3 { + 0 => ((x * 5 + y * 3 + p * 40) as u32 * max / 600) % (max + 1), + 1 => noise(&mut seed, max) as u32, + _ => max / 3, + }; + v.push(s as u16); + } + } + ps.push(v); + } + Frame { width: w, height: h, colorspace: cs, bit_depth: bits, chroma_shift: shift, planes: ps } +} + +fn round_trip(f: &Frame, cfg: EncoderConfig) -> Frame { + let enc = Encoder::new(f, cfg).expect("encoder"); + let config = enc.config_record(); + let packet = enc.encode(f).expect("encode"); + let dec = Decoder::new(&config, f.width, f.height).expect("decoder"); + dec.decode(&packet).expect("decode") +} + +#[test] +fn round_trips_every_shape() { + for (cs, bits, shift, planes) in [ + (Colorspace::YCbCr, 8u8, (0u8, 0u8), 1usize), + (Colorspace::YCbCr, 8, (1, 1), 3), + (Colorspace::YCbCr, 8, (1, 0), 3), + (Colorspace::YCbCr, 8, (0, 0), 4), + (Colorspace::YCbCr, 10, (1, 1), 3), + (Colorspace::YCbCr, 12, (0, 0), 3), + (Colorspace::YCbCr, 16, (1, 0), 3), + (Colorspace::YCbCr, 16, (0, 0), 1), + (Colorspace::Rgb, 8, (0, 0), 3), + (Colorspace::Rgb, 8, (0, 0), 4), + (Colorspace::Rgb, 10, (0, 0), 3), + (Colorspace::Rgb, 12, (0, 0), 4), + (Colorspace::Rgb, 15, (0, 0), 3), + ] { + for (w, h) in [(1, 1), (3, 5), (64, 48), (67, 41)] { + let f = frame(w, h, cs, bits, shift, planes); + for crc in [true, false] { + let back = round_trip(&f, EncoderConfig { slice_crc: crc, ..EncoderConfig::default() }); + assert_eq!(back.planes, f.planes, "{cs:?} {bits}-bit {shift:?} {planes} planes {w}x{h} crc={crc}"); + } + } + } +} + +#[test] +fn round_trips_with_several_slices() { + let f = frame(96, 64, Colorspace::YCbCr, 8, (1, 1), 3); + for (sh, sv) in [(2, 1), (1, 2), (3, 2), (4, 4)] { + let back = round_trip(&f, EncoderConfig { slices_h: sh, slices_v: sv, slice_crc: true }); + assert_eq!(back.planes, f.planes, "{sh}x{sv} slices"); + } + let rgb = frame(50, 30, Colorspace::Rgb, 8, (0, 0), 3); + assert_eq!(round_trip(&rgb, EncoderConfig { slices_h: 3, slices_v: 2, slice_crc: true }).planes, rgb.planes); +} + +#[test] +fn encoder_refuses_what_it_cannot_write() { + let f = frame(8, 8, Colorspace::YCbCr, 8, (1, 1), 3); + assert!(Encoder::new(&f, EncoderConfig { slices_h: 0, ..EncoderConfig::default() }).is_err()); + assert!(Encoder::new(&f, EncoderConfig { slices_h: 9, ..EncoderConfig::default() }).is_err()); + let mut bad = f.clone(); + bad.bit_depth = 7; + assert!(Encoder::new(&bad, EncoderConfig::default()).is_err()); + let mut rgb16 = frame(8, 8, Colorspace::Rgb, 8, (0, 0), 3); + rgb16.bit_depth = 16; + assert!(Encoder::new(&rgb16, EncoderConfig::default()).is_err()); + let enc = Encoder::new(&f, EncoderConfig::default()).expect("encoder"); + let mut wrong = f.clone(); + wrong.planes[1].pop(); + assert!(enc.encode(&wrong).is_err()); + let mut over = f; + over.planes[0][0] = 300; + assert!(enc.encode(&over).is_err()); +} + +#[test] +fn hostile_input_is_an_error_not_a_panic() { + let f = frame(24, 18, Colorspace::YCbCr, 8, (1, 1), 3); + let enc = Encoder::new(&f, EncoderConfig { slices_h: 2, slices_v: 1, slice_crc: true }).expect("encoder"); + let config = enc.config_record(); + let packet = enc.encode(&f).expect("encode"); + // Every truncation of the configuration record and of the packet. + for n in 0..config.len() { + let _ = Decoder::new(&config[..n], 24, 18); + } + let dec = Decoder::new(&config, 24, 18).expect("decoder"); + for n in 0..packet.len() { + let _ = dec.decode(&packet[..n]); + } + // Every single-bit flip: the CRCs catch them in a packet, and none panics. + for i in 0..packet.len() { + for bit in 0..8 { + let mut c = packet.clone(); + c[i] ^= 1 << bit; + assert!(dec.decode(&c).is_err(), "bit {bit} of byte {i} went unnoticed"); + } + } + for i in 0..config.len() { + for bit in 0..8 { + let mut c = config.clone(); + c[i] ^= 1 << bit; + assert!(matches!(Decoder::new(&c, 24, 18), Err(Error::Crc(_))), "config bit {bit} of byte {i}"); + } + } + // Without slice CRCs, flips may decode to wrong pixels but must not panic. + let enc = Encoder::new(&f, EncoderConfig { slice_crc: false, ..EncoderConfig::default() }).expect("encoder"); + let (config, packet) = (enc.config_record(), enc.encode(&f).expect("encode")); + let dec = Decoder::new(&config, 24, 18).expect("decoder"); + for i in 0..packet.len() { + for bit in 0..8 { + let mut c = packet.clone(); + c[i] ^= 1 << bit; + let _ = dec.decode(&c); + } + } + // A huge frame size is refused before any allocation. + assert!(Decoder::new(&config, u32::MAX, u32::MAX).is_err()); +} + +// ---- ffmpeg ---- + +fn ffmpeg_run(ff: &Path, args: &[&str]) -> Vec { + let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); + out.stdout +} + +fn raw_bytes(f: &Frame) -> Vec { + let mut out = Vec::new(); + for p in &f.planes { + for &v in p { + if f.bit_depth == 8 { + out.push(v as u8); + } else { + out.extend_from_slice(&v.to_le_bytes()); + } + } + } + out +} + +/// `(ffmpeg pix_fmt, colourspace, bits, chroma shift, planes)`; RGB planes are G, B, R in ffmpeg's gbrp. +type Format = (&'static str, Colorspace, u8, (u8, u8), usize); + +const FORMATS: &[Format] = &[ + ("gray", Colorspace::YCbCr, 8, (0, 0), 1), + ("yuv420p", Colorspace::YCbCr, 8, (1, 1), 3), + ("yuv422p", Colorspace::YCbCr, 8, (1, 0), 3), + ("yuv444p", Colorspace::YCbCr, 8, (0, 0), 3), + ("yuv420p10le", Colorspace::YCbCr, 10, (1, 1), 3), + ("yuv444p12le", Colorspace::YCbCr, 12, (0, 0), 3), + ("gray16le", Colorspace::YCbCr, 16, (0, 0), 1), + ("yuv444p16le", Colorspace::YCbCr, 16, (0, 0), 3), + ("gbrp", Colorspace::Rgb, 8, (0, 0), 3), + ("gbrp10le", Colorspace::Rgb, 10, (0, 0), 3), + ("gbrp12le", Colorspace::Rgb, 12, (0, 0), 3), + ("yuva444p", Colorspace::YCbCr, 8, (0, 0), 4), + ("gbrap", Colorspace::Rgb, 8, (0, 0), 4), + ("gbrap12le", Colorspace::Rgb, 12, (0, 0), 4), +]; + +/// Formats only ffmpeg writes: our encoder stops at 15-bit RGB (the transform needs 17 bits). +const DECODE_ONLY: &[Format] = &[("gbrp16le", Colorspace::Rgb, 16, (0, 0), 3), ("yuv411p", Colorspace::YCbCr, 8, (2, 0), 3)]; + +/// ffmpeg's planar RGB is G, B, R (then alpha); ours is R, G, B (then alpha). +fn gbr_order(planes: &[Vec]) -> Vec> { + let mut v = vec![planes[1].clone(), planes[2].clone(), planes[0].clone()]; + v.extend(planes[3..].iter().cloned()); + v +} + +fn avi_with(frame: &Frame, config: &[u8], packet: &[u8]) -> Vec { + let mut spec = VideoSpec::new(*b"FFV1", frame.width, frame.height, 25, 1); + spec.format.extra = config.to_vec(); + let mut w = AviWriter::new(std::io::Cursor::new(Vec::new()), vec![StreamSpec::Video(spec)], MuxOptions::default()).expect("writer"); + w.write_chunk(0, packet, true).expect("chunk"); + w.finish().expect("finish").into_inner() +} + +#[test] +fn ffmpeg_decodes_our_packets_to_our_pixels() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("ffv1"); + for &(pix_fmt, cs, bits, shift, planes) in FORMATS { + for (slices_h, slices_v) in [(1, 1), (2, 2), (3, 2)] { + let f = frame(96, 48, cs, bits, shift, planes); + let enc = Encoder::new(&f, EncoderConfig { slices_h, slices_v, slice_crc: true }).expect("encoder"); + let avi = avi_with(&f, &enc.config_record(), &enc.encode(&f).expect("encode")); + let path = dir.join(format!("ours_{pix_fmt}_{slices_h}x{slices_v}.avi")); + std::fs::write(&path, avi).expect("write"); + let theirs = ffmpeg_run(&ff, &["-i", path.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", pix_fmt, "-"]); + // gbrp is planar G, B, R; our RGB planes are R, G, B. + let mut want = f.clone(); + if cs == Colorspace::Rgb { + want.planes = gbr_order(&f.planes); + } + assert!(theirs == raw_bytes(&want), "{pix_fmt} {slices_h}x{slices_v}: ffmpeg's pixels differ from ours"); + } + } +} + +#[test] +fn our_decoder_reads_ffmpegs_files() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("ffv1"); + for &(pix_fmt, cs, bits, shift, planes) in FORMATS.iter().chain(DECODE_ONLY) { + for slices in ["1", "4", "6"] { + for (ctx, extra) in [("0", false), ("1", true)] { + let path = dir.join(format!("ffmpeg_{pix_fmt}_s{slices}_c{ctx}.avi")); + let lavfi = "testsrc2=size=96x48:rate=1"; + ffmpeg_run( + &ff, + &[ + "-f", + "lavfi", + "-i", + lavfi, + "-frames:v", + "1", + "-vf", + &format!("format={pix_fmt}"), + "-c:v", + "ffv1", + "-level", + "3", + "-coder", + "1", + "-context", + ctx, + "-slices", + slices, + "-slicecrc", + "1", + "-g", + "1", + path.to_str().expect("path"), + ], + ); + let _ = extra; + let file = std::fs::read(&path).expect("read"); + let avi = craft_media::avi::open(&file[..]).expect("open avi"); + let stream = &avi.streams[0]; + let config = stream.video.as_ref().expect("video").extra.clone(); + let chunk = stream.chunks[0]; + let packet = file[chunk.offset as usize..chunk.offset as usize + chunk.size as usize].to_vec(); + let dec = Decoder::new(&config, 96, 48).unwrap_or_else(|e| panic!("{pix_fmt} s{slices} c{ctx}: config: {e}")); + let got = dec.decode(&packet).unwrap_or_else(|e| panic!("{pix_fmt} s{slices} c{ctx}: decode: {e}")); + let theirs = ffmpeg_run(&ff, &["-i", path.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", pix_fmt, "-"]); + let mut want = got.clone(); + if cs == Colorspace::Rgb { + want.planes = gbr_order(&got.planes); + } + assert_eq!((got.colorspace, got.bit_depth, got.chroma_shift, got.planes.len()), (cs, bits, shift, planes), "{pix_fmt}"); + if theirs != raw_bytes(&want) { + let mut off = 0; + for (i, p) in want.planes.iter().enumerate() { + let n = p.len() * if bits == 8 { 1 } else { 2 }; + let same = theirs[off..off + n] == raw_bytes(&Frame { planes: vec![p.clone()], ..want.clone() })[..]; + eprintln!("{pix_fmt} s{slices} c{ctx}: plane {i} {}", if same { "equal" } else { "DIFFERENT" }); + off += n; + } + panic!("{pix_fmt} s{slices} c{ctx}: our pixels differ from ffmpeg's"); + } + } + } + } +} From ee20ae63fdc314da17362b0e1dc429fa081a686b Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 15:24:46 +0100 Subject: [PATCH 04/13] craft-audio: qoa_oracle test without index loops (CI clippy) --- crates/audio/tests/qoa_oracle.rs | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/crates/audio/tests/qoa_oracle.rs b/crates/audio/tests/qoa_oracle.rs index cf0ed8c37..7b5ac2674 100644 --- a/crates/audio/tests/qoa_oracle.rs +++ b/crates/audio/tests/qoa_oracle.rs @@ -55,12 +55,7 @@ fn ffmpeg_decodes_our_files_to_the_same_samples() { .expect("run ffmpeg"); assert!(out.status.success(), "ffmpeg failed on {}: {}", file.display(), String::from_utf8_lossy(&out.stderr)); let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); - let mut interleaved = Vec::with_capacity(frames * channels); - for i in 0..frames { - for c in 0..channels { - interleaved.push(ours.channels[c][i]); - } - } + let interleaved: Vec = (0..frames).flat_map(|i| ours.channels.iter().map(move |ch| ch[i])).collect(); assert_eq!(theirs.len(), interleaved.len(), "{rate} Hz, {channels} ch, {frames} frames: sample count"); assert!(theirs == interleaved, "{rate} Hz, {channels} ch, {frames} frames: samples differ"); } From 4d594a1130c78c88e9f9baf28891fc7d76162611 Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Sun, 15 Nov 2026 09:30:30 -0500 Subject: [PATCH 05/13] psd: share editable TySh binary envelope from PhotoCraft Preserve transform safety work and compatibility recovery; adapt to shared array geometry and add regression tests. Co-authored-by: David Mann Co-authored-by: Sean Lavery Co-authored-by: Dylan M. Taylor --- crates/psd/src/text.rs | 3 + crates/psd/src/text/envelope.rs | 142 ++++++++++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 crates/psd/src/text/envelope.rs diff --git a/crates/psd/src/text.rs b/crates/psd/src/text.rs index 6ba299bca..3a9e14952 100644 --- a/crates/psd/src/text.rs +++ b/crates/psd/src/text.rs @@ -150,3 +150,6 @@ mod tests { assert_eq!(t.style.size, Some(12.0)); } } + +/// Editable type-tool envelope with PhotoCraft-compatible recovery and geometry limits. +pub mod envelope; diff --git a/crates/psd/src/text/envelope.rs b/crates/psd/src/text/envelope.rs new file mode 100644 index 000000000..68664f7d7 --- /dev/null +++ b/crates/psd/src/text/envelope.rs @@ -0,0 +1,142 @@ +//! Editable PSD Type Tool Object Setting (`TySh`) envelope, extracted from PhotoCraft. +//! App-specific text styles, layout, units and editing policy stay with the consumer. +//! Parsing intentionally retains PhotoCraft's optional-warp and partial-bounds recovery. +//! Existing read-only [`super::TypeLayer`] behavior is unchanged. + +use crate::descriptor::{Descriptor, Id, Value as D, VersionedDescriptor}; + +/// Parsed `TySh` contents. +#[derive(Clone, Debug, PartialEq)] +pub struct TySh { + pub transform: [f64; 6], + pub text: Descriptor, + pub warp: Option, + /// The four trailing big-endian f32 values (left, top, right, bottom) after the warp + /// descriptor. Photoshop writes zeros for unwarped type and the text-space bounds (the + /// `bounds` descriptor's rectangle) for warped type. + pub bounds: [f32; 4], +} + +/// Whether a type transform can reach rendering. Pixel coordinates use i32 in the originating PhotoCraft consumer, so non-finite and unrepresentable affine terms are rejected (#4758). +pub fn transform_is_safe(t: &[f64; 6]) -> bool { + t.iter().all(|v| v.is_finite() && v.abs() <= f64::from(i32::MAX)) +} + +/// Parses a `TySh` block. +pub fn parse_tysh(data: &[u8]) -> Option { + let f = |at: usize| data.get(at..at + 8).map(|b| f64::from_be_bytes(b.try_into().unwrap_or([0; 8]))); + let mut m = [0.0; 6]; + for (i, v) in m.iter_mut().enumerate() { + *v = f(2 + i * 8)?; + } + if !transform_is_safe(&m) { + return None; + } + let (text, used) = VersionedDescriptor::parse_prefix(data.get(52..)?).ok()?; + let rest = data.get(52 + used..).unwrap_or(&[]); + let (warp, wused) = match rest.get(2..).and_then(|r| VersionedDescriptor::parse_prefix(r).ok()) { + Some((w, n)) => (Some(w.descriptor), n + 2), + None => (None, 0), + }; + let tail = rest.get(wused..).unwrap_or(&[]); + let mut bounds = [0f32; 4]; + for (i, b) in bounds.iter_mut().enumerate() { + if let Some(x) = tail.get(i * 4..i * 4 + 4) { + *b = f32::from_be_bytes(x.try_into().unwrap_or([0; 4])); + } + } + Some(TySh { transform: m, text: text.descriptor, warp, bounds }) +} + +/// `tysh` moved by (`dx`, `dy`): only the transform's translation changes. The text, its styles, +/// the warp and the trailing bounds (which are in text space) stay byte for byte, so a moved +/// Photoshop type layer keeps everything Photoshop wrote. `None` when the block is too short. +pub fn translate_tysh(tysh: &[u8], dx: f64, dy: f64) -> Option> { + let mut out = tysh.to_vec(); + // Version (2 bytes), then xx, xy, yx, yy, tx, ty as big-endian f64: tx at 34, ty at 42. + for (at, d) in [(34, dx), (42, dy)] { + let b = out.get_mut(at..at + 8)?; + let v = f64::from_be_bytes(b.try_into().ok()?) + d; + b.copy_from_slice(&v.to_be_bytes()); + } + Some(out) +} + +/// Serializes a `TySh` block. +pub fn write_tysh(t: &TySh) -> Vec { + let mut v = 1u16.to_be_bytes().to_vec(); + for x in t.transform { + v.extend_from_slice(&x.to_be_bytes()); + } + v.extend_from_slice(&50u16.to_be_bytes()); + v.extend(VersionedDescriptor::new(t.text.clone()).to_bytes()); + v.extend_from_slice(&1u16.to_be_bytes()); + v.extend(VersionedDescriptor::new(t.warp.clone().unwrap_or_else(default_warp)).to_bytes()); + for b in t.bounds { + v.extend_from_slice(&b.to_be_bytes()); + } + v +} + +fn default_warp() -> Descriptor { + Descriptor::new("warp") + .with("warpStyle", enumv("warpStyle", "warpNone")) + .with("warpValue", D::Double(0.0)) + .with("warpPerspective", D::Double(0.0)) + .with("warpPerspectiveOther", D::Double(0.0)) + .with("warpRotate", enumv("Ornt", "Hrzn")) +} + +fn enumv(t: &str, v: &str) -> D { + D::Enumerated { type_id: Id::new(t), value: Id::new(v) } +} + +#[cfg(test)] +mod tests { + use super::*; + fn sample() -> TySh { + TySh { + transform: [1.0, 0.0, 0.0, 1.0, 25.0, 30.0], + text: Descriptor::new("TxLr").with("EngineData", D::RawData(b"preserved".to_vec())), + warp: Some(default_warp()), + bounds: [-1.0, 2.0, 30.0, 40.0], + } + } + #[test] + fn roundtrip_preserves_descriptors_transform_and_bounds() { + let t = sample(); + let b = write_tysh(&t); + assert_eq!(parse_tysh(&b), Some(t)); + let shifted = translate_tysh(&b, 7.0, -3.0).unwrap(); + assert_eq!(&shifted[..34], &b[..34]); + assert_eq!(&shifted[50..], &b[50..]); + assert_eq!(parse_tysh(&shifted).unwrap().transform, [1.0, 0.0, 0.0, 1.0, 32.0, 27.0]); + } + #[test] + fn truncations_and_unsafe_transforms_preserve_recovery_contract() { + let mut t = sample(); + let bytes = write_tysh(&t); + let (_, n) = VersionedDescriptor::parse_prefix(&bytes[52..]).unwrap(); + for cut in 0..52 + n { + assert!(parse_tysh(&bytes[..cut]).is_none(), "{cut}"); + } + let short = parse_tysh(&bytes[..52 + n]).unwrap(); + assert!(short.warp.is_none()); + assert_eq!(short.bounds, [0.0; 4]); + for cut in 0..50 { + assert!(translate_tysh(&bytes[..cut], 1.0, 2.0).is_none()); + } + for bad in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY, f64::from(i32::MAX) + 1.0] { + for i in 0..6 { + t = sample(); + t.transform[i] = bad; + assert!(parse_tysh(&write_tysh(&t)).is_none()); + } + } + t = sample(); + t.warp = None; + assert!(parse_tysh(&write_tysh(&t)).unwrap().warp.is_some()); + let partial = parse_tysh(&bytes[..bytes.len() - 4]).unwrap(); + assert_eq!(partial.bounds, [-1.0, 2.0, 30.0, 0.0]); + } +} From 1e204c51dff0d49e528637b16d58f95cfa2b283a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:33:38 -0500 Subject: [PATCH 06/13] psd: bound TySh serialization and reject unsafe geometry --- crates/psd/src/text/envelope.rs | 186 ++++++++++++++++++++++++++++++-- 1 file changed, 175 insertions(+), 11 deletions(-) diff --git a/crates/psd/src/text/envelope.rs b/crates/psd/src/text/envelope.rs index 68664f7d7..e654ed390 100644 --- a/crates/psd/src/text/envelope.rs +++ b/crates/psd/src/text/envelope.rs @@ -3,7 +3,11 @@ //! Parsing intentionally retains PhotoCraft's optional-warp and partial-bounds recovery. //! Existing read-only [`super::TypeLayer`] behavior is unchanged. -use crate::descriptor::{Descriptor, Id, Value as D, VersionedDescriptor}; +use crate::descriptor::{Class, Descriptor, Id, ReferenceItem, UnicodeString, Value as D, VersionedDescriptor}; +use crate::error::{PsdError, Result}; + +/// Maximum encoded envelope size, bounding hostile input and serialized output. +pub const MAX_BYTES: usize = 8 * 1024 * 1024; /// Parsed `TySh` contents. #[derive(Clone, Debug, PartialEq)] @@ -24,6 +28,9 @@ pub fn transform_is_safe(t: &[f64; 6]) -> bool { /// Parses a `TySh` block. pub fn parse_tysh(data: &[u8]) -> Option { + if data.len() > MAX_BYTES { + return None; + } let f = |at: usize| data.get(at..at + 8).map(|b| f64::from_be_bytes(b.try_into().unwrap_or([0; 8]))); let mut m = [0.0; 6]; for (i, v) in m.iter_mut().enumerate() { @@ -45,6 +52,9 @@ pub fn parse_tysh(data: &[u8]) -> Option { *b = f32::from_be_bytes(x.try_into().unwrap_or([0; 4])); } } + if bounds.iter().any(|x| !x.is_finite()) { + return None; + } Some(TySh { transform: m, text: text.descriptor, warp, bounds }) } @@ -52,7 +62,21 @@ pub fn parse_tysh(data: &[u8]) -> Option { /// the warp and the trailing bounds (which are in text space) stay byte for byte, so a moved /// Photoshop type layer keeps everything Photoshop wrote. `None` when the block is too short. pub fn translate_tysh(tysh: &[u8], dx: f64, dy: f64) -> Option> { - let mut out = tysh.to_vec(); + if tysh.len() > MAX_BYTES || tysh.len() < 50 { + return None; + } + let mut transform = [0.0; 6]; + for (i, x) in transform.iter_mut().enumerate() { + *x = f64::from_be_bytes(tysh.get(2 + i * 8..10 + i * 8)?.try_into().ok()?); + } + transform[4] += dx; + transform[5] += dy; + if !transform_is_safe(&transform) { + return None; + } + let mut out = Vec::new(); + out.try_reserve_exact(tysh.len()).ok()?; + out.extend_from_slice(tysh); // Version (2 bytes), then xx, xy, yx, yy, tx, ty as big-endian f64: tx at 34, ty at 42. for (at, d) in [(34, dx), (42, dy)] { let b = out.get_mut(at..at + 8)?; @@ -63,19 +87,136 @@ pub fn translate_tysh(tysh: &[u8], dx: f64, dy: f64) -> Option> { } /// Serializes a `TySh` block. -pub fn write_tysh(t: &TySh) -> Vec { - let mut v = 1u16.to_be_bytes().to_vec(); +pub fn write_tysh(t: &TySh) -> Result> { + if !transform_is_safe(&t.transform) || t.bounds.iter().any(|x| !x.is_finite()) { + return Err(PsdError::LimitExceeded("TySh geometry")); + } + let default; + let warp = match &t.warp { + Some(w) => w, + None => { + default = default_warp(); + &default + } + }; + let mut budget = Budget(78); // versions, transform and trailing bounds + budget.descriptor(&t.text, 0)?; + budget.descriptor(warp, 0)?; + let mut v = Vec::new(); + v.try_reserve_exact(budget.0).map_err(|_| PsdError::OutOfMemory("TySh output"))?; + v.extend_from_slice(&1u16.to_be_bytes()); for x in t.transform { v.extend_from_slice(&x.to_be_bytes()); } v.extend_from_slice(&50u16.to_be_bytes()); - v.extend(VersionedDescriptor::new(t.text.clone()).to_bytes()); + v.extend_from_slice(&16u32.to_be_bytes()); + t.text.write(&mut v); v.extend_from_slice(&1u16.to_be_bytes()); - v.extend(VersionedDescriptor::new(t.warp.clone().unwrap_or_else(default_warp)).to_bytes()); + v.extend_from_slice(&16u32.to_be_bytes()); + warp.write(&mut v); for b in t.bounds { v.extend_from_slice(&b.to_be_bytes()); } - v + Ok(v) +} + +// Count before cloning or serializing: bound both recursive trees and total output. +struct Budget(usize); +impl Budget { + fn add(&mut self, n: usize) -> Result<()> { + self.0 = self.0.checked_add(n).filter(|n| *n <= MAX_BYTES).ok_or(PsdError::LimitExceeded("TySh bytes"))?; + Ok(()) + } + fn unicode(&mut self, s: &UnicodeString) -> Result<()> { + self.add(4)?; + self.add(s.0.len().checked_mul(2).ok_or(PsdError::LimitExceeded("TySh string"))?) + } + fn id(&mut self, id: &Id) -> Result<()> { + self.add(4)?; + self.add(id.as_bytes().len()) + } + fn class(&mut self, c: &Class) -> Result<()> { + self.unicode(&c.name)?; + self.id(&c.class_id) + } + fn descriptor(&mut self, d: &Descriptor, depth: usize) -> Result<()> { + if depth > 32 { + return Err(PsdError::LimitExceeded("TySh depth")); + } + self.unicode(&d.name)?; + self.id(&d.class_id)?; + self.add(4)?; + for (k, v) in &d.items { + self.id(k)?; + self.value(v, depth + 1)?; + } + Ok(()) + } + fn value(&mut self, v: &D, depth: usize) -> Result<()> { + if depth > 32 { + return Err(PsdError::LimitExceeded("TySh depth")); + } + self.add(4)?; + match v { + D::Descriptor(d) | D::GlobalObject(d) => self.descriptor(d, depth), + D::ObjectArray(o) => { + self.add(4)?; + self.descriptor(&o.body, depth) + } + D::List(xs) => { + self.add(4)?; + for x in xs { + self.value(x, depth + 1)?; + } + Ok(()) + } + D::Reference(xs) => { + self.add(4)?; + for x in xs { + self.add(4)?; + match x { + ReferenceItem::Property { class, key } => { + self.class(class)?; + self.id(key)?; + } + ReferenceItem::Class(c) => self.class(c)?, + ReferenceItem::Enumerated { class, type_id, value } => { + self.class(class)?; + self.id(type_id)?; + self.id(value)?; + } + ReferenceItem::Offset { class, .. } | ReferenceItem::Identifier { class, .. } | ReferenceItem::Index { class, .. } => { + self.class(class)?; + self.add(4)?; + } + ReferenceItem::Name { class, name } => { + self.class(class)?; + self.unicode(name)?; + } + } + } + Ok(()) + } + D::Text(x) => self.unicode(x), + D::Class(c) | D::GlobalClass(c) => self.class(c), + D::Enumerated { type_id, value } => { + self.id(type_id)?; + self.id(value) + } + D::UnitFloats { values, .. } => { + self.add(8)?; + self.add(values.len().checked_mul(8).ok_or(PsdError::LimitExceeded("TySh values"))?) + } + D::RawData(x) | D::Alias(x) | D::Path(x) => { + self.add(4)?; + self.add(x.len()) + } + D::Double(_) | D::LargeInteger(_) => self.add(8), + D::UnitFloat { .. } => self.add(12), + D::Integer(_) => self.add(4), + D::Boolean(_) => self.add(1), + } + } } fn default_warp() -> Descriptor { @@ -105,7 +246,7 @@ mod tests { #[test] fn roundtrip_preserves_descriptors_transform_and_bounds() { let t = sample(); - let b = write_tysh(&t); + let b = write_tysh(&t).unwrap(); assert_eq!(parse_tysh(&b), Some(t)); let shifted = translate_tysh(&b, 7.0, -3.0).unwrap(); assert_eq!(&shifted[..34], &b[..34]); @@ -115,7 +256,7 @@ mod tests { #[test] fn truncations_and_unsafe_transforms_preserve_recovery_contract() { let mut t = sample(); - let bytes = write_tysh(&t); + let bytes = write_tysh(&t).unwrap(); let (_, n) = VersionedDescriptor::parse_prefix(&bytes[52..]).unwrap(); for cut in 0..52 + n { assert!(parse_tysh(&bytes[..cut]).is_none(), "{cut}"); @@ -130,13 +271,36 @@ mod tests { for i in 0..6 { t = sample(); t.transform[i] = bad; - assert!(parse_tysh(&write_tysh(&t)).is_none()); + assert!(write_tysh(&t).is_err()); } } t = sample(); t.warp = None; - assert!(parse_tysh(&write_tysh(&t)).unwrap().warp.is_some()); + assert!(parse_tysh(&write_tysh(&t).unwrap()).unwrap().warp.is_some()); let partial = parse_tysh(&bytes[..bytes.len() - 4]).unwrap(); assert_eq!(partial.bounds, [-1.0, 2.0, 30.0, 0.0]); } + #[test] + fn hostile_output_and_translations_are_refused_before_copying() { + let bytes = write_tysh(&sample()).unwrap(); + for bad in [f64::NAN, f64::INFINITY, f64::MAX] { + assert!(translate_tysh(&bytes, bad, 0.0).is_none()); + } + let mut t = sample(); + t.bounds[0] = f32::NAN; + assert!(write_tysh(&t).is_err()); + t = sample(); + t.text = Descriptor::new("TxLr").with("data", D::RawData(vec![0; MAX_BYTES])); + assert!(write_tysh(&t).is_err()); + let oversized = vec![0; MAX_BYTES + 1]; + assert!(translate_tysh(&oversized, 0.0, 0.0).is_none()); + assert!(parse_tysh(&oversized).is_none()); + let mut nested = D::Integer(1); + for _ in 0..34 { + nested = D::List(vec![nested]); + } + t = sample(); + t.text = Descriptor::new("TxLr").with("nest", nested); + assert!(write_tysh(&t).is_err()); + } } From f483f9d6dd0ec9dcaf7697323cfab0b7f6fdc57b Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Sun, 15 Nov 2026 09:39:55 -0500 Subject: [PATCH 07/13] cms: preserve original PDFCraft ICC v2 sRGB generator Extracted unchanged from storytold/pdfcraft e098c5c85, crates/preflight/src/icc.rs; original implementation 4d60af8b1, rename d3db99818. --- crates/cms/src/builtin_v2.rs | 128 +++++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 crates/cms/src/builtin_v2.rs diff --git a/crates/cms/src/builtin_v2.rs b/crates/cms/src/builtin_v2.rs new file mode 100644 index 000000000..935dd105c --- /dev/null +++ b/crates/cms/src/builtin_v2.rs @@ -0,0 +1,128 @@ +//! A small sRGB ICC profile (version 2, display class, matrix/TRC), written from the published +//! sRGB primaries (IEC 61966-2-1) adapted to D50, with the sRGB tone curve sampled at 1024 +//! points. Used as the PDF/A output intent's destination profile. + +fn s15f16(v: f64) -> [u8; 4] { + ((v * 65536.0).round() as i32).to_be_bytes() +} + +fn xyz(x: f64, y: f64, z: f64) -> Vec { + let mut t = b"XYZ \0\0\0\0".to_vec(); + t.extend(s15f16(x)); + t.extend(s15f16(y)); + t.extend(s15f16(z)); + t +} + +fn desc(text: &str) -> Vec { + let mut t = b"desc\0\0\0\0".to_vec(); + let ascii: Vec = text.bytes().chain(std::iter::once(0)).collect(); + t.extend((ascii.len() as u32).to_be_bytes()); + t.extend(&ascii); + // No Unicode or ScriptCode descriptions. + t.extend([0u8; 4 + 4]); + t.extend([0u8; 2 + 1 + 67]); + t +} + +fn text(text: &str) -> Vec { + let mut t = b"text\0\0\0\0".to_vec(); + t.extend(text.bytes()); + t.push(0); + t +} + +fn curve() -> Vec { + const N: usize = 1024; + let mut t = b"curv\0\0\0\0".to_vec(); + t.extend((N as u32).to_be_bytes()); + for i in 0..N { + let v = i as f64 / (N - 1) as f64; + let lin = if v <= 0.04045 { v / 12.92 } else { ((v + 0.055) / 1.055).powf(2.4) }; + t.extend(((lin * 65535.0).round() as u16).to_be_bytes()); + } + t +} + +/// The profile's bytes. +pub fn srgb() -> Vec { + // sRGB primaries, Bradford-adapted to the D50 profile connection space. + let tags: Vec<(&[u8; 4], Vec)> = vec![ + (b"desc", desc("sRGB (PdfCraft)")), + (b"cprt", text("No copyright, use freely")), + (b"wtpt", xyz(0.9642, 1.0, 0.8249)), + (b"rXYZ", xyz(0.4361, 0.2225, 0.0139)), + (b"gXYZ", xyz(0.3851, 0.7169, 0.0971)), + (b"bXYZ", xyz(0.1431, 0.0606, 0.7141)), + (b"rTRC", curve()), + ]; + // gTRC and bTRC share rTRC's data. + let count = tags.len() + 2; + let table_len = 4 + count * 12; + let mut offset = 128 + table_len; + let mut table = (count as u32).to_be_bytes().to_vec(); + let mut data = Vec::new(); + let mut trc = (0, 0); + for (sig, body) in &tags { + let len = body.len(); + table.extend(*sig); + table.extend((offset as u32).to_be_bytes()); + table.extend((len as u32).to_be_bytes()); + if *sig == b"rTRC" { + trc = (offset, len); + } + data.extend(body); + // Tags start on 4-byte boundaries. + let pad = (4 - len % 4) % 4; + data.extend(std::iter::repeat_n(0u8, pad)); + offset += len + pad; + } + for sig in [b"gTRC", b"bTRC"] { + table.extend(sig); + table.extend((trc.0 as u32).to_be_bytes()); + table.extend((trc.1 as u32).to_be_bytes()); + } + let size = 128 + table.len() + data.len(); + let mut h = Vec::with_capacity(size); + h.extend((size as u32).to_be_bytes()); + h.extend(b"\0\0\0\0"); // preferred CMM + h.extend([2, 0x10, 0, 0]); // version 2.1 + h.extend(b"mntr"); + h.extend(b"RGB "); + h.extend(b"XYZ "); + h.extend([0u8; 12]); // date + h.extend(b"acsp"); + h.extend(b"\0\0\0\0"); // platform + h.extend([0u8; 4]); // flags + h.extend([0u8; 4]); // manufacturer + h.extend([0u8; 4]); // model + h.extend([0u8; 8]); // attributes + h.extend([0, 0, 0, 0]); // perceptual intent + h.extend(s15f16(0.9642)); + h.extend(s15f16(1.0)); + h.extend(s15f16(0.8249)); + h.extend([0u8; 4]); // creator + h.resize(128, 0); + h.extend(table); + h.extend(data); + h +} + +#[cfg(test)] +mod tests { + #[test] + fn profile_is_well_formed() { + let p = super::srgb(); + assert_eq!(u32::from_be_bytes(p[0..4].try_into().unwrap()) as usize, p.len()); + assert_eq!(&p[36..40], b"acsp"); + assert_eq!(&p[12..20], b"mntrRGB "); + let n = u32::from_be_bytes(p[128..132].try_into().unwrap()) as usize; + assert_eq!(n, 9); + for i in 0..n { + let e = 132 + i * 12; + let off = u32::from_be_bytes(p[e + 4..e + 8].try_into().unwrap()) as usize; + let len = u32::from_be_bytes(p[e + 8..e + 12].try_into().unwrap()) as usize; + assert!(off.is_multiple_of(4) && off + len <= p.len(), "tag {i}"); + } + } +} From 7bc5f2a4c8214b97394a5dcf60d01e9f5f5298c3 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:40:37 -0500 Subject: [PATCH 08/13] cms: expose fixed v2 sRGB profile and verify shared parsing --- crates/cms/src/builtin.rs | 12 ++++++++++++ crates/cms/src/builtin_v2.rs | 17 ++++++++++++++++- crates/cms/src/lib.rs | 1 + 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/crates/cms/src/builtin.rs b/crates/cms/src/builtin.rs index ca7034286..e62faa907 100644 --- a/crates/cms/src/builtin.rs +++ b/crates/cms/src/builtin.rs @@ -450,3 +450,15 @@ mod tests { assert!(cicp_rgb(u16::MAX, u16::MAX, true).is_none()); } } + +/// Generates the compact ICC v2.1 sRGB matrix/TRC profile used by PDFCraft. +/// +/// Unlike [`Builtin::Srgb`]'s v4 profile, this uses a 1024-sample tone curve and +/// v2 `desc`/`text` tags for consumers that require a v2 output intent. The legacy +/// description `sRGB (PdfCraft)` is retained to preserve existing document bytes. +/// The generated profile contains no external assets; callers choose where it is +/// appropriate (including their own PDF/A conformance policy). +/// All sizes are fixed; no input-controlled allocation or recursion is involved. +pub fn srgb_v2() -> Vec { + crate::builtin_v2::srgb() +} diff --git a/crates/cms/src/builtin_v2.rs b/crates/cms/src/builtin_v2.rs index 935dd105c..4a9e2e25b 100644 --- a/crates/cms/src/builtin_v2.rs +++ b/crates/cms/src/builtin_v2.rs @@ -44,7 +44,7 @@ fn curve() -> Vec { t } -/// The profile's bytes. +/// Fixed-size profile bytes; all tag sizes and loop counts are constants. pub fn srgb() -> Vec { // sRGB primaries, Bradford-adapted to the D50 profile connection space. let tags: Vec<(&[u8; 4], Vec)> = vec![ @@ -110,6 +110,21 @@ pub fn srgb() -> Vec { #[cfg(test)] mod tests { + #[test] + fn parses_as_v2_with_shared_rgb_curves() { + let bytes = super::srgb(); + let p = crate::Profile::parse(&bytes).unwrap(); + assert_eq!(p.version, (2, 0x10)); + assert_eq!(p.color_space, crate::ColorSpace::Rgb); + assert_eq!(p.pcs, crate::Pcs::Xyz); + assert_eq!(p.description, "sRGB (PdfCraft)"); + let curves = p.trc.unwrap(); + assert_eq!(curves[0], curves[1]); + assert_eq!(curves[1], curves[2]); + assert!(matches!(&curves[0], crate::Curve::Table(v) if v.len() == 1024 && v[0] == 0.0 && v[1023] == 1.0)); + assert_eq!(bytes, super::srgb()); + } + #[test] fn profile_is_well_formed() { let p = super::srgb(); diff --git a/crates/cms/src/lib.rs b/crates/cms/src/lib.rs index 8d4f99f49..5e8a1e268 100644 --- a/crates/cms/src/lib.rs +++ b/crates/cms/src/lib.rs @@ -20,6 +20,7 @@ #![forbid(unsafe_code)] pub mod builtin; +mod builtin_v2; pub mod clut; pub mod curve; pub mod gamut; From cab96afd08c3b68073340d2162657ccc989bd751 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:43:27 -0500 Subject: [PATCH 09/13] cms: keep public v2 helper before test module --- crates/cms/src/builtin.rs | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/crates/cms/src/builtin.rs b/crates/cms/src/builtin.rs index e62faa907..5a8b03228 100644 --- a/crates/cms/src/builtin.rs +++ b/crates/cms/src/builtin.rs @@ -424,6 +424,18 @@ fn shipped_cmyk(bytes: &[u8], b: Builtin) -> Profile { }) } +/// Generates the compact ICC v2.1 sRGB matrix/TRC profile used by PDFCraft. +/// +/// Unlike [`Builtin::Srgb`]'s v4 profile, this uses a 1024-sample tone curve and +/// v2 `desc`/`text` tags for consumers that require a v2 output intent. The legacy +/// description `sRGB (PdfCraft)` is retained to preserve existing document bytes. +/// The generated profile contains no external assets; callers choose where it is +/// appropriate (including their own PDF/A conformance policy). +/// All sizes are fixed; no input-controlled allocation or recursion is involved. +pub fn srgb_v2() -> Vec { + crate::builtin_v2::srgb() +} + #[cfg(test)] mod tests { use super::*; @@ -450,15 +462,3 @@ mod tests { assert!(cicp_rgb(u16::MAX, u16::MAX, true).is_none()); } } - -/// Generates the compact ICC v2.1 sRGB matrix/TRC profile used by PDFCraft. -/// -/// Unlike [`Builtin::Srgb`]'s v4 profile, this uses a 1024-sample tone curve and -/// v2 `desc`/`text` tags for consumers that require a v2 output intent. The legacy -/// description `sRGB (PdfCraft)` is retained to preserve existing document bytes. -/// The generated profile contains no external assets; callers choose where it is -/// appropriate (including their own PDF/A conformance policy). -/// All sizes are fixed; no input-controlled allocation or recursion is involved. -pub fn srgb_v2() -> Vec { - crate::builtin_v2::srgb() -} From 2bb5d0344f03a73833576b57847513ea529d3d2c Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:10:41 -0500 Subject: [PATCH 10/13] docs(psd): document editable TySh envelope fields --- crates/psd/src/text/envelope.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/crates/psd/src/text/envelope.rs b/crates/psd/src/text/envelope.rs index e654ed390..73345fa83 100644 --- a/crates/psd/src/text/envelope.rs +++ b/crates/psd/src/text/envelope.rs @@ -12,8 +12,11 @@ pub const MAX_BYTES: usize = 8 * 1024 * 1024; /// Parsed `TySh` contents. #[derive(Clone, Debug, PartialEq)] pub struct TySh { + /// Affine transform in PSD order: xx, xy, yx, yy, tx, ty. pub transform: [f64; 6], + /// Text descriptor, including text content and styling data. pub text: Descriptor, + /// Optional warp descriptor retained from the Type Tool block. pub warp: Option, /// The four trailing big-endian f32 values (left, top, right, bottom) after the warp /// descriptor. Photoshop writes zeros for unwarped type and the text-space bounds (the From 2c9903ca1d892b5446acf3598d8b142f3e64842f Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:29:27 +0000 Subject: [PATCH 11/13] Support configurable legacy MCP sessions and envelopes --- crates/jsonrpc/src/lib.rs | 58 ++++++++++++++++++++++++++++++ crates/mcp/src/lib.rs | 74 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 129 insertions(+), 3 deletions(-) diff --git a/crates/jsonrpc/src/lib.rs b/crates/jsonrpc/src/lib.rs index 9f8128d1d..cfb46ef79 100644 --- a/crates/jsonrpc/src/lib.rs +++ b/crates/jsonrpc/src/lib.rs @@ -195,3 +195,61 @@ where let responses: Vec<_> = batch.iter().filter_map(|v| one(v, limits, &mut on_request, &mut on_notification)).collect(); Ok((!responses.is_empty()).then_some(Value::Array(responses))) } +/// Process a permissive legacy JSON-RPC envelope. This mode accepts arbitrary IDs and +/// parameter shapes, ignores response envelopes, and retains legacy diagnostic messages. +/// The caller supplies dispatch and notification callbacks, and should bound transport input. +pub fn process_legacy(value: &Value, mut on_request: F, mut on_notification: N) -> Option +where + F: FnMut(Request<'_>) -> Result, + N: FnMut(Request<'_>), +{ + fn one(value: &Value, on_request: &mut F, on_notification: &mut N) -> Option + where + F: FnMut(Request<'_>) -> Result, + N: FnMut(Request<'_>), + { + let Some(object) = value.as_object() else { return Some(error_response(Value::Null, RpcError::new(-32600, "message must be an object"))) }; + let id = object.get("id"); + let Some(method) = object.get("method").and_then(Value::as_str) else { + if object.contains_key("result") || object.contains_key("error") { + return None; + } + return Some(error_response(id.cloned().unwrap_or(Value::Null), RpcError::new(-32600, "missing `method`"))); + }; + let request = Request { id, method, params: object.get("params") }; + let Some(id) = id else { + on_notification(request); + return None; + }; + Some(match on_request(request) { + Ok(result) => json!({"jsonrpc": "2.0", "id": id, "result": result}), + Err(error) => error_response(id.clone(), error), + }) + } + if let Some(batch) = value.as_array() { + if batch.is_empty() { + return Some(error_response(Value::Null, RpcError::new(-32600, "empty batch"))); + } + let replies: Vec<_> = batch.iter().filter_map(|v| one(v, &mut on_request, &mut on_notification)).collect(); + (!replies.is_empty()).then_some(Value::Array(replies)) + } else { + one(value, &mut on_request, &mut on_notification) + } +} + +#[cfg(test)] +mod legacy_tests { + use super::*; + #[test] + fn preserves_legacy_batch_routing_and_errors() { + let input = json!([{"id": [1], "method":"echo", "params":5}, {"method":"notice"}, {"result":1}, {}, 7]); + let seen = std::cell::Cell::new(false); + let result = process_legacy(&input, |r| Ok(r.params.cloned().unwrap_or(Value::Null)), |_| seen.set(true)).unwrap(); + assert!(seen.get()); + assert_eq!( + result, + json!([{"jsonrpc":"2.0","id":[1],"result":5}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"missing `method`"}}, {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"message must be an object"}}]) + ); + assert_eq!(process_legacy(&json!([]), |_| Ok(Value::Null), |_| {}).unwrap()["error"]["message"], "empty batch"); + } +} diff --git a/crates/mcp/src/lib.rs b/crates/mcp/src/lib.rs index 96cfdc7ae..6ca888fc0 100644 --- a/crates/mcp/src/lib.rs +++ b/crates/mcp/src/lib.rs @@ -34,11 +34,27 @@ pub struct Session { policy: Policy, state: State, capabilities: Value, + versions: Vec, + permissive_initialize: bool, + server_info: Option, + instructions: Option, + initialized: bool, } impl Session { pub fn new(name: impl Into, version: impl Into, policy: Policy) -> Self { - Self { name: name.into(), version: version.into(), policy, state: State::New, capabilities: json!({"tools": {}}) } + Self { + name: name.into(), + version: version.into(), + policy, + state: State::New, + capabilities: json!({"tools": {}}), + versions: vec![PROTOCOL_VERSION.into()], + permissive_initialize: false, + server_info: None, + instructions: None, + initialized: false, + } } /// Set the server capabilities returned at initialization. The value must be an object. @@ -50,6 +66,27 @@ impl Session { Ok(self) } + /// Configure a permissive legacy server: absent or malformed initialize parameters are + /// accepted, supported client versions are echoed, and unknown versions use the first entry. + pub fn with_legacy_initialize(mut self, versions: &[&str], server_info: Value) -> Self { + if !versions.is_empty() { + self.versions = versions.iter().map(|v| (*v).to_owned()).collect(); + } + self.permissive_initialize = true; + self.server_info = Some(server_info); + self + } + + /// Update connection-specific instructions returned by subsequent initialize requests. + pub fn set_instructions(&mut self, instructions: String) { + self.instructions = Some(instructions); + } + + /// Whether an initialized notification has been observed, including before initialize. + pub fn is_initialized(&self) -> bool { + self.initialized + } + pub fn state(&self) -> State { self.state } @@ -64,6 +101,18 @@ impl Session { if self.policy == Policy::Strict && (in_batch || self.state != State::New) { return Some(Err(RpcError::new(-32600, "Invalid Request"))); } + if self.permissive_initialize { + let asked = request.params.and_then(|p| p.get("protocolVersion")).and_then(Value::as_str); + let version = asked + .filter(|v| self.versions.iter().any(|supported| supported == v)) + .unwrap_or_else(|| self.versions.first().map(String::as_str).unwrap_or(PROTOCOL_VERSION)); + let mut result = json!({"protocolVersion": version, "capabilities": self.capabilities, "serverInfo": self.server_info}); + if let Some(instructions) = &self.instructions { + result["instructions"] = json!(instructions); + } + self.state = State::AwaitingInitialized; + return Some(Ok(result)); + } let Some(params) = request.params.and_then(Value::as_object) else { return Some(Err(invalid_initialize())); }; @@ -89,8 +138,11 @@ impl Session { /// Observe a JSON-RPC notification; notifications never receive replies. pub fn notification(&mut self, request: Request<'_>) { - if request.method == "notifications/initialized" && self.state == State::AwaitingInitialized { - self.state = State::Ready; + if request.method == "notifications/initialized" { + self.initialized = true; + if self.state == State::AwaitingInitialized { + self.state = State::Ready; + } } } } @@ -127,6 +179,22 @@ mod tests { Request { id: None, method, params } } + #[test] + fn legacy_initialization_negotiates_and_accepts_missing_parameters() { + let mut s = Session::new("test", "1", Policy::Compatible).with_legacy_initialize(&["new", "old"], json!({"name":"custom", "title":"Title"})); + s.notification(call("notifications/initialized", None)); + assert!(s.is_initialized()); + s.set_instructions("help".into()); + for (params, expected) in + [(None, "new"), (Some(json!({"protocolVersion":"old"})), "old"), (Some(json!({"protocolVersion":"unknown"})), "new")] + { + let result = s.request(call("initialize", params.as_ref()), false).unwrap().unwrap(); + assert_eq!(result["protocolVersion"], expected); + assert_eq!(result["serverInfo"]["title"], "Title"); + assert_eq!(result["instructions"], "help"); + } + } + #[test] fn compatible_negotiation_preserves_existing_clients() { let mut s = Session::new("test", "1", Policy::Compatible); From 451a390542fbde0519cbb8ade3a3325cf02d97be Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:37:41 +0000 Subject: [PATCH 12/13] Add opt-in legacy Base64 compatibility --- crates/mime/src/base64_compat.rs | 93 ++++++++++++++++++++++++++++++++ crates/mime/src/lib.rs | 1 + 2 files changed, 94 insertions(+) create mode 100644 crates/mime/src/base64_compat.rs diff --git a/crates/mime/src/base64_compat.rs b/crates/mime/src/base64_compat.rs new file mode 100644 index 000000000..452b276f9 --- /dev/null +++ b/crates/mime/src/base64_compat.rs @@ -0,0 +1,93 @@ +//! Compatibility decoding for legacy transports that accepted mixed Base64 alphabets and padding. +//! +//! This is deliberately permissive and must not be used for signatures, credentials or other +//! contexts requiring canonical Base64. Use [`crate::base64`] for strict RFC 4648 decoding. +use crate::base64::DecodeError; + +/// Decode standard or URL-safe Base64, accepting either alphabet even in the same input. +/// Spaces, CR, LF and `=` are ignored wherever they occur; an incomplete final sextet is +/// discarded. Other bytes are errors. Output allocation is bounded by the input length. +pub fn decode(input: impl AsRef<[u8]>) -> Result, DecodeError> { + let input = input.as_ref(); + let mut out = Vec::new(); + let capacity = (input.len() / 4) * 3 + (input.len() % 4) * 3 / 4; + out.try_reserve(capacity).map_err(|_| DecodeError)?; + let (mut acc, mut bits) = (0u32, 0u32); + for c in input { + let v = match c { + b'A'..=b'Z' => c - b'A', + b'a'..=b'z' => c - b'a' + 26, + b'0'..=b'9' => c - b'0' + 52, + b'+' | b'-' => 62, + b'/' | b'_' => 63, + b'=' | b'\n' | b'\r' | b' ' => continue, + _ => return Err(DecodeError), + }; + acc = (acc << 6) | u32::from(v); + bits += 6; + if bits >= 8 { + bits -= 8; + out.push((acc >> bits) as u8); + acc &= (1 << bits) - 1; + } + } + Ok(out) +} +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used)] + use super::*; + #[test] + fn accepts_mixed_alphabets_and_ignores_padding_anywhere() { + assert_eq!(decode("+_8=").unwrap(), [251, 255]); + assert_eq!(decode("Z=m 9\nv\r").unwrap(), b"foo"); + assert_eq!(decode("A").unwrap(), b""); + assert_eq!(decode("AB").unwrap(), [0]); + assert!(decode("Zm9v\t").is_err()); + assert!(decode("Zm9v!").is_err()); + assert!(crate::base64::STANDARD.decode("Z=m9v").is_err()); + } + // Differential against CADCraft's pre-cutover decoder, including malformed legacy inputs. + fn legacy(s: &str) -> Option> { + let mut out = Vec::new(); + let (mut acc, mut bits) = (0u32, 0u32); + for c in s.bytes() { + let value = match c { + b'A'..=b'Z' => c - b'A', + b'a'..=b'z' => c - b'a' + 26, + b'0'..=b'9' => c - b'0' + 52, + b'+' | b'-' => 62, + b'/' | b'_' => 63, + b'=' | b'\n' | b'\r' | b' ' => continue, + _ => return None, + }; + acc = (acc << 6) | u32::from(value); + bits += 6; + if bits >= 8 { + bits -= 8; + out.push((acc >> bits) as u8); + } + } + Some(out) + } + #[test] + fn matches_the_legacy_decoder_on_seeded_mixed_inputs() { + let alphabet = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/-_= \r\n!\t"; + let mut seed = 0x1234_5678u32; + for n in 0..50_000 { + let mut text = String::new(); + for _ in 0..n % 45 { + seed = seed.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + text.push(char::from(alphabet[(seed as usize) % alphabet.len()])); + } + assert_eq!(decode(&text).ok(), legacy(&text), "{text:?}"); + } + } + + #[test] + fn round_trip_rfc_vectors_with_the_shared_encoder() { + for data in [&b""[..], b"f", b"fo", b"foo", b"foobar", &[0, 255, 127]] { + assert_eq!(decode(crate::base64::STANDARD.encode(data)).unwrap(), data); + } + } +} diff --git a/crates/mime/src/lib.rs b/crates/mime/src/lib.rs index 72a930b8b..d3ff9f257 100644 --- a/crates/mime/src/lib.rs +++ b/crates/mime/src/lib.rs @@ -28,6 +28,7 @@ //! says) is the caller's: this crate has no notion of a mailbox or a document. pub mod base64; +pub mod base64_compat; pub mod charset; #[cfg(feature = "detect")] pub mod detect; From c9de09877ba38dba838ade37ba105032357709a9 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 12:29:34 -0500 Subject: [PATCH 13/13] Share bounded BMP coverage inspection (#1610) --- crates/image-codecs/src/bmp_probe.rs | 145 +++++++++++++++++++++++++++ crates/image-codecs/src/lib.rs | 1 + 2 files changed, 146 insertions(+) create mode 100644 crates/image-codecs/src/bmp_probe.rs diff --git a/crates/image-codecs/src/bmp_probe.rs b/crates/image-codecs/src/bmp_probe.rs new file mode 100644 index 000000000..59c78ca1e --- /dev/null +++ b/crates/image-codecs/src/bmp_probe.rs @@ -0,0 +1,145 @@ +//! Header-only BMP dimensions and pixel-data coverage, without allocating a canvas. + +/// Coverage of the declared pixel array. Row byte counts include row padding; RLE coverage +/// counts the pixels drawn by commands and may be smaller than the canvas. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Coverage { + pub pixels: u64, + pub row_bytes: Option<(u64, u64)>, +} + +/// Inspect pixel data for the given dimensions without decoding a bitmap. The row tuple is +/// `(available, needed)`; callers choose their own sparse-canvas and allocation policy. +pub fn coverage(bytes: &[u8], w: u32, h: u32) -> Coverage { + match bmp_layout(bytes) { + BmpLayout::Rle { offset, rle4 } => Coverage { pixels: bmp_rle_pixels(bytes, offset, rle4, w, h), row_bytes: None }, + BmpLayout::Rows { offset, bits } => { + let needed = u64::from(w).saturating_mul(u64::from(bits)).div_ceil(32).saturating_mul(4).saturating_mul(u64::from(h)); + let held = bytes.len().saturating_sub(offset) as u64; + Coverage { pixels: u64::from(w) * u64::from(h), row_bytes: Some((held, needed)) } + } + } +} + +enum BmpLayout { + /// RLE8 or RLE4 commands. + Rle { offset: usize, rle4: bool }, + /// Rows of `bits` per pixel, each padded to 4 bytes. + Rows { offset: usize, bits: u16 }, +} + +/// The layout the decoder reads, from the file header and the bitmap header: a 12-byte core header +/// (bits per pixel at 24, never compressed) or a 40-byte or larger one (bits at 28, compression at +/// 30). Fields the decoder would have refused are read as 1 bit per pixel at offset 0, the most +/// lenient layout. +fn bmp_layout(bytes: &[u8]) -> BmpLayout { + let u16_at = |i: usize| bytes.get(i..i.checked_add(2)?).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); + let u32_at = |i: usize| bytes.get(i..i.checked_add(4)?).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let offset = u32_at(10).and_then(|o| usize::try_from(o).ok()).unwrap_or(0); + let (bits, compression) = match u32_at(14) { + Some(12) => (u16_at(24), Some(0)), + _ => (u16_at(28), u32_at(30)), + }; + match compression { + Some(1) => BmpLayout::Rle { offset, rle4: false }, + Some(2) => BmpLayout::Rle { offset, rle4: true }, + _ => BmpLayout::Rows { offset, bits: bits.filter(|&b| b > 0).unwrap_or(1) }, + } +} + +/// The pixels an RLE8 or RLE4 BMP's commands draw on a `w` × `h` canvas, read the way the decoder +/// paints them: a run is clipped at the end of its row, an end-of-row code moves to the next row, a +/// delta skips pixels (left blank), and an end-of-bitmap code, a truncated command or the last row +/// ends the picture. Every command takes at least 2 bytes, so the walk is linear in the file. +fn bmp_rle_pixels(bytes: &[u8], offset: usize, rle4: bool, w: u32, h: u32) -> u64 { + let (w, h) = (u64::from(w), u64::from(h)); + let (mut pos, mut x, mut y, mut covered) = (offset, 0u64, 0u64, 0u64); + while y < h { + let (Some(&count), Some(&value)) = (bytes.get(pos), bytes.get(pos.saturating_add(1))) else { + break; + }; + pos = pos.saturating_add(2); + match (count, value) { + // end of row + (0, 0) => (x, y) = (0, y.saturating_add(1)), + // end of bitmap + (0, 1) => break, + // delta: right and down + (0, 2) => { + let (Some(&dx), Some(&dy)) = (bytes.get(pos), bytes.get(pos.saturating_add(1))) else { + break; + }; + pos = pos.saturating_add(2); + (x, y) = (x.saturating_add(u64::from(dx)), y.saturating_add(u64::from(dy))); + } + // absolute: `value` pixels stored one per byte (RLE8) or nibble (RLE4), padded to 2 bytes + (0, n) => { + let len = if rle4 { usize::from(n).div_ceil(2) } else { usize::from(n) }; + pos = pos.saturating_add(len + (len & 1)); + if pos > bytes.len() { + break; + } + covered = covered.saturating_add(u64::from(n).min(w.saturating_sub(x))); + x = x.saturating_add(u64::from(n)); + } + // a run of `count` pixels + (n, _) => { + covered = covered.saturating_add(u64::from(n).min(w.saturating_sub(x))); + x = x.saturating_add(u64::from(n)); + } + } + } + covered +} + +/// Reads BMP `(width, height)` from the DIB header without allocating. +pub fn dimensions(bytes: &[u8]) -> Option<(u32, u32)> { + if bytes.get(0..2) != Some(b"BM") { + return None; + } + let dib = u32::from_le_bytes(bytes.get(14..18)?.try_into().ok()?); + let (w, h) = if dib == 12 { + (u16::from_le_bytes(bytes.get(18..20)?.try_into().ok()?) as u32, u16::from_le_bytes(bytes.get(20..22)?.try_into().ok()?) as u32) + } else { + let w = i32::from_le_bytes(bytes.get(18..22)?.try_into().ok()?); + let h = i32::from_le_bytes(bytes.get(22..26)?.try_into().ok()?); + (u32::try_from(w).ok()?, h.unsigned_abs()) + }; + Some((w, h)) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn bmp(compression: u32, pixels: &[u8]) -> Vec { + let mut b = vec![0; 54]; + b[..2].copy_from_slice(b"BM"); + b[10..14].copy_from_slice(&54u32.to_le_bytes()); + b[14..18].copy_from_slice(&40u32.to_le_bytes()); + b[18..22].copy_from_slice(&4i32.to_le_bytes()); + b[22..26].copy_from_slice(&2i32.to_le_bytes()); + b[28..30].copy_from_slice(&8u16.to_le_bytes()); + b[30..34].copy_from_slice(&compression.to_le_bytes()); + b.extend_from_slice(pixels); + b + } + + #[test] + fn dimensions_and_padded_rows() { + let b = bmp(0, &[0; 7]); + assert_eq!(dimensions(&b), Some((4, 2))); + assert_eq!(coverage(&b, 4, 2), Coverage { pixels: 8, row_bytes: Some((7, 8)) }); + assert_eq!(dimensions(&b[..20]), None); + } + + #[test] + fn rle_counts_clipped_runs_deltas_and_complete_absolute_blocks() { + let b = bmp(1, &[3, 7, 0, 0, 0, 2, 1, 0, 0, 3, 1, 2, 3, 0, 0, 1]); + assert_eq!(coverage(&b, 4, 2).pixels, 6); + let truncated = bmp(1, &[0, 4, 1, 2]); + assert_eq!(coverage(&truncated, 4, 2).pixels, 0); + let nibble = bmp(2, &[0, 3, 0x12, 0x30, 0, 1]); + assert_eq!(coverage(&nibble, 4, 2).pixels, 3); + } +} diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 5a84e6368..adeed0825 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -16,6 +16,7 @@ mod allocation; pub mod apng; +pub mod bmp_probe; pub mod cicp; mod codecs; mod error;