From 62e09222f1499e0c0e71ef5a1c3208fe127ab5b0 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Thu, 12 Nov 2026 21:16:46 +0100 Subject: [PATCH 001/349] craft-video: AV1 decoding about 1.7x as fast with many threads Port of storytold/Filmcraft#4542 (the code moved here). Frames start as soon as the reference rows they read are done (row wavefront across frames), parsing is split from reconstruction, and there is one frame worker per thread. Output is bit-identical; single-thread speed is unchanged. Co-Authored-By: Claude Sonnet 5.5 --- crates/video/src/av1/decode/README.md | 54 +- crates/video/src/av1/decode/cdef.rs | 30 +- crates/video/src/av1/decode/decoder.rs | 1154 +++++++++++++++-- crates/video/src/av1/decode/frame.rs | 166 +++ crates/video/src/av1/decode/inter.rs | 29 +- crates/video/src/av1/decode/postfilter.rs | 160 ++- crates/video/src/av1/decode/restoration.rs | 14 +- crates/video/src/av1/decode/state.rs | 29 +- crates/video/src/av1/decode/tile.rs | 314 ++++- crates/video/src/av1/decode/tile/coeffs.rs | 52 + crates/video/src/av1/decode/tile/predict.rs | 23 +- crates/video/tests/av1_decode/fuzz_hostile.rs | 70 +- crates/video/tests/av1_decode/main.rs | 1 + crates/video/tests/av1_decode/wavefront.rs | 93 ++ 14 files changed, 1992 insertions(+), 197 deletions(-) create mode 100644 crates/video/tests/av1_decode/wavefront.rs diff --git a/crates/video/src/av1/decode/README.md b/crates/video/src/av1/decode/README.md index 1518df92c..e1b8e4732 100644 --- a/crates/video/src/av1/decode/README.md +++ b/crates/video/src/av1/decode/README.md @@ -73,11 +73,17 @@ with libdav1d: **bit-exact** on all 6 fixtures. `Decoder::new()` uses all cores (`Decoder::with_threads(1)` decodes on the calling thread; on wasm32, or without the default `threads` feature, everything runs on the calling thread). Headers are parsed in order; each frame is -then decoded by a frame worker once the reference frames it reads are finished, so independent -frames (hierarchical GOP layers) decode concurrently; tiles of a frame decode in parallel into -private buffers that are merged afterwards; the in-loop filters (deblocking, CDEF, loop -restoration) each run in parallel bands of 64 rows (`postfilter.rs` explains why the bands are -independent). Results never depend on scheduling (the oracle tests compare 1 thread, many threads +then decoded by a frame worker. With worker threads it first reads the symbols of all its tiles, +which needs only the parse results of its references (CDFs, segment ids, saved motion vectors), +publishes its own, and then reconstructs from the recorded blocks. Frames with several tiles +read the symbols of their tiles in parallel (one after another with intra block copy). A frame reconstructs superblock row by superblock +row (that row of every tile), each row waiting only for the reference rows its motion vectors +reach (row wavefront), and the in-loop filters (deblocking, CDEF, loop restoration) follow a few +64-row bands behind and publish each final band for the frames predicting from it +(`decoder.rs` and `postfilter.rs` give the dependency rules). Super-resolution frames wait for +their whole references and filter the whole frame. There is one frame worker per thread (at most +16), and the frames in flight are bounded by their size. Independent frames (hierarchical GOP +layers) decode concurrently. Results never depend on scheduling (the oracle tests compare 1 thread, many threads and libdav1d). With frame threads, pictures may be returned by a later `decode_pts` call or by `flush`; each carries the `pts` of the temporal unit that showed it. @@ -130,6 +136,44 @@ motion vectors nor CDFs reach another frame — skip deblocking, CDEF and loop r (super-resolution still runs, it sets the output size) and are flagged `Picture::draft`. In SVT-AV1's hierarchical GOPs that is the top layer, half of the frames. +Frame threading on a Ryzen 7800X3D (8 cores / 16 threads, release `examples/av1_av1dec`, median of 7 +alternating runs against Filmcraft `6909e461`, 2026-11-08), wall time for the whole file: + +| Fixture | Threads | Before | After | Speed-up | +|---|---|---|---|---| +| `perf_1080p_gop` (60 frames) | 1 | 69.2 fps | 69.1 fps | 1.00x | +| `perf_1080p_gop` | 16 | 159.6 fps | 227.3 fps | 1.42x | +| `perf_2160p_gop` (30 frames) | 1 | 17.9 fps | 17.8 fps | 1.00x | +| `perf_2160p_gop` | 16 | 40.2 fps | 57.7 fps | 1.43x | + +Peak RSS at 16 threads goes from 278 to 365 MB (1080p) and from 1031 to 1217 MB (2160p, +18%): +every frame in flight holds its parse record and its final samples are kept in 64-row bands. + +With one frame worker per thread, the row wavefront for frames with several tiles and parse +waits limited to what parsing reads (same machine, median of 5 alternating runs, 2026-11-08): + +| Fixture | Threads | Before (`6909e461`) | After | Speed-up | Peak RSS before / after | +|---|---|---|---|---|---| +| `perf_1080p_gop` | 4 | 95.7 fps | 185.2 fps | 1.94x | 148 / 236 MB | +| `perf_1080p_gop` | 16 | 155.0 fps | 259.7 fps | 1.68x | 274 / 560 MB | +| `perf_2160p_gop` | 4 | 23.6 fps | 47.1 fps | 2.00x | 512 / 798 MB | +| `perf_2160p_gop` | 16 | 39.9 fps | 65.8 fps | 1.65x | 994 / 1353 MB | +| `perf_1080p_gop_tiles` (4x2 tiles) | 16 | 186.3 fps | 237.2 fps | 1.27x | 328 / 617 MB | +| SVT-AV1 2160p, 4x2 tiles (30 frames) | 16 | 57.1 fps | 70.8 fps | 1.24x | 1197 / 1502 MB | + +Known limitations of the frame threading (the output is the same in every case, only the +overlap is smaller): + +- A frame whose parse record would pass 32 bytes per luma sample of a tile (pathological streams: + tiny blocks, large palettes, every coefficient coded), or that cannot reserve its record from + the decoder-wide budget of 1 GiB shared by the frames in flight, is decoded again in one pass. +- A superblock row using local warped motion, global motion beyond translation or a scaled + reference waits for the whole reference instead of the rows its motion vectors reach. +- Super-resolution frames do not use the row wavefront: they wait for their whole references + and filter the whole frame. +- The tile columns of a superblock row are reconstructed one after another on the frame's worker + (their symbols are still read in parallel). + ## Limits Frames beyond the AV1 level 6.x limits (Annex A: at most 16384 wide, 8704 high and 35 651 584 luma samples diff --git a/crates/video/src/av1/decode/cdef.rs b/crates/video/src/av1/decode/cdef.rs index edd119292..05eb0a2a7 100644 --- a/crates/video/src/av1/decode/cdef.rs +++ b/crates/video/src/av1/decode/cdef.rs @@ -10,19 +10,33 @@ use crate::av1::decode::state::FrameState; /// equals CurrFrame). Bands of 64 luma rows (whole 64x64 filter blocks) are filtered in /// parallel: every block reads only CurrFrame and writes only its own samples. pub(crate) fn apply(fs: &FrameState, pool: &Pool) -> Option { + if !active(fs) { + return None; + } + let mut out = fs.cur.clone(); + let ranges = bands(pool, fs.fh.mi_rows as usize * 4); + filter_bands(fs, pool, out.row_bands(&ranges), &ranges); + Some(out) +} + +/// Whether CDEF filters any block of the frame (it reads only parse results). +pub(crate) fn active(fs: &FrameState) -> bool { let fh = &fs.fh; if fh.coded_lossless || fh.allow_intrabc || !fs.seq.enable_cdef { - return None; + return false; } let (mi_rows, mi_cols) = (fh.mi_rows as usize, fh.mi_cols as usize); let fb_rows = mi_rows.div_ceil(16); let fb_cols = mi_cols.div_ceil(16); - if !(0..fb_rows).any(|fr| (0..fb_cols).any(|fc| fb_skip_mask(fs, fr * 16, fc * 16).is_some())) { - return None; - } - let mut out = fs.cur.clone(); - let ranges = bands(pool, mi_rows * 4); - let mut planes = out.row_bands(&ranges); + (0..fb_rows).any(|fr| (0..fb_cols).any(|fc| fb_skip_mask(fs, fr * 16, fc * 16).is_some())) +} + +/// Filter the bands `planes` covering luma rows `ranges` (whole 64x64 filter block rows), which +/// hold CurrFrame; reads CurrFrame up to 2 rows beyond each band. +pub(crate) fn filter_bands(fs: &FrameState, pool: &Pool, mut planes: Vec<[RowBand; 3]>, ranges: &[(usize, usize)]) { + let (mi_rows, mi_cols) = (fs.fh.mi_rows as usize, fs.fh.mi_cols as usize); + let fb_rows = mi_rows.div_ceil(16); + let fb_cols = mi_cols.div_ceil(16); pool.map_mut(&mut planes, |b, band| { let (start, end) = ranges[b]; let mut buf = [0i16; BUF_LEN]; @@ -34,8 +48,6 @@ pub(crate) fn apply(fs: &FrameState, pool: &Pool) -> Option { } } }); - drop(planes); - Some(out) } /// The filtered 8x8 blocks of the 64x64 filter block at (r, c): bit `(i << 3) | j` is set for diff --git a/crates/video/src/av1/decode/decoder.rs b/crates/video/src/av1/decode/decoder.rs index 3fb1f1326..dc9caf74b 100644 --- a/crates/video/src/av1/decode/decoder.rs +++ b/crates/video/src/av1/decode/decoder.rs @@ -2,31 +2,37 @@ //! (7.20), show-existing-frame and output (7.18). //! //! Threading: headers are parsed in order on the calling thread; each frame then becomes a job -//! that waits for the reference frames it uses and decodes on a frame worker thread, so frames -//! that do not depend on each other decode concurrently. Within a frame, tiles and the -//! post-filter row bands run on a shared worker pool. Every result depends only on finished -//! reference frames, so the output is identical whatever the scheduling. Shown pictures are -//! returned in order; with frame threads they can come out of a later `decode` call (or -//! `flush`), each carrying the `pts` of the temporal unit that showed it. +//! on a frame worker thread. A job first reads the symbols of its tiles (parse), which needs +//! only the parse results of its references (CDFs, segment ids, saved motion vectors), and +//! publishes its own; it then reconstructs. A frame is reconstructed superblock row by +//! superblock row (that row of every tile), each row waiting only for the reference rows its +//! motion vectors reach, with the in-loop filters following a few bands behind and every final +//! band published for the frames that predict from it (row wavefront); super-resolution frames +//! wait for their whole references. So a frame can parse while its references are still being reconstructed, and reconstruct +//! while their bottom is still being filtered. Within a frame, tiles and the post-filter row +//! bands run on a shared worker pool; waits happen only on frame worker threads. Every result +//! depends only on final reference data, so the output is identical whatever the scheduling. +//! Shown pictures are returned in order; with frame threads they can come out of a later +//! `decode` call (or `flush`), each carrying the `pts` of the temporal unit that showed it. use std::collections::VecDeque; use std::sync::{Arc, Condvar, Mutex}; use crate::av1::decode::bits::{BitReader, leb128}; use crate::av1::decode::cdf::Cdfs; -use crate::av1::decode::frame::FrameBuf; +use crate::av1::decode::frame::{BandFrame, FrameBuf, PlaneRef}; use crate::av1::decode::header::{ ColorConfig, FilmGrainParams, FrameHeader, HeaderState, LoopFilterDeltas, RefInfo, SegmentationFeatures, SequenceHeader, default_gm_params, }; use crate::av1::decode::par::Pool; use crate::av1::decode::spec_tables::{ - ALTREF_FRAME, ALTREF2_FRAME, BWDREF_FRAME, DEFAULT_INTRA_FRAME_Y_MODE_CDF, DIV_MULT, GOLDEN_FRAME, INTRA_FRAME, INTRA_ONLY_FRAME, KEY_FRAME, - LAST_FRAME, LAST2_FRAME, MAX_FRAME_DISTANCE, MAX_OFFSET_HEIGHT, MAX_OFFSET_WIDTH, MFMV_STACK_SIZE, NUM_REF_FRAMES, PRIMARY_REF_NONE, - REFMVS_LIMIT, REFS_PER_FRAME, + ALTREF_FRAME, ALTREF2_FRAME, BWDREF_FRAME, DEFAULT_INTRA_FRAME_Y_MODE_CDF, DIV_MULT, GLOBAL_GLOBALMV, GLOBALMV, GOLDEN_FRAME, INTRA_FRAME, + INTRA_ONLY_FRAME, KEY_FRAME, LAST_FRAME, LAST2_FRAME, LOCALWARP, MAX_FRAME_DISTANCE, MAX_OFFSET_HEIGHT, MAX_OFFSET_WIDTH, MFMV_STACK_SIZE, + NUM_REF_FRAMES, PRIMARY_REF_NONE, REFMVS_LIMIT, REFS_PER_FRAME, TRANSLATION, }; use crate::av1::decode::state::{FrameShared, FrameState, TileState}; use crate::av1::decode::stats::{DecodeStats, Stage, Timer}; -use crate::av1::decode::tile::TileDecoder; +use crate::av1::decode::tile::{Pass, TileDecoder, TileRecord}; use crate::av1::decode::{Error, Picture, Result}; /// Largest accepted frame: the AV1 level 6.x limits (Annex A: MaxHSize 16384, MaxVSize 8704, MaxPicSize @@ -49,22 +55,156 @@ const OBU_FRAME_T: u32 = 6; const OBU_REDUNDANT_FRAME_HEADER_T: u32 = 7; const OBU_TILE_LIST_T: u32 = 8; -/// A stored reference frame (FrameStore plus the saved per-frame state). +/// The samples of a stored reference frame (FrameStore), after every in-loop filter: a whole +/// buffer (decoding on one thread) or the bands published while decoding (with worker threads). pub(crate) struct RefFrame { pub buf: FrameBuf, - pub cdfs: Box, + pub bands: Option>, + pub num_planes: usize, pub bit_depth: u8, pub subsampling_x: u8, pub subsampling_y: u8, + pub color: (u8, u8, u8, bool), +} + +impl RefFrame { + pub fn plane(&self, p: usize) -> PlaneRef<'_> { + match &self.bands { + Some(b) => PlaneRef::Bands(&b.planes[p]), + None => PlaneRef::Whole(&self.buf.planes[p]), + } + } +} + +/// The saved per-frame state that later frames read while parsing (CDFs, segment ids and the +/// motion vectors for motion field estimation). It depends only on the frame's symbols, so it +/// is published as soon as the tiles are decoded, before the in-loop filters run. +pub(crate) struct Parsed { + pub cdfs: Box, pub segment_ids: Vec, pub mi_cols: usize, pub mi_rows: usize, - pub color: (u8, u8, u8, bool), - /// SavedRefFrames / SavedMvs (MfRefFrames / MfMvs of 7.19), mi units. + /// SavedRefFrames / SavedMvs (MfRefFrames / MfMvs of 7.19) at the odd row and column of + /// every 8x8 block, the only positions the projection reads. pub saved_ref_frames: Vec, pub saved_mvs: Vec<[i32; 2]>, } +/// How many luma rows of a frame are final (every in-loop filter applied), or that the frame +/// failed. Rows only ever grow; a failure wakes every waiter with an error. +pub(crate) struct Progress { + state: Mutex, + cv: Condvar, +} + +#[derive(Clone, Copy, Default)] +struct ProgressState { + rows: usize, + failed: bool, +} + +impl Progress { + fn new() -> Progress { + Progress { state: Mutex::new(ProgressState::default()), cv: Condvar::new() } + } + + /// Rows [0, rows) are final. A smaller value than already published is ignored. + pub fn publish(&self, rows: usize) { + #[cfg(test)] + tests::jitter(); + let mut g = self.state.lock().unwrap_or_else(|e| e.into_inner()); + if rows > g.rows { + g.rows = rows; + self.cv.notify_all(); + } + } + + /// The frame will publish no more rows. + pub fn fail(&self) { + let mut g = self.state.lock().unwrap_or_else(|e| e.into_inner()); + g.failed = true; + self.cv.notify_all(); + } + + /// Rows published so far. + #[cfg(test)] + fn rows(&self) -> usize { + self.state.lock().map(|g| g.rows).unwrap_or(0) + } + + /// Blocks until rows [0, rows) are final; an error when the frame failed first. + pub fn wait(&self, rows: usize) -> Result<()> { + #[cfg(test)] + tests::jitter(); + let mut g = self.state.lock().unwrap_or_else(|e| e.into_inner()); + loop { + if g.rows >= rows { + return Ok(()); + } + if g.failed { + return Err(Error::Invalid("reference frame failed to decode")); + } + g = self.cv.wait(g).unwrap_or_else(|e| e.into_inner()); + } + } +} + +/// Everything a decoding frame publishes for the frames that reference it and for the output: +/// its parse results, its final rows (bands, then the row progress) and the finished frame. The +/// parse results and the frame are set exactly once and the progress ends complete or failed, +/// also when decoding fails, so no waiter blocks forever. +pub(crate) struct FrameSlot { + parsed: Slot>, + pub progress: Progress, + /// The final samples, published band by band before the progress covers them (with + /// worker threads). + pub bands: Arc, + frame: Slot>, +} + +impl FrameSlot { + fn new(bands: BandFrame) -> Arc { + Arc::new(FrameSlot { parsed: Slot::new_plain(), progress: Progress::new(), bands: Arc::new(bands), frame: Slot::new_plain() }) + } + + /// The finished frame. + fn wait(&self) -> Result> { + self.frame.wait() + } + + fn is_set(&self) -> bool { + self.frame.is_set() + } + + /// The frame's parse results (available before its samples are final). + fn wait_parsed(&self) -> Result> { + self.parsed.wait() + } + + /// Publish the parse results (ignored when already set). + fn set_parsed(&self, v: Result>) { + self.parsed.set_once(v); + } + + /// Publish the finished frame: every row is final. On an error, the parse results (when + /// not yet published) and the progress fail too. + fn finish(&self, v: Result>, rows: usize) { + match &v { + Ok(_) => {} + Err(e) => { + self.parsed.set_once(Err(e.clone())); + } + } + let ok = v.is_ok(); + self.frame.set(v); + if ok { + self.progress.publish(rows); + } else { + self.progress.fail(); + } + } +} + /// A value produced by a decoding job, waited for by later jobs and by the output. pub(crate) struct Slot { value: Mutex>>, @@ -73,7 +213,11 @@ pub(crate) struct Slot { impl Slot { fn new() -> Arc> { - Arc::new(Slot { value: Mutex::new(None), cv: Condvar::new() }) + Arc::new(Slot::new_plain()) + } + + fn new_plain() -> Slot { + Slot { value: Mutex::new(None), cv: Condvar::new() } } fn set(&self, v: Result) { @@ -82,6 +226,15 @@ impl Slot { self.cv.notify_all(); } + /// [`Slot::set`] unless a value is already there. + fn set_once(&self, v: Result) { + let mut g = self.value.lock().unwrap_or_else(|e| e.into_inner()); + if g.is_none() { + *g = Some(v); + self.cv.notify_all(); + } + } + fn is_set(&self) -> bool { self.value.lock().map(|g| g.is_some()).unwrap_or(true) } @@ -108,8 +261,6 @@ impl Slot { } } -type FrameSlot = Slot>; - /// Everything needed to decode one frame, captured when its header is parsed. struct FrameJob { seq: SequenceHeader, @@ -130,6 +281,15 @@ struct FrameJob { draft: bool, #[cfg(test)] force_panic: bool, + /// Panic in the row wavefront at the first superblock row from this one after which rows + /// are published (tests). + #[cfg(test)] + panic_at_row: Option, + /// Overrides [`RECORD_BYTES_PER_SAMPLE`] (tests). + #[cfg(test)] + record_limit: Option, + /// The decoder's parse record budget. + record_budget: Arc, } /// A shown picture in output order. @@ -251,6 +411,8 @@ pub struct Decoder { draft: bool, stats: Arc>, pool: Pool, + /// Parse record bytes all frames in flight may hold together. + record_budget: Arc, #[cfg(all(feature = "threads", not(target_arch = "wasm32")))] workers: Option, /// Frames submitted to the workers and not known to be finished (oldest first). @@ -265,6 +427,14 @@ pub struct Decoder { /// Make every frame job panic (tests of the worker panic handling). #[cfg(test)] force_panic: bool, + /// (frame number, superblock row): that frame panics in the row wavefront after that row, + /// once it has published rows that later frames may already be using (tests). + #[cfg(test)] + panic_at_row: Option<(usize, usize)>, + #[cfg(test)] + record_limit: Option, + #[cfg(test)] + frame_number: usize, } fn default_threads() -> usize { @@ -278,10 +448,25 @@ fn default_threads() -> usize { } } -/// Frames decoded concurrently with `threads` threads (each in-flight 1080p frame holds a few -/// tens of MB of state). +/// Frame worker threads with `threads` threads. A frame worker spends most of its time waiting +/// for the parse results and rows of its references, so there is one per thread (at least two, +/// at most [`MAX_FRAME_THREADS`]); the memory is bounded by `in_flight_limit` instead. fn frame_threads(threads: usize) -> usize { - if threads <= 1 { 1 } else { threads.div_ceil(2).clamp(2, 8) } + if threads <= 1 { 1 } else { threads.clamp(2, MAX_FRAME_THREADS) } +} + +const MAX_FRAME_THREADS: usize = 16; + +/// Luma samples of the frames in flight (each in-flight frame holds its state, parse record and +/// samples, roughly 10 bytes per luma sample): ten 2160p frames. +#[cfg(all(feature = "threads", not(target_arch = "wasm32")))] +const IN_FLIGHT_SAMPLES: usize = 10 * 3840 * 2160; + +/// Frames submitted to the frame workers that may be unfinished: two more than the workers, +/// fewer for large frames (at least four). +#[cfg(all(feature = "threads", not(target_arch = "wasm32")))] +fn in_flight_limit(frame_threads: usize, luma_samples: usize) -> usize { + (frame_threads + 2).min((IN_FLIGHT_SAMPLES / luma_samples.max(1)).max(4)) } impl Default for Decoder { @@ -379,6 +564,7 @@ impl Decoder { draft: false, stats, pool, + record_budget: Arc::new(crate::av1::decode::tile::RecordBudget::new(RECORD_BUDGET_BYTES)), #[cfg(all(feature = "threads", not(target_arch = "wasm32")))] workers, in_flight: VecDeque::new(), @@ -388,6 +574,12 @@ impl Decoder { pts: 0, #[cfg(test)] force_panic: false, + #[cfg(test)] + panic_at_row: None, + #[cfg(test)] + record_limit: None, + #[cfg(test)] + frame_number: 0, } } @@ -655,6 +847,13 @@ impl Decoder { let picture = fh.show_frame.then(Slot::new); let draft = self.draft && fh.show_frame && fh.refresh_frame_flags == 0; let tile_count = fh.tile_info.cols.checked_mul(fh.tile_info.rows).ok_or(Error::Invalid("tile count overflows"))?; + let slot = FrameSlot::new(BandFrame::new( + fh.upscaled_width as usize, + fh.frame_height as usize, + seq.color.num_planes, + seq.color.subsampling_x as usize, + seq.color.subsampling_y as usize, + )); self.pending = Some(Box::new(FrameJob { seq, fh, @@ -662,14 +861,23 @@ impl Decoder { ref_info: self.refs.clone(), tiles: Vec::new(), tile_covered: vec![false; tile_count], - slot: Slot::new(), + slot, picture, pts: self.pts, apply_film_grain: self.apply_film_grain, draft, #[cfg(test)] force_panic: self.force_panic, + #[cfg(test)] + panic_at_row: self.panic_at_row.filter(|&(f, _)| f == self.frame_number).map(|(_, r)| r), + #[cfg(test)] + record_limit: self.record_limit, + record_budget: self.record_budget.clone(), })); + #[cfg(test)] + { + self.frame_number += 1; + } Ok(None) } @@ -767,6 +975,8 @@ impl Decoder { .clone() .map(|p| Output::Decoded(p, picture_bytes(job.fh.upscaled_width as usize, job.fh.frame_height as usize, &job.seq.color))); #[cfg(all(feature = "threads", not(target_arch = "wasm32")))] + let fh_samples = (fh.upscaled_width as usize).max(fh.frame_width as usize) * fh.frame_height as usize; + #[cfg(all(feature = "threads", not(target_arch = "wasm32")))] if let Some(w) = &self.workers && let Some(tx) = &w.tx { @@ -775,7 +985,8 @@ impl Decoder { Ok(()) => { self.in_flight.push_back(slot); // Bound the frames in flight (memory): wait for the oldest. - while self.in_flight.len() > self.max_in_flight { + let limit = in_flight_limit(w.handles.len(), fh_samples); + while self.in_flight.len() > limit { let Some(s) = self.in_flight.pop_front() else { break }; let _ = s.wait(); } @@ -796,18 +1007,19 @@ impl Decoder { fn run_job(job: FrameJob, pool: &Pool, stats: &Mutex) { let mut st = DecodeStats::default(); let res = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| decode_frame(&job, pool, &mut st))); + let rows = job.fh.frame_height as usize; match res.unwrap_or(Err(Error::Invalid("decoder panicked"))) { Ok((rf, pic)) => { if let Some(ps) = &job.picture { ps.set(pic.ok_or(Error::Invalid("shown frame without picture"))); } - job.slot.set(Ok(rf)); + job.slot.finish(Ok(rf), rows); } Err(e) => { if let Some(ps) = &job.picture { ps.set(Err(e.clone())); } - job.slot.set(Err(e)); + job.slot.finish(Err(e), rows); } } if let Ok(mut s) = stats.lock() { @@ -832,71 +1044,191 @@ fn decode_frame(job: &FrameJob, pool: &Pool, stats: &mut DecodeStats) -> Result< if fh.primary_ref_frame != PRIMARY_REF_NONE { used[fh.ref_frame_idx[fh.primary_ref_frame]] = true; } - let mut refs: [Option>; NUM_REF_FRAMES] = Default::default(); - for i in 0..NUM_REF_FRAMES { - if used[i] { - let slot = job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?; - refs[i] = Some(slot.wait()?); + // Prediction reads the reference planes with this frame's chroma format. + if !fh.frame_is_intra { + for i in 0..NUM_REF_FRAMES { + let Some(slot) = job.refs[i].as_ref().filter(|_| used[i]) else { continue }; + let b = &slot.bands; + let c = &seq.color; + if b.num_planes != c.num_planes || b.subsampling_x != c.subsampling_x as usize || b.subsampling_y != c.subsampling_y as usize { + return Err(Error::Invalid("reference frame has another chroma format")); + } } } - let t = Timer::start(); - let mut fs = FrameState::new(seq, fh); - fs.refs = refs; - fs.ref_info = job.ref_info.clone(); + // Parse dependencies first, then the samples. Parsing reads the CDFs and segment ids of + // the primary reference frame, and the saved motion vectors of the inter references only + // with use_ref_frame_mvs; the parse results of the other references are not waited for + // (their failures still fail this frame through the waits for their samples below). + let mut parse_deps = [false; NUM_REF_FRAMES]; if fh.primary_ref_frame != PRIMARY_REF_NONE { - // load_previous_segment_ids( ) - let (mi_cols, mi_rows) = (fs.mi.cols, fs.mi.rows); - let sh = &mut fs.sh; - if let Some(rf) = &sh.refs[fh.ref_frame_idx[fh.primary_ref_frame]] - && fh.seg.enabled - && rf.mi_cols == mi_cols - && rf.mi_rows == mi_rows - { - sh.prev_segment_ids.copy_from_slice(&rf.segment_ids); - } + parse_deps[fh.ref_frame_idx[fh.primary_ref_frame]] = true; } if fh.use_ref_frame_mvs { - motion_field_estimation(&mut fs); + for i in 0..REFS_PER_FRAME { + parse_deps[fh.ref_frame_idx[i]] = true; + } } - let mut cdfs = if fh.primary_ref_frame == PRIMARY_REF_NONE { - Cdfs::new(fh.quant.base_q_idx) - } else { - let rf = fs.refs[fh.ref_frame_idx[fh.primary_ref_frame]].as_ref().ok_or(Error::Invalid("primary reference frame missing"))?; - let mut c = rf.cdfs.clone(); - c.clear_counts(); - c + let mut parsed: [Option>; NUM_REF_FRAMES] = Default::default(); + for i in 0..NUM_REF_FRAMES { + if parse_deps[i] { + let slot = job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?; + parsed[i] = Some(slot.wait_parsed()?); + } + } + // The samples of the references predicted from (inter frames only). + let wait_samples = || -> Result<[Option>; NUM_REF_FRAMES]> { + let mut refs: [Option>; NUM_REF_FRAMES] = Default::default(); + if !fh.frame_is_intra { + for i in 0..NUM_REF_FRAMES { + if used[i] { + let slot = job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?; + slot.progress.wait(job.ref_info[i].frame_height as usize)?; + refs[i] = Some(slot.wait()?); + } + } + } + Ok(refs) }; + // With worker threads, the symbols of every tile are read first, so the parse results + // (which the next frames need before they can read their own symbols) are published + // before reconstruction, and parsing does not wait for the reference samples; on one + // thread each block is reconstructed as it is read. + let split = pool.is_parallel(); + // The frame state before tile decoding (with the reference samples when `with_refs`). + let setup = |with_refs: bool| -> Result<(FrameState, Box)> { + let mut fs = FrameState::new(seq, fh); + if with_refs { + fs.refs = wait_samples()?; + } + fs.parsed = parsed.clone(); + fs.ref_info = job.ref_info.clone(); + if fh.primary_ref_frame != PRIMARY_REF_NONE { + // load_previous_segment_ids( ) + let (mi_cols, mi_rows) = (fs.mi.cols, fs.mi.rows); + let sh = &mut fs.sh; + if let Some(rf) = &sh.parsed[fh.ref_frame_idx[fh.primary_ref_frame]] + && fh.seg.enabled + && rf.mi_cols == mi_cols + && rf.mi_rows == mi_rows + { + sh.prev_segment_ids.copy_from_slice(&rf.segment_ids); + } + } + if fh.use_ref_frame_mvs { + motion_field_estimation(&mut fs); + } + let cdfs = if fh.primary_ref_frame == PRIMARY_REF_NONE { + Cdfs::new(fh.quant.base_q_idx) + } else { + let rf = fs.parsed[fh.ref_frame_idx[fh.primary_ref_frame]].as_ref().ok_or(Error::Invalid("primary reference frame missing"))?; + let mut c = rf.cdfs.clone(); + c.clear_counts(); + c + }; + Ok((fs, cdfs)) + }; + let t = Timer::start(); + let (mut fs, mut cdfs) = setup(!split)?; stats.add(Stage::Setup, t.secs()); let t = Timer::start(); - let saved = decode_tiles(pool, &mut fs, &cdfs, &job.tiles)?; + // Time spent waiting for reference samples is not decoding time. + let mut waited = 0.0; + #[cfg(not(test))] + let record_limit = RECORD_BYTES_PER_SAMPLE; + #[cfg(test)] + let record_limit = job.record_limit.unwrap_or(RECORD_BYTES_PER_SAMPLE); + let mut tiles = parse_tiles(pool, &mut fs, &cdfs, &job.tiles, if split { Pass::Parse } else { Pass::Full }, record_limit, &job.record_budget)?; + // A frame whose record would take too much memory (pathological streams) is decoded again + // in one pass, as on one thread. + let one_pass = split && tiles.records.iter().any(|(_, r)| r.over_limit()); + if one_pass { + // The fallback starts again from the tile data: release the records first. + drop(tiles); + let wait = Timer::start(); + (fs, cdfs) = setup(true)?; + waited = wait.secs(); + tiles = parse_tiles(pool, &mut fs, &cdfs, &job.tiles, Pass::Full, record_limit, &job.record_budget)?; + } stats.tiles += job.tiles.len() as u64; - stats.add(Stage::Tiles, t.secs()); if !fh.disable_frame_end_update_cdf - && let Some(s) = saved + && let Some(s) = tiles.saved.take() { cdfs = s; } - crate::av1::decode::postfilter::apply(&mut fs, stats, pool, job.draft); + if split && !one_pass { + if tiles.whole { + if let Some(state) = tiles.states.pop() { + fs.put_tile_state(state); + job.slot.set_parsed(Ok(Arc::new(parse_results(&fs, cdfs)))); + tiles.states.push(fs.take_tile_state()); + } + } else { + for state in &tiles.states { + fs.merge_tile_modes(state); + } + job.slot.set_parsed(Ok(Arc::new(parse_results(&fs, cdfs)))); + } + if !fh.use_superres { + if !tiles.whole { + // The tiles were parsed into private buffers, merged into the frame above: + // reconstruct them in the frame's own buffers. + tiles.states.clear(); + tiles.states.push(fs.take_tile_state()); + tiles.whole = true; + } + // Reconstruct superblock row by superblock row (every tile of the row), each + // waiting only for the reference rows it reads, with the in-loop filters following + // behind. + waited = reconstruct_wavefront(job, pool, &mut fs, &mut tiles, stats)?; + } else { + let wait = Timer::start(); + fs.refs = wait_samples()?; + waited = wait.secs(); + reconstruct_tiles(pool, &fs.sh, &mut tiles)?; + tiles.finish(&mut fs); + let f = Timer::start(); + if fh.use_superres { + crate::av1::decode::postfilter::apply(&mut fs, stats, pool, job.draft); + publish_bands(&job.slot, &fs.cur, 0, usize::MAX, fh.frame_height as usize); + } else { + let mut pipe = crate::av1::decode::postfilter::Pipeline::new(&fs, job.draft); + let done = pipe.advance(&mut fs, stats, pool, usize::MAX); + publish_final(&job.slot, done, fh.frame_height as usize); + } + waited += f.secs(); + } + } else { + tiles.finish(&mut fs); + job.slot.set_parsed(Ok(Arc::new(parse_results(&fs, cdfs)))); + } + stats.add(Stage::Tiles, t.secs() - waited); + if !split || one_pass { + crate::av1::decode::postfilter::apply(&mut fs, stats, pool, job.draft); + } + if one_pass { + publish_bands(&job.slot, &fs.cur, 0, usize::MAX, fh.frame_height as usize); + } + if split { + // A frame using a reference only for its parse results (an intra frame's CDFs) still + // fails with it, as it does on one thread. + for i in 0..NUM_REF_FRAMES { + if used[i] { + job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?.wait()?; + } + } + } stats.draft_frames += job.draft as u64; let t = Timer::start(); stats.frames += 1; - if fh.seg.enabled && !fh.seg.update_map { - let prev = std::mem::take(&mut fs.prev_segment_ids); - fs.mi.segment_id.copy_from_slice(&prev); - } - let (mf_refs, mf_mvs) = motion_vector_storage(&fs); let rf = Arc::new(RefFrame { - buf: std::mem::take(&mut fs.cur), - cdfs, + // With worker threads the samples are in the published bands. + buf: if split { FrameBuf::default() } else { std::mem::take(&mut fs.cur) }, + bands: split.then(|| job.slot.bands.clone()), + num_planes: seq.color.num_planes, bit_depth: seq.color.bit_depth, subsampling_x: seq.color.subsampling_x, subsampling_y: seq.color.subsampling_y, - segment_ids: std::mem::take(&mut fs.mi.segment_id), - mi_cols: fs.mi.cols, - mi_rows: fs.mi.rows, color: (seq.color.color_primaries, seq.color.transfer_characteristics, seq.color.matrix_coefficients, seq.color.color_range), - saved_ref_frames: mf_refs, - saved_mvs: mf_mvs, }); // job.picture is None for a shown frame refused for its size (see tile_group) let pic = job.picture.is_some().then(|| { @@ -908,16 +1240,256 @@ fn decode_frame(job: &FrameJob, pool: &Pool, stats: &mut DecodeStats) -> Result< Ok((rf, pic)) } -/// Decode the tiles of a frame (tile number, data), in parallel when several; returns the final -/// CDFs of tile context_update_tile_id. -fn decode_tiles(pool: &Pool, fs: &mut FrameState, cdfs: &Cdfs, tiles: &[(usize, Vec)]) -> Result>> { +/// Publish bands [from, to) copied from the final samples `src`, and the row progress they make +/// final. +fn publish_bands(slot: &FrameSlot, src: &FrameBuf, from: usize, to: usize, height: usize) { + let to = to.min(slot.bands.bands()); + for b in from..to { + slot.bands.publish(b, src); + } + slot.progress.publish((to << crate::av1::decode::frame::BAND_LOG2).min(height)); +} + +/// Publish the bands that became final (in order, following those published before) and the +/// row progress they make final. +fn publish_final(slot: &FrameSlot, bands: crate::av1::decode::postfilter::FinalBands, height: usize) { + let mut end = None; + for (b, planes) in bands { + slot.bands.publish_owned(b, planes); + end = Some(b + 1); + } + if let Some(end) = end { + slot.progress.publish((end << crate::av1::decode::frame::BAND_LOG2).min(height)); + } +} + +/// Extra luma rows waited for below what a motion vector reaches: the 8-tap filters read 4 +/// rows below a block, chroma positions round, and the vertical sub-sample phase adds one. +const ROW_WAIT_MARGIN: usize = 16; + +/// The rows of each reference slot that reconstructing the blocks `blocks` (a superblock row +/// and the row above it, whose motion overlapped block motion compensation can reuse) reads, +/// for blocks ending at luma row `bottom`: their reach plus a margin, or everything +/// (`usize::MAX`) for warped motion and scaled references, whose reach is not bounded by the +/// motion vector. +fn rows_needed( + fh: &FrameHeader, + ref_info: &[RefInfo; NUM_REF_FRAMES], + blocks: impl Iterator, + bottom: usize, +) -> [usize; NUM_REF_FRAMES] { + let mut need = [0usize; NUM_REF_FRAMES]; + let mut used = [false; NUM_REF_FRAMES]; + let mut warp = false; + let global = (LAST_FRAME..=ALTREF_FRAME).any(|r| fh.gm_type[r] as usize > TRANSLATION); + for b in blocks { + if !b.inter { + continue; + } + if b.motion_mode as usize == LOCALWARP || (global && (b.y_mode == GLOBALMV || b.y_mode == GLOBAL_GLOBALMV)) { + warp = true; + } + let bottom = bottom.max((b.mi_row + b.bh4) * 4); + for list in 0..2 { + let rf = b.ref_frame[list]; + if rf <= INTRA_FRAME as i8 { + continue; + } + let Some(&i) = fh.ref_frame_idx.get(rf as usize - LAST_FRAME) else { continue }; + used[i] = true; + let ri = &ref_info[i]; + if ri.upscaled_width != fh.frame_width || ri.frame_height != fh.frame_height { + need[i] = usize::MAX; + continue; + } + let down = (b.mv[list][0].max(0) as usize).div_ceil(8); + need[i] = need[i].max(bottom.saturating_add(down).saturating_add(ROW_WAIT_MARGIN)); + } + } + if warp { + for i in 0..NUM_REF_FRAMES { + if used[i] { + need[i] = usize::MAX; + } + } + } + need +} + +/// Reconstructed luma rows between two runs of the in-loop filter pipeline in +/// [`reconstruct_wavefront`] (finer steps publish rows sooner, coarser ones filter more bands in +/// parallel). +const FILTER_STEP_ROWS: usize = 128; + +/// Reconstruct a frame superblock row by superblock row (row wavefront): before each row, wait +/// only for the reference rows it reads; then reconstruct that row in every tile it crosses +/// (tiles share no prediction context, so the order of the tiles within a row does not matter) +/// and run the in-loop filters on what that allows, publishing the bands that became final. +/// `tiles` holds the whole frame's buffers. Returns the seconds spent waiting for references +/// and filtering (not tile decoding). +fn reconstruct_wavefront(job: &FrameJob, pool: &Pool, fs: &mut FrameState, tiles: &mut FrameTiles, stats: &mut DecodeStats) -> Result { + let fh = &job.fh; + let mut other = 0.0; + let ti = fh.tile_info.clone(); + let Some(state) = tiles.states.pop() else { + return Err(Error::Invalid("no tile to reconstruct")); + }; + // The record of every tile, by tile number. + let mut recs: Vec> = (0..ti.rows * ti.cols).map(|_| None).collect(); + for (num, rec) in std::mem::take(&mut tiles.records) { + *recs.get_mut(num).ok_or(Error::Invalid("tile number out of range"))? = Some(rec); + } + let mut used = [false; NUM_REF_FRAMES]; + if !fh.frame_is_intra { + for i in 0..REFS_PER_FRAME { + used[fh.ref_frame_idx[i]] = true; + } + } + for i in 0..NUM_REF_FRAMES { + if used[i] { + let slot = job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?; + fs.ref_rows[i] = Some(slot.bands.clone()); + } + } + fs.put_tile_state(state); + let mut pipe = crate::av1::decode::postfilter::Pipeline::new(fs, job.draft); + let sb4 = if job.seq.use_128x128_superblock { 32 } else { 16 }; + let mi_rows = fh.mi_rows as usize; + let sb_rows = mi_rows.div_ceil(sb4); + let mut bufs = (crate::av1::decode::tile::Buffers::new(), Cdfs::new(fh.quant.base_q_idx)); + let mut filtered = 0; + let mut tile_row = 0; + for row in 0..sb_rows { + // Tile rows start on superblock rows. + while tile_row + 1 < ti.rows && row * sb4 >= ti.mi_row_starts[tile_row + 1] as usize { + tile_row += 1; + } + let local = (row * sb4).saturating_sub(ti.mi_row_starts[tile_row] as usize) / sb4; + let w = Timer::start(); + if !fh.frame_is_intra { + let mut need = [0usize; NUM_REF_FRAMES]; + for col in 0..ti.cols { + let Some(rec) = &recs[tile_row * ti.cols + col] else { continue }; + let width = (ti.mi_col_starts[col + 1] as usize).min(fh.mi_cols as usize).saturating_sub(ti.mi_col_starts[col] as usize); + let n = rows_needed(fh, &job.ref_info, rec.row_blocks(width.div_ceil(sb4), local.saturating_sub(1), local + 1), (row + 1) * sb4 * 4); + for i in 0..NUM_REF_FRAMES { + need[i] = need[i].max(n[i]); + } + } + for i in 0..NUM_REF_FRAMES { + if used[i] && need[i] > 0 { + let slot = job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?; + slot.progress.wait(need[i].min(job.ref_info[i].frame_height as usize))?; + } + } + } + other += w.secs(); + let mut t = fs.take_tile_state(); + let mut res = Ok(()); + for col in 0..ti.cols { + let Some(rec) = recs[tile_row * ti.cols + col].as_mut() else { continue }; + let (b, cdf) = bufs; + let mut td = TileDecoder::with_buffers(&fs.sh, &mut t, &[], cdf, tile_row, col, b); + td.pass = Pass::Reconstruct; + td.record = std::mem::take(rec); + res = td.reconstruct_sb_rows(1); + *rec = std::mem::take(&mut td.record); + bufs = td.into_buffers(); + if res.is_err() { + break; + } + } + fs.put_tile_state(t); + res?; + let f = Timer::start(); + let recon_rows = ((row + 1) * sb4 * 4).min(mi_rows * 4); + // Filter in steps of a few bands, so the bands of a step run in parallel. + if recon_rows >= filtered + FILTER_STEP_ROWS || recon_rows == mi_rows * 4 { + filtered = recon_rows; + let done = pipe.advance(fs, stats, pool, recon_rows); + publish_final(&job.slot, done, fh.frame_height as usize); + } + other += f.secs(); + #[cfg(test)] + assert!( + !(job.panic_at_row.is_some_and(|r| row >= r) && job.slot.progress.rows() > 0), + "forced panic in the row wavefront after publishing rows" + ); + } + // A reference that failed after publishing the rows used here still fails this frame, as + // it does when frames are decoded one after another. + for i in 0..NUM_REF_FRAMES { + if used[i] { + let slot = job.refs[i].as_ref().ok_or(Error::Invalid("missing reference frame"))?; + slot.wait()?; + } + } + Ok(other) +} + +/// Most bytes a tile's parse record may take per luma sample of the tile. Typical streams need +/// a fraction of this; past it (pathological streams: tiny blocks, large palettes, every +/// coefficient coded) the frame is decoded in one pass instead, so memory stays bounded. +const RECORD_BYTES_PER_SAMPLE: usize = 32; + +/// Most parse record bytes all frames of a decoder hold at once. Past it, the frames that +/// cannot reserve more are decoded in one pass, so the frames in flight together stay bounded +/// too (typical streams need a few bytes per luma sample: under 100 MB for a 2160p frame). +const RECORD_BUDGET_BYTES: usize = 1 << 30; + +/// The tiles of a frame between parsing and reconstruction. +struct FrameTiles { + /// One state per tile (decoded in parallel into private buffers), or one for the whole + /// frame (tiles one after another). + states: Vec, + /// Per tile: (tile number, record of [`Pass::Parse`]). + records: Vec<(usize, TileRecord)>, + /// The final CDFs of tile context_update_tile_id. + saved: Option>, + /// `states` holds the frame's own buffers (taken with [`FrameState::take_tile_state`]). + whole: bool, +} + +impl FrameTiles { + /// Move the tile buffers (mode info, filter parameters and, after reconstruction, the + /// samples) into the frame. + fn finish(self, fs: &mut FrameState) { + if self.whole { + if let Some(t) = self.states.into_iter().next() { + fs.put_tile_state(t); + } + } else { + for t in &self.states { + fs.merge_tile_state(t); + } + } + } +} + +/// Run `pass` (Full or Parse) over the tiles of a frame. +/// `record_limit`: most record bytes per luma sample of a tile (see [`RECORD_BYTES_PER_SAMPLE`]). +/// `budget`: the decoder-wide budget the records are reserved from. +fn parse_tiles( + pool: &Pool, + fs: &mut FrameState, + cdfs: &Cdfs, + tiles: &[(usize, Vec)], + pass: Pass, + record_limit: usize, + budget: &Arc, +) -> Result { let ti = fs.fh.tile_info.clone(); let ctx_tile = ti.context_update_tile_id as usize; - let run = |sh: &FrameShared, t: &mut TileState, num: usize, data: &[u8]| -> Result>> { + let run = |sh: &FrameShared, t: &mut TileState, num: usize, data: &[u8]| -> Result<(Option>, TileRecord)> { t.intra_frame_y_mode_cdf = DEFAULT_INTRA_FRAME_Y_MODE_CDF; let mut td = TileDecoder::new(sh, t, data, Box::new(cdfs.clone()), num / ti.cols, num % ti.cols); + td.pass = pass; + let (rows, cols) = (td.mi_row_end.saturating_sub(td.mi_row_start), td.mi_col_end.saturating_sub(td.mi_col_start)); + td.record.limit = rows.saturating_mul(cols).saturating_mul(16 * record_limit); + td.record.budget = Some(budget.clone()); td.decode_tile()?; - Ok((num == ctx_tile).then_some(td.cdf)) + let rec = std::mem::take(&mut td.record); + Ok(((num == ctx_tile).then_some(td.cdf), rec)) }; // Intra block copy reads the current frame through the tile's own buffer: keep whole-frame // buffers (tiles one after another) for it. @@ -933,42 +1505,75 @@ fn decode_tiles(pool: &Pool, fs: &mut FrameState, cdfs: &Cdfs, tiles: &[(usize, .collect(); let sh = &fs.sh; let results = pool.map_mut(&mut states, |i, t| run(sh, t, tiles[i].0, &tiles[i].1)); - for t in &states { - fs.merge_tile_state(t); - } let mut saved = None; - for r in results { - if let Some(c) = r? { - saved = Some(c); + let mut records = Vec::with_capacity(tiles.len()); + for (r, (num, _)) in results.into_iter().zip(tiles) { + let (c, rec) = r?; + if c.is_some() { + saved = c; } + records.push((*num, rec)); } - return Ok(saved); + return Ok(FrameTiles { states, records, saved, whole: false }); } let mut t = fs.take_tile_state(); let mut saved = None; + let mut records = Vec::with_capacity(tiles.len()); let mut res = Ok(()); for (num, data) in tiles { match run(&fs.sh, &mut t, *num, data) { - Ok(Some(c)) => saved = Some(c), - Ok(None) => {} + Ok((c, rec)) => { + if c.is_some() { + saved = c; + } + records.push((*num, rec)); + } Err(e) => { res = Err(e); break; } } } - fs.put_tile_state(t); - res.map(|_| saved) + if let Err(e) = res { + fs.put_tile_state(t); + return Err(e); + } + Ok(FrameTiles { states: vec![t], records, saved, whole: true }) +} + +/// Reconstruct parsed tiles (in parallel when each has its own state). +fn reconstruct_tiles(pool: &Pool, fs: &FrameShared, tiles: &mut FrameTiles) -> Result<()> { + let ti = fs.fh.tile_info.clone(); + let run = |t: &mut TileState, num: usize, rec: TileRecord| -> Result<()> { + let mut td = TileDecoder::new(fs, t, &[], Cdfs::new(fs.fh.quant.base_q_idx), num / ti.cols, num % ti.cols); + td.pass = Pass::Reconstruct; + td.record = rec; + td.decode_tile() + }; + let records = std::mem::take(&mut tiles.records); + if !tiles.whole { + let mut items: Vec<(&mut TileState, Option<(usize, TileRecord)>)> = tiles.states.iter_mut().zip(records.into_iter().map(Some)).collect(); + let results = pool.map_mut(&mut items, |_, (t, rec)| match rec.take() { + Some((num, rec)) => run(t, num, rec), + None => Ok(()), + }); + return results.into_iter().collect(); + } + let Some(t) = tiles.states.first_mut() else { return Ok(()) }; + for (num, rec) in records { + run(t, num, rec)?; + } + Ok(()) } fn output_picture(seq: &SequenceHeader, rf: &RefFrame, w: usize, h: usize, grain: &FilmGrainParams, apply_film_grain: bool, pts: i64) -> Picture { let ssx = rf.subsampling_x as usize; let ssy = rf.subsampling_y as usize; - let num_planes = rf.buf.num_planes; + let num_planes = rf.num_planes; let mut planes: [Vec; 3] = Default::default(); for p in 0..num_planes { let (pw, ph) = if p == 0 { (w, h) } else { ((w + ssx) >> ssx, (h + ssy) >> ssy) }; - let src = &rf.buf.planes[p]; + let src = rf.plane(p); let mut v = Vec::with_capacity(pw * ph); for y in 0..ph { v.extend_from_slice(&src.row(y)[..pw]); @@ -996,25 +1601,40 @@ fn output_picture(seq: &SequenceHeader, rf: &RefFrame, w: usize, h: usize, grain pic } -/// Motion field motion vector storage process (7.19): (MfRefFrames, MfMvs). +/// What later frames read from this one while parsing: the final CDFs, the segment ids (the +/// previous frame's when the map is not updated) and the stored motion vectors (7.19). The +/// in-loop filters read the decoded segment ids, so the frame's own map is left alone. +fn parse_results(fs: &FrameState, cdfs: Box) -> Parsed { + let fh = &fs.fh; + let segment_ids = if fh.seg.enabled && !fh.seg.update_map { fs.prev_segment_ids.clone() } else { fs.mi.segment_id.clone() }; + let (saved_ref_frames, saved_mvs) = motion_vector_storage(fs); + Parsed { cdfs, segment_ids, mi_cols: fs.mi.cols, mi_rows: fs.mi.rows, saved_ref_frames, saved_mvs } +} + +/// Motion field motion vector storage process (7.19): (MfRefFrames, MfMvs), kept only where +/// the projection process (7.9.2) reads them, the odd row and column of every 8x8 block +/// (index `y8 * (MiCols >> 1) + x8`). fn motion_vector_storage(fs: &FrameState) -> (Vec, Vec<[i32; 2]>) { let mi = &fs.mi; - let n = mi.rows * mi.cols; - let mut refs = vec![-1i8; n]; - let mut mvs = vec![[0i32; 2]; n]; let fh = &fs.fh; - for i in 0..n { - for list in 0..2 { - let r = mi.ref_frame[i][list]; - if r > INTRA_FRAME as i8 { - let ref_idx = fh.ref_frame_idx[r as usize - LAST_FRAME]; - let dist = crate::av1::decode::header::relative_dist(&fs.seq, fs.ref_info[ref_idx].order_hint, fh.order_hint); - if dist < 0 { - let m = mi.mv[i][list]; - let (row, col) = (m.row as i32, m.col as i32); - if row.abs() <= REFMVS_LIMIT as i32 && col.abs() <= REFMVS_LIMIT as i32 { - refs[i] = r; - mvs[i] = [row, col]; + let (mi_cols, w8, h8) = (fh.mi_cols as usize, fh.mi_cols as usize >> 1, fh.mi_rows as usize >> 1); + let mut refs = vec![-1i8; w8 * h8]; + let mut mvs = vec![[0i32; 2]; w8 * h8]; + for y8 in 0..h8 { + for x8 in 0..w8 { + let (i, o) = ((2 * y8 + 1) * mi_cols + 2 * x8 + 1, y8 * w8 + x8); + for list in 0..2 { + let r = mi.ref_frame[i][list]; + if r > INTRA_FRAME as i8 { + let ref_idx = fh.ref_frame_idx[r as usize - LAST_FRAME]; + let dist = crate::av1::decode::header::relative_dist(&fs.seq, fs.ref_info[ref_idx].order_hint, fh.order_hint); + if dist < 0 { + let m = mi.mv[i][list]; + let (row, col) = (m.row as i32, m.col as i32); + if row.abs() <= REFMVS_LIMIT as i32 && col.abs() <= REFMVS_LIMIT as i32 { + refs[o] = r; + mvs[o] = [row, col]; + } } } } @@ -1072,7 +1692,7 @@ fn project_pos(v8: i32, delta: i32, dst_sign: i32, max8: i32, max_off8: i32) -> /// Projection process (7.9.2). fn project(fs: &mut FrameState, src: usize, dst_sign: i32) -> bool { - let FrameShared { seq, fh, refs, ref_info, motion_field, .. } = &mut fs.sh; + let FrameShared { seq, fh, parsed, ref_info, motion_field, .. } = &mut fs.sh; let src_idx = fh.ref_frame_idx[src - LAST_FRAME]; let w8 = fh.mi_cols as i32 >> 1; let h8 = fh.mi_rows as i32 >> 1; @@ -1080,20 +1700,18 @@ fn project(fs: &mut FrameState, src: usize, dst_sign: i32) -> bool { if ri.mi_rows != fh.mi_rows || ri.mi_cols != fh.mi_cols || ri.frame_type == INTRA_ONLY_FRAME as u8 || ri.frame_type == KEY_FRAME as u8 { return false; } - let Some(rf) = &refs[src_idx] else { return false }; + let Some(rf) = &parsed[src_idx] else { return false }; let rd = |a: u32, b: u32| crate::av1::decode::header::relative_dist(seq, a, b); - let mi_cols = fh.mi_cols as usize; for y8 in 0..h8 { for x8 in 0..w8 { - let row = (2 * y8 + 1) as usize; - let col = (2 * x8 + 1) as usize; - let src_ref = rf.saved_ref_frames[row * mi_cols + col]; + let at = (y8 * w8 + x8) as usize; + let src_ref = rf.saved_ref_frames[at]; if src_ref > INTRA_FRAME as i8 { let ref_to_cur = rd(fh.order_hints[src], fh.order_hint); let ref_offset = rd(fh.order_hints[src], ri.saved_order_hints[src_ref as usize]); let pos_valid = ref_to_cur.abs() <= MAX_FRAME_DISTANCE as i32 && ref_offset.abs() <= MAX_FRAME_DISTANCE as i32 && ref_offset > 0; if pos_valid { - let mv = rf.saved_mvs[row * mi_cols + col]; + let mv = rf.saved_mvs[at]; let proj = get_mv_projection(mv, ref_to_cur * dst_sign, ref_offset); let py = project_pos(y8, proj[0], dst_sign, h8, MAX_OFFSET_HEIGHT as i32); let px = project_pos(x8, proj[1], dst_sign, w8, MAX_OFFSET_WIDTH as i32); @@ -1125,13 +1743,18 @@ mod tests { ref_info: Default::default(), tiles: Vec::new(), tile_covered: vec![false; 3], - slot: Slot::new(), + slot: FrameSlot::new(BandFrame::new(0, 0, 1, 0, 0)), picture: None, pts: 0, apply_film_grain: false, draft: false, #[cfg(test)] force_panic: false, + #[cfg(test)] + panic_at_row: None, + #[cfg(test)] + record_limit: None, + record_budget: decoder.record_budget.clone(), })); decoder } @@ -1278,6 +1901,317 @@ mod tests { assert!(frame_size_allowed(1, 1)); } + /// Random short sleeps in row progress publishing and waiting, to shake out scheduling + /// orders a quiet machine never produces (enabled by [`JitterGuard`]). + static JITTER: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0); + + pub(super) fn jitter() { + use std::cell::Cell; + use std::sync::atomic::Ordering; + if JITTER.load(Ordering::Relaxed) == 0 { + return; + } + static SEED: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0x2545_f491_4f6c_dd1d); + thread_local!(static RNG: Cell = Cell::new(SEED.fetch_add(0x9e37_79b9_7f4a_7c15, Ordering::Relaxed) | 1)); + let r = RNG.with(|c| { + let mut x = c.get(); + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + c.set(x); + x + }); + match r % 4 { + 0 => std::thread::yield_now(), + 1 => std::thread::sleep(std::time::Duration::from_micros(r % 300)), + _ => {} + } + } + + struct JitterGuard; + impl JitterGuard { + fn on() -> JitterGuard { + JITTER.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + JitterGuard + } + } + impl Drop for JitterGuard { + fn drop(&mut self) { + JITTER.fetch_sub(1, std::sync::atomic::Ordering::SeqCst); + } + } + + /// Inter test streams made with ffmpeg / SVT-AV1 (None, reported, without them): several + /// superblock rows and hierarchical references; odd size; super-resolution; 2x2 tiles. + const STREAMS: [(&str, &str, &str); 4] = [ + ("wavefront_unit_352x288", "testsrc2=size=352x288:rate=25", "-preset 8 -crf 35"), + ("wavefront_unit_odd", "testsrc2=size=203x117:rate=25,noise=alls=15:allf=t", "-preset 8 -crf 40"), + ("wavefront_unit_superres", "testsrc2=size=416x240:rate=25", "-preset 8 -crf 35 -svtav1-params superres-mode=1:superres-denom=12"), + ("wavefront_unit_tiles", "mandelbrot=size=650x370:rate=25", "-preset 8 -crf 32 -svtav1-params tile-columns=1:tile-rows=1"), + ]; + + fn inter_stream((name, src, args): (&str, &str, &str)) -> Option>> { + let ff = craft_media_testkit::ffmpeg_or_skip("av1 wavefront")?; + if !craft_media_testkit::ffmpeg_has_encoder(&ff, "libsvtav1") { + craft_media_testkit::skip_test("av1 wavefront", "this ffmpeg has no libsvtav1 encoder"); + return None; + } + let out = craft_media_testkit::fixtures_dir("av1").join(format!("{name}.ivf")); + let path = craft_media_testkit::fixtures::generate(&out, |tmp| { + std::process::Command::new(&ff) + .args([ + "-hide_banner", + "-loglevel", + "error", + "-y", + "-f", + "lavfi", + "-i", + src, + "-frames:v", + "16", + "-pix_fmt", + "yuv420p", + "-c:v", + "libsvtav1", + ]) + .args(args.split_whitespace()) + .args(["-f", "ivf"]) + .arg(tmp) + .stdin(std::process::Stdio::null()) + .status() + .is_ok_and(|s| s.success()) + }); + let path = path.unwrap_or_else(|| panic!("ffmpeg has libsvtav1 but could not encode {name}")); + let d = std::fs::read(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display())); + let mut pos = usize::from(u16::from_le_bytes([d[6], d[7]])); + let mut out = Vec::new(); + while let Some(h) = d.get(pos..pos + 12) { + let n = u32::from_le_bytes([h[0], h[1], h[2], h[3]]) as usize; + pos += 12; + out.push(d[pos..pos + n].to_vec()); + pos += n; + } + assert_eq!(out.len(), 16, "{name}: temporal units"); + Some(out) + } + + /// Decode `tus` with `dec`: (pictures, errors). + fn decode_tus(mut dec: Decoder, tus: &[Vec]) -> (Vec, usize) { + let (mut pics, mut errors) = (Vec::new(), 0); + for (i, tu) in tus.iter().enumerate() { + match dec.decode_pts(tu, i as i64) { + Ok(p) => pics.extend(p), + Err(_) => errors += 1, + } + } + match dec.flush_result() { + Ok(p) => pics.extend(p), + Err(_) => errors += 1, + } + (pics, errors) + } + + #[test] + fn jittered_wavefront_gives_the_single_thread_pictures() { + for stream in STREAMS { + let Some(tus) = inter_stream(stream) else { return }; + let name = stream.0; + let (want, errors) = decode_tus(Decoder::with_threads(1), &tus); + assert_eq!(errors, 0, "{name}"); + let _jitter = JitterGuard::on(); + for threads in [2, 3, 5, 8] { + for round in 0..2 { + let tus = tus.clone(); + let (got, errors) = within_a_minute(move || decode_tus(Decoder::with_threads(threads), &tus)); + assert_eq!(errors, 0, "{name}: threads {threads} round {round}"); + assert!(got == want, "{name}: threads {threads} round {round}: pictures differ"); + } + } + } + } + + #[test] + fn frames_over_the_record_limit_decode_in_one_pass() { + for stream in [STREAMS[0], STREAMS[3]] { + let Some(tus) = inter_stream(stream) else { return }; + let name = stream.0; + let (want, _) = decode_tus(Decoder::with_threads(1), &tus); + for (threads, limit) in [(3, 0), (8, 0), (8, 1)] { + let tus = tus.clone(); + let (got, errors) = within_a_minute(move || { + let mut dec = Decoder::with_threads(threads); + dec.record_limit = Some(limit); + decode_tus(dec, &tus) + }); + assert_eq!(errors, 0, "{name}: threads {threads}, limit {limit}"); + assert!(got == want, "{name}: threads {threads}, limit {limit}: pictures differ"); + } + } + } + + #[test] + fn the_parse_records_of_all_frames_stay_within_the_decoder_budget() { + for stream in [STREAMS[0], STREAMS[3]] { + let Some(tus) = inter_stream(stream) else { return }; + let name = stream.0; + let (want, _) = decode_tus(Decoder::with_threads(1), &tus); + // Room for about one frame's records: the other frames in flight decode in one pass. + for (threads, budget) in [(3, 0), (8, 3 << 20), (16, 1 << 20)] { + let tus = tus.clone(); + let b = Arc::new(crate::av1::decode::tile::RecordBudget::new(budget)); + let mut dec = Decoder::with_threads(threads); + dec.record_budget = b.clone(); + let (got, errors) = within_a_minute(move || decode_tus(dec, &tus)); + assert_eq!(errors, 0, "{name}: threads {threads}, budget {budget}"); + assert!(got == want, "{name}: threads {threads}, budget {budget}: pictures differ"); + assert!(b.peak.load(std::sync::atomic::Ordering::Acquire) <= budget, "{name}: threads {threads}: over the budget"); + assert_eq!(b.used(), 0, "{name}: threads {threads}: records not released"); + } + } + } + + #[cfg(all(feature = "threads", not(target_arch = "wasm32")))] + #[test] + fn a_reference_panicking_after_publishing_rows_fails_without_a_hang() { + let Some(tus) = inter_stream(STREAMS[0]) else { return }; + let _jitter = JitterGuard::on(); + // Frame 1 is the first inter frame; later frames predict from it. + for threads in [2, 3, 8] { + for frame in [0, 1, 2] { + let tus = tus.clone(); + let (pics, errors) = within_a_minute(move || { + let mut dec = Decoder::with_threads(threads); + dec.panic_at_row = Some((frame, 1)); + decode_tus(dec, &tus) + }); + assert!(errors > 0, "threads {threads}, frame {frame}: the panic was not reported ({} pictures)", pics.len()); + } + } + } + + #[test] + fn dropping_a_busy_decoder_does_not_hang() { + let Some(tus) = inter_stream(STREAMS[0]) else { return }; + for threads in [2, 3, 8, 16] { + for cut in [1, 3, tus.len() / 2] { + let tus = tus.clone(); + within_a_minute(move || { + let mut dec = Decoder::with_threads(threads); + for (i, tu) in tus.iter().take(cut).enumerate() { + let _ = dec.decode_pts(tu, i as i64); + } + drop(dec); + }); + } + } + } + + #[test] + fn a_flush_mid_stream_keeps_the_pictures() { + let Some(tus) = inter_stream(STREAMS[0]) else { return }; + let (want, _) = decode_tus(Decoder::with_threads(1), &tus); + for threads in [2, 8] { + for cut in [2, 5, tus.len() / 2] { + let tus = tus.clone(); + let got = within_a_minute(move || { + let mut dec = Decoder::with_threads(threads); + let mut pics = Vec::new(); + for (i, tu) in tus.iter().enumerate() { + if i == cut { + pics.extend(dec.flush_result().expect("flush")); + } + pics.extend(dec.decode_pts(tu, i as i64).expect("decode")); + } + pics.extend(dec.flush_result().expect("flush")); + pics + }); + assert!(got == want, "threads {threads}, flush before unit {cut}"); + } + } + } + + #[test] + fn progress_wakes_every_waiter_with_the_rows_or_the_failure() { + let p = Arc::new(Progress::new()); + let waiters: Vec<_> = (1..=8) + .map(|k| { + let p = p.clone(); + std::thread::spawn(move || p.wait(k * 10)) + }) + .collect(); + p.publish(40); + p.publish(20); // never goes back + assert_eq!(p.wait(40), Ok(())); + p.fail(); + let res: Vec<_> = waiters.into_iter().map(|w| w.join().expect("waiter")).collect(); + assert!(res[..4].iter().all(|r| r.is_ok()), "{res:?}"); + assert!(res[4..].iter().all(|r| r.is_err()), "{res:?}"); + assert_eq!(p.wait(40), Ok(()), "rows published before a failure stay readable"); + } + + #[test] + fn a_failed_frame_keeps_its_published_parse_results() { + let slot = FrameSlot::new(BandFrame::new(16, 16, 1, 0, 0)); + let parsed = Parsed { cdfs: Cdfs::new(0), segment_ids: vec![], mi_cols: 4, mi_rows: 4, saved_ref_frames: vec![], saved_mvs: vec![] }; + slot.set_parsed(Ok(Arc::new(parsed))); + slot.finish(Err(Error::Invalid("x")), 16); + assert!(slot.wait_parsed().is_ok()); + assert!(slot.wait().is_err()); + assert!(slot.progress.wait(1).is_err()); + // A frame failing before its parse results: every waiter gets the error. + let slot = FrameSlot::new(BandFrame::new(16, 16, 1, 0, 0)); + slot.finish(Err(Error::Invalid("y")), 16); + assert!(slot.wait_parsed().is_err()); + } + + fn motion(mi_row: usize, bh4: usize, ref_frame: [i8; 2], mv: [[i32; 2]; 2]) -> crate::av1::decode::tile::BlockMotion { + crate::av1::decode::tile::BlockMotion { + mi_row, + bh4, + inter: true, + ref_frame, + mv, + motion_mode: 0, + y_mode: crate::av1::decode::spec_tables::NEARESTMV, + } + } + + #[test] + fn rows_needed_follow_the_motion_vectors() { + let mut fh = FrameHeader { frame_width: 64, upscaled_width: 64, frame_height: 256, ..Default::default() }; + fh.ref_frame_idx = [0, 1, 2, 3, 4, 5, 6]; + let mut ri: [RefInfo; NUM_REF_FRAMES] = Default::default(); + for r in ri.iter_mut() { + (r.upscaled_width, r.frame_height) = (64, 256); + } + let none = [[0; 2]; 2]; + // 41/8 rows down rounds up to 6; upward motion needs only the block's own rows. + let need = rows_needed(&fh, &ri, [motion(0, 16, [1, -1], [[41, 0], [0, 0]]), motion(0, 16, [2, 3], [[-80, 0], [7, 0]])].into_iter(), 64); + assert_eq!(need[0], 64 + 6 + ROW_WAIT_MARGIN); + assert_eq!(need[1], 64 + ROW_WAIT_MARGIN); + assert_eq!(need[2], 64 + 1 + ROW_WAIT_MARGIN); + assert_eq!(need[3], 0); + // Intra blocks and intra block copy read no reference. + let intra = crate::av1::decode::tile::BlockMotion { inter: false, ..motion(0, 16, [1, -1], none) }; + assert_eq!(rows_needed(&fh, &ri, [intra].into_iter(), 64), [0; NUM_REF_FRAMES]); + // Blocks reaching below the superblock row count from their own bottom. + assert_eq!(rows_needed(&fh, &ri, [motion(12, 8, [1, -1], none)].into_iter(), 64)[0], 80 + ROW_WAIT_MARGIN); + // Local warp: the whole of every reference the rows use. + let warp = + crate::av1::decode::tile::BlockMotion { motion_mode: crate::av1::decode::spec_tables::LOCALWARP as u8, ..motion(0, 16, [1, -1], none) }; + let need = rows_needed(&fh, &ri, [warp, motion(0, 16, [2, -1], none)].into_iter(), 64); + assert_eq!((need[0], need[1], need[2]), (usize::MAX, usize::MAX, 0)); + // Global motion beyond translation for GLOBALMV blocks. + fh.gm_type[3] = (TRANSLATION + 1) as u8; + let global = crate::av1::decode::tile::BlockMotion { y_mode: GLOBALMV, ..motion(0, 16, [1, -1], none) }; + assert_eq!(rows_needed(&fh, &ri, [global].into_iter(), 64)[0], usize::MAX); + fh.gm_type[3] = 0; + // A scaled reference. + ri[0].frame_height = 128; + assert_eq!(rows_needed(&fh, &ri, [motion(0, 16, [1, -1], none)].into_iter(), 64)[0], usize::MAX); + } + #[test] fn frames_beyond_the_limits_are_refused() { assert!(!frame_size_allowed(16384, 2177)); // one row over MaxPicSize diff --git a/crates/video/src/av1/decode/frame.rs b/crates/video/src/av1/decode/frame.rs index d0432e2a8..e28ca89e9 100644 --- a/crates/video/src/av1/decode/frame.rs +++ b/crates/video/src/av1/decode/frame.rs @@ -197,6 +197,50 @@ impl FrameBuf { } } + /// Copy luma rows [y0, y1) (chroma rows scaled down; clipped to the stored rows) of `src`, a + /// frame of the same geometry. + pub fn copy_rows_from(&mut self, src: &FrameBuf, y0: usize, y1: usize) { + for p in 0..self.num_planes { + let sy = if p == 0 { 0 } else { self.subsampling_y }; + let (d, s) = (&mut self.planes[p], &src.planes[p]); + if d.stride != s.stride { + continue; + } + let a = (y0 >> sy).min(d.rows).min(s.rows) * d.stride; + let b = (y1 >> sy).min(d.rows).min(s.rows) * d.stride; + if let (Some(dst), Some(src)) = (d.data.get_mut(a..b), s.data.get(a..b)) { + dst.copy_from_slice(src); + } + } + } + + /// Copies of luma rows [y0, y1) (chroma rows scaled down; clipped to the stored rows), one + /// plane region each. + pub fn rows_copy(&self, y0: usize, y1: usize) -> [Plane; 3] { + std::array::from_fn(|p| { + if p >= self.num_planes { + return Plane::default(); + } + let sy = if p == 0 { 0 } else { self.subsampling_y }; + let s = &self.planes[p]; + let (a, b) = ((y0 >> sy).min(s.rows), (y1 >> sy).min(s.rows)); + let mut out = Plane::region(0, a, s.stride, b - a); + if let Some(src) = s.data.get(a * s.stride..b * s.stride) { + out.data.copy_from_slice(src); + } + out + }) + } + + /// A frame of this geometry (samples not copied: zero). + pub fn same_geometry(&self) -> FrameBuf { + let planes = std::array::from_fn(|p| { + let pl = &self.planes[p]; + Plane { data: zeroed(pl.data.len()), stride: pl.stride, rows: pl.rows, ox: pl.ox, oy: pl.oy } + }); + FrameBuf { planes, ..*self } + } + /// [`Plane::row_bands`] of all three planes for ranges of luma rows (chroma rows scaled /// down): element `i` holds the bands of range `i`. pub fn row_bands(&mut self, luma: &[(usize, usize)]) -> Vec<[RowBand<'_>; 3]> { @@ -208,6 +252,128 @@ impl FrameBuf { } } +/// Luma rows per published band of a [`BandFrame`] (log2). +pub const BAND_LOG2: u32 = 6; + +/// One plane of a frame's final samples, published band by band while the rest of the frame +/// is still being decoded (see [`BandFrame`]). A band is written once and then only read. +pub struct BandPlane { + bands: Vec>, + stride: usize, + rows: usize, + log2: u32, + /// Returned for rows of a band that is not published: zeros instead of a panic. Readers wait + /// for the row progress first and references of another chroma format are refused, so + /// this only happens through a scheduling bug. + missing: Box<[u16]>, +} + +impl BandPlane { + fn new(stride: usize, rows: usize, log2: u32) -> BandPlane { + let n = rows.div_ceil(1 << log2); + BandPlane { bands: (0..n).map(|_| std::sync::OnceLock::new()).collect(), stride, rows, log2, missing: vec![0; stride].into_boxed_slice() } + } + + /// Row `y` (`stride` samples) of a published band. + #[inline(always)] + pub fn row(&self, y: usize) -> &[u16] { + let o = (y & ((1 << self.log2) - 1)) * self.stride; + match self.bands.get(y >> self.log2).and_then(|b| b.get()).and_then(|b| b.data.get(o..o + self.stride)) { + Some(r) => r, + None => { + debug_assert!(false, "row {y} read before its band was published"); + &self.missing + } + } + } + + /// Publish band `band` copied from the rows of the whole plane `src` (same geometry); a + /// band is published once. + fn publish(&self, band: usize, src: &Plane) { + let y0 = band << self.log2; + let y1 = ((band + 1) << self.log2).min(self.rows); + let mut p = Plane::region(0, y0, self.stride, y1.saturating_sub(y0)); + let w = self.stride.min(src.stride); + for (y, out) in (y0..y1).zip(p.data.chunks_exact_mut(self.stride.max(1))) { + if let Some(r) = src.data.get(y * src.stride..y * src.stride + w) { + out[..w].copy_from_slice(r); + } + } + self.publish_owned(band, p); + } + + /// Publish band `band` as `p`, whose rows start at the band's first row (stride `stride`; + /// rows past the band are ignored). + fn publish_owned(&self, band: usize, p: Plane) { + if let Some(slot) = self.bands.get(band) + && p.stride == self.stride + { + let _ = slot.set(p); + } + } +} + +/// A frame's final samples (every in-loop filter applied) in bands of 64 luma rows, so later +/// frames can predict from the top of a reference while its bottom is still being decoded. +/// Each band is published once, before the frame's row progress says it is final. +pub struct BandFrame { + pub planes: [BandPlane; 3], + pub num_planes: usize, + pub subsampling_x: usize, + pub subsampling_y: usize, +} + +impl BandFrame { + /// Bands for the visible rows of a `width` x `height` frame stored like [`FrameBuf::new`]. + pub fn new(width: usize, height: usize, num_planes: usize, subsampling_x: usize, subsampling_y: usize) -> BandFrame { + let aw = width.div_ceil(128) * 128 + 160; + let planes = std::array::from_fn(|p| { + if p >= num_planes { + return BandPlane::new(0, 0, BAND_LOG2); + } + let (sx, sy) = if p == 0 { (0, 0) } else { (subsampling_x, subsampling_y) }; + BandPlane::new(aw >> sx, (height + sy) >> sy, BAND_LOG2 - sy as u32) + }); + BandFrame { planes, num_planes, subsampling_x, subsampling_y } + } + + /// Number of bands (of 64 luma rows). + pub fn bands(&self) -> usize { + self.planes[0].bands.len() + } + + /// Publish luma band `band` (and the chroma rows it covers) copied from `src`. + pub fn publish(&self, band: usize, src: &FrameBuf) { + for p in 0..self.num_planes { + self.planes[p].publish(band, &src.planes[p]); + } + } + + /// Publish luma band `band` from per-plane buffers starting at the band's first row. + pub fn publish_owned(&self, band: usize, planes: [Plane; 3]) { + for (p, pl) in planes.into_iter().enumerate().take(self.num_planes) { + self.planes[p].publish_owned(band, pl); + } + } +} + +/// A plane to predict from: a whole stored plane or the published bands of a reference. +#[derive(Clone, Copy)] +pub enum PlaneRef<'a> { + Whole(&'a Plane), + Bands(&'a BandPlane), +} + +impl<'a> PlaneRef<'a> { + #[inline(always)] + pub fn row(&self, y: usize) -> &'a [u16] { + match *self { + PlaneRef::Whole(p) => p.row(y), + PlaneRef::Bands(b) => b.row(y), + } + } +} + /// A motion vector (row, col) in 1/8 sample units. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] pub struct Mv { diff --git a/crates/video/src/av1/decode/inter.rs b/crates/video/src/av1/decode/inter.rs index 8b40717a3..8d80e96b0 100644 --- a/crates/video/src/av1/decode/inter.rs +++ b/crates/video/src/av1/decode/inter.rs @@ -3,7 +3,7 @@ use std::sync::OnceLock; -use crate::av1::decode::frame::Plane; +use crate::av1::decode::frame::{Plane, PlaneRef}; use crate::av1::decode::mvpred::round2_signed64; use crate::av1::decode::spec_tables::{ BLOCK_8X8, BLOCK_SIZES, COMPOUND_AVERAGE, COMPOUND_DIFFWTD, COMPOUND_DISTANCE, COMPOUND_INTRA, COMPOUND_WEDGE, DIV_LUT, DIV_LUT_BITS, @@ -227,12 +227,9 @@ impl TileDecoder<'_, '_> { (start_x as i32, start_y as i32, step_x as i32, step_y as i32) } - fn ref_plane(&self, ref_idx: i32, plane: usize) -> &Plane { + fn ref_plane(&self, ref_idx: i32, plane: usize) -> PlaneRef<'_> { // A missing reference (rejected earlier for valid streams) predicts from the current frame. - match usize::try_from(ref_idx).ok().and_then(|i| self.fs.refs.get(i)).and_then(|r| r.as_ref()) { - Some(r) => &r.buf.planes[plane], - None => &self.t.cur.planes[plane], - } + self.fs.ref_samples(ref_idx, plane).unwrap_or(PlaneRef::Whole(&self.t.cur.planes[plane])) } /// Block inter prediction process (7.11.3.4) into `pred` (stride PRED_STRIDE); `tmp` holds @@ -512,12 +509,12 @@ impl TileDecoder<'_, '_> { return false; } let fs = self.fs; - let Some(r) = usize::try_from(ref_idx).ok().and_then(|i| fs.refs.get(i)).and_then(|r| r.as_ref()) else { + let Some(refp) = fs.ref_samples(ref_idx, plane) else { return false; }; let dims = self.ref_plane_dims(ref_idx, plane); let max = ((1u32 << fs.bit_depth) - 1) as u16; - copy_fullpel(&r.buf.planes[plane], dims, McBlock { x: sx, y: sy, w, h }, &mut self.t.cur.planes[plane], (x, y), max); + copy_fullpel(refp, dims, McBlock { x: sx, y: sy, w, h }, &mut self.t.cur.planes[plane], (x, y), max); true } @@ -763,7 +760,7 @@ impl TileDecoder<'_, '_> { /// Unscaled single-reference prediction at a whole-sample position: both filter phases are the /// identity and Round2(128 * Round2(128 * v, InterRound0), InterRound1) == v for every bit /// depth, so the prediction is the (clamped) reference sample. -fn copy_fullpel(refp: &Plane, (last_x, last_y): (i32, i32), src_blk: McBlock, dst: &mut Plane, (dx, dy): (usize, usize), max: u16) { +fn copy_fullpel(refp: PlaneRef, (last_x, last_y): (i32, i32), src_blk: McBlock, dst: &mut Plane, (dx, dy): (usize, usize), max: u16) { let McBlock { x, y, w, h } = src_blk; let x0 = x >> 10; let y0 = y >> 10; @@ -831,7 +828,7 @@ fn vpass(rows: &[i32], vf: &[i16; 8], out: &mut [i32], half: i32 /// Block inter prediction without reference scaling: every column / row uses the same filter /// phase, so the filters run over whole rows (bit-identical to the per-sample process). fn mc_unscaled( - refp: &Plane, + refp: PlaneRef, (last_x, last_y): (i32, i32), blk: McBlock, (hf, vf): (&[i16; 8], &[i16; 8]), @@ -982,9 +979,17 @@ mod tests { [(0, 0), (-5, -3), (7, 9), (last_x - w as i32 / 2, last_y - h as i32 / 2), (last_x + 3, last_y + 2), (-(w as i32) - 4, 3)] { let (x, y) = ((px << 10) | 32, (py << 10) | 32); - mc_unscaled(&refp, (last_x, last_y), McBlock { x, y, w, h }, (&IDENTITY_TAPS, &IDENTITY_TAPS), rnd, &mut pred, &mut tmp); + mc_unscaled( + PlaneRef::Whole(&refp), + (last_x, last_y), + McBlock { x, y, w, h }, + (&IDENTITY_TAPS, &IDENTITY_TAPS), + rnd, + &mut pred, + &mut tmp, + ); let mut dst = Plane::new(w + 3, h); - copy_fullpel(&refp, (last_x, last_y), McBlock { x, y, w, h }, &mut dst, (3, 0), max); + copy_fullpel(PlaneRef::Whole(&refp), (last_x, last_y), McBlock { x, y, w, h }, &mut dst, (3, 0), max); for i in 0..h { for j in 0..w { let want = spec_phase0(&refp, (last_x, last_y), (px, py), (j, i), (w * 3 + h) % SUBPEL_FILTERS.len(), rnd) diff --git a/crates/video/src/av1/decode/postfilter.rs b/crates/video/src/av1/decode/postfilter.rs index 6304fdfb6..aa9c2e3ea 100644 --- a/crates/video/src/av1/decode/postfilter.rs +++ b/crates/video/src/av1/decode/postfilter.rs @@ -1,7 +1,7 @@ //! In-loop post filters run by decode_frame_wrapup: loop filter (7.14), CDEF (7.15), //! super-resolution upscaling (7.16) and loop restoration (7.17). -use crate::av1::decode::frame::RowBand; +use crate::av1::decode::frame::{FrameBuf, Plane, RowBand}; use crate::av1::decode::spec_tables::{ GLOBAL_GLOBALMV, GLOBALMV, INTRA_FRAME, MAX_LOOP_FILTER, NEARESTMV, NUM_4X4_BLOCKS_HIGH, NUM_4X4_BLOCKS_WIDE, SEG_LVL_ALT_LF_Y_V, TX_HEIGHT, TX_WIDTH, @@ -48,6 +48,121 @@ pub(crate) fn apply(fs: &mut FrameState, stats: &mut DecodeStats, pool: &crate:: stats.add(Stage::Restoration, t.lap()); } +/// The in-loop filters run band by band behind reconstruction (row wavefront): each stage of a +/// band starts once the stage before has finished the band below it, which bounds what the +/// stage reads beyond the band (the loop filter changes up to 7 rows above a band and intra +/// prediction of the next superblock row reads the unfiltered row above it; CDEF reads 2 rows +/// and loop restoration 3 rows beyond a band). Bands are 64 luma rows. The result is the same +/// as running each filter over the whole frame. Super-resolution frames use [`apply`]. +/// +/// The last active stage writes each band into its own buffers, which are handed out as the +/// band's final samples without a copy. +pub(crate) struct Pipeline { + bands: Vec<(usize, usize)>, + /// Luma rows of the coded frame (mi_rows * 4). + rows: usize, + lf_on: bool, + cdef_on: bool, + lr_on: bool, + /// Bands finished by each stage. + lf: usize, + cdef: usize, + lr: usize, + pending: [Vec; 3], + /// CdefFrame when loop restoration reads it. + cdef_out: Option, +} + +/// Final bands from [`Pipeline::advance`]: (band, its samples starting at the band's first row). +pub(crate) type FinalBands = Vec<(usize, [Plane; 3])>; + +impl Pipeline { + pub fn new(fs: &FrameState, draft: bool) -> Pipeline { + let rows = fs.fh.mi_rows as usize * 4; + let n = rows.div_ceil(BAND_ROWS).max(1); + let bands = (0..n).map(|b| (b * BAND_ROWS, if b + 1 == n { usize::MAX } else { (b + 1) * BAND_ROWS })).collect(); + let lvl = fs.fh.lf.level; + let cdef_on = !draft && crate::av1::decode::cdef::active(fs); + let lr_on = fs.fh.lr.uses_lr && !draft; + let cdef_out = (cdef_on && lr_on).then(|| fs.cur.same_geometry()); + Pipeline { + bands, + rows, + lf_on: (lvl[0] != 0 || lvl[1] != 0) && !draft, + cdef_on, + lr_on, + lf: 0, + cdef: 0, + lr: 0, + pending: Default::default(), + cdef_out, + } + } + + /// Filter what luma rows [0, `recon_rows`) of reconstructed samples allow (everything once + /// they cover the frame); returns the bands whose samples became final. + pub fn advance(&mut self, fs: &mut FrameState, stats: &mut DecodeStats, pool: &crate::av1::decode::par::Pool, recon_rows: usize) -> FinalBands { + let n = self.bands.len(); + let all = recon_rows >= self.rows; + let mut out = FinalBands::new(); + let mut t = Timer::start(); + // The loop filter of a band waits for the band below it to be reconstructed. + let lf_to = if all { n } else { (recon_rows / BAND_ROWS).saturating_sub(1) }; + if lf_to > self.lf { + if self.lf_on { + loop_filter_bands(fs, pool, &self.bands, self.lf..lf_to, &mut self.pending); + } + self.lf = lf_to; + } + stats.add(Stage::LoopFilter, t.lap()); + let cdef_to = if all { n } else { self.lf.saturating_sub(1) }; + if cdef_to > self.cdef { + let r = &self.bands[self.cdef..cdef_to]; + if self.cdef_on { + if let Some(cdef) = &mut self.cdef_out { + cdef.copy_rows_from(&fs.cur, r[0].0, r[r.len() - 1].1); + crate::av1::decode::cdef::filter_bands(fs, pool, cdef.row_bands(r), r); + } else { + let mut own: Vec<[Plane; 3]> = r.iter().map(|&(a, b)| fs.cur.rows_copy(a, b)).collect(); + crate::av1::decode::cdef::filter_bands(fs, pool, own_bands(&mut own), r); + out.extend((self.cdef..cdef_to).zip(own)); + } + } else if !self.lr_on { + // The loop filter is the last stage: the band is final once the band below it + // is filtered. + out.extend((self.cdef..cdef_to).zip(r.iter().map(|&(a, b)| fs.cur.rows_copy(a, b)))); + } + self.cdef = cdef_to; + } + stats.add(Stage::Cdef, t.lap()); + let lr_to = if all { n } else { self.cdef.saturating_sub(1) }; + if self.lr_on && lr_to > self.lr { + let r = &self.bands[self.lr..lr_to]; + let cdef = self.cdef_out.as_ref().unwrap_or(&fs.cur); + let mut own: Vec<[Plane; 3]> = r.iter().map(|&(a, b)| cdef.rows_copy(a, b)).collect(); + crate::av1::decode::restoration::restore_bands(fs, &fs.cur, cdef, own_bands(&mut own), pool, r); + out.extend((self.lr..lr_to).zip(own)); + self.lr = lr_to; + } + stats.add(Stage::Restoration, t.lap()); + out + } +} + +/// Row bands over per-band buffers made by [`FrameBuf::rows_copy`]. +fn own_bands(own: &mut [[Plane; 3]]) -> Vec<[RowBand<'_>; 3]> { + fn band(p: &mut Plane) -> RowBand<'_> { + let (stride, y0) = (p.stride.max(1), p.oy); + RowBand { data: p.data.as_mut_slice(), stride, y0 } + } + own.iter_mut() + .map(|planes| { + let [a, b, c] = planes; + [band(a), band(b), band(c)] + }) + .collect() +} + // --------------------------------------------------------------------------------------------- // Loop filter (7.14) @@ -69,23 +184,40 @@ const LF_MARGIN: usize = 8; /// written back; the band above never touches them. fn loop_filter(fs: &mut FrameState, pool: &crate::av1::decode::par::Pool) { let luma = bands(pool, fs.fh.mi_rows as usize * 4); + loop_filter_bands(fs, pool, &luma, 0..luma.len(), &mut Default::default()); +} + +/// The loop filter on bands `range` of `all` (the frame's bands). The bands above the range +/// are filtered already: `pending` holds the unfiltered rows above the first band of the range +/// (empty for band 0), saved before the band above was filtered, and is set to those of the +/// band after the range. +fn loop_filter_bands( + fs: &mut FrameState, + pool: &crate::av1::decode::par::Pool, + all: &[(usize, usize)], + range: std::ops::Range, + pending: &mut [Vec; 3], +) { + let Some(luma) = all.get(range.clone()) else { return }; let planes: Vec = (0..fs.num_planes).filter(|&p| p == 0 || fs.fh.lf.level[1 + p] != 0).collect(); let mut cur = std::mem::take(&mut fs.cur); let f: &FrameState = fs; - // Unfiltered copies of the rows above each band but the first. - let margins: Vec<[Vec; 3]> = luma - .iter() - .map(|&(start, _)| { - std::array::from_fn(|p| { - let sub_y = if p == 0 { 0 } else { f.ssy }; - let pl = &cur.planes[p]; - let (y0, y1) = ((start.saturating_sub(LF_MARGIN)) >> sub_y, start >> sub_y); - let rows = pl.data.get(y0 * pl.stride..y1 * pl.stride); - if start == 0 || !planes.contains(&p) { Vec::new() } else { rows.map(<[u16]>::to_vec).unwrap_or_default() } - }) + // Unfiltered copies of the rows above a band (none above the first). + let margin = |cur: &crate::av1::decode::frame::FrameBuf, start: usize| -> [Vec; 3] { + std::array::from_fn(|p| { + let sub_y = if p == 0 { 0 } else { f.ssy }; + let pl = &cur.planes[p]; + let (y0, y1) = ((start.saturating_sub(LF_MARGIN)) >> sub_y, start >> sub_y); + let rows = pl.data.get(y0 * pl.stride..y1 * pl.stride); + if start == 0 || !planes.contains(&p) { Vec::new() } else { rows.map(<[u16]>::to_vec).unwrap_or_default() } }) - .collect(); - let mut bands: Vec<([RowBand; 3], [Vec; 3])> = cur.row_bands(&luma).into_iter().zip(margins).collect(); + }; + let margins: Vec<[Vec; 3]> = + luma.iter().enumerate().map(|(i, &(start, _))| if i == 0 { std::mem::take(pending) } else { margin(&cur, start) }).collect(); + if let Some(&(next, _)) = all.get(range.end) { + *pending = margin(&cur, next); + } + let mut bands: Vec<([RowBand; 3], [Vec; 3])> = cur.row_bands(luma).into_iter().zip(margins).collect(); let changed = pool.map_mut(&mut bands, |b, (band, margin)| { let mut changed: [Vec<(usize, u16)>; 3] = Default::default(); for &p in &planes { diff --git a/crates/video/src/av1/decode/restoration.rs b/crates/video/src/av1/decode/restoration.rs index efc5a751f..d252f7b06 100644 --- a/crates/video/src/av1/decode/restoration.rs +++ b/crates/video/src/av1/decode/restoration.rs @@ -70,10 +70,16 @@ struct LrPlane<'a> { /// Bands of 64 luma rows are restored in parallel: every unit reads only the two input frames /// and writes only its own samples. pub(crate) fn loop_restoration(fs: &FrameState, cur: &FrameBuf, cdef: &FrameBuf, pool: &Pool) -> FrameBuf { - let fh = &fs.fh; let mut lr = cdef.clone(); - let ranges = bands(pool, fh.frame_height as usize); - let mut planes = lr.row_bands(&ranges); + let ranges = bands(pool, fs.fh.frame_height as usize); + restore_bands(fs, cur, cdef, lr.row_bands(&ranges), pool, &ranges); + lr +} + +/// Restore the bands `planes` covering luma rows `ranges`, which hold UpscaledCdefFrame; reads +/// both inputs up to 3 rows beyond each band. +pub(crate) fn restore_bands(fs: &FrameState, cur: &FrameBuf, cdef: &FrameBuf, mut planes: Vec<[RowBand; 3]>, pool: &Pool, ranges: &[(usize, usize)]) { + let fh = &fs.fh; pool.map_mut(&mut planes, |b, band| { let (start, end) = ranges[b]; let mut scratch = Scratch::default(); @@ -100,8 +106,6 @@ pub(crate) fn loop_restoration(fs: &FrameState, cur: &FrameBuf, cdef: &FrameBuf, p.restore(out, start >> sub_y, end >> sub_y, &mut scratch); } }); - drop(planes); - lr } /// Row buffers reused across stripes. diff --git a/crates/video/src/av1/decode/state.rs b/crates/video/src/av1/decode/state.rs index df2e2d682..e0e5a8522 100644 --- a/crates/video/src/av1/decode/state.rs +++ b/crates/video/src/av1/decode/state.rs @@ -6,8 +6,8 @@ //! with several, each tile decodes into private buffers covering its area (tiles never read //! outside themselves), which are then copied into the frame. -use crate::av1::decode::decoder::RefFrame; -use crate::av1::decode::frame::{FrameBuf, MiInfo}; +use crate::av1::decode::decoder::{Parsed, RefFrame}; +use crate::av1::decode::frame::{BandFrame, FrameBuf, MiInfo, PlaneRef}; use crate::av1::decode::header::{FrameHeader, RefInfo, SequenceHeader}; use crate::av1::decode::spec_tables::{DEFAULT_INTRA_FRAME_Y_MODE_CDF, NUM_REF_FRAMES, RESTORE_NONE, SUBSAMPLED_SIZE}; use std::ops::{Deref, DerefMut}; @@ -26,6 +26,11 @@ pub(crate) struct FrameShared { pub cdef_cols: usize, /// Reference slots (FrameStore and saved state) used by this frame. pub refs: [Option>; NUM_REF_FRAMES], + /// Parse results (CDFs, segment ids, saved motion vectors) of the same slots. + pub parsed: [Option>; NUM_REF_FRAMES], + /// The published bands of references that are still being decoded (row wavefront): read + /// only below the row progress that was waited for. + pub ref_rows: [Option>; NUM_REF_FRAMES], pub ref_info: [RefInfo; NUM_REF_FRAMES], /// MotionFieldMvs[ ref ][ y8 * w8 + x8 ] (7.9); empty when unused. pub motion_field: [Vec<[i32; 2]>; 8], @@ -34,6 +39,16 @@ pub(crate) struct FrameShared { } impl FrameShared { + /// The samples of reference slot `ref_idx` to predict from (None for a missing reference). + #[inline] + pub fn ref_samples(&self, ref_idx: i32, plane: usize) -> Option> { + let i = usize::try_from(ref_idx).ok()?; + if let Some(b) = self.ref_rows.get(i)?.as_ref() { + return b.planes.get(plane).map(PlaneRef::Bands); + } + self.refs.get(i)?.as_ref().map(|r| r.plane(plane)) + } + pub fn plane_residual_size(&self, subsize: usize, plane: usize) -> usize { let sx = if plane > 0 { self.ssx } else { 0 }; let sy = if plane > 0 { self.ssy } else { 0 }; @@ -210,6 +225,8 @@ impl FrameState { lr_unit_cols, cdef_cols, refs: Default::default(), + parsed: Default::default(), + ref_rows: Default::default(), ref_info: Default::default(), motion_field: Default::default(), prev_segment_ids: vec![0; mi_cols * mi_rows], @@ -276,6 +293,14 @@ impl FrameState { pub fn merge_tile_state(&mut self, t: &TileState) { for p in 0..self.num_planes { t.cur.planes[p].copy_into(&mut self.cur.planes[p]); + } + self.merge_tile_modes(t); + } + + /// Copy a tile's private buffers except the samples (after parsing, before reconstruction) + /// into the frame. + pub fn merge_tile_modes(&mut self, t: &TileState) { + for p in 0..self.num_planes { t.lf_tx_size[p].copy_into(&mut self.lf_tx_size[p]); for &u in &t.lr_written[p] { self.lr.lr_type[p][u] = t.lr.lr_type[p][u]; diff --git a/crates/video/src/av1/decode/tile.rs b/crates/video/src/av1/decode/tile.rs index 16d59ed3a..2572f9d21 100644 --- a/crates/video/src/av1/decode/tile.rs +++ b/crates/video/src/av1/decode/tile.rs @@ -94,6 +94,191 @@ pub(crate) struct Block { pub local_warp_params: [i32; 6], } +/// What a tile decoder does with the blocks it visits. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub(crate) enum Pass { + /// Read the symbols and reconstruct each block right away (single-threaded decoding). + Full, + /// Read the symbols only, recording what reconstruction needs in a [`TileRecord`]. + Parse, + /// Reconstruct from a [`TileRecord`], reading no symbols. + Reconstruct, +} + +/// The per-block values reconstruction needs beyond the mode info (which is final after +/// parsing): the block variables as parsed, its quantizer index and the warp samples / palette +/// color maps when used. +#[derive(Clone)] +pub(crate) struct BlockRecord { + b: Block, + current_q_index: i32, + warp_samples: Option>, + color_maps: Option, Vec)>>, +} + +/// A parsed tile: its blocks in decoding order, how many of them each superblock holds and the +/// coefficients of every coded transform block as a stream of +/// `eob, tx_type, count, (position, value) * count` (only non-zero values). +#[derive(Default)] +pub(crate) struct TileRecord { + blocks: Vec, + sb_blocks: Vec, + coeffs: Vec, + /// Read positions while reconstructing. + next_block: usize, + next_coeff: usize, + next_sb: usize, + next_sb_row: usize, + /// Bytes recorded and the most allowed. + pub bytes: usize, + pub limit: usize, + /// The decoder-wide budget the recorded bytes are reserved from, and how much is reserved. + pub budget: Option>, + reserved: usize, +} + +impl Drop for TileRecord { + fn drop(&mut self) { + if let Some(b) = &self.budget { + b.release(self.reserved); + } + } +} + +/// The parse record bytes all frames of a decoder may hold at once (frames in flight decode in +/// one pass once it is used up). +pub(crate) struct RecordBudget { + used: std::sync::atomic::AtomicUsize, + max: usize, + /// Most bytes ever reserved at once (tests). + #[cfg(test)] + pub peak: std::sync::atomic::AtomicUsize, +} + +/// Bytes reserved from a [`RecordBudget`] at a time. +const RESERVE_STEP: usize = 1 << 20; + +impl RecordBudget { + pub fn new(max: usize) -> RecordBudget { + RecordBudget { + used: Default::default(), + max, + #[cfg(test)] + peak: Default::default(), + } + } + + /// Reserve `n` bytes; false (nothing reserved) if that would go over the budget. + fn reserve(&self, n: usize) -> bool { + use std::sync::atomic::Ordering; + let ok = self.used.try_update(Ordering::AcqRel, Ordering::Acquire, |u| u.checked_add(n).filter(|&v| v <= self.max)).is_ok(); + #[cfg(test)] + if ok { + self.peak.fetch_max(self.used.load(Ordering::Acquire), Ordering::AcqRel); + } + ok + } + + fn release(&self, n: usize) { + self.used.fetch_sub(n, std::sync::atomic::Ordering::AcqRel); + } + + /// Bytes reserved now (tests). + #[cfg(test)] + pub fn used(&self) -> usize { + self.used.load(std::sync::atomic::Ordering::Acquire) + } +} + +/// The motion of a recorded block (what a reference row wait depends on). +pub(crate) struct BlockMotion { + pub mi_row: usize, + pub bh4: usize, + /// Inter prediction from reference frames (not intra block copy). + pub inter: bool, + pub ref_frame: [i8; 2], + /// Mv[ list ] (row, col) in 1/8 samples. + pub mv: [[i32; 2]; 2], + pub motion_mode: u8, + pub y_mode: usize, +} + +impl TileRecord { + /// Whether recording stopped at [`TileRecord::limit`] (the record is unusable). + pub fn over_limit(&self) -> bool { + self.bytes > self.limit + } + + /// Account for `n` more recorded bytes; false once over the limit (nothing more is kept). + fn grow(&mut self, n: usize) -> bool { + self.bytes = self.bytes.saturating_add(n); + if self.bytes > self.limit { + return false; + } + if self.bytes > self.reserved + && let Some(b) = &self.budget + { + let step = (self.bytes - self.reserved).max(RESERVE_STEP); + if !b.reserve(step) { + // The decoder-wide budget is used up: this frame is decoded in one pass. + self.limit = 0; + return false; + } + self.reserved += step; + } + true + } + /// The recorded blocks of superblock rows [first, end), for a tile `sbs_per_row` superblocks wide. + pub fn row_blocks(&self, sbs_per_row: usize, first: usize, end: usize) -> impl Iterator + '_ { + let start: usize = self.sb_blocks.iter().take(first * sbs_per_row).map(|&n| n as usize).sum(); + let count: usize = self.sb_blocks.iter().skip(first * sbs_per_row).take((end - first) * sbs_per_row).map(|&n| n as usize).sum(); + self.blocks.iter().skip(start).take(count).map(|r| BlockMotion { + mi_row: r.b.mi_row, + bh4: r.b.bh4, + inter: r.b.is_inter && !r.b.use_intrabc, + ref_frame: r.b.ref_frame, + mv: r.b.mv_i, + motion_mode: r.b.motion_mode, + y_mode: r.b.y_mode, + }) + } + + fn next_coeff(&mut self) -> Result { + let v = *self.coeffs.get(self.next_coeff).ok_or(crate::av1::decode::Error::Invalid("coefficient record exhausted"))?; + self.next_coeff += 1; + Ok(v) + } +} + +/// The work buffers of a [`TileDecoder`] (`quant` all zero between transform blocks). +pub(crate) struct Buffers { + quant: Vec, + dequant: Vec, + residual: Vec, + color_map_y: Vec, + color_map_uv: Vec, + pred_buf: [Vec; 2], + mask: Vec, + mc_tmp: Vec, + levels: Vec, +} + +impl Buffers { + pub fn new() -> Buffers { + Buffers { + quant: vec![0; 1024], + dequant: vec![0; 64 * 64], + residual: vec![0; 64 * 64], + color_map_y: vec![0; 64 * 64], + color_map_uv: vec![0; 64 * 64], + pred_buf: [vec![0; 128 * 128], vec![0; 128 * 128]], + mask: vec![0; 128 * 128], + mc_tmp: vec![0; (2 * 128 + 8) * 128], + levels: vec![0; (32 + TX_PAD) * (32 + TX_PAD)], + } + } +} + /// Decoder for one tile. pub(crate) struct TileDecoder<'a, 'f> { pub fs: &'f FrameShared, @@ -128,6 +313,9 @@ pub(crate) struct TileDecoder<'a, 'f> { pub mc_tmp: Vec, /// Coefficient levels of the current transform block, padded (see TX_PAD). levels: Vec, + pub pass: Pass, + /// Written by [`Pass::Parse`], read by [`Pass::Reconstruct`]. + pub record: TileRecord, } const SB_MAX: usize = 32; // superblock size in 4x4 units (128 / 4) @@ -141,6 +329,21 @@ fn block_height(bs: usize) -> usize { impl<'a, 'f> TileDecoder<'a, 'f> { pub fn new(fs: &'f FrameShared, t: &'f mut TileState, data: &'a [u8], cdf: Box, tile_row: usize, tile_col: usize) -> Self { + Self::with_buffers(fs, t, data, cdf, tile_row, tile_col, Buffers::new()) + } + + /// [`TileDecoder::new`] reusing the work buffers of an earlier decoder of the same frame + /// (see [`TileDecoder::into_buffers`]). + pub fn with_buffers( + fs: &'f FrameShared, + t: &'f mut TileState, + data: &'a [u8], + cdf: Box, + tile_row: usize, + tile_col: usize, + bufs: Buffers, + ) -> Self { + let Buffers { quant, dequant, residual, color_map_y, color_map_uv, pred_buf, mask, mc_tmp, levels } = bufs; let ti = &fs.fh.tile_info; let (rs, re) = (ti.mi_row_starts[tile_row] as usize, ti.mi_row_starts[tile_row + 1] as usize); let (cs, ce) = (ti.mi_col_starts[tile_col] as usize, ti.mi_col_starts[tile_col + 1] as usize); @@ -164,19 +367,27 @@ impl<'a, 'f> TileDecoder<'a, 'f> { b: Block::default(), mvs: Default::default(), nb: Default::default(), - quant: vec![0; 1024], - dequant: vec![0; 64 * 64], - residual: vec![0; 64 * 64], - color_map_y: vec![0; 64 * 64], - color_map_uv: vec![0; 64 * 64], + quant, + dequant, + residual, + color_map_y, + color_map_uv, plane_tx_type: 0, - pred_buf: [vec![0; 128 * 128], vec![0; 128 * 128]], - mask: vec![0; 128 * 128], - mc_tmp: vec![0; (2 * 128 + 8) * 128], - levels: vec![0; (32 + TX_PAD) * (32 + TX_PAD)], + pred_buf, + mask, + mc_tmp, + levels, + pass: Pass::Full, + record: TileRecord::default(), } } + /// The work buffers and CDFs, for [`TileDecoder::with_buffers`]. + pub fn into_buffers(self) -> (Buffers, Box) { + let TileDecoder { quant, dequant, residual, color_map_y, color_map_uv, pred_buf, mask, mc_tmp, levels, cdf, .. } = self; + (Buffers { quant, dequant, residual, color_map_y, color_map_uv, pred_buf, mask, mc_tmp, levels }, cdf) + } + fn seq(&self) -> &SequenceHeader { &self.fs.seq } @@ -189,8 +400,11 @@ impl<'a, 'f> TileDecoder<'a, 'f> { c >= self.mi_col_start as isize && c < self.mi_col_end as isize && r >= self.mi_row_start as isize && r < self.mi_row_end as isize } - /// decode_tile( ) + /// decode_tile( ), or its reconstruction from [`TileDecoder::record`] in [`Pass::Reconstruct`]. pub fn decode_tile(&mut self) -> Result<()> { + if self.pass == Pass::Reconstruct { + return self.reconstruct_tile(); + } // clear_above_context( ) let t = &mut *self.t; for p in 0..3 { @@ -223,7 +437,11 @@ impl<'a, 'f> TileDecoder<'a, 'f> { self.clear_cdef(r, c); self.clear_block_decoded_flags(r, c, sb4); self.read_lr(r, c, sb_size); + let before = self.record.blocks.len(); self.decode_partition(r, c, sb_size)?; + if self.pass == Pass::Parse { + self.record.sb_blocks.push((self.record.blocks.len() - before) as u32); + } c += sb4; } r += sb4; @@ -231,6 +449,76 @@ impl<'a, 'f> TileDecoder<'a, 'f> { Ok(()) } + /// The reconstruction half of decode_tile( ): the superblocks in the same order, each block + /// predicted and reconstructed from its record. + fn reconstruct_tile(&mut self) -> Result<()> { + self.reconstruct_sb_rows(usize::MAX) + } + + /// Reconstruct the next `rows` superblock rows of the tile (the record keeps the position). + pub fn reconstruct_sb_rows(&mut self, rows: usize) -> Result<()> { + let sb4 = if self.seq().use_128x128_superblock { 32 } else { 16 }; + let mut r = self.mi_row_start + self.record.next_sb_row * sb4; + let mut done = 0; + while r < self.mi_row_end && done < rows { + let mut c = self.mi_col_start; + while c < self.mi_col_end { + self.clear_block_decoded_flags(r, c, sb4); + let n = *self.record.sb_blocks.get(self.record.next_sb).ok_or(crate::av1::decode::Error::Invalid("block record exhausted"))?; + self.record.next_sb += 1; + for _ in 0..n { + self.reconstruct_block()?; + } + c += sb4; + } + r += sb4; + done += 1; + self.record.next_sb_row += 1; + } + Ok(()) + } + + fn reconstruct_block(&mut self) -> Result<()> { + let rec = self.record.blocks.get(self.record.next_block).ok_or(crate::av1::decode::Error::Invalid("block record exhausted"))?; + self.record.next_block += 1; + self.b = rec.b.clone(); + self.current_q_index = rec.current_q_index; + if let Some(w) = &rec.warp_samples { + self.mvs.num_samples = w.0; + self.mvs.cand_list = w.1; + } + if let Some(maps) = &rec.color_maps { + if let Some(d) = self.color_map_y.get_mut(..maps.0.len()) { + d.copy_from_slice(&maps.0); + } + if let Some(d) = self.color_map_uv.get_mut(..maps.1.len()) { + d.copy_from_slice(&maps.1); + } + } + self.compute_prediction()?; + self.residual() + } + + /// Records the block for [`Pass::Reconstruct`] (its variables as parsed). + fn record_block(&mut self) { + let b = &self.b; + // The rows of the color maps (stride 64) the block's palette prediction reads. + let map_rows = |n: usize, h: usize| if n > 0 { (h + 2).min(64) * 64 } else { 0 }; + let rows_y = map_rows(b.palette_size_y, block_height(b.mi_size)); + let rows_uv = map_rows(b.palette_size_uv, block_height(b.mi_size) >> self.fs.ssy); + let size = std::mem::size_of::() + + rows_y + + rows_uv + + if b.motion_mode as usize == crate::av1::decode::spec_tables::LOCALWARP { 160 } else { 0 }; + if !self.record.grow(size) { + return; + } + let warp_samples = + (b.motion_mode as usize == crate::av1::decode::spec_tables::LOCALWARP).then(|| Box::new((self.mvs.num_samples, self.mvs.cand_list))); + let color_maps = (rows_y + rows_uv > 0).then(|| Box::new((self.color_map_y[..rows_y].to_vec(), self.color_map_uv[..rows_uv].to_vec()))); + self.record.blocks.push(BlockRecord { b: b.clone(), current_q_index: self.current_q_index, warp_samples, color_maps }); + } + fn clear_cdef(&mut self, r: usize, c: usize) { let t = &mut *self.t; t.set_cdef_idx(r, c, -1); @@ -461,7 +749,11 @@ impl<'a, 'f> TileDecoder<'a, 'f> { } } } - self.compute_prediction()?; + if self.pass == Pass::Parse { + self.record_block(); + } else { + self.compute_prediction()?; + } self.residual()?; let b = &self.b; let delta_lf = self.delta_lf; diff --git a/crates/video/src/av1/decode/tile/coeffs.rs b/crates/video/src/av1/decode/tile/coeffs.rs index 6a704f8ac..df358e68d 100644 --- a/crates/video/src/av1/decode/tile/coeffs.rs +++ b/crates/video/src/av1/decode/tile/coeffs.rs @@ -459,6 +459,58 @@ impl<'a, 'f> TileDecoder<'a, 'f> { } } + /// Moves the coefficients `coeffs` left in `quant` into the record (leaving `quant` zero, as + /// reconstruction does). + pub(super) fn record_coeffs(&mut self, eob: usize, tx_sz: usize) { + let scan = self.get_scan(tx_sz); + let scan = scan.get(..eob).unwrap_or(scan); + if !self.record.grow(4 * (3 + 2 * scan.len())) { + // Over the limit: the record is dropped (the frame is decoded again in one pass); + // `quant` must still be left zero. + for &pos in scan { + if let Some(q) = self.quant.get_mut(pos as usize) { + *q = 0; + } + } + return; + } + let rec = &mut self.record.coeffs; + rec.push(eob as i32); + if eob == 0 { + return; + } + rec.push(self.plane_tx_type as i32); + let count_at = rec.len(); + rec.push(0); + let mut count = 0; + for &pos in scan { + let v = std::mem::take(&mut self.quant[pos as usize]); + if v != 0 { + rec.push(pos as i32); + rec.push(v); + count += 1; + } + } + rec[count_at] = count; + } + + /// The next transform block's coefficients from the record into `quant` (and its type); + /// returns its eob. + pub(super) fn replay_coeffs(&mut self) -> crate::av1::decode::Result { + let eob = self.record.next_coeff()?; + if eob <= 0 { + return Ok(0); + } + self.plane_tx_type = usize::try_from(self.record.next_coeff()?).map_err(|_| crate::av1::decode::Error::Invalid("coefficient record"))?; + let count = self.record.next_coeff()?; + for _ in 0..count { + let pos = self.record.next_coeff()? as usize; + let v = self.record.next_coeff()?; + *self.quant.get_mut(pos).ok_or(crate::av1::decode::Error::Invalid("coefficient record"))? = v; + } + Ok(eob as usize) + } + /// Reconstruct process (7.12.3). pub(super) fn reconstruct(&mut self, plane: usize, x: usize, y: usize, tx_sz: usize, dc_only: bool) { // dqDenom (7.12.3) is 1, 2 or 4 and the dividend is non-negative. diff --git a/crates/video/src/av1/decode/tile/predict.rs b/crates/video/src/av1/decode/tile/predict.rs index b1a53f399..244be62c6 100644 --- a/crates/video/src/av1/decode/tile/predict.rs +++ b/crates/video/src/av1/decode/tile/predict.rs @@ -213,7 +213,8 @@ impl<'a, 'f> TileDecoder<'a, 'f> { if start_x >= max_x || start_y >= max_y { return Ok(()); } - if !self.b.is_inter { + let parse_only = self.pass == super::Pass::Parse; + if !self.b.is_inter && !parse_only { let palette = if plane == 0 { self.b.palette_size_y } else { self.b.palette_size_uv }; if palette > 0 { self.predict_palette(plane, start_x, start_y, x, y, tx_sz); @@ -266,9 +267,23 @@ impl<'a, 'f> TileDecoder<'a, 'f> { } } if !self.b.skip { - let eob = self.coeffs(plane, start_x, start_y, tx_sz); - if eob > 0 { - self.reconstruct(plane, start_x, start_y, tx_sz, eob == 1); + match self.pass { + super::Pass::Full => { + let eob = self.coeffs(plane, start_x, start_y, tx_sz); + if eob > 0 { + self.reconstruct(plane, start_x, start_y, tx_sz, eob == 1); + } + } + super::Pass::Parse => { + let eob = self.coeffs(plane, start_x, start_y, tx_sz); + self.record_coeffs(eob, tx_sz); + } + super::Pass::Reconstruct => { + let eob = self.replay_coeffs()?; + if eob > 0 { + self.reconstruct(plane, start_x, start_y, tx_sz, eob == 1); + } + } } } for i in 0..step_y { diff --git a/crates/video/tests/av1_decode/fuzz_hostile.rs b/crates/video/tests/av1_decode/fuzz_hostile.rs index 05dbbe126..31cb66073 100644 --- a/crates/video/tests/av1_decode/fuzz_hostile.rs +++ b/crates/video/tests/av1_decode/fuzz_hostile.rs @@ -1,7 +1,6 @@ //! Hostile-input robustness: truncation, header-region sweeps and random mutation of small //! ffmpeg-generated AV1 streams (frame by frame) must never panic or run away. Skips without ffmpeg. -use std::panic::{AssertUnwindSafe, catch_unwind}; use std::process::{Command, Stdio}; use std::sync::atomic::{AtomicUsize, Ordering}; @@ -20,8 +19,15 @@ impl Rng { } } -/// (name, encoder args, pix_fmt) -const SEEDS: &[(&str, &str, &str)] = &[("av1_fz_default", "-c:v libsvtav1 -g 4", "yuv420p"), ("av1_fz_10bit", "-c:v libsvtav1 -g 6", "yuv420p10le")]; +// Seeds are at least 64x64: SVT-AV1 before 3.0 (the Ubuntu runners have 2.3) refuses a source under 64 lines. +/// (name, encoder args, pix_fmt, size, decoder thread counts) +const SEEDS: &[(&str, &str, &str, &str, &[usize])] = &[ + ("av1_fz_default", "-c:v libsvtav1 -g 4", "yuv420p", "64x64", &[1, 3]), + ("av1_fz_10bit", "-c:v libsvtav1 -g 6", "yuv420p10le", "64x64", &[1, 3]), + // Several superblock rows, so corrupt references meet frames already predicting from their + // top rows (row wavefront with frame threads). + ("av1_fz_rows", "-c:v libsvtav1 -g 6", "yuv420p", "64x136", &[1, 8]), +]; fn ivf_frames(data: &[u8]) -> Vec> { let mut out = Vec::new(); @@ -37,14 +43,13 @@ fn ivf_frames(data: &[u8]) -> Vec> { out } -// Seeds are 64x64: SVT-AV1 before 3.0 (the Ubuntu runners have 2.3) refuses a source under 64 lines. -fn make(ff: &std::path::Path, name: &str, args: &str, pix: &str) -> Option>> { +fn make(ff: &std::path::Path, name: &str, args: &str, pix: &str, size: &str) -> Option>> { let out = craft_media_testkit::fixtures_dir("av1").join(format!("{name}.ivf")); let p = craft_media_testkit::fixtures::generate(&out, |tmp| { let a: Vec<&str> = args.split_whitespace().collect(); matches!( Command::new(ff) - .args(["-hide_banner", "-loglevel", "error", "-y", "-f", "lavfi", "-i", "testsrc2=size=64x64:rate=25", "-frames:v", "6", "-pix_fmt", pix]) + .args(["-hide_banner", "-loglevel", "error", "-y", "-f", "lavfi", "-i", &format!("testsrc2=size={size}:rate=25"), "-frames:v", "6", "-pix_fmt", pix]) .args(a) .args(["-f", "ivf"]) .arg(tmp) @@ -69,20 +74,29 @@ fn count_panics() { }); } -fn run_all(frames: &[Vec], label: &str) { +fn run_all(frames: &[Vec], threads: &[usize], label: &str) { craft_media_testkit::set_progress(label); count_panics(); let before = PANICS.load(Ordering::SeqCst); - let res = catch_unwind(AssertUnwindSafe(|| { - for threads in [1, 3] { - let mut dec = Decoder::with_threads(threads); - for (i, f) in frames.iter().enumerate() { - let _ = dec.decode_pts(f, i as i64); - } - let _ = dec.flush_result(); - } - })); - assert!(res.is_ok() && PANICS.load(Ordering::SeqCst) == before, "panic: {label}"); + // Every thread count decodes the stream at the same time, each on a thread of its own. + let ok = std::thread::scope(|s| { + let runs: Vec<_> = threads + .iter() + .map(|&threads| { + s.spawn(move || { + let mut dec = Decoder::with_threads(threads); + for (i, f) in frames.iter().enumerate() { + let _ = dec.decode_pts(f, i as i64); + } + let _ = dec.flush_result(); + }) + }) + .collect(); + // Join every run (no short cut), then check them all. + let joined: Vec = runs.into_iter().map(|r| r.join().is_ok()).collect(); + joined.into_iter().all(|ok| ok) + }); + assert!(ok && PANICS.load(Ordering::SeqCst) == before, "panic: {label}"); } /// Random-mutation rounds per seed (raise with FILMCRAFT_FUZZ_ITERS for a long hunt). @@ -95,17 +109,23 @@ const DEADLINE_SECS: u64 = 600; #[test] fn hostile_streams_never_panic() { - craft_media_testkit::with_deadline(DEADLINE_SECS, sweep); + craft_media_testkit::with_deadline(DEADLINE_SECS, || sweep(&SEEDS[..2])); } -fn sweep() { +/// The seed with several superblock rows, in a test of its own so it runs beside the others. +#[test] +fn hostile_streams_with_superblock_rows_never_panic() { + craft_media_testkit::with_deadline(DEADLINE_SECS, || sweep(&SEEDS[2..])); +} + +fn sweep(seeds: &[(&str, &str, &str, &str, &[usize])]) { let Some(ff) = craft_media_testkit::ffmpeg_or_skip("AV1 fuzz") else { return }; - for &(name, args, pix) in SEEDS { + for &(name, args, pix, size, threads) in seeds { if !craft_media_testkit::ffmpeg_has_encoder(&ff, "libsvtav1") { craft_media_testkit::skip_test("AV1 fuzz", &format!("this ffmpeg has no libsvtav1 encoder (seed {name})")); continue; } - let Some(seed) = make(&ff, name, args, pix) else { + let Some(seed) = make(&ff, name, args, pix, size) else { panic!("ffmpeg has libsvtav1 but could not encode the {name} seed"); }; if seed.is_empty() { @@ -118,7 +138,7 @@ fn sweep() { for n in (0..len).step_by((len / 200).max(1)) { let mut d = seed.clone(); d[fi].truncate(n); - run_all(&d, &format!("{name} frame {fi} truncate {n}")); + run_all(&d, threads, &format!("{name} frame {fi} truncate {n}")); } } // header region of every frame: every byte to a few values, every bit @@ -127,12 +147,12 @@ fn sweep() { for v in [0u8, 0xff, 0x80, 0x01, 0x7f] { let mut d = seed.clone(); d[fi][p] = v; - run_all(&d, &format!("{name} frame {fi} byte {p}={v:#x}")); + run_all(&d, threads, &format!("{name} frame {fi} byte {p}={v:#x}")); } for b in 0..8 { let mut d = seed.clone(); d[fi][p] ^= 1 << b; - run_all(&d, &format!("{name} frame {fi} flip {p}.{b}")); + run_all(&d, threads, &format!("{name} frame {fi} flip {p}.{b}")); } } } @@ -151,7 +171,7 @@ fn sweep() { d[fi][p] = rng.next() as u8; } } - run_all(&d, &format!("{name} random {i}")); + run_all(&d, threads, &format!("{name} random {i}")); } } } diff --git a/crates/video/tests/av1_decode/main.rs b/crates/video/tests/av1_decode/main.rs index 50c3939f6..76a5adfcf 100644 --- a/crates/video/tests/av1_decode/main.rs +++ b/crates/video/tests/av1_decode/main.rs @@ -9,3 +9,4 @@ mod hostile_dims; mod oracle_inter; mod oracle_intra; mod perf; +mod wavefront; diff --git a/crates/video/tests/av1_decode/wavefront.rs b/crates/video/tests/av1_decode/wavefront.rs new file mode 100644 index 000000000..725b02544 --- /dev/null +++ b/crates/video/tests/av1_decode/wavefront.rs @@ -0,0 +1,93 @@ +//! Stress tests of the frame threading (parse / reconstruct split and the row wavefront across +//! frames): every thread count gives the single-thread pictures, run after run, and dropping +//! or flushing a busy decoder never hangs. A hang fails the test through the deadline. + +use crate::common; +use common::*; +use craft_video::av1::decode::{Decoder, Picture}; + +/// A GOP with many superblock rows (the wavefront has rows to overlap), hierarchical +/// references and motion reaching across rows. +fn spec() -> Spec { + Spec::new("wavefront_640x480", "testsrc2=s=640x480:r=25,rotate=a=t*0.5:c=black", 24, "yuv420p", &["-preset", "8", "-crf", "38"]) +} + +/// Seconds a test may take before it counts as a hang (override: FILMCRAFT_HOSTILE_TIMEOUT_SECS). +const DEADLINE_SECS: u64 = 300; + +fn decode(tus: &[Vec], threads: usize) -> Vec { + let mut dec = Decoder::with_threads(threads); + let mut pics = Vec::new(); + for (i, tu) in tus.iter().enumerate() { + pics.extend(dec.decode_pts(tu, i as i64).unwrap_or_else(|e| panic!("threads {threads}, unit {i}: {e}"))); + } + pics.extend(dec.flush_result().unwrap_or_else(|e| panic!("threads {threads}, flush: {e}"))); + pics +} + +#[test] +fn every_thread_count_gives_the_single_thread_pictures_repeatedly() { + let Some(ff) = ffmpeg() else { return }; + let tus = ivf_frames(&make(&ff, &spec())); + craft_media_testkit::with_deadline(DEADLINE_SECS, move || { + let want = decode(&tus, 1); + assert_eq!(want.len(), 24); + for threads in [2, 3, 4, 5, 8, 16] { + for round in 0..4 { + assert!(decode(&tus, threads) == want, "threads {threads}, round {round}: pictures differ"); + } + } + }); +} + +/// 128x128 superblocks in two tile columns (libaom), with motion field estimation: the +/// wavefront over the superblock rows of every tile column. +fn spec_sb128_tiles() -> Spec { + let enc = ["-cpu-used", "8", "-crf", "40", "-tile-columns", "1", "-lag-in-frames", "16", "-aom-params", "sb-size=128:enable-ref-frame-mvs=1"]; + Spec::new("wavefront_sb128_tiles", "testsrc2=s=640x400:r=25,rotate=a=t*0.5:c=black", 16, "yuv420p", &enc).encoder("libaom-av1") +} + +#[test] +fn superblocks_of_128_in_tile_columns_give_the_single_thread_pictures() { + let Some(ff) = ffmpeg_libaom() else { return }; + let tus = ivf_frames(&make(&ff, &spec_sb128_tiles())); + craft_media_testkit::with_deadline(DEADLINE_SECS, move || { + let want = decode(&tus, 1); + assert_eq!(want.len(), 16); + for threads in [2, 3, 4, 8, 16] { + for round in 0..2 { + assert!(decode(&tus, threads) == want, "threads {threads}, round {round}: pictures differ"); + } + } + }); +} + +#[test] +fn dropping_or_flushing_a_busy_decoder_never_hangs() { + let Some(ff) = ffmpeg() else { return }; + let tus = ivf_frames(&make(&ff, &spec())); + craft_media_testkit::with_deadline(DEADLINE_SECS, move || { + let want = decode(&tus, 1); + for threads in [2, 3, 8, 16] { + for cut in [1, 2, 7, 12, 23] { + // Dropped with frames in flight (no flush). + let mut dec = Decoder::with_threads(threads); + for (i, tu) in tus.iter().take(cut).enumerate() { + dec.decode_pts(tu, i as i64).expect("decode"); + } + drop(dec); + // Flushed mid-stream (as before a seek), then continued: the same pictures. + let mut dec = Decoder::with_threads(threads); + let mut pics = Vec::new(); + for (i, tu) in tus.iter().enumerate() { + if i == cut { + pics.extend(dec.flush_result().expect("flush")); + } + pics.extend(dec.decode_pts(tu, i as i64).expect("decode")); + } + pics.extend(dec.flush_result().expect("flush")); + assert!(pics == want, "threads {threads}, flush before unit {cut}: pictures differ"); + } + } + }); +} From c25999c8a48ab1065f4191d992dc6b916f59a4b8 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Thu, 12 Nov 2026 21:51:12 +0100 Subject: [PATCH 002/349] hevc decode: dequantise while decoding residuals, table-driven sig_coeff contexts Each coefficient is scaled (8.6.3) as it is decoded and stored in a list of (index, value) instead of a separate pass over the bounding box. Only the coefficient bounding box is cleared before the list is scattered into it. DC-only blocks add the inverse-DC constant straight to the prediction. sig_coeff_flag ctxInc comes from a per-sub-block table, last_sb / last_pos from inverse scan tables. Merge candidates use the fixed five-entry list instead of a Vec. Same change as storytold/Filmcraft#3188 (residual part), ported onto craft-video. Co-Authored-By: Claude Sonnet 5.5 --- crates/video/src/hevc/decode/mvpred.rs | 33 ++- crates/video/src/hevc/decode/slicedec.rs | 32 ++- .../hevc/decode/slicedec/transform_tree.rs | 194 +++++++++--------- crates/video/src/hevc/decode/tables.rs | 79 ++++++- 4 files changed, 224 insertions(+), 114 deletions(-) diff --git a/crates/video/src/hevc/decode/mvpred.rs b/crates/video/src/hevc/decode/mvpred.rs index 962bbaa8c..9abbe33aa 100644 --- a/crates/video/src/hevc/decode/mvpred.rs +++ b/crates/video/src/hevc/decode/mvpred.rs @@ -152,38 +152,35 @@ impl<'a, S: crate::hevc::decode::picture::Sample> SliceDecoder<'a, S> { col.ref_idx[1] = 0; col_avail = true; } - let mut cands: Vec = list[..n].to_vec(); if col_avail { - cands.push(col); + list[n] = col; + n += 1; } - if merge_idx < cands.len() { - return self.finish_merge(cands[merge_idx], w0, h0); + if merge_idx < n { + return self.finish_merge(list[merge_idx], w0, h0); } // combined bi-predictive candidates (8.5.3.2.4) - let num_orig = cands.len(); + let num_orig = n; if self.sh.is_b() && num_orig > 1 && num_orig < max { let mut comb = 0; - while comb < num_orig * (num_orig - 1) && cands.len() < max { + while comb < num_orig * (num_orig - 1) && n < max { let (i0, i1) = COMB[comb]; - let (c0, c1) = (cands[i0], cands[i1]); + let (c0, c1) = (list[i0], list[i1]); if c0.pred(0) && c1.pred(1) && (self.ref_pic(0, c0.ref_idx[0]).poc != self.ref_pic(1, c1.ref_idx[1]).poc || c0.mv[0] != c1.mv[1]) { - cands.push(MvField { mv: [c0.mv[0], c1.mv[1]], ref_idx: [c0.ref_idx[0], c1.ref_idx[1]] }); + list[n] = MvField { mv: [c0.mv[0], c1.mv[1]], ref_idx: [c0.ref_idx[0], c1.ref_idx[1]] }; + n += 1; } comb += 1; } } - if merge_idx < cands.len() { - return self.finish_merge(cands[merge_idx], w0, h0); + if merge_idx < n { + return self.finish_merge(list[merge_idx], w0, h0); } - // zero candidates (8.5.3.2.5) + // zero candidates (8.5.3.2.5): candidate merge_idx is the (merge_idx - n)-th one let num_ref = if self.sh.is_b() { self.sh.num_ref_idx[0].min(self.sh.num_ref_idx[1]) } else { self.sh.num_ref_idx[0] } as usize; - let mut zero_idx = 0; - while cands.len() <= merge_idx { - let r = if zero_idx < num_ref { zero_idx as i8 } else { 0 }; - cands.push(MvField { mv: [[0; 2]; 2], ref_idx: [r, if self.sh.is_b() { r } else { -1 }] }); - zero_idx += 1; - } - self.finish_merge(cands[merge_idx], w0, h0) + let zero_idx = merge_idx - n; + let r = if zero_idx < num_ref { zero_idx as i8 } else { 0 }; + self.finish_merge(MvField { mv: [[0; 2]; 2], ref_idx: [r, if self.sh.is_b() { r } else { -1 }] }, w0, h0) } fn finish_merge(&self, mut f: MvField, w: i32, h: i32) -> MvField { diff --git a/crates/video/src/hevc/decode/slicedec.rs b/crates/video/src/hevc/decode/slicedec.rs index 102b74719..8ebaeafb1 100644 --- a/crates/video/src/hevc/decode/slicedec.rs +++ b/crates/video/src/hevc/decode/slicedec.rs @@ -16,7 +16,7 @@ use crate::hevc::decode::spec_tables::{ INTRA_CHROMA, LAST_X_PREFIX, LAST_Y_PREFIX, MERGE_FLAG, MERGE_IDX, MVP_FLAG, PART_MODE, PRED_MODE, PREV_INTRA_LUMA, REF_IDX, RQT_ROOT_CBF, SAO_MERGE, SAO_TYPE, SIG_COEFF, SPLIT_CU, SPLIT_TRANSFORM, TRANSFORM_SKIP, }; -use crate::hevc::decode::tables::{CTX_IDX_MAP, INTRA_CHROMA_MODE_422, LEVEL_SCALE, SCAN_4, qpc, scan_order}; +use crate::hevc::decode::tables::{INTRA_CHROMA_MODE_422, LEVEL_SCALE, SCAN_4, SIG_CTX, qpc, scan_order, scan_pos}; use crate::hevc::decode::transform; use std::sync::Arc; @@ -340,6 +340,8 @@ pub struct SliceDecoder<'a, S> { pub cu_part: PartMode, // scratch pub coeffs: Vec, + /// Scaled non-zero coefficients of the current transform block: (index in `coeffs`, value). + pub nz: Vec<(u16, i32)>, pub pred0: Vec, pub pred1: Vec, pub mc: crate::hevc::decode::inter::McScratch, @@ -461,6 +463,7 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { intra_split: false, cu_part: PartMode::P2Nx2N, coeffs: vec![0; 32 * 32], + nz: vec![(0, 0); 32 * 32], pred0: vec![0; 64 * 64], pred1: vec![0; 64 * 64], mc: Default::default(), @@ -632,3 +635,30 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { Ok(()) } } + +#[cfg(test)] +mod tests { + use crate::hevc::decode::transform; + + /// `reconstruct` clears only the coefficient bounding box, so the inverse transform must not + /// read the stale values left outside it by the previous block. + #[test] + fn inverse_transform_reads_only_the_coefficient_box() { + for &(n, dst) in &[(4usize, true), (4, false), (8, false), (16, false), (32, false)] { + for (max_x, max_y) in [(0, 1), (1, 0), (2, 3), (n / 2, 1), (n - 1, 0), (n - 1, n - 1)] { + let (mut clean, mut stale) = (vec![0i32; n * n], vec![0i32; n * n]); + for (i, (c, s)) in clean.iter_mut().zip(stale.iter_mut()).enumerate() { + let (x, y) = (i % n, i / n); + *s = 12345 - i as i32; + if x <= max_x && y <= max_y { + *c = (i as i32 * 37) % 201 - 100; + *s = *c; + } + } + transform::inverse_transform(&mut clean, n, dst, max_x, max_y, 12); + transform::inverse_transform(&mut stale, n, dst, max_x, max_y, 12); + assert_eq!(clean, stale, "n {n} dst {dst} box ({max_x}, {max_y})"); + } + } + } +} diff --git a/crates/video/src/hevc/decode/slicedec/transform_tree.rs b/crates/video/src/hevc/decode/slicedec/transform_tree.rs index 8512c341a..aa099a957 100644 --- a/crates/video/src/hevc/decode/slicedec/transform_tree.rs +++ b/crates/video/src/hevc/decode/slicedec/transform_tree.rs @@ -1,7 +1,7 @@ use super::{ - CBF_CHROMA, CBF_LUMA, CODED_SUB_BLOCK, CTX_IDX_MAP, CU_QP_DELTA_ABS, ChromaFormat, E_TU_H, E_TU_V, F_CBF, F_INTRA, GT1, GT2, LAST_X_PREFIX, - LAST_Y_PREFIX, LEVEL_SCALE, PartMode, Result, SCAN_4, SIG_COEFF, SPLIT_TRANSFORM, Sample, SliceDecoder, TRANSFORM_SKIP, ensure, for_runs, intra, - scan_order, transform, + CBF_CHROMA, CBF_LUMA, CODED_SUB_BLOCK, CU_QP_DELTA_ABS, ChromaFormat, E_TU_H, E_TU_V, F_CBF, F_INTRA, GT1, GT2, LAST_X_PREFIX, LAST_Y_PREFIX, + LEVEL_SCALE, PartMode, Result, SCAN_4, SIG_COEFF, SIG_CTX, SPLIT_TRANSFORM, Sample, SliceDecoder, TRANSFORM_SKIP, ensure, for_runs, intra, + scan_order, scan_pos, transform, }; /// Significant scan positions of one sub-block, in decoding (descending) order. @@ -44,54 +44,26 @@ struct GreaterFlags { g1ctx: u32, } -/// sigCtx increment of sig_coeff_flag (9.3.4.2.5) for the position `(xp, yp)` inside the sub-block. -fn sig_ctx_inc(p: &SigMapParams, (xp, yp): (usize, usize)) -> usize { - let (xc, yc) = (p.xs * 4 + xp, p.ys * 4 + yp); +/// sigCtx increments (9.3.4.2.5) of the 16 scan positions of one sub-block. +fn sig_ctx_table(p: &SigMapParams) -> [u8; 16] { if p.log2 == 2 { - return CTX_IDX_MAP[(yc << 2) + xc] as usize; + return SIG_CTX[p.scan_idx][4]; } - if xc + yc == 0 { - return 0; - } - let mut s = match p.prev_csbf { - 0 => { - if xp + yp == 0 { - 2 - } else if xp + yp < 3 { - 1 - } else { - 0 - } - } - 1 => { - if yp == 0 { - 2 - } else if yp == 1 { - 1 - } else { - 0 - } - } - 2 => { - if xp == 0 { - 2 - } else if xp == 1 { - 1 - } else { - 0 - } - } - _ => 2, - }; - if p.c == 0 { - if p.xs + p.ys > 0 { - s += 3; - } - s += if p.log2 == 3 { if p.scan_idx == 0 { 9 } else { 15 } } else { 21 }; + let off = if p.c == 0 { + (if p.xs + p.ys > 0 { 3 } else { 0 }) + if p.log2 == 3 { if p.scan_idx == 0 { 9 } else { 15 } } else { 21 } + } else if p.log2 == 3 { + 9 } else { - s += if p.log2 == 3 { 9 } else { 12 }; + 12 + }; + let mut t = SIG_CTX[p.scan_idx][p.prev_csbf as usize]; + for v in t.iter_mut() { + *v += off; } - s + if p.xs + p.ys == 0 { + t[0] = 0; + } + t } /// A node of the transform tree: the block at (`x0`, `y0`) of size 2^`log2`, its parent's origin @@ -333,14 +305,13 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { /// sig_coeff_flag decoding of one coded sub-block, appending the significant scan positions /// (descending) to `list`. fn read_sig_map(&mut self, p: &SigMapParams, list: &mut SigList) { - let pos_scan = &SCAN_4[p.scan_idx]; let c_off_sig = if p.c == 0 { 0 } else { 27 }; + let ctx_tab = sig_ctx_table(p); let mut infer_dc = p.infer_dc; let mut np = p.start; while np >= 0 { - let (xp, yp) = (pos_scan[np as usize].0 as usize, pos_scan[np as usize].1 as usize); if np > 0 || !infer_dc { - let sig_ctx = sig_ctx_inc(p, (xp, yp)); + let sig_ctx = ctx_tab[np as usize] as usize; if self.c.decode_decision(SIG_COEFF + c_off_sig + sig_ctx) == 1 { list.push(np as u8); infer_dc = false; @@ -438,9 +409,23 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { let sb_scan = scan_order(log2sb, scan_idx); let pos_scan = &SCAN_4[scan_idx]; let sb_w = 1usize << log2sb; - let last_sb = sb_scan.iter().position(|&(x, y)| x as u32 == lx >> 2 && y as u32 == ly >> 2).unwrap_or(0); - let last_pos = pos_scan.iter().position(|&(x, y)| x as u32 == lx & 3 && y as u32 == ly & 3).unwrap_or(0); - self.coeffs[..n * n].fill(0); + let last_sb = scan_pos(log2sb, scan_idx, lx >> 2, ly >> 2); + let last_pos = scan_pos(2, scan_idx, lx & 3, ly & 3); + // scaling (8.6.3), applied as each coefficient is decoded + let bd = if c == 0 { self.pic.bd_y } else { self.pic.bd_c }; + let bd_shift = bd + log2 - 5; + let round = 1i64 << (bd_shift - 1); + let scale = (LEVEL_SCALE[(qp % 6) as usize] as i64) << (qp / 6); + let matrix = match &self.pic.scaling { + Some(s) if !bypass && !(ts && n > 4) => { + let size_id = (log2 - 2) as usize; + let matrix_id = if self.cu_intra { c } else { 3 + c }; + Some((s.clone(), size_id * 6 + matrix_id)) + } + _ => None, + }; + let m: Option<&[u8]> = matrix.as_ref().map(|(s, i)| &s[*i][..]); + let mut nnz = 0; let mut csbf = [0u8; 64]; let mut prev_g1: Option = None; let sdh = self.pps.sign_data_hiding && !bypass; @@ -485,12 +470,18 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { for k in 0..list.n { let np = list.pos[k] as usize; let (xc, yc) = (xs * 4 + pos_scan[np].0 as usize, ys * 4 + pos_scan[np].1 as usize); - self.coeffs[yc * n + xc] = values[k]; + let mut v = values[k]; + if !bypass { + let f = m.map_or(16, |m| m[yc * n + xc] as i64); + v = ((v as i64 * f * scale + round) >> bd_shift).clamp(-32768, 32767) as i32; + } + self.nz[nnz] = ((yc * n + xc) as u16, v); + nnz += 1; max_x = max_x.max(xc); max_y = max_y.max(yc); } } - self.reconstruct((x0, y0), log2, c, qp, ts, (max_x, max_y)) + self.reconstruct((x0, y0), log2, c, ts, nnz, (max_x, max_y)) } fn coeff_abs_level_remaining(&mut self, rice: u32) -> Result { @@ -508,55 +499,70 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { } } - /// Scaling, transform and addition to the prediction. - fn reconstruct(&mut self, (x0, y0): (i32, i32), log2: u32, c: usize, qp: i32, ts: bool, (max_x, max_y): (usize, usize)) -> Result<()> { + /// Transform of the scaled coefficients `nz[..nnz]` and addition to the prediction. + fn reconstruct(&mut self, (x0, y0): (i32, i32), log2: u32, c: usize, ts: bool, nnz: usize, (max_x, max_y): (usize, usize)) -> Result<()> { let n = 1usize << log2; let bd = if c == 0 { self.pic.bd_y } else { self.pic.bd_c }; - let coeffs = &mut self.coeffs[..n * n]; - let mut dc_only = false; - if !self.cu_transquant_bypass { - // scaling (8.6.3) - let bd_shift = bd + log2 - 5; - let round = 1i64 << (bd_shift - 1); - let scale = (LEVEL_SCALE[(qp % 6) as usize] as i64) << (qp / 6); - let m: Option<&[u8]> = match &self.pic.scaling { - Some(s) if !(ts && n > 4) => { - let size_id = (log2 - 2) as usize; - let matrix_id = if self.cu_intra { c } else { 3 + c }; - Some(&s[size_id * 6 + matrix_id]) - } - _ => None, - }; - for y in 0..=max_y { - for x in 0..=max_x { - let v = coeffs[y * n + x]; - if v != 0 { - let f = m.map_or(16, |m| m[y * n + x] as i64); - coeffs[y * n + x] = ((v as i64 * f * scale + round) >> bd_shift).clamp(-32768, 32767) as i32; - } - } + let bypass = self.cu_transquant_bypass; + let dst = self.cu_intra && c == 0 && n == 4; + let (stride, max) = (if c == 0 { self.pic.width } else { self.pic.cwidth }, (1i32 << bd) - 1); + let off = y0 as usize * stride + x0 as usize; + let plane = &mut self.pic.planes[c]; + let bd_shift = 20 - bd; + if !bypass && !ts && max_x == 0 && max_y == 0 && !dst { + let v = transform::inverse_dc(self.nz[0].1, bd_shift); + match n { + 4 => add_dc::(plane, off, stride, v, max), + 8 => add_dc::(plane, off, stride, v, max), + 16 => add_dc::(plane, off, stride, v, max), + _ => add_dc::(plane, off, stride, v, max), } - let bd_shift = 20 - bd; + return Ok(()); + } + // the inverse transform reads only the bounding box of the coefficients + let coeffs = &mut self.coeffs[..n * n]; + if bypass || ts { + coeffs.fill(0); + } else { + for row in coeffs.chunks_exact_mut(n).take(max_y + 1) { + row[..=max_x].fill(0); + } + } + for &(p, v) in &self.nz[..nnz] { + coeffs[p as usize] = v; + } + if !bypass { if ts { transform::transform_skip(coeffs, n, bd_shift); - } else if max_x == 0 && max_y == 0 && !(self.cu_intra && c == 0 && n == 4) { - let v = transform::inverse_dc(coeffs[0], bd_shift); - coeffs.fill(v); - dc_only = true; } else { - let dst = self.cu_intra && c == 0 && n == 4; transform::inverse_transform(coeffs, n, dst, max_x, max_y, bd_shift); } } - let _ = dc_only; - let (stride, max) = (if c == 0 { self.pic.width } else { self.pic.cwidth }, (1i32 << bd) - 1); - let plane = &mut self.pic.planes[c]; - for y in 0..n { - let row = &mut plane[(y0 as usize + y) * stride + x0 as usize..][..n]; - for (x, s) in row.iter_mut().enumerate() { - *s = S::from_i32((s.to_i32() + coeffs[y * n + x]).clamp(0, max)); - } + match n { + 4 => add_residual::(plane, off, stride, coeffs, max), + 8 => add_residual::(plane, off, stride, coeffs, max), + 16 => add_residual::(plane, off, stride, coeffs, max), + _ => add_residual::(plane, off, stride, coeffs, max), } Ok(()) } } + +#[inline(always)] +fn add_residual(plane: &mut [S], off: usize, stride: usize, res: &[i32], max: i32) { + for (y, r) in res.as_chunks::().0.iter().take(N).enumerate() { + let row = &mut plane[off + y * stride..][..N]; + for (s, &d) in row.iter_mut().zip(r) { + *s = S::from_i32((s.to_i32() + d).max(0).min(max)); + } + } +} + +#[inline(always)] +fn add_dc(plane: &mut [S], off: usize, stride: usize, v: i32, max: i32) { + for y in 0..N { + for s in &mut plane[off + y * stride..][..N] { + *s = S::from_i32((s.to_i32() + v).max(0).min(max)); + } + } +} diff --git a/crates/video/src/hevc/decode/tables.rs b/crates/video/src/hevc/decode/tables.rs index 7e20bd99e..1c9c39c44 100644 --- a/crates/video/src/hevc/decode/tables.rs +++ b/crates/video/src/hevc/decode/tables.rs @@ -51,6 +51,72 @@ pub fn scan_order(log2: u32, scan_idx: usize) -> &'static [(u8, u8)] { } } +/// Inverse of a scan of an `N x N` block: scan position at `[y * N + x]`. +const fn inverse(scan: [(u8, u8); L], n: usize) -> [u8; L] { + let mut out = [0u8; L]; + let mut i = 0; + while i < L { + out[scan[i].1 as usize * n + scan[i].0 as usize] = i as u8; + i += 1; + } + out +} + +static INV_SCAN_1: [[u8; 1]; 3] = [[0], [0], [0]]; +static INV_SCAN_2: [[u8; 4]; 3] = [inverse(diag::<4>(2), 2), inverse(hv::<4>(2, false), 2), inverse(hv::<4>(2, true), 2)]; +static INV_SCAN_4: [[u8; 16]; 3] = [inverse(diag::<16>(4), 4), inverse(hv::<16>(4, false), 4), inverse(hv::<16>(4, true), 4)]; +static INV_SCAN_8: [[u8; 64]; 3] = [inverse(diag::<64>(8), 8), inverse(hv::<64>(8, false), 8), inverse(hv::<64>(8, true), 8)]; + +/// Position of (x, y) in ScanOrder[log2BlockSize][scanIdx] (log2BlockSize 0..=3). +#[inline] +pub fn scan_pos(log2: u32, scan_idx: usize, x: u32, y: u32) -> usize { + let i = ((y << log2) + x) as usize; + (match log2 { + 0 => INV_SCAN_1[scan_idx][i], + 1 => INV_SCAN_2[scan_idx][i], + 2 => INV_SCAN_4[scan_idx][i], + _ => INV_SCAN_8[scan_idx][i], + }) as usize +} + +/// sig_coeff_flag ctxInc (9.3.4.2.5) by scan position n inside a 4x4 sub-block, `[scanIdx][k][n]`: +/// k = prevCsbf (0..=3) gives sigCtx of blocks larger than 4x4 before the position and size +/// offsets; k = 4 gives ctxIdxMap of 4x4 blocks. +pub static SIG_CTX: [[[u8; 16]; 5]; 3] = [sig_ctx(diag::<16>(4)), sig_ctx(hv::<16>(4, false)), sig_ctx(hv::<16>(4, true))]; + +const fn sig_ctx(scan: [(u8, u8); 16]) -> [[u8; 16]; 5] { + let mut out = [[0u8; 16]; 5]; + let mut n = 0; + while n < 16 { + let (x, y) = (scan[n].0, scan[n].1); + out[0][n] = if x + y == 0 { + 2 + } else if x + y < 3 { + 1 + } else { + 0 + }; + out[1][n] = if y == 0 { + 2 + } else if y == 1 { + 1 + } else { + 0 + }; + out[2][n] = if x == 0 { + 2 + } else if x == 1 { + 1 + } else { + 0 + }; + out[3][n] = 2; + out[4][n] = CTX_IDX_MAP[(y as usize) * 4 + x as usize]; + n += 1; + } + out +} + /// Up-right diagonal scan for log2 size 2 or 3. pub fn scan_diag(log2: u32) -> &'static [(u8, u8)] { scan_order(log2, 0) @@ -81,7 +147,7 @@ pub fn qpc(qpi: i32, chroma_array_type_1: bool) -> i32 { } /// Table 9-50 ctxIdxMap for 4x4 sig_coeff_flag contexts. -pub static CTX_IDX_MAP: [u8; 16] = [0, 1, 4, 5, 2, 3, 4, 5, 6, 6, 8, 8, 7, 7, 8, 8]; +pub const CTX_IDX_MAP: [u8; 16] = [0, 1, 4, 5, 2, 3, 4, 5, 6, 6, 8, 8, 7, 7, 8, 8]; /// levelScale (8-309). pub static LEVEL_SCALE: [i32; 6] = [40, 45, 51, 57, 64, 72]; @@ -137,6 +203,17 @@ mod tests { assert_eq!(SCAN_4[1][1], (1, 0)); } + #[test] + fn scan_pos_inverts_scan_order() { + for log2 in 0..4 { + for scan_idx in 0..3 { + for (i, &(x, y)) in scan_order(log2, scan_idx).iter().enumerate() { + assert_eq!(scan_pos(log2, scan_idx, x as u32, y as u32), i); + } + } + } + } + #[test] fn dct_matrix_properties() { // rows are nearly orthogonal with norm ~ 64^2 * 32 From 45ddc4ffa6243c5509ef34c8b5260acdcc90b645 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Thu, 12 Nov 2026 22:05:44 +0100 Subject: [PATCH 003/349] mpegts: a repeated PAT or PMT packet is not appended to the section in progress The scan fed every PAT and PMT packet to the section parser, so a packet sent twice (same continuity counter and payload, H.222.0 2.4.3.3) appended its payload to the section being collected. PAT and PMT packets now go through a per-PID repeat guard first, like the elementary stream packets; a packet that signals a discontinuity is never taken for a repeat. The rest of storytold/Filmcraft#1438 is already in craft-media (#993). Co-Authored-By: Claude Sonnet 5.5 --- crates/media/src/mpegts/tests.rs | 17 +++++++++++++++++ crates/media/src/mpegts/ts.rs | 8 ++++++++ 2 files changed, 25 insertions(+) diff --git a/crates/media/src/mpegts/tests.rs b/crates/media/src/mpegts/tests.rs index 0215680ad..b9cb1af3b 100644 --- a/crates/media/src/mpegts/tests.rs +++ b/crates/media/src/mpegts/tests.rs @@ -791,6 +791,23 @@ fn scrambled_packet_is_skipped_with_a_warning() { assert!(total(&f) < total(&base)); } +#[test] +fn repeated_pat_and_pmt_packets_are_dropped_before_the_section_parser() { + let clean = audio_ts(2); + let first = |pid: u16| { + (0..clean.len() / 188).map(|i| i * 188).find(|&o| (((clean[o + 1] & 0x1F) as u16) << 8 | clean[o + 2] as u16) == pid).expect("packet exists") + }; + let mut dup = clean.clone(); + for pid in [0x100, 0] { + let o = first(pid); + let copy = dup[o..o + 188].to_vec(); + dup.splice(o + 188..o + 188, copy); + } + let f = open(&dup).unwrap(); + assert!(f.warnings.iter().any(|w| w.contains("2 duplicate packet(s) dropped")), "{:?}", f.warnings); + assert!(!f.warnings.iter().any(|w| w.contains("continuity") || w.contains("CRC")), "{:?}", f.warnings); +} + #[test] fn duplicate_packet_is_dropped_but_a_different_payload_with_the_same_counter_is_kept() { let clean = audio_ts(6); diff --git a/crates/media/src/mpegts/ts.rs b/crates/media/src/mpegts/ts.rs index a4c01a986..1d28bb736 100644 --- a/crates/media/src/mpegts/ts.rs +++ b/crates/media/src/mpegts/ts.rs @@ -497,6 +497,7 @@ pub(crate) fn scan(src: &S, packet_size: usize, sync_off let mut warnings: Vec = Vec::new(); let mut pat = Psi::default(); let mut pmt = PmtState::default(); + let mut psi_dup: HashMap = HashMap::new(); let mut es: HashMap = HashMap::new(); let mut order: Vec = Vec::new(); // one timestamp unwrapper for the program: its streams share one clock, so a stream whose @@ -560,6 +561,13 @@ pub(crate) fn scan(src: &S, packet_size: usize, sync_off } continue; } + if pk.pid == 0 || Some(pk.pid) == pmt.pmt_pid { + // a repeated packet would append its payload to the section in progress + if psi_dup.entry(pk.pid).or_default().is_dup(&pk) { + duplicates += 1; + continue; + } + } if pk.pid == 0 { feed_pat(&pk, &mut pat, &mut pmt, &mut crc_errors); continue; From 81bf3feb39a3304a9d9bb30025ad208ffd158602 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Thu, 12 Nov 2026 22:09:46 +0100 Subject: [PATCH 004/349] mxf: CinemaDNG in MXF (frame-wrapped DNG pictures), read and write The demuxer identifies CinemaDNG from the CinemaDNG container labels, the registered MXF-GC TIFF/EP container and picture coding labels, a 42h picture element type, or a TIFF header with the DNGVersion tag at the start of the essence. The writer produces OP1a files with frame-wrapped DNG pictures, the provisional container label, element type 42h and an RGBA descriptor (no coding label); OP-Atom is refused because it is clip-wrapped here. Same change as the crates/mxf part of storytold/Filmcraft#1078, ported onto craft-media. Co-Authored-By: Claude Sonnet 5.5 --- crates/media/README.md | 11 +++- crates/media/src/mxf/essence.rs | 81 ++++++++++++++++++++++++++-- crates/media/src/mxf/file.rs | 8 ++- crates/media/src/mxf/mod.rs | 5 +- crates/media/src/mxf/write.rs | 54 ++++++++++++++++--- crates/media/src/mxf/write/labels.rs | 4 ++ crates/media/src/mxf/write/tests.rs | 50 +++++++++++++++++ 7 files changed, 198 insertions(+), 15 deletions(-) diff --git a/crates/media/README.md b/crates/media/README.md index 387ab8cdd..48c930d1b 100644 --- a/crates/media/README.md +++ b/crates/media/README.md @@ -614,6 +614,7 @@ Implemented from the SMPTE documents (editions used): | SMPTE ST 386 | 2004 | D-10 (IMX) mapping: container label, sound element type | | SMPTE ST 2019-4 | 2009 | VC-3 (DNxHD / DNxHR) mapping | | SMPTE RDD 44 | 2017 | Apple ProRes mapping | +| Adobe CinemaDNG Image Data Format Specification | 1.0.0.0 (September 2009), §7 | CinemaDNG in MXF: frame-wrapped DNG picture elements (element type 42h), the essence container labels for CFA / LinearRaw content, RGBA descriptor; the labels are the specification's **provisional** values from Adobe's experimental range (byte 9 = 0Fh), not SMPTE-registered | | SMPTE RP 224 / RP 210 | registers | labels: data definitions, picture coding, essence containers, operational patterns; property labels of the primer pack (writer) | | SMPTE ST 330 | 2011 | basic UMIDs of the written packages | @@ -655,7 +656,10 @@ let pcm = mxf.read_pcm(&file, a, 48_000, 1920)?; // planar f32, sample-exact orders by the bitstream (the AVC picture order counts). - **Codecs.** From the picture essence coding label, then the essence container label, then the essence bytes: AVC / AVC-Intra, VC-3, ProRes (profile from the label), MPEG-2, - MPEG-4 visual, JPEG 2000, DV, uncompressed. + MPEG-4 visual, JPEG 2000, DV, uncompressed, CinemaDNG (the CinemaDNG container labels, the + registered MXF-GC TIFF/EP container and TIFF/EP picture coding labels, a 42h picture element + type, or a TIFF header with the DNGVersion tag at the start of the essence; the DNG pictures + themselves are developed by `craft-raw`). - **Sound.** PCM chunks (frame- or clip-wrapped) with sample counts; `read_pcm` decodes little-endian 8/16/24/32-bit PCM (wave / AES3 descriptors) and ST 331 AES3 elements (D-10). - **Timecode.** The material package timecode component (start frame count, rounded base, @@ -728,7 +732,10 @@ w.finish()?; element types 0x0C / 0x0D), ProRes (RDD 44: coding label profile byte, container `02 1C`), AVC byte stream (ST 381-3: container `02 10 60`, coding label from `profile_idc`; Annex B access units with in-band SPS / PPS — the AVC sub-descriptor is not written), Broadcast Wave PCM - (ST 382: container `02 06 01/02`, element types 0x01 / 0x02). + (ST 382: container `02 06 01/02`, element types 0x01 / 0x02), CinemaDNG (frame-wrapped DNG + datasets, element type 0x42, the provisional container label `0F 0A 0D 0B 02 7F 01/02 00`, an + RGBA descriptor with pixel layout and reference levels of the decoded 16-bit RGB picture and no + coding label; OP-Atom is refused because it is clip-wrapped here and DNG datasets cannot be). - `write_opatom_pcm(&OpAtomPcm, &[i32])` builds a complete in-memory OP-Atom PCM file (AAF media consolidation); `encode_pcm` interleaves planar f32 as little-endian PCM. diff --git a/crates/media/src/mxf/essence.rs b/crates/media/src/mxf/essence.rs index 27f893dc5..2c0d1ef7e 100644 --- a/crates/media/src/mxf/essence.rs +++ b/crates/media/src/mxf/essence.rs @@ -27,6 +27,9 @@ pub enum Codec { Dv, /// Uncompressed pictures (ST 384). Uncompressed, + /// CinemaDNG: one DNG (TIFF) dataset per frame-wrapped picture element (CinemaDNG Image Data + /// Format Specification §7), or TIFF/EP pictures under the registered MXF-GC TIFF/EP labels. + CinemaDng, /// Linear PCM, little-endian (Broadcast Wave and AES3 descriptors, ST 382). Pcm, /// 8-channel AES3 element data (ST 331, D-10 sound). @@ -46,13 +49,14 @@ impl Codec { Codec::Jpeg2000 => "JPEG 2000", Codec::Dv => "DV", Codec::Uncompressed => "Uncompressed", + Codec::CinemaDng => "CinemaDNG", Codec::Pcm => "PCM", Codec::Aes3Element => "AES3 PCM", Codec::Unknown => "unknown", } } /// The crate-wide identifier: VC-3 is [`CodecId::Dnxhd`], PCM and AES3 element data are - /// [`CodecId::Pcm`]; JPEG 2000, DV and uncompressed pictures have no identifier. + /// [`CodecId::Pcm`]; JPEG 2000, DV, uncompressed and CinemaDNG pictures have no identifier. /// /// [`CodecId::Dnxhd`]: crate::CodecId::Dnxhd /// [`CodecId::Pcm`]: crate::CodecId::Pcm @@ -65,15 +69,35 @@ impl Codec { Codec::Mpeg2 => Id::Mpeg2Video, Codec::Mpeg4Visual => Id::Mpeg4Video, Codec::Pcm | Codec::Aes3Element => Id::Pcm, - Codec::Jpeg2000 | Codec::Dv | Codec::Uncompressed | Codec::Unknown => Id::Unknown, + Codec::Jpeg2000 | Codec::Dv | Codec::Uncompressed | Codec::CinemaDng | Codec::Unknown => Id::Unknown, } } /// Every picture is coded independently. pub fn intra_only(&self) -> bool { - matches!(self, Codec::Avc { intra: true } | Codec::Vc3 | Codec::ProRes { .. } | Codec::Jpeg2000 | Codec::Dv | Codec::Uncompressed) + matches!( + self, + Codec::Avc { intra: true } | Codec::Vc3 | Codec::ProRes { .. } | Codec::Jpeg2000 | Codec::Dv | Codec::Uncompressed | Codec::CinemaDng + ) } } +/// The CinemaDNG essence container labels (CinemaDNG Image Data Format Specification 1.0.0.0, +/// §7.2.1): provisional, unregistered labels from Adobe's experimental range (byte 9 = 0F h), +/// `…0F 0A 0D 0B 02 7F cc 00` with content kind `cc` 01 (CFA) or 02 (LinearRaw). +pub const CINEMADNG_CONTAINER_PREFIX: [u8; 6] = [0x0F, 0x0A, 0x0D, 0x0B, 0x02, 0x7F]; + +/// Element type (byte 15 of the picture element key) of a frame-wrapped CinemaDNG picture: the +/// "TIFF" type of ST 331 (CinemaDNG specification §7.1.1.2). +pub const CINEMADNG_ELEMENT_TYPE: u8 = 0x42; + +/// Whether `ul` is a CinemaDNG essence container label (CFA or LinearRaw content), or the +/// registered MXF-GC TIFF/EP container (`…0D 01 03 01 02 14 ww 00`, RP 224). +pub fn is_cinemadng_container(ul: &Ul) -> bool { + ul.is_smpte() + && (ul.item_starts_with(&CINEMADNG_CONTAINER_PREFIX) && matches!(ul.0[14], 0x01 | 0x02) + || ul.item_starts_with(&[0x0D, 0x01, 0x03, 0x01, 0x02, 0x14])) +} + /// Identify a picture codec from the picture essence coding label and the essence container label. pub fn identify_picture(coding: Option
    , container: Option
      , mpeg_descriptor: bool) -> Codec { if let Some(c) = coding.filter(Ul::is_smpte) { @@ -81,6 +105,9 @@ pub fn identify_picture(coding: Option
        , container: Option
          , mpeg_descript // 04 01 02 02 .. : compressed picture coding if b[8..12] == [0x04, 0x01, 0x02, 0x02] { match (b[12], b[13]) { + // TIFF/EP Profile 2 picture coding (RP 224: 03 02 01 01 uncompressed CFA … 04 + // compressed LinearRaw), the coding of DNG pictures + (0x03, 0x02) if b[14] == 0x01 => return Codec::CinemaDng, // 01: MPEG compression (ISO/IEC 13818-2 profiles, 14496-2, 14496-10) (0x01, 0x01..=0x1F) => return Codec::Mpeg2, (0x01, 0x20..=0x2F) => return Codec::Mpeg4Visual, @@ -99,6 +126,9 @@ pub fn identify_picture(coding: Option
            , container: Option
              , mpeg_descript return Codec::Uncompressed; } } + if container.is_some_and(|c| is_cinemadng_container(&c)) { + return Codec::CinemaDng; + } if let Some(c) = container.filter(Ul::is_smpte) && c.item_starts_with(&[0x0D, 0x01, 0x03, 0x01, 0x02]) { @@ -117,8 +147,30 @@ pub fn identify_picture(coding: Option
                , container: Option
                  , mpeg_descript if mpeg_descriptor { Codec::Mpeg2 } else { Codec::Unknown } } +/// DNG evidence in the leading bytes of a TIFF: a TIFF 6.0 §2 header whose first IFD, when it lies +/// within `b`, holds the DNGVersion tag (DNG 1.x §2, tag 50706). A plain TIFF has no such tag. +fn is_dng(b: &[u8]) -> bool { + let le = match b.get(..4) { + Some(h) if h == b"II*\0" => true, + Some(h) if h == b"MM\0*" => false, + _ => return false, + }; + let u16_at = |o: usize| b.get(o..o + 2).map(|v| if le { u16::from_le_bytes([v[0], v[1]]) } else { u16::from_be_bytes([v[0], v[1]]) }); + let Some(ifd) = b.get(4..8).map(|v| if le { u32::from_le_bytes([v[0], v[1], v[2], v[3]]) } else { u32::from_be_bytes([v[0], v[1], v[2], v[3]]) }) + else { + return false; + }; + let Some(count) = usize::try_from(ifd).ok().and_then(|o| u16_at(o).map(|n| (o, n))) else { + return false; + }; + (0..usize::from(count.1)).any(|i| u16_at(count.0 + 2 + i * 12) == Some(50706)) +} + /// Identify a picture codec from the first bytes of an essence element. pub fn sniff_picture(b: &[u8]) -> Option { + if is_dng(b) { + return Some(Codec::CinemaDng); + } if b.len() >= 8 && &b[4..8] == b"icpf" { return Some(Codec::ProRes { profile: None }); } @@ -367,6 +419,20 @@ mod tests { assert_eq!(identify_picture(None, None, false), Codec::Unknown); } + #[test] + fn identifies_cinemadng() { + // CinemaDNG specification §7.2.1: CFA and LinearRaw containers (any registry version byte) + let adobe = |kind: u8| Ul([0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x0F, 0x0A, 0x0D, 0x0B, 0x02, 0x7F, kind, 0x00]); + assert_eq!(identify_picture(None, Some(adobe(1)), false), Codec::CinemaDng); + assert_eq!(identify_picture(None, Some(adobe(2)), false), Codec::CinemaDng); + assert_eq!(identify_picture(None, Some(adobe(3)), false), Codec::Unknown); + // RP 224: MXF-GC frame-wrapped TIFF/EP container, TIFF/EP picture coding + assert_eq!(identify_picture(None, Some(ul(&[0x0D, 1, 3, 1, 2, 0x14, 1])), false), Codec::CinemaDng); + assert_eq!(identify_picture(Some(ul(&[4, 1, 2, 2, 3, 2, 1, 3])), None, false), Codec::CinemaDng); + assert!(Codec::CinemaDng.intra_only()); + assert_eq!(Codec::CinemaDng.name(), "CinemaDNG"); + } + #[test] fn sniffs_essence() { assert_eq!(sniff_picture(&[0, 0, 0, 1, 0x09, 0x10]), Some(Codec::Avc { intra: false })); @@ -374,6 +440,15 @@ mod tests { assert_eq!(sniff_picture(&[0, 0, 2, 0x80, 1]), Some(Codec::Vc3)); assert_eq!(sniff_picture(&[0, 0, 0, 9, b'i', b'c', b'p', b'f']), Some(Codec::ProRes { profile: None })); assert_eq!(sniff_picture(&[1, 2, 3]), None); + // a TIFF header alone is not DNG; an IFD0 with the DNGVersion tag (50706 = 0xC612) is + let tiff_le = |tag: u16| [b"II*\0\x08\0\0\0\x01\0".as_slice(), &tag.to_le_bytes(), &[1, 0, 4, 0, 0, 0, 1, 4, 0, 0], &[0; 8]].concat(); + let tiff_be = |tag: u16| [b"MM\0*\0\0\0\x08\0\x01".as_slice(), &tag.to_be_bytes(), &[0, 1, 0, 0, 0, 4, 1, 4, 0, 0], &[0; 8]].concat(); + assert_eq!(sniff_picture(&tiff_le(0xC612)), Some(Codec::CinemaDng)); + assert_eq!(sniff_picture(&tiff_be(0xC612)), Some(Codec::CinemaDng)); + assert_eq!(sniff_picture(&tiff_le(0x0100)), None); + assert_eq!(sniff_picture(&tiff_be(0x0100)), None); + assert_eq!(sniff_picture(b"II*\0\x08\0\0\0"), None); + assert_eq!(sniff_picture(b"II*\0"), None); } #[test] diff --git a/crates/media/src/mxf/file.rs b/crates/media/src/mxf/file.rs index 15d847c7d..9064bcb83 100644 --- a/crates/media/src/mxf/file.rs +++ b/crates/media/src/mxf/file.rs @@ -910,7 +910,7 @@ fn build_track( } // A wrong or missing label: trust the essence bytes. if let Some(first) = elements.first() { - let head = read_upto(src, first.value_offset, 64)?; + let head = read_upto(src, first.value_offset, 4096)?; if let Some(sniffed) = sniff_picture(&head) { let agree = std::mem::discriminant(&sniffed) == std::mem::discriminant(&codec); if !agree && !matches!(codec, Codec::Avc { intra: true }) { @@ -918,6 +918,12 @@ fn build_track( } } } + // CinemaDNG §7.1.1.2: a "TIFF" picture element type names DNG pictures + if codec == Codec::Unknown + && elements.first().is_some_and(|e| e.key.0[12] == 0x15 && e.key.0[14] == super::essence::CINEMADNG_ELEMENT_TYPE) + { + codec = Codec::CinemaDng; + } t.codec = codec; t.picture = Some(pi); build_pictures(src, &mut t, elements, index, warnings)?; diff --git a/crates/media/src/mxf/mod.rs b/crates/media/src/mxf/mod.rs index ca0e8f918..56de637c7 100644 --- a/crates/media/src/mxf/mod.rs +++ b/crates/media/src/mxf/mod.rs @@ -2,7 +2,8 @@ //! ST 377-1 (file format: KLV, partitions, primer pack, header metadata, index tables, random //! index pack), ST 378 (OP1a), ST 390 (OP-Atom), ST 379-1/2 (generic container), ST 381-1 (MPEG //! video mapping), ST 381-3 (AVC mapping), ST 382 (AES3 / Broadcast Wave audio mapping), ST 331 -//! (AES3 element data, D-10 sound), ST 2019-4 (VC-3 mapping) and RDD 44 (ProRes mapping). +//! (AES3 element data, D-10 sound), ST 2019-4 (VC-3 mapping), RDD 44 (ProRes mapping) and the CinemaDNG +//! specification's MXF mapping (frame-wrapped DNG pictures). //! //! [`open`] walks the file's KLV packets (keys and lengths only; essence payloads are never read //! while opening), parses the partition packs, the primer pack and header metadata of the most @@ -32,7 +33,7 @@ mod meta; pub mod write; pub use crate::source::{ByteSource, ReadSeekSource}; -pub use essence::{Codec, PictureInfo, SoundFormat, SoundInfo, aes3_element_samples, decode_pcm}; +pub use essence::{CINEMADNG_CONTAINER_PREFIX, CINEMADNG_ELEMENT_TYPE, Codec, PictureInfo, SoundFormat, SoundInfo, aes3_element_samples, decode_pcm}; pub use file::{Chunk, EssenceTrack, MxfFile, OperationalPattern, Partition, PartitionKind, Sample, Timecode, TrackKind, Wrapping, open}; pub use index::{IndexEntry, IndexSegment}; pub use klv::{Rational, Ul}; diff --git a/crates/media/src/mxf/write.rs b/crates/media/src/mxf/write.rs index 9fb6bfea2..42abf846f 100644 --- a/crates/media/src/mxf/write.rs +++ b/crates/media/src/mxf/write.rs @@ -107,6 +107,10 @@ pub enum PictureCoding { ProRes { profile: u8 }, /// H.264 / AVC Annex B byte stream; `profile_idc` from the SPS (66, 77, 100, …). Avc { profile_idc: u8, intra: bool }, + /// CinemaDNG: one DNG dataset per picture (CinemaDNG specification §7), frame-wrapped only, + /// with an RGBA descriptor of the decoded 16-bit RGB image. `linear_raw`: the pictures are + /// LinearRaw (PhotometricInterpretation 34892) rather than CFA (32803). + CinemaDng { linear_raw: bool }, } impl PictureCoding { @@ -116,9 +120,10 @@ impl PictureCoding { _ => true, } } - /// Picture essence coding label. - fn coding_label(&self) -> [u8; 16] { - match *self { + /// Picture essence coding label (None: CinemaDNG, which has no registered one, §7.2.2.2). + fn coding_label(&self) -> Option<[u8; 16]> { + Some(match *self { + PictureCoding::CinemaDng { .. } => return None, PictureCoding::Vc3 { cid } => { let code = if (1235..=1234 + 0x7F).contains(&cid) { (cid - 1234) as u8 } else { 0 }; [0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x0A, 0x04, 0x01, 0x02, 0x02, 0x71, code, 0x00, 0x00] @@ -145,7 +150,7 @@ impl PictureCoding { }; [0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x0A, 0x04, 0x01, 0x02, 0x02, 0x01, b13, b14, 0x01] } - } + }) } /// (essence container label, element type) for frame or clip wrapping. fn container(&self, clip: bool) -> ([u8; 16], u8) { @@ -154,6 +159,12 @@ impl PictureCoding { PictureCoding::Vc3 { .. } => (essence_container(0x0A, 0x11, w, 0x00), if clip { 0x0D } else { 0x0C }), PictureCoding::ProRes { .. } => (essence_container(0x0D, 0x1C, w, 0x00), if clip { 0x18 } else { 0x17 }), PictureCoding::Avc { .. } => (essence_container(0x0A, 0x10, 0x60, w), if clip { 0x16 } else { 0x15 }), + // CinemaDNG §7.2.1 (provisional label) and §7.1.1.2 (element type 42h); always frame + // wrapped (`MxfWriter::new` refuses clip wrapping) + PictureCoding::CinemaDng { linear_raw } => ( + [0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x0F, 0x0A, 0x0D, 0x0B, 0x02, 0x7F, if *linear_raw { 0x02 } else { 0x01 }, 0x00], + 0x42, + ), } } } @@ -202,6 +213,8 @@ impl PictureDesc { if matches!(cid, 1235 | 1241 | 1250 | 1256 | 1270 | 1271) { 10 } else { 8 }, if matches!(cid, 1256 | 1270) { (1, 1) } else { (2, 1) }, ), + // §7.2.2.3: the decoded image is described as 16 bits per component + PictureCoding::CinemaDng { .. } => (16, (1, 1)), }; PictureDesc { coding, @@ -589,6 +602,19 @@ impl MxfWriter { return Err(io::Error::new(io::ErrorKind::InvalidInput, "invalid PCM sound description")); } let clip = cfg.pattern == Pattern::OpAtom; + if clip && matches!(cfg.picture.as_ref().map(|p| p.coding), Some(PictureCoding::CinemaDng { .. })) { + // CinemaDNG §7.1.1: a TIFF dataset has no length field, so DNG pictures can't be clip wrapped + return Err(io::Error::new( + io::ErrorKind::InvalidInput, + "CinemaDNG pictures are frame wrapped only (this writer's OP-Atom is clip wrapped)", + )); + } + if let Some(p) = &cfg.picture { + // CinemaDNG §7.2.2.3 fixes the decoded image at 16 bits per component + if matches!(p.coding, PictureCoding::CinemaDng { .. }) && p.depth != 16 { + return Err(io::Error::new(io::ErrorKind::InvalidInput, "CinemaDNG pictures are described at 16 bits per component")); + } + } let mut tracks = Vec::new(); let mut id = cfg.first_track_id.max(2); if let Some(p) = &cfg.picture { @@ -985,7 +1011,8 @@ impl MxfWriter { TrackKind::Picture => { // Picture tracks exist only with a picture configuration. let Some(p) = cfg.picture.as_ref() else { continue }; - let mut s = Set::new(0x28, uid); + let rgba = matches!(p.coding, PictureCoding::CinemaDng { .. }); + let mut s = Set::new(if rgba { 0x29 } else { 0x28 }, uid); if multiple { s.u32(0x3006, t.id); } @@ -1020,8 +1047,21 @@ impl MxfWriter { // field dominance: the temporally first field (1 top, 2 bottom) s.u8(0x3212, if p.bottom_field_first { 2 } else { 1 }); } - s.p(0x3201, &p.coding.coding_label()) - .p(0x3210, &tcl) + if let Some(label) = p.coding.coding_label() { + s.p(0x3201, &label); + } + if rgba { + // RGBA descriptor (ST 377-1 G.2.40): pixel layout R, G, B of 16 bits each and + // the component reference levels. CinemaDNG §7.2.2.3 fixes the decoded + // image at 16 bits; `MxfWriter::new` rejects any other `PictureDesc::depth`. + let mut layout = [0u8; 16]; + layout[..6].copy_from_slice(&[b'R', 16, b'G', 16, b'B', 16]); + let max = u32::from(u16::MAX); + s.p(0x3401, &layout).u32(0x3406, max).u32(0x3407, 0); + s.write(&mut out); + continue; + } + s.p(0x3210, &tcl) .p(0x321A, &ce) .p(0x3219, &cp) .u32(0x3301, depth) diff --git a/crates/media/src/mxf/write/labels.rs b/crates/media/src/mxf/write/labels.rs index eb8fbc040..12f62c7fd 100644 --- a/crates/media/src/mxf/write/labels.rs +++ b/crates/media/src/mxf/write/labels.rs @@ -120,6 +120,10 @@ pub const PRIMER: &[(u16, [u8; 16])] = &[ (0x3304, ul(&[0x01, 0x01, 0x01, 0x01, 0x04, 0x01, 0x05, 0x03, 0x03])), (0x3305, ul(&[0x01, 0x01, 0x01, 0x01, 0x04, 0x01, 0x05, 0x03, 0x04])), (0x3306, ul(&[0x01, 0x01, 0x01, 0x02, 0x04, 0x01, 0x05, 0x03, 0x05])), + // RGBA picture essence descriptor (ST 377-1; RP 210): PixelLayout, ComponentMaxRef, ComponentMinRef + (0x3401, ul(&[0x01, 0x01, 0x01, 0x02, 0x04, 0x01, 0x05, 0x03, 0x06])), + (0x3406, ul(&[0x01, 0x01, 0x01, 0x05, 0x04, 0x01, 0x05, 0x03, 0x0B])), + (0x3407, ul(&[0x01, 0x01, 0x01, 0x05, 0x04, 0x01, 0x05, 0x03, 0x0C])), (0x3D03, ul(&[0x01, 0x01, 0x01, 0x05, 0x04, 0x02, 0x03, 0x01, 0x01, 0x01])), (0x3D02, ul(&[0x01, 0x01, 0x01, 0x04, 0x04, 0x02, 0x03, 0x01, 0x04])), (0x3D07, ul(&[0x01, 0x01, 0x01, 0x05, 0x04, 0x02, 0x01, 0x01, 0x04])), diff --git a/crates/media/src/mxf/write/tests.rs b/crates/media/src/mxf/write/tests.rs index 91574fec7..eac50a0e9 100644 --- a/crates/media/src/mxf/write/tests.rs +++ b/crates/media/src/mxf/write/tests.rs @@ -401,6 +401,56 @@ fn long_pcm_reads_backed_by_the_file_are_not_capped() { assert!(m.read_pcm(&f, 0, 0, frames + (1 << 24)).is_err()); } +/// A TIFF-headed stand-in for a DNG dataset (the demuxer only carries the bytes). +fn dng_like(i: usize) -> Vec { + let mut v = b"II*\0\x08\0\0\0".to_vec(); + v.extend(std::iter::repeat_n(i as u8 ^ 0x33, 300 + 11 * i)); + v +} + +#[test] +fn cinemadng_op1a_reads_back() { + for linear_raw in [false, true] { + let mut cfg = op1a_config(Rational::new(24, 1), PictureCoding::CinemaDng { linear_raw }); + cfg.sound.truncate(1); + let mut w = MxfWriter::new(Cursor::new(Vec::new()), cfg).unwrap(); + for i in 0..6 { + w.push_picture(&dng_like(i), FrameInfo::intra()).unwrap(); + w.push_sound(0, &pcm16(i * 2000, 2000)).unwrap(); + } + let f = w.finish().unwrap().into_inner(); + // CinemaDNG §7.1.1.2: picture element key 06.0E.2B.34.01.02.01.01.0D.01.03.01.15.01.42.01 + let key = [0x06, 0x0E, 0x2B, 0x34, 0x01, 0x02, 0x01, 0x01, 0x0D, 0x01, 0x03, 0x01, 0x15, 0x01, 0x42, 0x01]; + assert_eq!(f.windows(16).filter(|k| *k == key).count(), 6); + // §7.2.1: the essence container label of the content kind + let ec = [0x06, 0x0E, 0x2B, 0x34, 0x04, 0x01, 0x01, 0x01, 0x0F, 0x0A, 0x0D, 0x0B, 0x02, 0x7F, if linear_raw { 2 } else { 1 }, 0x00]; + assert!(f.windows(16).any(|k| k == ec)); + let m = open(&f).unwrap(); + assert!(m.warnings.is_empty(), "{:?}", m.warnings); + let v = m.track_of_kind(TrackKind::Picture).unwrap(); + let t = &m.tracks[v]; + assert_eq!(t.codec, Codec::CinemaDng); + assert_eq!(t.wrapping, Wrapping::Frame); + assert_eq!(t.samples.len(), 6); + let p = t.picture.as_ref().unwrap(); + assert!(p.rgba, "RGBA picture essence descriptor (§7.2.2)"); + assert_eq!((p.frame_width(), p.frame_height()), (64, 36)); + assert!(p.picture_coding.is_none()); + for i in 0..6 { + assert!(t.samples[i].key); + assert_eq!(m.read_sample(&f, v, i).unwrap(), dng_like(i)); + } + assert_eq!(m.timecode.unwrap().format(), "01:02:30:00"); + } +} + +#[test] +fn cinemadng_is_never_clip_wrapped() { + let mut cfg = WriterConfig::new(Pattern::OpAtom, Rational::new(24, 1), PackageIds::from_seed("t", "T")); + cfg.picture = Some(PictureDesc::new(PictureCoding::CinemaDng { linear_raw: false }, 64, 36)); + assert!(MxfWriter::new(Cursor::new(Vec::new()), cfg).is_err()); +} + /// One `push_sound` of a long clip must not cost more than the clip itself: draining the buffered /// PCM from the front for every edit unit made this quadratic (about 16 s for 10 minutes). #[test] From 9541787aa9666adeb71abf3d8c05ef28316178dc Mon Sep 17 00:00:00 2001 From: vangel76 Date: Thu, 12 Nov 2026 22:17:58 +0100 Subject: [PATCH 005/349] hevc: simplify scaling-list condition for clippy nonminimal_bool Co-Authored-By: Claude Sonnet 5.5 --- crates/video/src/hevc/decode/slicedec/transform_tree.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/video/src/hevc/decode/slicedec/transform_tree.rs b/crates/video/src/hevc/decode/slicedec/transform_tree.rs index aa099a957..1ffaebbff 100644 --- a/crates/video/src/hevc/decode/slicedec/transform_tree.rs +++ b/crates/video/src/hevc/decode/slicedec/transform_tree.rs @@ -417,7 +417,7 @@ impl<'a, S: Sample> SliceDecoder<'a, S> { let round = 1i64 << (bd_shift - 1); let scale = (LEVEL_SCALE[(qp % 6) as usize] as i64) << (qp / 6); let matrix = match &self.pic.scaling { - Some(s) if !bypass && !(ts && n > 4) => { + Some(s) if !(bypass || (ts && n > 4)) => { let size_id = (log2 - 2) as usize; let matrix_id = if self.cu_intra { c } else { 3 + c }; Some((s.clone(), size_id * 6 + matrix_id)) From 756def2bc6211909afcd894fc6c10c55c695d42c Mon Sep 17 00:00:00 2001 From: vangel76 Date: Thu, 12 Nov 2026 23:18:51 +0100 Subject: [PATCH 006/349] mxf: checked end offset for the TIFF u16 read in DNG sniffing Co-Authored-By: Claude Sonnet 5.5 --- crates/media/src/mxf/essence.rs | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/crates/media/src/mxf/essence.rs b/crates/media/src/mxf/essence.rs index 2c0d1ef7e..74818e0e8 100644 --- a/crates/media/src/mxf/essence.rs +++ b/crates/media/src/mxf/essence.rs @@ -147,6 +147,14 @@ pub fn identify_picture(coding: Option
                    , container: Option
                      , mpeg_descript if mpeg_descriptor { Codec::Mpeg2 } else { Codec::Unknown } } +/// Read a TIFF `u16` at offset `o`. The end offset is computed with checked arithmetic, so an +/// untrusted offset near `usize::MAX` (a 32-bit target with IFD offset `0xFFFF_FFFF`) is +/// out of bounds instead of overflowing. +fn tiff_u16(b: &[u8], le: bool, o: usize) -> Option { + let v = b.get(o..o.checked_add(2)?)?; + Some(if le { u16::from_le_bytes([v[0], v[1]]) } else { u16::from_be_bytes([v[0], v[1]]) }) +} + /// DNG evidence in the leading bytes of a TIFF: a TIFF 6.0 §2 header whose first IFD, when it lies /// within `b`, holds the DNGVersion tag (DNG 1.x §2, tag 50706). A plain TIFF has no such tag. fn is_dng(b: &[u8]) -> bool { @@ -155,7 +163,7 @@ fn is_dng(b: &[u8]) -> bool { Some(h) if h == b"MM\0*" => false, _ => return false, }; - let u16_at = |o: usize| b.get(o..o + 2).map(|v| if le { u16::from_le_bytes([v[0], v[1]]) } else { u16::from_be_bytes([v[0], v[1]]) }); + let u16_at = |o: usize| tiff_u16(b, le, o); let Some(ifd) = b.get(4..8).map(|v| if le { u32::from_le_bytes([v[0], v[1], v[2], v[3]]) } else { u32::from_be_bytes([v[0], v[1], v[2], v[3]]) }) else { return false; @@ -419,6 +427,15 @@ mod tests { assert_eq!(identify_picture(None, None, false), Codec::Unknown); } + #[test] + fn tiff_offset_near_usize_max_is_out_of_bounds() { + let b = [0x49, 0x49, 0x2A, 0x00, 0xFF, 0xFF, 0xFF, 0xFF]; + assert_eq!(tiff_u16(&b, true, usize::MAX), None); + assert_eq!(tiff_u16(&b, true, usize::MAX - 1), None); + assert_eq!(tiff_u16(&b, true, 0), Some(0x4949)); + assert!(!is_dng(&b)); + } + #[test] fn identifies_cinemadng() { // CinemaDNG specification §7.2.1: CFA and LinearRaw containers (any registry version byte) From 1bdaa7aff32035ca09a178d296b082a53366b3b7 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 23:23:02 -0500 Subject: [PATCH 007/349] craft-xlsx: the XLSB function table, with the numbers 0x17C-0x1E4 (port of gridcraft#3810) [MS-XLSB]'s Ftab (2.5.98.10) continues the [MS-XLS] table from 0x17C: the cube functions, the old Analysis ToolPak functions, IFERROR, COUNTIFS, SUMIFS and AVERAGEIF(S). Excel writes these by number in .xlsb (PtgFunc / PtgFuncVar) where .xls calls them by name, so an XLSB formula decoder needs them. Generated from the spec with the same argument-count rule as the existing entries. Ported from storytold/gridcraft#3810 (issue gridcraft#3806). There the entries were appended to GridCraft's .xls table, which is now craft-xls's. Here the table is craft-xlsx's own (xlsb/ftab.rs): craft-xls's 0-379, which match GridCraft's table before the PR, then the PR's entries. The two formats follow separate specifications and develop separately; they can share a table later if both readers settle on one. The PR's table checks come along. Its decoding checks (IFERROR, SUMIFS by number) go with the decoder in the next commit, and its check that every new name is a GridCraft function stays in GridCraft. --- crates/xlsx/src/xlsb.rs | 2 + crates/xlsx/src/xlsb/ftab.rs | 516 +++++++++++++++++++++++++++++++++++ 2 files changed, 518 insertions(+) create mode 100644 crates/xlsx/src/xlsb/ftab.rs diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index dbff61dd7..542fd580c 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -2,6 +2,8 @@ //! their records. Saved values only: formulas are token streams that are not decoded, and //! styles are not read. A record that does not parse fails the read. +mod ftab; + use std::sync::Arc; use craft_opc::{ContentTypes, Rels}; diff --git a/crates/xlsx/src/xlsb/ftab.rs b/crates/xlsx/src/xlsb/ftab.rs new file mode 100644 index 000000000..c6b59092a --- /dev/null +++ b/crates/xlsx/src/xlsb/ftab.rs @@ -0,0 +1,516 @@ +//! The XLSB function table ([MS-XLSB] 2.5.98.10, `Ftab`): the functions a `PtgFunc` or +//! `PtgFuncVar` token calls by number. Up to 379 (0x17B) it is the table of [MS-XLS] 2.5.198.17, +//! which craft-xls also carries. The entries from 380 (0x17C) on are the rest of the XLSB table: +//! XLSB files call these functions by number, where `.xls` files call them by name. Kept apart from +//! craft-xls's copy: the two formats follow separate specifications. + +/// (iftab, name, fixed argument count or -1 when the function takes a variable number of +/// arguments), sorted by number. +const FTAB: &[(u16, &str, i8)] = &[ + (0, "COUNT", -1), + (1, "IF", -1), + (2, "ISNA", 1), + (3, "ISERROR", 1), + (4, "SUM", -1), + (5, "AVERAGE", -1), + (6, "MIN", -1), + (7, "MAX", -1), + (8, "ROW", -1), + (9, "COLUMN", -1), + (10, "NA", 0), + (11, "NPV", -1), + (12, "STDEV", -1), + (13, "DOLLAR", -1), + (14, "FIXED", -1), + (15, "SIN", 1), + (16, "COS", 1), + (17, "TAN", 1), + (18, "ATAN", 1), + (19, "PI", 0), + (20, "SQRT", 1), + (21, "EXP", 1), + (22, "LN", 1), + (23, "LOG10", 1), + (24, "ABS", 1), + (25, "INT", 1), + (26, "SIGN", 1), + (27, "ROUND", 2), + (28, "LOOKUP", -1), + (29, "INDEX", -1), + (30, "REPT", 2), + (31, "MID", 3), + (32, "LEN", 1), + (33, "VALUE", 1), + (34, "TRUE", 0), + (35, "FALSE", 0), + (36, "AND", -1), + (37, "OR", -1), + (38, "NOT", 1), + (39, "MOD", 2), + (40, "DCOUNT", 3), + (41, "DSUM", 3), + (42, "DAVERAGE", 3), + (43, "DMIN", 3), + (44, "DMAX", 3), + (45, "DSTDEV", 3), + (46, "VAR", -1), + (47, "DVAR", 3), + (48, "TEXT", 2), + (49, "LINEST", -1), + (50, "TREND", -1), + (51, "LOGEST", -1), + (52, "GROWTH", -1), + (53, "GOTO", 1), + (54, "HALT", -1), + (55, "RETURN", -1), + (56, "PV", -1), + (57, "FV", -1), + (58, "NPER", -1), + (59, "PMT", -1), + (60, "RATE", -1), + (61, "MIRR", 3), + (62, "IRR", -1), + (63, "RAND", 0), + (64, "MATCH", -1), + (65, "DATE", 3), + (66, "TIME", 3), + (67, "DAY", 1), + (68, "MONTH", 1), + (69, "YEAR", 1), + (70, "WEEKDAY", -1), + (71, "HOUR", 1), + (72, "MINUTE", 1), + (73, "SECOND", 1), + (74, "NOW", 0), + (75, "AREAS", 1), + (76, "ROWS", 1), + (77, "COLUMNS", 1), + (78, "OFFSET", -1), + (79, "ABSREF", 2), + (80, "RELREF", 2), + (81, "ARGUMENT", -1), + (82, "SEARCH", -1), + (83, "TRANSPOSE", 1), + (84, "ERROR", -1), + (85, "STEP", 0), + (86, "TYPE", 1), + (87, "ECHO", -1), + (88, "SET.NAME", -1), + (89, "CALLER", 0), + (90, "DEREF", 1), + (91, "WINDOWS", -1), + (92, "SERIES", -1), + (93, "DOCUMENTS", -1), + (94, "ACTIVE.CELL", 0), + (95, "SELECTION", 0), + (96, "RESULT", -1), + (97, "ATAN2", 2), + (98, "ASIN", 1), + (99, "ACOS", 1), + (100, "CHOOSE", -1), + (101, "HLOOKUP", -1), + (102, "VLOOKUP", -1), + (103, "LINKS", -1), + (104, "INPUT", -1), + (105, "ISREF", 1), + (106, "GET.FORMULA", 1), + (107, "GET.NAME", -1), + (108, "SET.VALUE", 2), + (109, "LOG", -1), + (110, "EXEC", -1), + (111, "CHAR", 1), + (112, "LOWER", 1), + (113, "UPPER", 1), + (114, "PROPER", 1), + (115, "LEFT", -1), + (116, "RIGHT", -1), + (117, "EXACT", 2), + (118, "TRIM", 1), + (119, "REPLACE", 4), + (120, "SUBSTITUTE", -1), + (121, "CODE", 1), + (122, "NAMES", -1), + (123, "DIRECTORY", -1), + (124, "FIND", -1), + (125, "CELL", -1), + (126, "ISERR", 1), + (127, "ISTEXT", 1), + (128, "ISNUMBER", 1), + (129, "ISBLANK", 1), + (130, "T", 1), + (131, "N", 1), + (132, "FOPEN", -1), + (133, "FCLOSE", 1), + (134, "FSIZE", 1), + (135, "FREADLN", 1), + (136, "FREAD", 2), + (137, "FWRITELN", 2), + (138, "FWRITE", 2), + (139, "FPOS", -1), + (140, "DATEVALUE", 1), + (141, "TIMEVALUE", 1), + (142, "SLN", 3), + (143, "SYD", 4), + (144, "DDB", -1), + (145, "GET.DEF", -1), + (146, "REFTEXT", -1), + (147, "TEXTREF", -1), + (148, "INDIRECT", -1), + (149, "REGISTER", -1), + (150, "CALL", -1), + (151, "ADD.BAR", -1), + (152, "ADD.MENU", -1), + (153, "ADD.COMMAND", -1), + (154, "ENABLE.COMMAND", -1), + (155, "CHECK.COMMAND", -1), + (156, "RENAME.COMMAND", -1), + (157, "SHOW.BAR", -1), + (158, "DELETE.MENU", -1), + (159, "DELETE.COMMAND", -1), + (160, "GET.CHART.ITEM", -1), + (161, "DIALOG.BOX", 1), + (162, "CLEAN", 1), + (163, "MDETERM", 1), + (164, "MINVERSE", 1), + (165, "MMULT", 2), + (166, "FILES", -1), + (167, "IPMT", -1), + (168, "PPMT", -1), + (169, "COUNTA", -1), + (170, "CANCEL.KEY", -1), + (171, "FOR", -1), + (172, "WHILE", 1), + (173, "BREAK", 0), + (174, "NEXT", 0), + (175, "INITIATE", 2), + (176, "REQUEST", 2), + (177, "POKE", 3), + (178, "EXECUTE", 2), + (179, "TERMINATE", 1), + (180, "RESTART", -1), + (181, "HELP", -1), + (182, "GET.BAR", -1), + (183, "PRODUCT", -1), + (184, "FACT", 1), + (185, "GET.CELL", -1), + (186, "GET.WORKSPACE", 1), + (187, "GET.WINDOW", -1), + (188, "GET.DOCUMENT", -1), + (189, "DPRODUCT", 3), + (190, "ISNONTEXT", 1), + (191, "GET.NOTE", -1), + (192, "NOTE", -1), + (193, "STDEVP", -1), + (194, "VARP", -1), + (195, "DSTDEVP", 3), + (196, "DVARP", 3), + (197, "TRUNC", -1), + (198, "ISLOGICAL", 1), + (199, "DCOUNTA", 3), + (200, "DELETE.BAR", 1), + (201, "UNREGISTER", 1), + (204, "USDOLLAR", -1), + (205, "FINDB", -1), + (206, "SEARCHB", -1), + (207, "REPLACEB", 4), + (208, "LEFTB", -1), + (209, "RIGHTB", -1), + (210, "MIDB", 3), + (211, "LENB", 1), + (212, "ROUNDUP", 2), + (213, "ROUNDDOWN", 2), + (214, "ASC", 1), + (215, "DBCS", 1), + (216, "RANK", -1), + (219, "ADDRESS", -1), + (220, "DAYS360", -1), + (221, "TODAY", 0), + (222, "VDB", -1), + (223, "ELSE", 0), + (224, "ELSE.IF", 1), + (225, "END.IF", 0), + (226, "FOR.CELL", -1), + (227, "MEDIAN", -1), + (228, "SUMPRODUCT", -1), + (229, "SINH", 1), + (230, "COSH", 1), + (231, "TANH", 1), + (232, "ASINH", 1), + (233, "ACOSH", 1), + (234, "ATANH", 1), + (235, "DGET", 3), + (236, "CREATE.OBJECT", -1), + (237, "VOLATILE", -1), + (238, "LAST.ERROR", 0), + (239, "CUSTOM.UNDO", -1), + (240, "CUSTOM.REPEAT", -1), + (241, "FORMULA.CONVERT", -1), + (242, "GET.LINK.INFO", -1), + (243, "TEXT.BOX", -1), + (244, "INFO", 1), + (245, "GROUP", 0), + (246, "GET.OBJECT", -1), + (247, "DB", -1), + (248, "PAUSE", -1), + (251, "RESUME", -1), + (252, "FREQUENCY", 2), + (253, "ADD.TOOLBAR", -1), + (254, "DELETE.TOOLBAR", 1), + (256, "RESET.TOOLBAR", 1), + (257, "EVALUATE", 1), + (258, "GET.TOOLBAR", -1), + (259, "GET.TOOL", -1), + (260, "SPELLING.CHECK", -1), + (261, "ERROR.TYPE", 1), + (262, "APP.TITLE", -1), + (263, "WINDOW.TITLE", -1), + (264, "SAVE.TOOLBAR", -1), + (265, "ENABLE.TOOL", 3), + (266, "PRESS.TOOL", 3), + (267, "REGISTER.ID", -1), + (268, "GET.WORKBOOK", -1), + (269, "AVEDEV", -1), + (270, "BETADIST", -1), + (271, "GAMMALN", 1), + (272, "BETAINV", -1), + (273, "BINOMDIST", 4), + (274, "CHIDIST", 2), + (275, "CHIINV", 2), + (276, "COMBIN", 2), + (277, "CONFIDENCE", 3), + (278, "CRITBINOM", 3), + (279, "EVEN", 1), + (280, "EXPONDIST", 3), + (281, "FDIST", 3), + (282, "FINV", 3), + (283, "FISHER", 1), + (284, "FISHERINV", 1), + (285, "FLOOR", 2), + (286, "GAMMADIST", 4), + (287, "GAMMAINV", 3), + (288, "CEILING", 2), + (289, "HYPGEOMDIST", 4), + (290, "LOGNORMDIST", 3), + (291, "LOGINV", 3), + (292, "NEGBINOMDIST", 3), + (293, "NORMDIST", 4), + (294, "NORMSDIST", 1), + (295, "NORMINV", 3), + (296, "NORMSINV", 1), + (297, "STANDARDIZE", 3), + (298, "ODD", 1), + (299, "PERMUT", 2), + (300, "POISSON", 3), + (301, "TDIST", 3), + (302, "WEIBULL", 4), + (303, "SUMXMY2", 2), + (304, "SUMX2MY2", 2), + (305, "SUMX2PY2", 2), + (306, "CHITEST", 2), + (307, "CORREL", 2), + (308, "COVAR", 2), + (309, "FORECAST", 3), + (310, "FTEST", 2), + (311, "INTERCEPT", 2), + (312, "PEARSON", 2), + (313, "RSQ", 2), + (314, "STEYX", 2), + (315, "SLOPE", 2), + (316, "TTEST", 4), + (317, "PROB", -1), + (318, "DEVSQ", -1), + (319, "GEOMEAN", -1), + (320, "HARMEAN", -1), + (321, "SUMSQ", -1), + (322, "KURT", -1), + (323, "SKEW", -1), + (324, "ZTEST", -1), + (325, "LARGE", 2), + (326, "SMALL", 2), + (327, "QUARTILE", 2), + (328, "PERCENTILE", 2), + (329, "PERCENTRANK", -1), + (330, "MODE", -1), + (331, "TRIMMEAN", 2), + (332, "TINV", 2), + (334, "MOVIE.COMMAND", -1), + (335, "GET.MOVIE", -1), + (336, "CONCATENATE", -1), + (337, "POWER", 2), + (338, "PIVOT.ADD.DATA", -1), + (339, "GET.PIVOT.TABLE", -1), + (340, "GET.PIVOT.FIELD", -1), + (341, "GET.PIVOT.ITEM", -1), + (342, "RADIANS", 1), + (343, "DEGREES", 1), + (344, "SUBTOTAL", -1), + (345, "SUMIF", -1), + (346, "COUNTIF", 2), + (347, "COUNTBLANK", 1), + (348, "SCENARIO.GET", -1), + (349, "OPTIONS.LISTS.GET", 1), + (350, "ISPMT", 4), + (351, "DATEDIF", 3), + (352, "DATESTRING", 1), + (353, "NUMBERSTRING", 2), + (354, "ROMAN", -1), + (355, "OPEN.DIALOG", -1), + (356, "SAVE.DIALOG", -1), + (357, "VIEW.GET", -1), + (358, "GETPIVOTDATA", -1), + (359, "HYPERLINK", -1), + (360, "PHONETIC", 1), + (361, "AVERAGEA", -1), + (362, "MAXA", -1), + (363, "MINA", -1), + (364, "STDEVPA", -1), + (365, "VARPA", -1), + (366, "STDEVA", -1), + (367, "VARA", -1), + (368, "BAHTTEXT", 1), + (369, "THAIDAYOFWEEK", 1), + (370, "THAIDIGIT", 1), + (371, "THAIMONTHOFYEAR", 1), + (372, "THAINUMSOUND", 1), + (373, "THAINUMSTRING", 1), + (374, "THAISTRINGLENGTH", 1), + (375, "ISTHAIDIGIT", 1), + (376, "ROUNDBAHTDOWN", 1), + (377, "ROUNDBAHTUP", 1), + (378, "THAIYEAR", 1), + (379, "RTD", -1), + (380, "CUBEVALUE", -1), + (381, "CUBEMEMBER", -1), + (382, "CUBEMEMBERPROPERTY", 3), + (383, "CUBERANKEDMEMBER", -1), + (384, "HEX2BIN", -1), + (385, "HEX2DEC", 1), + (386, "HEX2OCT", -1), + (387, "DEC2BIN", -1), + (388, "DEC2HEX", -1), + (389, "DEC2OCT", -1), + (390, "OCT2BIN", -1), + (391, "OCT2HEX", -1), + (392, "OCT2DEC", 1), + (393, "BIN2DEC", 1), + (394, "BIN2OCT", -1), + (395, "BIN2HEX", -1), + (396, "IMSUB", 2), + (397, "IMDIV", 2), + (398, "IMPOWER", 2), + (399, "IMABS", 1), + (400, "IMSQRT", 1), + (401, "IMLN", 1), + (402, "IMLOG2", 1), + (403, "IMLOG10", 1), + (404, "IMSIN", 1), + (405, "IMCOS", 1), + (406, "IMEXP", 1), + (407, "IMARGUMENT", 1), + (408, "IMCONJUGATE", 1), + (409, "IMAGINARY", 1), + (410, "IMREAL", 1), + (411, "COMPLEX", -1), + (412, "IMSUM", -1), + (413, "IMPRODUCT", -1), + (414, "SERIESSUM", 4), + (415, "FACTDOUBLE", 1), + (416, "SQRTPI", 1), + (417, "QUOTIENT", 2), + (418, "DELTA", -1), + (419, "GESTEP", -1), + (420, "ISEVEN", 1), + (421, "ISODD", 1), + (422, "MROUND", 2), + (423, "ERF", -1), + (424, "ERFC", 1), + (425, "BESSELJ", 2), + (426, "BESSELK", 2), + (427, "BESSELY", 2), + (428, "BESSELI", 2), + (429, "XIRR", -1), + (430, "XNPV", 3), + (431, "PRICEMAT", -1), + (432, "YIELDMAT", -1), + (433, "INTRATE", -1), + (434, "RECEIVED", -1), + (435, "DISC", -1), + (436, "PRICEDISC", -1), + (437, "YIELDDISC", -1), + (438, "TBILLEQ", 3), + (439, "TBILLPRICE", 3), + (440, "TBILLYIELD", 3), + (441, "PRICE", -1), + (442, "YIELD", -1), + (443, "DOLLARDE", 2), + (444, "DOLLARFR", 2), + (445, "NOMINAL", 2), + (446, "EFFECT", 2), + (447, "CUMPRINC", 6), + (448, "CUMIPMT", 6), + (449, "EDATE", 2), + (450, "EOMONTH", 2), + (451, "YEARFRAC", -1), + (452, "COUPDAYBS", -1), + (453, "COUPDAYS", -1), + (454, "COUPDAYSNC", -1), + (455, "COUPNCD", -1), + (456, "COUPNUM", -1), + (457, "COUPPCD", -1), + (458, "DURATION", -1), + (459, "MDURATION", -1), + (460, "ODDLPRICE", -1), + (461, "ODDLYIELD", -1), + (462, "ODDFPRICE", -1), + (463, "ODDFYIELD", -1), + (464, "RANDBETWEEN", 2), + (465, "WEEKNUM", -1), + (466, "AMORDEGRC", -1), + (467, "AMORLINC", -1), + (469, "ACCRINT", -1), + (470, "ACCRINTM", -1), + (471, "WORKDAY", -1), + (472, "NETWORKDAYS", -1), + (473, "GCD", -1), + (474, "MULTINOMIAL", -1), + (475, "LCM", -1), + (476, "FVSCHEDULE", 2), + (477, "CUBEKPIMEMBER", -1), + (478, "CUBESET", -1), + (479, "CUBESETCOUNT", 1), + (480, "IFERROR", 2), + (481, "COUNTIFS", -1), + (482, "SUMIFS", -1), + (483, "AVERAGEIF", -1), + (484, "AVERAGEIFS", -1), +]; + +/// The function a `PtgFunc` or `PtgFuncVar` calls: its name and fixed argument count (-1 when it +/// takes a variable number). `None` for a number the table doesn't assign. +// The formula decoder calls it. +#[allow(dead_code)] +pub(super) fn function(iftab: u16) -> Option<(&'static str, i8)> { + FTAB.binary_search_by_key(&iftab, |(i, _, _)| *i).ok().and_then(|i| FTAB.get(i)).map(|(_, n, a)| (*n, *a)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn xlsb_function_numbers() { + // `function` binary-searches the table: sorted, each number once. + assert!(FTAB.windows(2).all(|w| w[0].0 < w[1].0)); + // The [MS-XLS] part, unchanged. + assert_eq!(function(0), Some(("COUNT", -1))); + assert_eq!(function(379), Some(("RTD", -1))); + // [MS-XLSB] 2.5.98.10 continues the table from 0x17C. Excel writes these by number in + // XLSB: PtgFunc for a fixed argument count, PtgFuncVar otherwise. + assert_eq!(function(0x17C), Some(("CUBEVALUE", -1))); + assert_eq!(function(449), Some(("EDATE", 2))); + assert_eq!(function(480), Some(("IFERROR", 2))); + assert_eq!(function(482), Some(("SUMIFS", -1))); + assert_eq!(function(0x1D4), None, "unassigned"); + assert_eq!(function(0x1E5), None); + } +} From 787b3e44f49541b2b34bad86b296edb6f1aa6b5e Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 23:29:29 -0500 Subject: [PATCH 008/349] craft-xlsx: read cell formulas from .xlsb files (port of gridcraft#3818) A BIFF12 decoder for cell formulas (xlsb/formula.rs), separate from craft-xls's BIFF8 one because nearly every operand differs (32-bit rows, 14-bit columns, UTF-16 strings, its own array-constant codes, newer functions called through hidden names). It reads references, 3-D references, constants, array constants, functions by number (xlsb/ftab.rs) and newer functions through Excel's hidden _xlfn. names. A formula cell's CellFormula holds the text as an .xlsx file holds it (`_xlfn.CONCAT`, `_xlpm.x`, no implicit `@`), and a BrtCellMeta before a cell gives it cell_metadata, as `cm` does. Reverse-Polish tokens group by order alone, so the decoded tree gets the parentheses its text needs from operator precedence; Excel's own text is unchanged. A chain of string constants joined with & prints as one flat chain. What a formula refers to must be readable too, so shared, array and data-table forms, user defined names (XLSB names aren't read yet), table references, external links and PY(index, ...) (code stored elsewhere in the package) keep only their saved results, with a warning saying why. So does a formula past Limits::binary_formula_text (128 MiB of text over the workbook). The workbook's links and names are optional: if they can't be read, the file opens with values only, as before, and a warning says so. Ported from storytold/gridcraft#3818 (issue gridcraft#3806), with its two review fixes (grouping by precedence, the flat & chain). Changed from the GridCraft PR: - The tree and its A1 printer (xlsb/expr.rs) are a copy of craft-xls's expr.rs, with BinOp::precedence added; the decoder's stack and depth guards are copies of craft-xls's. The PR used GridCraft's formula crate and shared these with GridCraft's .xls decoder. - No fmla::from_file, implicit `@`, parse check or Python-cell adoption: those are GridCraft's reading of the text, not the file's. A single-cell dynamic-array formula is read (with its cell metadata) instead of being kept as its value; the PR left dynamic arrays to the next PR. - The links are read with the workbook part and kept by Package for its sheets. Its tests come along in tests/xlsb.rs, with the expected text in the file's spelling. Checked against Excel: of the formulas in a workbook Excel saved both as .xlsb and as .xlsx, every one this reads (26) has the text of the .xlsx; the other 12 are the kinds above. --- crates/xlsx/src/lib.rs | 5 + crates/xlsx/src/package.rs | 15 +- crates/xlsx/src/xlsb.rs | 158 +++++++++- crates/xlsx/src/xlsb/expr.rs | 345 ++++++++++++++++++++ crates/xlsx/src/xlsb/formula.rs | 538 ++++++++++++++++++++++++++++++++ crates/xlsx/src/xlsb/ftab.rs | 2 - crates/xlsx/tests/common/mod.rs | 19 +- crates/xlsx/tests/xlsb.rs | 267 ++++++++++++++++ 8 files changed, 1329 insertions(+), 20 deletions(-) create mode 100644 crates/xlsx/src/xlsb/expr.rs create mode 100644 crates/xlsx/src/xlsb/formula.rs diff --git a/crates/xlsx/src/lib.rs b/crates/xlsx/src/lib.rs index b0771d366..5a64ae0ab 100644 --- a/crates/xlsx/src/lib.rs +++ b/crates/xlsx/src/lib.rs @@ -145,6 +145,10 @@ pub struct Limits { pub binary_cells: usize, /// Bytes of decoded text (shared and inline strings) in a binary workbook, over all its parts. pub binary_text: usize, + /// Bytes of decoded formula text in a binary workbook, over all its sheets. A cell formula + /// may hold 16 KB of tokens, so without a total a million cells of long formulas would cost + /// gigabytes; past it, formulas keep their saved results (the file still opens). + pub binary_formula_text: usize, } impl Default for Limits { @@ -156,6 +160,7 @@ impl Default for Limits { binary_records: 40_000_000, binary_cells: 4_000_000, binary_text: 256 << 20, + binary_formula_text: 128 << 20, } } } diff --git a/crates/xlsx/src/package.rs b/crates/xlsx/src/package.rs index 1c133d0ad..8f2c5efc6 100644 --- a/crates/xlsx/src/package.rs +++ b/crates/xlsx/src/package.rs @@ -29,6 +29,9 @@ pub struct Package<'a> { binary: Option, workbook_rels: Option, budget: xlsb::Budget, + /// What a binary workbook's formulas refer to, once its workbook part is read: `Some(None)` + /// when that couldn't be read (every formula keeps its saved result). + binary_links: Option>, /// Shared strings in a binary workbook, once counted: a cell's index is checked against it. binary_strings: Option, } @@ -67,6 +70,7 @@ impl<'a> Package<'a> { binary, workbook_rels: None, budget: xlsb::Budget::default(), + binary_links: None, binary_strings: None, }) } @@ -145,7 +149,9 @@ impl<'a> Package<'a> { if self.binary.is_some() { let bytes = self.required(&self.workbook_part.clone())?; let rels = self.workbook_rels()?; - return xlsb::workbook(&bytes, &rels, &self.limits, &self.budget, &mut self.warnings); + let (wb, links) = xlsb::workbook(&bytes, &rels, &self.limits, &self.budget, &mut self.warnings)?; + self.binary_links = Some(links); + return Ok(wb); } let options = self.xml_options(); let root = match self.opc.read_xml(&self.workbook_part, &options)? { @@ -234,8 +240,13 @@ impl<'a> Package<'a> { Some(n) => n, None => self.shared_strings()?.len(), }; + // Formulas name sheets and functions through the workbook part. + if self.binary_links.is_none() { + self.workbook()?; + } let bytes = self.required(&part)?; - let mut sheet = xlsb::worksheet(&bytes, strings, &self.limits, &self.budget, &mut self.warnings, &mut each)?; + let links = self.binary_links.as_ref().and_then(Option::as_ref); + let mut sheet = xlsb::worksheet(&bytes, strings, links, &self.limits, &self.budget, &mut self.warnings, &mut each)?; sheet.part = part; return Ok(sheet); } diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 542fd580c..aedbae5ab 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -1,7 +1,10 @@ //! Binary workbooks ([MS-XLSB]): the workbook part, shared strings and worksheet cells, from -//! their records. Saved values only: formulas are token streams that are not decoded, and -//! styles are not read. A record that does not parse fails the read. +//! their records. Cell formulas are decoded from their tokens ([`formula`]) into the text an +//! `.xlsx` file holds; one that can't be keeps only its saved result, with a warning saying why. +//! Styles are not read. A record that does not parse fails the read. +mod expr; +mod formula; mod ftab; use std::sync::Arc; @@ -9,10 +12,12 @@ use std::sync::Arc; use craft_opc::{ContentTypes, Rels}; use craft_sheet::{CellError, CellRef, MAX_COLS, MAX_ROWS, Range, Visibility}; -use crate::sheet::{Cell, CellValue, Row, SheetPart}; +use crate::sheet::{Cell, CellFormula, CellValue, Row, SheetPart}; use crate::strings::StringItem; use crate::workbook::{SheetEntry, SheetKind, Workbook}; use crate::{Error, Limits, Warnings}; +pub(crate) use formula::Links; +use formula::{Book, Name, Xti}; pub(crate) const MAIN: &str = "application/vnd.ms-excel.main"; const BINARY_MAIN: &str = "application/vnd.ms-excel.sheet.binary.macroEnabled.main"; @@ -22,6 +27,9 @@ pub(crate) const STRINGS: &str = "application/vnd.ms-excel.sharedStrings"; const MAX_SHEETS: usize = 1024; /// Most merged ranges in one worksheet. const MAX_MERGES: usize = 100_000; +/// Defined names (Excel's hidden ones for newer functions included) read at most; past it, the +/// workbook's formulas keep their saved results. +const MAX_NAMES: usize = 65_536; pub(crate) fn invalid(msg: impl Into) -> Error { Error::Invalid(format!("XLSB: {}", msg.into())) @@ -43,9 +51,21 @@ pub(crate) struct Budget { cells: std::cell::Cell, text: std::cell::Cell, records: std::cell::Cell, + formula_text: std::cell::Cell, } impl Budget { + /// Charges a decoded formula's text if it fits [`Limits::binary_formula_text`]; a formula + /// that doesn't keeps its saved result. + fn try_formula_text(&self, len: usize, limits: &Limits) -> bool { + let total = self.formula_text.get().saturating_add(len); + let fits = total <= limits.binary_formula_text; + if fits { + self.formula_text.set(total); + } + fits + } + fn text(&self, len: usize, limits: &Limits) -> Result<(), Error> { self.text.set(self.text.get().saturating_add(len)); if self.text.get() > limits.binary_text { @@ -97,6 +117,9 @@ impl<'a> Bytes<'a> { fn u32(&mut self) -> Result { Ok(u32::from_le_bytes(self.take(4)?.try_into().map_err(|_| invalid("truncated u32"))?)) } + fn i32(&mut self) -> Result { + Ok(i32::from_le_bytes(self.take(4)?.try_into().map_err(|_| invalid("truncated i32"))?)) + } fn f64(&mut self) -> Result { let n = f64::from_le_bytes(self.take(8)?.try_into().map_err(|_| invalid("truncated number"))?); @@ -224,10 +247,19 @@ impl<'a, 'l> Records<'a, 'l> { } /// The workbook part: BrtBeginBook, BrtWbProp, the BrtBundleSh list. -pub(crate) fn workbook(bytes: &[u8], rels: &Rels, limits: &Limits, budget: &Budget, warnings: &mut Warnings) -> Result { +/// The workbook part, and the tables its formulas refer to ([`Links`]): `None` when those can't +/// be read, so that the workbook still opens, with every formula kept as its saved result. +pub(crate) fn workbook( + bytes: &[u8], + rels: &Rels, + limits: &Limits, + budget: &Budget, + warnings: &mut Warnings, +) -> Result<(Workbook, Option), Error> { let mut records = Records::new(bytes, limits, budget); records.first(131, warnings)?; let mut wb = Workbook::default(); + let mut links = Some(Links::default()); let mut bundle = false; let mut bundle_seen = false; while let Some((id, payload)) = records.next(warnings)? { @@ -241,7 +273,17 @@ pub(crate) fn workbook(bytes: &[u8], rels: &Rels, limits: &Limits, budget: &Budg if wb.sheets.is_empty() { return Err(invalid("no supported worksheets")); } - return Ok(wb); + if links.is_none() { + warnings.warn("XLSB: the workbook's sheet links or names could not be read; formulas keep their saved results"); + } + return Ok((wb, links)); + } + 39 | 355 | 357 | 358 | 362 | 667 => { + if let Some(l) = links.as_mut() + && link_record(id, payload, l).is_err() + { + links = None; + } } 143 => { if bundle_seen { @@ -289,6 +331,10 @@ pub(crate) fn workbook(bytes: &[u8], rels: &Rels, limits: &Limits, budget: &Budg return Err(invalid("worksheet relationship is null")); } warnings.warn("XLSB module sheets were skipped"); + // Formulas name sheets by their place in this list, skipped sheets included. + if let Some(l) = links.as_mut() { + l.sheets.push(None); + } continue; }; let rel = rels.by_id(&rel_id).ok_or_else(|| invalid("worksheet relationship is missing"))?; @@ -299,6 +345,10 @@ pub(crate) fn workbook(bytes: &[u8], rels: &Rels, limits: &Limits, budget: &Budg if let SheetKind::Other(_) = kind { return Err(invalid("unknown sheet relationship type")); } + // Only a worksheet has cells a formula can refer to. + if let Some(l) = links.as_mut() { + l.sheets.push((kind == SheetKind::Worksheet).then(|| name.clone())); + } wb.sheets.push(SheetEntry { name, sheet_id, visibility, rel_id, kind, part: Some(rel.target.clone()) }); } _ => {} @@ -307,6 +357,48 @@ pub(crate) fn workbook(bytes: &[u8], rels: &Rels, limits: &Limits, budget: &Budg Err(invalid("missing workbook end record")) } +/// A supporting link (`BrtSupSelf`, `BrtSupSame`, `BrtSupAddin`, `BrtSupBookSrc`), the sheet links +/// (`BrtExternSheet`) or a defined name (`BrtName`), added to `links`. +fn link_record(id: u16, payload: &[u8], links: &mut Links) -> Result<(), Error> { + let mut b = Bytes::new(payload); + match id { + 357 | 358 | 667 => { + b.finish()?; + links.books.push(match id { + 357 => Book::This, + 358 => Book::Same, + _ => Book::Addin, + }); + } + 355 => links.books.push(Book::External), + 362 => { + // [MS-XLSB] 2.4.672: cXti "MUST be less than 65536" (PtgRef3d's ixti is 16 bits). + let count = b.u32()?; + if count >= 65_536 || !links.xti.is_empty() { + return Err(invalid("invalid sheet link list")); + } + for _ in 0..count { + let book = b.u32()?; + let (first, last) = (b.i32()?, b.i32()?); + links.xti.push(Xti { book, first, last }); + } + b.finish()?; + } + _ => { + // BrtName ([MS-XLSB] 2.4.718): flags, chKey, itab, then the name; the formula and the + // rest aren't needed to call a function or tell a name from one. + if links.names.len() >= MAX_NAMES { + return Err(invalid("too many defined names")); + } + let flags = b.u32()?; + b.take(5)?; + let text = b.text(255)?; + links.names.push(Name { text, future: flags & (1 << 17) != 0 }); + } + } + Ok(()) +} + /// A `RichStr`: the text; formatting and phonetic runs are skipped. fn rich_string(b: &mut Bytes<'_>) -> Result { let flags = b.u8()?; @@ -397,17 +489,37 @@ fn boolean(b: &mut Bytes<'_>) -> Result { } } -/// The formula after a cell's saved result: checked for framing, not decoded. -fn skip_formula(b: &mut Bytes<'_>) -> Result<(), Error> { +/// The `grbitFlags` and `CellParsedFormula` after a formula cell's value: its tokens (`rgce`) +/// and their extra data (`rgcb`). The flags' only bit, `fAlwaysCalc`, is the calculator's to know. +fn cell_formula<'a>(b: &mut Bytes<'a>) -> Result<(&'a [u8], &'a [u8]), Error> { b.take(2)?; let cce = b.u32()?; if !(1..=16384).contains(&cce) { return Err(invalid("invalid formula token length")); } - b.take(cce as usize)?; + let rgce = b.take(cce as usize)?; let extra = b.u32()?; - b.take(extra as usize)?; - Ok(()) + let rgcb = b.take(extra as usize)?; + Ok((rgce, rgcb)) +} + +/// A formula's text, or `None` (with a warning saying why) for one that keeps its saved result: +/// the workbook's links couldn't be read, the tokens can't be decoded, or the formula text +/// allowance is spent. +fn decode_formula(rgce: &[u8], rgcb: &[u8], links: Option<&Links>, limits: &Limits, budget: &Budget, warnings: &mut Warnings) -> Option { + let links = links?; + let text = match formula::decode(rgce, rgcb, links) { + Ok(e) => expr::print(&e), + Err(formula::Unsupported(why)) => { + warnings.warn(format!("XLSB: some formulas were kept as their saved results ({why})")); + return None; + } + }; + if !budget.try_formula_text(text.len(), limits) { + warnings.warn("XLSB: some formulas were kept as their saved results (more formula text than the limits allow)"); + return None; + } + Some(text) } fn value(id: u16, b: &mut Bytes<'_>, strings: usize, limits: &Limits, budget: &Budget) -> Result { @@ -444,16 +556,16 @@ fn value(id: u16, b: &mut Bytes<'_>, strings: usize, limits: &Limits, budget: &B } _ => return Err(invalid("unsupported cell record")), }; - if (8..=11).contains(&id) { - skip_formula(b)?; - } Ok(value) } /// A worksheet part: rows (BrtRowHdr) and cells inside BrtBeginSheetData, merged cells after. +/// Formulas refer to the workbook's `links`; with none, each keeps its saved result. +#[allow(clippy::too_many_arguments)] pub(crate) fn worksheet( bytes: &[u8], strings: usize, + links: Option<&Links>, limits: &Limits, budget: &Budget, warnings: &mut Warnings, @@ -466,9 +578,18 @@ pub(crate) fn worksheet( let mut data_seen = false; let mut row: Option = None; let mut col = None; + // BrtCellMeta applies to the cell record that follows it (a dynamic-array formula), as `cm` + // does in `.xlsx`: a one-based index into the metadata part's cell metadata. + let mut meta: Option = None; while let Some((id, payload)) = records.next(warnings)? { let mut b = Bytes::new(payload); + let cell_metadata = meta.take(); match id { + 49 => { + let icmb = b.i32()?; + b.finish()?; + meta = u32::try_from(icmb).ok().filter(|&i| i >= 1); + } 130 => { if data || !data_seen { return Err(invalid("incomplete worksheet data")); @@ -527,7 +648,14 @@ pub(crate) fn worksheet( } let style = b.u32()?; let value = value(id, &mut b, strings, limits, budget)?; - b.finish()?; + let formula = if (8..=11).contains(&id) { + let (rgce, rgcb) = cell_formula(&mut b)?; + b.finish()?; + decode_formula(rgce, rgcb, links, limits, budget, warnings).map(|text| CellFormula { text, ..CellFormula::default() }) + } else { + b.finish()?; + None + }; if value != CellValue::Empty { budget.cell(limits)?; } @@ -536,6 +664,8 @@ pub(crate) fn worksheet( style: style & 0x00FF_FFFF, phonetic: style & 0x0100_0000 != 0, value, + formula, + cell_metadata, ..Cell::default() }); col = Some(c); diff --git a/crates/xlsx/src/xlsb/expr.rs b/crates/xlsx/src/xlsb/expr.rs new file mode 100644 index 000000000..3dd643a6a --- /dev/null +++ b/crates/xlsx/src/xlsb/expr.rs @@ -0,0 +1,345 @@ +//! The expression tree an XLSB formula decodes to, and its A1 formula text (without `=`), in the +//! file's spelling (`_xlfn.` and `_xlpm.` names as written). A copy of craft-xls's: the two +//! readers follow separate specifications, and can share one tree when both settle. + +use std::fmt::Write; +use std::sync::Arc; + +use craft_sheet::{CellError, push_col, quote_sheet, sheet_needs_quotes}; + +/// One end of a reference, with `$` anchors. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) struct Anchor { + pub row: u32, + pub col: u32, + pub row_abs: bool, + pub col_abs: bool, +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum RefKind { + Cell(Anchor), + Range(Anchor, Anchor), + /// Whole rows `3:5` as (row, absolute) pairs. + Rows(u32, bool, u32, bool), + /// Whole columns `A:C`. + Cols(u32, bool, u32, bool), +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) enum SheetSel { + /// Unqualified: the formula's own sheet. + Current, + Named(String), + /// 3-D span `Sheet1:Sheet3`. + Span(String, String), +} + +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct Reference { + pub sheet: SheetSel, + pub kind: RefKind, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum UnOp { + Neg, + Plus, + Percent, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(crate) enum BinOp { + Add, + Sub, + Mul, + Div, + Pow, + Concat, + Eq, + Ne, + Lt, + Gt, + Le, + Ge, + /// `:` between two references. + Range, + /// `,` inside parentheses. + Union, + /// A space between two references. + Intersect, +} + +impl BinOp { + /// How tightly the operator binds, as formula text is read: `:` 90, space 85, `,` 80, `^` 50, + /// `*` `/` 40, `+` `-` 30, `&` 20, comparisons 10. + pub(crate) fn precedence(self) -> u8 { + match self { + BinOp::Range => 90, + BinOp::Intersect => 85, + BinOp::Union => 80, + BinOp::Pow => 50, + BinOp::Mul | BinOp::Div => 40, + BinOp::Add | BinOp::Sub => 30, + BinOp::Concat => 20, + BinOp::Eq | BinOp::Ne | BinOp::Lt | BinOp::Gt | BinOp::Le | BinOp::Ge => 10, + } + } + + fn symbol(self) -> &'static str { + match self { + BinOp::Add => "+", + BinOp::Sub => "-", + BinOp::Mul => "*", + BinOp::Div => "/", + BinOp::Pow => "^", + BinOp::Concat => "&", + BinOp::Eq => "=", + BinOp::Ne => "<>", + BinOp::Lt => "<", + BinOp::Gt => ">", + BinOp::Le => "<=", + BinOp::Ge => ">=", + BinOp::Range => ":", + BinOp::Union => ",", + BinOp::Intersect => " ", + } + } +} + +/// A formula's syntax tree. The decoder bounds its depth, so printing and dropping it recurse +/// safely. +#[derive(Debug, PartialEq)] +pub(crate) enum Expr { + Number(f64), + Text(Arc), + Bool(bool), + Error(CellError), + /// Array constant `{1,2;3,4}` (rows of literals). + Array(Vec>), + Ref(Reference), + /// A defined name. + Name(String), + Unary(UnOp, Box), + Binary(BinOp, Box, Box), + Call(String, Vec), + /// An omitted argument. + Missing, + Paren(Box), +} + +fn push_anchor(s: &mut String, a: &Anchor) { + if a.col_abs { + s.push('$'); + } + push_col(s, a.col); + if a.row_abs { + s.push('$'); + } + let _ = write!(s, "{}", u64::from(a.row) + 1); +} + +fn push_reference(s: &mut String, r: &Reference) { + match &r.sheet { + SheetSel::Current => {} + SheetSel::Named(n) => { + s.push_str("e_sheet(n)); + s.push('!'); + } + SheetSel::Span(a, b) => { + let joined = format!("{a}:{b}"); + if sheet_needs_quotes(a) || sheet_needs_quotes(b) { + let _ = write!(s, "'{}'!", joined.replace('\'', "''")); + } else { + let _ = write!(s, "{joined}!"); + } + } + } + let dollar = |abs: bool| if abs { "$" } else { "" }; + match &r.kind { + RefKind::Cell(a) => push_anchor(s, a), + RefKind::Range(a, b) => { + push_anchor(s, a); + s.push(':'); + push_anchor(s, b); + } + RefKind::Rows(r0, a0, r1, a1) => { + let _ = write!(s, "{}{}:{}{}", dollar(*a0), u64::from(*r0) + 1, dollar(*a1), u64::from(*r1) + 1); + } + RefKind::Cols(c0, a0, c1, a1) => { + s.push_str(dollar(*a0)); + push_col(s, *c0); + s.push(':'); + s.push_str(dollar(*a1)); + push_col(s, *c1); + } + } +} + +/// Removes trailing zeros (and a trailing point) from a decimal string. +fn trim_decimal(s: &str) -> String { + if s.contains('.') { + let t = s.trim_end_matches('0').trim_end_matches('.'); + if t == "-0" { "0".into() } else { t.to_string() } + } else { + s.to_string() + } +} + +/// Scientific text like `1.23456789012346E+15` with up to `sig` significant digits. +fn sci_text(n: f64, sig: usize) -> String { + let s = format!("{:.*e}", sig.saturating_sub(1), n); + let Some((mant, exp)) = s.split_once('e') else { return s }; + let mant = trim_decimal(mant); + let e: i32 = exp.parse().unwrap_or(0); + format!("{}E{}{:02}", mant, if e < 0 { '-' } else { '+' }, e.abs()) +} + +/// A number as a formula spells it: up to 15 significant digits, scientific for very large or +/// very small magnitudes. +pub(crate) fn number_to_text(n: f64) -> String { + if n == 0.0 || !n.is_finite() { + return "0".into(); + } + let a = n.abs(); + if !(1e-9..1e15).contains(&a) && a.round() != a || a >= 1e15 { + return sci_text(n, 15); + } + // A value just below 1e15 can round up to 1e15 at 15 significant digits. + if format!("{a:.14e}").parse::().is_ok_and(|r| r >= 1e15) { + return sci_text(n, 15); + } + let mag = a.log10().floor() as i32; + let decimals = (14 - mag).clamp(0, 30) as usize; + trim_decimal(&format!("{n:.decimals$}")) +} + +fn number(n: f64) -> String { + let text = number_to_text(n); + // 15 significant digits can round past f64::MAX, which no longer parses. + if text.parse::().is_ok_and(f64::is_finite) { + return text; + } + let exact = format!("{n:E}"); + match exact.split_once('E') { + Some((m, e)) if !e.starts_with('-') => format!("{m}E+{e}"), + _ => exact, + } +} + +/// Splits a sheet-qualified name at its last `!` outside brackets. +fn sheet_split(n: &str) -> Option<(&str, &str)> { + let mut depth = 0usize; + let mut escaped = false; + let mut at = None; + for (i, c) in n.char_indices() { + if escaped { + escaped = false; + continue; + } + match c { + '\'' if depth > 0 => escaped = true, + '[' => depth = depth.saturating_add(1), + ']' => depth = depth.saturating_sub(1), + '!' if depth == 0 => at = Some(i), + _ => {} + } + } + at.and_then(|i| Some((n.get(..i)?, n.get(i + 1..)?))) +} + +/// Prints an expression in A1 notation. +pub(crate) fn print(e: &Expr) -> String { + let mut s = String::new(); + write_expr(&mut s, e); + s +} + +fn write_args(s: &mut String, args: &[Expr], sep: char) { + for (i, a) in args.iter().enumerate() { + if i > 0 { + s.push(sep); + } + write_expr(s, a); + } +} + +fn write_expr(s: &mut String, e: &Expr) { + match e { + Expr::Number(n) => s.push_str(&number(*n)), + Expr::Text(t) => { + s.push('"'); + s.push_str(&t.replace('"', "\"\"")); + s.push('"'); + } + Expr::Bool(b) => s.push_str(if *b { "TRUE" } else { "FALSE" }), + Expr::Error(err) => s.push_str(err.as_str()), + Expr::Array(rows) => { + s.push('{'); + for (ri, row) in rows.iter().enumerate() { + if ri > 0 { + s.push(';'); + } + write_args(s, row, ','); + } + s.push('}'); + } + Expr::Ref(r) => push_reference(s, r), + Expr::Name(n) => match sheet_split(n) { + // A sheet-qualified name holds the bare sheet name (`My Sheet!Total`): quote it so it parses back. + Some((sheet, name)) => { + s.push_str("e_sheet(sheet)); + s.push('!'); + s.push_str(name); + } + None => s.push_str(n), + }, + Expr::Unary(UnOp::Neg, x) => { + s.push('-'); + write_expr(s, x); + } + Expr::Unary(UnOp::Plus, x) => { + s.push('+'); + write_expr(s, x); + } + Expr::Unary(UnOp::Percent, x) => { + write_expr(s, x); + s.push('%'); + } + Expr::Binary(op, a, b) => { + write_expr(s, a); + s.push_str(op.symbol()); + write_expr(s, b); + } + Expr::Call(name, args) => { + s.push_str(name); + s.push('('); + write_args(s, args, ','); + s.push(')'); + } + Expr::Missing => {} + Expr::Paren(x) => { + s.push('('); + write_expr(s, x); + s.push(')'); + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn numbers_print_with_fifteen_significant_digits() { + assert_eq!(number_to_text(1.0), "1"); + assert_eq!(number_to_text(-2.5), "-2.5"); + assert_eq!(number_to_text(0.1 + 0.2), "0.3"); + assert_eq!(number_to_text(123456789012345.0), "123456789012345"); + assert_eq!(number_to_text(1e15), "1E+15"); + assert_eq!(number_to_text(1234567890123456.0), "1.23456789012346E+15"); + assert_eq!(number_to_text(0.0001), "0.0001"); + assert_eq!(number_to_text(1e-10), "1E-10"); + assert!(number(f64::MAX).parse::().is_ok_and(f64::is_finite)); + } +} diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs new file mode 100644 index 000000000..bed0adcd0 --- /dev/null +++ b/crates/xlsx/src/xlsb/formula.rs @@ -0,0 +1,538 @@ +//! BIFF12 parsed formulas ([MS-XLSB] 2.2.2, 2.5.98): reverse-Polish `Ptg` tokens back to an +//! expression tree, for cell formulas. The tokens are BIFF8's, but nearly every operand differs +//! (32-bit rows, 14-bit columns, UTF-16 strings, its own array-constant codes, newer functions +//! called through hidden names), so this is its own decoder, with its own function table +//! ([`super::ftab`]) and its own copies of craft-xls's depth guards and limits. Anything outside the +//! token set it knows is reported as unsupported, and the caller keeps the cell's cached value. +//! So is a formula that needs something the reader doesn't read: a user's defined name (XLSB +//! names are not read yet) or Python code stored outside the cell. +//! +//! Names keep their file spelling (`_xlfn.CONCAT`, `_xlpm.x`), as `.xlsx` formula text has them. + +use std::sync::Arc; + +use craft_sheet::{CellError, MAX_COLS, MAX_ROWS}; + +use super::expr::{Anchor, BinOp, Expr, RefKind, Reference, SheetSel, UnOp}; +use super::ftab::function; + +/// Formula token bytes decoded at most (a cell formula holds at most 16,384). +pub(super) const MAX_RGCE: usize = 16 * 1024; +/// Values in one array constant at most. +const MAX_ARRAY: usize = 65_536; + +/// Why a formula could not be turned back into text. +#[derive(Debug, PartialEq)] +pub(super) struct Unsupported(pub &'static str); + +/// Expression nesting at most: deeper trees would overflow the stack when printed or dropped (a +/// hostile file can chain thousands of PtgParen tokens). +const MAX_DEPTH: usize = 256; + +/// Operand stack entries: an expression and its nesting depth. +type Stack = Vec<(Expr, usize)>; + +/// Pops an operand, recording its depth in `kids` (the deepest operand this token consumed). +fn pop(stack: &mut Stack, kids: &mut usize) -> Result { + let (e, d) = stack.pop().ok_or(Unsupported("malformed formula (operand missing)"))?; + *kids = (*kids).max(d); + Ok(e) +} + +fn pop_n(stack: &mut Stack, n: usize, kids: &mut usize) -> Result, Unsupported> { + let at = stack.len().checked_sub(n).ok_or(Unsupported("malformed formula (argument missing)"))?; + let popped = stack.split_off(at); + *kids = popped.iter().map(|(_, d)| *d).fold(*kids, usize::max); + Ok(popped.into_iter().map(|(e, _)| e).collect()) +} + +/// Pushes the result of a token one level above the operands it consumed. +fn push(stack: &mut Stack, kids: usize, e: Expr) -> Result<(), Unsupported> { + let depth = kids.saturating_add(1); + if depth > MAX_DEPTH { + return Err(Unsupported("formula nested too deeply")); + } + stack.push((e, depth)); + Ok(()) +} + +/// An error constant's code ([MS-XLSB] 2.5.98.21, `BErr`). +fn error_code(code: u8) -> Option { + Some(match code { + 0x00 => CellError::Null, + 0x07 => CellError::Div0, + 0x0F => CellError::Value, + 0x17 => CellError::Ref, + 0x1D => CellError::Name, + 0x24 => CellError::Num, + 0x2A => CellError::NA, + 0x2B => CellError::GettingData, + _ => return None, + }) +} + +/// A supporting link record ([MS-XLSB] 2.2.7.3), in the order of the workbook's externals block. +#[derive(Clone, Copy, Debug, PartialEq)] +pub(super) enum Book { + /// `BrtSupSelf`: this workbook. + This, + /// `BrtSupSame`: the caller's sheet (macro sheets and names only). + Same, + /// `BrtSupAddin`: add-in functions. + Addin, + /// `BrtSupBookSrc`: another workbook, DDE or OLE. Never followed. + External, +} + +/// Xti ([MS-XLSB] 2.5.173): a supporting link and a range of its sheets. +#[derive(Clone, Copy, Debug)] +pub(super) struct Xti { + pub book: u32, + pub first: i32, + pub last: i32, +} + +/// A `BrtName` as far as cell formulas need it. +#[derive(Clone, Debug)] +pub(super) struct Name { + /// The name as written (`_xlfn.CONCAT`, `_xlpm.x`, `Rate`). + pub text: String, + /// `fFutureFunction`: a hidden name standing for a function newer than the file format. + pub future: bool, +} + +/// Workbook-level tables formulas refer to. +#[derive(Default)] +pub(crate) struct Links { + /// Every sheet's name in `BrtBundleSh` order, `None` for sheets the reader skips or that hold + /// no cells (chart, dialog and macro sheets). + pub(super) sheets: Vec>, + /// Every `BrtName`, in order: `PtgName` indexes them from 1. + pub(super) names: Vec, + pub(super) books: Vec, + pub(super) xti: Vec, +} + +/// Whether a name stands for a LET parameter (`_xlpm.x`), which only the formula itself defines. +fn is_param(name: &str) -> bool { + name.get(..6).is_some_and(|p| p.eq_ignore_ascii_case("_xlpm.")) +} + +impl Links { + /// The sheets a 3-D reference names, or `None` for a deleted sheet (the reference is `#REF!`). + fn sheet_sel(&self, ixti: u16) -> Result, Unsupported> { + let x = self.xti.get(usize::from(ixti)).ok_or(Unsupported("reference to a missing sheet link"))?; + match usize::try_from(x.book).ok().and_then(|b| self.books.get(b)) { + Some(Book::This) => {} + Some(Book::External) => return Err(Unsupported("references to other workbooks (external links)")), + Some(_) => return Err(Unsupported("references through add-in or same-sheet links")), + None => return Err(Unsupported("reference to a missing workbook link")), + } + // -1: "the first sheet in the reference cannot be found" (a deleted sheet). + if x.first == -1 || x.last == -1 { + return Ok(None); + } + // -2 (the whole workbook) is for names, not cell references. + let (Ok(first), Ok(last)) = (usize::try_from(x.first), usize::try_from(x.last)) else { + return Err(Unsupported("reference to a missing sheet")); + }; + // A span takes every sheet between its ends, so a skipped one anywhere in it changes + // what the reference means. + let span = self.sheets.get(first..=last).filter(|s| !s.is_empty()).ok_or(Unsupported("reference to a missing sheet"))?; + if span.iter().any(Option::is_none) { + return Err(Unsupported("references to sheets the reader skips")); + } + let (Some(Some(a)), Some(Some(b))) = (span.first(), span.last()) else { + return Err(Unsupported("reference to a missing sheet")); + }; + Ok(Some(if first == last { SheetSel::Named(a.clone()) } else { SheetSel::Span(a.clone(), b.clone()) })) + } +} + +struct Bytes<'a> { + b: &'a [u8], + pos: usize, +} + +const TRUNC: Unsupported = Unsupported("truncated formula"); + +impl Bytes<'_> { + fn take(&mut self, n: usize) -> Result<&[u8], Unsupported> { + let s = self.b.get(self.pos..self.pos.checked_add(n).ok_or(TRUNC)?).ok_or(TRUNC)?; + self.pos += n; + Ok(s) + } + fn u8(&mut self) -> Result { + self.take(1)?.first().copied().ok_or(TRUNC) + } + fn u16(&mut self) -> Result { + let s: [u8; 2] = self.take(2)?.try_into().map_err(|_| TRUNC)?; + Ok(u16::from_le_bytes(s)) + } + fn u32(&mut self) -> Result { + let s: [u8; 4] = self.take(4)?.try_into().map_err(|_| TRUNC)?; + Ok(u32::from_le_bytes(s)) + } + fn f64(&mut self) -> Result { + let s: [u8; 8] = self.take(8)?.try_into().map_err(|_| TRUNC)?; + let n = f64::from_le_bytes(s); + if !n.is_finite() { + return Err(Unsupported("invalid number constant")); + } + Ok(n) + } + /// `cch` UTF-16 code units; unpaired surrogates are refused, not replaced. + fn chars(&mut self, cch: usize) -> Result { + let units = self.take(cch.checked_mul(2).ok_or(TRUNC)?)?.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes(*c)); + char::decode_utf16(units).collect::>().map_err(|_| Unsupported("invalid text constant")) + } +} + +/// The last row and column of the grid: a range from 0 to these is a whole column or row. +const LAST_ROW: u32 = MAX_ROWS - 1; +const LAST_COL: u32 = MAX_COLS - 1; + +/// RgceLoc ([MS-XLSB] 2.5.98.91): a row and a `ColRelShort` (14-bit column, then the +/// column-relative and row-relative flags). In a cell formula the coordinates are absolute +/// whatever the flags say; the flags only decide where `$` goes. +fn anchor(row: u32, col: u16) -> Result { + let c = u32::from(col & 0x3FFF); + if row > LAST_ROW || c > LAST_COL { + return Err(Unsupported("reference outside the grid")); + } + Ok(Anchor { row, col: c, row_abs: col & 0x8000 == 0, col_abs: col & 0x4000 == 0 }) +} + +/// RgceArea: a range spanning every row (or column) is a whole-column (row) reference. +fn area(r0: u32, r1: u32, c0: u16, c1: u16) -> Result { + let (a, b) = (anchor(r0, c0)?, anchor(r1, c1)?); + Ok(if a.row == 0 && b.row == LAST_ROW { + RefKind::Cols(a.col, a.col_abs, b.col, b.col_abs) + } else if a.col == 0 && b.col == LAST_COL { + RefKind::Rows(a.row, a.row_abs, b.row, b.row_abs) + } else { + RefKind::Range(a, b) + }) +} + +fn reference(sheet: Option, kind: RefKind) -> Expr { + match sheet { + Some(sheet) => Expr::Ref(Reference { sheet, kind }), + None => Expr::Error(CellError::Ref), + } +} + +/// Decodes a cell formula's `rgce` (tokens) with its `rgcb` (extra data for array constants and +/// cached areas). Returns the expression, with names in their file spelling, or why it can't be +/// represented. +pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links) -> Result { + if rgce.len() > MAX_RGCE { + return Err(Unsupported("formula too long")); + } + let mut t = Bytes { b: rgce, pos: 0 }; + let mut extra = Bytes { b: rgcb, pos: 0 }; + let mut stack: Stack = Vec::new(); + while t.pos < rgce.len() { + let ptg = t.u8()?; + let mut kids = 0usize; + // Operand classes (reference / value / array) share one token number. + let id = if ptg & 0x60 != 0 { 0x20 | (ptg & 0x1F) } else { ptg }; + match id { + 0x03..=0x11 => { + let op = match id { + 0x03 => BinOp::Add, + 0x04 => BinOp::Sub, + 0x05 => BinOp::Mul, + 0x06 => BinOp::Div, + 0x07 => BinOp::Pow, + 0x08 => BinOp::Concat, + 0x09 => BinOp::Lt, + 0x0A => BinOp::Le, + 0x0B => BinOp::Eq, + 0x0C => BinOp::Ge, + 0x0D => BinOp::Gt, + 0x0E => BinOp::Ne, + 0x0F => BinOp::Intersect, + 0x10 => BinOp::Union, + _ => BinOp::Range, + }; + let b = pop(&mut stack, &mut kids)?; + let a = pop(&mut stack, &mut kids)?; + push(&mut stack, kids, Expr::Binary(op, Box::new(a), Box::new(b)))?; + } + 0x12..=0x14 => { + let op = match id { + 0x12 => UnOp::Plus, + 0x13 => UnOp::Neg, + _ => UnOp::Percent, + }; + let x = pop(&mut stack, &mut kids)?; + push(&mut stack, kids, Expr::Unary(op, Box::new(x)))?; + } + 0x15 => { + let x = pop(&mut stack, &mut kids)?; + push(&mut stack, kids, Expr::Paren(Box::new(x)))?; + } + 0x16 => push(&mut stack, kids, Expr::Missing)?, + // PtgStr: cch (u16, at most 255) and always UTF-16, unlike BIFF8. + 0x17 => { + let cch = usize::from(t.u16()?); + if cch > 255 { + return Err(Unsupported("text constant too long")); + } + push(&mut stack, kids, Expr::Text(Arc::from(t.chars(cch)?)))?; + } + 0x19 => { + let kind = t.u8()?; + if kind & 0x04 != 0 { + // PtgAttrChoose: jump table of cOffset + 1 entries. + let n = usize::from(t.u16()?) + 1; + t.take(n * 2)?; + } else { + t.take(2)?; + } + if kind & 0x10 != 0 { + // PtgAttrSum: SUM of the single operand. + let x = pop(&mut stack, &mut kids)?; + push(&mut stack, kids, Expr::Call("SUM".into(), vec![x]))?; + } + // Semi (volatile), If, Goto, Space, Baxcel: no effect on the expression. + } + 0x1C => { + let e = t.u8()?; + push(&mut stack, kids, Expr::Error(error_code(e).ok_or(Unsupported("unknown error constant"))?))?; + } + 0x1D => push(&mut stack, kids, Expr::Bool(t.u8()? != 0))?, + 0x1E => push(&mut stack, kids, Expr::Number(f64::from(t.u16()?)))?, + 0x1F => { + let n = t.f64()?; + push(&mut stack, kids, Expr::Number(n))?; + } + 0x20 => { + // PtgArray: 14 unused bytes (Excel leaves junk in them); the values are in rgcb. + t.take(14)?; + push(&mut stack, kids, array_constant(&mut extra)?)?; + } + 0x21 => { + let iftab = t.u16()?; + let (name, args) = function(iftab).ok_or(Unsupported("unknown function"))?; + let n = usize::try_from(args).map_err(|_| Unsupported("unknown function argument count"))?; + let args = pop_n(&mut stack, n, &mut kids)?; + push(&mut stack, kids, Expr::Call(name.to_string(), args))?; + } + 0x22 => { + let n = usize::from(t.u8()?); + let tab = t.u16()?; + if tab & 0x8000 != 0 { + return Err(Unsupported("macro sheet commands")); + } + let mut args = pop_n(&mut stack, n, &mut kids)?; + if tab & 0x7FFF == 0x00FF { + // A function called by name (a newer function, add-in or LAMBDA): the name + // comes first, as a PtgName to a hidden `_xlfn.` name for a newer function. + if args.is_empty() { + return Err(Unsupported("malformed function call")); + } + let name = match args.remove(0) { + Expr::Name(n) => n, + _ => return Err(Unsupported("function call through an expression")), + }; + // `PY(index, …)` runs a script stored elsewhere in the package, which this + // import doesn't read. `PY("code", …)` carries its code and becomes a Python cell. + let py = name.rsplit('.').next().is_some_and(|n| n.eq_ignore_ascii_case("PY")); + if py && !args.first().is_some_and(literal_text) { + return Err(Unsupported("Python code stored outside the cell")); + } + push(&mut stack, kids, Expr::Call(name, args))?; + } else { + let (name, _) = function(tab & 0x7FFF).ok_or(Unsupported("unknown function"))?; + push(&mut stack, kids, Expr::Call(name.to_string(), args))?; + } + } + 0x23 => { + // PtgName: a 1-based index into every BrtName, hidden ones included. + let i = usize::try_from(t.u32()?).ok().and_then(|i| i.checked_sub(1)); + let name = i.and_then(|i| links.names.get(i)).ok_or(Unsupported("reference to a missing defined name"))?; + // Defined names are not imported from XLSB yet: a cell using one would calculate + // to #NAME?, so it keeps its saved result. Newer functions and LET parameters are + // hidden names that the formula text itself defines. + if !name.future && !is_param(&name.text) { + return Err(Unsupported("defined names")); + } + push(&mut stack, kids, Expr::Name(name.text.clone()))?; + } + 0x24 => { + let (r, c) = (t.u32()?, t.u16()?); + push(&mut stack, kids, Expr::Ref(Reference { sheet: SheetSel::Current, kind: RefKind::Cell(anchor(r, c)?) }))?; + } + 0x25 => { + let (r0, r1, c0, c1) = (t.u32()?, t.u32()?, t.u16()?, t.u16()?); + push(&mut stack, kids, Expr::Ref(Reference { sheet: SheetSel::Current, kind: area(r0, r1, c0, c1)? }))?; + } + 0x26 => { + // PtgMemArea: a cache of the sub-expression that follows. Its rgcb entry + // (PtgExtraMem) is a count and 16 bytes per cached area: skip both. + t.take(6)?; + let n = usize::try_from(extra.u32()?).map_err(|_| TRUNC)?; + extra.take(n.checked_mul(16).ok_or(TRUNC)?)?; + } + // PtgMemErr, PtgMemNoMem: 6 bytes; PtgMemFunc: 2. The sub-expression follows them. + 0x27 | 0x28 => { + t.take(6)?; + } + 0x29 => { + t.take(2)?; + } + 0x2A => { + t.take(6)?; + push(&mut stack, kids, Expr::Error(CellError::Ref))?; + } + 0x2B => { + t.take(12)?; + push(&mut stack, kids, Expr::Error(CellError::Ref))?; + } + 0x39 => return Err(Unsupported("names in other workbooks or on other sheets")), + 0x3A => { + let ixti = t.u16()?; + let (r, c) = (t.u32()?, t.u16()?); + let kind = RefKind::Cell(anchor(r, c)?); + push(&mut stack, kids, reference(links.sheet_sel(ixti)?, kind))?; + } + 0x3B => { + let ixti = t.u16()?; + let (r0, r1, c0, c1) = (t.u32()?, t.u32()?, t.u16()?, t.u16()?); + let kind = area(r0, r1, c0, c1)?; + push(&mut stack, kids, reference(links.sheet_sel(ixti)?, kind))?; + } + 0x3C | 0x3D => { + let ixti = t.u16()?; + t.take(if id == 0x3C { 6 } else { 12 })?; + // The sheet link must still be one the reader follows: an external #REF! stays cached. + links.sheet_sel(ixti)?; + push(&mut stack, kids, Expr::Error(CellError::Ref))?; + } + 0x01 => return Err(Unsupported("the shared or array formula form")), + 0x02 => return Err(Unsupported("what-if data tables")), + 0x18 => return Err(Unsupported("structured table references")), + 0x2C | 0x2D => return Err(Unsupported("relative references in a cell formula")), + _ => return Err(Unsupported("unknown formula token")), + } + if stack.len() > MAX_RGCE { + return Err(Unsupported("formula too complex")); + } + } + let (e, _) = stack.pop().ok_or(Unsupported("malformed formula (operand missing)"))?; + if !stack.is_empty() { + return Err(Unsupported("malformed formula (unused operands)")); + } + Ok(grouped(e, false)) +} + +/// Text written out in the formula: a string, or strings joined with `&` (how Python code +/// longer than a string constant is written). +fn literal_text(e: &Expr) -> bool { + match e { + Expr::Text(_) => true, + Expr::Binary(BinOp::Concat, a, b) => literal_text(a) && literal_text(b), + _ => false, + } +} + +/// How tightly an expression binds when printed, as the formula parser reads it: binary +/// operators by [`BinOp::precedence`], prefix `+`/`-` at 60 and `%` at 70 (`-2^2` is `(-2)^2`); +/// anything else is one operand. +fn binding(e: &Expr) -> u8 { + match e { + Expr::Binary(op, ..) => op.precedence(), + Expr::Unary(UnOp::Neg | UnOp::Plus, _) => 60, + Expr::Unary(UnOp::Percent, _) => 70, + _ => u8::MAX, + } +} + +/// The strings of a [`literal_text`] chain, left to right. +fn flatten_texts(e: Expr, out: &mut Vec) { + match e { + Expr::Binary(BinOp::Concat, a, b) => { + flatten_texts(*a, out); + flatten_texts(*b, out); + } + text => out.push(text), + } +} + +fn paren(e: Expr) -> Expr { + Expr::Paren(Box::new(e)) +} + +/// The tree with the parentheses its text needs to mean the same. Tokens are reverse Polish, so +/// grouping lives in their order: Excel adds `PtgParen` wherever its text has parentheses, but +/// `1 2 + 3 *` (another writer's, or a crafted file's) would print as `1+2*3`. Binary operators +/// are left-associative; a union in a function's arguments needs parentheses of its own. +/// Recursion follows the decoded tree, which `push` bounds at `MAX_DEPTH` levels. +fn grouped(e: Expr, in_args: bool) -> Expr { + match e { + // Strings joined with `&` are written as one flat chain, however their tokens nest: `&` + // is associative, and `PY("…"&"…")` is read as Python code only in that form. + e @ Expr::Binary(BinOp::Concat, ..) if literal_text(&e) => { + let mut texts = vec![]; + flatten_texts(e, &mut texts); + let mut texts = texts.into_iter(); + let first = texts.next().unwrap_or(Expr::Missing); + texts.fold(first, |a, b| Expr::Binary(BinOp::Concat, Box::new(a), Box::new(b))) + } + Expr::Binary(op, a, b) => { + let (a, b) = (grouped(*a, in_args), grouped(*b, in_args)); + let a = if binding(&a) < op.precedence() { paren(a) } else { a }; + let b = if binding(&b) <= op.precedence() { paren(b) } else { b }; + let e = Expr::Binary(op, Box::new(a), Box::new(b)); + if in_args && op == BinOp::Union { paren(e) } else { e } + } + Expr::Unary(op, x) => { + let x = grouped(*x, in_args); + // Each of `+`, `-` and `%` takes an operand that binds at least as tightly as a sign. The + // parser reads `-1%` as `-(1%)`, Excel's tokens as `(-1)%`: the same value, so a sign + // under `%` keeps Excel's spelling. + let needs = binding(&x) < 60; + Expr::Unary(op, Box::new(if needs { paren(x) } else { x })) + } + Expr::Paren(x) => paren(grouped(*x, false)), + Expr::Call(name, args) => Expr::Call(name, args.into_iter().map(|a| grouped(a, true)).collect()), + other => other, + } +} + +/// PtgExtraArray ([MS-XLSB] 2.5.98.41): row and column counts, then `SerAr` values in row-major +/// order. The type codes are not BIFF8's: 0x00 is a number here, not a missing value. +fn array_constant(b: &mut Bytes<'_>) -> Result { + let rows = usize::try_from(b.u32()?).map_err(|_| TRUNC)?; + let cols = usize::try_from(b.u32()?).map_err(|_| TRUNC)?; + if rows == 0 || cols == 0 || rows.saturating_mul(cols) > MAX_ARRAY { + return Err(Unsupported("array constant too large or empty")); + } + let mut out = Vec::with_capacity(rows); + for _ in 0..rows { + let mut row = Vec::with_capacity(cols); + for _ in 0..cols { + row.push(match b.u8()? { + 0x00 => Expr::Number(b.f64()?), + 0x01 => { + let cch = usize::from(b.u16()?); + if cch > 255 { + return Err(Unsupported("text constant too long")); + } + Expr::Text(Arc::from(b.chars(cch)?)) + } + 0x02 => Expr::Bool(b.u8()? != 0), + 0x04 => { + let e = b.u8()?; + b.take(3)?; + Expr::Error(error_code(e).ok_or(Unsupported("unknown error constant"))?) + } + _ => return Err(Unsupported("unknown array constant value")), + }); + } + out.push(row); + } + Ok(Expr::Array(out)) +} diff --git a/crates/xlsx/src/xlsb/ftab.rs b/crates/xlsx/src/xlsb/ftab.rs index c6b59092a..87f369519 100644 --- a/crates/xlsx/src/xlsb/ftab.rs +++ b/crates/xlsx/src/xlsb/ftab.rs @@ -487,8 +487,6 @@ const FTAB: &[(u16, &str, i8)] = &[ /// The function a `PtgFunc` or `PtgFuncVar` calls: its name and fixed argument count (-1 when it /// takes a variable number). `None` for a number the table doesn't assign. -// The formula decoder calls it. -#[allow(dead_code)] pub(super) fn function(iftab: u16) -> Option<(&'static str, i8)> { FTAB.binary_search_by_key(&iftab, |(i, _, _)| *i).ok().and_then(|i| FTAB.get(i)).map(|(_, n, a)| (*n, *a)) } diff --git a/crates/xlsx/tests/common/mod.rs b/crates/xlsx/tests/common/mod.rs index 59d3d8372..30703b3cd 100644 --- a/crates/xlsx/tests/common/mod.rs +++ b/crates/xlsx/tests/common/mod.rs @@ -3,12 +3,15 @@ use std::collections::BTreeMap; -use craft_xlsx::{CellRef, Error, Limits, Package, Range, SheetKind, Value, Visibility}; +use craft_xlsx::{CellFormula, CellRef, Error, Limits, Package, Range, SheetKind, Value, Visibility}; pub struct Sheet { pub name: String, pub visibility: Visibility, pub cells: BTreeMap, + /// Every cell's formula, and its cell metadata index (`cm`), where it has one. + pub formulas: BTreeMap, + pub cell_metadata: BTreeMap, pub merges: Vec, } @@ -16,6 +19,11 @@ impl Sheet { pub fn value(&self, at: CellRef) -> Value { self.cells.get(&at).cloned().unwrap_or_default() } + + /// The formula text at `at`, if the cell has a formula. + pub fn formula(&self, at: CellRef) -> Option<&str> { + self.formulas.get(&at).map(|f| f.text.as_str()) + } } pub struct Book { @@ -37,8 +45,15 @@ pub fn read_with(bytes: &[u8], limits: &Limits) -> Result { continue; } let mut cells = BTreeMap::new(); + let (mut formulas, mut cell_metadata) = (BTreeMap::new(), BTreeMap::new()); let part = p.sheet(e, |row| { for c in row.cells { + if let Some(f) = c.formula { + formulas.insert(c.at, f); + } + if let Some(m) = c.cell_metadata { + cell_metadata.insert(c.at, m); + } let v = c.value.resolve(&strings, wb.date_1904); if !v.is_empty() { cells.insert(c.at, v); @@ -46,7 +61,7 @@ pub fn read_with(bytes: &[u8], limits: &Limits) -> Result { } Ok(()) })?; - book.sheets.push(Sheet { name: e.name.clone(), visibility: e.visibility, cells, merges: part.merges }); + book.sheets.push(Sheet { name: e.name.clone(), visibility: e.visibility, cells, formulas, cell_metadata, merges: part.merges }); } book.warnings = p.warnings().to_vec(); Ok(book) diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index cef6d9cbe..42c27158b 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -442,3 +442,270 @@ fn phonetic_runs_use_documented_size_and_tolerate_padding() { } assert!(read(&file(&worksheet(&[row(0), cell(62, 0, &phonetic(2, 12))].concat(), &[]))).is_err()); } + +/// A formula cell (`BrtFmlaNum`, cached 0) with its own tokens and extra data. +fn formula_cell(col: u32, rgce: &[u8], rgcb: &[u8]) -> Vec { + let mut data = col.to_le_bytes().to_vec(); + data.extend([0; 4]); + data.extend(0f64.to_le_bytes()); + data.extend([0; 2]); + data.extend((rgce.len() as u32).to_le_bytes()); + data.extend(rgce); + data.extend((rgcb.len() as u32).to_le_bytes()); + data.extend(rgcb); + record(9, &data) +} + +fn name(flags: u32, text: &str) -> Vec { + let mut data = flags.to_le_bytes().to_vec(); + data.push(0); + data.extend(u32::MAX.to_le_bytes()); // Workbook scope. + data.extend(wide(text)); + data.extend([2, 0, 0, 0, 0x1c, 0x1d, 0, 0, 0, 0]); // Formula `#NAME?`, no extra data. + data.extend(u32::MAX.to_le_bytes()); // No comment. + record(39, &data) +} + +/// `book(false)` with a supporting-link block and defined names, as Excel writes them: this +/// workbook, then another; sheet links Data, Hidden, Data:Hidden, a deleted sheet and the other +/// workbook; hidden names for CONCAT, LET and a LET parameter, then the user name Rate. +fn book_with_links(extern_sheet: &[u8]) -> Vec { + let plain = book(false); + let end = record(132, &[]); + let mut out = plain[..plain.len() - end.len()].to_vec(); + out.extend(record(353, &[])); + out.extend(record(357, &[])); + out.extend(record(355, &wide("rId9"))); + out.extend(record(362, extern_sheet)); + out.extend(record(354, &[])); + const FUTURE: u32 = 0x0002_000b; + out.extend(name(FUTURE, "_xlfn.CONCAT")); + out.extend(name(FUTURE, "_xlfn.LET")); + out.extend(name(0x0002_0019, "_xlpm.x")); + out.extend(name(0, "Rate")); + out.extend(end); + out +} + +fn xti() -> Vec { + let mut out = 5u32.to_le_bytes().to_vec(); + for (book, first, last) in [(0u32, 0i32, 0i32), (0, 1, 1), (0, 0, 1), (0, -1, -1), (1, 0, 0)] { + out.extend(book.to_le_bytes()); + out.extend(first.to_le_bytes()); + out.extend(last.to_le_bytes()); + } + out +} + +fn loc(row: u32, col: u16) -> Vec { + [&row.to_le_bytes()[..], &col.to_le_bytes()].concat() +} + +/// Relative row and column flags of a `ColRelShort`. +const REL: u16 = 0xC000; + +fn warned(wb: &common::Book, why: &str) -> bool { + wb.warnings.iter().any(|w| w.contains("kept as their saved results") && w.contains(why)) +} + +#[test] +fn cell_formulas_are_read_in_their_xlsx_spelling() { + let ref3d = |ixti: u16, row: u32, col: u16| [&[0x5Au8][..], &ixti.to_le_bytes(), &loc(row, col)].concat(); + let cells: Vec<(u32, Vec, Vec)> = vec![ + (1, [&[0x44u8][..], &loc(0, REL), &[0x1E, 2, 0, 0x05]].concat(), vec![]), + (2, [&[0x25u8][..], &0u32.to_le_bytes(), &1u32.to_le_bytes(), &0u16.to_le_bytes(), &REL.to_le_bytes(), &[0x19, 0x10, 0, 0]].concat(), vec![]), + (3, ref3d(1, 1, 1 | REL), vec![]), + ( + 4, + [ + &[0x3Bu8][..], + &2u16.to_le_bytes(), + &0u32.to_le_bytes(), + &0xFFFFFu32.to_le_bytes(), + &REL.to_le_bytes(), + &REL.to_le_bytes(), + &[0x19, 0x10, 0, 0], + ] + .concat(), + vec![], + ), + (5, [&[0x23u8, 1, 0, 0, 0][..], &[0x17, 1, 0, b'a', 0], &[0x17, 1, 0, b'b', 0], &[0x42, 3, 0xFF, 0]].concat(), vec![]), + (6, vec![0x1E, 1, 0, 0x1E, 0, 0, 0x06, 0x1E, 2, 0, 0x41, 0xE0, 0x01], vec![]), + ( + 7, + [&[0x60u8][..], &[0xAB; 14]].concat(), + [&2u32.to_le_bytes()[..], &2u32.to_le_bytes(), &[0], &1f64.to_le_bytes(), &[1, 1, 0, b'x', 0], &[2, 1], &[4, 0x2A, 0, 0, 0]].concat(), + ), + ( + 8, + [&[0x23u8, 2, 0, 0, 0][..], &[0x23, 3, 0, 0, 0, 0x1E, 1, 0], &[0x23, 3, 0, 0, 0, 0x1E, 1, 0, 0x03], &[0x42, 4, 0xFF, 0]].concat(), + vec![], + ), + (9, ref3d(3, 0, 0), vec![]), + (10, [&[0x25u8][..], &0u32.to_le_bytes(), &1u32.to_le_bytes(), &REL.to_le_bytes(), &REL.to_le_bytes(), &[0x41, 20, 0]].concat(), vec![]), + // Kept as their saved results: + (11, vec![0x43, 4, 0, 0, 0, 0x1E, 2, 0, 0x05], vec![]), + (12, ref3d(4, 0, REL), vec![]), + (13, vec![0x01, 0, 0, 0, 0], vec![0, 0, 0, 0]), + ]; + let mut data = row(0); + data.extend(cell(5, 0, &3.0f64.to_le_bytes())); + for (col, rgce, rgcb) in &cells { + data.extend(formula_cell(*col, rgce, rgcb)); + } + data.extend(record(49, &1u32.to_le_bytes())); // BrtCellMeta: the next formula is a dynamic array. + data.extend(formula_cell(14, &[0x1E, 1, 0], &[])); + data.extend(formula_cell(15, &[0x18, 0x19, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0], &[])); // A table reference. + let wb = read(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + let sheet = &wb.sheets[0]; + let got: Vec<_> = (1..=15).map(|c| sheet.formula(CellRef::new(0, c))).collect(); + // As an `.xlsx` file holds them: names in their file spelling (`_xlfn.`, `_xlpm.`), and no + // implicit `@`, which is how a calculator reads a legacy formula, not how the file spells it. + let want = [ + Some("A1*2"), + Some("SUM($A$1:A2)"), + Some("Hidden!B2"), + Some("SUM(Data:Hidden!A:A)"), + Some("_xlfn.CONCAT(\"a\",\"b\")"), + Some("IFERROR(1/0,2)"), + Some("{1,\"x\";TRUE,#N/A}"), + Some("_xlfn.LET(_xlpm.x,1,_xlpm.x+1)"), + Some("#REF!"), + Some("SQRT(A1:A2)"), + None, + None, + None, + // A BrtCellMeta before a cell gives it cell metadata, as `cm` does in .xlsx. + Some("1"), + None, + ]; + assert_eq!(got, want); + assert!(sheet.formulas.values().all(|f| f.kind == craft_xlsx::FormulaKind::Normal)); + assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&CellRef::new(0, 14), &1)]); + // Every formula cell keeps its saved result as its value. + assert!((1..=15).all(|c| sheet.value(CellRef::new(0, c)) == Value::Number(0.0))); + for why in ["defined names", "other workbooks", "the shared or array formula form", "structured table references"] { + assert!(warned(&wb, why), "{why}: {:?}", wb.warnings); + } +} + +#[test] +fn unreadable_links_keep_every_formula_as_its_value() { + // A sheet-link count past the spec's limit, and a truncated list: the file opens as it did + // before formulas were read, with values only. + let mut truncated = xti(); + truncated.truncate(20); + for extern_sheet in [70_000u32.to_le_bytes().to_vec(), truncated] { + let data = [row(0), formula_cell(0, &[0x1E, 1, 0], &[])].concat(); + let wb = read(&package(&book_with_links(&extern_sheet), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), None); + assert_eq!(wb.sheets[0].value(CellRef::new(0, 0)), Value::Number(0.0)); + assert!(wb.warnings.iter().any(|w| w.contains("could not be read")), "{:?}", wb.warnings); + } +} + +#[test] +fn formula_grouping_follows_token_order() { + // Reverse-Polish tokens group by their order alone. Excel writes PtgParen wherever its text + // has parentheses, but another writer need not: the text gets the ones it needs to mean the + // same, and no more. + let a = |row: u32| [&[0x24u8][..], &loc(row, REL)].concat(); + let int = |n: u8| vec![0x1E, n, 0]; + let cases: Vec<(Vec, &str)> = vec![ + ([int(1), int(2), vec![0x03], int(3), vec![0x05]].concat(), "(1+2)*3"), + ([int(1), int(2), int(3), vec![0x04, 0x04]].concat(), "1-(2-3)"), + ([int(1), int(2), vec![0x04], int(3), vec![0x04]].concat(), "1-2-3"), + ([int(2), vec![0x13], int(2), vec![0x07]].concat(), "-2^2"), + ([int(2), int(2), vec![0x07, 0x13]].concat(), "-(2^2)"), + // Excel's tokens for its own `-1%`: the parser groups it the other way, to the same value. + ([int(1), vec![0x13, 0x14]].concat(), "-1%"), + ([int(1), int(2), vec![0x03, 0x14]].concat(), "(1+2)%"), + ([a(0), a(1), vec![0x10], vec![0x19, 0x10, 0, 0]].concat(), "SUM((A1,A2))"), + ([int(1), int(2), vec![0x03, 0x15], int(3), vec![0x05]].concat(), "(1+2)*3"), + ]; + let data: Vec = + [row(0)].into_iter().chain(cases.iter().enumerate().map(|(i, (rgce, _))| formula_cell(i as u32, rgce, &[]))).flatten().collect(); + let wb = read(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + for (i, (_, want)) in cases.iter().enumerate() { + assert_eq!(wb.sheets[0].formula(CellRef::new(0, i as u32)), Some(*want)); + } +} + +#[test] +fn functions_past_0x17b_are_called_by_number() { + // [MS-XLSB] 2.5.98.10's numbers past the .xls table: IFERROR (PtgFunc) and SUMIFS (PtgFuncVar). + let sumifs = [&[0x1Eu8, 1, 0][..], &[0x1E, 2, 0], &[0x17, 2, 0, b'>', 0, b'0', 0], &[0x42, 3, 0xE2, 0x01]].concat(); + let data = [row(0), formula_cell(0, &[0x1E, 1, 0, 0x1E, 2, 0, 0x41, 0xE0, 0x01], &[]), formula_cell(1, &sumifs, &[])].concat(); + let wb = read(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), Some("IFERROR(1,2)")); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 1)), Some("SUMIFS(1,2,\">0\")")); +} + +#[test] +fn hostile_formula_tokens_keep_the_saved_result() { + let mut deep = vec![0x1E, 1, 0]; + deep.resize(16384, 0x15); // Thousands of parentheses: refused by the depth guard. + let empty_array = [&[0x60u8][..], &[0; 14]].concat(); + let bad: Vec<(Vec, Vec)> = vec![ + (vec![0x1E, 1], vec![]), // Truncated PtgInt. + (vec![0x17, 1, 0, 0x00, 0xD8], vec![]), // Unpaired surrogate. + (vec![0x17, 0, 1], vec![]), // Text constant over 255. + ([&[0x24u8][..], &loc(1_048_576, 0)].concat(), vec![]), // Row past the grid. + (empty_array.clone(), vec![0; 8]), // Empty array constant. + (empty_array, vec![0xFF; 8]), // Huge one. + (vec![0x1E, 1, 0, 0x1E, 2, 0], vec![]), // Unused operand. + (vec![0x21, 0xD4, 0x01], vec![]), // Unassigned function number. + (vec![0x2C, 0, 0, 0, 0, 0, 0], vec![]), // PtgRefN outside a shared formula. + (vec![0x23, 0xFF, 0xFF, 0xFF, 0xFF], vec![]), // Name index past the list. + ([&[0x5Au8][..], &9u16.to_le_bytes(), &loc(0, 0)].concat(), vec![]), // Missing sheet link. + (deep, vec![]), + ]; + for (rgce, rgcb) in bad { + let data = [row(0), formula_cell(0, &rgce, &rgcb)].concat(); + let wb = read(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), None, "{rgce:?}"); + assert_eq!(wb.sheets[0].value(CellRef::new(0, 0)), Value::Number(0.0)); + } +} + +#[test] +fn python_formulas_need_their_code_in_the_cell() { + // `PY("code", 0)` carries its code; `PY(0, 0)` names a script elsewhere in the package, which + // the reader doesn't read, and keeps its saved result. + let mut book = book_with_links(&xti()); + let end = record(132, &[]); + book.truncate(book.len() - end.len()); + book.extend(name(0x0002_000b, "_xlfn._xlws.PY")); + book.extend(end); + let py = |arg: &[u8]| [&[0x23u8, 5, 0, 0, 0][..], arg, &[0x1E, 0, 0, 0x42, 3, 0xFF, 0]].concat(); + // Code longer than one string constant is written as constants joined with `&`. + let joined = [&[0x17u8, 1, 0, b'1', 0][..], &[0x17, 2, 0, b'+', 0, b'1', 0], &[0x08]].concat(); + // The same strings nested to the right, `"1"&("+"&"1")` by token order: still one flat chain. + let nested = [&[0x17u8, 1, 0, b'1', 0][..], &[0x17, 1, 0, b'+', 0], &[0x17, 1, 0, b'1', 0], &[0x08, 0x08]].concat(); + let data = [ + row(0), + formula_cell(0, &py(&[0x17, 1, 0, b'1', 0]), &[]), + formula_cell(1, &py(&[0x1E, 0, 0]), &[]), + formula_cell(2, &py(&joined), &[]), + formula_cell(3, &py(&nested), &[]), + ] + .concat(); + let wb = read(&package(&book, &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + let formula = |c| wb.sheets[0].formula(CellRef::new(0, c)); + assert_eq!(formula(0), Some("_xlfn._xlws.PY(\"1\",0)")); + assert_eq!(formula(1), None); + assert_eq!(formula(2), Some("_xlfn._xlws.PY(\"1\"&\"+1\",0)")); + assert_eq!(formula(3), Some("_xlfn._xlws.PY(\"1\"&\"+\"&\"1\",0)")); + assert!(warned(&wb, "Python code stored outside"), "{:?}", wb.warnings); +} + +#[test] +fn formula_text_past_the_allowance_keeps_the_saved_result() { + // `1` takes the last byte of a one-byte allowance; the next formula doesn't fit. + let data = [row(0), formula_cell(0, &[0x1E, 1, 0], &[]), formula_cell(1, &[0x1E, 1, 0], &[])].concat(); + let limits = Limits { binary_formula_text: 1, ..Limits::default() }; + let wb = read_with(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES), &limits).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), Some("1")); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 1)), None); + assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); +} From 734ade8cd988f95c318c788e810a07b86f3bc880 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 23:34:15 -0500 Subject: [PATCH 009/349] craft-xlsx: read shared, array and dynamic-array formulas from .xlsb files (port of gridcraft#3821) A cell whose tokens are only PtgExp (row) + PtgExtraCol (column) belongs to the shared or array formula starting there; its first cell is followed by BrtShrFmla or BrtArrFmla. - Shared formulas: each cell's copy is decoded from the shared tokens at its own cell, as [MS-XLSB] defines it (PtgRefN/PtgAreaN offsets, wrapping around the grid). Every cell of the group gets FormulaKind::Shared, its own text and the group's index (`si`, counted per sheet); the first also gets the group's range. Its first cell is the first that uses it, anywhere in its range. Copies are charged to the formula text allowance before they are decoded, so a long formula shared by a million cells stops costing once the allowance is spent. - Ctrl+Shift+Enter and dynamic arrays: the first cell gets FormulaKind::Array with its range; a dynamic one also has its cell metadata (BrtCellMeta, which now also holds across a BrtValueMeta written in between), as `cm` marks it in .xlsx. The other cells of an array keep their cached values and have no formula, as in .xlsx. - A record that can't be read leaves its range as values and never fails the file, with a warning; so does a first cell with no formula record after it. Ported from storytold/gridcraft#3821 (issue gridcraft#3806), with its review fixes (each copy decoded at its own cell; a shared formula may start inside its range). Changed from the GridCraft PR: - In .xlsx a shared formula's other cells have empty text. Here they have their own decoded text (and CellFormula's doc says so), because that is exact where shifting the first cell's text is not, as the PR's review found. - Clearing an array's other cells for recalculation, marking dynamic arrays to spill, and the check against GridCraft's parser's 8,192-character limit are GridCraft's reading, not the file's: the cells keep what the file holds. That test becomes one that a copy may be longer than its first cell. The PR's tests come along in tests/xlsb.rs, with craft-xlsx's model in the expectations. Checked against Excel: in a workbook Excel saved both as .xlsb and as .xlsx, every formula this reads (33, shared, array and dynamic ones included) has the .xlsx text, kind and range; the other 5 use tables, an external link or defined names. --- crates/xlsx/src/sheet.rs | 6 +- crates/xlsx/src/xlsb.rs | 210 ++++++++++++++++++++++++++++++-- crates/xlsx/src/xlsb/formula.rs | 51 +++++++- crates/xlsx/tests/xlsb.rs | 170 +++++++++++++++++++++++++- 4 files changed, 415 insertions(+), 22 deletions(-) diff --git a/crates/xlsx/src/sheet.rs b/crates/xlsx/src/sheet.rs index 243430f8e..2691764d5 100644 --- a/crates/xlsx/src/sheet.rs +++ b/crates/xlsx/src/sheet.rs @@ -113,8 +113,10 @@ pub enum FormulaKind { #[derive(Clone, Debug, Default, PartialEq)] pub struct CellFormula { pub kind: FormulaKind, - /// The formula as the file spells it (`_xlfn.` prefixes and all), trimmed. Empty for a - /// cell that shares the formula of its group's first cell. + /// The formula as the file spells it (`_xlfn.` prefixes and all), trimmed. In `.xlsx`, empty + /// for a cell that shares the formula of its group's first cell. A binary workbook (`.xlsb`) + /// stores a shared formula's tokens once, so every cell of the group gets its own text, + /// decoded at the cell. pub text: String, /// `si`: the shared formula group. pub shared_index: Option, diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index aedbae5ab..dfea974b6 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -7,17 +7,18 @@ mod expr; mod formula; mod ftab; +use std::collections::HashMap; use std::sync::Arc; use craft_opc::{ContentTypes, Rels}; use craft_sheet::{CellError, CellRef, MAX_COLS, MAX_ROWS, Range, Visibility}; -use crate::sheet::{Cell, CellFormula, CellValue, Row, SheetPart}; +use crate::sheet::{Cell, CellFormula, CellValue, FormulaKind, Row, SheetPart}; use crate::strings::StringItem; use crate::workbook::{SheetEntry, SheetKind, Workbook}; use crate::{Error, Limits, Warnings}; pub(crate) use formula::Links; -use formula::{Book, Name, Xti}; +use formula::{Book, Mode, Name, Xti}; pub(crate) const MAIN: &str = "application/vnd.ms-excel.main"; const BINARY_MAIN: &str = "application/vnd.ms-excel.sheet.binary.macroEnabled.main"; @@ -57,6 +58,11 @@ pub(crate) struct Budget { impl Budget { /// Charges a decoded formula's text if it fits [`Limits::binary_formula_text`]; a formula /// that doesn't keeps its saved result. + /// Whether formula text of `len` bytes would still fit, without charging it. + fn formula_text_fits(&self, len: usize, limits: &Limits) -> bool { + self.formula_text.get().saturating_add(len) <= limits.binary_formula_text + } + fn try_formula_text(&self, len: usize, limits: &Limits) -> bool { let total = self.formula_text.get().saturating_add(len); let fits = total <= limits.binary_formula_text; @@ -506,22 +512,178 @@ fn cell_formula<'a>(b: &mut Bytes<'a>) -> Result<(&'a [u8], &'a [u8]), Error> { /// A formula's text, or `None` (with a warning saying why) for one that keeps its saved result: /// the workbook's links couldn't be read, the tokens can't be decoded, or the formula text /// allowance is spent. -fn decode_formula(rgce: &[u8], rgcb: &[u8], links: Option<&Links>, limits: &Limits, budget: &Budget, warnings: &mut Warnings) -> Option { +fn decode_formula( + rgce: &[u8], + rgcb: &[u8], + mode: Mode, + links: Option<&Links>, + limits: &Limits, + budget: &Budget, + warnings: &mut Warnings, +) -> Option { let links = links?; - let text = match formula::decode(rgce, rgcb, links) { + let text = match formula::decode(rgce, rgcb, links, mode) { Ok(e) => expr::print(&e), Err(formula::Unsupported(why)) => { - warnings.warn(format!("XLSB: some formulas were kept as their saved results ({why})")); + kept(warnings, why); return None; } }; if !budget.try_formula_text(text.len(), limits) { - warnings.warn("XLSB: some formulas were kept as their saved results (more formula text than the limits allow)"); + kept(warnings, "more formula text than the limits allow"); return None; } Some(text) } +/// Warns, once per reason, that formulas were kept as their saved results. +fn kept(warnings: &mut Warnings, why: &str) { + warnings.warn(format!("XLSB: some formulas were kept as their saved results ({why})")); +} + +/// A `BrtShrFmla`: the cells it may cover, its tokens, its first cell's text length (what a copy +/// is expected to cost) and the group's index (`si`). +struct SharedFormula { + range: Range, + rgce: Vec, + rgcb: Vec, + len: usize, + si: u32, +} + +/// A formula cell whose tokens are only `PtgExp`: part of a shared or array formula. +enum Part { + /// The first cell: its formula is the `BrtShrFmla` or `BrtArrFmla` record that follows. + First, + /// Another cell of the formula whose first cell is this. + Of(CellRef), +} + +/// `PtgExp` ([MS-XLSB] 2.5.98.40) with its `PtgExtraCol`: the first cell of the shared or array +/// formula this cell belongs to. BIFF12 keeps only the row in the token and the column in rgcb. +fn part_of(rgce: &[u8], rgcb: &[u8], at: CellRef) -> Option> { + let (&ptg, row) = rgce.split_first()?; + if ptg != 0x01 { + return None; + } + let (Ok(row), Ok(col)) = (<[u8; 4]>::try_from(row), <[u8; 4]>::try_from(rgcb)) else { + return Some(Err("malformed shared or array formula references")); + }; + let first = CellRef::new(u32::from_le_bytes(row), u32::from_le_bytes(col)); + Some(Ok(if first == at { Part::First } else { Part::Of(first) })) +} + +/// One sheet's shared and array formulas, by first cell, as the reader meets them. `None` when +/// the formula keeps its values (so its other cells keep theirs). +#[derive(Default)] +struct RangeFormulas { + shared: HashMap>>, + arrays: HashMap>, +} + +impl RangeFormulas { + /// The formula of another cell `at` of the shared or array formula starting at `first`. A + /// shared formula's copy is decoded from the shared tokens at its own cell, as [MS-XLSB] + /// defines it (relative offsets wrap around the grid), and checked like any formula: its text + /// may be longer than the first cell's. That length estimates its cost, and a copy that can't + /// fit isn't decoded at all, so a long formula shared by a million cells stops costing once + /// the allowance is spent. An array formula's other cells have none, as in `.xlsx`. + fn follower( + &self, + at: CellRef, + first: CellRef, + links: Option<&Links>, + limits: &Limits, + budget: &Budget, + warnings: &mut Warnings, + ) -> Option { + if let Some(shared) = self.shared.get(&first) { + let sh = shared.as_ref()?; + if !sh.range.contains(at) { + kept(warnings, "malformed shared or array formula references"); + return None; + } + if !budget.formula_text_fits(sh.len, limits) { + kept(warnings, "more formula text than the limits allow"); + return None; + } + let text = decode_formula(&sh.rgce, &sh.rgcb, Mode::Shared(at), links, limits, budget, warnings)?; + return Some(CellFormula { kind: FormulaKind::Shared, text, shared_index: Some(sh.si), ..CellFormula::default() }); + } + match self.arrays.get(&first) { + Some(Some(range)) if range.contains(at) => {} + Some(Some(_)) => kept(warnings, "malformed shared or array formula references"), + Some(None) => {} + None => kept(warnings, "a shared or array formula that is missing from the file"), + } + None + } + + /// `BrtShrFmla` (427) or `BrtArrFmla` (426) right after the first cell `first` of its range: + /// the formula that cell keeps, recorded for the range's other cells. A record that can't be + /// read leaves the whole range as values; it never fails the file, as these records were + /// skipped before formulas were read. + #[allow(clippy::too_many_arguments)] + fn range_formula( + &mut self, + id: u16, + payload: &[u8], + first: CellRef, + links: Option<&Links>, + limits: &Limits, + budget: &Budget, + warnings: &mut Warnings, + ) -> Option { + let read = |b: &mut Bytes<'_>| -> Result<(Range, Vec, Vec), Error> { + let (r0, r1, c0, c1) = (b.u32()?, b.u32()?, b.u32()?, b.u32()?); + if id == 426 { + b.u8()?; // Only fAlwaysCalc, the calculator's to know. + } + let cce = b.u32()?; + if !(1..=16384).contains(&cce) { + return Err(invalid("invalid formula token length")); + } + let rgce = b.take(cce as usize)?.to_vec(); + let cb = b.u32()?; + let rgcb = b.take(cb as usize)?.to_vec(); + if r0 > r1 || c0 > c1 || r1 >= MAX_ROWS || c1 >= MAX_COLS { + return Err(invalid("invalid formula range")); + } + let range = Range::new(CellRef::new(r0, c0), CellRef::new(r1, c1)); + // An array formula's first cell is its range's top-left one. A shared formula's is the + // first cell that uses it, which need not be: the top-left cell may not share it. + let start_ok = if id == 427 { range.contains(first) } else { range.first == first }; + if !start_ok { + return Err(invalid("invalid formula range")); + } + Ok((range, rgce, rgcb)) + }; + let mut b = Bytes::new(payload); + let Ok((range, rgce, rgcb)) = read(&mut b).and_then(|r| b.finish().map(|()| r)) else { + kept(warnings, "malformed shared or array formulas"); + self.shared.insert(first, None); + self.arrays.insert(first, None); + return None; + }; + if id == 427 { + let text = decode_formula(&rgce, &rgcb, Mode::Shared(first), links, limits, budget, warnings); + let si = u32::try_from(self.shared.len()).unwrap_or(u32::MAX); + let shared = text.as_ref().map(|t| Arc::new(SharedFormula { range, rgce, rgcb, len: t.len(), si })); + self.shared.insert(first, shared); + return text.map(|text| CellFormula { + kind: FormulaKind::Shared, + text, + shared_index: Some(si), + range: Some(range), + ..CellFormula::default() + }); + } + let text = decode_formula(&rgce, &rgcb, Mode::Cell, links, limits, budget, warnings); + self.arrays.insert(first, text.as_ref().map(|_| range)); + text.map(|text| CellFormula { kind: FormulaKind::Array, text, range: Some(range), ..CellFormula::default() }) + } +} + fn value(id: u16, b: &mut Bytes<'_>, strings: usize, limits: &Limits, budget: &Budget) -> Result { let value = match id { 1 => CellValue::Empty, @@ -579,11 +741,25 @@ pub(crate) fn worksheet( let mut row: Option = None; let mut col = None; // BrtCellMeta applies to the cell record that follows it (a dynamic-array formula), as `cm` - // does in `.xlsx`: a one-based index into the metadata part's cell metadata. + // does in `.xlsx`: a one-based index into the metadata part's cell metadata. Excel may write + // the cell's BrtValueMeta (a rich value, such as a spill error) in between. let mut meta: Option = None; + let mut ranges = RangeFormulas::default(); + // The first cell of a shared or array formula, waiting for the record holding the formula. + let mut first: Option = None; while let Some((id, payload)) = records.next(warnings)? { let mut b = Bytes::new(payload); - let cell_metadata = meta.take(); + let cell_metadata = if id == 50 { meta } else { meta.take() }; + if let Some(at) = first.take() { + if matches!(id, 426 | 427) { + let f = ranges.range_formula(id, payload, at, links, limits, budget, warnings); + if let Some(cell) = row.as_mut().and_then(|r| r.cells.last_mut()).filter(|c| c.at == at) { + cell.formula = f; + } + continue; + } + kept(warnings, "a shared or array formula that is missing from the file"); + } match id { 49 => { let icmb = b.i32()?; @@ -648,10 +824,24 @@ pub(crate) fn worksheet( } let style = b.u32()?; let value = value(id, &mut b, strings, limits, budget)?; + let at = CellRef::new(current.index, c); let formula = if (8..=11).contains(&id) { let (rgce, rgcb) = cell_formula(&mut b)?; b.finish()?; - decode_formula(rgce, rgcb, links, limits, budget, warnings).map(|text| CellFormula { text, ..CellFormula::default() }) + match part_of(rgce, rgcb, at) { + None => decode_formula(rgce, rgcb, Mode::Cell, links, limits, budget, warnings) + .map(|text| CellFormula { text, ..CellFormula::default() }), + Some(Ok(Part::First)) => { + first = links.map(|_| at); + None + } + Some(Ok(Part::Of(start))) if links.is_some() => ranges.follower(at, start, links, limits, budget, warnings), + Some(Ok(Part::Of(_))) => None, + Some(Err(why)) => { + kept(warnings, why); + None + } + } } else { b.finish()?; None @@ -660,7 +850,7 @@ pub(crate) fn worksheet( budget.cell(limits)?; } current.cells.push(Cell { - at: CellRef::new(current.index, c), + at, style: style & 0x00FF_FFFF, phonetic: style & 0x0100_0000 != 0, value, diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index bed0adcd0..53b02f8a1 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -11,7 +11,7 @@ use std::sync::Arc; -use craft_sheet::{CellError, MAX_COLS, MAX_ROWS}; +use craft_sheet::{CellError, CellRef, MAX_COLS, MAX_ROWS}; use super::expr::{Anchor, BinOp, Expr, RefKind, Reference, SheetSel, UnOp}; use super::ftab::function; @@ -192,6 +192,14 @@ impl Bytes<'_> { const LAST_ROW: u32 = MAX_ROWS - 1; const LAST_COL: u32 = MAX_COLS - 1; +/// Where a formula lives: a cell formula's references hold coordinates; a shared formula's +/// relative tokens (`PtgRefN`, `PtgAreaN`) hold offsets from the shared formula's first cell. +#[derive(Clone, Copy, PartialEq)] +pub(super) enum Mode { + Cell, + Shared(CellRef), +} + /// RgceLoc ([MS-XLSB] 2.5.98.91): a row and a `ColRelShort` (14-bit column, then the /// column-relative and row-relative flags). In a cell formula the coordinates are absolute /// whatever the flags say; the flags only decide where `$` goes. @@ -203,9 +211,29 @@ fn anchor(row: u32, col: u16) -> Result { Ok(Anchor { row, col: c, row_abs: col & 0x8000 == 0, col_abs: col & 0x4000 == 0 }) } +/// RgceLocRel ([MS-XLSB] 2.5.98.92), in a shared formula: a relative row or column is an offset +/// from `base`, wrapping around the grid (1,048,576 rows, 16,384 columns), as Excel adds them. +/// An absolute one is a coordinate. +fn relative_anchor(row: u32, col: u16, base: CellRef) -> Result { + let (row_rel, col_rel) = (col & 0x8000 != 0, col & 0x4000 != 0); + let r = if row_rel { base.row.wrapping_add(row) % MAX_ROWS } else { row }; + let c = if col_rel { (base.col + u32::from(col & 0x3FFF)) % MAX_COLS } else { u32::from(col & 0x3FFF) }; + anchor(r, (c as u16) | (col & 0xC000)) +} + +fn loc(row: u32, col: u16, mode: Mode) -> Result { + match mode { + Mode::Cell => anchor(row, col), + Mode::Shared(base) => relative_anchor(row, col, base), + } +} + /// RgceArea: a range spanning every row (or column) is a whole-column (row) reference. fn area(r0: u32, r1: u32, c0: u16, c1: u16) -> Result { - let (a, b) = (anchor(r0, c0)?, anchor(r1, c1)?); + area_of(anchor(r0, c0)?, anchor(r1, c1)?) +} + +fn area_of(a: Anchor, b: Anchor) -> Result { Ok(if a.row == 0 && b.row == LAST_ROW { RefKind::Cols(a.col, a.col_abs, b.col, b.col_abs) } else if a.col == 0 && b.col == LAST_COL { @@ -222,10 +250,11 @@ fn reference(sheet: Option, kind: RefKind) -> Expr { } } -/// Decodes a cell formula's `rgce` (tokens) with its `rgcb` (extra data for array constants and +/// Decodes a formula's `rgce` (tokens) with its `rgcb` (extra data for array constants and /// cached areas). Returns the expression, with names in their file spelling, or why it can't be -/// represented. -pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links) -> Result { +/// represented. A shared formula's tokens are decoded once for each of its cells +/// (`Mode::Shared` with that cell), whose relative references are offsets from it. +pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Result { if rgce.len() > MAX_RGCE { return Err(Unsupported("formula too long")); } @@ -414,7 +443,17 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links) -> Result return Err(Unsupported("the shared or array formula form")), 0x02 => return Err(Unsupported("what-if data tables")), 0x18 => return Err(Unsupported("structured table references")), - 0x2C | 0x2D => return Err(Unsupported("relative references in a cell formula")), + 0x2C => { + let Mode::Shared(_) = mode else { return Err(Unsupported("relative references in a cell formula")) }; + let (r, c) = (t.u32()?, t.u16()?); + push(&mut stack, kids, Expr::Ref(Reference { sheet: SheetSel::Current, kind: RefKind::Cell(loc(r, c, mode)?) }))?; + } + 0x2D => { + let Mode::Shared(_) = mode else { return Err(Unsupported("relative references in a cell formula")) }; + let (r0, r1, c0, c1) = (t.u32()?, t.u32()?, t.u16()?, t.u16()?); + let kind = area_of(loc(r0, c0, mode)?, loc(r1, c1, mode)?)?; + push(&mut stack, kids, Expr::Ref(Reference { sheet: SheetSel::Current, kind }))?; + } _ => return Err(Unsupported("unknown formula token")), } if stack.len() > MAX_RGCE { diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 42c27158b..d2b03dbbd 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -5,7 +5,7 @@ mod common; use common::{read, read_with}; use craft_xlsx::testing::zip; -use craft_xlsx::{CellError, CellRef, Error, Limits, Range, SheetKind, Value, Visibility, is_xlsb}; +use craft_xlsx::{CellError, CellRef, Error, FormulaKind, Limits, Range, SheetKind, Value, Visibility, is_xlsb}; const ROOT: &str = r#""#; const RELS: &str = r#""#; @@ -546,7 +546,7 @@ fn cell_formulas_are_read_in_their_xlsx_spelling() { // Kept as their saved results: (11, vec![0x43, 4, 0, 0, 0, 0x1E, 2, 0, 0x05], vec![]), (12, ref3d(4, 0, REL), vec![]), - (13, vec![0x01, 0, 0, 0, 0], vec![0, 0, 0, 0]), + (13, vec![0x01, 0, 0, 0, 0], vec![0, 0, 0, 0]), // Part of a shared formula at A1 that isn't one. ]; let mut data = row(0); data.extend(cell(5, 0, &3.0f64.to_le_bytes())); @@ -580,11 +580,11 @@ fn cell_formulas_are_read_in_their_xlsx_spelling() { None, ]; assert_eq!(got, want); - assert!(sheet.formulas.values().all(|f| f.kind == craft_xlsx::FormulaKind::Normal)); + assert!(sheet.formulas.values().all(|f| f.kind == FormulaKind::Normal)); assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&CellRef::new(0, 14), &1)]); // Every formula cell keeps its saved result as its value. assert!((1..=15).all(|c| sheet.value(CellRef::new(0, c)) == Value::Number(0.0))); - for why in ["defined names", "other workbooks", "the shared or array formula form", "structured table references"] { + for why in ["defined names", "other workbooks", "missing from the file", "structured table references"] { assert!(warned(&wb, why), "{why}: {:?}", wb.warnings); } } @@ -709,3 +709,165 @@ fn formula_text_past_the_allowance_keeps_the_saved_result() { assert_eq!(wb.sheets[0].formula(CellRef::new(0, 1)), None); assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); } + +fn range_formula(id: u16, (r0, c0, r1, c1): (u32, u32, u32, u32), rgce: &[u8]) -> Vec { + let mut data = vec![]; + for n in [r0, r1, c0, c1] { + data.extend(n.to_le_bytes()); + } + if id == 426 { + data.push(0x08); // The flags Excel writes for an ordinary array. + } + data.extend((rgce.len() as u32).to_le_bytes()); + data.extend(rgce); + data.extend(0u32.to_le_bytes()); + record(id, &data) +} + +/// A cell of the shared or array formula whose first cell is `row`, `col` (PtgExp + PtgExtraCol). +fn part(col: u32, (row, first_col): (u32, u32)) -> Vec { + formula_cell(col, &[&[0x01u8][..], &row.to_le_bytes()].concat(), &first_col.to_le_bytes()) +} + +fn ref_n(row: i32, col: u16) -> Vec { + [&[0x4Cu8][..], &row.to_le_bytes(), &col.to_le_bytes()].concat() +} + +fn at(a1: &str) -> CellRef { + CellRef::parse(a1).unwrap() +} + +#[test] +fn shared_array_and_dynamic_formulas_read_as_from_xlsx() { + // As Excel writes them: C1:C3 share `A1*10` (PtgRefN, column offset -2 as 16382); D1:E2 + // share `$A1+A$1`; F1:F2 hold the Ctrl+Shift+Enter array {=A1:A2*2}; G1 spills `=A1:A2`. + let area = [&[0x45u8][..], &0u32.to_le_bytes(), &1u32.to_le_bytes(), &REL.to_le_bytes(), &REL.to_le_bytes()].concat(); + let mut data = row(0); + data.extend(cell(5, 0, &1.0f64.to_le_bytes())); + data.extend(part(2, (0, 2))); + data.extend(range_formula(427, (0, 2, 2, 2), &[ref_n(0, 16382 | REL), vec![0x1E, 10, 0, 0x05]].concat())); + data.extend(part(3, (0, 3))); + data.extend(range_formula(427, (0, 3, 1, 4), &[ref_n(0, 0x8000), ref_n(0, 16381 | 0x4000), vec![0x03]].concat())); + data.extend(part(4, (0, 3))); + data.extend(part(5, (0, 5))); + data.extend(range_formula(426, (0, 5, 1, 5), &[area.clone(), vec![0x1E, 2, 0, 0x05]].concat())); + data.extend(record(49, &1u32.to_le_bytes())); + data.extend(record(50, &1u32.to_le_bytes())); // BrtValueMeta in between, as Excel writes for a spill error. + data.extend(part(6, (0, 6))); + data.extend(range_formula(426, (0, 6, 1, 6), &area)); + data.extend(row(1)); + data.extend(cell(5, 0, &2.0f64.to_le_bytes())); + for (col, first) in [(2, (0, 2)), (3, (0, 3)), (4, (0, 3)), (5, (0, 5)), (6, (0, 6))] { + data.extend(part(col, first)); + } + data.extend(row(2)); + data.extend(part(2, (0, 2))); + let wb = read(&file(&worksheet(&data, &[]))).unwrap(); + let sheet = &wb.sheets[0]; + let formula = |a: &str| sheet.formulas.get(&at(a)); + // Each cell of a shared formula has its own text, decoded at the cell: the first with the + // group's range, all with its index. + for (a, want, si) in [ + ("C1", "A1*10", 0), + ("C2", "A2*10", 0), + ("C3", "A3*10", 0), + ("D1", "$A1+A$1", 1), + ("E1", "$A1+B$1", 1), + ("D2", "$A2+A$1", 1), + ("E2", "$A2+B$1", 1), + ] { + let f = formula(a).unwrap_or_else(|| panic!("{a}")); + assert_eq!((f.kind, f.text.as_str(), f.shared_index), (FormulaKind::Shared, want, Some(si)), "{a}"); + } + assert_eq!(formula("C1").and_then(|f| f.range), Range::parse("C1:C3")); + assert_eq!(formula("D1").and_then(|f| f.range), Range::parse("D1:E2")); + assert_eq!(formula("C2").and_then(|f| f.range), None); + // An array formula's first cell has it, with its range; a dynamic array's has its cell + // metadata too, as `cm` in .xlsx, though Excel wrote a BrtValueMeta in between. + let f1 = formula("F1").unwrap(); + assert_eq!((f1.kind, f1.text.as_str(), f1.range), (FormulaKind::Array, "A1:A2*2", Range::parse("F1:F2"))); + let g1 = formula("G1").unwrap(); + assert_eq!((g1.kind, g1.text.as_str(), g1.range), (FormulaKind::Array, "A1:A2", Range::parse("G1:G2"))); + assert_eq!(sheet.cell_metadata.get(&at("G1")), Some(&1)); + assert_eq!(sheet.cell_metadata.get(&at("F1")), None); + // Their other cells have no formula and keep their saved results, as in .xlsx. + for a in ["F2", "G2"] { + assert!(formula(a).is_none(), "{a}"); + assert_eq!(sheet.value(at(a)), Value::Number(0.0), "{a}"); + } + assert!(!wb.warnings.iter().any(|w| w.contains("kept as their saved results")), "{:?}", wb.warnings); +} + +#[test] +fn unreadable_shared_formulas_keep_their_values() { + // A shared formula with an unsupported token, a range that doesn't start at its first cell, + // a truncated record, and a first cell with no formula record after it: every cell of each + // keeps its saved result, and the file opens. + let unknown = range_formula(427, (0, 0, 1, 0), &[0xFF]); + let wrong_start = range_formula(427, (0, 1, 1, 1), &[0x1E, 1, 0]); + // A well-framed record whose payload stops before rgcb's length. + let short: Vec = [&[0u8; 4][..], &1u32.to_le_bytes(), &[0; 8], &3u32.to_le_bytes(), &[0x1E, 1, 0]].concat(); + let truncated = record(427, &short); + for after_first in [unknown, wrong_start, truncated, cell(5, 1, &1.0f64.to_le_bytes())] { + let data = [row(0), part(0, (0, 0)), after_first, row(1), part(0, (0, 0))].concat(); + let wb = read(&file(&worksheet(&data, &[]))).unwrap(); + for r in [0, 1] { + assert_eq!(wb.sheets[0].formula(CellRef::new(r, 0)), None); + assert_eq!(wb.sheets[0].value(CellRef::new(r, 0)), Value::Number(0.0)); + } + assert!(wb.warnings.iter().any(|w| w.contains("kept as their saved results")), "{:?}", wb.warnings); + } +} + +#[test] +fn shared_formulas_wrap_and_may_start_inside_their_range() { + // `=` the cell to the left (column offset -1, written 16383), shared over A1:B2 from B1: A1 + // isn't part of it. In column A the offset wraps around the grid, as [MS-XLSB] defines it. + let left = ref_n(0, 16383 | REL); + let data = [ + row(0), + cell(5, 0, &1.0f64.to_le_bytes()), + part(1, (0, 1)), + range_formula(427, (0, 0, 1, 1), &left), + row(1), + part(0, (0, 1)), + part(1, (0, 1)), + ] + .concat(); + let wb = read(&file(&worksheet(&data, &[]))).unwrap(); + let text = |a: &str| wb.sheets[0].formula(at(a)); + assert_eq!((text("A1"), text("B1"), text("A2"), text("B2")), (None, Some("A1"), Some("XFD2"), Some("A2"))); + assert!(!wb.warnings.iter().any(|w| w.contains("kept as their saved results")), "{:?}", wb.warnings); +} + +#[test] +fn a_shared_formula_copy_may_be_longer_than_its_first_cell() { + // SUM of nine SUMs of 255 references to the cell on the left: about 6,900 characters at B9, + // over 18,000 at B999999, where each `A9` is `A999999`. Each copy has its own text. + let mut rgce = vec![]; + for _ in 0..9 { + for _ in 0..255 { + rgce.extend(ref_n(0, 16383 | REL)); + } + rgce.extend([0x22, 255, 4, 0]); + } + rgce.extend([0x22, 9, 4, 0]); + let data = [row(8), part(1, (8, 1)), range_formula(427, (8, 1, 999_998, 1), &rgce), row(999_998), part(1, (8, 1))].concat(); + let wb = read(&file(&worksheet(&data, &[]))).unwrap(); + let (b9, last) = (wb.sheets[0].formula(at("B9")).unwrap(), wb.sheets[0].formula(at("B999999")).unwrap()); + assert!(b9.len() < 8192 && last.len() > 18_000, "{} {}", b9.len(), last.len()); + assert!(last.starts_with("SUM(SUM(A999999,A999999"), "{}", &last[..40]); +} + +#[test] +fn shared_formula_copies_are_charged_before_they_are_made() { + // A1:A3 share `1+1` (3 bytes); with 6 bytes allowed, the first cell and one copy fit, and the + // last copy keeps its value without being decoded. + let one_plus_one = [0x1E, 1, 0, 0x1E, 1, 0, 0x03]; + let data = [row(0), part(0, (0, 0)), range_formula(427, (0, 0, 2, 0), &one_plus_one), row(1), part(0, (0, 0)), row(2), part(0, (0, 0))].concat(); + let limits = Limits { binary_formula_text: 6, ..Limits::default() }; + let wb = read_with(&file(&worksheet(&data, &[])), &limits).unwrap(); + let got: Vec<_> = (0..3).map(|r| wb.sheets[0].formula(CellRef::new(r, 0))).collect(); + assert_eq!(got, [Some("1+1"), Some("1+1"), None]); + assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); +} From 1f5f1f0f5143c312650c972bae48961414906b00 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 23:36:18 -0500 Subject: [PATCH 010/349] craft-xlsx: a shared formula stops decoding copies once one is kept as its value From gridcraft#3821's review (CodeRabbit, still open there): a shared formula's copies are checked against the formula text allowance with the first cell's length, which a copy can exceed. A copy that was decoded and printed, then kept as its value because it didn't fit, or because it couldn't be decoded, charged nothing, so a file with many cells of one long shared formula could repeat that work for each of them. The PR's case was GridCraft's 8,192-character rejection, which isn't here; the allowance and decode failures are the same path. After one such copy the group keeps every later copy as its value without decoding it, so a group costs at most one wasted decode. A new test shows a later copy that would have fit kept as its value; it fails without this commit. --- crates/xlsx/src/xlsb.rs | 13 ++++++++++--- crates/xlsx/tests/xlsb.rs | 14 ++++++++++++++ 2 files changed, 24 insertions(+), 3 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index dfea974b6..d0bf980c9 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -589,7 +589,7 @@ impl RangeFormulas { /// fit isn't decoded at all, so a long formula shared by a million cells stops costing once /// the allowance is spent. An array formula's other cells have none, as in `.xlsx`. fn follower( - &self, + &mut self, at: CellRef, first: CellRef, links: Option<&Links>, @@ -598,7 +598,7 @@ impl RangeFormulas { warnings: &mut Warnings, ) -> Option { if let Some(shared) = self.shared.get(&first) { - let sh = shared.as_ref()?; + let sh = shared.clone()?; if !sh.range.contains(at) { kept(warnings, "malformed shared or array formula references"); return None; @@ -607,7 +607,14 @@ impl RangeFormulas { kept(warnings, "more formula text than the limits allow"); return None; } - let text = decode_formula(&sh.rgce, &sh.rgcb, Mode::Shared(at), links, limits, budget, warnings)?; + let Some(text) = decode_formula(&sh.rgce, &sh.rgcb, Mode::Shared(at), links, limits, budget, warnings) else { + // A copy that was decoded but kept as its value charged nothing: one past the + // allowance (it may be longer than the first cell's estimate) or one that can't be + // decoded. The group's later copies would fail the same way, so they keep their + // values without being decoded: a group costs at most one wasted decode. + self.shared.insert(first, None); + return None; + }; return Some(CellFormula { kind: FormulaKind::Shared, text, shared_index: Some(sh.si), ..CellFormula::default() }); } match self.arrays.get(&first) { diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index d2b03dbbd..3f1c51b7f 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -871,3 +871,17 @@ fn shared_formula_copies_are_charged_before_they_are_made() { assert_eq!(got, [Some("1+1"), Some("1+1"), None]); assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); } + +#[test] +fn a_shared_formula_stops_decoding_copies_once_one_is_kept_as_its_value() { + // A1:Z2 share `=` the cell to the right. A1 is `B1` (2 bytes), Z1's copy is `AA1` (3): it + // passes the estimate from the first cell but not the allowance, after being decoded. The + // group's later copies keep their values without being decoded, though B2's (`C2`) would fit. + let right = ref_n(0, 1 | REL); + let data = [row(0), part(0, (0, 0)), range_formula(427, (0, 0, 1, 25), &right), part(25, (0, 0)), row(1), part(1, (0, 0))].concat(); + let limits = Limits { binary_formula_text: 4, ..Limits::default() }; + let wb = read_with(&file(&worksheet(&data, &[])), &limits).unwrap(); + let text = |a: &str| wb.sheets[0].formula(at(a)); + assert_eq!((text("A1"), text("Z1"), text("B2")), (Some("B1"), None, None)); + assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); +} From 20050077adcd794cfef32805f73de6191069962d Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Thu, 12 Nov 2026 23:36:47 -0500 Subject: [PATCH 011/349] craft-xlsx: the README describes formulas in binary workbooks They were "token streams that are not decoded". The README now says what the decoder gives (text in the file's spelling, shared and array kinds and ranges, cell metadata, each shared copy's own text), what keeps its saved result and why, that the function table and printer are this crate's own, and the binary_formula_text limit with the decoder's fixed bounds. --- crates/xlsx/README.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 3d3808ad3..1dc30574d 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -83,9 +83,15 @@ for new pictures (`vm = i + 1`) and the `XLDAPR` dynamic-array metadata (`cm = 1 The parts this crate writes use the transitional namespaces; a strict file's kept parts stay as they were. A binary workbook is not written. -A binary workbook gives the same `Workbook`, strings, rows and merged cells, with saved values -only: its formulas are token streams that are not decoded, and its styles are not read (each -cell keeps its format index). +A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not +read (each cell keeps its format index). Its cell formulas are decoded from their tokens into the +text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with +`FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell +metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the +file keeps the tokens once. A formula whose decoding needs something the reader does not read +keeps only its saved result, with a warning saying why: user defined names, table references, +other workbooks, Python code stored outside the cell, data tables. The XLSB function table +(`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from `craft-xls`'s. ## Hostile input @@ -94,7 +100,9 @@ cell keeps its format index). string and what is left of a part, not a sheet's length. - `Limits.binary_records`, `binary_cells`, `binary_text`: a binary workbook, over all its parts (40 million records, 4 million cells and as many shared strings, 256 MiB of text, as - `craft-xls` allows). Fixed caps: 1024 sheets, 100,000 merged ranges per sheet, 64 nested + `craft-xls` allows). `binary_formula_text`: decoded formula text over the workbook (128 MiB); + past it, formulas keep their saved results. A formula's tokens are bounded at 16 KB, its + nesting at 256 levels and an array constant at 65,536 values. Fixed caps: 1024 sheets, 100,000 merged ranges per sheet, 64 nested extension blocks. - Cells and rows outside the 1,048,576 × 16,384 grid are dropped and counted. From 79b4fd014497d72305aa2ff7e2802127d42e37fa Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Fri, 13 Nov 2026 00:04:32 -0500 Subject: [PATCH 012/349] craft-xlsx: review fixes: CONVERT, shared formula tokens borrowed, cell metadata with its formula From the first review round: - 468 (0x1D4) is CONVERT, with 3 arguments. [MS-XLSB]'s Ftab table has no row for it, though its grammar lists convert-params among the fixed-argument functions; Excel writes =CONVERT(1,"m","ft") in .xlsb as a PtgFunc calling 0x1D4 (observed in Excel). It was the only unassigned number from 0x17C to 0x1E4. The module doc says it isn't the specification's row. - A BrtShrFmla's tokens and extra data are borrowed from the worksheet part instead of copied: a record may claim up to 256 MiB, and each shared formula is kept for the rest of the sheet, so the copies could cost as much again as the part. BrtArrFmla's are used at once and borrowed too. - A formula record's cell metadata goes with its formula: when the formula is kept as its value (tokens the reader can't decode, an unreadable BrtArrFmla), the cell loses its `cm`, which would otherwise mark a dynamic-array formula that isn't there. A value cell keeps its cell metadata, as the file has it. The CONVERT and cell-metadata tests fail without this commit. The Excel-saved workbook still reads with all 33 formulas as in its .xlsx. --- crates/xlsx/src/xlsb.rs | 46 +++++++++++++++++++++++------------- crates/xlsx/src/xlsb/ftab.rs | 9 ++++++- crates/xlsx/tests/xlsb.rs | 33 ++++++++++++++++++++++++++ 3 files changed, 71 insertions(+), 17 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index d0bf980c9..d46c2ea20 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -542,11 +542,14 @@ fn kept(warnings: &mut Warnings, why: &str) { } /// A `BrtShrFmla`: the cells it may cover, its tokens, its first cell's text length (what a copy -/// is expected to cost) and the group's index (`si`). -struct SharedFormula { +/// is expected to cost) and the group's index (`si`). The tokens are borrowed from the worksheet +/// part, which outlives the sheet's read: a record can be up to 256 MiB, and copying every +/// shared formula's would cost as much again as the part. +#[derive(Clone, Copy)] +struct SharedFormula<'a> { range: Range, - rgce: Vec, - rgcb: Vec, + rgce: &'a [u8], + rgcb: &'a [u8], len: usize, si: u32, } @@ -576,12 +579,12 @@ fn part_of(rgce: &[u8], rgcb: &[u8], at: CellRef) -> Option>>, +struct RangeFormulas<'a> { + shared: HashMap>>, arrays: HashMap>, } -impl RangeFormulas { +impl<'a> RangeFormulas<'a> { /// The formula of another cell `at` of the shared or array formula starting at `first`. A /// shared formula's copy is decoded from the shared tokens at its own cell, as [MS-XLSB] /// defines it (relative offsets wrap around the grid), and checked like any formula: its text @@ -598,7 +601,7 @@ impl RangeFormulas { warnings: &mut Warnings, ) -> Option { if let Some(shared) = self.shared.get(&first) { - let sh = shared.clone()?; + let sh = (*shared)?; if !sh.range.contains(at) { kept(warnings, "malformed shared or array formula references"); return None; @@ -607,7 +610,7 @@ impl RangeFormulas { kept(warnings, "more formula text than the limits allow"); return None; } - let Some(text) = decode_formula(&sh.rgce, &sh.rgcb, Mode::Shared(at), links, limits, budget, warnings) else { + let Some(text) = decode_formula(sh.rgce, sh.rgcb, Mode::Shared(at), links, limits, budget, warnings) else { // A copy that was decoded but kept as its value charged nothing: one past the // allowance (it may be longer than the first cell's estimate) or one that can't be // decoded. The group's later copies would fail the same way, so they keep their @@ -634,14 +637,14 @@ impl RangeFormulas { fn range_formula( &mut self, id: u16, - payload: &[u8], + payload: &'a [u8], first: CellRef, links: Option<&Links>, limits: &Limits, budget: &Budget, warnings: &mut Warnings, ) -> Option { - let read = |b: &mut Bytes<'_>| -> Result<(Range, Vec, Vec), Error> { + let read = |b: &mut Bytes<'a>| -> Result<(Range, &'a [u8], &'a [u8]), Error> { let (r0, r1, c0, c1) = (b.u32()?, b.u32()?, b.u32()?, b.u32()?); if id == 426 { b.u8()?; // Only fAlwaysCalc, the calculator's to know. @@ -650,9 +653,9 @@ impl RangeFormulas { if !(1..=16384).contains(&cce) { return Err(invalid("invalid formula token length")); } - let rgce = b.take(cce as usize)?.to_vec(); + let rgce = b.take(cce as usize)?; let cb = b.u32()?; - let rgcb = b.take(cb as usize)?.to_vec(); + let rgcb = b.take(cb as usize)?; if r0 > r1 || c0 > c1 || r1 >= MAX_ROWS || c1 >= MAX_COLS { return Err(invalid("invalid formula range")); } @@ -673,9 +676,9 @@ impl RangeFormulas { return None; }; if id == 427 { - let text = decode_formula(&rgce, &rgcb, Mode::Shared(first), links, limits, budget, warnings); + let text = decode_formula(rgce, rgcb, Mode::Shared(first), links, limits, budget, warnings); let si = u32::try_from(self.shared.len()).unwrap_or(u32::MAX); - let shared = text.as_ref().map(|t| Arc::new(SharedFormula { range, rgce, rgcb, len: t.len(), si })); + let shared = text.as_ref().map(|t| SharedFormula { range, rgce, rgcb, len: t.len(), si }); self.shared.insert(first, shared); return text.map(|text| CellFormula { kind: FormulaKind::Shared, @@ -685,7 +688,7 @@ impl RangeFormulas { ..CellFormula::default() }); } - let text = decode_formula(&rgce, &rgcb, Mode::Cell, links, limits, budget, warnings); + let text = decode_formula(rgce, rgcb, Mode::Cell, links, limits, budget, warnings); self.arrays.insert(first, text.as_ref().map(|_| range)); text.map(|text| CellFormula { kind: FormulaKind::Array, text, range: Some(range), ..CellFormula::default() }) } @@ -761,6 +764,11 @@ pub(crate) fn worksheet( if matches!(id, 426 | 427) { let f = ranges.range_formula(id, payload, at, links, limits, budget, warnings); if let Some(cell) = row.as_mut().and_then(|r| r.cells.last_mut()).filter(|c| c.at == at) { + // A dynamic array's cell metadata describes its formula: with none kept, the + // cell is a value, and `cm` on it would mark a formula that isn't there. + if f.is_none() { + cell.cell_metadata = None; + } cell.formula = f; } continue; @@ -856,6 +864,12 @@ pub(crate) fn worksheet( if value != CellValue::Empty { budget.cell(limits)?; } + // A formula record's cell metadata describes its formula (a dynamic array), so a + // formula kept as its value drops it; the first cell of a shared or array formula + // keeps it until its formula record is read. Other cells keep theirs as the file + // has it. + let formula_kept = !(8..=11).contains(&id) || formula.is_some() || first == Some(at); + let cell_metadata = cell_metadata.filter(|_| formula_kept); current.cells.push(Cell { at, style: style & 0x00FF_FFFF, diff --git a/crates/xlsx/src/xlsb/ftab.rs b/crates/xlsx/src/xlsb/ftab.rs index 87f369519..efd6e4426 100644 --- a/crates/xlsx/src/xlsb/ftab.rs +++ b/crates/xlsx/src/xlsb/ftab.rs @@ -3,6 +3,10 @@ //! which craft-xls also carries. The entries from 380 (0x17C) on are the rest of the XLSB table: //! XLSB files call these functions by number, where `.xls` files call them by name. Kept apart from //! craft-xls's copy: the two formats follow separate specifications. +//! +//! One entry is not in the specification's table: 468 (0x1D4) is CONVERT. The table has no row +//! for it, but its grammar lists `convert-params` among the fixed-argument functions, and Excel +//! writes `=CONVERT(1,"m","ft")` in `.xlsb` as a `PtgFunc` calling 0x1D4. /// (iftab, name, fixed argument count or -1 when the function takes a variable number of /// arguments), sorted by number. @@ -467,6 +471,7 @@ const FTAB: &[(u16, &str, i8)] = &[ (465, "WEEKNUM", -1), (466, "AMORDEGRC", -1), (467, "AMORLINC", -1), + (468, "CONVERT", 3), (469, "ACCRINT", -1), (470, "ACCRINTM", -1), (471, "WORKDAY", -1), @@ -508,7 +513,9 @@ mod tests { assert_eq!(function(449), Some(("EDATE", 2))); assert_eq!(function(480), Some(("IFERROR", 2))); assert_eq!(function(482), Some(("SUMIFS", -1))); - assert_eq!(function(0x1D4), None, "unassigned"); + // Not in the specification's table, but what Excel writes for CONVERT. + assert_eq!(function(0x1D4), Some(("CONVERT", 3))); + assert_eq!(function(0x17B), Some(("RTD", -1))); assert_eq!(function(0x1E5), None); } } diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 3f1c51b7f..518ca5214 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -885,3 +885,36 @@ fn a_shared_formula_stops_decoding_copies_once_one_is_kept_as_its_value() { assert_eq!((text("A1"), text("Z1"), text("B2")), (Some("B1"), None, None)); assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); } + +#[test] +fn convert_is_called_by_its_number_as_excel_writes_it() { + // Excel's tokens for `=CONVERT(1,"m","ft")` in .xlsb: PtgFunc 0x1D4, which the + // specification's Ftab table leaves out. + let rgce = [0x1E, 0x01, 0x00, 0x17, 0x01, 0x00, 0x6D, 0x00, 0x17, 0x02, 0x00, 0x66, 0x00, 0x74, 0x00, 0x41, 0xD4, 0x01]; + let wb = read(&file(&worksheet(&[row(0), formula_cell(0, &rgce, &[])].concat(), &[]))).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), Some("CONVERT(1,\"m\",\"ft\")")); +} + +#[test] +fn a_dynamic_array_kept_as_its_value_has_no_cell_metadata() { + let meta = record(49, &1u32.to_le_bytes()); + let table_ref = [0x18, 0x19, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0]; + let data = [ + row(0), + // A1: a dynamic-array formula the reader can't decode (a table reference). + meta.clone(), + formula_cell(0, &table_ref, &[]), + // B1:B2: a dynamic array whose BrtArrFmla holds an unknown token. + meta.clone(), + part(1, (0, 1)), + range_formula(426, (0, 1, 1, 1), &[0xFF]), + // C1: a value with cell metadata keeps it, as the file has it. + meta, + cell(5, 2, &1.0f64.to_le_bytes()), + ] + .concat(); + let wb = read(&file(&worksheet(&data, &[]))).unwrap(); + let sheet = &wb.sheets[0]; + assert_eq!((sheet.formula(at("A1")), sheet.formula(at("B1"))), (None, None)); + assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&at("C1"), &1)]); +} From fd8a0dcf22b7e2d59393a5852727700d39fdebce Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Fri, 13 Nov 2026 19:12:02 -0500 Subject: [PATCH 013/349] craft-xlsx: review fixes: a long string chain stays within the depth bound; pending array metadata From the second review round (FredApps): - Strings joined with `&` are printed as one flat chain, which nests one level per string. A balanced tree of 4,096 empty strings fits in 16,383 token bytes and is 13 levels deep, but as a chain it was 4,096 levels, and printing and dropping it recurse: on a 256 KiB stack it overflowed. The chain is now made only up to MAX_DEPTH strings, the bound push keeps on the decoded tree (Excel's 8,192 characters hold at most about 33 full-length constants, so Python code split into constants is unaffected). A longer one prints as its tokens nest, with the parentheses that needs. GridCraft's tree walks a left-deep chain in a loop; the printer copied from craft-xls recurses, which is how the port lost the bound. - The first cell of a shared or array formula whose BrtShrFmla/BrtArrFmla never comes (another cell or the next row follows) loses its cell metadata too, as a formula kept as its value does. The new unit test overflowed its stack without this commit; the extended metadata test fails without it. The Excel-saved workbook still reads with all 33 formulas as in its .xlsx. --- crates/xlsx/src/xlsb.rs | 4 +++ crates/xlsx/src/xlsb/formula.rs | 61 +++++++++++++++++++++++++++++++-- crates/xlsx/tests/xlsb.rs | 16 +++++++-- 3 files changed, 77 insertions(+), 4 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index d46c2ea20..2fdde59be 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -773,6 +773,10 @@ pub(crate) fn worksheet( } continue; } + // No formula record: the cell stays a value, so its formula's cell metadata goes too. + if let Some(cell) = row.as_mut().and_then(|r| r.cells.last_mut()).filter(|c| c.at == at) { + cell.cell_metadata = None; + } kept(warnings, "a shared or array formula that is missing from the file"); } match id { diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 53b02f8a1..327ffcc25 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -477,6 +477,15 @@ fn literal_text(e: &Expr) -> bool { } } +/// How many strings a [`literal_text`] chain joins, or `None` for anything else. +fn literal_texts(e: &Expr) -> Option { + match e { + Expr::Text(_) => Some(1), + Expr::Binary(BinOp::Concat, a, b) => literal_texts(a)?.checked_add(literal_texts(b)?), + _ => None, + } +} + /// How tightly an expression binds when printed, as the formula parser reads it: binary /// operators by [`BinOp::precedence`], prefix `+`/`-` at 60 and `%` at 70 (`-2^2` is `(-2)^2`); /// anything else is one operand. @@ -512,8 +521,13 @@ fn paren(e: Expr) -> Expr { fn grouped(e: Expr, in_args: bool) -> Expr { match e { // Strings joined with `&` are written as one flat chain, however their tokens nest: `&` - // is associative, and `PY("…"&"…")` is read as Python code only in that form. - e @ Expr::Binary(BinOp::Concat, ..) if literal_text(&e) => { + // is associative, and `PY("…"&"…")` is read as Python code only in that form. The chain + // nests one level per string, so it is made only up to `MAX_DEPTH` strings, the bound + // `push` keeps on the decoded tree (Excel's 8,192 characters hold at most about 33 + // full-length constants). A longer one prints as its tokens nest, with the parentheses + // that needs: a balanced tree of thousands of strings is only a few levels deep, and + // printing or dropping a chain of thousands would recurse past the stack. + e @ Expr::Binary(BinOp::Concat, ..) if literal_texts(&e).is_some_and(|n| n <= MAX_DEPTH) => { let mut texts = vec![]; flatten_texts(e, &mut texts); let mut texts = texts.into_iter(); @@ -575,3 +589,46 @@ fn array_constant(b: &mut Bytes<'_>) -> Result { } Ok(Expr::Array(out)) } + +#[cfg(test)] +mod tests { + use super::*; + + /// Postfix tokens for `n` empty strings joined by `&` as a balanced tree. + fn balanced_strings(n: usize, out: &mut Vec) { + if n == 1 { + out.extend([0x17, 0, 0]); + } else { + balanced_strings(n / 2, out); + balanced_strings(n - n / 2, out); + out.push(0x08); + } + } + + #[test] + fn a_long_chain_of_strings_stays_within_the_depth_bound() { + // 4,096 strings and 4,095 `&` fill 16,383 token bytes, 13 levels deep as written. Made + // into one flat chain they would be 4,096 levels deep, past what printing and dropping + // the tree may recurse; on a small stack that overflows. They print as written instead. + let mut rgce = vec![]; + balanced_strings(4096, &mut rgce); + assert!(rgce.len() <= MAX_RGCE); + let text = std::thread::Builder::new() + .stack_size(256 * 1024) + .spawn(move || { + let e = decode(&rgce, &[], &Links::default(), Mode::Cell).unwrap(); + let text = super::super::expr::print(&e); + drop(e); + text + }) + .unwrap() + .join() + .unwrap(); + assert_eq!(text.matches("\"\"").count(), 4096); + // A short chain, such as Python code split into constants, is still one flat chain. + let mut short = vec![]; + balanced_strings(4, &mut short); + let e = decode(&short, &[], &Links::default(), Mode::Cell).unwrap(); + assert_eq!(super::super::expr::print(&e), "\"\"&\"\"&\"\"&\"\""); + } +} diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 518ca5214..ee9ac3afd 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -909,12 +909,24 @@ fn a_dynamic_array_kept_as_its_value_has_no_cell_metadata() { part(1, (0, 1)), range_formula(426, (0, 1, 1, 1), &[0xFF]), // C1: a value with cell metadata keeps it, as the file has it. - meta, + meta.clone(), cell(5, 2, &1.0f64.to_le_bytes()), + // D1: the first cell of a dynamic array with no BrtArrFmla after it, then a value, E1. + meta.clone(), + part(3, (0, 3)), + cell(5, 4, &1.0f64.to_le_bytes()), + // F1: the same as the last cell of its row. + meta, + part(5, (0, 5)), + row(1), + cell(5, 0, &1.0f64.to_le_bytes()), ] .concat(); let wb = read(&file(&worksheet(&data, &[]))).unwrap(); let sheet = &wb.sheets[0]; - assert_eq!((sheet.formula(at("A1")), sheet.formula(at("B1"))), (None, None)); + for a in ["A1", "B1", "D1", "F1"] { + assert_eq!(sheet.formula(at(a)), None, "{a}"); + } assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&at("C1"), &1)]); + assert!(warned(&wb, "missing from the file"), "{:?}", wb.warnings); } From 3e957e0fd1a9821221154bb151b4debab5f30955 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Fri, 13 Nov 2026 23:35:18 -0500 Subject: [PATCH 014/349] craft-xlsx: read the styles part of a binary workbook Package::styles() reads styles.bin into the same Styles the XML part gives: number formats, fonts, fills, borders, cell and cell style formats, cell styles, differential formats and indexed colours, spelled as Excel writes them in styles.xml. A damaged part is a warning and no styles; each table holds at most 65,536 entries. Closes #1253. --- crates/xlsx/README.md | 7 +- crates/xlsx/src/document.rs | 4 +- crates/xlsx/src/package.rs | 20 +- crates/xlsx/src/xlsb.rs | 6 +- crates/xlsx/src/xlsb/styles.rs | 471 +++++++++++++++++++++++++++++++++ crates/xlsx/tests/xlsb.rs | 266 ++++++++++++++++++- 6 files changed, 764 insertions(+), 10 deletions(-) create mode 100644 crates/xlsx/src/xlsb/styles.rs diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 1dc30574d..b2b581112 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -83,8 +83,11 @@ for new pictures (`vm = i + 1`) and the `XLDAPR` dynamic-array metadata (`cm = 1 The parts this crate writes use the transitional namespaces; a strict file's kept parts stay as they were. A binary workbook is not written. -A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not -read (each cell keeps its format index). Its cell formulas are decoded from their tokens into the +A binary workbook gives the same `Workbook`, strings, rows and merged cells, and the same +`Styles`: number formats, fonts, fills, borders, cell and cell style formats, cell styles, +differential formats and the indexed colours, as Excel writes them in `styles.xml` (default fill +colours and empty settings left out, a cell style format's `apply*="0"`). Custom table styles and +recent colours are not read; a damaged styles part is a warning and no styles. Its cell formulas are decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with `FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the diff --git a/crates/xlsx/src/document.rs b/crates/xlsx/src/document.rs index 26e6a84c6..1be23029e 100644 --- a/crates/xlsx/src/document.rs +++ b/crates/xlsx/src/document.rs @@ -209,8 +209,8 @@ pub struct Document { } impl Document { - /// Reads every part. A binary workbook is refused: its formulas and styles are not read, so - /// it cannot be written back as SpreadsheetML without loss. + /// Reads every part. A binary workbook is refused: only some of its parts are read, so it + /// cannot be written back as SpreadsheetML without loss. pub fn read(bytes: &[u8], limits: &Limits) -> Result { let mut p = Package::open(bytes, limits)?; if p.is_binary() { diff --git a/crates/xlsx/src/package.rs b/crates/xlsx/src/package.rs index 8f2c5efc6..f16b20d57 100644 --- a/crates/xlsx/src/package.rs +++ b/crates/xlsx/src/package.rs @@ -214,16 +214,28 @@ impl<'a> Package<'a> { Ok(items) } - /// The styles part, `None` when the workbook has none (or is binary: its styles are not read). + /// The styles part, `None` when the workbook has none. A damaged one is a warning and `None`; + /// only a limit is an error. pub fn styles(&mut self) -> Result, Error> { - if self.binary.is_some() { - return Ok(None); - } let rels = self.workbook_rels()?; let Some(rel) = rels.first("styles").filter(|r| !r.external) else { self.warn("no styles part"); return Ok(None); }; + if let Some(types) = &self.binary { + let read = xlsb::check_type(types, &rel.target, xlsb::STYLES).and_then(|()| { + let bytes = self.opc.read(&rel.target)?.ok_or_else(|| xlsb::invalid(format!("missing part {}", rel.target)))?; + xlsb::styles(&bytes, &self.limits, &self.budget, &mut self.warnings) + }); + return match read { + Ok(styles) => Ok(Some(styles)), + Err(Error::TooLarge(m)) => Err(Error::TooLarge(m)), + Err(e) => { + self.warn(format!("skipped {}: {e}", rel.target)); + Ok(None) + } + }; + } Ok(self.optional_xml(&rel.target.clone())?.map(Styles::read)) } diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 2fdde59be..50da6185c 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -1,11 +1,13 @@ //! Binary workbooks ([MS-XLSB]): the workbook part, shared strings and worksheet cells, from //! their records. Cell formulas are decoded from their tokens ([`formula`]) into the text an //! `.xlsx` file holds; one that can't be keeps only its saved result, with a warning saying why. -//! Styles are not read. A record that does not parse fails the read. +//! The styles part is read into the same [`crate::styles::Styles`] ([`styles`]). A record that +//! does not parse fails the read. mod expr; mod formula; mod ftab; +mod styles; use std::collections::HashMap; use std::sync::Arc; @@ -19,11 +21,13 @@ use crate::workbook::{SheetEntry, SheetKind, Workbook}; use crate::{Error, Limits, Warnings}; pub(crate) use formula::Links; use formula::{Book, Mode, Name, Xti}; +pub(crate) use styles::styles; pub(crate) const MAIN: &str = "application/vnd.ms-excel.main"; const BINARY_MAIN: &str = "application/vnd.ms-excel.sheet.binary.macroEnabled.main"; pub(crate) const WORKSHEET: &str = "application/vnd.ms-excel.worksheet"; pub(crate) const STRINGS: &str = "application/vnd.ms-excel.sharedStrings"; +pub(crate) const STYLES: &str = "application/vnd.ms-excel.styles"; /// Most sheets in the workbook. const MAX_SHEETS: usize = 1024; /// Most merged ranges in one worksheet. diff --git a/crates/xlsx/src/xlsb/styles.rs b/crates/xlsx/src/xlsb/styles.rs new file mode 100644 index 000000000..094620a07 --- /dev/null +++ b/crates/xlsx/src/xlsb/styles.rs @@ -0,0 +1,471 @@ +//! The styles part of a binary workbook (`styles.bin`, [MS-XLSB] 2.1.7.50), read into the same +//! [`Styles`] the XML part gives: what Excel writes in `styles.xml` for the same workbook. Table +//! styles, recent colours and future records are not read. + +use craft_sheet::{BorderStyle, HAlign, Pattern, Script, Underline, VAlign}; +use craft_xml::El; + +use super::{Budget, Bytes, Records, invalid}; +use crate::styles::{ + Alignment, Border, BorderEdge, CellStyle, Color, ColorSource, Dxf, Fill, Font, FontScheme, GradientFill, NumFmt, PatternFill, Protection, Styles, + Xf, +}; +use crate::{Error, Limits, Warnings}; + +/// Characters of a font name or number format kept, as the XML side keeps of a font name. +const MAX_NAME_CHARS: usize = 255; +/// Longest string read from the part (Excel's own limits are 31 and 255 characters). +const MAX_STRING_UNITS: u32 = 32_767; +/// Most stops in one gradient fill (Excel writes a handful). +const MAX_STOPS: u32 = 1024; +/// Most entries in one table of the part (Excel allows about 64,000 cell formats). Each entry is +/// an allocation, and the record allowance alone would let a small part hold millions. +const MAX_ENTRIES: usize = 65_536; + +/// `BrtColor` and `XFPropColor`: the same eight bytes. `None` for "not set" (`XFPropColor` type 4). +fn color(b: &mut Bytes<'_>) -> Result, Error> { + let kind = b.u8()? >> 1; + let index = b.u8()?; + let tint = i16::from_le_bytes(<[u8; 2]>::try_from(b.take(2)?).map_err(|_| invalid("truncated colour"))?); + let [r, g, bl, a] = <[u8; 4]>::try_from(b.take(4)?).map_err(|_| invalid("truncated colour"))?; + let source = match kind { + 0 => ColorSource::Auto, + 1 => ColorSource::Indexed(u32::from(index)), + 2 => ColorSource::Rgb(u32::from_be_bytes([a, r, g, bl])), + 3 => ColorSource::Theme(u32::from(index)), + _ => return Ok(None), + }; + Ok(Some(Color { source, tint: (f64::from(tint) / 32767.0).clamp(-1.0, 1.0) })) +} + +fn pattern(fls: u32) -> Result { + const PATTERNS: [Pattern; 19] = [ + Pattern::None, + Pattern::Solid, + Pattern::Gray50, + Pattern::Gray75, + Pattern::Gray25, + Pattern::DarkHorizontal, + Pattern::DarkVertical, + Pattern::DarkDown, + Pattern::DarkUp, + Pattern::DarkGrid, + Pattern::DarkTrellis, + Pattern::LightHorizontal, + Pattern::LightVertical, + Pattern::LightDown, + Pattern::LightUp, + Pattern::LightGrid, + Pattern::LightTrellis, + Pattern::Gray125, + Pattern::Gray0625, + ]; + PATTERNS.get(fls as usize).copied().ok_or_else(|| invalid("unknown fill pattern")) +} + +fn border_style(dg: u16) -> Result { + const STYLES: [BorderStyle; 14] = [ + BorderStyle::None, + BorderStyle::Thin, + BorderStyle::Medium, + BorderStyle::Dashed, + BorderStyle::Dotted, + BorderStyle::Thick, + BorderStyle::Double, + BorderStyle::Hair, + BorderStyle::MediumDashed, + BorderStyle::DashDot, + BorderStyle::MediumDashDot, + BorderStyle::DashDotDot, + BorderStyle::MediumDashDotDot, + BorderStyle::SlantDashDot, + ]; + STYLES.get(usize::from(dg)).copied().ok_or_else(|| invalid("unknown border style")) +} + +fn halign(alc: u32) -> Option { + [HAlign::General, HAlign::Left, HAlign::Center, HAlign::Right, HAlign::Fill, HAlign::Justify, HAlign::CenterAcross, HAlign::Distributed] + .get(alc as usize) + .copied() +} + +fn valign(alcv: u32) -> Option { + [VAlign::Top, VAlign::Center, VAlign::Bottom, VAlign::Justify, VAlign::Distributed].get(alcv as usize).copied() +} + +fn underline(uls: u32) -> Underline { + match uls { + 0 => Underline::None, + 2 => Underline::Double, + 0x21 => Underline::SingleAccounting, + 0x22 => Underline::DoubleAccounting, + _ => Underline::Single, + } +} + +fn script(sss: u32) -> Script { + match sss { + 1 => Script::Superscript, + 2 => Script::Subscript, + _ => Script::Baseline, + } +} + +fn scheme(s: u32) -> Option { + match s { + 0 => Some(FontScheme::None), + 1 => Some(FontScheme::Major), + 2 => Some(FontScheme::Minor), + _ => None, + } +} + +fn name(text: String) -> String { + text.chars().take(MAX_NAME_CHARS).collect() +} + +/// `BrtFont`: only what Excel's `.xlsx` states for the same font (no ``, no scheme +/// `none`, no family or character set 0). +fn font(b: &mut Bytes<'_>) -> Result { + let height = b.u16()?; + let flags = b.u16()?; + let weight = b.u16()?; + let sss = b.u16()?; + let uls = b.u8()?; + let family = b.u8()?; + let charset = b.u8()?; + b.u8()?; + let color = color(b)?; + let font_scheme = b.u8()?; + let font_name = name(b.text(MAX_STRING_UNITS)?); + let on = |bit: u16| (flags & bit != 0).then_some(true); + Ok(Font { + name: Some(font_name), + size: Some(f64::from(height) / 20.0), + bold: (weight >= 0x2BC).then_some(true), + italic: on(0x02), + strike: on(0x08), + outline: on(0x10), + shadow: on(0x20), + condense: on(0x40), + extend: on(0x80), + underline: (uls != 0).then(|| underline(u32::from(uls))), + vert_align: (sss != 0).then(|| script(u32::from(sss))), + color, + family: (family != 0).then_some(u32::from(family)), + charset: (charset != 0).then_some(u32::from(charset)), + scheme: scheme(u32::from(font_scheme)).filter(|s| *s != FontScheme::None), + }) +} + +/// A gradient's angle and inner rectangle, as `BrtFill` and `XFPropGradient` hold them. +fn gradient(b: &mut Bytes<'_>, path: bool) -> Result { + Ok(GradientFill { path, degree: b.f64()?, left: b.f64()?, right: b.f64()?, top: b.f64()?, bottom: b.f64()?, stops: vec![] }) +} + +/// `BrtFill`. Excel's `.xlsx` leaves out the default colours: system foreground (indexed 64) as +/// the pattern colour and system background (indexed 65) as the background. +fn fill(b: &mut Bytes<'_>) -> Result { + let fls = b.u32()?; + let fg = color(b)?; + let bg = color(b)?; + let kind = b.u32()?; + let mut g = gradient(b, kind == 1)?; + let count = b.u32()?; + if fls == 0x28 { + if count > MAX_STOPS { + return Err(invalid("too many gradient stops")); + } + for _ in 0..count { + let c = color(b)?.unwrap_or_default(); + g.stops.push((b.f64()?, c)); + } + return Ok(Fill::Gradient(g)); + } + let system = |c: Color, i: u32| c.source == ColorSource::Indexed(i) && c.tint == 0.0; + Ok(Fill::Pattern(PatternFill { pattern: Some(pattern(fls)?), fg: fg.filter(|c| !system(*c, 64)), bg: bg.filter(|c| !system(*c, 65)) })) +} + +/// `BrtBorder`: the five edges a cell border has, each stated (`` when it has no line). +fn border(b: &mut Bytes<'_>) -> Result { + let flags = b.u8()?; + let mut edge = || -> Result { + let style = border_style(u16::from(b.u8()?))?; + b.u8()?; + let c = color(b)?; + Ok(BorderEdge { style, color: c.filter(|_| style != BorderStyle::None) }) + }; + let (top, bottom, left, right, diagonal) = (edge()?, edge()?, edge()?, edge()?, edge()?); + Ok(Border { + left: Some(left), + right: Some(right), + top: Some(top), + bottom: Some(bottom), + diagonal: Some(diagonal), + vertical: None, + horizontal: None, + diagonal_up: flags & 2 != 0, + diagonal_down: flags & 1 != 0, + outline: true, + }) +} + +/// `BrtXF`. A cell style format (`style`) marks what it leaves out (`apply*="0"`); a cell format +/// marks what it sets apart from its style (`apply*="1"`). +fn xf(b: &mut Bytes<'_>, style: bool) -> Result { + const APPLY: [(u8, &str); 6] = [ + (0x01, "applyNumberFormat"), + (0x02, "applyFont"), + (0x10, "applyFill"), + (0x08, "applyBorder"), + (0x04, "applyAlignment"), + (0x20, "applyProtection"), + ]; + let parent = b.u16()?; + let num_fmt_id = u32::from(b.u16()?); + let font_id = u32::from(b.u16()?); + let fill_id = u32::from(b.u16()?); + let border_id = u32::from(b.u16()?); + let rotation = u32::from(b.u8()?); + let indent = u32::from(b.u8()?); + let flags = u32::from(b.u16()?); + let apply = b.u8()?; + b.u8()?; + let alignment = Alignment { + horizontal: halign(flags & 7).filter(|h| *h != HAlign::General), + vertical: valign((flags >> 3) & 7).filter(|v| *v != VAlign::Bottom), + text_rotation: (rotation != 0).then_some(rotation), + wrap_text: flags & 0x40 != 0, + justify_last_line: flags & 0x80 != 0, + shrink_to_fit: flags & 0x100 != 0, + indent: (indent != 0).then_some(indent), + reading_order: Some((flags >> 10) & 3).filter(|r| *r != 0), + }; + let protection = Protection { locked: (flags & 0x1000 == 0).then_some(false), hidden: (flags & 0x2000 != 0).then_some(true) }; + let mut el = El::new("xf"); + for (bit, attr) in APPLY { + if apply & bit != 0 { + el = el.with_attr(attr, if style { "0" } else { "1" }); + } + } + Ok(Xf { + num_fmt_id, + font_id, + fill_id, + border_id, + xf_id: (!style).then_some(u32::from(parent)), + alignment: (alignment != Alignment::default()).then_some(alignment), + protection: (protection != Protection::default()).then_some(protection), + quote_prefix: flags & 0x8000 != 0, + el, + }) +} + +/// `BrtStyle`. +fn cell_style(b: &mut Bytes<'_>) -> Result { + let xf_id = b.u32()?; + let flags = b.u16()?; + let builtin = b.u8()?; + let level = b.u8()?; + let style_name = b.string(MAX_STRING_UNITS, true)?.map(name).unwrap_or_default(); + let is_builtin = flags & 1 != 0; + Ok(CellStyle { + name: style_name, + xf_id, + builtin_id: is_builtin.then_some(u32::from(builtin)), + level: (is_builtin && matches!(builtin, 1 | 2)).then_some(u32::from(level)), + hidden: flags & 2 != 0, + custom_builtin: flags & 4 != 0, + }) +} + +/// An unsigned integer of the size a property has (1, 2 or 4 bytes). +fn uint(data: &[u8]) -> Result { + match *data { + [a] => Ok(u32::from(a)), + [a, b] => Ok(u32::from(u16::from_le_bytes([a, b]))), + [a, b, c, d] => Ok(u32::from_le_bytes([a, b, c, d])), + _ => Err(invalid("unexpected formatting property size")), + } +} + +/// A string with a 2-byte length (`LPWideString`, and the number format of `XFProp` 0x26). +fn short_string(b: &mut Bytes<'_>) -> Result { + let count = usize::from(b.u16()?); + let mut text = String::new(); + for ch in char::decode_utf16(b.take(count * 2)?.as_chunks::<2>().0.iter().copied().map(u16::from_le_bytes)) { + text.push(ch.map_err(|_| invalid("invalid UTF-16 string"))?); + } + Ok(name(text)) +} + +fn dxf_font(d: &mut Dxf) -> &mut Font { + d.font.get_or_insert_with(Font::default) +} + +/// `BrtDXF`: its `XFProps`, each stating one property. +fn dxf(b: &mut Bytes<'_>) -> Result { + b.u16()?; + b.u16()?; + let count = b.u16()?; + let mut d = Dxf::default(); + let mut gradient_fill: Option = None; + let mut pattern_fill: Option = None; + for _ in 0..count { + let kind = b.u16()?; + let size = usize::from(b.u16()?).checked_sub(4).ok_or_else(|| invalid("formatting property too short"))?; + let data = b.take(size)?; + let mut p = Bytes::new(data); + match kind { + 0x00 => pattern_fill.get_or_insert_with(PatternFill::default).pattern = Some(pattern(uint(data)?)?), + 0x01 => pattern_fill.get_or_insert_with(PatternFill::default).fg = color(&mut p)?, + 0x02 => pattern_fill.get_or_insert_with(PatternFill::default).bg = color(&mut p)?, + 0x03 => { + let path = p.u32()? == 1; + gradient_fill = Some(gradient(&mut p, path)?); + } + 0x04 => { + let g = gradient_fill.as_mut().ok_or_else(|| invalid("gradient stop without a gradient"))?; + if g.stops.len() >= MAX_STOPS as usize { + return Err(invalid("too many gradient stops")); + } + p.u16()?; + let position = p.f64()?; + g.stops.push((position, color(&mut p)?.unwrap_or_default())); + } + 0x05 => dxf_font(&mut d).color = color(&mut p)?, + 0x06..=0x0C => { + let c = color(&mut p)?; + let edge = Some(BorderEdge { style: border_style(p.u16()?)?, color: c }); + let border = d.border.get_or_insert_with(|| Border { outline: true, ..Border::default() }); + match kind { + 0x06 => border.top = edge, + 0x07 => border.bottom = edge, + 0x08 => border.left = edge, + 0x09 => border.right = edge, + 0x0A => border.diagonal = edge, + 0x0B => border.vertical = edge, + _ => border.horizontal = edge, + } + } + 0x0D => d.border.get_or_insert_with(|| Border { outline: true, ..Border::default() }).diagonal_up = uint(data)? != 0, + 0x0E => d.border.get_or_insert_with(|| Border { outline: true, ..Border::default() }).diagonal_down = uint(data)? != 0, + 0x0F..=0x16 => { + let v = uint(data)?; + let a = d.alignment.get_or_insert_with(Alignment::default); + match kind { + 0x0F => a.horizontal = halign(v), + 0x10 => a.vertical = valign(v), + 0x11 => a.text_rotation = Some(v), + 0x12 => a.indent = Some(v), + 0x13 => a.reading_order = Some(v), + 0x14 => a.wrap_text = v != 0, + 0x15 => a.justify_last_line = v != 0, + _ => a.shrink_to_fit = v != 0, + } + } + 0x18 => dxf_font(&mut d).name = Some(short_string(&mut p)?), + 0x19 => dxf_font(&mut d).bold = Some(uint(data)? >= 0x2BC), + 0x1A => dxf_font(&mut d).underline = Some(underline(uint(data)?)), + 0x1B => dxf_font(&mut d).vert_align = Some(script(uint(data)?)), + 0x1C => dxf_font(&mut d).italic = Some(uint(data)? != 0), + 0x1D => dxf_font(&mut d).strike = Some(uint(data)? != 0), + 0x1E => dxf_font(&mut d).outline = Some(uint(data)? != 0), + 0x1F => dxf_font(&mut d).shadow = Some(uint(data)? != 0), + 0x20 => dxf_font(&mut d).condense = Some(uint(data)? != 0), + 0x21 => dxf_font(&mut d).extend = Some(uint(data)? != 0), + 0x22 => dxf_font(&mut d).charset = Some(uint(data)?), + 0x23 => dxf_font(&mut d).family = Some(uint(data)?), + 0x24 => dxf_font(&mut d).size = Some(f64::from(uint(data)?) / 20.0), + 0x25 => dxf_font(&mut d).scheme = scheme(uint(data)?), + 0x26 => d.num_fmt.get_or_insert_with(NumFmt::default).code = Some(short_string(&mut p)?), + 0x29 => d.num_fmt.get_or_insert_with(NumFmt::default).id = Some(uint(data)?), + 0x2B => d.protection.get_or_insert_with(Protection::default).locked = Some(uint(data)? != 0), + 0x2C => d.protection.get_or_insert_with(Protection::default).hidden = Some(uint(data)? != 0), + // Merged cells (0x17) and relative indents (0x2A) have no place in ``. + _ => {} + } + } + d.fill = gradient_fill.map(Fill::Gradient).or(pattern_fill.map(Fill::Pattern)); + Ok(d) +} + +/// The styles part: `BrtBeginStyleSheet` to `BrtEndStyleSheet`. +pub(crate) fn styles(bytes: &[u8], limits: &Limits, budget: &Budget, warnings: &mut Warnings) -> Result { + let mut records = Records::new(bytes, limits, budget); + records.first(278, warnings)?; + let mut s = Styles::default(); + // Inside BrtBeginCellStyleXFs (true) or BrtBeginCellXFs (false). + let mut xfs: Option = None; + let mut palette = false; + while let Some((id, payload)) = records.next(warnings)? { + let mut b = Bytes::new(payload); + let entries = match id { + 44 => s.num_fmts.len(), + 43 => s.fonts.len(), + 45 => s.fills.len(), + 46 => s.borders.len(), + 47 => s.cell_style_xfs.len().max(s.cell_xfs.len()), + 48 => s.cell_styles.len(), + 507 => s.dxfs.len(), + 475 => s.indexed_colors.len(), + _ => 0, + }; + if entries >= MAX_ENTRIES { + return Err(invalid(format!("more than {MAX_ENTRIES} entries in a styles table"))); + } + match id { + 279 => { + records.end(payload, warnings)?; + return Ok(s); + } + 44 => { + let id = u32::from(b.u16()?); + let code = name(b.text(MAX_STRING_UNITS)?); + budget.text(code.len(), limits)?; + s.num_fmts.push((id, code)); + } + 43 => { + let f = font(&mut b)?; + budget.text(f.name.as_ref().map_or(0, String::len), limits)?; + s.fonts.push(f); + } + 45 => s.fills.push(fill(&mut b)?), + 46 => s.borders.push(border(&mut b)?), + 626 => xfs = Some(true), + 617 => xfs = Some(false), + 627 | 618 => xfs = None, + 47 => match xfs { + Some(true) => s.cell_style_xfs.push(xf(&mut b, true)?), + Some(false) => s.cell_xfs.push(xf(&mut b, false)?), + None => return Err(invalid("cell format outside its list")), + }, + 48 => { + let c = cell_style(&mut b)?; + budget.text(c.name.len(), limits)?; + s.cell_styles.push(c); + } + 507 => s.dxfs.push(dxf(&mut b)?), + // BrtBeginIndexedColors, BrtEndIndexedColors. + 565 => palette = true, + 566 => palette = false, + 475 if palette => { + let [r, g, bl, _] = <[u8; 4]>::try_from(b.take(4)?).map_err(|_| invalid("truncated colour"))?; + s.indexed_colors.push(u32::from_be_bytes([0, r, g, bl])); + } + // BrtBeginTableStyles: the count of custom table styles, which are not read. + 508 => { + if b.u32()? > 0 { + warnings.warn("custom table styles in a binary workbook were not read"); + } + continue; + } + _ => continue, + } + // The records read above are read whole; the rest are skipped. + if matches!(id, 44 | 43 | 45 | 46 | 47 | 48 | 507 | 475) { + b.finish()?; + } + } + Err(invalid("missing styles end record")) +} diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index ee9ac3afd..bc1a7f6bd 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -5,7 +5,10 @@ mod common; use common::{read, read_with}; use craft_xlsx::testing::zip; -use craft_xlsx::{CellError, CellRef, Error, FormulaKind, Limits, Range, SheetKind, Value, Visibility, is_xlsb}; +use craft_xlsx::{ + CellError, CellRef, Color, ColorSource, Error, Fill, FormulaKind, Limits, Package, Pattern, PatternFill, Protection, Range, SheetKind, Styles, + Value, Visibility, is_xlsb, +}; const ROOT: &str = r#""#; const RELS: &str = r#""#; @@ -930,3 +933,264 @@ fn a_dynamic_array_kept_as_its_value_has_no_cell_metadata() { assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&at("C1"), &1)]); assert!(warned(&wb, "missing from the file"), "{:?}", wb.warnings); } + +// Styles ([MS-XLSB] 2.1.7.50): a styles part assembled from records, and the `styles.xml` Excel +// writes for the same formats when it saves the workbook as `.xlsx`. + +const STYLES_RELS: &str = r#""#; +const STYLES_TYPES: &str = r#""#; + +fn styled_file(styles: &[u8], types: &str) -> Vec { + let sheet = worksheet(&[row(0), cell(5, 0, &1.0f64.to_le_bytes())].concat(), &[]); + zip(&[ + ("[Content_Types].xml", types.as_bytes()), + ("_rels/.rels", ROOT.as_bytes()), + ("records/book.bin", &book(false)), + ("records/_rels/book.bin.rels", STYLES_RELS.as_bytes()), + ("data/one.bin", &sheet), + ("data/two.bin", &worksheet(&[], &[])), + ("look/styles.bin", styles), + ]) +} + +/// The styles part of a package, and the warnings reading it gave. +fn styles_of(bytes: &[u8]) -> (Option, Vec) { + let mut p = Package::open(bytes, &Limits::default()).unwrap(); + let styles = p.styles().unwrap(); + (styles, p.warnings().to_vec()) +} + +/// `BrtColor`: auto 0, indexed 1, RGB 2, theme 3. +fn color(kind: u8, index: u8, tint: i16, rgba: [u8; 4]) -> Vec { + [&[kind << 1 | 1, index][..], &tint.to_le_bytes(), &rgba].concat() +} +fn indexed(i: u8) -> Vec { + color(1, i, 0, [0, 0, 0, 255]) +} +fn theme(i: u8, tint: i16) -> Vec { + color(3, i, tint, [0, 0, 0, 255]) +} +fn rgb(r: u8, g: u8, b: u8) -> Vec { + color(2, 255, 0, [r, g, b, 255]) +} +#[allow(clippy::too_many_arguments)] +fn font(twips: u16, flags: u16, weight: u16, script: u16, underline: u8, family: u8, charset: u8, c: &[u8], scheme: u8, name: &str) -> Vec { + let head = + [&twips.to_le_bytes()[..], &flags.to_le_bytes(), &weight.to_le_bytes(), &script.to_le_bytes(), &[underline, family, charset, 0]].concat(); + record(43, &[&head[..], c, &[scheme], &wide(name)].concat()) +} +fn pattern_fill(fls: u32, fg: &[u8], bg: &[u8]) -> Vec { + record(45, &[&fls.to_le_bytes()[..], fg, bg, &[0; 48]].concat()) +} +fn edge(dg: u8, c: &[u8]) -> Vec { + [&[dg, 0][..], c].concat() +} +#[allow(clippy::too_many_arguments)] +fn brt_xf(parent: u16, fmt: u16, font: u16, fill: u16, border: u16, rotation: u8, indent: u8, flags: u16, apply: u8) -> Vec { + let ids = [parent, fmt, font, fill, border].map(u16::to_le_bytes).concat(); + record(47, &[&ids[..], &[rotation, indent], &flags.to_le_bytes(), &[apply, 0]].concat()) +} +fn style(xf: u32, flags: u16, builtin: u8, level: u8, name: &str) -> Vec { + record(48, &[&xf.to_le_bytes()[..], &flags.to_le_bytes(), &[builtin, level], &wide(name)].concat()) +} +fn prop(kind: u16, data: &[u8]) -> Vec { + [&kind.to_le_bytes()[..], &(data.len() as u16 + 4).to_le_bytes(), data].concat() +} +fn short(text: &str) -> Vec { + let units: Vec = text.encode_utf16().collect(); + [(units.len() as u16).to_le_bytes().to_vec(), units.iter().flat_map(|u| u.to_le_bytes()).collect()].concat() +} +fn brt_dxf(props: &[Vec]) -> Vec { + record(507, &[&[0, 0x80, 0, 0][..], &(props.len() as u16).to_le_bytes(), &props.concat()].concat()) +} +fn begin(id: u16, count: u32) -> Vec { + record(id, &count.to_le_bytes()) +} + +/// Every kind of record the styles part has, as Excel writes them. +fn styles_bin() -> Vec { + let normal = font(220, 0, 400, 0, 0, 2, 0, &theme(1, 0), 2, "Aptos Narrow"); + // Bold, italic, struck out, superscript, double accounting underline; family and + // character set 0 and scheme "none" are not written in `.xlsx`. + let fancy = font(290, 0x0A, 700, 1, 0x22, 0, 2, &rgb(0, 128, 255), 0, "Wingdings"); + let heading = font(220, 0, 400, 0, 0, 2, 0, &theme(4, 13106), 1, "Aptos Display"); + let gradient = [ + &0x28u32.to_le_bytes()[..], + &indexed(64), + &indexed(65), + &1u32.to_le_bytes(), + &[0.0f64, 0.5, 0.5, 0.5, 0.5].map(f64::to_le_bytes).concat(), + &2u32.to_le_bytes(), + &theme(0, 0), + &0.0f64.to_le_bytes(), + &theme(4, 0), + &1.0f64.to_le_bytes(), + ] + .concat(); + let none = edge(0, &color(0, 0, 0, [0, 0, 0, 0])); + let parts: Vec> = vec![ + record(278, &[]), + begin(615, 1), + record(44, &[&164u16.to_le_bytes()[..], &wide(r"yyyy\-mm\-dd")].concat()), + record(616, &[]), + begin(611, 3), + normal, + fancy, + heading, + record(612, &[]), + begin(603, 5), + pattern_fill(0, &indexed(64), &indexed(65)), + pattern_fill(17, &indexed(64), &indexed(65)), + pattern_fill(1, &rgb(255, 255, 0), &indexed(64)), + pattern_fill(9, &theme(5, -8191), &indexed(65)), + record(45, &gradient), + record(604, &[]), + begin(613, 2), + record(46, &[&[0][..], &none, &none, &none, &none, &none].concat()), + record( + 46, + &[&[3][..], &edge(2, &rgb(200, 0, 0)), &none, &edge(7, &indexed(64)), &edge(13, &color(0, 0, 0, [0, 0, 0, 0])), &edge(1, &theme(4, 0))] + .concat(), + ), + record(614, &[]), + begin(626, 3), + brt_xf(0xFFFF, 0, 0, 0, 0, 0, 0, 0x1010, 0), + brt_xf(0xFFFF, 9, 0, 0, 0, 0, 0, 0x1010, 0x3E), + brt_xf(0xFFFF, 0, 2, 0, 0, 0, 0, 0x1010, 0), + record(627, &[]), + begin(617, 4), + brt_xf(0, 0, 0, 0, 0, 0, 0, 0x1010, 0), + brt_xf(0, 164, 0, 0, 0, 0, 0, 0x1010, 0x01), + // Left, top, wrapped, shrunk, right to left, unlocked, hidden, quote prefix. + brt_xf(0, 0, 0, 0, 0, 180, 2, 0x01 | 0x40 | 0x100 | 0x800 | 0x2000 | 0x8000, 0x24), + brt_xf(1, 0, 1, 4, 1, 0, 0, 0x1010, 0x1A), + record(618, &[]), + begin(619, 3), + style(0, 1, 0, 0, "Normal"), + // Excel wraps each style in alternate content, which is skipped. + record(37, &[1, 0, 2, 0x0e, 0, 0x80]), + record(3072, &[0; 16]), + record(38, &[]), + style(1, 1 | 4, 1, 1, "RowLevel_2"), + style(2, 2, 0, 0, "Probe Style"), + record(620, &[]), + begin(505, 2), + brt_dxf(&[ + prop(0x05, &rgb(0x9C, 0, 6)), + prop(0x19, &700u16.to_le_bytes()), + prop(0x1C, &[0]), + prop(0x1A, &0x21u16.to_le_bytes()), + prop(0x24, &240u32.to_le_bytes()), + prop(0x18, &short("Arial")), + prop(0x29, &170u16.to_le_bytes()), + prop(0x26, &short("0.0")), + prop(0x02, &rgb(0xFF, 0xC7, 0xCE)), + prop(0x0F, &[2]), + prop(0x14, &[1]), + prop(0x2B, &[0]), + prop(0x07, &[&color(0, 0, 0, [0, 0, 0, 0])[..], &1u16.to_le_bytes()].concat()), + ]), + brt_dxf(&[ + prop(0x03, &[&0u32.to_le_bytes()[..], &[90.0f64, 0.0, 0.0, 0.0, 0.0].map(f64::to_le_bytes).concat()].concat()), + prop(0x04, &[&[0, 0][..], &0.0f64.to_le_bytes(), &rgb(255, 255, 255)].concat()), + prop(0x04, &[&[0, 0][..], &1.0f64.to_le_bytes(), &theme(4, 0)].concat()), + ]), + record(506, &[]), + record(508, &[&0u32.to_le_bytes()[..], &wide("TableStyleMedium2"), &wide("PivotStyleLight16")].concat()), + record(509, &[]), + record(473, &[]), + record(565, &[]), + record(475, &[0x11, 0x22, 0x33, 0]), + record(475, &[0xFF, 0xFF, 0xFF, 0]), + record(566, &[]), + record(474, &[]), + record(279, &[]), + ]; + parts.concat() +} + +const STYLES_XML: &str = r#""#; + +/// The same styles from a SpreadsheetML package. +fn xml_styles(xml: &str) -> Styles { + let types = r#""#; + let root = r#""#; + let rels = r#""#; + let bytes = zip(&[ + ("[Content_Types].xml", types.as_bytes()), + ("_rels/.rels", root.as_bytes()), + ("xl/workbook.xml", br#""#), + ("xl/_rels/workbook.xml.rels", rels.as_bytes()), + ("xl/styles.xml", xml.as_bytes()), + ]); + styles_of(&bytes).0.unwrap() +} + +/// What both readers lift out: an ``'s element keeps only its `apply*` flags, and the XML +/// part's own element is dropped. +fn lifted(mut s: Styles) -> Styles { + for xf in s.cell_style_xfs.iter_mut().chain(&mut s.cell_xfs) { + let attrs = xf.el.attrs.iter().filter(|(k, _)| k.starts_with("apply")).cloned().collect(); + xf.el = craft_xml::El::new("xf"); + xf.el.attrs = attrs; + } + s.root = craft_xml::El::default(); + s +} + +#[test] +fn styles_are_read_as_their_xlsx_spelling() { + let (binary, warnings) = styles_of(&styled_file(&styles_bin(), STYLES_TYPES)); + let binary = binary.expect("styles are read"); + assert_eq!(lifted(binary.clone()), lifted(xml_styles(STYLES_XML))); + // A few of the conversions, spelled out. + assert_eq!(binary.fonts[1].size, Some(14.5)); + assert_eq!(binary.fonts[1].family, None); + let solid = Fill::Pattern(PatternFill { + pattern: Some(Pattern::Solid), + fg: Some(Color { source: ColorSource::Rgb(0xFFFF_FF00), tint: 0.0 }), + bg: Some(Color { source: ColorSource::Indexed(64), tint: 0.0 }), + }); + assert_eq!(binary.fills[2], solid); + assert_eq!(binary.cell_xfs[2].protection, Some(Protection { locked: Some(false), hidden: Some(true) })); + assert_eq!(binary.palette()[0], 0x11_2233); + // Written back as SpreadsheetML, a cell style format says what it leaves out, as Excel's does. + let written = String::from_utf8(binary.to_xml()).unwrap(); + assert!(written.contains(r#"applyFont="0" applyFill="0" applyBorder="0" applyAlignment="0" applyProtection="0""#), "{written}"); + assert!(warnings.iter().any(|w| w.contains("alternate-content")), "{warnings:?}"); + assert!(!warnings.iter().any(|w| w.contains("table styles")), "{warnings:?}"); +} + +#[test] +fn damaged_styles_are_a_warning_and_the_workbook_opens() { + let good = styles_bin(); + let end = record(279, &[]); + let body = &good[..good.len() - end.len()]; + let with = |extra: &[u8]| [body, extra, &end].concat(); + let cases: Vec<(&str, Vec, &str)> = vec![ + ("truncated", good[..good.len() - 1].to_vec(), STYLES_TYPES), + ("no end record", body.to_vec(), STYLES_TYPES), + ("unknown fill pattern", with(&pattern_fill(99, &indexed(64), &indexed(65))), STYLES_TYPES), + ("unknown border style", with(&record(46, &[&[0][..], &edge(14, &indexed(64)), &[0; 40]].concat())), STYLES_TYPES), + ("cell format outside its list", with(&brt_xf(0, 0, 0, 0, 0, 0, 0, 0x1010, 0)), STYLES_TYPES), + ("short property", with(&brt_dxf(&[vec![0x19, 0, 2, 0]])), STYLES_TYPES), + ("wrong content type", good.clone(), TYPES), + ]; + for (why, part, types) in cases { + let bytes = styled_file(&part, types); + let (styles, warnings) = styles_of(&bytes); + assert!(styles.is_none(), "{why}"); + assert!(warnings.iter().any(|w| w.contains("look/styles.bin")), "{why}: {warnings:?}"); + assert_eq!(read(&bytes).unwrap().sheets[0].value(CellRef::new(0, 0)), Value::Number(1.0), "{why}"); + } + // A table past 65,536 entries is refused before it is held. + let xfs = brt_xf(0, 0, 0, 0, 0, 0, 0, 0x1010, 0).repeat(65_537); + let (styles, warnings) = styles_of(&styled_file(&with(&[&begin(617, 65_537)[..], &xfs, &record(618, &[])].concat()), STYLES_TYPES)); + assert!(styles.is_none()); + assert!(warnings.iter().any(|w| w.contains("65536 entries")), "{warnings:?}"); + // Custom table styles are not read, and say so. + let table_styles = [body, &record(508, &[&1u32.to_le_bytes()[..], &wide("Probe Table"), &wide("")].concat()), &end].concat(); + let (styles, warnings) = styles_of(&styled_file(&table_styles, STYLES_TYPES)); + assert!(styles.is_some()); + assert!(warnings.iter().any(|w| w.contains("table styles")), "{warnings:?}"); +} From 25f1ac5801dcf687990bdaf1ca2aee0d91934cf5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Legrand?= Date: Sat, 14 Nov 2026 10:39:34 +0100 Subject: [PATCH 015/349] test(prc): validate compressed mesh reconstruction --- crates/prc/README.md | 4 +- crates/prc/src/tess/compressed.rs | 2 + crates/prc/src/tess/compressed/independent.rs | 451 ++++++++++++++++++ 3 files changed, 455 insertions(+), 2 deletions(-) create mode 100644 crates/prc/src/tess/compressed/independent.rs diff --git a/crates/prc/README.md b/crates/prc/README.md index 4d40f0962..c76d0af5b 100644 --- a/crates/prc/README.md +++ b/crates/prc/README.md @@ -30,7 +30,7 @@ BitReader: bit, bits, character, unsigned_integer, integer, integer_vbn, double_ - `Tessellation::Mesh` is a `TriangleMesh`: positions, triangles, one triangle range per face, the stored normals and texture coordinates with each triangle's corner indices into them, and per-triangle line-attribute styles. `Wire` is polylines; `Markup` is read past. -- `Tessellation::Compressed` is read to its end so later entities decode; its triangles are not rebuilt yet. +- `Tessellation::Compressed` is read to its end so later entities decode. Recalculated-normal meshes in the accepted 3T form are rebuilt when their arrays fit; stored-normal meshes and unsupported traversals stay `Compressed`. - A face may carry at most 8 texture-coordinate sets; more is `Malformed`. Optimised vertex colours are `Unsupported`. - The product tree: each drawable tessellation placed by its occurrence path's locations and the item's coordinate systems (a 4x4 `Matrix`), coloured by the style inheritance rules, with occurrences' entity references applied @@ -39,6 +39,6 @@ BitReader: bit, bits, character, unsigned_integer, integer, integer_vbn, double_ came from, its visibility and the range of placements it drew. - Occurrence and prototype cycles are `Malformed`; the walk is capped at depth 64, 2^20 visits and `MAX_PLACEMENTS`. - A tree's markups (PMI), views, scene lights and clipping planes are read past, not modelled; so are textures. -- Not yet in the crate: rebuilding compressed meshes, textures. +- Not yet in the crate: stored-normal or one-status compressed mesh reconstruction, textures. - The `Double` code table's rows come from [prc-rs](https://github.com/ralovich/prc-rs) (MIT); its notice is in `src/acof/table.rs`. A few reading choices also follow prc-rs; each is marked `// prc-rs:` in the source. diff --git a/crates/prc/src/tess/compressed.rs b/crates/prc/src/tess/compressed.rs index 53e082b4d..f6fa70317 100644 --- a/crates/prc/src/tess/compressed.rs +++ b/crates/prc/src/tess/compressed.rs @@ -349,5 +349,7 @@ impl Walk { } } +#[cfg(test)] +mod independent; #[cfg(test)] mod tests; diff --git a/crates/prc/src/tess/compressed/independent.rs b/crates/prc/src/tess/compressed/independent.rs new file mode 100644 index 000000000..209337f78 --- /dev/null +++ b/crates/prc/src/tess/compressed/independent.rs @@ -0,0 +1,451 @@ +#![allow( + clippy::cast_possible_truncation, + clippy::cast_precision_loss, + clippy::expect_used, + clippy::float_cmp, + clippy::many_single_char_names, + clippy::panic, + clippy::unwrap_used +)] + +use super::*; + +const S: f64 = std::f64::consts::SQRT_2; + +#[derive(Clone, Copy)] +enum Slot { + Point(V), + #[allow(dead_code)] + Reference(u32), +} + +#[derive(Clone, Copy)] +enum Recipe { + Seed { slots: [Slot; 3], status: i32, face: u32 }, + Apex { edge: (u32, u32), opposite: u32, slot: Slot, status: i32, face: u32 }, +} + +impl Recipe { + fn status(self) -> i32 { + match self { + Self::Seed { status, .. } | Self::Apex { status, .. } => status, + } + } + + fn face(self) -> u32 { + match self { + Self::Seed { face, .. } | Self::Apex { face, .. } => face, + } + } +} + +#[derive(Clone)] +struct Encoded { + tolerance: f64, + origin: V, + points: Vec, + edge_status: Vec, + face_of: Vec, + is_reference: Vec, + references: Vec, + positions: Vec, + triangles: Vec<[u32; 3]>, +} + +impl Encoded { + fn arrays(&self, limit: usize) -> Arrays<'_> { + Arrays { + tolerance: self.tolerance, + origin: self.origin, + points: &self.points, + edge_status: &self.edge_status, + triangles: self.triangles.len(), + is_reference: &self.is_reference, + references: &self.references, + limit, + } + } + + #[allow(dead_code)] + fn faces(&self) -> usize { + self.face_of.iter().max().map_or(0, |&face| face as usize + 1) + } + + fn push_reference(&mut self, vertex: u32) -> u32 { + let index = usize::try_from(vertex).unwrap(); + assert!(index < self.positions.len(), "a recipe reference must name an earlier vertex"); + self.is_reference.push(true); + self.references.push(vertex); + vertex + } + + fn push_position(&mut self, position: V, point: [i64; 3]) -> u32 { + self.points.extend(point); + self.is_reference.push(false); + self.positions.push(position); + u32::try_from(self.positions.len() - 1).unwrap() + } + + fn push_seed_point(&mut self, index: usize, target: V, triangle: [u32; 3]) -> u32 { + let base = match index { + 0 => self.origin, + 1 => self.positions[usize::try_from(triangle[0]).unwrap()], + 2 => { + let first = self.positions[usize::try_from(triangle[0]).unwrap()]; + let second = self.positions[usize::try_from(triangle[1]).unwrap()]; + p_scale(p_add(first, second), 0.5) + } + _ => panic!("a seed has exactly three slots"), + }; + let point = quantize(p_sub(target, base), self.tolerance); + let position = p_add(base, scaled(point, self.tolerance)); + self.push_position(position, point) + } + + fn push_apex_point(&mut self, edge: (u32, u32), opposite: u32, target: V) -> u32 { + let (p, q) = edge; + let (lo, hi) = if p < q { (p, q) } else { (q, p) }; + let lo = self.positions[usize::try_from(lo).unwrap()]; + let hi = self.positions[usize::try_from(hi).unwrap()]; + let opposite = self.positions[usize::try_from(opposite).unwrap()]; + let (origin, x, y, z) = encoder_frame(lo, hi, opposite); + let offset = p_sub(target, origin); + let point = [ + quantize_component(p_dot(offset, x), self.tolerance), + quantize_component(-p_dot(offset, y), self.tolerance), + quantize_component(-p_dot(offset, z), self.tolerance), + ]; + let delta = scaled(point, self.tolerance); + let position = p_sub(p_sub(p_add(origin, p_scale(x, delta[0])), p_scale(y, delta[1])), p_scale(z, delta[2])); + self.push_position(position, point) + } +} + +fn encode(origin: V, tolerance: f64, recipes: &[Recipe]) -> Encoded { + assert!(tolerance.is_finite() && tolerance > 0.0, "a positive finite tolerance"); + let mut edge_status: Vec = recipes.iter().map(|recipe| recipe.status()).collect(); + edge_status.resize(recipes.len().saturating_mul(3), 0); + let mut encoded = Encoded { + tolerance, + origin, + points: Vec::new(), + edge_status, + face_of: Vec::new(), + is_reference: Vec::new(), + references: Vec::new(), + positions: Vec::new(), + triangles: Vec::new(), + }; + + for &recipe in recipes { + encoded.face_of.push(recipe.face()); + match recipe { + Recipe::Seed { slots, .. } => { + let mut triangle = [0; 3]; + for (index, slot) in slots.into_iter().enumerate() { + triangle[index] = match slot { + Slot::Point(target) => encoded.push_seed_point(index, target, triangle), + Slot::Reference(vertex) => encoded.push_reference(vertex), + }; + } + encoded.triangles.push(triangle); + } + Recipe::Apex { edge: (p, q), opposite, slot, .. } => { + let vertex = match slot { + Slot::Point(target) => encoded.push_apex_point((p, q), opposite, target), + Slot::Reference(vertex) => encoded.push_reference(vertex), + }; + encoded.triangles.push([p, q, vertex]); + } + } + } + encoded +} + +fn p_add(a: V, b: V) -> V { + [a[0] + b[0], a[1] + b[1], a[2] + b[2]] +} + +fn p_sub(a: V, b: V) -> V { + [a[0] - b[0], a[1] - b[1], a[2] - b[2]] +} + +fn p_scale(a: V, factor: f64) -> V { + a.map(|component| component * factor) +} + +fn p_dot(a: V, b: V) -> f64 { + a[0] * b[0] + a[1] * b[1] + a[2] * b[2] +} + +fn p_cross(a: V, b: V) -> V { + [a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]] +} + +fn quantize_component(value: f64, tolerance: f64) -> i64 { + let quantized = (value / tolerance).round(); + assert!(quantized.is_finite() && quantized >= i64::MIN as f64 && quantized <= i64::MAX as f64); + quantized as i64 +} + +fn quantize(value: V, tolerance: f64) -> [i64; 3] { + value.map(|component| quantize_component(component, tolerance)) +} + +fn scaled(point: [i64; 3], tolerance: f64) -> V { + point.map(|component| component as f64 * tolerance) +} + +fn encoder_length(value: V) -> Option { + let squared = (value[0] * value[0] + value[1] * value[1] + value[2] * value[2]) as f32; + let bits = squared.to_bits(); + let exponent = (bits >> 23) & 0xff; + let seed = if exponent > 127 { f32::from_bits((bits & !(0xff << 23)) | (((exponent - 127) / 2 + 127) << 23)) } else { squared }; + let squared = f64::from(squared); + let mut current = f64::from(seed); + for _ in 0..100 { + let next = 0.5 * (current + squared / current); + if next == current { + return Some(next); + } + current = next; + } + None +} + +fn encoder_unit(value: V) -> Option { + let length = encoder_length(value).filter(|&length| length >= f64::from(f32::EPSILON))?; + Some([value[0] / length, value[1] / length, value[2] / length]) +} + +fn encoder_ortho_z(x: V) -> Option { + let x = encoder_unit(x)?; + encoder_unit(p_cross(x, [0.0, 1.0, 0.0])).or_else(|| encoder_unit(p_cross(x, [1.0, 0.0, 0.0]))) +} + +fn encoder_frame(lo: V, hi: V, opposite: V) -> (V, V, V, V) { + let origin = p_scale(p_add(lo, hi), 0.5); + let difference = p_sub(lo, hi); + let x = encoder_unit(difference).unwrap_or(difference); + let residue = p_cross(p_sub(opposite, origin), x); + let (y, z) = encoder_unit(residue) + .and_then(|z| Some((encoder_unit(p_cross(z, x))?, z))) + .or_else(|| { + let z = encoder_ortho_z(x)?; + let y = encoder_unit(p_cross(z, x))?; + Some(if p_dot(residue, z) < 0.0 { (p_scale(y, -1.0), p_scale(z, -1.0)) } else { (y, z) }) + }) + .unwrap_or_default(); + (origin, x, y, z) +} + +fn assert_positions(actual: &[V], expected: &[V]) { + assert_eq!(actual.len(), expected.len(), "vertex counts differ"); + for (index, (actual, expected)) in actual.iter().zip(expected).enumerate() { + for component in 0..3 { + assert!( + (actual[component] - expected[component]).abs() < 1e-9, + "vertex {index}, component {component}: actual {actual:?}, expected {expected:?}", + ); + } + } +} + +#[allow(dead_code)] +fn assert_within_tolerance(actual: &[V], source: &[V], tolerance: f64) { + assert_eq!(actual.len(), source.len(), "vertex counts differ"); + let limit = tolerance * 3.0_f64.sqrt() / 2.0; + for (index, (actual, source)) in actual.iter().zip(source).enumerate() { + let difference = p_sub(*actual, *source); + let distance = p_dot(difference, difference).sqrt(); + assert!(distance <= limit + 1e-12, "vertex {index}: distance {distance} exceeds {limit}; actual {actual:?}, source {source:?}"); + } +} + +fn triangle_seed(x: f64, status: i32, face: u32) -> Recipe { + Recipe::Seed { slots: [Slot::Point([x, 0.0, 0.0]), Slot::Point([x + 2.0, 0.0, 0.0]), Slot::Point([x, 2.0, 0.0])], status, face } +} + +fn panel(target: V) -> Encoded { + encode( + [0.0; 3], + 0.5, + &[ + triangle_seed(0.0, 3, 0), + Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point(target), status: 3, face: 0 }, + Recipe::Apex { edge: (2, 3), opposite: 1, slot: Slot::Reference(0), status: 2, face: 0 }, + Recipe::Apex { edge: (0, 3), opposite: 2, slot: Slot::Reference(1), status: 0, face: 0 }, + ], + ) +} + +#[test] +fn independent_seed_and_apex_match_a_hand_computed_stream() { + let encoded = encode( + [10.0, 0.0, 0.0], + 0.5, + &[ + Recipe::Seed { slots: [Slot::Point([10.0, 0.0, 0.0]), Slot::Point([12.0, 0.0, 0.0]), Slot::Point([10.0, 2.0, 0.0])], status: 2, face: 0 }, + Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point([11.0 + 2.0 * S, 1.0 + S, -1.0]), status: 0, face: 0 }, + ], + ); + + assert_eq!(encoded.points, [0, 0, 0, 4, 0, 0, -2, 4, 0, 2, -6, 2]); + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3]]); + let expected = [[10.0, 0.0, 0.0], [12.0, 0.0, 0.0], [10.0, 2.0, 0.0], [11.0 + 2.0 * S, 1.0 + S, -1.0]]; + assert_positions(&rebuilt.positions, &expected); +} + +#[test] +fn independent_components_and_a_reference_are_rebuilt() { + let encoded = encode( + [0.0; 3], + 0.5, + &[ + triangle_seed(0.0, 2, 0), + Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Reference(0), status: 0, face: 0 }, + triangle_seed(5.0, 0, 1), + ], + ); + + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 0], [3, 4, 5]]); + assert_eq!(encoded.references, [0]); + assert_eq!(encoded.face_of, [0, 0, 1]); + assert_eq!(rebuilt.positions.len(), 6); + let expected = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [5.0, 0.0, 0.0], [7.0, 0.0, 0.0], [5.0, 2.0, 0.0]]; + assert_positions(&rebuilt.positions, &expected); +} + +#[test] +fn independent_fold_and_component_retry_rebuild_the_same_panel() { + let folded = [1.0 - 1.0 / S, 1.0 - S, 0.0]; + let unfolded = [1.0 + S, 1.0 + 1.0 / S, 0.0]; + for target in [folded, unfolded] { + let source = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], target]; + let encoded = panel(target); + assert_within_tolerance(&encoded.positions, &source, 0.5); + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3], [2, 3, 0], [0, 3, 1]]); + assert_eq!(rebuilt.positions.len(), 4); + assert_within_tolerance(&rebuilt.positions, &source, 0.5); + } +} + +#[test] +fn independent_closed_continuation_uses_the_open_edge() { + let encoded = encode( + [0.0; 3], + 0.5, + &[ + triangle_seed(0.0, 2, 0), + Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point([0.0, 0.0, 2.0]), status: 2, face: 0 }, + Recipe::Apex { edge: (3, 1), opposite: 2, slot: Slot::Reference(0), status: 2, face: 0 }, + Recipe::Apex { edge: (3, 0), opposite: 1, slot: Slot::Reference(2), status: 0, face: 0 }, + ], + ); + + let source = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.0, 0.0, 2.0]]; + assert_within_tolerance(&encoded.positions, &source, 0.5); + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3], [3, 1, 0], [3, 0, 2]]); + assert_within_tolerance(&rebuilt.positions, &source, 0.5); +} + +#[test] +fn independent_non_planar_strip_tracks_the_quantized_working_mesh() { + let source: Vec = (0..16).map(|index| [f64::from(index) * 0.05, f64::from(index % 2) * 2.0, (f64::from(index % 5) - 2.0) * 0.03]).collect(); + let mut recipes = vec![Recipe::Seed { slots: [Slot::Point(source[0]), Slot::Point(source[1]), Slot::Point(source[2])], status: 2, face: 0 }]; + let (mut p, mut q, mut opposite) = (2_u32, 1_u32, 0_u32); + + for index in 1..source.len() - 2 { + let vertex = u32::try_from(index + 2).unwrap(); + let status = if index % 2 == 1 { 1 } else { 2 }; + recipes.push(Recipe::Apex { edge: (p, q), opposite, slot: Slot::Point(source[index + 2]), status, face: 0 }); + if status == 1 { + (p, q, opposite) = (p, vertex, q); + } else { + (p, q, opposite) = (vertex, q, p); + } + } + + let encoded = encode([0.0; 3], 1e-4, &recipes); + assert_within_tolerance(&encoded.positions, &source, 1e-4); + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + assert_eq!( + rebuilt.triangles, + [ + [0, 1, 2], + [2, 1, 3], + [2, 3, 4], + [4, 3, 5], + [4, 5, 6], + [6, 5, 7], + [6, 7, 8], + [8, 7, 9], + [8, 9, 10], + [10, 9, 11], + [10, 11, 12], + [12, 11, 13], + [12, 13, 14], + [14, 13, 15], + ] + ); + assert_eq!(encoded.points.len(), source.len() * 3); + assert_within_tolerance(&rebuilt.positions, &source, 1e-4); +} + +#[test] +fn independent_near_degenerate_parent_uses_an_orthogonal_frame() { + let encoded = encode( + [0.0; 3], + 1e-8, + &[ + Recipe::Seed { + slots: [Slot::Point([1.0, 1.0 + 1e-8, 0.0]), Slot::Point([2.0, 0.0, 0.0]), Slot::Point([0.0, 2.0, 0.0])], + status: 2, + face: 0, + }, + Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point([0.3, 0.7, 0.2]), status: 0, face: 0 }, + ], + ); + + let source = [[1.0, 1.0 + 1e-8, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.3, 0.7, 0.2]]; + assert_within_tolerance(&encoded.positions, &source, 1e-8); + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3]]); + assert_within_tolerance(&rebuilt.positions, &source, 1e-8); +} + +#[test] +fn independent_rebuild_requires_exact_arrays_and_enough_budget() { + let encoded = encode([0.0; 3], 0.5, &[triangle_seed(0.0, 0, 0)]); + assert!(rebuild(&encoded.arrays(usize::MAX)).is_ok()); + + let mut extra_point = encoded.clone(); + extra_point.points.push(0); + assert_eq!(rebuild(&extra_point.arrays(usize::MAX)).unwrap_err(), "the decoded triangles do not use up the stored arrays",); + + let mut extra_slot = encoded.clone(); + extra_slot.is_reference.push(false); + assert_eq!(rebuild(&extra_slot.arrays(usize::MAX)).unwrap_err(), "the decoded triangles do not use up the stored arrays",); + + let mut extra_reference = encoded.clone(); + extra_reference.references.push(0); + assert_eq!(rebuild(&extra_reference.arrays(usize::MAX)).unwrap_err(), "the decoded triangles do not use up the stored arrays",); + + assert_eq!(rebuild(&encoded.arrays(0)).unwrap_err(), "the rebuild needs more than the decoded-element allowance left",); +} + +#[test] +fn independent_faces_group_walk_order_triangles() { + let encoded = encode([0.0; 3], 0.5, &[triangle_seed(0.0, 0, 1), triangle_seed(5.0, 0, 0)]); + let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap(); + let mesh = super::super::by_face(rebuilt, &encoded.face_of, encoded.faces(), &[]); + + assert_eq!(mesh.faces, [0..1, 1..2]); + assert_eq!(mesh.triangles, [[3, 4, 5], [0, 1, 2]]); + let expected = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [5.0, 0.0, 0.0], [7.0, 0.0, 0.0], [5.0, 2.0, 0.0]]; + assert_positions(&mesh.positions, &expected); +} From a528fa7430314b3a0905a5cdc86be39631bf86f8 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 11:23:04 +0100 Subject: [PATCH 016/349] rtf: keep right-to-left paragraph direction Read \rtlpar/\rtldir and \ltrpar/\ltrdir into the paragraph's bidi flag and write \rtlpar for right-to-left paragraphs. The flow paragraph carries the direction between the document and the RTF reader/writer. Co-Authored-By: Claude Sonnet 5.5 --- crates/flow/src/from_doc.rs | 3 +++ crates/flow/src/to_doc.rs | 3 +++ crates/flow/src/types.rs | 2 ++ crates/rtf/src/doc/export.rs | 4 ++++ crates/rtf/src/doc/state.rs | 3 +++ crates/rtf/src/doc/styles.rs | 1 + crates/rtf/src/doc/tests.rs | 30 ++++++++++++++++++++++++++++++ crates/rtf/src/doc/word.rs | 4 ++++ 8 files changed, 50 insertions(+) diff --git a/crates/flow/src/from_doc.rs b/crates/flow/src/from_doc.rs index 341ded449..ea7f6fc92 100644 --- a/crates/flow/src/from_doc.rs +++ b/crates/flow/src/from_doc.rs @@ -493,6 +493,8 @@ fn flow_paras_in(doc: &Document, p: &Paragraph, opts: FlowOpts) -> Vec { kind, list, align: p.props.align, + // Direction can come from the paragraph's style (`w:bidi` in the style's pPr). + rtl: doc.styles.resolve_para(&p.props).bidi, page_break: p.props.page_break_before.unwrap_or(false), keep_next: p.props.keep_next.unwrap_or(false), inlines: Vec::new(), @@ -536,6 +538,7 @@ fn flow_paras_in(doc: &Document, p: &Paragraph, opts: FlowOpts) -> Vec { kind, list: None, align: p.props.align, + rtl: out.rtl, page_break: true, keep_next: p.props.keep_next.unwrap_or(false), inlines: Vec::new(), diff --git a/crates/flow/src/to_doc.rs b/crates/flow/src/to_doc.rs index c10be85c2..ce29a4448 100644 --- a/crates/flow/src/to_doc.rs +++ b/crates/flow/src/to_doc.rs @@ -159,6 +159,9 @@ fn para_props(p: &Para, list_num: Option) -> ParaProps { out.numbering = Some(NumRef { num, level: li.level.min(8) }); } out.align = p.align; + if p.rtl { + out.bidi = Some(true); + } let sp = p.spacing; out.space_before = sp.before; out.space_after = sp.after; diff --git a/crates/flow/src/types.rs b/crates/flow/src/types.rs index e897778f9..f1c281c62 100644 --- a/crates/flow/src/types.rs +++ b/crates/flow/src/types.rs @@ -676,6 +676,8 @@ pub struct Para { pub kind: Kind, pub list: Option, pub align: Option, + /// The paragraph reads right to left (OOXML `w:bidi`, RTF `\rtlpar`). + pub rtl: bool, pub page_break: bool, /// Keep the paragraph on the same page as the next one (ODT `fo:keep-with-next`). pub keep_next: bool, diff --git a/crates/rtf/src/doc/export.rs b/crates/rtf/src/doc/export.rs index 69fab3d76..8f0f1734b 100644 --- a/crates/rtf/src/doc/export.rs +++ b/crates/rtf/src/doc/export.rs @@ -664,6 +664,10 @@ impl Writer { Some(Align::Distribute) => out.push_str("\\qd"), _ => out.push_str("\\ql"), } + // The paragraph's text direction, as Word writes it (`\rtlpar`; `\ltrpar` is the default). + if p.rtl { + out.push_str("\\rtlpar"); + } if p.page_break { out.push_str("\\pagebb"); } diff --git a/crates/rtf/src/doc/state.rs b/crates/rtf/src/doc/state.rs index 486b94a32..1f5d8d2e6 100644 --- a/crates/rtf/src/doc/state.rs +++ b/crates/rtf/src/doc/state.rs @@ -148,6 +148,8 @@ pub(super) struct St { pub(super) hidden: bool, // Paragraph properties. pub(super) align: Option, + /// `\rtlpar`: the paragraph reads right to left. + pub(super) rtldir: bool, pub(super) style: i32, pub(super) intbl: bool, pub(super) ls: Option, @@ -185,6 +187,7 @@ impl Default for St { uc: 1, hidden: false, align: None, + rtldir: false, style: 0, intbl: false, ls: None, diff --git a/crates/rtf/src/doc/styles.rs b/crates/rtf/src/doc/styles.rs index 014a105b4..dd42f3b87 100644 --- a/crates/rtf/src/doc/styles.rs +++ b/crates/rtf/src/doc/styles.rs @@ -87,6 +87,7 @@ impl Reader { pub(super) fn para_props(&self, st: &St) -> Para { let mut p = Para::new(self.para_kind(st)); p.align = st.align; + p.rtl = st.rtldir; p.page_break = st.pagebb; p.spacing = spacing(st); p.borders = st.borders.any_visible().then_some(st.borders); diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index 7c1075a86..9274104ab 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -38,6 +38,36 @@ fn basic_reader() { assert!(matches!(&l.inlines[0], Inline::Text(_, f) if f.link.as_deref() == Some("http://a.b"))); } +#[test] +fn rtl_paragraphs_read_and_write_their_direction() { + // Word writes an RTL paragraph as `\rtlpar` (`\ltrpar` for LTR); reading it keeps the + // direction as w:bidi on the document paragraph, and export writes it back. + let rtf = br#"{\rtf1\ansi\pard\rtlpar RTL\par\pard\ltrpar LTR\par\pard plain\par}"#; + let flow = parse(rtf).unwrap(); + let paras: Vec<&Para> = flow.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect(); + assert!(paras[0].rtl, "rtlpar sets the direction"); + assert!(!paras[1].rtl && !paras[2].rtl, "ltrpar and no word: not RTL"); + // \rtldir and \ltrdir, which some writers used for paragraphs, are read too. + let old = parse(br#"{\rtf1\ansi\pard\rtldir RTL\par\pard\ltrdir LTR\par}"#).unwrap(); + let old: Vec<&Para> = old.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect(); + assert!(old[0].rtl && !old[1].rtl, "rtldir and ltrdir are read"); + // \pard resets the direction. + let reset = parse(br#"{\rtf1\ansi\pard\rtlpar A\par\pard B\par}"#).unwrap(); + let reset: Vec<&Para> = reset.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p) } else { None }).collect(); + assert!(reset[0].rtl && !reset[1].rtl, "pard resets the direction"); + // Import keeps it as bidi on the document paragraph. + let bidi = |d: &Document| { + d.body.iter().filter_map(|b| if let Block::Para(p) = &**b { Some(p.props.bidi.unwrap_or(false)) } else { None }).collect::>() + }; + let doc = import(rtf).unwrap(); + assert_eq!(bidi(&doc), [true, false, false]); + // Export writes \rtlpar once, and not the \rtldir. + let out = export(&doc); + assert_eq!(out.matches("\\rtlpar").count(), 1, "{out}"); + assert!(!out.contains("rtldir"), "{out}"); + assert_eq!(bidi(&import(out.as_bytes()).unwrap()), [true, false, false]); +} + #[test] fn stylesheet_names_take_unicode_escapes() { // \u116?=t \u105?=i \u116?=t \u108?=l \u101?=e — how Word writes a non-Latin style name. diff --git a/crates/rtf/src/doc/word.rs b/crates/rtf/src/doc/word.rs index 28360c616..bf163db0c 100644 --- a/crates/rtf/src/doc/word.rs +++ b/crates/rtf/src/doc/word.rs @@ -171,6 +171,10 @@ impl Reader { "qr" => self.st.align = Some(Align::Right), "qj" => self.st.align = Some(Align::Justify), "qd" => self.st.align = Some(Align::Distribute), + // `\rtldir`/`\ltrdir` are not paragraph words (they set a table's or section's + // direction in RTF); some writers used them for paragraphs, so they are read too. + "rtlpar" | "rtldir" => self.st.rtldir = true, + "ltrpar" | "ltrdir" => self.st.rtldir = false, "s" => self.st.style = pv, "outlinelevel" => self.st.outline = Some(pv.clamp(0, 9) as u8), "pagebb" => self.st.pagebb = on, From b6a2df0c1d76729c7bca72113000948c49841efe Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 11:27:03 +0100 Subject: [PATCH 017/349] docx: chart axis and series formatting Add the series formatting (fill, line, markers, smooth, labels, number format) and the category/value axis formatting (title, bounds, number format, gridlines, tick labels, axis line) to the chart model, and read and write them in the DOCX chart part. GraphicItem::Text gets an angle for the rotated vertical axis title. With none of the new fields set the chart part is written as before. Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/chart_spec.rs | 399 +++++++++++++++++++---- crates/docx/src/read/chart.rs | 4 +- crates/docx/src/read/chart/canvas.rs | 7 +- crates/docx/src/read/chart/model.rs | 29 +- crates/docx/src/read/chart/parse.rs | 18 +- crates/docx/src/read/chart/plot.rs | 162 +++++++-- crates/docx/src/read/chart/polar.rs | 6 +- crates/docx/src/read/diagram.rs | 11 +- crates/docx/src/write/embed.rs | 3 +- crates/flow/src/from_doc.rs | 2 +- crates/odf/src/text/chart.rs | 7 +- crates/odf/src/text/tests_more/charts.rs | 18 +- crates/odf/src/text/tests_more/groups.rs | 1 + crates/wordmodel/src/chart.rs | 172 +++++++++- crates/wordmodel/src/graphic.rs | 6 +- 15 files changed, 726 insertions(+), 119 deletions(-) diff --git a/crates/docx/src/chart_spec.rs b/crates/docx/src/chart_spec.rs index e31363903..1950b15bf 100644 --- a/crates/docx/src/chart_spec.rs +++ b/crates/docx/src/chart_spec.rs @@ -6,7 +6,7 @@ //! [`spec_of`] turns a chart part back into the model only when writing that model again gives //! the same markup, so a chart with anything the model leaves out stays as it was read. -use craft_wordmodel::chart::{ChartSeries, ChartSpec, ChartType, LegendPos, MAX_POINTS, MAX_SERIES}; +use craft_wordmodel::chart::{ChartAxis, ChartSeries, ChartSpec, ChartType, LegendPos, MAX_POINTS, MAX_SERIES}; use craft_wordmodel::graphic::GraphicItem; use craft_wordmodel::props::Rgb; @@ -102,11 +102,24 @@ fn bounded(spec: &ChartSpec) -> ChartSpec { .series .iter() .take(MAX_SERIES) - .map(|s| ChartSeries { name: s.name.clone(), values: s.values.iter().take(MAX_POINTS).copied().collect() }) + .map(|s| ChartSeries { + name: s.name.clone(), + values: s.values.iter().take(MAX_POINTS).copied().collect(), + fill: s.fill, + no_fill: s.no_fill, + line_w: s.line_w, + no_line: s.no_line, + markers: s.markers, + smooth: s.smooth, + labels: s.labels, + fmt: s.fmt.clone(), + }) .collect(), title: spec.title.clone(), legend: spec.legend, data_labels: spec.data_labels, + cat_axis: spec.cat_axis.clone(), + val_axis: spec.val_axis.clone(), } .sanitized() } @@ -185,17 +198,19 @@ fn plot(w: &mut W, spec: &ChartSpec) { match k { ChartType::Pie | ChartType::Doughnut => {} ChartType::Scatter => { - value_axis(w, CAT_AX, VAL_AX, "b", false, "midCat"); - value_axis(w, VAL_AX, CAT_AX, "l", true, "midCat"); + value_axis(w, CAT_AX, VAL_AX, "b", "midCat", &spec.cat_axis); + value_axis(w, VAL_AX, CAT_AX, "l", "midCat", &spec.val_axis); } _ => { - category_axis(w, if horizontal { "l" } else { "b" }); - value_axis(w, VAL_AX, CAT_AX, if horizontal { "b" } else { "l" }, true, "between"); + category_axis(w, if horizontal { "l" } else { "b" }, &spec.cat_axis); + value_axis(w, VAL_AX, CAT_AX, if horizontal { "b" } else { "l" }, "between", &spec.val_axis); } } } -/// One `c:ser` (ECMA-376 element order: idx, order, tx, spPr, marker, cat/xVal, val/yVal, smooth). +/// One `c:ser` (ECMA-376 element order: idx, order, tx, spPr, marker, invertIfNegative, dLbls, +/// cat/xVal, val/yVal, smooth): the series' formatting (fill, line, markers, its own labels) sits +/// in `c:spPr`, `c:marker` and `c:dLbls`; the values carry their number format. fn series(w: &mut W, spec: &ChartSpec, i: usize, s: &ChartSeries) { let k = spec.kind; let i = i.to_string(); @@ -207,25 +222,26 @@ fn series(w: &mut W, spec: &ChartSpec, i: usize, s: &ChartSeries) { w.leaf("c:v", &[], &s.name); w.close("c:tx"); } - match k { - // Markers only: the series has no line. - ChartType::Scatter => { - w.open("c:spPr", &[]); - w.open("a:ln", &[("w", "19050")]); - w.empty("a:noFill", &[]); - w.close("a:ln"); - w.close("c:spPr"); - } - ChartType::Column | ChartType::ColumnStacked | ChartType::Bar | ChartType::BarStacked => { - w.empty("c:invertIfNegative", &[("val", "0")]); - } - ChartType::Line => { - w.open("c:marker", &[]); - w.empty("c:symbol", &[("val", "none")]); - w.close("c:marker"); - } - _ => {} + series_props(w, s); + series_marker(w, k, s); + if matches!(k, ChartType::Column | ChartType::ColumnStacked | ChartType::Bar | ChartType::BarStacked) { + w.empty("c:invertIfNegative", &[("val", "0")]); } + if let Some(on) = s.labels { + w.open("c:dLbls", &[]); + for (name, show) in [ + ("c:showLegendKey", false), + ("c:showVal", on), + ("c:showCatName", false), + ("c:showSerName", false), + ("c:showPercent", false), + ("c:showBubbleSize", false), + ] { + w.empty(name, &[("val", if show { "1" } else { "0" })]); + } + w.close("c:dLbls"); + } + let code = s.fmt.as_deref().unwrap_or("General"); if k == ChartType::Scatter { let xs: Option>> = spec .categories @@ -234,27 +250,84 @@ fn series(w: &mut W, spec: &ChartSpec, i: usize, s: &ChartSeries) { .collect(); w.open("c:xVal", &[]); match xs { - Some(xs) => num_lit(w, &xs), + Some(xs) => num_lit(w, &xs, "General"), None => str_lit(w, &spec.categories), } w.close("c:xVal"); w.open("c:yVal", &[]); - num_lit(w, &s.values); + num_lit(w, &s.values, code); w.close("c:yVal"); } else { w.open("c:cat", &[]); str_lit(w, &spec.categories); w.close("c:cat"); w.open("c:val", &[]); - num_lit(w, &s.values); + num_lit(w, &s.values, code); w.close("c:val"); } if matches!(k, ChartType::Line | ChartType::Scatter) { - w.empty("c:smooth", &[("val", "0")]); + w.empty("c:smooth", &[("val", if s.smooth { "1" } else { "0" })]); } w.close("c:ser"); } +/// `c:spPr`: the series' fill (`a:solidFill` / `a:noFill`) and line (`a:ln`), written when the +/// model sets them. `a:ln` without `w` is the default width, `w` a fixed one, and `a:noFill` +/// inside it "no line" (a scatter series keeps its markers with no line). +fn series_props(w: &mut W, s: &ChartSeries) { + let fill_set = s.no_fill || s.fill.is_some(); + let ln_set = s.no_line || s.line_w.is_some(); + if !(fill_set || ln_set) { + return; + } + w.open("c:spPr", &[]); + if fill_set { + match &s.fill { + Some(c) => { + w.open("a:solidFill", &[]); + w.empty("a:srgbClr", &[("val", &c.hex())]); + w.close("a:solidFill"); + } + None => w.empty("a:noFill", &[]), + } + } + if ln_set { + let w_attr = s.line_w.map(emu).unwrap_or_default(); + let attrs = [("w", w_attr.as_str())]; + w.open("a:ln", if w_attr.is_empty() { &[] } else { &attrs }); + if s.no_line { + w.empty("a:noFill", &[]); + } + w.close("a:ln"); + } + w.close("c:spPr"); +} + +/// `c:marker`: line and scatter series say which symbol each point gets; other types have none. +fn series_marker(w: &mut W, k: ChartType, s: &ChartSeries) { + match k { + ChartType::Line => { + w.open("c:marker", &[]); + w.empty("c:symbol", &[("val", if s.markers == Some(true) { "circle" } else { "none" })]); + w.close("c:marker"); + } + // Unset: no `c:marker`, so Word picks its automatic symbol for each series. + ChartType::Scatter => { + if let Some(on) = s.markers { + w.open("c:marker", &[]); + w.empty("c:symbol", &[("val", if on { "circle" } else { "none" })]); + w.close("c:marker"); + } + } + _ => {} + } +} + +/// A line width in points as the `w` attribute DrawingML wants (EMU). +fn emu(pt: f32) -> String { + ((pt * 12700.0).round().max(0.0) as i64).to_string() +} + fn str_lit(w: &mut W, items: &[String]) { w.open("c:strLit", &[]); w.empty("c:ptCount", &[("val", &items.len().to_string())]); @@ -266,9 +339,9 @@ fn str_lit(w: &mut W, items: &[String]) { w.close("c:strLit"); } -fn num_lit(w: &mut W, values: &[Option]) { +fn num_lit(w: &mut W, values: &[Option], code: &str) { w.open("c:numLit", &[]); - w.leaf("c:formatCode", &[], "General"); + w.leaf("c:formatCode", &[], code); w.empty("c:ptCount", &[("val", &values.len().to_string())]); for (i, v) in values.iter().enumerate() { if let Some(v) = v.filter(|v| v.is_finite()) { @@ -285,17 +358,21 @@ fn num(v: f64) -> String { if v == 0.0 { "0".to_string() } else { format!("{v}") } } -fn category_axis(w: &mut W, pos: &str) { +fn category_axis(w: &mut W, pos: &str, ax: &ChartAxis) { w.open("c:catAx", &[]); w.empty("c:axId", &[("val", CAT_AX)]); - w.open("c:scaling", &[]); - w.empty("c:orientation", &[("val", "minMax")]); - w.close("c:scaling"); + scaling(w, ax); w.empty("c:delete", &[("val", "0")]); w.empty("c:axPos", &[("val", pos)]); + if ax.gridlines { + w.empty("c:majorGridlines", &[]); + } + axis_title(w, ax); + num_fmt(w, ax); w.empty("c:majorTickMark", &[("val", "none")]); w.empty("c:minorTickMark", &[("val", "none")]); - w.empty("c:tickLblPos", &[("val", "nextTo")]); + w.empty("c:tickLblPos", &[("val", if ax.labels { "nextTo" } else { "none" })]); + axis_line(w, ax); w.empty("c:crossAx", &[("val", VAL_AX)]); w.empty("c:crosses", &[("val", "autoZero")]); w.empty("c:auto", &[("val", "1")]); @@ -305,34 +382,81 @@ fn category_axis(w: &mut W, pos: &str) { w.close("c:catAx"); } -/// A value axis: with gridlines and no axis line (`grid`), else with its line and no gridlines. -fn value_axis(w: &mut W, id: &str, cross: &str, pos: &str, grid: bool, between: &str) { +/// A value axis (scatter x axes included): its scale, gridlines, title, labels and line, as the +/// model sets them. +fn value_axis(w: &mut W, id: &str, cross: &str, pos: &str, between: &str, ax: &ChartAxis) { w.open("c:valAx", &[]); w.empty("c:axId", &[("val", id)]); - w.open("c:scaling", &[]); - w.empty("c:orientation", &[("val", "minMax")]); - w.close("c:scaling"); + scaling(w, ax); w.empty("c:delete", &[("val", "0")]); w.empty("c:axPos", &[("val", pos)]); - if grid { + if ax.gridlines { w.empty("c:majorGridlines", &[]); } + axis_title(w, ax); + num_fmt(w, ax); w.empty("c:majorTickMark", &[("val", "none")]); w.empty("c:minorTickMark", &[("val", "none")]); - w.empty("c:tickLblPos", &[("val", "nextTo")]); - if grid { - w.open("c:spPr", &[]); - w.open("a:ln", &[]); - w.empty("a:noFill", &[]); - w.close("a:ln"); - w.close("c:spPr"); - } + w.empty("c:tickLblPos", &[("val", if ax.labels { "nextTo" } else { "none" })]); + axis_line(w, ax); w.empty("c:crossAx", &[("val", cross)]); w.empty("c:crosses", &[("val", "autoZero")]); w.empty("c:crossBetween", &[("val", between)]); w.close("c:valAx"); } +/// `c:scaling`: the orientation, then the fixed bounds when the model sets them. +fn scaling(w: &mut W, ax: &ChartAxis) { + w.open("c:scaling", &[]); + w.empty("c:orientation", &[("val", "minMax")]); + for (name, v) in [("c:max", ax.max), ("c:min", ax.min)] { + if let Some(v) = v.filter(|v| v.is_finite()) { + w.empty(name, &[("val", &num(v))]); + } + } + w.close("c:scaling"); +} + +/// The axis title, in the same rich-text shape the chart title uses. +fn axis_title(w: &mut W, ax: &ChartAxis) { + let Some(t) = &ax.title else { return }; + w.open("c:title", &[]); + w.open("c:tx", &[]); + w.open("c:rich", &[]); + w.empty("a:bodyPr", &[]); + w.empty("a:lstStyle", &[]); + w.open("a:p", &[]); + w.open("a:r", &[]); + w.leaf("a:t", &[], t); + w.close("a:r"); + w.close("a:p"); + w.close("c:rich"); + w.close("c:tx"); + w.empty("c:overlay", &[("val", "0")]); + w.close("c:title"); +} + +/// Tick-label number format: the model's code, unlinked from the source, else the default. +fn num_fmt(w: &mut W, ax: &ChartAxis) { + match &ax.fmt { + Some(code) => w.empty("c:numFmt", &[("formatCode", code), ("sourceLinked", "0")]), + None => w.empty("c:numFmt", &[("formatCode", "General"), ("sourceLinked", "1")]), + } +} + +/// `c:spPr`: an axis line only when the model keeps it (the default writes nothing, which reads +/// as a line); `a:noFill` when the axis line is off. +fn axis_line(w: &mut W, ax: &ChartAxis) { + if ax.line { + return; + } + w.open("c:spPr", &[]); + w.open("a:ln", &[]); + w.empty("a:noFill", &[]); + w.close("a:ln"); + w.close("c:spPr"); +} + /// The chart a chart part holds, when the part is exactly what [`chart_xml`] writes for it (so /// editing and saving it loses nothing). `None` for any other chart. pub(crate) fn spec_of(space: &El) -> Option { @@ -365,15 +489,40 @@ pub(crate) fn spec_of(space: &El) -> Option { let categories = sers.first().and_then(|s| s.child(if scatter { "c:xVal" } else { "c:cat" })).map(literal).unwrap_or_default(); let series = sers .iter() - .map(|s| ChartSeries { - name: s.child("c:tx").and_then(|t| t.child("c:v")).map(|v| v.text()).unwrap_or_default(), - values: s - .child(if scatter { "c:yVal" } else { "c:val" }) - .map(literal) - .unwrap_or_default() - .iter() - .map(|v| v.parse::().ok().filter(|v| v.is_finite())) - .collect(), + .map(|s| { + let ln = s.child("c:spPr").and_then(|p| p.child("a:ln")); + let symbol = s.child("c:marker").and_then(|m| m.child("c:symbol")).and_then(|m| m.attr("val")); + ChartSeries { + name: s.child("c:tx").and_then(|t| t.child("c:v")).map(|v| v.text()).unwrap_or_default(), + values: s + .child(if scatter { "c:yVal" } else { "c:val" }) + .map(literal) + .unwrap_or_default() + .iter() + .map(|v| v.parse::().ok().filter(|v| v.is_finite())) + .collect(), + fill: s + .child("c:spPr") + .and_then(|p| p.child("a:solidFill")) + .and_then(|f| f.child("a:srgbClr")) + .and_then(|c| c.attr("val")) + .and_then(Rgb::parse), + no_fill: s.child("c:spPr").and_then(|p| p.child("a:noFill")).is_some(), + line_w: ln.and_then(|l| l.attr("w")).and_then(|w| w.parse::().ok()).filter(|w| w.is_finite()).map(|w| (w / 12700.0) as f32), + no_line: ln.and_then(|l| l.child("a:noFill")).is_some(), + // Line series show no markers by default: only a setting that differs from that + // belongs in the model. A scatter series keeps what the file says, so a missing + // `c:marker` (Word's automatic symbols) stays unset and is not written back. + markers: symbol.map(|v| v != "none").filter(|m| scatter || *m), + smooth: s.child("c:smooth").and_then(|v| v.attr("val")).is_some_and(|v| v == "1"), + labels: s.child("c:dLbls").and_then(|d| d.child("c:showVal")).and_then(|v| v.attr("val")).map(|v| v == "1"), + fmt: s + .child(if scatter { "c:yVal" } else { "c:val" }) + .and_then(|v| v.els().find(|e| e.name == "c:numLit")) + .and_then(|l| l.child("c:formatCode")) + .map(|f| f.text()) + .filter(|f| *f != "General"), + } }) .collect(); let title = chart.child("c:title").and_then(|t| t.find("a:t")).map(|t| t.text()); @@ -384,12 +533,48 @@ pub(crate) fn spec_of(space: &El) -> Option { _ => LegendPos::Right, }); let data_labels = ty.child("c:dLbls").and_then(|d| d.child("c:showVal")).and_then(|v| v.attr("val")) == Some("1"); - let spec = ChartSpec { kind, categories, series, title, legend, data_labels }.sanitized(); - // Editable only when nothing would be lost: writing the model again gives the same part. - let again = xml::parse(chart_xml(&spec).as_bytes()).ok()?; + let (cat_a, val_a) = crate::read::chart::chart_axes(plot, scatter); + let axis = |a: crate::read::chart::Axis| ChartAxis { + title: a.title, + min: a.min, + max: a.max, + fmt: a.fmt, + gridlines: a.grid, + labels: a.labels, + line: a.line, + }; + let spec = ChartSpec { kind, categories, series, title, legend, data_labels, cat_axis: axis(cat_a), val_axis: axis(val_a) }.sanitized(); + // Editable only when nothing would be lost: writing the model again gives the same part, as + // this writer or the earlier one wrote it. + let mut again = xml::parse(chart_xml(&spec).as_bytes()).ok()?; + if same(space, &again, 0) { + return Some(spec); + } + as_previous_writer(&mut again); same(space, &again, 0).then_some(spec) } +/// `part` (what [`chart_xml`] writes) as the earlier WordCraft writer wrote the same model: it +/// had no axis `c:numFmt`. Only that element goes, and only with the value its absence reads as +/// (General, linked to the source), so a part that matches still holds nothing the model leaves out. +fn as_previous_writer(part: &mut El) { + fn els_mut(e: &mut El) -> impl Iterator { + e.kids.iter_mut().filter_map(|n| match n { + Node::El(e) => Some(e), + Node::Text(_) => None, + }) + } + fn drop_els(e: &mut El, drop: impl Fn(&El) -> bool) { + e.kids.retain(|n| !matches!(n, Node::El(c) if drop(c))); + } + let Some(plot) = els_mut(part).find(|e| e.name == "c:chart").and_then(|c| els_mut(c).find(|e| e.name == "c:plotArea")) else { return }; + for e in els_mut(plot) { + if matches!(e.name.as_str(), "c:catAx" | "c:valAx") { + drop_els(e, |c| c.name == "c:numFmt" && c.attr("sourceLinked") == Some("1")); + } + } +} + /// The points of a `c:strLit` / `c:numLit` (or a cache) as texts by index, `ptCount` long. fn literal(e: &El) -> Vec { let Some(lit) = e.els().find(|c| matches!(c.name.as_str(), "c:strLit" | "c:numLit")) else { return Vec::new() }; @@ -461,10 +646,11 @@ mod tests { let spec = ChartSpec { kind: ChartType::Column, categories: (0..4500).map(|i| i.to_string()).collect(), - series: (0..300).map(|i| ChartSeries { name: format!("S{i}"), values: vec![Some(1.0); 4500] }).collect(), + series: (0..300).map(|i| ChartSeries { name: format!("S{i}"), values: vec![Some(1.0); 4500], ..Default::default() }).collect(), title: None, legend: None, data_labels: false, + ..Default::default() }; let x = chart_xml(&spec); let series = x.matches("").count(); @@ -500,6 +686,61 @@ mod tests { assert_eq!(spec_of(&xml::parse(x.as_bytes()).unwrap()), None); } + /// Chart parts as the previous WordCraft chart writer saved them (its output for + /// `ChartSpec::sample`): no axis `c:numFmt`, and scatter series with no `c:marker`. + const PREVIOUS_COLUMN: &str = r#"Series 1Q1Q2Q3Q4General3.24.13.65Series 2Q1Q2Q3Q4General22.73.93.3Series 3Q1Q2Q3Q4General1.52.22.43.8"#; + const PREVIOUS_SCATTER: &str = r#"Series 1General1234General2.13.434.6Series 2General1234General1.21.92.83.1"#; + + #[test] + fn charts_saved_by_the_previous_writer_stay_editable() { + for (x, kind) in [(PREVIOUS_COLUMN, ChartType::Column), (PREVIOUS_SCATTER, ChartType::Scatter)] { + let spec = spec_of(&xml::parse(x.as_bytes()).unwrap()).unwrap_or_else(|| panic!("{kind:?}: the earlier part is read-only")); + assert_eq!((spec.kind, spec.series.len()), (kind, if kind == ChartType::Scatter { 2 } else { 3 })); + assert_eq!((spec.cat_axis.fmt.as_deref(), spec.val_axis.fmt.as_deref()), (None, None), "{kind:?}"); + assert!(spec.series.iter().all(|s| s.markers.is_none()), "{kind:?}: markers unset"); + // Saved again, it is in the current shape and still reads back as the same model. + assert_eq!(spec_of(&parse(&spec)).as_ref(), Some(&spec), "{kind:?}"); + } + // What neither writer writes still keeps such a part read-only: an axis format linked to + // the source that isn't General, a scatter marker other than the default, a marker size. + let edited = |x: &str, from: &str, to: &str| { + assert!(x.contains(from), "{from}"); + spec_of(&xml::parse(x.replacen(from, to, 1).as_bytes()).unwrap()) + }; + let ax = r#""#; + assert_eq!(edited(PREVIOUS_COLUMN, ax, &format!(r#"{ax}"#)), None); + let ln = r#""#; + assert_eq!(edited(PREVIOUS_SCATTER, ln, &format!(r#"{ln}"#)), None); + assert_eq!(edited(PREVIOUS_SCATTER, ln, &format!(r#"{ln}"#)), None); + assert_eq!(edited(PREVIOUS_COLUMN, "", ""), None); + } + + /// A scatter series with no `c:marker` (Word's automatic symbols) stays without one after an + /// unrelated edit and a save; an explicit circle or "none" stays explicit. + #[test] + fn scatter_series_without_a_marker_stay_without_after_a_save() { + let marker_of = |x: &El| -> Vec> { + let sc = x.child("c:chart").unwrap().child("c:plotArea").unwrap().child("c:scatterChart").unwrap(); + sc.children("c:ser").map(|s| s.child("c:marker").map(|m| m.child("c:symbol").unwrap().attr("val").unwrap().to_string())).collect() + }; + let mut spec = spec_of(&xml::parse(PREVIOUS_SCATTER.as_bytes()).unwrap()).unwrap(); + assert_eq!(marker_of(&xml::parse(PREVIOUS_SCATTER.as_bytes()).unwrap()), [None, None]); + spec.title = Some("Edited".into()); + spec.series[0].name = "Renamed".into(); + let saved = parse(&spec); + assert_eq!(marker_of(&saved), [None, None]); + let again = spec_of(&saved).unwrap(); + assert_eq!(again, spec); + assert!(again.series.iter().all(|s| s.markers.is_none())); + // Explicit choices are kept as written. + spec.series[0].markers = Some(true); + spec.series[1].markers = Some(false); + let saved = parse(&spec); + assert_eq!(marker_of(&saved), [Some("circle".to_string()), Some("none".to_string())]); + let again = spec_of(&saved).unwrap(); + assert_eq!((again.series[0].markers, again.series[1].markers), (Some(true), Some(false))); + } + #[test] fn elements_come_in_schema_order() { let mut spec = ChartSpec::sample(ChartType::ColumnStacked); @@ -517,6 +758,11 @@ mod tests { ["c:barDir", "c:grouping", "c:varyColors", "c:ser", "c:ser", "c:ser", "c:dLbls", "c:gapWidth", "c:overlap", "c:axId", "c:axId"] ); assert_eq!(names(bar.child("c:ser").unwrap()), ["c:idx", "c:order", "c:tx", "c:invertIfNegative", "c:cat", "c:val"]); + // A series with its own labels keeps `c:invertIfNegative` ahead of `c:dLbls` (CT_BarSer). + spec.series[0].labels = Some(true); + let labelled = parse(&spec); + let ser = labelled.child("c:chart").unwrap().child("c:plotArea").unwrap().child("c:barChart").unwrap().child("c:ser").unwrap(); + assert_eq!(names(ser), ["c:idx", "c:order", "c:tx", "c:invertIfNegative", "c:dLbls", "c:cat", "c:val"]); let val_ax = plot.child("c:valAx").unwrap(); assert_eq!( names(val_ax), @@ -526,6 +772,7 @@ mod tests { "c:delete", "c:axPos", "c:majorGridlines", + "c:numFmt", "c:majorTickMark", "c:minorTickMark", "c:tickLblPos", @@ -535,13 +782,35 @@ mod tests { "c:crossBetween" ] ); + let cat_ax = plot.child("c:catAx").unwrap(); + assert_eq!( + names(cat_ax), + [ + "c:axId", + "c:scaling", + "c:delete", + "c:axPos", + "c:numFmt", + "c:majorTickMark", + "c:minorTickMark", + "c:tickLblPos", + "c:crossAx", + "c:crosses", + "c:auto", + "c:lblAlgn", + "c:lblOffset", + "c:noMultiLvlLbl" + ] + ); let line = parse(&ChartSpec { data_labels: true, ..ChartSpec::sample(ChartType::Line) }); let lc = line.child("c:chart").unwrap().child("c:plotArea").unwrap().child("c:lineChart").unwrap(); assert_eq!(names(lc), ["c:grouping", "c:varyColors", "c:ser", "c:ser", "c:ser", "c:dLbls", "c:marker", "c:axId", "c:axId"]); assert_eq!(names(lc.child("c:ser").unwrap()), ["c:idx", "c:order", "c:tx", "c:marker", "c:cat", "c:val", "c:smooth"]); - let sc = parse(&ChartSpec::sample(ChartType::Scatter)); + let mut scatter = ChartSpec::sample(ChartType::Scatter); + scatter.series.iter_mut().for_each(|s| s.markers = Some(true)); + let sc = parse(&scatter); let sc = sc.child("c:chart").unwrap().child("c:plotArea").unwrap().child("c:scatterChart").unwrap(); - assert_eq!(names(sc.child("c:ser").unwrap()), ["c:idx", "c:order", "c:tx", "c:spPr", "c:xVal", "c:yVal", "c:smooth"]); + assert_eq!(names(sc.child("c:ser").unwrap()), ["c:idx", "c:order", "c:tx", "c:spPr", "c:marker", "c:xVal", "c:yVal", "c:smooth"]); let dn = parse(&ChartSpec::sample(ChartType::Doughnut)); let dn = dn.child("c:chart").unwrap().child("c:plotArea").unwrap(); assert_eq!(names(dn), ["c:layout", "c:doughnutChart"]); diff --git a/crates/docx/src/read/chart.rs b/crates/docx/src/read/chart.rs index a0087a3bb..5b02603d6 100644 --- a/crates/docx/src/read/chart.rs +++ b/crates/docx/src/read/chart.rs @@ -29,7 +29,9 @@ pub(super) use canvas::text_w; use canvas::{Rect, clip_text, legend, text}; #[cfg(test)] use format::{civil, excel_stamp, format_value}; -use model::{Axis, Grouping, Kind, Pos, Series}; +pub(crate) use model::Axis; +use model::{Grouping, Kind, Pos, Series}; +pub(crate) use parse::chart_axes; #[cfg(test)] use parse::{axis, category_text, labels, numbers}; use parse::{read_series, text_size, title_of}; diff --git a/crates/docx/src/read/chart/canvas.rs b/crates/docx/src/read/chart/canvas.rs index a8280e4ba..ab3fbf410 100644 --- a/crates/docx/src/read/chart/canvas.rs +++ b/crates/docx/src/read/chart/canvas.rs @@ -41,8 +41,13 @@ pub(super) fn widest(items: &[String], size: f32) -> f32 { items.iter().map(|s| text_w(s, size)).fold(0.0, f32::max) } +/// Text in `rect`; `angle` degrees clockwise turns it about the rect's centre (axis titles). pub(super) fn text(out: &mut Vec, rect: Rect, s: &str, size: f32, align: TextAlign, bold: bool) { - out.push(GraphicItem::Text { rect: rect.arr(), text: s.to_string(), size, color: TEXT, bold, align, font: None }); + text_angle(out, rect, s, size, align, bold, 0.0); +} + +pub(super) fn text_angle(out: &mut Vec, rect: Rect, s: &str, size: f32, align: TextAlign, bold: bool, angle: f32) { + out.push(GraphicItem::Text { rect: rect.arr(), text: s.to_string(), size, color: TEXT, bold, align, font: None, angle }); } /// Text centred on `cx` with its top at `y`. diff --git a/crates/docx/src/read/chart/model.rs b/crates/docx/src/read/chart/model.rs index 71ee7040f..fd2760db0 100644 --- a/crates/docx/src/read/chart/model.rs +++ b/crates/docx/src/read/chart/model.rs @@ -52,16 +52,21 @@ pub(super) enum Pos { /// One value axis (or category axis) as the file states it. #[derive(Default)] -pub(super) struct Axis { - pub(super) deleted: bool, - pub(super) grid: bool, - pub(super) line: bool, +pub(crate) struct Axis { + pub(crate) deleted: bool, + pub(crate) grid: bool, + pub(crate) line: bool, /// `c:crossBetween val="midCat"`: categories sit on the tick marks, not between them. pub(super) mid: bool, - pub(super) min: Option, - pub(super) max: Option, + pub(crate) min: Option, + pub(crate) max: Option, /// Number format of the tick labels, when not linked to the source data. - pub(super) fmt: Option, + pub(crate) fmt: Option, + /// The axis title, when the file gives it one. + pub(crate) title: Option, + /// Tick labels, as `c:tickLblPos` says (`none` hides them; a file that says nothing shows + /// them, as Word does). + pub(crate) labels: bool, } pub(super) struct Series { @@ -70,9 +75,17 @@ pub(super) struct Series { /// when missing or not a valid number. pub(super) idx: Option, pub(super) color: Option, - pub(super) line_w: f32, + /// Fixed line width in points, `None`: the chart's default. + pub(super) line_w: Option, /// Whether the series is drawn as a line (scatter series without one get markers). pub(super) line: bool, + /// The series' own fill: `Some` colour, `None` colour with `no_fill` set, else the chart's + /// accent for the series. + pub(super) no_fill: bool, + /// Markers on the series' points, when the file says. + pub(super) markers: Option, + /// Draw the series' line as a smooth curve (`c:smooth`). + pub(super) smooth: bool, pub(super) values: Vec>, /// Scatter x values (index + 1 when the file has none). pub(super) xs: Vec>, diff --git a/crates/docx/src/read/chart/parse.rs b/crates/docx/src/read/chart/parse.rs index 3c09fcfe9..45586509b 100644 --- a/crates/docx/src/read/chart/parse.rs +++ b/crates/docx/src/read/chart/parse.rs @@ -1,7 +1,7 @@ use super::format::{date_text, excel_stamp, format_value, is_date_code}; use super::model::{Axis, Grouping, Kind, Pos, Series}; use super::plot::label; -use super::{Chart, El, FONT, LINE_W, MAX_CELLS, MAX_POINTS, MAX_RADAR_SERIES, MAX_SERIES, MAX_SPOKES, Rgb, fill_colour, int, measure, slot}; +use super::{Chart, El, FONT, MAX_CELLS, MAX_POINTS, MAX_RADAR_SERIES, MAX_SERIES, MAX_SPOKES, Rgb, fill_colour, int, measure, slot}; impl Chart { pub(super) fn parse(space: &El, theme: &[Rgb]) -> Option { @@ -149,7 +149,7 @@ fn to_percent(series: &mut [Series], n: usize) { } /// The category axis (scatter: the horizontal value axis) and the value axis of a plot area. -fn chart_axes(plot: &El, scatter: bool) -> (Axis, Axis) { +pub(crate) fn chart_axes(plot: &El, scatter: bool) -> (Axis, Axis) { let vals_ax: Vec<&El> = plot.children("c:valAx").collect(); let horiz_pos = |a: &&El| matches!(a.child("c:axPos").and_then(|p| p.attr("val")), Some("b" | "t")); let (val_el, x_el) = if scatter { @@ -207,8 +207,14 @@ impl Series { let ln = sp.and_then(|p| p.child("a:ln")); let marker = ser.child("c:marker").and_then(|m| m.child("c:spPr")).and_then(|p| fill_colour(p, theme)); let color = sp.and_then(|p| fill_colour(p, theme)).or_else(|| ln.and_then(|l| fill_colour(l, theme))).or(marker); - let line_w = ln.and_then(|l| l.attr("w")).and_then(|v| measure(v, 12_700.0)).map_or(LINE_W, |w| w.clamp(0.0, 20.0)); + let no_fill = sp.and_then(|p| p.child("a:noFill")).is_some(); + let line_w = ln.and_then(|l| l.attr("w")).and_then(|v| measure(v, 12_700.0)).map(|w| w.clamp(0.0, 20.0)); let line = ln.is_none_or(|l| l.child("a:noFill").is_none()); + // `c:marker/c:symbol`: which symbol each point gets (`none` for no markers). Scatter + // series show markers unless the file says not; line series only when it says so. + let symbol = ser.child("c:marker").and_then(|m| m.child("c:symbol")).and_then(|s| s.attr("val")).map(str::to_string); + let markers = symbol.map(|s| s != "none").or_else(|| scatter.then_some(true)); + let smooth = ser.child("c:smooth").and_then(|s| s.attr("val")).is_some_and(truthy); let (values, fmt) = numbers(ser.child(if scatter { "c:yVal" } else { "c:val" }), cap); let (mut xs, x_fmt) = if scatter { numbers(ser.child("c:xVal"), cap) } else { (Vec::new(), None) }; if scatter && xs.is_empty() { @@ -223,7 +229,7 @@ impl Series { } } let labels = show_values(ser.child("c:dLbls")); - Series { name, idx, color, line_w, line, values, xs, points, fmt, x_fmt, labels, raw: Vec::new() } + Series { name, idx, color, line_w, line, no_fill, markers, smooth, values, xs, points, fmt, x_fmt, labels, raw: Vec::new() } } } @@ -290,7 +296,7 @@ fn pts(cache: &El, cap: usize) -> Vec> { } pub(super) fn axis(a: Option<&El>) -> Axis { - let Some(a) = a else { return Axis { deleted: true, ..Default::default() } }; + let Some(a) = a else { return Axis { deleted: true, labels: true, line: true, ..Default::default() } }; let scaling = a.child("c:scaling"); let num = |n: &str| scaling.and_then(|s| s.child(n)).and_then(|e| e.attr("val")).and_then(|v| v.trim().parse::().ok()).filter(|v| v.is_finite()); @@ -307,6 +313,8 @@ pub(super) fn axis(a: Option<&El>) -> Axis { .and_then(|f| f.attr("formatCode")) .filter(|f| f.len() <= MAX_FORMAT_CODE) .map(str::to_string), + title: a.child("c:title").and_then(title_text), + labels: a.child("c:tickLblPos").and_then(|p| p.attr("val")) != Some("none"), } } diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index 652ee79a8..09fe672d0 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -1,9 +1,9 @@ -use super::canvas::{Rect, fill, rect_segs, runs, seg, stroke, text, text_at, text_w, widest, wrap}; +use super::canvas::{Rect, clip_text, fill, rect_segs, runs, seg, stroke, text, text_angle, text_at, text_w, widest, wrap}; use super::format::format_value; use super::model::{DataLabel, Grouping, Kind, Series}; use super::parse::category_text; use super::polar::{draw_data_labels, label_of}; -use super::{AXIS, Chart, El, GAP, GRID, GraphicItem, LINE, MAX_LABEL, MAX_TICKS, PathSeg, Rgb, ShapeKind, TextAlign, fill_colour, measure}; +use super::{AXIS, Chart, El, GAP, GRID, GraphicItem, LINE, LINE_W, MAX_LABEL, MAX_TICKS, PathSeg, Rgb, ShapeKind, TextAlign, fill_colour, measure}; pub(super) fn label(s: &str) -> String { s.chars().take(MAX_LABEL).collect() @@ -151,21 +151,23 @@ struct Margins { } /// The margins the axis labels need around the plot in `area`. Category labels under a column -/// chart wrap to the band; labels that still don't fit show every k-th category. +/// chart wrap to the band; labels that still don't fit show every k-th category. Hidden tick +/// labels take no room; an axis title adds one line on its side. fn axis_margins(c: &Chart, ax: &Axes, area: Rect) -> Margins { let fs = c.text_size; let lh = fs * LINE; let scatter = c.kind == Kind::Scatter; let (cat_on, val_on) = (!c.cat.deleted, !c.val.deleted); + let (cat_labels, val_labels) = (cat_on && c.cat.labels, val_on && c.val.labels); let left = if c.horizontal { - if cat_on { widest(&c.cats, fs).min(area.w * 0.4) + GAP } else { 0.0 } - } else if val_on { + if cat_labels { widest(&c.cats, fs).min(area.w * 0.4) + GAP } else { 0.0 } + } else if val_labels { ax.vticks.iter().map(|(_, s)| text_w(s, fs)).fold(0.0, f32::max) + GAP } else { 0.0 - }; + } + title_left(c, cat_on, val_on, lh); let band_w = (area.w - left).max(1.0) / c.n as f32; - let wrapped: Vec> = if cat_on && !scatter { + let wrapped: Vec> = if cat_labels && !scatter { let width = if c.horizontal { left - GAP } else { band_w }; c.cats.iter().map(|s| wrap(s, width, fs)).collect() } else { @@ -174,17 +176,31 @@ fn axis_margins(c: &Chart, ax: &Axes, area: Rect) -> Margins { let widest_line = wrapped.iter().flatten().map(|s| text_w(s, fs)).fold(0.0, f32::max); let skip = ((widest_line / band_w).ceil() as usize).max(1); let label_lines = wrapped.iter().map(Vec::len).max().unwrap_or(1) as f32; - let bottom = if cat_on && !c.horizontal { + let bottom = (if cat_labels && !c.horizontal { if scatter { lh + GAP } else { label_lines * lh + GAP } - } else if c.horizontal && val_on { + } else if c.horizontal && val_labels { lh + GAP } else { 0.0 - }; - let top = if !c.horizontal && val_on { lh / 2.0 } else { 0.0 }; + }) + title_bottom(c, cat_on, val_on, lh); + let top = if !c.horizontal && val_labels { lh / 2.0 } else { 0.0 }; Margins { left, top, bottom, wrapped, skip } } +/// Room for the vertical axis title on the plot's left: one line when the axis that sits there +/// (the value axis for columns, the category axis for bars) has a title. +fn title_left(c: &Chart, cat_on: bool, val_on: bool, lh: f32) -> f32 { + let side = if c.horizontal { cat_on && c.cat.title.is_some() } else { val_on && c.val.title.is_some() }; + if side { lh } else { 0.0 } +} + +/// Room for the horizontal axis title under the plot: one line when the axis that sits there +/// (the category axis for columns, the value axis for bars) has a title. +fn title_bottom(c: &Chart, cat_on: bool, val_on: bool, lh: f32) -> f32 { + let side = if c.horizontal { val_on && c.val.title.is_some() } else { cat_on && c.cat.title.is_some() }; + if side { lh } else { 0.0 } +} + /// A bar, column, line, area or scatter chart in `area`: gridlines, series, axes, then labels. pub(super) fn cartesian(out: &mut Vec, c: &Chart, area: Rect) { if c.n == 0 { @@ -200,6 +216,9 @@ pub(super) fn cartesian(out: &mut Vec, c: &Chart, area: Rect) { if c.val.grid { draw_grid(out, &g, &ax.vticks); } + if c.cat.grid { + draw_cat_grid(out, &g, &ax.xticks, c.kind == Kind::Scatter); + } let mut labels = Vec::new(); match c.kind { Kind::Bar => bars(out, c, &g, &mut labels), @@ -210,12 +229,36 @@ pub(super) fn cartesian(out: &mut Vec, c: &Chart, area: Rect) { } draw_axes(out, c, &g); draw_data_labels(out, &labels, c.text_size, g.horiz && c.kind == Kind::Bar); - if !c.val.deleted { - draw_value_labels(out, c, &g, &ax.vticks, Rect { w: m.left, ..area }); + if !c.val.deleted && c.val.labels { + let room = title_left(c, !c.cat.deleted, true, c.text_size * LINE); + draw_value_labels(out, c, &g, &ax.vticks, Rect { x: area.x + room, w: m.left - room, ..area }); } - if !c.cat.deleted { + if !c.cat.deleted && c.cat.labels { draw_category_labels(out, c, &g, &ax.xticks, &m, area); } + draw_axis_titles(out, c, &g, area); +} + +/// The axis titles, one line: the title of the vertical axis (the value axis for columns, the +/// category axis for bars) is rotated 90° on the plot's left; the horizontal axis's title sits +/// under the plot. +fn draw_axis_titles(out: &mut Vec, c: &Chart, g: &Frame, area: Rect) { + let lh = c.text_size * LINE; + // The axis drawn along the plot's left (the value axis for columns, the category axis for + // bars) gets its title rotated there; the other axis's title sits under the plot. + let (left, bottom) = if c.horizontal { (&c.cat, &c.val) } else { (&c.val, &c.cat) }; + if !left.deleted + && let Some(t) = &left.title + { + let t = clip_text(t, g.plot.h, c.text_size); + text_angle(out, Rect { x: area.x, y: g.plot.y, w: lh, h: g.plot.h }, &t, c.text_size, TextAlign::Center, false, 90.0); + } + if !bottom.deleted + && let Some(t) = &bottom.title + { + let t = clip_text(t, g.plot.w, c.text_size); + text_angle(out, Rect { x: g.plot.x, y: area.bottom() - lh, w: g.plot.w, h: lh }, &t, c.text_size, TextAlign::Center, false, 0.0); + } } /// Major gridlines at the value ticks. @@ -228,6 +271,24 @@ fn draw_grid(out: &mut Vec, g: &Frame, ticks: &[(f64, String)]) { } } +/// Gridlines along the category axis: across the plot at each category's centre, at the x ticks +/// of a scatter chart. +fn draw_cat_grid(out: &mut Vec, g: &Frame, xticks: &[(f64, String)], scatter: bool) { + let plot = g.plot; + if scatter { + for (t, _) in xticks { + let p = g.scat_x(*t); + stroke(out, seg(p, plot.y, p, plot.bottom()), GRID, 0.75); + } + return; + } + for i in 0..g.n { + let p = g.band_start(i) + g.band() / 2.0; + let segs = if g.horiz { seg(plot.x, p, plot.right(), p) } else { seg(p, plot.y, p, plot.bottom()) }; + stroke(out, segs, GRID, 0.75); + } +} + /// The category axis line, the plot area's outline and the value axis line, as the file shows them. fn draw_axes(out: &mut Vec, c: &Chart, g: &Frame) { let plot = g.plot; @@ -361,7 +422,9 @@ fn bars(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, pts: impl Iterator, colour: Rgb) { + const MARKER: f32 = 6.0; + for (x, y) in pts { + let rect = [x - MARKER / 2.0, y - MARKER / 2.0, MARKER, MARKER]; + out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(colour), stroke: None, stroke_width: 0.0 }); + } +} + +/// A polyline through `pts`, a smooth curve (Catmull-Rom pieces) when `smooth` and there are at +/// least three points in a row; gaps (`None`) end a run. +fn curve(pts: impl Iterator>, smooth: bool) -> Vec { + if !smooth { + return runs(pts); + } + let pts: Vec> = pts.collect(); + let mut segs = Vec::new(); + let mut i = 0; + while i < pts.len() { + let Some(first) = pts[i] else { + i += 1; + continue; + }; + // Collect one run of points. + let mut run = vec![first]; + while let Some(p) = pts.get(i + 1).copied().flatten() { + run.push(p); + i += 1; + } + i += 1; + if run.len() < 3 { + segs.extend(runs(run.into_iter().map(Some))); + continue; + } + segs.push(PathSeg::Move(run[0].0, run[0].1)); + for k in 0..run.len() - 1 { + // Catmull-Rom: tangent at p1 from p0 to p2 (ends mirror their own tangent). + let p0 = run[k.max(1) - 1]; + let p1 = run[k]; + let p2 = run[k + 1]; + let p3 = run.get(k + 2).copied().unwrap_or(p2); + let c1 = (p1.0 + (p2.0 - p0.0) / 6.0, p1.1 + (p2.1 - p0.1) / 6.0); + let c2 = (p2.0 - (p3.0 - p1.0) / 6.0, p2.1 - (p3.1 - p1.1) / 6.0); + segs.push(PathSeg::Cubic(c1.0, c1.1, c2.0, c2.1, p2.0, p2.1)); + } + } + segs +} + fn areas(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec) { let mut base = vec![0.0f64; g.n]; for (j, s) in c.series.iter().enumerate().filter(|(_, s)| has_values(s)) { @@ -434,7 +551,7 @@ fn areas(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec) { const MARKER: f32 = 6.0; for (j, s) in c.series.iter().enumerate() { @@ -452,12 +569,13 @@ fn draw_scatter(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut V } } if s.line { - stroke(out, runs(pts.iter().copied()), c.series_colour(j), s.line_w); - continue; + stroke(out, curve(pts.iter().copied(), s.smooth), c.series_colour(j), s.line_w.unwrap_or(LINE_W)); } - for (x, y) in pts.iter().flatten() { - let rect = [x - MARKER / 2.0, y - MARKER / 2.0, MARKER, MARKER]; - out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(c.series_colour(j)), stroke: None, stroke_width: 0.0 }); + if s.markers != Some(false) { + for (x, y) in pts.iter().flatten() { + let rect = [x - MARKER / 2.0, y - MARKER / 2.0, MARKER, MARKER]; + out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(c.series_colour(j)), stroke: None, stroke_width: 0.0 }); + } } } } diff --git a/crates/docx/src/read/chart/polar.rs b/crates/docx/src/read/chart/polar.rs index 57ad10472..ec7768d5c 100644 --- a/crates/docx/src/read/chart/polar.rs +++ b/crates/docx/src/read/chart/polar.rs @@ -2,7 +2,7 @@ use super::canvas::{Rect, clip_text, fill, stroke, text, text_w, widest}; use super::format::format_value; use super::model::{DataLabel, Kind, Series}; use super::plot::{Axes, has_values}; -use super::{Chart, FRAC_PI_2, GAP, GRID, GraphicItem, LINE, PathSeg, Rgb, ShapeKind, TAU, TEXT, TextAlign}; +use super::{Chart, FRAC_PI_2, GAP, GRID, GraphicItem, LINE, LINE_W, PathSeg, Rgb, ShapeKind, TAU, TEXT, TextAlign}; pub(super) fn pie(out: &mut Vec, c: &Chart, area: Rect) { let Some(s) = c.series.first() else { return }; @@ -92,7 +92,7 @@ pub(super) fn radar(out: &mut Vec, c: &Chart, area: Rect) { if c.radar_fill { fill(out, segs.clone(), col); } - stroke(out, segs, col, s.line_w); + stroke(out, segs, col, s.line_w.unwrap_or(LINE_W)); for (i, p) in ring.iter().enumerate() { if c.radar_marks && s.values.get(i).copied().flatten().is_some() { let rect = [p.0 as f32 - MARKER / 2.0, p.1 as f32 - MARKER / 2.0, MARKER, MARKER]; @@ -171,7 +171,7 @@ pub(super) fn draw_data_labels(out: &mut Vec, labels: &[DataLabel], (Rect { x: l.x - w / 2.0, y: l.y - lh, w, h: lh }, TextAlign::Center) }; let color = if l.inside { Rgb::WHITE } else { TEXT }; - out.push(GraphicItem::Text { rect: rect.arr(), text: l.text.clone(), size: fs, color, bold: false, align, font: None }); + out.push(GraphicItem::Text { rect: rect.arr(), text: l.text.clone(), size: fs, color, bold: false, align, font: None, angle: 0.0 }); } } diff --git a/crates/docx/src/read/diagram.rs b/crates/docx/src/read/diagram.rs index 7f03e8b51..7b7bbeebf 100644 --- a/crates/docx/src/read/diagram.rs +++ b/crates/docx/src/read/diagram.rs @@ -463,7 +463,16 @@ fn text(sp: &El, xf: Xf, b: [f64; 4], theme: &[Rgb], filled: bool, fit: f32, out let mut y = y0 + (th - total) / 2.0; for l in lines { let lh = l.size * LINE; - out.push(GraphicItem::Text { rect: [x0, y, tw, lh], text: l.text, size: l.size, color: l.color, bold: l.bold, align: l.align, font: l.font }); + out.push(GraphicItem::Text { + rect: [x0, y, tw, lh], + text: l.text, + size: l.size, + color: l.color, + bold: l.bold, + align: l.align, + font: l.font, + angle: 0.0, + }); y += lh; } } diff --git a/crates/docx/src/write/embed.rs b/crates/docx/src/write/embed.rs index 9a8051e09..7673a6f26 100644 --- a/crates/docx/src/write/embed.rs +++ b/crates/docx/src/write/embed.rs @@ -884,10 +884,11 @@ mod tests { let spec = ChartSpec { kind: ChartType::Column, categories: vec!["a".into(), "b".into()], - series: (0..series).map(|i| ChartSeries { name: format!("S{i}"), values: vec![Some(1.0); 2] }).collect(), + series: (0..series).map(|i| ChartSeries { name: format!("S{i}"), values: vec![Some(1.0); 2], ..Default::default() }).collect(), title: None, legend: None, data_labels: false, + ..Default::default() }; let graphic = Graphic { kind: GraphicKind::Chart, w: 100.0, h: 100.0, chart: Some(Arc::new(spec)), ..Default::default() }; InlineObject::Graphic { w: 100.0, h: 100.0, alt: String::new(), float: Default::default(), graphic: Arc::new(graphic) } diff --git a/crates/flow/src/from_doc.rs b/crates/flow/src/from_doc.rs index 341ded449..18b287bb5 100644 --- a/crates/flow/src/from_doc.rs +++ b/crates/flow/src/from_doc.rs @@ -749,7 +749,7 @@ fn graphic_group( let inline = Inline::Shape { kind: *kind, w: rect[2] * sx, h: rect[3] * sy, float: None, blocks: Vec::new(), look, path: None }; Some(Member { x: rect[0] * sx, y: rect[1] * sy, inline }) } - GraphicItem::Text { rect, text, size, color, bold, align, font } if finite(rect) && !text.trim().is_empty() => { + GraphicItem::Text { rect, text, size, color, bold, align, font, .. } if finite(rect) && !text.trim().is_empty() => { let size = if size.is_finite() { size.clamp(1.0, 400.0) } else { 11.0 }; // One line, centred vertically in its place as the graphic draws it. let line = size * 1.2; diff --git a/crates/odf/src/text/chart.rs b/crates/odf/src/text/chart.rs index 9d073ecd2..2a79352a1 100644 --- a/crates/odf/src/text/chart.rs +++ b/crates/odf/src/text/chart.rs @@ -229,7 +229,7 @@ impl Reader { }; let name = s.label.as_deref().and_then(|a| cells_of(a).first().copied()).map(|at| label(self.cell(at))).unwrap_or_default(); let name = if name.is_empty() { format!("Series {}", i + 1) } else { name }; - ChartSeries { name, values } + ChartSeries { name, values, ..Default::default() } }) .collect(); // A scatter chart's x values: its first series' domain. @@ -248,7 +248,10 @@ impl Reader { _ => LegendPos::Right, }); let title = self.title.as_deref().map(str::trim).filter(|t| !t.is_empty()).map(str::to_string); - Some(ChartSpec { kind, categories, series, title, legend, data_labels }.sanitized()) + // ODF axis formatting is not read; the value axis keeps the look every chart had before + // axes were formattable (gridlines, no axis line), a round chart has none. + let val_axis = if kind.is_round() { Default::default() } else { craft_wordmodel::chart::value_axis() }; + Some(ChartSpec { kind, categories, series, title, legend, data_labels, val_axis, ..Default::default() }.sanitized()) } } diff --git a/crates/odf/src/text/tests_more/charts.rs b/crates/odf/src/text/tests_more/charts.rs index 9ac0b6b96..5aa892cf4 100644 --- a/crates/odf/src/text/tests_more/charts.rs +++ b/crates/odf/src/text/tests_more/charts.rs @@ -57,8 +57,8 @@ fn spec(chart: &str) -> Option { fn north_south() -> Vec { vec![ - ChartSeries { name: "North".into(), values: vec![Some(10.0), Some(14.0), Some(8.0), Some(16.0)] }, - ChartSeries { name: "South".into(), values: vec![Some(12.0), None, Some(11.0), Some(13.0)] }, + ChartSeries { name: "North".into(), values: vec![Some(10.0), Some(14.0), Some(8.0), Some(16.0)], ..Default::default() }, + ChartSeries { name: "South".into(), values: vec![Some(12.0), None, Some(11.0), Some(13.0)], ..Default::default() }, ] } @@ -78,6 +78,8 @@ fn a_column_chart_reads_its_data_title_and_legend() { title: Some("Sales by quarter".into()), legend: Some(LegendPos::Right), data_labels: false, + val_axis: craft_wordmodel::chart::value_axis(), + ..Default::default() } ); // The frame's size, in points. @@ -135,7 +137,7 @@ fn line_area_pie_doughnut_and_scatter_classes() { let s = spec(&chart_xml("chart:scatter", "", "", "", scatter)).unwrap(); assert_eq!(s.kind, ChartType::Scatter); assert_eq!(s.categories, vec!["10", "14", "8", "16"]); - assert_eq!(s.series, vec![ChartSeries { name: "South".into(), values: vec![Some(12.0), None, Some(11.0), Some(13.0)] }]); + assert_eq!(s.series, vec![ChartSeries { name: "South".into(), values: vec![Some(12.0), None, Some(11.0), Some(13.0)], ..Default::default() }]); } #[test] @@ -249,7 +251,15 @@ fn every_chart_type_is_saved_as_a_chart_object_and_reads_back() { let bytes = crate::text::export(&doc_with(spec.clone(), false)).unwrap(); let back = reread(&bytes); assert_eq!(back.len(), 1, "{kind:?}"); - assert_eq!(*back[0].spec, spec.clone().sanitized(), "{kind:?}"); + // ODF keeps no series or axis formatting here: only the data, the title and the legend + // come back; the value axis has the gridlines every chart had before axes were formattable. + let mut expected = spec.clone().sanitized(); + for s in &mut expected.series { + *s = ChartSeries { name: std::mem::take(&mut s.name), values: std::mem::take(&mut s.values), ..Default::default() }; + } + expected.cat_axis = Default::default(); + expected.val_axis = if kind.is_round() { Default::default() } else { craft_wordmodel::chart::value_axis() }; + assert_eq!(*back[0].spec, expected, "{kind:?}"); assert_eq!((back[0].w, back[0].h, back[0].alt.as_str()), (300.0, 180.0, "Sales chart"), "{kind:?}"); // The package lists the chart object. let z = crate::Package::open(&bytes, &crate::Limits::DEFAULT).unwrap(); diff --git a/crates/odf/src/text/tests_more/groups.rs b/crates/odf/src/text/tests_more/groups.rs index bf1b056a6..4fada68a9 100644 --- a/crates/odf/src/text/tests_more/groups.rs +++ b/crates/odf/src/text/tests_more/groups.rs @@ -130,6 +130,7 @@ fn a_diagram_is_saved_as_a_group_of_its_drawing() { bold: false, align: TextAlign::Center, font: None, + angle: 0.0, }, GraphicItem::Shape { rect: [90.0, 9.0, 18.0, 18.0], kind: ShapeKind::Arrow, fill: Some(blue), stroke: None, stroke_width: 0.0 }, ], diff --git a/crates/wordmodel/src/chart.rs b/crates/wordmodel/src/chart.rs index b0cb6ad60..4744d8b88 100644 --- a/crates/wordmodel/src/chart.rs +++ b/crates/wordmodel/src/chart.rs @@ -11,6 +11,8 @@ use serde::{Deserialize, Serialize}; +use crate::props::Rgb; + /// Most series in a chart. pub const MAX_SERIES: usize = 255; /// Most categories (points per series) in a chart. @@ -123,13 +125,107 @@ impl LegendPos { } } -/// One series: its name and a value per category (`None` = no value, a gap). +/// One series: its name, a value per category (`None` = no value, a gap) and how it is drawn +/// (Chart Design â–¸ Format Series): fill, line, markers, smooth lines, its own data labels and +/// number format. Unset fields follow the chart's defaults. #[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct ChartSeries { pub name: String, #[serde(default)] pub values: Vec>, + /// Fill colour; `None`: the chart's accent colour for the series. + #[serde(default)] + pub fill: Option, + /// "None" fill: the series draws no fill. + #[serde(default)] + pub no_fill: bool, + /// Line width in points; `None`: the chart's default. + #[serde(default)] + pub line_w: Option, + /// "None" line: the series draws no line. + #[serde(default)] + pub no_line: bool, + /// Markers on points; `None`: unset (scatter charts draw them; a saved scatter series then has no `c:marker`, so Word picks its own symbols). + #[serde(default)] + pub markers: Option, + /// Draw the line as a smooth curve. + #[serde(default)] + pub smooth: bool, + /// Data labels for this series; `None`: follow the chart's setting. + #[serde(default)] + pub labels: Option, + /// Number format of this series's labels and values; `None`: linked to the source. + #[serde(default)] + pub fmt: Option, +} + +/// One chart axis as Word formats it (Format Axis): title, scale bounds, tick-label number +/// format, gridlines, tick labels and the axis line. +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +#[serde(rename_all = "camelCase")] +pub struct ChartAxis { + /// `None`: no axis title; text cut to [`MAX_TEXT`] characters. + #[serde(default)] + pub title: Option, + /// Fixed lower bound; `None`: automatic. + #[serde(default)] + pub min: Option, + /// Fixed upper bound; `None`: automatic. + #[serde(default)] + pub max: Option, + /// Tick-label number format (`#,##0`, `0.00`, `0%`…); `None`: linked to the source data. + #[serde(default)] + pub fmt: Option, + /// Major gridlines drawn along this axis. + #[serde(default)] + pub gridlines: bool, + /// Tick labels; `false` hides the axis the way Word's Axis Labels â–¸ None does. + #[serde(default = "the_true")] + pub labels: bool, + /// The axis line. + #[serde(default = "the_true")] + pub line: bool, +} + +fn the_true() -> bool { + true +} + +impl Default for ChartAxis { + fn default() -> Self { + ChartAxis { title: None, min: None, max: None, fmt: None, gridlines: false, labels: true, line: true } + } +} + +/// The value axis as a new chart has it: gridlines, labels, no axis line. +pub fn value_axis() -> ChartAxis { + ChartAxis { gridlines: true, line: false, ..ChartAxis::default() } +} + +impl ChartAxis { + /// Make the axis safe to store: texts cleaned, bounds finite, `min` under `max` (an + /// impossible pair drops both), the format code cut to [`MAX_FMT`] characters. + pub fn sanitize(&mut self) { + self.title = self.title.as_deref().map(clean_text).filter(|t| !t.is_empty()); + self.min = self.min.filter(|v| v.is_finite()); + self.max = self.max.filter(|v| v.is_finite()); + if matches!((self.min, self.max), (Some(lo), Some(hi)) if lo >= hi) { + self.min = None; + self.max = None; + } + self.fmt = self.fmt.as_deref().map(clean_fmt).filter(|f| !f.is_empty()); + } +} + +/// Longest axis number format kept, characters. +pub const MAX_FMT: usize = 128; + +/// A number format code: control characters as spaces, ends trimmed, at most [`MAX_FMT`] +/// characters. +pub fn clean_fmt(s: &str) -> String { + let s: String = s.chars().take(MAX_FMT * 4).map(|c| if c.is_control() { ' ' } else { c }).collect(); + s.trim().chars().take(MAX_FMT).collect::().trim_end().to_string() } /// A chart the app can edit. @@ -151,6 +247,12 @@ pub struct ChartSpec { /// Show each point's value next to it. #[serde(default)] pub data_labels: bool, + /// The category axis (scatter charts: the x axis). + #[serde(default)] + pub cat_axis: ChartAxis, + /// The value axis (scatter charts: the y axis); gridlines on, no axis line, as a new chart has them. + #[serde(default = "value_axis")] + pub val_axis: ChartAxis, } impl ChartSpec { @@ -168,10 +270,23 @@ impl ChartSpec { ChartSpec { kind, categories: categories.into_iter().map(str::to_string).collect(), - series: series.into_iter().map(|(n, v)| ChartSeries { name: n.to_string(), values: v.into_iter().map(Some).collect() }).collect(), + series: series + .into_iter() + .map(|(n, v)| ChartSeries { + name: n.to_string(), + values: v.into_iter().map(Some).collect(), + // Scatter series are drawn as markers without a line. + no_line: kind == ChartType::Scatter, + ..Default::default() + }) + .collect(), title: None, legend: Some(LegendPos::Bottom), data_labels: false, + cat_axis: ChartAxis::default(), + // Pie and doughnut charts have no axes: their axes stay plain, so the chart reads back + // as the same model. + val_axis: if kind.is_round() { ChartAxis::default() } else { value_axis() }, } } @@ -203,8 +318,12 @@ impl ChartSpec { *v = v.filter(|x| x.is_finite()); } s.values.resize(n, None); + s.fmt = s.fmt.as_deref().map(clean_fmt).filter(|f| !f.is_empty()); + s.line_w = s.line_w.filter(|w| w.is_finite()).map(|w| w.clamp(0.0, 20.0)); } self.title = self.title.as_deref().map(clean_text).filter(|t| !t.is_empty()); + self.cat_axis.sanitize(); + self.val_axis.sanitize(); } /// The chart after `sanitize`. @@ -229,7 +348,11 @@ mod tests { let mut c = ChartSpec { categories: vec!["a".into(); MAX_POINTS + 10], series: (0..MAX_SERIES + 5) - .map(|i| ChartSeries { name: format!("{}\n{}", "x".repeat(400), i), values: vec![Some(f64::NAN), Some(f64::INFINITY), Some(1.0)] }) + .map(|i| ChartSeries { + name: format!("{}\n{}", "x".repeat(400), i), + values: vec![Some(f64::NAN), Some(f64::INFINITY), Some(1.0)], + ..Default::default() + }) .collect(), title: Some(" ".into()), ..Default::default() @@ -250,7 +373,7 @@ mod tests { fn short_categories_are_padded_to_the_longest_series() { let c = ChartSpec { categories: vec!["a".into()], - series: vec![ChartSeries { name: "s".into(), values: vec![Some(1.0), Some(2.0)] }], + series: vec![ChartSeries { name: "s".into(), values: vec![Some(1.0), Some(2.0)], ..Default::default() }], ..Default::default() } .sanitized(); @@ -258,4 +381,45 @@ mod tests { assert_eq!(ChartType::from_id("BARSTACKED"), Some(ChartType::BarStacked)); assert_eq!(LegendPos::from_id("top"), Some(LegendPos::Top)); } + + #[test] + fn axis_bounds_and_formats_are_cleaned() { + let mut a = ChartAxis { + title: Some(" Sales\n".into()), + min: Some(f64::NAN), + max: Some(50.0), + fmt: Some("x".repeat(MAX_FMT + 40)), + gridlines: true, + labels: false, + line: true, + }; + a.sanitize(); + assert_eq!(a.title.as_deref(), Some("Sales")); + assert_eq!(a.min, None); + assert_eq!(a.max, Some(50.0)); + assert_eq!(a.fmt.as_deref().map(|f| f.chars().count()), Some(MAX_FMT)); + + // min not under max drops the pair; a format of only spaces is no format. + let mut b = ChartAxis { min: Some(50.0), max: Some(50.0), fmt: Some(" ".into()), ..Default::default() }; + b.sanitize(); + assert_eq!((b.min, b.max), (None, None)); + assert_eq!(b.fmt, None); + + let mut spec = ChartSpec { + series: vec![ChartSeries { name: "s".into(), values: vec![Some(1.0)], ..Default::default() }], + categories: vec!["a".into()], + ..Default::default() + }; + spec.series[0].line_w = Some(f32::NAN); + spec.series[0].fmt = Some("0.00".into()); + spec.sanitize(); + assert_eq!(spec.series[0].line_w, None); + assert_eq!(spec.series[0].fmt.as_deref(), Some("0.00")); + let mut spec = ChartSpec { + series: vec![ChartSeries { name: "s".into(), values: vec![], line_w: Some(100.0), ..Default::default() }], + ..Default::default() + }; + spec.sanitize(); + assert_eq!(spec.series[0].line_w, Some(20.0), "a wild width clamps to 20 pt"); + } } diff --git a/crates/wordmodel/src/graphic.rs b/crates/wordmodel/src/graphic.rs index c77c0e5e7..f4a7bcf2e 100644 --- a/crates/wordmodel/src/graphic.rs +++ b/crates/wordmodel/src/graphic.rs @@ -115,7 +115,9 @@ pub enum GraphicItem { #[serde(default)] stroke_width: f32, }, - /// One line of text in `rect`, aligned horizontally by `align`, centred vertically. + /// One line of text in `rect`, aligned horizontally by `align`, centred vertically; `angle` + /// degrees clockwise turns the text about `rect`'s centre as it is drawn (chart axis titles + /// use 90° for the vertical axis). Text { rect: [f32; 4], text: String, @@ -127,6 +129,8 @@ pub enum GraphicItem { align: TextAlign, #[serde(default)] font: Option, + #[serde(default)] + angle: f32, }, /// A picture (`Document::media` key) stretched into `rect`. Image { rect: [f32; 4], media: String }, From 12656b3d0fad48bb958e42c50a07a0959966fb27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Legrand?= Date: Sat, 14 Nov 2026 17:20:40 +0100 Subject: [PATCH 018/349] docs(dxf): describe configurable tag limit --- crates/dxf/src/lib.rs | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/crates/dxf/src/lib.rs b/crates/dxf/src/lib.rs index 4cf3e46e9..040fe3888 100644 --- a/crates/dxf/src/lib.rs +++ b/crates/dxf/src/lib.rs @@ -195,8 +195,9 @@ pub use codepage::decode_code_page; /// # Errors /// /// Returns an error for empty input, an invalid group code, an incomplete group-code/value pair, -/// truncated binary data, or more than [`MAX_TAGS`] group codes. For ASCII input, invalid numeric -/// text becomes `0.0` for real values or `0` for integer values, and an EOF tag is not required. +/// truncated binary data, or more group codes than the limit returned by [`max_tags()`], which is +/// [`MAX_TAGS`] by default. For ASCII input, invalid numeric text becomes `0.0` for real values or +/// `0` for integer values, and an EOF tag is not required. pub fn parse(bytes: &[u8]) -> Result> { parse_with_limit(bytes, max_tags()) } From d2b6416db9b8358e337ed7472ec52c262593a27c Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 11:32:34 -0500 Subject: [PATCH 019/349] craft-xlsx: binary styles: legacy number formats, automatic font colours, tinted fills A broader Excel probe found three differences from the styles.xml Excel writes for the same workbook: - A number format with a newer locale tag ([$-ja-JP-x-gannen]) is only in alternate content: the newer spelling in a block for later versions, and the one .xlsx keeps as formatCode in a block listing version 12 onwards. The styles part now reads the alternate content meant for Excel 2007 (version 12), so the format is no longer lost. - A font whose colour is automatic has no in .xlsx. - A pattern fill whose pattern colour has a tint states the system background (bgColor indexed 65), as Excel's .xlsx does for any pattern. --- crates/xlsx/README.md | 3 ++- crates/xlsx/src/xlsb.rs | 29 ++++++++++++++++++++++------- crates/xlsx/src/xlsb/styles.rs | 12 +++++++++--- crates/xlsx/tests/xlsb.rs | 21 +++++++++++++++++---- 4 files changed, 50 insertions(+), 15 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index b2b581112..81941fac1 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -86,7 +86,8 @@ they were. A binary workbook is not written. A binary workbook gives the same `Workbook`, strings, rows and merged cells, and the same `Styles`: number formats, fonts, fills, borders, cell and cell style formats, cell styles, differential formats and the indexed colours, as Excel writes them in `styles.xml` (default fill -colours and empty settings left out, a cell style format's `apply*="0"`). Custom table styles and +colours and empty settings left out, a cell style format's `apply*="0"`, a number format with a +newer locale tag in its Excel 2007 spelling, as `formatCode` has it). Custom table styles and recent colours are not read; a damaged styles part is a warning and no styles. Its cell formulas are decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with `FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 50da6185c..043b0743b 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -175,12 +175,16 @@ struct Records<'a, 'l> { bytes: Bytes<'a>, limits: &'l Limits, budget: &'l Budget, - blocks: Vec, + /// Each open block's end record, and whether its records are read. + blocks: Vec<(u16, bool)>, + /// Read the alternate content meant for Excel 2007 (version 12), as an `.xlsx` reader sees + /// the main attribute where Excel keeps a newer spelling in an extension. + excel_2007: bool, } impl<'a, 'l> Records<'a, 'l> { fn new(bytes: &'a [u8], limits: &'l Limits, budget: &'l Budget) -> Self { - Self { bytes: Bytes::new(bytes), limits, budget, blocks: vec![] } + Self { bytes: Bytes::new(bytes), limits, budget, blocks: vec![], excel_2007: false } } fn next(&mut self, warnings: &mut Warnings) -> Result, Error> { @@ -209,6 +213,7 @@ impl<'a, 'l> Records<'a, 'l> { // BrtFRTBegin, BrtACBegin. 35 | 37 => { let mut b = Bytes::new(payload); + let mut read = false; if id == 35 { b.take(4)?; } else { @@ -216,22 +221,32 @@ impl<'a, 'l> Records<'a, 'l> { if count == 0 { return Err(invalid("empty alternate-content version list")); } - b.take(usize::from(count) * 4)?; + // ACProductVersion: fileVersion, then fileProduct (15 bits) and + // fileExtension (the version and later). + for _ in 0..count { + let (version, product) = (b.u16()?, b.u16()?); + let later = product & 0x8000 != 0; + read |= self.excel_2007 && product & 0x7FFF == 0 && (version == 12 || later && version <= 12); + } } b.finish()?; if self.blocks.len() >= 64 { return Err(invalid("extension blocks nested too deeply")); } - self.blocks.push(id + 1); - warnings.warn("unsupported XLSB future-record and alternate-content blocks were skipped"); + // Inside a skipped block, everything is skipped. + let read = read && self.blocks.iter().all(|(_, r)| *r); + self.blocks.push((id + 1, read)); + if !read { + warnings.warn("unsupported XLSB future-record and alternate-content blocks were skipped"); + } } // BrtFRTEnd, BrtACEnd. 36 | 38 => { - if self.blocks.pop() != Some(id) || !payload.is_empty() { + if self.blocks.pop().map(|(end, _)| end) != Some(id) || !payload.is_empty() { return Err(invalid("mismatched extension block end")); } } - _ if !self.blocks.is_empty() => {} + _ if self.blocks.iter().any(|(_, read)| !read) => {} _ => return Ok(Some((id, payload))), } } diff --git a/crates/xlsx/src/xlsb/styles.rs b/crates/xlsx/src/xlsb/styles.rs index 094620a07..50673ef28 100644 --- a/crates/xlsx/src/xlsb/styles.rs +++ b/crates/xlsx/src/xlsb/styles.rs @@ -151,10 +151,11 @@ fn font(b: &mut Bytes<'_>) -> Result { extend: on(0x80), underline: (uls != 0).then(|| underline(u32::from(uls))), vert_align: (sss != 0).then(|| script(u32::from(sss))), - color, family: (family != 0).then_some(u32::from(family)), charset: (charset != 0).then_some(u32::from(charset)), scheme: scheme(u32::from(font_scheme)).filter(|s| *s != FontScheme::None), + // An automatic colour is a font with no `` in `.xlsx`. + color: color.filter(|c| c.source != ColorSource::Auto), }) } @@ -164,7 +165,8 @@ fn gradient(b: &mut Bytes<'_>, path: bool) -> Result { } /// `BrtFill`. Excel's `.xlsx` leaves out the default colours: system foreground (indexed 64) as -/// the pattern colour and system background (indexed 65) as the background. +/// the pattern colour and system background (indexed 65) as the background, unless the pattern +/// colour has a tint (as the built-in "20% - Accent1" styles do), when it states the background. fn fill(b: &mut Bytes<'_>) -> Result { let fls = b.u32()?; let fg = color(b)?; @@ -183,7 +185,8 @@ fn fill(b: &mut Bytes<'_>) -> Result { return Ok(Fill::Gradient(g)); } let system = |c: Color, i: u32| c.source == ColorSource::Indexed(i) && c.tint == 0.0; - Ok(Fill::Pattern(PatternFill { pattern: Some(pattern(fls)?), fg: fg.filter(|c| !system(*c, 64)), bg: bg.filter(|c| !system(*c, 65)) })) + let tinted = fg.is_some_and(|c| c.tint != 0.0); + Ok(Fill::Pattern(PatternFill { pattern: Some(pattern(fls)?), fg: fg.filter(|c| !system(*c, 64)), bg: bg.filter(|c| tinted || !system(*c, 65)) })) } /// `BrtBorder`: the five edges a cell border has, each stated (`` when it has no line). @@ -393,6 +396,9 @@ fn dxf(b: &mut Bytes<'_>) -> Result { /// The styles part: `BrtBeginStyleSheet` to `BrtEndStyleSheet`. pub(crate) fn styles(bytes: &[u8], limits: &Limits, budget: &Budget, warnings: &mut Warnings) -> Result { let mut records = Records::new(bytes, limits, budget); + // Excel keeps a number format with a newer locale tag in two alternate-content blocks: the + // newer spelling for itself, and for Excel 2007 the one `.xlsx` has as `formatCode`. + records.excel_2007 = true; records.first(278, warnings)?; let mut s = Styles::default(); // Inside BrtBeginCellStyleXFs (true) or BrtBeginCellXFs (false). diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index bc1a7f6bd..85643b0ee 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1014,6 +1014,8 @@ fn styles_bin() -> Vec { // character set 0 and scheme "none" are not written in `.xlsx`. let fancy = font(290, 0x0A, 700, 1, 0x22, 0, 2, &rgb(0, 128, 255), 0, "Wingdings"); let heading = font(220, 0, 400, 0, 0, 2, 0, &theme(4, 13106), 1, "Aptos Display"); + // An automatic colour: no `` in `.xlsx`. + let auto = font(220, 0x02, 400, 0, 0, 2, 0, &color(0, 64, 0, [0, 0, 0, 255]), 2, "Aptos Narrow"); let gradient = [ &0x28u32.to_le_bytes()[..], &indexed(64), @@ -1030,20 +1032,31 @@ fn styles_bin() -> Vec { let none = edge(0, &color(0, 0, 0, [0, 0, 0, 0])); let parts: Vec> = vec![ record(278, &[]), - begin(615, 1), + begin(615, 2), record(44, &[&164u16.to_le_bytes()[..], &wide(r"yyyy\-mm\-dd")].concat()), + // A format in two alternate-content blocks: the newer spelling for version 13 and later + // (skipped), and the one for versions 12 and 13, which `.xlsx` has as `formatCode`. + record(37, &[1, 0, 13, 0, 0, 0x80]), + record(44, &[&165u16.to_le_bytes()[..], &wide("[$-ja-JP-x-gannen]ge")].concat()), + record(38, &[]), + record(37, &[2, 0, 12, 0, 0, 0, 13, 0, 0, 0]), + record(44, &[&165u16.to_le_bytes()[..], &wide("[$]ge")].concat()), + record(38, &[]), record(616, &[]), - begin(611, 3), + begin(611, 4), normal, fancy, heading, + auto, record(612, &[]), - begin(603, 5), + begin(603, 6), pattern_fill(0, &indexed(64), &indexed(65)), pattern_fill(17, &indexed(64), &indexed(65)), pattern_fill(1, &rgb(255, 255, 0), &indexed(64)), pattern_fill(9, &theme(5, -8191), &indexed(65)), record(45, &gradient), + // A tinted pattern colour: `.xlsx` states the system background, as for darkGrid above. + pattern_fill(1, &theme(4, 26213), &indexed(65)), record(604, &[]), begin(613, 2), record(46, &[&[0][..], &none, &none, &none, &none, &none].concat()), @@ -1109,7 +1122,7 @@ fn styles_bin() -> Vec { parts.concat() } -const STYLES_XML: &str = r#""#; +const STYLES_XML: &str = r#""#; /// The same styles from a SpreadsheetML package. fn xml_styles(xml: &str) -> Styles { From 99223e1972bbb1682cfa57e7f6ab5d56c4411ca6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Legrand?= Date: Sat, 31 Oct 2026 14:17:41 +0100 Subject: [PATCH 020/349] refactor(i18n): satisfy Clippy pedantic lints --- crates/i18n/src/collate.rs | 2 ++ crates/i18n/src/fold.rs | 14 +++++++++++--- crates/i18n/src/format.rs | 13 +++++++++---- crates/i18n/src/lib.rs | 17 ++++++++++++----- crates/i18n/src/number.rs | 11 +++++++++++ crates/i18n/src/region.rs | 4 ++++ crates/i18n/src/scripts.rs | 28 +++++++++++++++++++++++----- crates/i18n/src/size.rs | 8 ++++++++ 8 files changed, 80 insertions(+), 17 deletions(-) diff --git a/crates/i18n/src/collate.rs b/crates/i18n/src/collate.rs index 06d417897..629b3bf75 100644 --- a/crates/i18n/src/collate.rs +++ b/crates/i18n/src/collate.rs @@ -30,6 +30,7 @@ impl Collator { /// Sorting for `locale`, a language code such as `sv`, `pt-br` or `zh-hant` (any case, `-` /// or `_`, glibc forms such as `sv_SE.UTF-8` and `sr_RS@latin`). A BCP 47 collation type /// picks another order where there is one: `zh-hant-u-co-pinyin`, `zh-hans-u-co-stroke`. + #[must_use] pub fn new(locale: &str) -> Collator { let mut prefs: CollatorPreferences = Locale::try_from_str(&bcp47(locale)).unwrap_or(Locale::UNKNOWN).into(); prefs.numeric_ordering = Some(CollationNumericOrdering::True); @@ -46,6 +47,7 @@ impl Collator { /// the collation counts as equal (`Layer 2` and `Layer 02`) is in code point order, so a sort /// doesn't depend on the input order. Without collation data (never with the embedded data) /// this is code point order. + #[must_use] pub fn compare(&self, a: &str, b: &str) -> Ordering { match &self.0 { Some(c) => c.as_borrowed().compare(a, b).then_with(|| a.cmp(b)), diff --git a/crates/i18n/src/fold.rs b/crates/i18n/src/fold.rs index 959c6425a..dd77b6dfd 100644 --- a/crates/i18n/src/fold.rs +++ b/crates/i18n/src/fold.rs @@ -15,7 +15,7 @@ //! `IRMAK` and `ırmak`. Plain `str::to_lowercase` follows no locale and turns `İ` into `i` plus a //! combining dot, which nothing typed would match. //! -//! The Turkish i handling and sigma folding come from PdfCraft's `fold_case` (snipeTR, +//! The Turkish i handling and sigma folding come from `PdfCraft`'s `fold_case` (snipeTR, //! nevicia2010-hub). use std::ops::Range; @@ -34,6 +34,7 @@ pub struct Folder { impl Folder { /// Case- and accent-insensitive folding for `locale`, a language code such as `tr`, `pt-br` /// or `zh-hant` (any case, `-` or `_`). + #[must_use] pub fn new(locale: &str) -> Folder { let language = locale.split(['-', '_', '.', '@']).next().unwrap_or_default(); Folder { turkic: language.eq_ignore_ascii_case("tr") || language.eq_ignore_ascii_case("az"), accents: false } @@ -41,11 +42,13 @@ impl Folder { /// Accents count: `é` no longer matches `e`, and a match can't end on a letter whose accent it /// leaves out. + #[must_use] pub fn keep_accents(self) -> Folder { Folder { accents: true, ..self } } /// `s` folded, with the map back to `s`. + #[must_use] pub fn fold(&self, s: &str) -> Folded { let nfkd = DecomposingNormalizerBorrowed::new_nfkd(); let extend = CodePointSetData::new::(); @@ -75,17 +78,19 @@ impl Folder { } /// `s` folded, without the map: a key to compare or store. + #[must_use] pub fn key(&self, s: &str) -> String { self.fold(s).text } /// Whether `haystack` contains `needle`, both folded. + #[must_use] pub fn contains(&self, haystack: &str, needle: &str) -> bool { self.fold(haystack).find(&self.fold(needle)).is_some() } /// One cluster, already in NFKD. - fn fold_cluster(&self, cluster: &str, out: &mut String) { + fn fold_cluster(self, cluster: &str, out: &mut String) { let mut chars = cluster.chars().peekable(); while let Some(c) = chars.next() { match c { @@ -219,6 +224,7 @@ pub struct Folded { impl Folded { /// The folded text. + #[must_use] pub fn as_str(&self) -> &str { &self.text } @@ -226,6 +232,7 @@ impl Folded { /// The source byte range that folded bytes `range` came from, widened to whole source /// characters with their accents: `ss` in the folding of `Straße` maps back to `ß`, `e` in /// that of `é` to the whole `é`. An empty range maps to an empty one. + #[must_use] pub fn source_range(&self, range: Range) -> Range { // The last cluster starting at or before `at` is the one holding it: clusters that fold to // nothing share their offset with the next one. @@ -241,6 +248,7 @@ impl Folded { /// The first match of `needle` (folded the same way), as a byte range of the source text. /// An empty needle matches at the start. + #[must_use] pub fn find(&self, needle: &Folded) -> Option> { self.matches(needle).next() } @@ -363,10 +371,10 @@ mod tests { #[test] fn matches_map_back_to_the_source() { - let f = Folder::new("en"); fn find<'a>(f: Folder, haystack: &'a str, needle: &str) -> Option<&'a str> { f.fold(haystack).find(&f.fold(needle)).map(|r| &haystack[r]) } + let f = Folder::new("en"); let find = |haystack, needle| find(f, haystack, needle); assert_eq!(find("Große Straße", "strasse"), Some("Straße")); assert_eq!(find("Große Straße", "SS"), Some("ß")); diff --git a/crates/i18n/src/format.rs b/crates/i18n/src/format.rs index 14eb8c102..badfbdfca 100644 --- a/crates/i18n/src/format.rs +++ b/crates/i18n/src/format.rs @@ -4,7 +4,7 @@ use std::fmt; use fixed_decimal::{Decimal, Sign}; -use icu_decimal::{DecimalFormatter, parts}; +use icu_decimal::{DecimalFormatter, options::DecimalFormatterOptions, parts}; use icu_locale_core::Locale; use icu_locale_core::extensions::unicode::{key, value}; use writeable::{Part, PartsWrite, Writeable}; @@ -46,7 +46,8 @@ impl Format { if digits == Digits::Latin { locale.extensions.unicode.keywords.set(key!("nu"), value!("latn")); } - let decimal = data::provider().and_then(|p| DecimalFormatter::try_new_with_buffer_provider(p, (&locale).into(), Default::default()).ok()); + let decimal = data::provider() + .and_then(|p| DecimalFormatter::try_new_with_buffer_provider(p, (&locale).into(), DecimalFormatterOptions::default()).ok()); let mut format = Format { decimal, group: None, point: None, percent: ("", "%"), marks: Marks::default() }; // The locale's own separators and digits, read from a number that shows them all. let probe = format.parts(&Decimal::try_from_str("-1234567.5").unwrap_or_default()); @@ -81,6 +82,7 @@ impl Format { } /// The format for a locale tag (`de-CH`, `ar-EG`), with the locale's own digits. + #[must_use] pub fn from_tag(tag: &str) -> Format { Format::new(&Region::from_tag(tag), Digits::Locale) } @@ -92,6 +94,7 @@ impl Format { /// `value` rounded to `decimals` digits after the decimal separator; infinities and NaN are /// `∞`, `-∞` and `NaN`. + #[must_use] pub fn number(&self, value: f64, decimals: usize) -> String { match to_decimal(value, decimals) { Some(d) => self.write(&d), @@ -101,6 +104,7 @@ impl Format { /// [`Self::number`] without grouping separators, for values such as pixel sizes and years: /// `1920`, `١٩٢٠`, `1234,5`. + #[must_use] pub fn number_ungrouped(&self, value: f64, decimals: usize) -> String { match to_decimal(value, decimals) { Some(d) => { @@ -113,6 +117,7 @@ impl Format { /// `ratio` as a percentage with `decimals` digits after the decimal separator: `0.5` is /// `50%`, `50 %` (French, German), `%50` (Turkish), `٥٠٪؜` (Egyptian Arabic). + #[must_use] pub fn percent(&self, ratio: f64, decimals: usize) -> String { let Some(d) = to_decimal(ratio * 100.0, decimals) else { return format!("{}{}{}", self.percent.0, non_finite(ratio), self.percent.1); @@ -212,7 +217,7 @@ impl PartsWrite for Sink<'_> { _ => return result, }; if slot.is_empty() { - *slot = written.to_owned(); + written.clone_into(slot); } } result @@ -370,7 +375,7 @@ mod tests { for (tag, want) in [("en", "50%"), ("de", "50\u{a0}%"), ("fr", "12,5\u{a0}%"), ("tr", "%50"), ("ar-EG", "٥٠٪\u{61c}"), ("fa", "ÛµÛ°Ùª"), ("hi", "50%")] { - let decimals = if tag == "fr" { 1 } else { 0 }; + let decimals = usize::from(tag == "fr"); let ratio = if tag == "fr" { 0.125 } else { 0.5 }; assert_eq!(Format::from_tag(tag).percent(ratio, decimals), want, "{tag}"); } diff --git a/crates/i18n/src/lib.rs b/crates/i18n/src/lib.rs index 53bbffe9e..ce473d84f 100644 --- a/crates/i18n/src/lib.rs +++ b/crates/i18n/src/lib.rs @@ -113,7 +113,9 @@ impl Locale { rows.entry(e.context).or_default().insert(e.source, e.translation); } } - problems.iter().for_each(|p| log::warn!("translation catalog: {p}; row skipped")); + for p in &problems { + log::warn!("translation catalog: {p}; row skipped"); + } Parsed { rows, problems } }) } @@ -156,6 +158,7 @@ impl I18n { /// to left, say). Locales that can't be used are skipped and come back as problems for the app /// to log. A locale's bad rows are logged (`log::warn!`) when it is first looked up in, and /// [`I18n::check_all`] lists them all. + #[must_use] pub fn new(embedded: &'static Embedded, offered: &[&str]) -> (I18n, Vec) { let mut problems = Vec::new(); let mut locales = vec![bare("en"), bare("pseudo")]; @@ -417,6 +420,7 @@ impl I18n { /// value that already is one isolate keeps it; pass numbers, paths and codes through [`ltr`]. /// Other text gets no marks, and a value's own isolate is taken off. Unknown placeholders stay as written, /// and inserted values are never read as templates, so a file name containing `{n}` stays intact. +#[must_use] pub fn fmt(template: &str, args: &[(&str, &str)]) -> String { fill(template, args, true) } @@ -424,6 +428,7 @@ pub fn fmt(template: &str, args: &[(&str, &str)]) -> String { /// [`fmt`] without isolates, for text that goes where the marks would get in the way: file /// names, logs, terminals, text compared or parsed later. Every isolate mark is taken off, in /// the template and in the values. +#[must_use] pub fn fmt_plain(template: &str, args: &[(&str, &str)]) -> String { strip_isolates(&fill(template, args, false)) } @@ -444,6 +449,7 @@ const ALM: char = '\u{061C}'; /// `value` as a first-strong isolate (FSI…PDI): it takes the direction of its first strong /// letter and can't reorder the text around it. What [`fmt`] does to each value in text with a /// right-to-left letter. +#[must_use] pub fn isolate(value: &str) -> String { wrap(FSI, value) } @@ -452,12 +458,14 @@ pub fn isolate(value: &str) -> String { /// codes, which read left to right in every language. In an RTL first-strong isolate, the /// segments of `/home/مستخدم/file.txt` would run right to left. [`fmt`] takes the isolate off /// again in text with no right-to-left letter. +#[must_use] pub fn ltr(value: &str) -> String { wrap(LRI, value) } /// `text` without isolate marks (LRI, RLI, FSI, PDI): a [`fmt`] or [`I18n::trn`] result made fit /// for a file name, a log or a comparison. +#[must_use] pub fn strip_isolates(text: &str) -> String { text.chars().filter(|c| !matches!(*c, LRI | RLI | FSI | PDI)).collect() } @@ -483,14 +491,13 @@ fn wrap(initiator: char, value: &str) -> String { PDF if open.last() == Some(&false) => { open.pop(); } - PDF => continue, PDI if isolates > 0 => { while open.pop() == Some(false) { out.push(PDF); } isolates -= 1; } - PDI => continue, + PDF | PDI => continue, _ => {} } out.push(c); @@ -713,11 +720,11 @@ fn plural_rules(code: &str) -> Option<(PluralRules, Vec)> { categories.push(c); } } - categories.sort_by_key(rank); + categories.sort_by_key(|c| rank(*c)); Some((rules, categories)) } -fn rank(c: &PluralCategory) -> u8 { +fn rank(c: PluralCategory) -> u8 { match c { PluralCategory::Zero => 0, PluralCategory::One => 1, diff --git a/crates/i18n/src/number.rs b/crates/i18n/src/number.rs index 1120fbe88..211d9dfe0 100644 --- a/crates/i18n/src/number.rs +++ b/crates/i18n/src/number.rs @@ -80,6 +80,12 @@ impl Format { /// /// Percent signs, units and the space before a unit (`50 %`, `12 px`) are not read; strip them /// first. Anything else is an error rather than a guess. + /// + /// # Errors + /// + /// Returns `NumberError::Empty` for an empty input or one reduced to spaces and a sign, + /// `Unexpected` for an invalid character, `MixedDigits` for mixed digit sets, `Separator` + /// for misplaced marks, and `TooLarge` when the parsed value is not finite. pub fn parse(&self, text: &str) -> Result { let marks = self.marks; let text: String = text.chars().filter(|c| !is_bidi_mark(*c)).collect(); @@ -129,6 +135,11 @@ impl Format { /// The number in `text` as `locale` (a language tag, `de-CH`, `ar_EG.UTF-8`) writes it: /// [`Format::parse`] for [`Format::from_tag`]. Build the [`Format`] once to read many numbers. A /// locale CLDR doesn't know reads as CLDR's root does (`1,234.5`). +/// +/// # Errors +/// +/// Returns the same `NumberError` as [`Format::parse`] for invalid digits, characters, or +/// separators, or when the value is not finite. pub fn parse_number(text: &str, locale: &str) -> Result { Format::from_tag(locale).parse(text) } diff --git a/crates/i18n/src/region.rs b/crates/i18n/src/region.rs index fcdffe8af..205444c25 100644 --- a/crates/i18n/src/region.rs +++ b/crates/i18n/src/region.rs @@ -73,6 +73,7 @@ impl Region { /// `nu` stays in the number and time locales (`ar-EG-u-nu-latn`). `C` and `POSIX` are the C /// locale: English, A4, metric, a `.` decimal and no grouping. An empty or unreadable tag is /// `en-US`; a bare `en` is the United States, any other bare language has no territory. + #[must_use] pub fn from_tag(tag: &str) -> Region { match Tag::parse(tag) { Some(tag) => Region::from_parts(&tag), @@ -85,6 +86,7 @@ impl Region { /// The region for an app's saved region setting: `""` or `auto` (any case) is /// [`Region::system`], anything else a locale tag for [`Region::from_tag`]. + #[must_use] pub fn from_setting(setting: &str) -> Region { let setting = setting.trim(); if setting.is_empty() || setting.eq_ignore_ascii_case("auto") { Region::system() } else { Region::from_tag(setting) } @@ -99,6 +101,7 @@ impl Region { /// - Linux and the BSDs: `LC_ALL`, else each of `LC_NUMERIC`, `LC_TIME`, `LC_MEASUREMENT` and /// `LC_PAPER` on its own, else `LANG`. /// - The web and Android: the preferred language, the only locale they expose. + #[must_use] pub fn system() -> Region { static SYSTEM: OnceLock = OnceLock::new(); SYSTEM.get_or_init(read_system).clone() @@ -298,6 +301,7 @@ fn from_apple(identifier: &str, metric: bool, decimal: &str, grouping: &str, hou /// A grouping separator the system sets: none at all when empty (Windows' `sThousand` the user /// cleared), else one character. #[cfg(any(test, windows, target_vendor = "apple"))] +#[expect(clippy::option_option, reason = "The public setting distinguishes following the locale, no grouping, and a custom separator")] fn grouping(s: &str) -> Option> { if s.is_empty() { Some(None) } else { single_char(s).map(Some) } } diff --git a/crates/i18n/src/scripts.rs b/crates/i18n/src/scripts.rs index 1ae0f29bc..e16342e26 100644 --- a/crates/i18n/src/scripts.rs +++ b/crates/i18n/src/scripts.rs @@ -39,6 +39,7 @@ pub enum Script { impl Script { /// The ISO 15924 code, `Latn`. + #[must_use] pub fn code(self) -> &'static str { match self { Script::Arab => "Arab", @@ -75,6 +76,7 @@ impl Script { } /// Whether text in this script runs right to left. + #[must_use] pub fn rtl(self) -> bool { matches!(self, Script::Arab | Script::Hebr | Script::Syrc | Script::Thaa) } @@ -112,8 +114,12 @@ pub enum Han { /// where it is the language's own script. A language not in the table is taken to be written in /// Latin. // ponytail: the languages a Craft app ships or could plausibly ship; add a row with the locale. +#[must_use] pub fn scripts(tag: &str) -> &'static [Script] { - use Script::*; + use Script::{ + Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mymr, Orya, Sinh, + Syrc, Taml, Telu, Thaa, Thai, Tibt, + }; let tag = Subtags::parse(tag); if let Some(s) = tag.script.as_deref().and_then(subtag_scripts) { return s; @@ -154,6 +160,7 @@ pub fn scripts(tag: &str) -> &'static [Script] { } /// The direction of a language tag's text: right to left when its main script is. +#[must_use] pub fn direction(tag: &str) -> Direction { match scripts(tag).first() { Some(s) if s.rtl() => Direction::Rtl, @@ -165,6 +172,7 @@ pub fn direction(tag: &str) -> Direction { /// P3): the contents of isolates (LRI, RLI or FSI up to the matching PDI) are skipped, and the /// search stops at the first paragraph separator. `None` when the paragraph has no strong /// character; P3 then reads it as left to right, and an app may use the interface direction. +#[must_use] pub fn base_direction(text: &str) -> Option { match unicode_bidi::get_base_direction(text) { unicode_bidi::Direction::Ltr => Some(Direction::Ltr), @@ -175,9 +183,10 @@ pub fn base_direction(text: &str) -> Option { /// The forms a language tag's Han characters take: `zh-CN`, `zh-SG`, `zh-Hans` and plain `zh` → /// Simplified; `zh-TW`, `zh-Hant` and the other regions CLDR writes in Traditional characters -/// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → HongKong; `ja` → +/// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → `HongKong`; `ja` → /// Japanese; `ko` → Korean. `None` for a language not written with Han, which leaves the choice /// to the font stack. +#[must_use] pub fn han(tag: &str) -> Option { let tag = Subtags::parse(tag); let hong_kong = matches!(tag.region.as_deref(), Some("hk" | "mo")); @@ -202,8 +211,14 @@ pub fn han(tag: &str) -> Option { // ponytail: mn-CN → Mong is left out until vertical Mongolian layout is supported. pub(crate) fn region_script(language: &str, region: &str) -> Option<&'static str> { Some(match (language, region) { - ("az", "iq" | "ir") | ("ha", "cm" | "sd") | ("kk", "af" | "cn" | "ir" | "mn") | ("ku", "iq" | "ir" | "lb") => "arab", - ("ky", "cn") | ("ms", "cc") | ("pa", "pk") | ("tg", "pk") | ("uz", "af") => "arab", + ("az", "iq" | "ir") + | ("ha", "cm" | "sd") + | ("kk", "af" | "cn" | "ir" | "mn") + | ("ku", "iq" | "ir" | "lb") + | ("ky", "cn") + | ("ms", "cc") + | ("pa" | "tg", "pk") + | ("uz", "af") => "arab", ("az", "ru") | ("ku", "am" | "az" | "ge" | "tm") | ("ug", "kz" | "mn") | ("uz", "cn") => "cyrl", ("ky", "tr") | ("sr", "me" | "ro" | "tr") => "latn", ("sd", "in") => "deva", @@ -216,7 +231,10 @@ pub(crate) fn region_script(language: &str, region: &str) -> Option<&'static str /// The scripts a script subtag stands for, including the CLDR unions (`jpan`, `kore`). `None` for /// one not in [`Script`], so the language's own scripts apply. fn subtag_scripts(subtag: &str) -> Option<&'static [Script]> { - use Script::*; + use Script::{ + Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mong, Mymr, Orya, + Sinh, Syrc, Taml, Telu, Thaa, Thai, Tibt, + }; Some(match subtag { "hans" | "hant" | "hani" => &[Hani], "jpan" => &[Hani, Hira, Kana], diff --git a/crates/i18n/src/size.rs b/crates/i18n/src/size.rs index 830c09573..b316360a5 100644 --- a/crates/i18n/src/size.rs +++ b/crates/i18n/src/size.rs @@ -33,6 +33,7 @@ impl SizeUnit { /// // `12 MB`, `3.4 MB`, `640 KB`: decimal steps, whole kilobytes, no decimals from 10 MB. /// let style = FileSize::DECIMAL.smallest(SizeUnit::Kilo).largest(SizeUnit::Mega).unit_decimals(SizeUnit::Kilo, 0).whole_from(10); /// ``` +#[must_use] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub struct FileSize { step: u64, @@ -104,6 +105,10 @@ impl FileSize { } /// The unit `bytes` is written in, the number in it and its digits after the point. + #[expect( + clippy::cast_precision_loss, + reason = "File sizes are displayed as rounded f64 values; exact u64 arithmetic is not required for presentation" + )] fn parts(&self, bytes: u64) -> (SizeUnit, f64, usize) { let (smallest, largest) = (self.smallest.min(self.largest), self.largest); let mut unit = smallest; @@ -137,6 +142,7 @@ impl FileSize { } } + #[expect(clippy::cast_precision_loss, reason = "Unit scales are displayed as f64 values; exact u64 arithmetic is not required for presentation")] fn scale(&self, unit: SizeUnit) -> f64 { (self.step as f64).powi(unit as i32) } @@ -160,6 +166,7 @@ impl FileSize { impl I18n { /// `bytes` as a file size in `lang`, written the way `style` says (`1.5 MB`, `512 bytes`), the /// number as [`I18n::format`] writes it (`1,5 Mo`). + #[must_use] pub fn file_size(&self, lang: Lang, bytes: u64, style: FileSize) -> String { let (unit, n, decimals) = style.parts(bytes); if unit == SizeUnit::Byte && !style.byte_symbol { @@ -171,6 +178,7 @@ impl I18n { /// `value` with `decimals` digits after the decimal separator in the unit template `unit`, an /// English catalog key with the number as `{n}` (`{n} px`, `{n} dB`), the number as /// [`I18n::format`] writes it. Percentages are [`crate::Format::percent`]. + #[must_use] pub fn measure(&self, lang: Lang, value: f64, decimals: usize, unit: &str) -> String { self.unit_text(lang, unit, &self.format().number(value, decimals)) } From 271a2a7296be4b9ba4a0f7b6e13a09fb5377d83f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Legrand?= Date: Sun, 1 Nov 2026 22:08:57 +0100 Subject: [PATCH 021/349] style: remove review churn --- crates/i18n/src/collate.rs | 2 -- crates/i18n/src/fold.rs | 8 -------- crates/i18n/src/format.rs | 4 ---- crates/i18n/src/lib.rs | 6 ------ crates/i18n/src/region.rs | 3 --- crates/i18n/src/scripts.rs | 6 ------ crates/i18n/src/size.rs | 3 --- 7 files changed, 32 deletions(-) diff --git a/crates/i18n/src/collate.rs b/crates/i18n/src/collate.rs index 629b3bf75..06d417897 100644 --- a/crates/i18n/src/collate.rs +++ b/crates/i18n/src/collate.rs @@ -30,7 +30,6 @@ impl Collator { /// Sorting for `locale`, a language code such as `sv`, `pt-br` or `zh-hant` (any case, `-` /// or `_`, glibc forms such as `sv_SE.UTF-8` and `sr_RS@latin`). A BCP 47 collation type /// picks another order where there is one: `zh-hant-u-co-pinyin`, `zh-hans-u-co-stroke`. - #[must_use] pub fn new(locale: &str) -> Collator { let mut prefs: CollatorPreferences = Locale::try_from_str(&bcp47(locale)).unwrap_or(Locale::UNKNOWN).into(); prefs.numeric_ordering = Some(CollationNumericOrdering::True); @@ -47,7 +46,6 @@ impl Collator { /// the collation counts as equal (`Layer 2` and `Layer 02`) is in code point order, so a sort /// doesn't depend on the input order. Without collation data (never with the embedded data) /// this is code point order. - #[must_use] pub fn compare(&self, a: &str, b: &str) -> Ordering { match &self.0 { Some(c) => c.as_borrowed().compare(a, b).then_with(|| a.cmp(b)), diff --git a/crates/i18n/src/fold.rs b/crates/i18n/src/fold.rs index dd77b6dfd..fb420e1e1 100644 --- a/crates/i18n/src/fold.rs +++ b/crates/i18n/src/fold.rs @@ -34,7 +34,6 @@ pub struct Folder { impl Folder { /// Case- and accent-insensitive folding for `locale`, a language code such as `tr`, `pt-br` /// or `zh-hant` (any case, `-` or `_`). - #[must_use] pub fn new(locale: &str) -> Folder { let language = locale.split(['-', '_', '.', '@']).next().unwrap_or_default(); Folder { turkic: language.eq_ignore_ascii_case("tr") || language.eq_ignore_ascii_case("az"), accents: false } @@ -42,13 +41,11 @@ impl Folder { /// Accents count: `é` no longer matches `e`, and a match can't end on a letter whose accent it /// leaves out. - #[must_use] pub fn keep_accents(self) -> Folder { Folder { accents: true, ..self } } /// `s` folded, with the map back to `s`. - #[must_use] pub fn fold(&self, s: &str) -> Folded { let nfkd = DecomposingNormalizerBorrowed::new_nfkd(); let extend = CodePointSetData::new::(); @@ -78,13 +75,11 @@ impl Folder { } /// `s` folded, without the map: a key to compare or store. - #[must_use] pub fn key(&self, s: &str) -> String { self.fold(s).text } /// Whether `haystack` contains `needle`, both folded. - #[must_use] pub fn contains(&self, haystack: &str, needle: &str) -> bool { self.fold(haystack).find(&self.fold(needle)).is_some() } @@ -224,7 +219,6 @@ pub struct Folded { impl Folded { /// The folded text. - #[must_use] pub fn as_str(&self) -> &str { &self.text } @@ -232,7 +226,6 @@ impl Folded { /// The source byte range that folded bytes `range` came from, widened to whole source /// characters with their accents: `ss` in the folding of `Straße` maps back to `ß`, `e` in /// that of `é` to the whole `é`. An empty range maps to an empty one. - #[must_use] pub fn source_range(&self, range: Range) -> Range { // The last cluster starting at or before `at` is the one holding it: clusters that fold to // nothing share their offset with the next one. @@ -248,7 +241,6 @@ impl Folded { /// The first match of `needle` (folded the same way), as a byte range of the source text. /// An empty needle matches at the start. - #[must_use] pub fn find(&self, needle: &Folded) -> Option> { self.matches(needle).next() } diff --git a/crates/i18n/src/format.rs b/crates/i18n/src/format.rs index badfbdfca..b907b469c 100644 --- a/crates/i18n/src/format.rs +++ b/crates/i18n/src/format.rs @@ -82,7 +82,6 @@ impl Format { } /// The format for a locale tag (`de-CH`, `ar-EG`), with the locale's own digits. - #[must_use] pub fn from_tag(tag: &str) -> Format { Format::new(&Region::from_tag(tag), Digits::Locale) } @@ -94,7 +93,6 @@ impl Format { /// `value` rounded to `decimals` digits after the decimal separator; infinities and NaN are /// `∞`, `-∞` and `NaN`. - #[must_use] pub fn number(&self, value: f64, decimals: usize) -> String { match to_decimal(value, decimals) { Some(d) => self.write(&d), @@ -104,7 +102,6 @@ impl Format { /// [`Self::number`] without grouping separators, for values such as pixel sizes and years: /// `1920`, `١٩٢٠`, `1234,5`. - #[must_use] pub fn number_ungrouped(&self, value: f64, decimals: usize) -> String { match to_decimal(value, decimals) { Some(d) => { @@ -117,7 +114,6 @@ impl Format { /// `ratio` as a percentage with `decimals` digits after the decimal separator: `0.5` is /// `50%`, `50 %` (French, German), `%50` (Turkish), `٥٠٪؜` (Egyptian Arabic). - #[must_use] pub fn percent(&self, ratio: f64, decimals: usize) -> String { let Some(d) = to_decimal(ratio * 100.0, decimals) else { return format!("{}{}{}", self.percent.0, non_finite(ratio), self.percent.1); diff --git a/crates/i18n/src/lib.rs b/crates/i18n/src/lib.rs index ce473d84f..24ce578a6 100644 --- a/crates/i18n/src/lib.rs +++ b/crates/i18n/src/lib.rs @@ -158,7 +158,6 @@ impl I18n { /// to left, say). Locales that can't be used are skipped and come back as problems for the app /// to log. A locale's bad rows are logged (`log::warn!`) when it is first looked up in, and /// [`I18n::check_all`] lists them all. - #[must_use] pub fn new(embedded: &'static Embedded, offered: &[&str]) -> (I18n, Vec) { let mut problems = Vec::new(); let mut locales = vec![bare("en"), bare("pseudo")]; @@ -420,7 +419,6 @@ impl I18n { /// value that already is one isolate keeps it; pass numbers, paths and codes through [`ltr`]. /// Other text gets no marks, and a value's own isolate is taken off. Unknown placeholders stay as written, /// and inserted values are never read as templates, so a file name containing `{n}` stays intact. -#[must_use] pub fn fmt(template: &str, args: &[(&str, &str)]) -> String { fill(template, args, true) } @@ -428,7 +426,6 @@ pub fn fmt(template: &str, args: &[(&str, &str)]) -> String { /// [`fmt`] without isolates, for text that goes where the marks would get in the way: file /// names, logs, terminals, text compared or parsed later. Every isolate mark is taken off, in /// the template and in the values. -#[must_use] pub fn fmt_plain(template: &str, args: &[(&str, &str)]) -> String { strip_isolates(&fill(template, args, false)) } @@ -449,7 +446,6 @@ const ALM: char = '\u{061C}'; /// `value` as a first-strong isolate (FSI…PDI): it takes the direction of its first strong /// letter and can't reorder the text around it. What [`fmt`] does to each value in text with a /// right-to-left letter. -#[must_use] pub fn isolate(value: &str) -> String { wrap(FSI, value) } @@ -458,14 +454,12 @@ pub fn isolate(value: &str) -> String { /// codes, which read left to right in every language. In an RTL first-strong isolate, the /// segments of `/home/مستخدم/file.txt` would run right to left. [`fmt`] takes the isolate off /// again in text with no right-to-left letter. -#[must_use] pub fn ltr(value: &str) -> String { wrap(LRI, value) } /// `text` without isolate marks (LRI, RLI, FSI, PDI): a [`fmt`] or [`I18n::trn`] result made fit /// for a file name, a log or a comparison. -#[must_use] pub fn strip_isolates(text: &str) -> String { text.chars().filter(|c| !matches!(*c, LRI | RLI | FSI | PDI)).collect() } diff --git a/crates/i18n/src/region.rs b/crates/i18n/src/region.rs index 205444c25..15874d67f 100644 --- a/crates/i18n/src/region.rs +++ b/crates/i18n/src/region.rs @@ -73,7 +73,6 @@ impl Region { /// `nu` stays in the number and time locales (`ar-EG-u-nu-latn`). `C` and `POSIX` are the C /// locale: English, A4, metric, a `.` decimal and no grouping. An empty or unreadable tag is /// `en-US`; a bare `en` is the United States, any other bare language has no territory. - #[must_use] pub fn from_tag(tag: &str) -> Region { match Tag::parse(tag) { Some(tag) => Region::from_parts(&tag), @@ -86,7 +85,6 @@ impl Region { /// The region for an app's saved region setting: `""` or `auto` (any case) is /// [`Region::system`], anything else a locale tag for [`Region::from_tag`]. - #[must_use] pub fn from_setting(setting: &str) -> Region { let setting = setting.trim(); if setting.is_empty() || setting.eq_ignore_ascii_case("auto") { Region::system() } else { Region::from_tag(setting) } @@ -101,7 +99,6 @@ impl Region { /// - Linux and the BSDs: `LC_ALL`, else each of `LC_NUMERIC`, `LC_TIME`, `LC_MEASUREMENT` and /// `LC_PAPER` on its own, else `LANG`. /// - The web and Android: the preferred language, the only locale they expose. - #[must_use] pub fn system() -> Region { static SYSTEM: OnceLock = OnceLock::new(); SYSTEM.get_or_init(read_system).clone() diff --git a/crates/i18n/src/scripts.rs b/crates/i18n/src/scripts.rs index e16342e26..aa39d8917 100644 --- a/crates/i18n/src/scripts.rs +++ b/crates/i18n/src/scripts.rs @@ -39,7 +39,6 @@ pub enum Script { impl Script { /// The ISO 15924 code, `Latn`. - #[must_use] pub fn code(self) -> &'static str { match self { Script::Arab => "Arab", @@ -76,7 +75,6 @@ impl Script { } /// Whether text in this script runs right to left. - #[must_use] pub fn rtl(self) -> bool { matches!(self, Script::Arab | Script::Hebr | Script::Syrc | Script::Thaa) } @@ -114,7 +112,6 @@ pub enum Han { /// where it is the language's own script. A language not in the table is taken to be written in /// Latin. // ponytail: the languages a Craft app ships or could plausibly ship; add a row with the locale. -#[must_use] pub fn scripts(tag: &str) -> &'static [Script] { use Script::{ Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mymr, Orya, Sinh, @@ -160,7 +157,6 @@ pub fn scripts(tag: &str) -> &'static [Script] { } /// The direction of a language tag's text: right to left when its main script is. -#[must_use] pub fn direction(tag: &str) -> Direction { match scripts(tag).first() { Some(s) if s.rtl() => Direction::Rtl, @@ -172,7 +168,6 @@ pub fn direction(tag: &str) -> Direction { /// P3): the contents of isolates (LRI, RLI or FSI up to the matching PDI) are skipped, and the /// search stops at the first paragraph separator. `None` when the paragraph has no strong /// character; P3 then reads it as left to right, and an app may use the interface direction. -#[must_use] pub fn base_direction(text: &str) -> Option { match unicode_bidi::get_base_direction(text) { unicode_bidi::Direction::Ltr => Some(Direction::Ltr), @@ -186,7 +181,6 @@ pub fn base_direction(text: &str) -> Option { /// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → `HongKong`; `ja` → /// Japanese; `ko` → Korean. `None` for a language not written with Han, which leaves the choice /// to the font stack. -#[must_use] pub fn han(tag: &str) -> Option { let tag = Subtags::parse(tag); let hong_kong = matches!(tag.region.as_deref(), Some("hk" | "mo")); diff --git a/crates/i18n/src/size.rs b/crates/i18n/src/size.rs index b316360a5..e0d45d59d 100644 --- a/crates/i18n/src/size.rs +++ b/crates/i18n/src/size.rs @@ -33,7 +33,6 @@ impl SizeUnit { /// // `12 MB`, `3.4 MB`, `640 KB`: decimal steps, whole kilobytes, no decimals from 10 MB. /// let style = FileSize::DECIMAL.smallest(SizeUnit::Kilo).largest(SizeUnit::Mega).unit_decimals(SizeUnit::Kilo, 0).whole_from(10); /// ``` -#[must_use] #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)] pub struct FileSize { step: u64, @@ -166,7 +165,6 @@ impl FileSize { impl I18n { /// `bytes` as a file size in `lang`, written the way `style` says (`1.5 MB`, `512 bytes`), the /// number as [`I18n::format`] writes it (`1,5 Mo`). - #[must_use] pub fn file_size(&self, lang: Lang, bytes: u64, style: FileSize) -> String { let (unit, n, decimals) = style.parts(bytes); if unit == SizeUnit::Byte && !style.byte_symbol { @@ -178,7 +176,6 @@ impl I18n { /// `value` with `decimals` digits after the decimal separator in the unit template `unit`, an /// English catalog key with the number as `{n}` (`{n} px`, `{n} dB`), the number as /// [`I18n::format`] writes it. Percentages are [`crate::Format::percent`]. - #[must_use] pub fn measure(&self, lang: Lang, value: f64, decimals: usize, unit: &str) -> String { self.unit_text(lang, unit, &self.format().number(value, decimals)) } From abceed3f17c3a17de5680c5bd8d14666804e22f7 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 11:56:51 -0500 Subject: [PATCH 022/349] craft-xlsx: binary formulas keep typed spacing and Excel's number spelling Checked against a wider Excel probe (every worksheet function Excel accepts, operators, references, constants, spacing, shared and array formulas), three differences from the .xlsx text are fixed: - PtgAttrSpace: the spaces and line breaks typed in a formula are kept where Excel writes them in .xlsx (before an operand, an operator's symbol or a call, after a parenthesis's or call's opening and before its closing), and the text is trimmed as the .xlsx reader trims it. - Numbers are written out in full when that takes at most 21 characters (100000000000000000000, 0.0000000000000000001), scientific past that (1E+21, 1.5E-19, 1.23456789012345E-06), as Excel spells them. - ISO.CEILING, ECMA.CEILING, NETWORKDAYS.INTL and WORKDAY.INTL are called through hidden _xlfn. names in .xlsb, but .xlsx names them bare. --- crates/xlsx/README.md | 4 +- crates/xlsx/src/xlsb/expr.rs | 64 +++++++++++---- crates/xlsx/src/xlsb/formula.rs | 133 +++++++++++++++++++++++++++++--- crates/xlsx/tests/xlsb.rs | 77 ++++++++++++++++++ 4 files changed, 249 insertions(+), 29 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 1dc30574d..e03128e81 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -85,7 +85,9 @@ they were. A binary workbook is not written. A binary workbook gives the same `Workbook`, strings, rows and merged cells. Its styles are not read (each cell keeps its format index). Its cell formulas are decoded from their tokens into the -text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, no implicit `@`), with +text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, apart from the four +ISO/IEC 29500 functions `.xlsx` names bare, no implicit `@`, the spaces and line breaks typed in +the formula, numbers as Excel spells them), with `FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the file keeps the tokens once. A formula whose decoding needs something the reader does not read diff --git a/crates/xlsx/src/xlsb/expr.rs b/crates/xlsx/src/xlsb/expr.rs index 3dd643a6a..197644a33 100644 --- a/crates/xlsx/src/xlsb/expr.rs +++ b/crates/xlsx/src/xlsb/expr.rs @@ -120,6 +120,9 @@ pub(crate) enum Expr { Ref(Reference), /// A defined name. Name(String), + /// Spaces and line breaks typed before and after an expression (`PtgAttrSpace`), which + /// `.xlsx` formula text keeps. + Spaced(String, Box, String), Unary(UnOp, Box), Binary(BinOp, Box, Box), Call(String, Vec), @@ -195,23 +198,33 @@ fn sci_text(n: f64, sig: usize) -> String { format!("{}E{}{:02}", mant, if e < 0 { '-' } else { '+' }, e.abs()) } -/// A number as a formula spells it: up to 15 significant digits, scientific for very large or -/// very small magnitudes. +/// A number as Excel spells it in a formula: rounded to 15 significant digits, written out in +/// full (`100000000000000000000`, `0.0000000000000000001`) when that takes at most 21 characters +/// without the sign, and scientific (`1E+21`, `1.5E-19`, `1.23456789012345E-06`) when it would +/// take more. pub(crate) fn number_to_text(n: f64) -> String { if n == 0.0 || !n.is_finite() { return "0".into(); } - let a = n.abs(); - if !(1e-9..1e15).contains(&a) && a.round() != a || a >= 1e15 { + let s = format!("{:.14e}", n.abs()); + let Some((mant, exp)) = s.split_once('e') else { return s }; + let Ok(e) = exp.parse::() else { return s }; + let digits: String = mant.chars().filter(char::is_ascii_digit).collect(); + let digits = digits.trim_end_matches('0'); + let digits = if digits.is_empty() { "0" } else { digits }; + let k = digits.len() as i32; + let plain_len = if e >= 0 { (e + 1).max(k + i32::from(k > e + 1)) } else { 1 - e + k }; + if plain_len > 21 { return sci_text(n, 15); } - // A value just below 1e15 can round up to 1e15 at 15 significant digits. - if format!("{a:.14e}").parse::().is_ok_and(|r| r >= 1e15) { - return sci_text(n, 15); - } - let mag = a.log10().floor() as i32; - let decimals = (14 - mag).clamp(0, 30) as usize; - trim_decimal(&format!("{n:.decimals$}")) + let sign = if n < 0.0 { "-" } else { "" }; + let plain = if e >= 0 { + let int = (e + 1) as usize; + if digits.len() <= int { format!("{digits}{}", "0".repeat(int - digits.len())) } else { format!("{}.{}", &digits[..int], &digits[int..]) } + } else { + format!("0.{}{digits}", "0".repeat((-e - 1) as usize)) + }; + format!("{sign}{plain}") } fn number(n: f64) -> String { @@ -248,11 +261,14 @@ fn sheet_split(n: &str) -> Option<(&str, &str)> { at.and_then(|i| Some((n.get(..i)?, n.get(i + 1..)?))) } -/// Prints an expression in A1 notation. +/// Prints an expression in A1 notation, trimmed as the `.xlsx` reader trims formula text. pub(crate) fn print(e: &Expr) -> String { let mut s = String::new(); write_expr(&mut s, e); - s + match s.trim() { + t if t.len() == s.len() => s, + t => t.to_string(), + } } fn write_args(s: &mut String, args: &[Expr], sep: char) { @@ -323,6 +339,11 @@ fn write_expr(s: &mut String, e: &Expr) { write_expr(s, x); s.push(')'); } + Expr::Spaced(before, x, after) => { + s.push_str(before); + write_expr(s, x); + s.push_str(after); + } } } @@ -336,10 +357,21 @@ mod tests { assert_eq!(number_to_text(-2.5), "-2.5"); assert_eq!(number_to_text(0.1 + 0.2), "0.3"); assert_eq!(number_to_text(123456789012345.0), "123456789012345"); - assert_eq!(number_to_text(1e15), "1E+15"); - assert_eq!(number_to_text(1234567890123456.0), "1.23456789012346E+15"); + // Written out in full up to 21 characters, as Excel writes them in .xlsx. + assert_eq!(number_to_text(1e15), "1000000000000000"); + assert_eq!(number_to_text(1234567890123456.0), "1234567890123460"); + assert_eq!(number_to_text(-1e20), "-100000000000000000000"); + assert_eq!(number_to_text(1e21), "1E+21"); + assert_eq!(number_to_text(1.5e21), "1.5E+21"); assert_eq!(number_to_text(0.0001), "0.0001"); - assert_eq!(number_to_text(1e-10), "1E-10"); + assert_eq!(number_to_text(1e-10), "0.0000000001"); + assert_eq!(number_to_text(1e-19), "0.0000000000000000001"); + assert_eq!(number_to_text(1e-20), "1E-20"); + assert_eq!(number_to_text(1.5e-19), "1.5E-19"); + assert_eq!(number_to_text(1.23456789012345e-5), "0.0000123456789012345"); + assert_eq!(number_to_text(1.23456789012345e-6), "1.23456789012345E-06"); + assert_eq!(number_to_text(1234567890.12345), "1234567890.12345"); + assert_eq!(number_to_text(1e100), "1E+100"); assert!(number(f64::MAX).parse::().is_ok_and(f64::is_finite)); } } diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 327ffcc25..22355b630 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -46,9 +46,10 @@ fn pop_n(stack: &mut Stack, n: usize, kids: &mut usize) -> Result, Uns Ok(popped.into_iter().map(|(e, _)| e).collect()) } -/// Pushes the result of a token one level above the operands it consumed. +/// Pushes the result of a token one level above the operands it consumed (two for one with the +/// spacing typed around it, which prints as a level of its own). fn push(stack: &mut Stack, kids: usize, e: Expr) -> Result<(), Unsupported> { - let depth = kids.saturating_add(1); + let depth = kids.saturating_add(1).saturating_add(usize::from(matches!(e, Expr::Spaced(..)))); if depth > MAX_DEPTH { return Err(Unsupported("formula nested too deeply")); } @@ -56,6 +57,48 @@ fn push(stack: &mut Stack, kids: usize, e: Expr) -> Result<(), Unsupported> { Ok(()) } +/// Spaces and line breaks typed in the formula (`PtgAttrSpace`, [MS-XLSB] 2.5.98.32), waiting +/// for the token they belong to. Excel writes the attribute just before that token: spaces +/// before an operand, an operator's symbol or a function call go in `before`; those before a +/// parenthesis's `(`, or before the `)` of a parenthesis or a call, in `open` and `close`. +#[derive(Default)] +struct Spacing { + before: String, + open: String, + close: String, +} + +/// `e` with `ws` typed before it. +fn spaced_before(e: Expr, ws: String) -> Expr { + match e { + _ if ws.is_empty() => e, + Expr::Spaced(b, x, a) => Expr::Spaced(ws + &b, x, a), + e => Expr::Spaced(ws, Box::new(e), String::new()), + } +} + +/// `e` with `ws` typed after it. +fn spaced_after(e: Expr, ws: String) -> Expr { + match e { + _ if ws.is_empty() => e, + Expr::Spaced(b, x, a) => Expr::Spaced(b, x, a + &ws), + e => Expr::Spaced(String::new(), Box::new(e), ws), + } +} + +/// A call's arguments with the spacing typed before its `)`: after the last argument, or alone +/// between the parentheses (`PI( )`). +fn close_args(mut args: Vec, ws: String) -> Vec { + if ws.is_empty() { + return args; + } + match args.pop() { + Some(last) => args.push(spaced_after(last, ws)), + None => args.push(Expr::Spaced(String::new(), Box::new(Expr::Missing), ws)), + } + args +} + /// An error constant's code ([MS-XLSB] 2.5.98.21, `BErr`). fn error_code(code: u8) -> Option { Some(match code { @@ -261,11 +304,16 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res let mut t = Bytes { b: rgce, pos: 0 }; let mut extra = Bytes { b: rgcb, pos: 0 }; let mut stack: Stack = Vec::new(); + let mut ws = Spacing::default(); while t.pos < rgce.len() { let ptg = t.u8()?; let mut kids = 0usize; // Operand classes (reference / value / array) share one token number. let id = if ptg & 0x60 != 0 { 0x20 | (ptg & 0x1F) } else { ptg }; + // An operand (a constant, reference or name) takes the spacing typed before it; operators, + // calls and parentheses place theirs below, and attribute and cache tokens take none. + let operand = !matches!(id, 0x03..=0x15 | 0x19 | 0x21 | 0x22 | 0x26..=0x29); + let height = stack.len(); match id { 0x03..=0x11 => { let op = match id { @@ -287,6 +335,10 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res }; let b = pop(&mut stack, &mut kids)?; let a = pop(&mut stack, &mut kids)?; + // Spacing before the operator's symbol follows the left operand. + let before = std::mem::take(&mut ws.before); + kids = kids.saturating_add(usize::from(!before.is_empty())); + let a = spaced_after(a, before); push(&mut stack, kids, Expr::Binary(op, Box::new(a), Box::new(b)))?; } 0x12..=0x14 => { @@ -296,11 +348,23 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res _ => UnOp::Percent, }; let x = pop(&mut stack, &mut kids)?; - push(&mut stack, kids, Expr::Unary(op, Box::new(x)))?; + // A sign's spacing comes before it; `%`'s before its symbol, after the operand. + let before = std::mem::take(&mut ws.before); + let e = if op == UnOp::Percent { + kids = kids.saturating_add(usize::from(!before.is_empty())); + Expr::Unary(op, Box::new(spaced_after(x, before))) + } else { + spaced_before(Expr::Unary(op, Box::new(x)), before) + }; + push(&mut stack, kids, e)?; } 0x15 => { let x = pop(&mut stack, &mut kids)?; - push(&mut stack, kids, Expr::Paren(Box::new(x)))?; + let close = std::mem::take(&mut ws.close); + kids = kids.saturating_add(usize::from(!close.is_empty())); + let x = spaced_after(x, close); + let before = std::mem::take(&mut ws.open) + &std::mem::take(&mut ws.before); + push(&mut stack, kids, spaced_before(Expr::Paren(Box::new(x)), before))?; } 0x16 => push(&mut stack, kids, Expr::Missing)?, // PtgStr: cch (u16, at most 255) and always UTF-16, unlike BIFF8. @@ -318,14 +382,27 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res let n = usize::from(t.u16()?) + 1; t.take(n * 2)?; } else { - t.take(2)?; + let data = t.take(2)?; + if kind & 0x40 != 0 { + // PtgAttrSpace / PtgAttrSpaceSemi: PtgAttrSpaceType's `type` and `cch`. + let (kind, n) = (data.first().copied().unwrap_or(0), data.get(1).copied().unwrap_or(0)); + let text = if matches!(kind, 1 | 3 | 5) { "\n" } else { " " }.repeat(usize::from(n)); + match kind { + 0 | 1 | 6 => ws.before.push_str(&text), + 2 | 3 => ws.open.push_str(&text), + 4 | 5 => ws.close.push_str(&text), + _ => return Err(Unsupported("unknown spacing in a formula")), + } + } } if kind & 0x10 != 0 { // PtgAttrSum: SUM of the single operand. let x = pop(&mut stack, &mut kids)?; - push(&mut stack, kids, Expr::Call("SUM".into(), vec![x]))?; + let args = close_args(vec![x], std::mem::take(&mut ws.close)); + let call = spaced_before(Expr::Call("SUM".into(), args), std::mem::take(&mut ws.before)); + push(&mut stack, kids.saturating_add(1), call)?; } - // Semi (volatile), If, Goto, Space, Baxcel: no effect on the expression. + // Semi (volatile), If, Goto, Baxcel: no effect on the expression. } 0x1C => { let e = t.u8()?; @@ -346,8 +423,9 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res let iftab = t.u16()?; let (name, args) = function(iftab).ok_or(Unsupported("unknown function"))?; let n = usize::try_from(args).map_err(|_| Unsupported("unknown function argument count"))?; - let args = pop_n(&mut stack, n, &mut kids)?; - push(&mut stack, kids, Expr::Call(name.to_string(), args))?; + let args = close_args(pop_n(&mut stack, n, &mut kids)?, std::mem::take(&mut ws.close)); + let call = spaced_before(Expr::Call(name.to_string(), args), std::mem::take(&mut ws.before)); + push(&mut stack, kids.saturating_add(1), call)?; } 0x22 => { let n = usize::from(t.u8()?); @@ -362,20 +440,33 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res if args.is_empty() { return Err(Unsupported("malformed function call")); } - let name = match args.remove(0) { + // Spacing typed after the `(` comes before the name's token: it belongs to the + // first argument. + let (lead, first) = match args.remove(0) { + Expr::Spaced(before, x, _) => (before, *x), + e => (String::new(), e), + }; + let name = match first { Expr::Name(n) => n, _ => return Err(Unsupported("function call through an expression")), }; + if let Some(a) = args.first_mut() { + *a = spaced_before(std::mem::replace(a, Expr::Missing), lead); + } // `PY(index, …)` runs a script stored elsewhere in the package, which this // import doesn't read. `PY("code", …)` carries its code and becomes a Python cell. let py = name.rsplit('.').next().is_some_and(|n| n.eq_ignore_ascii_case("PY")); if py && !args.first().is_some_and(literal_text) { return Err(Unsupported("Python code stored outside the cell")); } - push(&mut stack, kids, Expr::Call(name, args))?; + let args = close_args(args, std::mem::take(&mut ws.close)); + let call = spaced_before(Expr::Call(bare_function(name), args), std::mem::take(&mut ws.before)); + push(&mut stack, kids.saturating_add(1), call)?; } else { let (name, _) = function(tab & 0x7FFF).ok_or(Unsupported("unknown function"))?; - push(&mut stack, kids, Expr::Call(name.to_string(), args))?; + let args = close_args(args, std::mem::take(&mut ws.close)); + let call = spaced_before(Expr::Call(name.to_string(), args), std::mem::take(&mut ws.before)); + push(&mut stack, kids.saturating_add(1), call)?; } } 0x23 => { @@ -456,6 +547,10 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res } _ => return Err(Unsupported("unknown formula token")), } + if operand && !ws.before.is_empty() && stack.len() == height + 1 { + let (e, depth) = stack.pop().ok_or(Unsupported("malformed formula (operand missing)"))?; + push(&mut stack, depth, spaced_before(e, std::mem::take(&mut ws.before)))?; + } if stack.len() > MAX_RGCE { return Err(Unsupported("formula too complex")); } @@ -467,11 +562,23 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res Ok(grouped(e, false)) } +/// The name a function called through a hidden name is written with in `.xlsx`: that name +/// (`_xlfn.CONCAT`), except for the four ISO/IEC 29500 functions, which `.xlsx` names without the +/// prefix though `.xlsb` calls them as it calls newer functions. +fn bare_function(name: String) -> String { + const ISO: [&str; 4] = ["ISO.CEILING", "ECMA.CEILING", "NETWORKDAYS.INTL", "WORKDAY.INTL"]; + match name.get(..6).filter(|p| p.eq_ignore_ascii_case("_xlfn.")).and(name.get(6..)) { + Some(bare) if ISO.iter().any(|f| f.eq_ignore_ascii_case(bare)) => bare.to_string(), + _ => name, + } +} + /// Text written out in the formula: a string, or strings joined with `&` (how Python code /// longer than a string constant is written). fn literal_text(e: &Expr) -> bool { match e { Expr::Text(_) => true, + Expr::Spaced(_, x, _) => literal_text(x), Expr::Binary(BinOp::Concat, a, b) => literal_text(a) && literal_text(b), _ => false, } @@ -494,6 +601,7 @@ fn binding(e: &Expr) -> u8 { Expr::Binary(op, ..) => op.precedence(), Expr::Unary(UnOp::Neg | UnOp::Plus, _) => 60, Expr::Unary(UnOp::Percent, _) => 70, + Expr::Spaced(_, x, _) => binding(x), _ => u8::MAX, } } @@ -550,6 +658,7 @@ fn grouped(e: Expr, in_args: bool) -> Expr { Expr::Unary(op, Box::new(if needs { paren(x) } else { x })) } Expr::Paren(x) => paren(grouped(*x, false)), + Expr::Spaced(before, x, after) => Expr::Spaced(before, Box::new(grouped(*x, in_args)), after), Expr::Call(name, args) => Expr::Call(name, args.into_iter().map(|a| grouped(a, true)).collect()), other => other, } diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index ee9ac3afd..1be653c87 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -930,3 +930,80 @@ fn a_dynamic_array_kept_as_its_value_has_no_cell_metadata() { assert_eq!(sheet.cell_metadata.iter().collect::>(), [(&at("C1"), &1)]); assert!(warned(&wb, "missing from the file"), "{:?}", wb.warnings); } + +/// `PtgAttrSpace` ([MS-XLSB] 2.5.98.31): its type (0 spaces before the next token, 1 line breaks +/// before it, 2 spaces before a `(`, 4 spaces before a `)`) and count. +fn space(kind: u8, n: u8) -> Vec { + vec![0x19, 0x40, kind, n] +} + +#[test] +fn typed_spacing_numbers_and_iso_functions_read_as_in_xlsx() { + let a1 = || [&[0x24u8][..], &loc(0, REL)].concat(); + let b1 = || [&[0x24u8][..], &loc(0, 1 | REL)].concat(); + let num = |n: f64| [&[0x1Fu8][..], &n.to_le_bytes()].concat(); + let area = |c: u16| [&[0x25u8][..], &0u32.to_le_bytes(), &1u32.to_le_bytes(), &(c | REL).to_le_bytes(), &(c | REL).to_le_bytes()].concat(); + let goto = [0x19u8, 0x08, 0, 0]; + let cells: Vec> = vec![ + // Spacing goes before the next token: an operand, or an operator's symbol. + [&[0x1Eu8, 1, 0][..], &space(0, 2), &[0x1E, 2, 0], &space(0, 1), &[0x03]].concat(), + // ... or a call's `)`, and inside a call's parentheses. + [space(0, 1), a1(), space(0, 1), b1(), space(4, 1), vec![0x42, 2, 4, 0]].concat(), + // Line breaks. + [ + a1(), + vec![0x1E, 0, 0, 0x0D, 0x19, 0x02, 0, 0], + space(1, 1), + space(0, 2), + vec![0x1E, 1, 0], + goto.to_vec(), + space(1, 1), + space(0, 2), + vec![0x1E, 2, 0], + goto.to_vec(), + vec![0x42, 3, 1, 0], + ] + .concat(), + // Inside and before parentheses. + [space(0, 1), vec![0x1E, 1, 0], space(0, 1), vec![0x1E, 2, 0], space(0, 1), vec![0x03], space(4, 1), vec![0x15]].concat(), + [vec![0x1E, 1, 0, 0x1E, 2, 0], space(2, 1), vec![0x15, 0x03]].concat(), + // A call with no arguments, and one through PtgAttrSum. + [space(4, 1), vec![0x41, 19, 0]].concat(), + [area(0), area(1), space(0, 1), vec![0x0F, 0x19, 0x10, 0, 0]].concat(), + // A sign, `%`, and leading spacing (trimmed, as `.xlsx` text is read). + [space(0, 1), vec![0x1E, 1, 0, 0x13], space(0, 1), vec![0x14]].concat(), + [space(0, 3), a1()].concat(), + // A newer function: spacing before its name's token is the first argument's. + [vec![0x1E, 1, 0], space(0, 1), vec![0x23, 5, 0, 0, 0], num(1.5), space(0, 1), vec![0x42, 2, 0xFF, 0, 0x03]].concat(), + vec![0x23, 1, 0, 0, 0, 0x17, 1, 0, b'a', 0, 0x42, 2, 0xFF, 0], + // Numbers written out up to 21 characters, scientific past them. + [num(1e20), num(1e21), vec![0x03], num(1e-19), vec![0x03], num(1.5e-19), vec![0x03], num(1234567890123456.0), vec![0x03]].concat(), + ]; + let mut data = row(0); + for (i, rgce) in cells.iter().enumerate() { + data.extend(formula_cell(i as u32 + 1, rgce, &[])); + } + // Name 5: the hidden name ISO.CEILING is called through, as Excel writes it. + let mut book = book_with_links(&xti()); + let end = record(132, &[]); + book.truncate(book.len() - end.len()); + book.extend(name(0x0002_000b, "_xlfn.ISO.CEILING")); + book.extend(end); + let wb = read(&package(&book, &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + let got: Vec<_> = (1..=cells.len() as u32).map(|c| wb.sheets[0].formula(CellRef::new(0, c))).collect(); + let want = [ + "1 + 2", + "SUM( A1, B1 )", + "IF(A1>0,\n 1,\n 2)", + "( 1 + 2 )", + "1+ (2)", + "PI( )", + "SUM(A1:A2 B1:B2)", + "- 1 %", + "A1", + "1+ ISO.CEILING( 1.5)", + "_xlfn.CONCAT(\"a\")", + "100000000000000000000+1E+21+0.0000000000000000001+1.5E-19+1234567890123460", + ]; + assert_eq!(got, want.map(Some)); +} From 5742279729a6a9cd0118ccf4cee4b99314e7bb56 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 12:01:46 -0500 Subject: [PATCH 023/349] craft-xlsx: binary formulas name macro sheets and span chart sheets An Excel probe showed two references the decoder refused that .xlsx spells: - A reference to an XLM macro sheet (Macro1!$A$1): macro sheets have cells, so the sheet links now name them. - A 3-D span with a chart sheet between its ends ('Data:After Sheet'!$A$1): a span is spelled by its ends, as .xlsx has it. An end with no cells is still refused. --- crates/xlsx/src/xlsb.rs | 5 +++-- crates/xlsx/src/xlsb/formula.rs | 13 +++++-------- crates/xlsx/tests/xlsb.rs | 28 ++++++++++++++++++++++++++++ 3 files changed, 36 insertions(+), 10 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 2fdde59be..65aab0eb8 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -351,9 +351,10 @@ pub(crate) fn workbook( if let SheetKind::Other(_) = kind { return Err(invalid("unknown sheet relationship type")); } - // Only a worksheet has cells a formula can refer to. + // Only worksheets and macro sheets have cells a formula can refer to (a macro's + // name refers to its macro sheet: `Macro1!$A$1`). if let Some(l) = links.as_mut() { - l.sheets.push((kind == SheetKind::Worksheet).then(|| name.clone())); + l.sheets.push(matches!(kind, SheetKind::Worksheet | SheetKind::Macrosheet).then(|| name.clone())); } wb.sheets.push(SheetEntry { name, sheet_id, visibility, rel_id, kind, part: Some(rel.target.clone()) }); } diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 22355b630..3a6960b39 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -147,8 +147,8 @@ pub(super) struct Name { /// Workbook-level tables formulas refer to. #[derive(Default)] pub(crate) struct Links { - /// Every sheet's name in `BrtBundleSh` order, `None` for sheets the reader skips or that hold - /// no cells (chart, dialog and macro sheets). + /// Every sheet's name in `BrtBundleSh` order, `None` for the sheets that hold no cells (chart, + /// dialog and module sheets). pub(super) sheets: Vec>, /// Every `BrtName`, in order: `PtgName` indexes them from 1. pub(super) names: Vec, @@ -179,14 +179,11 @@ impl Links { let (Ok(first), Ok(last)) = (usize::try_from(x.first), usize::try_from(x.last)) else { return Err(Unsupported("reference to a missing sheet")); }; - // A span takes every sheet between its ends, so a skipped one anywhere in it changes - // what the reference means. + // A span is spelled by its ends. A sheet between them with no cells (a chart sheet) adds + // nothing to it, and `.xlsx` spells the span the same; an end with no cells can't be named. let span = self.sheets.get(first..=last).filter(|s| !s.is_empty()).ok_or(Unsupported("reference to a missing sheet"))?; - if span.iter().any(Option::is_none) { - return Err(Unsupported("references to sheets the reader skips")); - } let (Some(Some(a)), Some(Some(b))) = (span.first(), span.last()) else { - return Err(Unsupported("reference to a missing sheet")); + return Err(Unsupported("references to sheets with no cells")); }; Ok(Some(if first == last { SheetSel::Named(a.clone()) } else { SheetSel::Span(a.clone(), b.clone()) })) } diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 1be653c87..950dc8847 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1007,3 +1007,31 @@ fn typed_spacing_numbers_and_iso_functions_read_as_in_xlsx() { ]; assert_eq!(got, want.map(Some)); } + +#[test] +fn references_to_macro_sheets_and_spans_over_chart_sheets_are_named() { + // Sheets Data, a chart sheet, an XLM macro sheet, Hidden; sheet links Macro1, Data:Hidden + // (over the chart sheet) and Chart1 (no cells). + let mut book = record(131, &[]); + book.extend(record(153, &[[0u8; 8].as_slice(), &wide("")].concat())); + book.extend(record(143, &[])); + for (id, rel, name) in [(1u32, "one", "Data"), (3, "c", "Chart1"), (4, "m", "Macro1"), (2, "two", "Hidden")] { + book.extend(record(156, &[&0u32.to_le_bytes()[..], &id.to_le_bytes(), &wide(rel), &wide(name)].concat())); + } + book.extend(record(144, &[])); + let mut xti = 3u32.to_le_bytes().to_vec(); + for (first, last) in [(2i32, 2i32), (0, 3), (1, 1)] { + xti.extend([0u32.to_le_bytes(), first.to_le_bytes(), last.to_le_bytes()].concat()); + } + book.extend([record(353, &[]), record(357, &[]), record(362, &xti), record(354, &[]), record(132, &[])].concat()); + let rels = RELS.replace( + "", + r#""#, + ); + let ref3d = |ixti: u16| [&[0x5Au8][..], &ixti.to_le_bytes(), &loc(0, 0)].concat(); + let data = [row(0), formula_cell(1, &ref3d(0), &[]), formula_cell(2, &ref3d(1), &[]), formula_cell(3, &ref3d(2), &[])].concat(); + let wb = read(&package(&book, &worksheet(&data, &[]), &sst(), ROOT, &rels, TYPES)).unwrap(); + let got: Vec<_> = (1..=3).map(|c| wb.sheets[0].formula(CellRef::new(0, c))).collect(); + assert_eq!(got, [Some("Macro1!$A$1"), Some("Data:Hidden!$A$1"), None]); + assert!(warned(&wb, "references to sheets with no cells"), "{:?}", wb.warnings); +} From 1a4e11926ce8fe6851f881537798299bd629dcb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=A9dric=20Legrand?= Date: Sat, 14 Nov 2026 17:11:58 +0100 Subject: [PATCH 024/349] refactor(dwg): apply behavior-preserving cleanups --- crates/dwg/src/lib.rs | 79 ++++++++++++++++++++++++++++++------------- 1 file changed, 55 insertions(+), 24 deletions(-) diff --git a/crates/dwg/src/lib.rs b/crates/dwg/src/lib.rs index 2db7afeae..de42828c7 100644 --- a/crates/dwg/src/lib.rs +++ b/crates/dwg/src/lib.rs @@ -57,6 +57,10 @@ impl Limits { /// A byte count in megabytes for messages ("9.9 MB", "1024 MB"). #[cfg_attr(no_dwg_bridge, allow(dead_code))] +#[expect( + clippy::cast_precision_loss, + reason = "Megabyte formatting is rounded for display; exact integer precision beyond 2^53 bytes is not meaningful." +)] fn mb(n: u64) -> String { let m = n as f64 / f64::from(1u32 << 20); if m >= 100.0 { format!("{m:.0} MB") } else { format!("{m:.1} MB") } @@ -71,12 +75,17 @@ mod proxy_transport; #[cfg(not(no_dwg_bridge))] mod native { + use std::fmt::Write as _; use std::io::{Cursor, Write}; use std::panic::AssertUnwindSafe; use super::{Limits, mb}; /// Read DWG bytes and return an ASCII DXF rendition, within [`Limits::DEFAULT`]. + /// + /// # Errors + /// + /// Returns an error when the DWG cannot be read or post-processed, or its DXF rendition exceeds the default limits. pub fn dwg_to_dxf(bytes: &[u8]) -> Result, String> { dwg_to_dxf_with(bytes, Limits::DEFAULT) } @@ -84,6 +93,10 @@ mod native { /// [`dwg_to_dxf`] with explicit limits. Both are checked before the expensive step they /// guard: the input size before the DWG reader runs, the DXF size while it is written, so a /// runaway conversion stops at the limit instead of filling memory first. + /// + /// # Errors + /// + /// Returns an error when the input exceeds `limits`, decoding fails, or the DXF output exceeds `limits`. pub fn dwg_to_dxf_with(bytes: &[u8], limits: Limits) -> Result, String> { dwg_to_dxf_noted(bytes, limits).map(|(dxf, _)| dxf) } @@ -92,6 +105,10 @@ mod native { /// failsafe mode: an object record it can't decode is skipped instead of failing the whole /// file, and the notes say how many were skipped and of which types, so a partial read never /// passes for a complete one. + /// + /// # Errors + /// + /// Returns an error when the input exceeds `limits`, decoding fails, or the DXF output exceeds `limits`. pub fn dwg_to_dxf_noted(bytes: &[u8], limits: Limits) -> Result<(Vec, Vec), String> { if bytes.len() > limits.max_dwg_bytes { return Err(format!( @@ -114,13 +131,13 @@ mod native { let mut notes = read_notes(&outcome.stats); let mut doc = outcome.document; notes.extend( - guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|_| "the DWG application object conversion failed".to_string())?, + guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|()| "the DWG application object conversion failed".to_string())?, ); // After application_objects, so the proxy objects it makes are numbered as the DXF's. notes.extend( - guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|_| "the DWG proxy conversion failed".to_string())?, + guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|()| "the DWG proxy conversion failed".to_string())?, ); - let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|_| "the DWG post-processing failed on this file".to_string())?; + let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|()| "the DWG post-processing failed on this file".to_string())?; if orphans > 0 { let (s, were) = if orphans == 1 { ("", "was") } else { ("s", "were") }; notes.push(format!("DWG: {orphans} DGN line style component{s} that no line style definition uses {were} left out")); @@ -624,7 +641,7 @@ mod native { // A real table has at most one merge per cell; more ranges than that come from a // damaged file and would only make this rows × cols × ranges. let max_ranges = rows.saturating_mul(cols).min(1 << 16); - for r in t.merged_ranges.iter().take(max_ranges).cloned().collect::>() { + for r in t.merged_ranges.iter().take(max_ranges).copied().collect::>() { // Clamp to the table: the ranges come from the file. let (bottom, right) = (r.bottom_row.min(rows.saturating_sub(1)), r.right_col.min(cols.saturating_sub(1))); if r.top_row > bottom || r.left_col > right || rows == 0 || cols == 0 || (r.top_row, r.left_col) == (bottom, right) { @@ -707,8 +724,8 @@ mod native { } /// Leave out DGN line style components (`LS*COMPONENT`) that no line style definition uses - /// (#1482). A drawing that once came from MicroStation can carry hundreds of thousands of - /// them, orphaned copies piled up by earlier DGN imports and copy-pastes (AutoCAD's PURGE + /// (#1482). A drawing that once came from `MicroStation` can carry hundreds of thousands of + /// them, orphaned copies piled up by earlier DGN imports and copy-pastes (`AutoCAD`'s PURGE /// removes them as orphaned data): in a real 83 MB site plan they were 888,483 of 889,053 /// components and made its DXF rendition 1.2 GB, over [`Limits::DEFAULT`], so the file /// didn't open at all. No definition that was read refers to them (a definition the reader @@ -838,7 +855,7 @@ mod native { for (name, code, value) in unwritten_header_vars(h) { let written = section.windows(name.len() + 2).any(|w| w.starts_with(name.as_bytes()) && w.ends_with(b"\r\n")); if !written && value.parse::().is_ok_and(f64::is_finite) { - add.push_str(&format!(" 9\r\n{name}\r\n{code:>3}\r\n{value}\r\n")); + let _ = write!(add, " 9\r\n{name}\r\n{code:>3}\r\n{value}\r\n"); } } dxf.splice(end..end, add.into_bytes()); @@ -870,14 +887,22 @@ mod native { /// Oldest DWG version written; older DXF input is written as this version. const MIN_DWG_VERSION: acadrust::DxfVersion = acadrust::DxfVersion::AC1018; - /// Convert DXF bytes into a DWG file of the DXF's version, and at least AutoCAD 2004 + /// Convert DXF bytes into a DWG file of the DXF's version, and at least `AutoCAD` 2004 /// (AC1018). + /// + /// # Errors + /// + /// Returns an error when the DXF cannot be decoded or the DWG cannot be written, including oversized input. pub fn dxf_to_dwg(dxf: &[u8]) -> Result, String> { convert(dxf, None, None).map(|(dwg, _)| dwg) } /// Convert DXF bytes into a DWG file of `version`, a code from [`super::VERSIONS`] ("AC1032"), /// whatever version the DXF declares. + /// + /// # Errors + /// + /// Returns an error for an unsupported version, invalid DXF, oversized input, or a DWG write failure. pub fn dxf_to_dwg_as(dxf: &[u8], version: &str) -> Result, String> { dxf_to_dwg_noted(dxf, version).map(|(dwg, _)| dwg) } @@ -1003,7 +1028,7 @@ mod native { /// The current dimension style (`$DIMSTYLE`) by its name: the DXF gives the name, and the /// handle read with it needn't be the style's in the document, in which case the DWG writer - /// fell back to Standard and AutoCAD opened the drawing with Standard current (#1051). + /// fell back to Standard and `AutoCAD` opened the drawing with Standard current (#1051). fn current_dimstyle(doc: &mut acadrust::CadDocument) { let name = doc.header.current_dimstyle_name.clone(); if let Some(h) = doc.dim_styles.iter().find(|ds| ds.name.eq_ignore_ascii_case(&name)).map(|ds| ds.handle) { @@ -1013,7 +1038,7 @@ mod native { /// The current text style (`$TEXTSTYLE`) by its name, the same way as [`current_dimstyle`]: /// the handle read with the DXF needn't be the style's in the document, in which case the DWG - /// writer fell back to Standard and AutoCAD opened the drawing with Standard current (#1650). + /// writer fell back to Standard and `AutoCAD` opened the drawing with Standard current (#1650). fn current_text_style(doc: &mut acadrust::CadDocument) { let name = doc.header.current_text_style_name.clone(); if let Some(h) = doc.text_styles.iter().find(|ts| ts.name.eq_ignore_ascii_case(&name)).map(|ts| ts.handle) { @@ -1203,7 +1228,7 @@ mod native { }; let (classes, source) = guarded(AssertUnwindSafe(|| (dxf_class_names(&data), super::proxy_transport::source_classes(&data)))) .map_err(|_| "the DXF proxy class conversion failed".to_string())?; - let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(|r| r.read())) + let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(acadrust::DxfReader::read)) .map_err(|_| "the DXF→DWG conversion failed".to_string())? .map_err(|e| format!("DXF: {e}"))?; match version { @@ -1242,14 +1267,14 @@ mod native { current_layer(&mut doc); unwritten })) - .map_err(|_| "the DXF to DWG conversion failed on this file".to_string())?; + .map_err(|()| "the DXF to DWG conversion failed on this file".to_string())?; let dwg = std::panic::catch_unwind(AssertUnwindSafe(|| acadrust::DwgWriter::write_to_vec(&doc))) .map_err(|_| "the DWG writer failed on this drawing".to_string())? .map_err(|e| format!("DWG write: {e}"))?; Ok((dwg, unwritten)) } - /// AutoCAD's entry name for the drawing variables dictionary (the DXF Reference calls it the + /// `AutoCAD`'s entry name for the drawing variables dictionary (the DXF Reference calls it the /// ACDBVARIABLEDICTIONARY; dictionary keys are case-insensitive). const VARIABLE_DICTIONARY: &str = "AcDbVariableDictionary"; @@ -1265,11 +1290,11 @@ mod native { if valid.contains(&value) { value.to_string() } else { default.to_string() } } - /// Add the drawing variables dictionary AutoCAD always writes into the named object + /// Add the drawing variables dictionary `AutoCAD` always writes into the named object /// dictionary, with the variables it keeps there, when the drawing has none (#1813). /// Vectric Aspire 10.5 reads a 2004 (AC1018) DWG without it as empty ("No data was imported /// from the DXF / DWG file"), though it reads the same drawing as DXF — which has no such - /// dictionary either, as CADCraft's and ezdxf's writers don't make one. AutoCAD's AC1032 DWGs + /// dictionary either, as CADCraft's and ezdxf's writers don't make one. `AutoCAD`'s AC1032 DWGs /// read there without it, so newer output is left as it was, and a dictionary the drawing /// does have keeps its own entries and values. fn add_variable_dictionary(doc: &mut acadrust::CadDocument) { @@ -1318,7 +1343,7 @@ mod native { /// Entities of a layout other than the one in `*Paper_Space` are written owned by their block /// (entity mode 0, with its handle). acadrust writes every paper-space entity with mode 1, - /// "paper space", which AutoCAD reads as the `*Paper_Space` block's: everything drawn on a + /// "paper space", which `AutoCAD` reads as the `*Paper_Space` block's: everything drawn on a /// second layout landed on the first one, and the second stayed empty (#1057). fn other_layout_owners(doc: &mut acadrust::CadDocument) { let others: std::collections::HashSet = doc @@ -1541,11 +1566,11 @@ thread_local! { /// Panics when a test asked for `stage` to fail (see [`PANIC_IN`]); does nothing otherwise. #[cfg(not(no_dwg_bridge))] #[allow(clippy::panic)] -fn fail_in_test(_stage: &str) { +fn fail_in_test(stage: &str) { + #[cfg(not(test))] + let _ = stage; #[cfg(test)] - if PANIC_IN.with(|p| p.get()) == Some(_stage) { - panic!("test-forced panic in {_stage}"); - } + assert!(PANIC_IN.with(std::cell::Cell::get) != Some(stage), "test-forced panic in {stage}"); } /// The error for a DWG version this writer can't create. @@ -1623,6 +1648,8 @@ pub fn dxf_to_dwg_kept_noted(_dxf: &[u8], _version: &str, _kept: &str) -> Result #[cfg(test)] mod tests { + use std::fmt::Write as _; + use super::*; /// The DXF of an empty drawing, enough for the bridge to make a small DWG. @@ -1716,9 +1743,9 @@ mod tests { let mut s = String::from(" 0\nSECTION\n 2\nHEADER\n 9\n$ACADVER\n 1\nAC1032\n 0\nENDSEC\n 0\nSECTION\n 2\nENTITIES\n"); for (text, flags, sub, pts) in dims { s += " 0\nDIMENSION\n 8\n0\n100\nAcDbEntity\n100\nAcDbDimension\n 10\n0\n 20\n0\n 30\n0\n"; - s += &format!(" 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n 1\n{text}\n 3\nStandard\n100\n{sub}\n"); - for (code, [x, y]) in pts.iter() { - s += &format!("{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20); + let _ = write!(s, " 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n 1\n{text}\n 3\nStandard\n100\n{sub}\n"); + for (code, [x, y]) in *pts { + let _ = write!(s, "{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20); } } s + " 0\nENDSEC\n 0\nEOF\n" @@ -1787,13 +1814,17 @@ mod tests { .collect() } - /// Issue #1482: a DWG that once came from MicroStation can carry hundreds of thousands of DGN + /// Issue #1482: a DWG that once came from `MicroStation` can carry hundreds of thousands of DGN /// line style components no definition uses (a real 83 MB site plan: 888,483 of 889,053, a /// 1.2 GB DXF rendition over the limit, so it didn't open). They're left out with a note, and /// their dictionary entries with them; the definition and every component it reaches — /// through compound and point components, around a cycle — are kept. #[cfg(not(no_dwg_bridge))] #[test] + #[expect( + clippy::too_many_lines, + reason = "This integration test builds and verifies one complete DGN component graph; splitting the fixture would obscure reachability." + )] fn orphaned_dgn_line_style_components_are_left_out() { use acadrust::objects::*; let mut doc = acadrust::CadDocument::new(); From fa5457bed643d167816d9d188c3b1fc4ebd68d2e Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 12:35:54 -0500 Subject: [PATCH 025/349] craft-xlsx: review fixes: array constants bounded per formula, a spent allowance skips decoding - A formula's array constants share one allowance of 65,536 values, each array charged before its rows are allocated. Before, the cap was per array, so a formula of many arrays could hold gigabytes before the formula text allowance was checked. - Once binary_formula_text is spent, a formula is not decoded only to be dropped: it keeps its saved result straight away. --- crates/xlsx/README.md | 5 +++-- crates/xlsx/src/xlsb.rs | 5 +++++ crates/xlsx/src/xlsb/formula.rs | 15 ++++++++++----- crates/xlsx/tests/xlsb.rs | 27 +++++++++++++++++++++++++++ 4 files changed, 45 insertions(+), 7 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index e03128e81..b8669288e 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -104,8 +104,9 @@ other workbooks, Python code stored outside the cell, data tables. The XLSB func (40 million records, 4 million cells and as many shared strings, 256 MiB of text, as `craft-xls` allows). `binary_formula_text`: decoded formula text over the workbook (128 MiB); past it, formulas keep their saved results. A formula's tokens are bounded at 16 KB, its - nesting at 256 levels and an array constant at 65,536 values. Fixed caps: 1024 sheets, 100,000 merged ranges per sheet, 64 nested - extension blocks. + nesting at 256 levels and its array constants at 65,536 values in all, each charged before + it is held; once the formula text allowance is spent, no formula is decoded. Fixed caps: 1024 + sheets, 100,000 merged ranges per sheet, 64 nested extension blocks. - Cells and rows outside the 1,048,576 × 16,384 grid are dropped and counted. SpreadsheetML is read leniently: a damaged optional part is a warning, a damaged worksheet keeps diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index 65aab0eb8..ea37f59ca 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -523,6 +523,11 @@ fn decode_formula( warnings: &mut Warnings, ) -> Option { let links = links?; + // Once the allowance is spent no formula fits it, so none is decoded only to be dropped. + if !budget.formula_text_fits(1, limits) { + kept(warnings, "more formula text than the limits allow"); + return None; + } let text = match formula::decode(rgce, rgcb, links, mode) { Ok(e) => expr::print(&e), Err(formula::Unsupported(why)) => { diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index 3a6960b39..b62072ad2 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -18,7 +18,8 @@ use super::ftab::function; /// Formula token bytes decoded at most (a cell formula holds at most 16,384). pub(super) const MAX_RGCE: usize = 16 * 1024; -/// Values in one array constant at most. +/// Values in one formula's array constants at most, all of them together: each array is charged +/// before its values are held, so a formula of many arrays can't hold more than this. const MAX_ARRAY: usize = 65_536; /// Why a formula could not be turned back into text. @@ -301,6 +302,7 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res let mut t = Bytes { b: rgce, pos: 0 }; let mut extra = Bytes { b: rgcb, pos: 0 }; let mut stack: Stack = Vec::new(); + let mut array_values = MAX_ARRAY; let mut ws = Spacing::default(); while t.pos < rgce.len() { let ptg = t.u8()?; @@ -414,7 +416,7 @@ pub(super) fn decode(rgce: &[u8], rgcb: &[u8], links: &Links, mode: Mode) -> Res 0x20 => { // PtgArray: 14 unused bytes (Excel leaves junk in them); the values are in rgcb. t.take(14)?; - push(&mut stack, kids, array_constant(&mut extra)?)?; + push(&mut stack, kids, array_constant(&mut extra, &mut array_values)?)?; } 0x21 => { let iftab = t.u16()?; @@ -663,12 +665,15 @@ fn grouped(e: Expr, in_args: bool) -> Expr { /// PtgExtraArray ([MS-XLSB] 2.5.98.41): row and column counts, then `SerAr` values in row-major /// order. The type codes are not BIFF8's: 0x00 is a number here, not a missing value. -fn array_constant(b: &mut Bytes<'_>) -> Result { +fn array_constant(b: &mut Bytes<'_>, left: &mut usize) -> Result { let rows = usize::try_from(b.u32()?).map_err(|_| TRUNC)?; let cols = usize::try_from(b.u32()?).map_err(|_| TRUNC)?; - if rows == 0 || cols == 0 || rows.saturating_mul(cols) > MAX_ARRAY { - return Err(Unsupported("array constant too large or empty")); + let values = rows.saturating_mul(cols); + if values == 0 { + return Err(Unsupported("empty array constant")); } + // Charged before the rows are allocated, against what the formula's arrays may hold in all. + *left = left.checked_sub(values).ok_or(Unsupported("array constants too large"))?; let mut out = Vec::with_capacity(rows); for _ in 0..rows { let mut row = Vec::with_capacity(cols); diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 950dc8847..94bb51ba6 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1035,3 +1035,30 @@ fn references_to_macro_sheets_and_spans_over_chart_sheets_are_named() { assert_eq!(got, [Some("Macro1!$A$1"), Some("Data:Hidden!$A$1"), None]); assert!(warned(&wb, "references to sheets with no cells"), "{:?}", wb.warnings); } + +#[test] +fn a_formulas_array_constants_share_one_allowance() { + // Two arrays of 40,000 Boolean values, each within what one array may hold, added together: + // charged before their values are held, together they pass what a formula's arrays may hold + // (65,536 values), so the cell keeps its saved result. One of them alone decodes. + let array = |n: u32| [&n.to_le_bytes()[..], &1u32.to_le_bytes(), &[2u8, 1].repeat(n as usize)].concat(); + let ptg = [&[0x60u8][..], &[0; 14]].concat(); + let two = [&ptg[..], &ptg, &[0x03]].concat(); + let data = [row(0), formula_cell(0, &two, &[array(40_000), array(40_000)].concat()), formula_cell(1, &ptg, &array(40_000))].concat(); + let wb = read(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), None); + assert_eq!(wb.sheets[0].value(CellRef::new(0, 0)), Value::Number(0.0)); + assert!(wb.sheets[0].formula(CellRef::new(0, 1)).is_some_and(|f| f.starts_with("{TRUE;TRUE"))); + assert!(warned(&wb, "array constants too large"), "{:?}", wb.warnings); +} + +#[test] +fn a_spent_formula_allowance_skips_decoding() { + // With no allowance, a formula is not decoded at all: an unknown token is never reached. + let data = [row(0), formula_cell(0, &[0xFF], &[])].concat(); + let limits = Limits { binary_formula_text: 0, ..Limits::default() }; + let wb = read_with(&package(&book_with_links(&xti()), &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES), &limits).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), None); + assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); + assert!(!warned(&wb, "unknown formula token"), "{:?}", wb.warnings); +} From 88287a6b46e4b7a5e8fab18d07c6ca71791803e9 Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 12:40:55 -0500 Subject: [PATCH 026/349] craft-xlsx: review fixes: styles caps are too large, differential format strings are charged - A styles table past 65,536 entries, or a gradient past 1,024 stops, is past a fixed cap: Error::TooLarge, as the error's contract and the other caps have it, not a damaged part that is skipped with a warning. - A differential format's font name and number format are charged to binary_text, as the other string-bearing style records are. --- crates/xlsx/README.md | 31 ++++++++++++++++--------------- crates/xlsx/src/xlsb/styles.rs | 15 +++++++++++---- crates/xlsx/tests/xlsb.rs | 18 ++++++++++++++---- 3 files changed, 41 insertions(+), 23 deletions(-) diff --git a/crates/xlsx/README.md b/crates/xlsx/README.md index 088e82e3e..9d8e1b785 100644 --- a/crates/xlsx/README.md +++ b/crates/xlsx/README.md @@ -83,21 +83,22 @@ for new pictures (`vm = i + 1`) and the `XLDAPR` dynamic-array metadata (`cm = 1 The parts this crate writes use the transitional namespaces; a strict file's kept parts stay as they were. A binary workbook is not written. -A binary workbook gives the same `Workbook`, strings, rows and merged cells, and the same -`Styles`: number formats, fonts, fills, borders, cell and cell style formats, cell styles, -differential formats and the indexed colours, as Excel writes them in `styles.xml` (default fill -colours and empty settings left out, a cell style format's `apply*="0"`, a number format with a -newer locale tag in its Excel 2007 spelling, as `formatCode` has it). Custom table styles and -recent colours are not read; a damaged styles part is a warning and no styles. Its cell formulas -are decoded from their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as -written, apart from the four ISO/IEC 29500 functions `.xlsx` names bare, no implicit `@`, the -spaces and line breaks typed in the formula, numbers as Excel spells them), with -`FormulaKind::Shared` or `FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell -metadata index. Every cell of a shared formula gets its own text, decoded at the cell, since the -file keeps the tokens once. A formula whose decoding needs something the reader does not read -keeps only its saved result, with a warning saying why: user defined names, table references, -other workbooks, Python code stored outside the cell, data tables. The XLSB function table -(`xlsb/ftab.rs`) and the expression printer are this crate's own, apart from `craft-xls`'s. +A binary workbook gives the same `Workbook`, strings, rows and merged cells, and the same `Styles`: +number formats, fonts, fills, borders, cell and cell style formats, cell styles, differential +formats and the indexed colours, as Excel writes them in `styles.xml` (default fill colours and +empty settings left out, a cell style format's `apply*="0"`, a number format with a newer locale tag +in its Excel 2007 spelling, as `formatCode` has it). Custom table styles and recent colours are not +read; a damaged styles part is a warning and no styles, while one past a cap (65,536 entries in a +table, 1,024 gradient stops) or past `binary_text` is too large. Its cell formulas are decoded from +their tokens into the text an `.xlsx` file holds (`_xlfn.` and `_xlpm.` names as written, apart from +the four ISO/IEC 29500 functions `.xlsx` names bare, no implicit `@`, the spaces and line breaks +typed in the formula, numbers as Excel spells them), with `FormulaKind::Shared` or +`FormulaKind::Array` and their ranges, and `BrtCellMeta` as the cell metadata index. Every cell of a +shared formula gets its own text, decoded at the cell, since the file keeps the tokens once. A +formula whose decoding needs something the reader does not read keeps only its saved result, with a +warning saying why: user defined names, table references, other workbooks, Python code stored +outside the cell, data tables. The XLSB function table (`xlsb/ftab.rs`) and the expression printer +are this crate's own, apart from `craft-xls`'s. ## Hostile input diff --git a/crates/xlsx/src/xlsb/styles.rs b/crates/xlsx/src/xlsb/styles.rs index 50673ef28..88c6bee51 100644 --- a/crates/xlsx/src/xlsb/styles.rs +++ b/crates/xlsx/src/xlsb/styles.rs @@ -176,7 +176,7 @@ fn fill(b: &mut Bytes<'_>) -> Result { let count = b.u32()?; if fls == 0x28 { if count > MAX_STOPS { - return Err(invalid("too many gradient stops")); + return Err(Error::TooLarge(format!("more than {MAX_STOPS} gradient stops"))); } for _ in 0..count { let c = color(b)?.unwrap_or_default(); @@ -330,7 +330,7 @@ fn dxf(b: &mut Bytes<'_>) -> Result { 0x04 => { let g = gradient_fill.as_mut().ok_or_else(|| invalid("gradient stop without a gradient"))?; if g.stops.len() >= MAX_STOPS as usize { - return Err(invalid("too many gradient stops")); + return Err(Error::TooLarge(format!("more than {MAX_STOPS} gradient stops"))); } p.u16()?; let position = p.f64()?; @@ -418,7 +418,7 @@ pub(crate) fn styles(bytes: &[u8], limits: &Limits, budget: &Budget, warnings: & _ => 0, }; if entries >= MAX_ENTRIES { - return Err(invalid(format!("more than {MAX_ENTRIES} entries in a styles table"))); + return Err(Error::TooLarge(format!("more than {MAX_ENTRIES} entries in a styles table"))); } match id { 279 => { @@ -451,7 +451,14 @@ pub(crate) fn styles(bytes: &[u8], limits: &Limits, budget: &Budget, warnings: & budget.text(c.name.len(), limits)?; s.cell_styles.push(c); } - 507 => s.dxfs.push(dxf(&mut b)?), + 507 => { + let d = dxf(&mut b)?; + // What it keeps of its strings, after a later property has replaced an earlier. + let font = d.font.as_ref().and_then(|f| f.name.as_ref()).map_or(0, String::len); + let format = d.num_fmt.as_ref().and_then(|n| n.code.as_ref()).map_or(0, String::len); + budget.text(font + format, limits)?; + s.dxfs.push(d); + } // BrtBeginIndexedColors, BrtEndIndexedColors. 565 => palette = true, 566 => palette = false, diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index bd8b36176..b72705b9f 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1196,11 +1196,11 @@ fn damaged_styles_are_a_warning_and_the_workbook_opens() { assert!(warnings.iter().any(|w| w.contains("look/styles.bin")), "{why}: {warnings:?}"); assert_eq!(read(&bytes).unwrap().sheets[0].value(CellRef::new(0, 0)), Value::Number(1.0), "{why}"); } - // A table past 65,536 entries is refused before it is held. + // A table past 65,536 entries is past a fixed cap: refused before it is held, as too large. let xfs = brt_xf(0, 0, 0, 0, 0, 0, 0, 0x1010, 0).repeat(65_537); - let (styles, warnings) = styles_of(&styled_file(&with(&[&begin(617, 65_537)[..], &xfs, &record(618, &[])].concat()), STYLES_TYPES)); - assert!(styles.is_none()); - assert!(warnings.iter().any(|w| w.contains("65536 entries")), "{warnings:?}"); + let bytes = styled_file(&with(&[&begin(617, 65_537)[..], &xfs, &record(618, &[])].concat()), STYLES_TYPES); + let mut p = Package::open(&bytes, &Limits::default()).unwrap(); + assert!(matches!(p.styles(), Err(Error::TooLarge(m)) if m.contains("65536 entries"))); // Custom table styles are not read, and say so. let table_styles = [body, &record(508, &[&1u32.to_le_bytes()[..], &wide("Probe Table"), &wide("")].concat()), &end].concat(); let (styles, warnings) = styles_of(&styled_file(&table_styles, STYLES_TYPES)); @@ -1339,3 +1339,13 @@ fn a_spent_formula_allowance_skips_decoding() { assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); assert!(!warned(&wb, "unknown formula token"), "{:?}", wb.warnings); } + +#[test] +fn differential_format_strings_are_charged_to_the_text_allowance() { + // A DXF's font name and number format are text the styles part keeps, charged like a font's. + let dxf = |name: &str| [record(278, &[]), begin(505, 1), brt_dxf(&[prop(0x18, &short(name))]), record(506, &[]), record(279, &[])].concat(); + let limits = Limits { binary_text: 100, ..Limits::default() }; + let open = |part: &[u8]| Package::open(&styled_file(part, STYLES_TYPES), &limits).unwrap().styles(); + assert!(open(&dxf("Arial")).is_ok_and(|s| s.is_some_and(|s| s.dxfs.len() == 1))); + assert!(matches!(open(&dxf(&"x".repeat(200))), Err(Error::TooLarge(_)))); +} From 4d8273712e80832c4dc36f8d91ca49271acefa9d Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 18:58:38 +0100 Subject: [PATCH 027/349] docx: count chart axis format characters like the model The reader counted UTF-8 bytes against 255 while the model keeps 128 characters, so a CJK axis format was written and then dropped on reading. Use MAX_FMT. Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/chart_spec.rs | 15 +++++++++++++++ crates/docx/src/read/chart/parse.rs | 2 +- crates/docx/src/read/chart/tests.rs | 8 ++++++-- 3 files changed, 22 insertions(+), 3 deletions(-) diff --git a/crates/docx/src/chart_spec.rs b/crates/docx/src/chart_spec.rs index 1950b15bf..167be6b0d 100644 --- a/crates/docx/src/chart_spec.rs +++ b/crates/docx/src/chart_spec.rs @@ -677,6 +677,21 @@ mod tests { assert_eq!(spec_of(&parse(&plain)), Some(plain)); } + #[test] + fn an_axis_format_is_limited_in_characters_not_bytes() { + use craft_wordmodel::chart::MAX_FMT; + let cjk = format!("0\"{}\"", "\u{5143}".repeat(90)); + let ascii = format!("0\"{}\"", "x".repeat(90)); + for fmt in [cjk, ascii] { + assert!(fmt.chars().count() <= MAX_FMT); + let mut spec = ChartSpec::sample(ChartType::Column); + spec.val_axis.fmt = Some(fmt.clone()); + let spec = spec.sanitized(); + assert_eq!(spec.val_axis.fmt.as_deref(), Some(fmt.as_str())); + assert_eq!(spec_of(&parse(&spec)).as_ref(), Some(&spec), "{} chars", fmt.chars().count()); + } + } + #[test] fn a_chart_with_more_than_the_model_stays_read_only() { let spec = ChartSpec::sample(ChartType::Column); diff --git a/crates/docx/src/read/chart/parse.rs b/crates/docx/src/read/chart/parse.rs index 45586509b..6b20879c6 100644 --- a/crates/docx/src/read/chart/parse.rs +++ b/crates/docx/src/read/chart/parse.rs @@ -311,7 +311,7 @@ pub(super) fn axis(a: Option<&El>) -> Axis { .child("c:numFmt") .filter(|f| f.attr("sourceLinked") != Some("1")) .and_then(|f| f.attr("formatCode")) - .filter(|f| f.len() <= MAX_FORMAT_CODE) + .filter(|f| f.chars().count() <= craft_wordmodel::chart::MAX_FMT) .map(str::to_string), title: a.child("c:title").and_then(title_text), labels: a.child("c:tickLblPos").and_then(|p| p.attr("val")) != Some("none"), diff --git a/crates/docx/src/read/chart/tests.rs b/crates/docx/src/read/chart/tests.rs index 6e8bcfd82..8b26f40c4 100644 --- a/crates/docx/src/read/chart/tests.rs +++ b/crates/docx/src/read/chart/tests.rs @@ -386,9 +386,13 @@ fn axis_format_code_length_is_capped() { let x = format!(r#""#); axis(Some(&crate::xml::parse(x.as_bytes()).unwrap())).fmt }; - let ok = format!("{}0", "x".repeat(254)); + use craft_wordmodel::chart::MAX_FMT; + // The limit is the model's, counted in characters (a CJK character is one). + let ok = format!("{}0", "x".repeat(MAX_FMT - 1)); assert_eq!(fmt(&ok), Some(ok.clone())); - assert_eq!(fmt(&format!("{}0", "x".repeat(300))), None); + let cjk = format!("{}0", "\u{5143}".repeat(MAX_FMT - 1)); + assert_eq!(fmt(&cjk), Some(cjk.clone())); + assert_eq!(fmt(&format!("{}0", "x".repeat(MAX_FMT))), None); } #[test] From e1cd8b5e01cd649d1527a8e9d5393f2563c79d94 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 18:58:38 +0100 Subject: [PATCH 028/349] docx: no_fill wins over a stored series colour Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/chart_spec.rs | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/crates/docx/src/chart_spec.rs b/crates/docx/src/chart_spec.rs index 167be6b0d..a090c5c96 100644 --- a/crates/docx/src/chart_spec.rs +++ b/crates/docx/src/chart_spec.rs @@ -282,13 +282,14 @@ fn series_props(w: &mut W, s: &ChartSeries) { } w.open("c:spPr", &[]); if fill_set { + // "No fill" wins over a stored colour, so the pair reads back as it was written. match &s.fill { - Some(c) => { + Some(c) if !s.no_fill => { w.open("a:solidFill", &[]); w.empty("a:srgbClr", &[("val", &c.hex())]); w.close("a:solidFill"); } - None => w.empty("a:noFill", &[]), + _ => w.empty("a:noFill", &[]), } } if ln_set { @@ -677,6 +678,18 @@ mod tests { assert_eq!(spec_of(&parse(&plain)), Some(plain)); } + #[test] + fn no_fill_wins_over_a_stored_colour() { + let mut spec = ChartSpec::sample(ChartType::Column); + spec.series[0].fill = Some(Rgb(255, 0, 0)); + spec.series[0].no_fill = true; + let x = chart_xml(&spec); + assert!(!x.contains("FF0000"), "colour written next to no_fill"); + let back = spec_of(&parse(&spec)).expect("stays editable"); + assert!(back.series[0].no_fill); + assert_eq!(back.series[0].fill, None); + } + #[test] fn an_axis_format_is_limited_in_characters_not_bytes() { use craft_wordmodel::chart::MAX_FMT; From ca3390ec17917d4d4d687233afbc208250d2e59f Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 18:58:38 +0100 Subject: [PATCH 029/349] wordmodel: ChartSpec::default uses the value-axis preset Co-Authored-By: Claude Sonnet 5.5 --- crates/wordmodel/src/chart.rs | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/crates/wordmodel/src/chart.rs b/crates/wordmodel/src/chart.rs index 4744d8b88..6c7296647 100644 --- a/crates/wordmodel/src/chart.rs +++ b/crates/wordmodel/src/chart.rs @@ -229,7 +229,7 @@ pub fn clean_fmt(s: &str) -> String { } /// A chart the app can edit. -#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)] +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(rename_all = "camelCase")] pub struct ChartSpec { #[serde(rename = "type")] @@ -255,6 +255,23 @@ pub struct ChartSpec { pub val_axis: ChartAxis, } +impl Default for ChartSpec { + /// An empty chart whose value axis is the one a new chart (and a missing JSON field) has: + /// gridlines on, no axis line. + fn default() -> Self { + ChartSpec { + kind: ChartType::default(), + categories: Vec::new(), + series: Vec::new(), + title: None, + legend: None, + data_labels: false, + cat_axis: ChartAxis::default(), + val_axis: value_axis(), + } + } +} + impl ChartSpec { /// A new chart of type `kind` with the app's sample data: four quarters and three series /// (one for pie and doughnut charts, x values for scatter charts), legend at the bottom. @@ -382,6 +399,14 @@ mod tests { assert_eq!(LegendPos::from_id("top"), Some(LegendPos::Top)); } + #[test] + fn default_and_missing_json_axis_fields_agree() { + let from_json: ChartSpec = serde_json::from_str(r#"{"type":"column"}"#).unwrap(); + let d = ChartSpec::default(); + assert_eq!((d.cat_axis.clone(), d.val_axis.clone()), (from_json.cat_axis, from_json.val_axis)); + assert!(d.val_axis.gridlines && !d.val_axis.line); + } + #[test] fn axis_bounds_and_formats_are_cleaned() { let mut a = ChartAxis { From 40d27e4ededfcb0eb85d0017b129575760721258 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 18:59:56 +0100 Subject: [PATCH 030/349] docx: bar category labels start after the axis title strip Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/read/chart/plot.rs | 11 +++++++---- crates/docx/src/read/chart/tests.rs | 24 ++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 4 deletions(-) diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index 09fe672d0..50108b8dc 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -142,6 +142,8 @@ impl Axes { /// The room around the plot for axis labels, and the category labels as they'll be drawn. struct Margins { left: f32, + /// Part of `left` taken by the rotated category-axis title (bars): the labels start after it. + title: f32, top: f32, bottom: f32, /// Category labels in lines (none for scatter charts or a deleted category axis). @@ -159,16 +161,17 @@ fn axis_margins(c: &Chart, ax: &Axes, area: Rect) -> Margins { let scatter = c.kind == Kind::Scatter; let (cat_on, val_on) = (!c.cat.deleted, !c.val.deleted); let (cat_labels, val_labels) = (cat_on && c.cat.labels, val_on && c.val.labels); + let title = title_left(c, cat_on, val_on, lh); let left = if c.horizontal { if cat_labels { widest(&c.cats, fs).min(area.w * 0.4) + GAP } else { 0.0 } } else if val_labels { ax.vticks.iter().map(|(_, s)| text_w(s, fs)).fold(0.0, f32::max) + GAP } else { 0.0 - } + title_left(c, cat_on, val_on, lh); + } + title; let band_w = (area.w - left).max(1.0) / c.n as f32; let wrapped: Vec> = if cat_labels && !scatter { - let width = if c.horizontal { left - GAP } else { band_w }; + let width = if c.horizontal { left - title - GAP } else { band_w }; c.cats.iter().map(|s| wrap(s, width, fs)).collect() } else { Vec::new() @@ -184,7 +187,7 @@ fn axis_margins(c: &Chart, ax: &Axes, area: Rect) -> Margins { 0.0 }) + title_bottom(c, cat_on, val_on, lh); let top = if !c.horizontal && val_labels { lh / 2.0 } else { 0.0 }; - Margins { left, top, bottom, wrapped, skip } + Margins { left, title, top, bottom, wrapped, skip } } /// Room for the vertical axis title on the plot's left: one line when the axis that sits there @@ -332,7 +335,7 @@ fn draw_category_labels(out: &mut Vec, c: &Chart, g: &Frame, xticks for (i, lines) in m.wrapped.iter().enumerate() { let top = g.band_start(i) + g.band() / 2.0 - lines.len() as f32 * lh / 2.0; for (k, s) in lines.iter().enumerate() { - text(out, Rect { x: area.x, y: top + k as f32 * lh, w: m.left - GAP, h: lh }, s, fs, TextAlign::Right, false); + text(out, Rect { x: area.x + m.title, y: top + k as f32 * lh, w: m.left - m.title - GAP, h: lh }, s, fs, TextAlign::Right, false); } } } else { diff --git a/crates/docx/src/read/chart/tests.rs b/crates/docx/src/read/chart/tests.rs index 8b26f40c4..528f46ee2 100644 --- a/crates/docx/src/read/chart/tests.rs +++ b/crates/docx/src/read/chart/tests.rs @@ -594,3 +594,27 @@ fn series_without_a_usable_c_idx_take_their_place() { let big = [renumbered(&a, &format!(r#""#, u32::MAX))]; assert_eq!(column_colours(&big).0.len(), 1); } + +#[test] +fn bar_category_labels_start_after_the_axis_title() { + let long = "A category label that is much too long for its column"; + let title = r#"Region"#; + let plot = format!( + r#"{}{title}"#, + ser(0, "S", Some("FF0000"), &[long, "Short"], &["4", "8"]), + ); + let items = chart_items(&space(&plot), &theme(), 300.0, 200.0); + let rect_of = |f: &dyn Fn(&str, &TextAlign) -> bool| -> Vec<[f32; 4]> { + items + .iter() + .filter_map(|it| if let GraphicItem::Text { rect, text, align, .. } = it { f(text, align).then_some(*rect) } else { None }) + .collect() + }; + let title_rect = rect_of(&|t, _| t == "Region"); + assert_eq!(title_rect.len(), 1); + let strip_end = title_rect[0][0] + title_rect[0][2]; + let labels = rect_of(&|t, a| matches!(a, TextAlign::Right) && t != "Region" && (long.contains(t) || t == "Short")); + assert!(!labels.is_empty()); + assert!(labels.iter().all(|r| r[0] >= strip_end - 1e-3), "labels {labels:?} overlap the title strip ending at {strip_end}"); + assert!(labels.iter().all(|r| r[2] <= 0.4 * 300.0), "{labels:?}"); +} From 0edccaf1bc46f21bc35cc3b40f85a5a13b5bbae7 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 18:59:56 +0100 Subject: [PATCH 031/349] docx: category gridlines follow line and area points when the axis crosses mid Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/read/chart/plot.rs | 21 ++++++++++------ crates/docx/src/read/chart/tests.rs | 38 +++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 7 deletions(-) diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index 50108b8dc..eae203546 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -220,7 +220,7 @@ pub(super) fn cartesian(out: &mut Vec, c: &Chart, area: Rect) { draw_grid(out, &g, &ax.vticks); } if c.cat.grid { - draw_cat_grid(out, &g, &ax.xticks, c.kind == Kind::Scatter); + draw_cat_grid(out, &g, &ax.xticks, c.kind); } let mut labels = Vec::new(); match c.kind { @@ -274,11 +274,12 @@ fn draw_grid(out: &mut Vec, g: &Frame, ticks: &[(f64, String)]) { } } -/// Gridlines along the category axis: across the plot at each category's centre, at the x ticks -/// of a scatter chart. -fn draw_cat_grid(out: &mut Vec, g: &Frame, xticks: &[(f64, String)], scatter: bool) { +/// Gridlines along the category axis: across the plot at each category's centre (where line and +/// area points sit, on the tick marks when the axis crosses "midCat"), at the x ticks of a +/// scatter chart. +fn draw_cat_grid(out: &mut Vec, g: &Frame, xticks: &[(f64, String)], kind: Kind) { let plot = g.plot; - if scatter { + if kind == Kind::Scatter { for (t, _) in xticks { let p = g.scat_x(*t); stroke(out, seg(p, plot.y, p, plot.bottom()), GRID, 0.75); @@ -286,8 +287,14 @@ fn draw_cat_grid(out: &mut Vec, g: &Frame, xticks: &[(f64, String)] return; } for i in 0..g.n { - let p = g.band_start(i) + g.band() / 2.0; - let segs = if g.horiz { seg(plot.x, p, plot.right(), p) } else { seg(p, plot.y, p, plot.bottom()) }; + let segs = if g.horiz { + let p = g.band_start(i) + g.band() / 2.0; + seg(plot.x, p, plot.right(), p) + } else { + // Bars stay in their bands; only line and area points move onto the ticks. + let p = if matches!(kind, Kind::Line | Kind::Area) { g.cat_x(i) } else { g.band_start(i) + g.band() / 2.0 }; + seg(p, plot.y, p, plot.bottom()) + }; stroke(out, segs, GRID, 0.75); } } diff --git a/crates/docx/src/read/chart/tests.rs b/crates/docx/src/read/chart/tests.rs index 528f46ee2..74573b5d8 100644 --- a/crates/docx/src/read/chart/tests.rs +++ b/crates/docx/src/read/chart/tests.rs @@ -618,3 +618,41 @@ fn bar_category_labels_start_after_the_axis_title() { assert!(labels.iter().all(|r| r[0] >= strip_end - 1e-3), "labels {labels:?} overlap the title strip ending at {strip_end}"); assert!(labels.iter().all(|r| r[2] <= 0.4 * 300.0), "{labels:?}"); } + +#[test] +fn category_gridlines_follow_the_points_when_the_axis_crosses_mid() { + let line = |cross: &str| { + let plot = format!( + r#"{}"#, + ser(0, "L", Some("FF0000"), &["Q1", "Q2", "Q3"], &["1", "5", "3"]), + ); + let items = chart_items(&space(&plot), &theme(), 300.0, 200.0); + let grid: Vec = items + .iter() + .filter_map(|it| match it { + GraphicItem::Path { segs, stroke: Some(c), .. } if *c == GRID => match segs.first() { + Some(PathSeg::Move(x, _)) => Some(*x), + _ => None, + }, + _ => None, + }) + .collect(); + let pts: Vec = items + .iter() + .filter_map(|it| match it { + GraphicItem::Path { segs, stroke: Some(c), .. } if *c == Rgb(255, 0, 0) => Some( + segs.iter().filter_map(|s| if let PathSeg::Move(x, _) | PathSeg::Line(x, _) = s { Some(*x) } else { None }).collect::>(), + ), + _ => None, + }) + .next() + .unwrap_or_default(); + (grid, pts) + }; + for cross in ["midCat", "between"] { + let (grid, pts) = line(cross); + assert_eq!(grid.len(), 3, "{cross}"); + assert_eq!(pts.len(), 3, "{cross}"); + assert!(grid.iter().zip(&pts).all(|(g, p)| (g - p).abs() < 1e-3), "{cross}: grid {grid:?} points {pts:?}"); + } +} From 80ed9665e7d27a98cc55e5526a1523327a380784 Mon Sep 17 00:00:00 2001 From: batistalucasv Date: Sat, 14 Nov 2026 15:25:54 -0300 Subject: [PATCH 032/349] craft-docx: preserve w:numberingChange without active list and raise w:original bound --- crates/docx/src/read/story/blocks.rs | 9 +++--- crates/docx/src/write/props.rs | 8 +++-- crates/docx/tests/it/fixtures.rs | 44 ++++++++++++++++++++++++++++ 3 files changed, 54 insertions(+), 7 deletions(-) diff --git a/crates/docx/src/read/story/blocks.rs b/crates/docx/src/read/story/blocks.rs index 38c35a02b..878429454 100644 --- a/crates/docx/src/read/story/blocks.rs +++ b/crates/docx/src/read/story/blocks.rs @@ -249,10 +249,11 @@ impl Reader<'_> { .unwrap_or_default(); para.props.fmt_change = PropChange::boxed(self.revision(RevisionKind::Format, ch), old); } - if para.props.numbering.is_some() - && let Some(ch) = ppr.child("w:numPr").and_then(|n| n.child("w:numberingChange")) - { - let original = ch.attr("w:original").unwrap_or("").chars().take(256).collect(); + if let Some(ch) = ppr.child("w:numPr").and_then(|n| n.child("w:numberingChange")) { + // Multi-level numbering caches (`w:original`) routinely exceed 256 chars while staying + // bounded against hostile attributes. + const MAX_CHANGE_ORIGINAL: usize = 4096; + let original = ch.attr("w:original").unwrap_or("").chars().take(MAX_CHANGE_ORIGINAL).collect(); para.props.num_change = Some(Box::new(NumChange { rev: self.revision(RevisionKind::Format, ch), original })); } if let Some(s) = ppr.child("w:sectPr") { diff --git a/crates/docx/src/write/props.rs b/crates/docx/src/write/props.rs index 0a64fc20a..0b92ce191 100644 --- a/crates/docx/src/write/props.rs +++ b/crates/docx/src/write/props.rs @@ -261,10 +261,12 @@ pub fn ppr_inner(w: &mut W, p: &ParaProps, framed: bool, num_change: Option<&Cha toggle(w, "w:pageBreakBefore", p.page_break_before); write_frame(w, p, framed); toggle(w, "w:widowControl", p.widow_control); - if let Some(nr) = p.numbering { + if p.numbering.is_some() || num_change.is_some() { w.open("w:numPr", &[]); - w.val("w:ilvl", &n(nr.level.min(8) as i64)); - w.val("w:numId", &n(nr.num as i64)); + if let Some(nr) = p.numbering { + w.val("w:ilvl", &n(nr.level.min(8) as i64)); + w.val("w:numId", &n(nr.num as i64)); + } if let Some(a) = num_change { let refs: Vec<(&str, &str)> = a.iter().map(|(k, v)| (*k, v.as_str())).collect(); w.empty("w:numberingChange", &refs); diff --git a/crates/docx/tests/it/fixtures.rs b/crates/docx/tests/it/fixtures.rs index 868e8cbb0..348d6239e 100644 --- a/crates/docx/tests/it/fixtures.rs +++ b/crates/docx/tests/it/fixtures.rs @@ -2197,6 +2197,50 @@ fn formatting_revisions_round_trip() { assert_eq!(again.revisions, d.revisions); } +#[test] +fn numbering_change_without_active_list_roundtrips() { + let body = r#"Removed"#; + let d = read_body(body); + let p = paras(&d); + assert_eq!(p.len(), 1); + assert!(p[0].props.numbering.is_none()); + let nc = p[0].props.num_change.as_deref().expect("numberingChange read back"); + assert_eq!(nc.original, "%1:1:0:."); + + let bytes = craft_docx::write(&d).unwrap(); + let mut zip = zip::ZipArchive::new(std::io::Cursor::new(&bytes)).unwrap(); + let mut xml = String::new(); + std::io::Read::read_to_string(&mut zip.by_name("word/document.xml").unwrap(), &mut xml).unwrap(); + assert!(xml.contains(r#""#), "{xml}"); + + let again = craft_docx::read(&bytes).unwrap(); + let ap = paras(&again); + assert!(ap[0].props.numbering.is_none()); + let anc = ap[0].props.num_change.as_deref().expect("numberingChange preserved after save"); + assert_eq!(anc.original, "%1:1:0:."); +} + +#[test] +fn numbering_change_original_preserves_long_values_within_bound() { + let long_orig = "%1:1:0:.".repeat(64); // 512 chars, well past the old 256-char cap + assert!(long_orig.len() > 256 && long_orig.len() < 4096); + let over_cap = "x".repeat(5000); + let body = format!( + r#"Long +Bounded"# + ); + let d = read_body(&body); + let p = paras(&d); + assert_eq!(p[0].props.num_change.as_deref().map(|n| n.original.as_str()), Some(long_orig.as_str())); + assert_eq!(p[1].props.num_change.as_deref().map(|n| n.original.chars().count()), Some(4096)); + + let bytes = craft_docx::write(&d).unwrap(); + let again = craft_docx::read(&bytes).unwrap(); + let ap = paras(&again); + assert_eq!(ap[0].props.num_change.as_deref().map(|n| n.original.as_str()), Some(long_orig.as_str())); +} + /// A package with `styles`, a theme (accent1 4472C4, accent2 ED7D31, major font "Major Face") and, /// when given, `settings`. fn themed_docx(body: &str, styles: &str, settings: Option<&str>) -> Document { From 24e626611985746bebbbdd9c252b8ee705701efd Mon Sep 17 00:00:00 2001 From: kiwi4boy Date: Sat, 14 Nov 2026 13:27:25 -0500 Subject: [PATCH 033/349] craft-xlsx: review fixes: spaced string chains flatten, module sheets and supporting links are capped - literal_texts now accepts a spaced operand as literal_text does, and the chain flattens with the spacing kept on its strings, so a chain the Python check accepts is written flat ("x"& "="&"1", not "x"&( "="&"1")). - Every BrtBundleSh counts toward the 1,024-sheet cap, a skipped module sheet too, since each keeps a place in the sheet links. - Supporting links are capped at 65,536; past it the links aren't read and formulas keep their saved results. --- crates/xlsx/src/xlsb.rs | 12 +++++++++++- crates/xlsx/src/xlsb/formula.rs | 30 ++++++++++++++++++++++++++++-- crates/xlsx/tests/xlsb.rs | 18 ++++++++++++++++++ 3 files changed, 57 insertions(+), 3 deletions(-) diff --git a/crates/xlsx/src/xlsb.rs b/crates/xlsx/src/xlsb.rs index ea37f59ca..b3f94b5fa 100644 --- a/crates/xlsx/src/xlsb.rs +++ b/crates/xlsx/src/xlsb.rs @@ -26,6 +26,9 @@ pub(crate) const WORKSHEET: &str = "application/vnd.ms-excel.worksheet"; pub(crate) const STRINGS: &str = "application/vnd.ms-excel.sharedStrings"; /// Most sheets in the workbook. const MAX_SHEETS: usize = 1024; +/// Supporting links (this workbook, add-ins, other workbooks) read at most; past it, formulas +/// keep their saved results. +const MAX_BOOKS: usize = 65_536; /// Most merged ranges in one worksheet. const MAX_MERGES: usize = 100_000; /// Defined names (Excel's hidden ones for newer functions included) read at most; past it, the @@ -268,6 +271,9 @@ pub(crate) fn workbook( let mut links = Some(Links::default()); let mut bundle = false; let mut bundle_seen = false; + // Every BrtBundleSh counts toward the cap, a skipped module sheet too: each keeps a place + // in the sheet links. + let mut bundle_count = 0usize; while let Some((id, payload)) = records.next(warnings)? { let mut b = Bytes::new(payload); match id { @@ -316,9 +322,10 @@ pub(crate) fn workbook( if !bundle { return Err(invalid("worksheet outside the worksheet list")); } - if wb.sheets.len() >= MAX_SHEETS { + if bundle_count >= MAX_SHEETS { return Err(Error::TooLarge(format!("XLSB exceeds {MAX_SHEETS} sheets"))); } + bundle_count += 1; let visibility = match b.u32()? { 0 => Visibility::Visible, 1 => Visibility::Hidden, @@ -368,6 +375,9 @@ pub(crate) fn workbook( /// (`BrtExternSheet`) or a defined name (`BrtName`), added to `links`. fn link_record(id: u16, payload: &[u8], links: &mut Links) -> Result<(), Error> { let mut b = Bytes::new(payload); + if matches!(id, 355 | 357 | 358 | 667) && links.books.len() >= MAX_BOOKS { + return Err(invalid("too many supporting links")); + } match id { 357 | 358 | 667 => { b.finish()?; diff --git a/crates/xlsx/src/xlsb/formula.rs b/crates/xlsx/src/xlsb/formula.rs index b62072ad2..a7293c0df 100644 --- a/crates/xlsx/src/xlsb/formula.rs +++ b/crates/xlsx/src/xlsb/formula.rs @@ -583,10 +583,13 @@ fn literal_text(e: &Expr) -> bool { } } -/// How many strings a [`literal_text`] chain joins, or `None` for anything else. +/// How many strings a [`literal_text`] chain joins, or `None` for anything else. It accepts +/// what [`literal_text`] does, typed spacing included, so a chain the Python check accepts is +/// one that is written flat. fn literal_texts(e: &Expr) -> Option { match e { Expr::Text(_) => Some(1), + Expr::Spaced(_, x, _) => literal_texts(x), Expr::Binary(BinOp::Concat, a, b) => literal_texts(a)?.checked_add(literal_texts(b)?), _ => None, } @@ -605,13 +608,24 @@ fn binding(e: &Expr) -> u8 { } } -/// The strings of a [`literal_text`] chain, left to right. +/// The strings of a [`literal_text`] chain, left to right. Spacing typed around a part of the +/// chain stays with that part's first and last strings, where it is written. fn flatten_texts(e: Expr, out: &mut Vec) { match e { Expr::Binary(BinOp::Concat, a, b) => { flatten_texts(*a, out); flatten_texts(*b, out); } + Expr::Spaced(before, x, after) if matches!(*x, Expr::Binary(BinOp::Concat, ..)) => { + let start = out.len(); + flatten_texts(*x, out); + if let Some(first) = out.get_mut(start) { + *first = spaced_before(std::mem::replace(first, Expr::Missing), before); + } + if let Some(last) = out.last_mut() { + *last = spaced_after(std::mem::replace(last, Expr::Missing), after); + } + } text => out.push(text), } } @@ -716,6 +730,18 @@ mod tests { } } + #[test] + fn a_spaced_part_of_a_string_chain_is_written_flat() { + // `"x"`, then `"="` typed with a space before it joined to `"1"`, then joined: the tokens + // nest to the right, and the space is on the inner chain. Written flat, as Python code + // must be, with the space where it was typed. + let s = |c: u8| [0x17, 1, 0, c, 0]; + let rgce = [&s(b'x')[..], &[0x19, 0x40, 0, 1], &s(b'=')[..], &s(b'1')[..], &[0x08, 0x08]].concat(); + let e = decode(&rgce, &[], &Links::default(), Mode::Cell).unwrap(); + assert_eq!(super::super::expr::print(&e), "\"x\"& \"=\"&\"1\""); + assert!(literal_text(&e) && literal_texts(&e) == Some(3)); + } + #[test] fn a_long_chain_of_strings_stays_within_the_depth_bound() { // 4,096 strings and 4,095 `&` fill 16,383 token bytes, 13 levels deep as written. Made diff --git a/crates/xlsx/tests/xlsb.rs b/crates/xlsx/tests/xlsb.rs index 94bb51ba6..748d1b86d 100644 --- a/crates/xlsx/tests/xlsb.rs +++ b/crates/xlsx/tests/xlsb.rs @@ -1062,3 +1062,21 @@ fn a_spent_formula_allowance_skips_decoding() { assert!(warned(&wb, "more formula text than the limits allow"), "{:?}", wb.warnings); assert!(!warned(&wb, "unknown formula token"), "{:?}", wb.warnings); } + +#[test] +fn module_sheets_and_supporting_links_are_bounded() { + // 1,025 very hidden module sheets (no relationship) before the worksheets: each keeps a place + // in the sheet links, so together they are past the 1,024-sheet cap. + let plain = book(false); + let at = plain.windows(3).position(|w| w == record(143, &[]).as_slice()).unwrap() + 3; + let module = record(156, &[&2u32.to_le_bytes()[..], &9u32.to_le_bytes(), &u32::MAX.to_le_bytes(), &wide("Module")].concat()); + let modules = [&plain[..at], &module.repeat(1025), &plain[at..]].concat(); + assert!(matches!(read(&package(&modules, &worksheet(&[], &[]), &sst(), ROOT, RELS, TYPES)), Err(Error::TooLarge(_)))); + // 65,537 supporting links: past the cap the links aren't read, and formulas keep their values. + let end = record(132, &[]); + let selves = [&plain[..plain.len() - end.len()], &record(353, &[]), &record(357, &[]).repeat(65_537), &record(354, &[]), &end].concat(); + let data = [row(0), formula_cell(0, &[0x1E, 1, 0], &[])].concat(); + let wb = read(&package(&selves, &worksheet(&data, &[]), &sst(), ROOT, RELS, TYPES)).unwrap(); + assert_eq!(wb.sheets[0].formula(CellRef::new(0, 0)), None); + assert!(wb.warnings.iter().any(|w| w.contains("sheet links or names could not be read")), "{:?}", wb.warnings); +} From 76ddfc37493022c9127095f8fa20a23429ba59a6 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 21:57:59 +0100 Subject: [PATCH 034/349] craft-heif: items reads the primary image's metadata; add scan and exif_tiff Port the container reader of storytold/lightcraft#1208 into `items`: - `read` follows `pitm`, `cdsc` and the `dimg` inputs to return the primary image's EXIF and XMP, then items tied to no image. A thumbnail's or depth map's metadata is no longer the photo's. - `scan` returns every EXIF and XMP item, with each item's bytes or why they can't be read, and `Scan::complete` is false when the item catalog can't be read in full. An app that must prove a file has no location refuses when unsure. - `exif_tiff` finds the TIFF stream with or without a correct offset field or an `Exif\0\0` prefix. - `iloc` is walked once; the module denies indexing and unchecked arithmetic; boxes, items and gathered bytes are bounded. The tests of #1055 and lightcraft#1208 come along, adapted to assert the returned bytes and the scan's completeness. --- crates/heif/Cargo.toml | 3 + crates/heif/src/items.rs | 1044 +++++++++++++++++----------- crates/heif/src/items/tests.rs | 1173 ++++++++++++++++++++++++++++++++ 3 files changed, 1806 insertions(+), 414 deletions(-) create mode 100644 crates/heif/src/items/tests.rs diff --git a/crates/heif/Cargo.toml b/crates/heif/Cargo.toml index a5734e611..9cd59453f 100644 --- a/crates/heif/Cargo.toml +++ b/crates/heif/Cargo.toml @@ -19,6 +19,9 @@ heic-rs = { version = "=0.1.4", default-features = false, features = ["std"], op heic-rs = { version = "=0.1.4", default-features = false, features = ["std", "parallel"], optional = true } rayon = { workspace = true, optional = true } +[dev-dependencies] +proptest = { workspace = true } + [features] default = ["decode"] # The decoder (probe, decode, decode_thumbnail, read_metadata): heic-rs for the container and HEVC. diff --git a/crates/heif/src/items.rs b/crates/heif/src/items.rs index 7d4ffe0dc..d00dbdf06 100644 --- a/crates/heif/src/items.rs +++ b/crates/heif/src/items.rs @@ -1,223 +1,652 @@ //! HEIF / HEIC / AVIF metadata from the box structure alone (feature `metadata`): the `Exif` and -//! XMP items of the ISO base media file container (box structure from ISO/IEC 14496-12, item model -//! from ISO/IEC 23008-12). It needs no HEVC decoder and no heic-rs, so a build that only catalogues +//! XMP items of the image file format built on the ISO base media file format (ISO/IEC 23008-12 +//! on ISO/IEC 14496-12). It needs no HEVC decoder and no heic-rs, so a build that only catalogues //! photos can read their capture time, camera and lens. //! -//! The `meta` box holds an item information box (`iinf`, one `infe` per item) naming each item's -//! type, and an item location box (`iloc`) saying where its bytes are: in the file, or in the -//! `idat` box next to it. The `Exif` item is a four-byte offset followed by a TIFF stream; the XMP -//! packet is a `mime` item whose content type is `application/rdf+xml`. The first such item counts -//! (the decoder's [`crate::read_metadata`] takes the primary image's instead). Moved from LightCraft's -//! `lightcraft-meta`. +//! - `ftyp` names a HEIF or AVIF brand ([`is_heif`]). +//! - The top-level `meta` box lists the items (`iinf`, one `infe` each), says where each item's +//! bytes are (`iloc`: extents in the file, construction method 0, or in the `meta` box's own +//! `idat`, method 1), which item is the photo (`pitm`) and how items relate (`iref`). +//! - EXIF is an item of type `Exif`: a 4-byte big-endian offset to the TIFF header, then the +//! payload (ISO/IEC 23008-12 annex A). iPhones write offset 6 and an `Exif\0\0` prefix; libheif +//! and avif-serialize write offset 0 and the TIFF stream ([`exif_tiff`]). +//! - XMP is an item of type `mime` with content type `application/rdf+xml`. +//! - A `cdsc` ("content describes") reference ties a metadata item to the image it describes. The +//! photo's items are those tied to the primary image or to an image it is made from (its `dimg` +//! inputs: a grid's tiles, the picture an `iden` turns, an `iovl` overlay's or a `tmap` tone +//! map's inputs), else those tied to no image (they describe the file). An item tied only to +//! other images (a thumbnail, a depth map, another photo of a collection) is not this photo's. +//! +//! [`read`] returns the photo's own EXIF and XMP, as the decoder's [`crate::read_metadata`] does. +//! [`scan`] returns every EXIF and XMP item instead, whichever image it describes, and says when +//! it can't be sure it saw them all ([`Scan::complete`], [`Unreadable`]). An app that must prove a +//! file holds no location before copying it out (export's "remove location") refuses when unsure. +//! +//! The ICC profile is left to the decoder, which reads it for rendering. Every size and offset is +//! checked against the buffer; the boxes read, the items considered and the bytes gathered are +//! bounded, and `iloc` is walked once. Moved from LightCraft's `lightcraft-meta`. +#![deny(clippy::indexing_slicing, clippy::arithmetic_side_effects, clippy::unwrap_used, clippy::expect_used, clippy::panic)] + +use std::collections::{HashMap, HashSet}; use crate::{Error, SEQUENCE}; -/// The Exif and XMP blocks found. -#[derive(Default)] -struct Embedded { - exif: Option>, - xmp: Option, -} +/// The `ftyp` brands of HEIF still images and image sequences, and of AVIF. +const IMAGE_BRANDS: [&[u8; 4]; 12] = [b"mif1", b"msf1", b"heic", b"heix", b"hevc", b"hevx", b"heim", b"heis", b"hevm", b"hevs", b"avif", b"avis"]; +/// Brands of other formats in the same container (Canon CR3, JPEG XL), which win when listed too. +const OTHER_BRANDS: [&[u8; 4]; 2] = [b"crx ", b"jxl "]; -/// The first `Exif` item's TIFF stream (without HEIF's offset header) and the first XMP packet of a -/// HEIF file, as [`crate::read_metadata`] returns them. An error when the file is not an ISO base -/// media still image ([`is_heif`]), or has no `meta` box (an image sequence); an item that can't be -/// located is left out rather than reported. -pub fn read(bytes: &[u8]) -> Result<(Option>, Option), Error> { - if !is_heif(bytes) { - return Err(Error::Malformed("not a HEIF file".into())); - } - let mut budget = MAX_BOXES; - if !boxes(bytes, 0, bytes.len(), &mut budget).iter().any(|b| &b.kind == b"meta") { - return Err(Error::Unsupported(SEQUENCE)); - } - let e = metadata(bytes); - Ok((e.exif, e.xmp)) -} - -/// At most this many boxes are walked in one file. -pub const MAX_BOXES: usize = 4096; - -/// Brands that declare a still image in the ISO base media container. -const IMAGE_BRANDS: [&[u8]; 12] = [b"heic", b"heix", b"hevc", b"hevx", b"heim", b"heis", b"hevm", b"hevs", b"mif1", b"msf1", b"avif", b"avis"]; - -/// Longest `ftyp` box this reads brands from. +/// How far into the `ftyp` box brands are looked for. pub const MAX_FTYP: usize = 4096; -/// Most items one file's `iinf` / `iloc` describes (an iPhone HEIC has a handful). -pub const MAX_ITEMS: usize = 1024; -/// Most extents one item's bytes are split into. -pub const MAX_EXTENTS: u16 = 1024; -/// Largest metadata item this returns; a real photo's Exif and XMP are a few hundred kilobytes. -pub const MAX_ITEM: usize = 32 << 20; +/// Boxes read in one file. An iPhone photo has about a hundred items, a large grid a few hundred. +pub const MAX_BOXES: usize = 1 << 16; +/// Metadata items [`read`] considers for the photo's own EXIF and XMP (a real file has one or two). +pub const MAX_CANDIDATES: usize = 64; +/// Metadata items [`scan`] returns; a file with more is not [`Scan::complete`]. +pub const MAX_SCANNED: usize = 1024; +/// The most bytes one metadata item may gather (EXIF and XMP are kilobytes). +pub const MAX_ITEM: usize = 16 << 20; +/// The most bytes [`scan`] gathers over all items. +pub const MAX_SCANNED_BYTES: usize = 64 << 20; -/// Does this file declare an ISO base media still image (HEIF / HEIC / AVIF)? +/// Does the `ftyp` box name a HEIF or AVIF brand (and not CR3 or JPEG XL)? pub fn is_heif(bytes: &[u8]) -> bool { if bytes.get(4..8) != Some(b"ftyp".as_slice()) { return false; } - let Some(size) = be32(bytes, 0).map(|v| v as usize) else { - return false; - }; - let end = size.min(bytes.len()).min(MAX_FTYP); - let brand = |at: usize| bytes.get(at..at.saturating_add(4)).is_some_and(|b| IMAGE_BRANDS.contains(&b)); - // the major brand, then (after the minor version) the compatible brands - brand(8) || (16..end).step_by(4).any(brand) + // major brand at 8, minor version at 12, compatible brands from 16 to the end of the box + let size = be32(bytes, 0).and_then(|s| usize::try_from(s).ok()).unwrap_or(0); + let end = size.clamp(12, MAX_FTYP).min(bytes.len()); + let compatible = (16..end).step_by(4).filter_map(|at| bytes.get(at..at.checked_add(4).filter(|&e| e <= end)?)); + let mut heif = false; + for brand in bytes.get(8..12).into_iter().chain(compatible) { + if OTHER_BRANDS.iter().any(|b| b.as_slice() == brand) { + return false; + } + heif |= IMAGE_BRANDS.iter().any(|b| b.as_slice() == brand); + } + heif } -/// The Exif and XMP blocks of a HEIF file. Anything malformed is left out rather than reported: -/// a file whose items can't be located simply has no metadata, as before this reader existed. -fn metadata(bytes: &[u8]) -> Embedded { - let mut out = Embedded::default(); - let mut budget = MAX_BOXES; - let Some(meta) = boxes(bytes, 0, bytes.len(), &mut budget).into_iter().find(|b| &b.kind == b"meta") else { - return out; +/// The photo's EXIF (its TIFF stream, see [`exif_tiff`]) and XMP packet, as +/// [`crate::read_metadata`] returns them: the primary image's items first, then those tied to no +/// image; the first that reads well wins. An error when the file is not HEIF ([`is_heif`]) or has +/// no `meta` box (an image sequence); an item that can't be read is left out rather than reported. +pub fn read(bytes: &[u8]) -> Result<(Option>, Option), Error> { + let c = Container::read(bytes, MAX_CANDIDATES).ok_or_else(not_heif)?; + if !c.has_meta { + return Err(Error::Unsupported(SEQUENCE)); + } + let ranked = |kind: Kind| { + let mut order: Vec<(u8, usize)> = + c.items.iter().enumerate().filter(|(_, it)| it.kind == kind).filter_map(|(i, it)| Some((it.rank(c.primary.is_some())?, i))).collect(); + order.sort_by_key(|&(rank, _)| rank); + order.into_iter().filter_map(|(_, i)| match c.gather(i, MAX_ITEM) { + Gathered::Bytes(b) => Some(b), + _ => None, + }) }; - // `meta` is a FullBox: a version and flags before its children - let (mut items, mut locs, mut idat) = (Vec::new(), Vec::new(), None); - for b in boxes(bytes, meta.body.saturating_add(4), meta.end, &mut budget) { - match &b.kind { - b"iinf" => items = item_infos(bytes, &b, &mut budget), - b"iloc" => locs = item_locations(bytes.get(b.body..b.end).unwrap_or_default()), - b"idat" => idat = bytes.get(b.body..b.end), - _ => {} + let exif = ranked(Kind::Exif).find_map(|item| exif_tiff(&item).map(<[u8]>::to_vec)); + let xmp = ranked(Kind::Xmp).next().map(|item| String::from_utf8_lossy(&item).trim_end_matches('\0').to_string()); + Ok((exif, xmp)) +} + +/// Every EXIF and XMP item of a HEIF file, whichever image it describes, in `iinf` order. An error +/// only when the file is not HEIF ([`is_heif`]); a file without a `meta` box has no items. +/// +/// The scan says when it may be missing something: [`Scan::complete`] is false when the item +/// catalog can't be read in full, and an item whose bytes can't be read comes back as +/// [`Unreadable`]. An item a complete `iloc` doesn't place is left out: it has no bytes. +pub fn scan(bytes: &[u8]) -> Result, Error> { + scan_within(bytes, MAX_SCANNED_BYTES) +} + +/// [`scan`], gathering at most `budget` bytes over all items. +fn scan_within(bytes: &[u8], budget: usize) -> Result, Error> { + let container = Container::read(bytes, MAX_SCANNED).ok_or_else(not_heif)?; + Ok(Scan { container, next: 0, budget }) +} + +fn not_heif() -> Error { + Error::Malformed("not a HEIF file".into()) +} + +/// The metadata items of a HEIF file, from [`scan`]: an iterator over [`Item`]s. +pub struct Scan<'a> { + container: Container<'a>, + next: usize, + /// Bytes still to gather, of [`MAX_SCANNED_BYTES`]. + budget: usize, +} + +impl Scan<'_> { + /// Whether the iterator returns every metadata item in the file: the boxes up to and through + /// the item catalog were read to their ends, there was one `meta` box with one `iinf`, every + /// catalog entry was understood, and there were at most [`MAX_SCANNED`] metadata items. A + /// complete file without a `meta` box is complete, with no items. + pub fn complete(&self) -> bool { + self.container.catalog_complete && !self.container.more + } +} + +impl Iterator for Scan<'_> { + type Item = Item; + + fn next(&mut self) -> Option { + loop { + let i = self.next; + let (id, kind) = self.container.items.get(i).map(|c| (c.id, c.kind))?; + self.next = i.saturating_add(1); + let data = match self.container.gather(i, MAX_ITEM.min(self.budget)) { + Gathered::Bytes(b) => { + self.budget = self.budget.saturating_sub(b.len()); + Ok(b) + } + Gathered::NotPlaced => continue, + Gathered::Unreadable => Err(Unreadable::Placement), + Gathered::TooLarge => Err(Unreadable::TooLarge), + }; + return Some(Item { id, kind, data }); } } - for (id, kind, content_type) in items { - let want_exif = &kind == b"Exif" && out.exif.is_none(); - let want_xmp = &kind == b"mime" && content_type == "application/rdf+xml" && out.xmp.is_none(); - if !want_exif && !want_xmp { - continue; - } - let Some(loc) = locs.iter().find(|l| l.id == id) else { continue }; - let Some(block) = item_bytes(bytes, idat, loc) else { continue }; - if want_exif { - // ISO/IEC 23008-12 A.2.1: a four-byte offset from the end of itself to the TIFF header - let skip = be32(&block, 0).and_then(|v| usize::try_from(v).ok()).and_then(|v| v.checked_add(4)); - out.exif = skip.and_then(|at| block.get(at..)).filter(|b| !b.is_empty()).map(<[u8]>::to_vec); +} + +/// One metadata item from [`scan`]. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Item { + /// Its item id. + pub id: u32, + pub kind: Kind, + /// Its bytes as stored (for EXIF, with the offset field: see [`exif_tiff`]), or why there are + /// none. + pub data: Result, Unreadable>, +} + +/// What a metadata item holds. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub enum Kind { + /// An `Exif` item. + Exif, + /// An XMP packet: a `mime` item of type `application/rdf+xml`. + Xmp, + /// An XMP packet with a content encoding (compressed). Its bytes are returned as stored; this + /// crate doesn't decode them. + EncodedXmp, +} + +/// Why a metadata item's bytes can't be read. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +#[non_exhaustive] +pub enum Unreadable { + /// `iloc` is missing or damaged before the item's entry, or the entry points outside the file + /// (or `idat`), into another file, or builds the item from other items (method 2). + Placement, + /// More than [`MAX_ITEM`] bytes, or more than [`scan`] has left of [`MAX_SCANNED_BYTES`]. + TooLarge, +} + +/// The TIFF stream of an `Exif` item: past its 4-byte offset field and the bytes that offset +/// skips. An item whose offset is wrong, or that has no offset field, is read too when an +/// `Exif\0\0` prefix or the TIFF header itself shows where the stream starts. `None` when no TIFF +/// header is found. +pub fn exif_tiff(item: &[u8]) -> Option<&[u8]> { + let tiff = |b: &&[u8]| b.starts_with(b"II*\0") || b.starts_with(b"MM\0*"); + let stated = be32(item, 0).and_then(|n| usize::try_from(n).ok()?.checked_add(4)).and_then(|at| item.get(at..)); + let after_field = item.get(4..).map(strip_exif_header); + [stated, after_field, Some(strip_exif_header(item))].into_iter().flatten().find(tiff) +} + +/// `b` without a leading `Exif\0` and the byte after it (the JPEG APP1 prefix), if it has one. +fn strip_exif_header(b: &[u8]) -> &[u8] { + match b.get(..5) { + Some(b"Exif\0") => b.get(6..).unwrap_or(b), + _ => b, + } +} + +/// A metadata item and the images it describes. +#[derive(Debug)] +struct Candidate { + id: u32, + kind: Kind, + /// Tied to some image by a `cdsc` reference. + describes: bool, + /// Tied to the primary image or an image it is made from. + describes_primary: bool, +} + +impl Candidate { + /// 0 for the photo's own, 1 for one tied to no image (or any, when the file names no primary + /// image that exists); `None` for one that describes other images only. + fn rank(&self, has_primary: bool) -> Option { + if self.describes_primary { + Some(0) + } else if !self.describes || !has_primary { + Some(1) } else { - out.xmp = Some(String::from_utf8_lossy(&block).trim_end_matches('\0').to_string()); + None } } - out } -/// `iinf` → one `(item_ID, item_type, content_type)` per `infe` entry. Entries of version 0 and 1 -/// name no item type and are skipped; HEIF files use version 2 or 3. -fn item_infos(bytes: &[u8], iinf: &BoxRef, budget: &mut usize) -> Vec<(u32, [u8; 4], String)> { - // FullBox version and flags, then a 16- or 32-bit entry count before the `infe` boxes - let version = *bytes.get(iinf.body).unwrap_or(&0); - let entries_at = iinf.body.saturating_add(if version == 0 { 6 } else { 8 }); - let mut out = Vec::new(); - for b in boxes(bytes, entries_at, iinf.end, budget) { - if &b.kind != b"infe" || out.len() >= MAX_ITEMS { - continue; +/// What the `meta` box says about the metadata items, and where their bytes are. +struct Container<'a> { + file: &'a [u8], + /// A top-level `meta` box was found. + has_meta: bool, + idat: Option<&'a [u8]>, + iloc: Option>, + /// The primary image, when `pitm` names an item `iinf` lists. + primary: Option, + /// The EXIF and XMP items, in `iinf` order (the first `cap` of them). + items: Vec, + /// More metadata items than `cap`. + more: bool, + /// Discovery read the whole item catalog, including each entry's type. + catalog_complete: bool, + /// Where each of `items` is (from one walk of `iloc`). + places: Vec>, + /// A complete `iloc` walk established that any unplaced item has no entry. + iloc_complete: bool, +} + +impl<'a> Container<'a> { + /// `None` when `bytes` is not HEIF; no items when there is no `meta` box. + fn read(bytes: &'a [u8], cap: usize) -> Option> { + if !is_heif(bytes) { + return None; } - let Some(e) = bytes.get(b.body..b.end) else { continue }; - let (id, kind_at) = match *e.first().unwrap_or(&0) { - 2 => (be16(e, 4).map(u32::from), 8), - 3 => (be32(e, 4), 10), + let mut c = Container { + file: bytes, + has_meta: false, + idat: None, + iloc: None, + primary: None, + items: Vec::new(), + more: false, + catalog_complete: false, + places: Vec::new(), + iloc_complete: false, + }; + let mut budget = MAX_BOXES; + let top = boxes(bytes, 0, bytes.len(), &mut budget); + c.catalog_complete = top.last().is_some_and(|b| b.end == bytes.len()); + // A complete file without an item `meta` has no item catalog (e.g. a sequence). + let Some(meta) = top.iter().find(|b| &b.kind == b"meta") else { return Some(c) }; + c.has_meta = true; + // `meta` is a full box: version and flags, then the boxes inside it. + let first = meta.body.saturating_add(4); + let inside = boxes(bytes, first, meta.end, &mut budget); + c.catalog_complete &= version(bytes, meta) == Some(0) + && first <= meta.end + && inside.last().map_or(first, |b| b.end) == meta.end + && top.iter().filter(|b| &b.kind == b"meta").count() == 1 + && inside.iter().filter(|b| &b.kind == b"iinf").count() == 1; + let child = |kind: &[u8; 4]| inside.iter().find(|b| &b.kind == kind); + let payload = |kind: &[u8; 4]| child(kind).and_then(|b| bytes.get(b.body..b.end)); + let mut ids = Vec::new(); + if let Some(iinf) = child(b"iinf") { + let catalog = item_infos(bytes, iinf, cap, &mut budget); + ids = catalog.ids; + c.items = catalog.items; + c.more = catalog.more; + c.catalog_complete &= catalog.complete; + } + c.primary = payload(b"pitm").and_then(primary_item).filter(|p| ids.binary_search(p).is_ok()); + if let Some(iref) = child(b"iref") { + link(bytes, iref, c.primary, &mut c.items, &mut budget); + } + c.idat = payload(b"idat"); + c.iloc = payload(b"iloc").and_then(Iloc::parse); + (c.places, c.iloc_complete) = match &c.iloc { + Some(iloc) => iloc.locate(&c.items), + None => (Vec::new(), false), + }; + Some(c) + } + + /// The bytes of `items[i]`, at most `limit` of them. + fn gather(&self, i: usize, limit: usize) -> Gathered { + match (&self.iloc, self.places.get(i)) { + (Some(iloc), Some(Some(place))) => iloc.gather(self.file, self.idat, place, limit), + _ if self.iloc_complete => Gathered::NotPlaced, + _ => Gathered::Unreadable, + } + } +} + +/// An item's bytes, or why there are none. +#[derive(Debug)] +enum Gathered { + Bytes(Vec), + /// A complete `iloc` walk found no entry for the item. + NotPlaced, + /// Placement unresolved, outside the data, in another file, or built from other items (method 2). + Unreadable, + /// More than the limit. + TooLarge, +} + +/// A full box's version: the first byte of its own payload (`None` for an empty box). +fn version(bytes: &[u8], b: &BoxRef) -> Option { + bytes.get(b.body..b.end)?.first().copied() +} + +/// `pitm`: the primary item's id (16 bits in version 0, else 32). +fn primary_item(pitm: &[u8]) -> Option { + match pitm.first()? { + 0 => be16(pitm, 4).map(u32::from), + _ => be32(pitm, 4), + } +} + +/// What `iinf` lists. Best-effort discovery is kept even when the catalog cannot establish that +/// all items were read. +#[derive(Default)] +struct ItemCatalog { + /// Every item id listed, sorted. + ids: Vec, + items: Vec, + more: bool, + complete: bool, +} + +/// `iinf` → its item ids and its metadata items (at most `cap`). The catalog is complete when the +/// table version is known, its count matches its entries, the entries fill the box, and each is +/// an `infe` this reader understands. +fn item_infos(bytes: &[u8], iinf: &BoxRef, cap: usize, budget: &mut usize) -> ItemCatalog { + let mut catalog = ItemCatalog::default(); + let Some(data) = bytes.get(iinf.body..iinf.end) else { return catalog }; + // Only the supported versions establish the count and where the entries start. + let (count, header) = match version(bytes, iinf) { + Some(0) => (be16(data, 4).map(u32::from), 6), + Some(1) => (be32(data, 4), 8), + _ => return catalog, + }; + let Some(count) = count else { return catalog }; + let first = iinf.body.saturating_add(header); + let entries = boxes(bytes, first, iinf.end, budget); + catalog.complete = entries.last().map_or(first, |b| b.end) == iinf.end && u32::try_from(entries.len()).ok() == Some(count); + for b in &entries { + let info = bytes.get(b.body..b.end).filter(|_| &b.kind == b"infe").and_then(item_info); + let Some((id, kind)) = info else { + catalog.complete = false; + continue; + }; + catalog.ids.push(id); + match kind { + Some(_) if catalog.items.len() >= cap => catalog.more = true, + Some(kind) => catalog.items.push(Candidate { id, kind, describes: false, describes_primary: false }), + None => {} + } + } + catalog.ids.sort_unstable(); + catalog.ids.dedup(); + catalog +} + +/// An `infe` entry's item id, and its kind when it is an unprotected `Exif` or XMP item (`mime`, +/// `application/rdf+xml`). `None` when the entry can't be read to its last field. +fn item_info(infe: &[u8]) -> Option<(u32, Option)> { + let version = *infe.first()?; + // version and flags, the item id (32 bits in version 3), the protection index + let (id, at) = match version { + 0..=2 => (u32::from(be16(infe, 4)?), 6usize), + 3 => (be32(infe, 4)?, 8usize), + _ => return None, + }; + if be16(infe, at)? != 0 { + return Some((id, None)); // protected (encrypted) + } + let at = at.checked_add(2)?; + // versions 0 and 1 have no item type and describe MIME items; 2 and 3 name the type + let (kind, at) = if version >= 2 { (infe.get(at..at.checked_add(4)?)?, at.checked_add(4)?) } else { (b"mime".as_slice(), at) }; + let (_name, at) = string(infe, at)?; + let kind = match kind { + b"Exif" => Some(Kind::Exif), + b"mime" => { + let (content_type, at) = string(infe, at)?; + // Content encoding may be absent, but a present string must terminate. + let encoding = if at == infe.len() { b"".as_slice() } else { string(infe, at)?.0 }; + match (content_type.trim_ascii().eq_ignore_ascii_case(b"application/rdf+xml"), encoding.trim_ascii().is_empty()) { + (true, true) => Some(Kind::Xmp), + (true, false) => Some(Kind::EncodedXmp), + (false, _) => None, + } + } + b"uri " => { + string(infe, at)?; + None + } + _ => None, + }; + Some((id, kind)) +} + +/// The NUL-terminated string at `at` and where the next field starts. +fn string(b: &[u8], at: usize) -> Option<(&[u8], usize)> { + let rest = b.get(at..)?; + let n = rest.iter().position(|&c| c == 0)?; + Some((rest.get(..n)?, at.checked_add(n)?.checked_add(1)?)) +} + +/// Mark the candidates that `cdsc` references tie to an image, and those tied to the primary image +/// or one it is made from (`dimg`, followed to any depth; each image once, so loops end). +fn link(bytes: &[u8], iref: &BoxRef, primary: Option, items: &mut [Candidate], budget: &mut usize) { + // full box; item ids are 16 bits in version 0, 32 in version 1 + let width = match version(bytes, iref) { + Some(0) => 2usize, + Some(1) => 4, + _ => return, + }; + let index: HashMap = items.iter().enumerate().rev().map(|(i, c)| (c.id, i)).collect(); + let mut inputs: HashMap> = HashMap::new(); + let mut described: Vec<(usize, Vec)> = Vec::new(); + for r in boxes(bytes, iref.body.saturating_add(4), iref.end, budget) { + let cdsc = match &r.kind { + b"cdsc" => true, + b"dimg" => false, _ => continue, }; - let (Some(id), Some(kind)) = (id, e.get(kind_at..kind_at + 4)) else { continue }; - let mut kind4 = [0u8; 4]; - kind4.copy_from_slice(kind); - // the item name, then (for a `mime` item) the content type, both NUL-terminated - let mut strings = e.get(kind_at + 4..).unwrap_or_default().split(|&c| c == 0).skip(1); - let content_type = String::from_utf8_lossy(strings.next().unwrap_or_default()).into_owned(); - out.push((id, kind4, content_type)); + let Some(body) = bytes.get(r.body..r.end) else { continue }; + let Some(from) = id_at(body, 0, width) else { continue }; + let item = index.get(&from).copied(); + if cdsc && item.is_none() { + continue; + } + let count = be16(body, width).unwrap_or(0); + let mut to = Vec::new(); + let mut at = width.saturating_add(2); + for _ in 0..count { + let Some(id) = id_at(body, at, width) else { break }; + to.push(id); + at = at.saturating_add(width); + } + match item { + Some(i) if cdsc => described.push((i, to)), + _ => inputs.entry(from).or_default().extend(to), + } + } + // the primary image and every image it is made from + let mut photo = HashSet::new(); + let mut todo: Vec = primary.into_iter().collect(); + while let Some(id) = todo.pop() { + if photo.insert(id) { + todo.extend(inputs.get(&id).into_iter().flatten().filter(|i| !photo.contains(*i))); + } + } + for (i, to) in described { + if let Some(item) = items.get_mut(i) + && !to.is_empty() + { + item.describes = true; + item.describes_primary |= to.iter().any(|t| photo.contains(t)); + } } - out } -/// Where one item's bytes are. -struct Loc { - id: u32, - /// 0 = offsets into the file, 1 = into the `idat` box, 2 = another item (not read). - construction: u8, +fn id_at(b: &[u8], at: usize, width: usize) -> Option { + if width == 2 { be16(b, at).map(u32::from) } else { be32(b, at) } +} + +/// `iloc`: its field sizes, read once. +struct Iloc<'a> { + data: &'a [u8], + version: u8, + offset_size: usize, + length_size: usize, + base_size: usize, + index_size: usize, +} + +/// Where an item is: how it is built, and its extents in `iloc`. +#[derive(Clone, Copy, Debug)] +struct Place { + method: u16, + data_reference: u16, base: u64, - /// `(offset, length)` per extent, in order. - extents: Vec<(u64, u64)>, + /// Where its first extent starts in `iloc`. + extents_at: usize, + extents: usize, } -/// `iloc` (payload after the box header) → one [`Loc`] per entry, stopping at the first -/// unreadable one. -fn item_locations(p: &[u8]) -> Vec { - let version = *p.first().unwrap_or(&0); - let (Some(sizes), Some(base_index)) = (p.get(4), p.get(5)) else { return Vec::new() }; - let (offset_size, length_size) = ((sizes >> 4) as usize, (sizes & 0xf) as usize); - let (base_size, index_size) = ((base_index >> 4) as usize, if version > 0 { (base_index & 0xf) as usize } else { 0 }); - let (count, mut at) = match version { - 0 | 1 => (be16(p, 6).map(usize::from), 8), - 2 => (be32(p, 6).and_then(|v| usize::try_from(v).ok()), 10), - _ => return Vec::new(), - }; - let mut out = Vec::new(); - for _ in 0..count.unwrap_or(0).min(MAX_ITEMS) { - let (id, after_id) = match version { - 2 => (be32(p, at), at + 4), - _ => (be16(p, at).map(u32::from), at + 2), - }; - // version 1 and 2 put the construction method in the low nibble of a reserved 16-bit field - let construction = if version == 0 { Some(0) } else { be16(p, after_id).map(|v| (v & 0xf) as u8) }; - let after_method = after_id + if version == 0 { 0 } else { 2 }; - // a data reference index of 0 means this file; an external reference has no bytes here - let external = be16(p, after_method).is_some_and(|v| v != 0); - let base = uint(p, after_method + 2, base_size); - let extent_at = after_method + 2 + base_size; - let (Some(id), Some(construction), Some(base), Some(extent_count)) = (id, construction, base, be16(p, extent_at)) else { - break; - }; - let stride = index_size + offset_size + length_size; - let mut extents = Vec::new(); - let mut e = extent_at + 2; - for _ in 0..extent_count.min(MAX_EXTENTS) { - let (Some(offset), Some(length)) = (uint(p, e + index_size, offset_size), uint(p, e + index_size + offset_size, length_size)) else { - return out; - }; - extents.push((offset, length)); - e += stride; +impl<'a> Iloc<'a> { + fn parse(data: &'a [u8]) -> Option> { + let version = *data.first()?; + if version > 2 { + return None; } - at = e; - if !external { - out.push(Loc { id, construction, base, extents }); + // version and flags, then four 4-bit field sizes: offset, length, base offset, extent index + let (sizes, more) = (*data.get(4)?, *data.get(5)?); + let (offset_size, length_size) = (usize::from(sizes >> 4), usize::from(sizes & 15)); + let base_size = usize::from(more >> 4); + let index_size = if version == 0 { 0 } else { usize::from(more & 15) }; // reserved in version 0 + if [offset_size, length_size, base_size, index_size].into_iter().any(|n| !matches!(n, 0 | 4 | 8)) { + return None; } + Some(Iloc { data, version, offset_size, length_size, base_size, index_size }) + } + + /// One walk over the entries: where each of `items` is (the first entry for an id wins). It + /// stops once all are placed, or where the entries stop making sense. The boolean is true + /// only if the walk exhausted the entries, so an absent placement is known to be absent. + fn locate(&self, items: &[Candidate]) -> (Vec>, bool) { + let mut places = vec![None; items.len()]; + if items.is_empty() { + return (places, false); + } + let wanted: HashMap = items.iter().enumerate().rev().map(|(i, c)| (c.id, i)).collect(); + let mut left = wanted.len(); + let complete = self.walk(|id, place| { + if let Some(&i) = wanted.get(&id) + && let Some(slot @ None) = places.get_mut(i) + { + *slot = Some(place); + left = left.saturating_sub(1); + } + left > 0 + }); + (places, complete.unwrap_or(false)) + } + + /// Call `f` with each entry's item id and place. `Some(true)` means every entry was read, + /// `Some(false)` means `f` stopped the walk, and `None` means an entry ran past the box. + fn walk(&self, mut f: impl FnMut(u32, Place) -> bool) -> Option { + let (version, data) = (self.version, self.data); + let id_size = if version == 2 { 4 } else { 2 }; + let (count, mut at) = if version == 2 { (be32(data, 6)?, 10usize) } else { (u32::from(be16(data, 6)?), 8usize) }; + let extent_size = self.index_size.checked_add(self.offset_size)?.checked_add(self.length_size)?; + // (every entry takes at least six bytes, so a count larger than the box ends at its end) + for _ in 0..count { + iloc_entry_visited(); + let id = uint(data, at, id_size)?; + at = at.checked_add(id_size)?; + let method = if version == 0 { + 0 + } else { + let m = be16(data, at)? & 15; + at = at.checked_add(2)?; + m + }; + let data_reference = be16(data, at)?; + let base = uint(data, at.checked_add(2)?, self.base_size)?; + at = at.checked_add(2)?.checked_add(self.base_size)?; + let extents = usize::from(be16(data, at)?); + at = at.checked_add(2)?; + let place = Place { method, data_reference, base, extents_at: at, extents }; + at = at.checked_add(extents.checked_mul(extent_size)?)?; + if at > data.len() { + return None; + } + if let Ok(id) = u32::try_from(id) + && !f(id, place) + { + return Some(false); + } + } + Some(true) + } + + /// An item's bytes, its extents in order from the file (construction method 0) or from the + /// `meta` box's `idat` (method 1), at most `limit` of them. + fn gather(&self, file: &[u8], idat: Option<&[u8]>, place: &Place, limit: usize) -> Gathered { + // data reference 0 is this file + let source = match (place.data_reference, place.method, idat) { + (0, 0, _) => file, + (0, 1, Some(idat)) => idat, + _ => return Gathered::Unreadable, + }; + let mut out = Vec::new(); + let mut at = place.extents_at; + for _ in 0..place.extents { + let Some((piece, next)) = self.extent(source, place.base, at) else { return Gathered::Unreadable }; + at = next; + if out.len().saturating_add(piece.len()) > limit { + return Gathered::TooLarge; + } + out.extend_from_slice(piece); + } + Gathered::Bytes(out) + } + + /// The extent at `at`: its bytes in `source` (a length of 0 runs to the end) and where the + /// next extent starts. + fn extent<'s>(&self, source: &'s [u8], base: u64, at: usize) -> Option<(&'s [u8], usize)> { + let at = at.checked_add(self.index_size)?; + let offset = uint(self.data, at, self.offset_size)?; + let at = at.checked_add(self.offset_size)?; + let length = uint(self.data, at, self.length_size)?; + let at = at.checked_add(self.length_size)?; + let rest = source.get(usize::try_from(base.checked_add(offset)?).ok()?..)?; + let piece = if length == 0 { rest } else { rest.get(..usize::try_from(length).ok()?)? }; + Some((piece, at)) } - out } -/// A big-endian unsigned integer of `size` bytes; `size` 0 is the value 0, and the item boxes -/// allow no other width than 4 or 8. +#[cfg(test)] +thread_local! { + /// `iloc` entries walked on this thread, for the tests that bound the work. + static ILOC_ENTRIES: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + +fn iloc_entry_visited() { + #[cfg(test)] + ILOC_ENTRIES.with(|n| n.set(n.get().saturating_add(1))); +} + +/// A big-endian unsigned field of `size` bytes (0 reads as 0). fn uint(b: &[u8], at: usize, size: usize) -> Option { match size { 0 => Some(0), + 2 => be16(b, at).map(u64::from), 4 => be32(b, at).map(u64::from), 8 => be64(b, at), _ => None, } } -/// An item's bytes, its extents concatenated. `None` when they don't fit the file (or the `idat` -/// box), when the item is built by referencing another one, or when it is implausibly large. -fn item_bytes(bytes: &[u8], idat: Option<&[u8]>, loc: &Loc) -> Option> { - let src = match loc.construction { - 0 => bytes, - 1 => idat?, - _ => return None, - }; - let mut out = Vec::new(); - for &(offset, length) in &loc.extents { - let at = loc.base.checked_add(offset)?; - let (start, end) = (usize::try_from(at).ok()?, usize::try_from(at.checked_add(length)?).ok()?); - let extent = src.get(start..end)?; - if out.len().checked_add(extent.len())? > MAX_ITEM { - return None; - } - out.extend_from_slice(extent); - } - (!out.is_empty()).then_some(out) -} - -/// A box: its type and where its payload ends. +/// A box: its type, where its payload starts and where it ends. struct BoxRef { kind: [u8; 4], /// Start of the payload (after the header and, for `uuid`, the 16-byte uuid). @@ -225,33 +654,33 @@ struct BoxRef { end: usize, } -/// The boxes directly inside `[from, to)`; stops at the first malformed header. +/// The boxes directly inside `[from, to)`, at most `budget` of them (shared over the calls of one +/// read); stops at the first malformed header. fn boxes(bytes: &[u8], from: usize, to: usize, budget: &mut usize) -> Vec { let mut out = Vec::new(); - let mut at = from; let to = to.min(bytes.len()); - while at.saturating_add(8) <= to && *budget > 0 { - *budget -= 1; - let (Some(size), Some(kind)) = (be32(bytes, at), bytes.get(at + 4..at + 8)) else { break }; - let mut kind4 = [0u8; 4]; - kind4.copy_from_slice(kind); - let (len, mut hdr) = match size { - 0 => (to - at, 8), - 1 => match be64(bytes, at + 8).and_then(|v| usize::try_from(v).ok()) { - Some(l) => (l, 16), + let mut at = from; + while *budget > 0 { + let Some(header_end) = at.checked_add(8).filter(|&e| e <= to) else { break }; + *budget = budget.saturating_sub(1); + let (Some(size), Some(kind)) = (be32(bytes, at), bytes.get(at.saturating_add(4)..header_end)) else { break }; + let Ok(kind) = <[u8; 4]>::try_from(kind) else { break }; + let (len, header) = match size { + 0 => (to.saturating_sub(at), 8usize), + 1 => match be64(bytes, header_end).and_then(|v| usize::try_from(v).ok()) { + Some(len) => (len, 16), None => break, }, - n => (n as usize, 8), + n => match usize::try_from(n) { + Ok(len) => (len, 8), + Err(_) => break, + }, }; - let Some(end) = at.checked_add(len).filter(|&e| e <= to && len >= hdr) else { break }; - if &kind4 == b"uuid" { - // the 16-byte extended type is part of the header - if at + hdr + 16 > end { - break; - } - hdr += 16; - } - out.push(BoxRef { kind: kind4, body: at + hdr, end }); + // the 16-byte extended type of a `uuid` box is part of its header + let header = if &kind == b"uuid" { header.saturating_add(16) } else { header }; + let Some(end) = at.checked_add(len).filter(|&e| e <= to && len >= header) else { break }; + let Some(body) = at.checked_add(header) else { break }; + out.push(BoxRef { kind, body, end }); at = end; } out @@ -259,231 +688,18 @@ fn boxes(bytes: &[u8], from: usize, to: usize, budget: &mut usize) -> Vec Option { - b.get(at..at.checked_add(2)?).map(|s| u16::from_be_bytes([s[0], s[1]])) + b.get(at..at.checked_add(2)?)?.try_into().ok().map(u16::from_be_bytes) } + /// A big-endian `u32` at `at`, or `None` when the buffer is shorter than that. fn be32(b: &[u8], at: usize) -> Option { - b.get(at..at.checked_add(4)?).map(|s| u32::from_be_bytes([s[0], s[1], s[2], s[3]])) + b.get(at..at.checked_add(4)?)?.try_into().ok().map(u32::from_be_bytes) } + /// A big-endian `u64` at `at`, or `None` when the buffer is shorter than that. fn be64(b: &[u8], at: usize) -> Option { - let s = b.get(at..at.checked_add(8)?)?; - let mut a = [0u8; 8]; - a.copy_from_slice(s); - Some(u64::from_be_bytes(a)) + b.get(at..at.checked_add(8)?)?.try_into().ok().map(u64::from_be_bytes) } #[cfg(test)] -mod tests { - use super::*; - - /// One box: its own size, its four-letter kind, then its payload. - fn bx(kind: &[u8; 4], payload: &[u8]) -> Vec { - let mut v = ((payload.len() + 8) as u32).to_be_bytes().to_vec(); - v.extend_from_slice(kind); - v.extend_from_slice(payload); - v - } - - /// A FullBox: a box whose payload begins with a version byte and three flag bytes. - fn full_box(kind: &[u8; 4], version: u8, payload: &[u8]) -> Vec { - bx(kind, &[&[version, 0, 0, 0][..], payload].concat()) - } - - struct Item<'a> { - kind: &'a [u8; 4], - content_type: &'a str, - data: Vec, - } - - /// A HEIC-shaped file holding `items`: `ftyp`, a `meta` box with one `infe` per item, and the - /// item bytes in `idat` (`in_idat`, construction method 1) or in `mdat` (method 0). - fn heic(items: &[Item<'_>], iloc_version: u8, in_idat: bool) -> Vec { - let mut iinf = (items.len() as u16).to_be_bytes().to_vec(); - for (i, it) in items.iter().enumerate() { - let mut e = vec![2u8, 0, 0, 0]; // version 2, flags - e.extend_from_slice(&(i as u16 + 1).to_be_bytes()); - e.extend_from_slice(&[0, 0]); // protection index - e.extend_from_slice(it.kind); - e.extend_from_slice(b"an item\0"); - if it.kind == b"mime" { - e.extend_from_slice(it.content_type.as_bytes()); - e.push(0); - } - iinf.extend_from_slice(&bx(b"infe", &e)); - } - let iinf = full_box(b"iinf", 0, &iinf); - let payload: Vec = items.iter().flat_map(|i| i.data.iter().copied()).collect(); - let idat = if in_idat { bx(b"idat", &payload) } else { Vec::new() }; - let iloc = |base: u32| { - // four-byte offsets and lengths, no base offset and no extent index - let mut l = vec![0x44, 0x00]; - match iloc_version { - 2 => l.extend_from_slice(&(items.len() as u32).to_be_bytes()), - _ => l.extend_from_slice(&(items.len() as u16).to_be_bytes()), - } - let mut at = base; - for (i, it) in items.iter().enumerate() { - match iloc_version { - 2 => l.extend_from_slice(&(i as u32 + 1).to_be_bytes()), - _ => l.extend_from_slice(&(i as u16 + 1).to_be_bytes()), - } - if iloc_version > 0 { - l.extend_from_slice(&[0, u8::from(in_idat)]); // construction method - } - l.extend_from_slice(&[0, 0]); // data reference index: this file - l.extend_from_slice(&[0, 1]); // one extent - l.extend_from_slice(&at.to_be_bytes()); - l.extend_from_slice(&(it.data.len() as u32).to_be_bytes()); - at += it.data.len() as u32; - } - full_box(b"iloc", iloc_version, &l) - }; - let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); - let meta = |base| full_box(b"meta", 0, &[iloc(base), iinf.clone(), idat.clone()].concat()); - if in_idat { - return [ftyp, meta(0)].concat(); - } - let base = (ftyp.len() + meta(0).len() + 8) as u32; - [ftyp, meta(base), bx(b"mdat", &payload)].concat() - } - - const TIFF: &[u8] = b"MM\0\x2a\0\0\0\x08\0\0\0\0\0\0"; - - /// An `Exif` item's payload: the offset from the end of this field to the TIFF header, then - /// `skip` bytes of padding, then the TIFF stream. - fn exif_item(tiff: &[u8], skip: usize) -> Vec { - [&(skip as u32).to_be_bytes()[..], &vec![0u8; skip], tiff].concat() - } - - fn exif_only(tiff: &[u8]) -> Vec> { - vec![Item { kind: b"Exif", content_type: "", data: exif_item(tiff, 0) }] - } - - /// Every item location box the format allows: counts and ids are 16-bit before version 2 and - /// 32-bit in it, and the bytes live in `mdat` or in `idat` next to the location box itself. - #[test] - fn items_are_located_in_every_iloc_version() { - for (version, in_idat) in [(0, false), (1, false), (1, true), (2, false), (2, true)] { - let file = heic(&exif_only(TIFF), version, in_idat); - assert_eq!(read(&file).unwrap(), (Some(TIFF.to_vec()), None), "iloc v{version}, idat {in_idat}"); - } - } - - /// The XMP packet is the `mime` item that declares `application/rdf+xml`, not any other one. - #[test] - fn the_xmp_packet_is_the_rdf_mime_item() { - let items = vec![ - Item { kind: b"mime", content_type: "text/plain", data: b"not the packet".to_vec() }, - Item { kind: b"mime", content_type: "application/rdf+xml", data: b"\0".to_vec() }, - Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 0) }, - ]; - assert_eq!(read(&heic(&items, 1, false)).unwrap(), (Some(TIFF.to_vec()), Some("".into()))); - } - - /// The `Exif` item's leading offset may point past padding, not only straight at the TIFF header. - #[test] - fn the_exif_items_tiff_header_offset_is_honoured() { - let items = vec![Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 6) }]; - assert_eq!(read(&heic(&items, 1, false)).unwrap().0.as_deref(), Some(TIFF)); - } - - /// Which `ftyp` brands count as a still image in this container, major or compatible. - #[test] - fn brands() { - for brand in ["heic", "heix", "mif1", "avif", "hevc", "msf1"] { - let file = bx(b"ftyp", format!("{brand}\0\0\0\0mif1").as_bytes()); - assert!(is_heif(&file), "{brand}"); - } - assert!(is_heif(&bx(b"ftyp", b"mp41\0\0\0\0isomheic"))); - assert!(!is_heif(&bx(b"ftyp", b"crx \0\0\0\0crx isom"))); - assert!(!is_heif(&bx(b"ftyp", b"jxl \0\0\0\0jxl "))); - assert!(!is_heif(b"\xff\xd8\xff\xe1 a jpeg")); - assert!(!is_heif(b"")); - // a compatible brand past MAX_FTYP bytes is not read - let mut long = b"mp41\0\0\0\0".to_vec(); - long.resize(MAX_FTYP, b'x'); - long.extend_from_slice(b"heic"); - assert!(!is_heif(&bx(b"ftyp", &long))); - } - - /// Not a HEIF file, an image sequence (no `meta`), garbage: errors as the decoder reports them. - #[test] - fn what_is_not_a_still_image_is_an_error() { - assert!(matches!(read(b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"), Err(Error::Unsupported(m)) if m.contains("sequence"))); - for bytes in [&b""[..], b"\0\0\0\x18ftypheic\0\0\0\0mif1heic", &[0xFF; 64]] { - assert!(read(bytes).is_err()); - } - } - - /// A truncated or scrambled file never panics, and lies about sizes find nothing. - #[test] - fn broken_files_never_panic() { - let good = heic( - &[ - Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 0) }, - Item { kind: b"mime", content_type: "application/rdf+xml", data: b"".to_vec() }, - ], - 1, - false, - ); - for cut in 0..good.len() { - let _ = read(&good[..cut]); - } - for at in 0..good.len() { - let mut bad = good.clone(); - bad[at] ^= 0xff; - let _ = read(&bad); - } - let mut lying = good.clone(); - if let Some(at) = lying.windows(4).position(|w| w == b"iloc") { - lying.splice(at + 8..at + 12, u32::MAX.to_be_bytes()); - } - assert_eq!(read(&lying).unwrap().0, None); - } - - /// Past MAX_ITEMS `infe` entries the rest are not read; an item larger than MAX_ITEM is left out. - #[test] - fn item_limits() { - let mut items: Vec> = (0..MAX_ITEMS).map(|_| Item { kind: b"mime", content_type: "text/plain", data: vec![b'x'] }).collect(); - items.push(Item { kind: b"Exif", content_type: "", data: exif_item(TIFF, 0) }); - assert_eq!(read(&heic(&items, 2, false)).unwrap().0, None, "the Exif item is entry {}", MAX_ITEMS + 1); - items.remove(0); - assert_eq!(read(&heic(&items, 2, false)).unwrap().0.as_deref(), Some(TIFF)); - let big = vec![Item { kind: b"Exif", content_type: "", data: exif_item(&vec![0; MAX_ITEM], 0) }]; - assert_eq!(read(&heic(&big, 1, true)).unwrap().0, None); - } - - /// The box walk stops after MAX_BOXES boxes: a `meta` box after that many is not found. - #[test] - fn box_limit() { - let mut file = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); - for _ in 0..MAX_BOXES { - file.extend(bx(b"free", &[])); - } - file.extend(heic(&exif_only(TIFF), 1, true).split_off(bx(b"ftyp", b"heic\0\0\0\0mif1heic").len())); - assert!(matches!(read(&file), Err(Error::Unsupported(_)))); - } - - /// The container writer of this crate's tests: the reader agrees with the layout an encoder writes. - #[test] - fn a_synthetic_heif_file_carries_its_exif() { - let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); - spec.exif = Some(TIFF.to_vec()); - assert_eq!(read(&crate::testdata::build(&spec)).unwrap(), (Some(TIFF.to_vec()), None)); - assert_eq!(read(&crate::testdata::build(&crate::testdata::Spec::new(16, 16, &|_, _| [0; 3]))).unwrap(), (None, None)); - } - - /// With the decoder built too, both readers give the same answer on files with one Exif item. - #[cfg(feature = "decode")] - #[test] - fn agrees_with_the_decoders_read_metadata() { - let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); - spec.exif = Some(TIFF.to_vec()); - for file in [crate::testdata::build(&spec), crate::testdata::build(&crate::testdata::Spec::new(8, 8, &|_, _| [0; 3]))] { - assert_eq!(read(&file), crate::read_metadata(&file)); - } - let sequence = b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"; - assert_eq!(read(sequence), crate::read_metadata(sequence)); - } -} +mod tests; diff --git a/crates/heif/src/items/tests.rs b/crates/heif/src/items/tests.rs new file mode 100644 index 000000000..49cc9d789 --- /dev/null +++ b/crates/heif/src/items/tests.rs @@ -0,0 +1,1173 @@ +#![allow(clippy::arithmetic_side_effects)] + +use super::*; + +/// One box: its own size, its four-letter kind, then its payload. +fn bx(kind: &[u8; 4], payload: &[u8]) -> Vec { + let mut v = ((payload.len() + 8) as u32).to_be_bytes().to_vec(); + v.extend_from_slice(kind); + v.extend_from_slice(payload); + v +} + +/// A FullBox: a box whose payload begins with a version byte and three flag bytes. +fn full_box(kind: &[u8; 4], version: u8, payload: &[u8]) -> Vec { + bx(kind, &[&[version, 0, 0, 0][..], payload].concat()) +} + +/// A big-endian field of `size` bytes. +fn put(v: &mut Vec, x: u64, size: u8) { + match size { + 0 => assert_eq!(x, 0, "a value needs a field"), + 2 => v.extend_from_slice(&(x as u16).to_be_bytes()), + 4 => v.extend_from_slice(&(x as u32).to_be_bytes()), + 8 => v.extend_from_slice(&x.to_be_bytes()), + _ => panic!("no {size}-byte fields"), + } +} + +const TIFF: &[u8] = b"MM\0\x2a\0\0\0\x08\0\0\0\0\0\0"; + +/// The 100-byte EXIF of LightCraft's issue sweep `synthetic-metadata.heic`: Make "Synthetic", +/// Model "Issue sweep camera", DateTime 2026:10:12 12:34:56, big-endian. +const SWEEP_TIFF: [u8; 100] = [ + 0x4d, 0x4d, 0x00, 0x2a, 0x00, 0x00, 0x00, 0x08, 0x00, 0x03, 0x01, 0x0f, 0x00, 0x02, 0x00, 0x00, 0x00, 0x0a, 0x00, 0x00, // + 0x00, 0x32, 0x01, 0x10, 0x00, 0x02, 0x00, 0x00, 0x00, 0x13, 0x00, 0x00, 0x00, 0x3c, 0x01, 0x32, 0x00, 0x02, 0x00, 0x00, // + 0x00, 0x14, 0x00, 0x00, 0x00, 0x50, 0x00, 0x00, 0x00, 0x00, 0x53, 0x79, 0x6e, 0x74, 0x68, 0x65, 0x74, 0x69, 0x63, 0x00, // + 0x49, 0x73, 0x73, 0x75, 0x65, 0x20, 0x73, 0x77, 0x65, 0x65, 0x70, 0x20, 0x63, 0x61, 0x6d, 0x65, 0x72, 0x61, 0x00, 0x00, // + 0x32, 0x30, 0x32, 0x36, 0x3a, 0x31, 0x30, 0x3a, 0x31, 0x32, 0x20, 0x31, 0x32, 0x3a, 0x33, 0x34, 0x3a, 0x35, 0x36, 0x00, +]; + +/// A TIFF stream as far as this reader looks: a big-endian TIFF header, then `marker`. +fn tiff_with(marker: &str) -> Vec { + [b"MM\0*\0\0\0\x08".as_slice(), marker.as_bytes()].concat() +} + +/// An XMP packet holding `title`. +fn xmp_with(title: &str) -> String { + format!("{title}") +} + +/// An EXIF item as HEIF stores it: the 4-byte offset, `skip` (which the offset jumps), the TIFF. +fn exif_item(skip: &[u8], tiff: &[u8]) -> Vec { + [&(skip.len() as u32).to_be_bytes()[..], skip, tiff].concat() +} + +/// The photo's EXIF, as [`read`] gives it. +fn exif(f: &[u8]) -> Option> { + read(f).ok()?.0 +} + +/// The photo's XMP packet, as [`read`] gives it. +fn xmp(f: &[u8]) -> Option { + read(f).ok()?.1 +} + +/// Every metadata item [`scan`] finds, when it is sure it saw them all: `None` when the catalog +/// is incomplete or an item can't be read. +fn sure(f: &[u8]) -> Option)>> { + let s = scan(f).ok()?; + if !s.complete() { + return None; + } + s.map(|it| it.data.ok().map(|d| (it.id, it.kind, d))).collect() +} + +// -- The single-`meta` builder of the first version of this reader -------------------------------- + +struct Entry<'a> { + kind: &'a [u8; 4], + content_type: &'a str, + data: Vec, +} + +/// A HEIC-shaped file holding `items`: `ftyp`, a `meta` box with one `infe` per item, and the +/// item bytes in `idat` (`in_idat`, construction method 1) or in `mdat` (method 0). No `pitm` and +/// no `iref`: every item describes the file. +fn heic(items: &[Entry<'_>], iloc_version: u8, in_idat: bool) -> Vec { + let mut iinf = (items.len() as u16).to_be_bytes().to_vec(); + for (i, it) in items.iter().enumerate() { + let mut e = vec![2u8, 0, 0, 0]; // version 2, flags + e.extend_from_slice(&(i as u16 + 1).to_be_bytes()); + e.extend_from_slice(&[0, 0]); // protection index + e.extend_from_slice(it.kind); + e.extend_from_slice(b"an item\0"); + if it.kind == b"mime" { + e.extend_from_slice(it.content_type.as_bytes()); + e.push(0); + } + iinf.extend_from_slice(&bx(b"infe", &e)); + } + let iinf = full_box(b"iinf", 0, &iinf); + let payload: Vec = items.iter().flat_map(|i| i.data.iter().copied()).collect(); + let idat = if in_idat { bx(b"idat", &payload) } else { Vec::new() }; + let iloc = |base: u32| { + // four-byte offsets and lengths, no base offset and no extent index + let mut l = vec![0x44, 0x00]; + match iloc_version { + 2 => l.extend_from_slice(&(items.len() as u32).to_be_bytes()), + _ => l.extend_from_slice(&(items.len() as u16).to_be_bytes()), + } + let mut at = base; + for (i, it) in items.iter().enumerate() { + match iloc_version { + 2 => l.extend_from_slice(&(i as u32 + 1).to_be_bytes()), + _ => l.extend_from_slice(&(i as u16 + 1).to_be_bytes()), + } + if iloc_version > 0 { + l.extend_from_slice(&[0, u8::from(in_idat)]); // construction method + } + l.extend_from_slice(&[0, 0]); // data reference index: this file + l.extend_from_slice(&[0, 1]); // one extent + l.extend_from_slice(&at.to_be_bytes()); + l.extend_from_slice(&(it.data.len() as u32).to_be_bytes()); + at += it.data.len() as u32; + } + full_box(b"iloc", iloc_version, &l) + }; + let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + let meta = |base| full_box(b"meta", 0, &[iloc(base), iinf.clone(), idat.clone()].concat()); + if in_idat { + return [ftyp, meta(0)].concat(); + } + let base = (ftyp.len() + meta(0).len() + 8) as u32; + [ftyp, meta(base), bx(b"mdat", &payload)].concat() +} + +/// An `Exif` item's payload: the offset from the end of this field to the TIFF header, then +/// `skip` bytes of padding, then the TIFF stream. +fn exif_padded(tiff: &[u8], skip: usize) -> Vec { + [&(skip as u32).to_be_bytes()[..], &vec![0u8; skip], tiff].concat() +} + +fn exif_only(tiff: &[u8]) -> Vec> { + vec![Entry { kind: b"Exif", content_type: "", data: exif_padded(tiff, 0) }] +} + +/// Every item location box the format allows: counts and ids are 16-bit before version 2 and +/// 32-bit in it, and the bytes live in `mdat` or in `idat` next to the location box itself. +#[test] +fn items_are_located_in_every_iloc_version() { + for (version, in_idat) in [(0, false), (1, false), (1, true), (2, false), (2, true)] { + let file = heic(&exif_only(TIFF), version, in_idat); + assert_eq!(read(&file).unwrap(), (Some(TIFF.to_vec()), None), "iloc v{version}, idat {in_idat}"); + } +} + +/// The XMP packet is the `mime` item that declares `application/rdf+xml`, not any other one. +#[test] +fn the_xmp_packet_is_the_rdf_mime_item() { + let items = vec![ + Entry { kind: b"mime", content_type: "text/plain", data: b"not the packet".to_vec() }, + Entry { kind: b"mime", content_type: "application/rdf+xml", data: b"\0".to_vec() }, + Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }, + ]; + assert_eq!(read(&heic(&items, 1, false)).unwrap(), (Some(TIFF.to_vec()), Some("".into()))); +} + +/// The `Exif` item's leading offset may point past padding, not only straight at the TIFF header. +#[test] +fn the_exif_items_tiff_header_offset_is_honoured() { + let items = vec![Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 6) }]; + assert_eq!(read(&heic(&items, 1, false)).unwrap().0.as_deref(), Some(TIFF)); +} + +/// Which `ftyp` brands count as a still image in this container, major or compatible. +#[test] +fn brands() { + for brand in ["heic", "heix", "mif1", "avif", "hevc", "msf1"] { + let file = bx(b"ftyp", format!("{brand}\0\0\0\0mif1").as_bytes()); + assert!(is_heif(&file), "{brand}"); + } + assert!(is_heif(&bx(b"ftyp", b"mp41\0\0\0\0isomheic"))); + assert!(!is_heif(&bx(b"ftyp", b"crx \0\0\0\0crx isom"))); + assert!(!is_heif(&bx(b"ftyp", b"jxl \0\0\0\0jxl "))); + assert!(!is_heif(b"\xff\xd8\xff\xe1 a jpeg")); + assert!(!is_heif(b"")); + // a compatible brand past MAX_FTYP bytes is not read + let mut long = b"mp41\0\0\0\0".to_vec(); + long.resize(MAX_FTYP, b'x'); + long.extend_from_slice(b"heic"); + assert!(!is_heif(&bx(b"ftyp", &long))); +} + +/// Not a HEIF file, an image sequence (no `meta`), garbage: errors as the decoder reports them. +#[test] +fn what_is_not_a_still_image_is_an_error() { + assert!(matches!(read(b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"), Err(Error::Unsupported(m)) if m.contains("sequence"))); + for bytes in [&b""[..], b"\0\0\0\x18ftypheic\0\0\0\0mif1heic", &[0xFF; 64]] { + assert!(read(bytes).is_err()); + } + assert!(scan(&[0xFF; 64]).is_err(), "only a file that isn't HEIF is an error to scan"); +} + +/// A truncated or scrambled file never panics, and lies about sizes find nothing. +#[test] +fn broken_files_never_panic() { + let good = heic( + &[ + Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }, + Entry { kind: b"mime", content_type: "application/rdf+xml", data: b"".to_vec() }, + ], + 1, + false, + ); + for cut in 0..good.len() { + let _ = read(&good[..cut]); + let _ = scan(&good[..cut]).map(Iterator::count); + } + for at in 0..good.len() { + let mut bad = good.clone(); + bad[at] ^= 0xff; + let _ = read(&bad); + let _ = scan(&bad).map(Iterator::count); + } + let mut lying = good.clone(); + if let Some(at) = lying.windows(4).position(|w| w == b"iloc") { + lying.splice(at + 8..at + 12, u32::MAX.to_be_bytes()); + } + assert_eq!(read(&lying).unwrap().0, None); + assert_eq!(sure(&lying), None, "an item `iloc` can't place is unreadable, not absent"); +} + +/// [`read`] considers the first MAX_CANDIDATES metadata items; an item larger than MAX_ITEM is +/// left out by [`read`] and too large for [`scan`]. +#[test] +fn item_limits() { + let mut items: Vec> = + (0..MAX_CANDIDATES).map(|_| Entry { kind: b"Exif", content_type: "", data: exif_padded(b"not TIFF", 0) }).collect(); + items.push(Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }); + assert_eq!(read(&heic(&items, 2, false)).unwrap().0, None, "the TIFF is metadata item {}", MAX_CANDIDATES + 1); + items.remove(0); + assert_eq!(read(&heic(&items, 2, false)).unwrap().0.as_deref(), Some(TIFF)); + let big = heic(&[Entry { kind: b"Exif", content_type: "", data: exif_padded(&vec![0; MAX_ITEM], 0) }], 1, true); + assert_eq!(read(&big).unwrap().0, None); + let found: Vec = scan(&big).unwrap().collect(); + assert_eq!(found, [Item { id: 1, kind: Kind::Exif, data: Err(Unreadable::TooLarge) }]); +} + +/// The scan gathers at most its byte budget over all items; past it an item is too large. +#[test] +fn the_scan_byte_budget() { + let items = [ + Entry { kind: b"Exif", content_type: "", data: exif_padded(TIFF, 0) }, + Entry { kind: b"mime", content_type: "application/rdf+xml", data: b"".to_vec() }, + ]; + let f = heic(&items, 1, true); + let first = TIFF.len() + 4; + let found: Vec = scan_within(&f, first + 5).unwrap().collect(); + assert_eq!(found[0].data.as_deref().map(<[u8]>::len), Ok(first)); + assert_eq!(found[1].data, Err(Unreadable::TooLarge)); + let found: Vec = scan_within(&f, first + 12).unwrap().collect(); + assert_eq!(found[1].data.as_deref(), Ok(b"".as_slice())); +} + +/// The box walk stops after MAX_BOXES boxes: a `meta` box after that many is not found. +#[test] +fn box_limit() { + let mut file = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + for _ in 0..MAX_BOXES { + file.extend(bx(b"free", &[])); + } + file.extend(heic(&exif_only(TIFF), 1, true).split_off(bx(b"ftyp", b"heic\0\0\0\0mif1heic").len())); + assert!(matches!(read(&file), Err(Error::Unsupported(_)))); + assert!(!scan(&file).unwrap().complete()); +} + +/// The container writer of this crate's tests: the reader agrees with the layout an encoder writes. +#[test] +fn a_synthetic_heif_file_carries_its_exif() { + let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); + spec.exif = Some(TIFF.to_vec()); + let file = crate::testdata::build(&spec); + assert_eq!(read(&file).unwrap(), (Some(TIFF.to_vec()), None)); + let mut exif = 0u32.to_be_bytes().to_vec(); + exif.extend_from_slice(TIFF); + assert!(matches!(sure(&file).as_deref(), Some([(_, Kind::Exif, data)]) if *data == exif)); + assert_eq!(read(&crate::testdata::build(&crate::testdata::Spec::new(16, 16, &|_, _| [0; 3]))).unwrap(), (None, None)); +} + +/// With the decoder built too, both readers give the same answer, also on files with a +/// thumbnail and with several items. +#[cfg(feature = "decode")] +#[test] +fn agrees_with_the_decoders_read_metadata() { + let mut spec = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); + spec.exif = Some(TIFF.to_vec()); + let mut thumbnailed = crate::testdata::Spec::new(16, 16, &|x, _| [x as u16 * 4, 0, 0]); + thumbnailed.exif = Some(TIFF.to_vec()); + thumbnailed.thumbnail = Some(&|_, y| [y as u16 * 4, 0, 0]); + let files = [ + crate::testdata::build(&spec), + crate::testdata::build(&thumbnailed), + crate::testdata::build(&crate::testdata::Spec::new(8, 8, &|_, _| [0; 3])), + ]; + for file in files { + assert_eq!(read(&file), crate::read_metadata(&file)); + } + let sequence = b"\0\0\0\x18ftypmsf1\0\0\0\0msf1hevc"; + assert_eq!(read(sequence), crate::read_metadata(sequence)); +} + +// -- A builder with a primary image, references and every `iloc` layout ---------------------------- + +#[derive(Clone, Copy, PartialEq)] +enum Store { + File, + Idat, +} + +struct Part { + id: u32, + kind: &'static [u8; 4], + /// `mime` items: content type and content encoding. + mime: (&'static str, &'static str), + data: Vec, + store: Store, + /// Extents the data is split into. + extents: usize, +} + +/// A HEIF file for the tests: `ftyp`, `meta` (`hdlr`, `pitm`, `iinf`, `iref`, `iloc`, `idat`) +/// and `mdat`. +struct Heif { + ftyp: Vec, + primary: u32, + items: Vec, + /// `iref` references: type, from, to. + refs: Vec<(&'static [u8; 4], u32, Vec)>, + /// `iloc` version and its offset, length, base-offset and index field sizes. + iloc: (u8, [u8; 4]), + /// 32-bit item ids: `infe` version 3, `pitm` and `iref` version 1 (`iloc` must be version 2). + wide: bool, +} + +impl Heif { + /// A primary HEVC picture, item 1 (its bytes don't matter here). + fn new() -> Heif { + let picture = Part { id: 1, kind: b"hvc1", mime: ("", ""), data: b"coded picture".to_vec(), store: Store::File, extents: 1 }; + Heif { ftyp: b"heic\0\0\0\0mif1heic".to_vec(), primary: 1, items: vec![picture], refs: Vec::new(), iloc: (1, [4, 4, 0, 0]), wide: false } + } + + fn item(mut self, id: u32, kind: &'static [u8; 4], data: Vec, store: Store, extents: usize) -> Heif { + self.items.push(Part { id, kind, mime: ("", ""), data, store, extents }); + self + } + + fn xmp(mut self, id: u32, mime: (&'static str, &'static str), data: Vec) -> Heif { + self.items.push(Part { id, kind: b"mime", mime, data, store: Store::File, extents: 1 }); + self + } + + fn cdsc(self, from: u32, to: &[u32]) -> Heif { + self.iref(b"cdsc", from, to) + } + + fn iref(mut self, kind: &'static [u8; 4], from: u32, to: &[u32]) -> Heif { + self.refs.push((kind, from, to.to_vec())); + self + } + + fn meta(&self, mdat_at: usize) -> Vec { + let id = |v: &mut Vec, id: u32| put(v, u64::from(id), if self.wide { 4 } else { 2 }); + let mut hdlr = vec![0u8; 4]; + hdlr.extend_from_slice(b"pict"); + hdlr.extend_from_slice(&[0; 13]); + let mut pitm = Vec::new(); + id(&mut pitm, self.primary); + let mut iinf = Vec::new(); + put(&mut iinf, self.items.len() as u64, if self.wide { 4 } else { 2 }); + for it in &self.items { + let mut e = Vec::new(); + id(&mut e, it.id); + e.extend_from_slice(&[0, 0]); // not protected + e.extend_from_slice(it.kind); + e.push(0); // no name + if it.kind == b"mime" { + e.extend_from_slice(it.mime.0.as_bytes()); + e.push(0); + e.extend_from_slice(it.mime.1.as_bytes()); + e.push(0); + } + iinf.extend(full_box(b"infe", if self.wide { 3 } else { 2 }, &e)); + } + let mut iref = Vec::new(); + for (kind, from, to) in &self.refs { + let mut r = Vec::new(); + id(&mut r, *from); + put(&mut r, to.len() as u64, 2); + to.iter().for_each(|t| id(&mut r, *t)); + iref.extend(bx(kind, &r)); + } + let (version, [o, l, b, i]) = self.iloc; + let mut iloc = vec![o << 4 | l, b << 4 | i]; + put(&mut iloc, self.items.len() as u64, if version == 2 { 4 } else { 2 }); + let (mut in_file, mut in_idat) = (mdat_at as u64, 0u64); + let mut idat = Vec::new(); + for it in &self.items { + put(&mut iloc, u64::from(it.id), if version == 2 { 4 } else { 2 }); + let at = match it.store { + Store::File => &mut in_file, + Store::Idat => &mut in_idat, + }; + if version > 0 { + put(&mut iloc, if it.store == Store::Idat { 1 } else { 0 }, 2); + } + put(&mut iloc, 0, 2); // this file + let base = if b > 0 { *at } else { 0 }; + put(&mut iloc, base, b); + let chunk = it.data.len().div_ceil(it.extents.max(1)).max(1); + let pieces: Vec<&[u8]> = it.data.chunks(chunk).collect(); + put(&mut iloc, pieces.len() as u64, 2); + for piece in pieces { + if version > 0 { + put(&mut iloc, 0, i); + } + put(&mut iloc, *at - base, o); + put(&mut iloc, piece.len() as u64, l); + *at += piece.len() as u64; + } + if it.store == Store::Idat { + idat.extend_from_slice(&it.data); + } + } + let ref_version = if self.wide { 1 } else { 0 }; + let boxes = [ + full_box(b"hdlr", 0, &hdlr), + full_box(b"pitm", ref_version, &pitm), + full_box(b"iinf", ref_version, &iinf), + full_box(b"iref", ref_version, &iref), + full_box(b"iloc", version, &iloc), + bx(b"idat", &idat), + ]; + full_box(b"meta", 0, &boxes.concat()) + } + + fn build(&self) -> Vec { + let ftyp = bx(b"ftyp", &self.ftyp); + let mdat_at = ftyp.len() + self.meta(0).len() + 8; + let mdat: Vec = self.items.iter().filter(|i| i.store == Store::File).flat_map(|i| i.data.iter().copied()).collect(); + [ftyp, self.meta(mdat_at), bx(b"mdat", &mdat)].concat() + } +} + +/// One item's bytes, as [`read`] gathers them: its place from `iloc`, then its extents. +fn item_bytes(file: &[u8], iloc: &[u8], idat: Option<&[u8]>, id: u32) -> Option> { + let iloc = Iloc::parse(iloc)?; + let mut place = None; + iloc.walk(|i, p| { + if i == id { + place = Some(p); + } + place.is_none() + })?; + match iloc.gather(file, idat, &place?, MAX_ITEM) { + Gathered::Bytes(b) => Some(b), + _ => None, + } +} + +/// LightCraft's issue sweep case, laid out as its HEIF test builder writes it: `iloc` version 1, +/// the EXIF item (offset 0, then the TIFF) tied to the primary image by `cdsc`. +#[test] +fn the_issue_sweep_heic_gives_its_exif() { + let f = Heif::new().item(8, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(8, &[1]).build(); + assert_eq!(exif(&f).as_deref(), Some(SWEEP_TIFF.as_slice())); +} + +/// The 4-byte offset in front of the TIFF stream: iPhones write 6 and `Exif\0\0`, libheif and +/// avif-serialize 0. Writers that left the field out, or got it wrong, are read when the stream +/// is plain to see; anything else is no EXIF. +#[test] +fn exif_items_with_and_without_their_offset() { + let t = &SWEEP_TIFF[..]; + let tiff = Some(t); + assert_eq!(exif_tiff(&exif_item(b"Exif\0\0", t)), tiff, "iPhone"); + assert_eq!(exif_tiff(&exif_item(&[], t)), tiff, "libheif, avif-serialize"); + assert_eq!(exif_tiff(&exif_item(b"\0\0padding", t)), tiff, "any bytes the offset skips"); + assert_eq!(exif_tiff(&[b"\0\0\0\0Exif\0\0".as_slice(), t].concat()), tiff, "offset 0 though a prefix follows"); + assert_eq!(exif_tiff(&[&1000u32.to_be_bytes()[..], t].concat()), tiff, "offset past the end"); + assert_eq!(exif_tiff(&[b"Exif\0\0".as_slice(), t].concat()), tiff, "no offset field, JPEG style"); + assert_eq!(exif_tiff(t), tiff, "no offset field at all"); + assert_eq!(exif_tiff(&exif_item(&[], b"not a TIFF stream")), None); + assert_eq!(exif_tiff(&[0, 0]), None); + assert_eq!(exif_tiff(&[]), None); + assert_eq!(exif_tiff(b"Exif\0"), None, "a prefix cut short"); + // and through a whole file, the iPhone way + let f = Heif::new().item(2, b"Exif", exif_item(b"Exif\0\0", t), Store::File, 1).cdsc(2, &[1]).build(); + assert_eq!(exif(&f).as_deref(), tiff); +} + +/// Items in several extents, in the file or the `meta` box's `idat`, with every `iloc` version +/// and field size. +#[test] +fn item_extents_and_construction_methods() { + let packet = xmp_with("Harbour at dusk"); + let rdf = ("application/rdf+xml", ""); + // EXIF in `idat` (method 1), XMP in the file in three extents, a 32-bit base offset + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::Idat, 1).cdsc(2, &[1]).xmp(3, rdf, packet.clone().into_bytes()); + h.items[2].extents = 3; + h.iloc = (1, [8, 4, 4, 0]); + let f = h.cdsc(3, &[1]).build(); + assert_eq!(read(&f).unwrap(), (Some(SWEEP_TIFF.to_vec()), Some(packet.clone()))); + // version 2: 32-bit item ids, an extent index, 64-bit lengths; EXIF in two extents + let mut h = Heif::new().item(70_000, b"Exif", exif_item(b"Exif\0\0", &SWEEP_TIFF), Store::File, 2).cdsc(70_000, &[70_001]); + (h.primary, h.items[0].id, h.wide, h.iloc) = (70_001, 70_001, true, (2, [4, 8, 0, 4])); + assert_eq!(exif(&h.build()).as_deref(), Some(SWEEP_TIFF.as_slice())); + // version 0: no construction method, file offsets only + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(2, &[1]); + h.iloc = (0, [4, 4, 0, 0]); + assert_eq!(exif(&h.build()).as_deref(), Some(SWEEP_TIFF.as_slice())); + // an XMP item in `idat` + let mut h = Heif::new().xmp(5, rdf, packet.clone().into_bytes()); + h.items[1].store = Store::Idat; + assert_eq!(xmp(&h.build()), Some(packet)); +} + +/// `iloc` entries the builder doesn't write: a length of 0 (to the end of the data), an item +/// in another file, an item built from other items, unknown versions and field sizes. +#[test] +fn iloc_entries_that_are_read_or_refused() { + let file = b"0123456789".as_slice(); + let idat = b"abcdefgh".as_slice(); + // version 1, offset and length 4 bytes, no base or index; one item with one extent + let iloc = |version: u8, sizes: [u8; 2], method: u16, data_ref: u16, offset: u32, length: u32| { + let mut l = vec![version, 0, 0, 0]; + l.extend_from_slice(&sizes); + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&7u16.to_be_bytes()); + if version > 0 { + l.extend_from_slice(&method.to_be_bytes()); + } + l.extend_from_slice(&data_ref.to_be_bytes()); + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&offset.to_be_bytes()); + l.extend_from_slice(&length.to_be_bytes()); + l + }; + let get = |l: &[u8]| item_bytes(file, l, Some(idat), 7); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 2, 3)).as_deref(), Some(b"234".as_slice())); + assert_eq!(get(&iloc(1, [0x44, 0], 1, 0, 2, 3)).as_deref(), Some(b"cde".as_slice()), "from idat"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 6, 0)).as_deref(), Some(b"6789".as_slice()), "length 0: to the end of the file"); + assert_eq!(get(&iloc(1, [0x44, 0], 1, 0, 5, 0)).as_deref(), Some(b"fgh".as_slice()), "length 0: to the end of idat"); + assert_eq!(item_bytes(file, &iloc(1, [0x44, 0], 1, 0, 0, 1), None, 7), None, "method 1 without idat"); + assert_eq!(get(&iloc(1, [0x44, 0], 2, 0, 0, 1)), None, "method 2 (from other items)"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 1, 0, 1)), None, "in another file"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 8, 3)), None, "past the end"); + assert_eq!(get(&iloc(1, [0x44, 0], 0, 0, 11, 0)), None, "starts past the end"); + assert_eq!(get(&iloc(1, [0x22, 0], 0, 0, 0, 1)), None, "2-byte fields are not in the standard"); + assert_eq!(get(&iloc(3, [0x44, 0], 0, 0, 0, 1)), None, "unknown version"); + assert_eq!(item_bytes(file, &iloc(1, [0x44, 0], 0, 0, 0, 1), None, 8), None, "no such item"); + // a base offset near u64::MAX plus an extent offset overflows: refused, not wrapped + let mut l = vec![1, 0, 0, 0, 0x44, 0x80]; + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&7u16.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0]); // method 0, data reference 0 + l.extend_from_slice(&u64::MAX.to_be_bytes()); + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&1u32.to_be_bytes()); + l.extend_from_slice(&1u32.to_be_bytes()); + assert_eq!(get(&l), None); +} + +/// The primary image's metadata is read; metadata tied only to another image is not. +#[test] +fn the_primary_images_metadata_is_read() { + let thumb = |h: Heif| h.item(2, b"hvc1", b"thumbnail".to_vec(), Store::File, 1); + // a thumbnail's EXIF comes first in the file; the primary image's is the one read + let f = thumb(Heif::new()) + .item(10, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Primary")), Store::File, 1) + .cdsc(10, &[2]) + .cdsc(11, &[1]) + .build(); + assert_eq!(exif(&f), Some(tiff_with("Primary"))); + // EXIF tied only to another image is not this photo's + let f = thumb(Heif::new()).item(10, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1).cdsc(10, &[2]).build(); + assert_eq!(exif(&f), None); + // tied to no image: it describes the file; tied to both: read + let f = Heif::new().item(10, b"Exif", exif_item(&[], &tiff_with("Whole file")), Store::File, 1).build(); + assert_eq!(exif(&f), Some(tiff_with("Whole file"))); + let f = thumb(Heif::new()).item(10, b"Exif", exif_item(&[], &tiff_with("Both")), Store::File, 1).cdsc(10, &[2, 1]).build(); + assert_eq!(exif(&f), Some(tiff_with("Both"))); + // a primary image's EXIF that can't be read gives way to one tied to no image + let f = Heif::new() + .item(10, b"Exif", exif_item(&[], b"damaged"), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Fallback")), Store::File, 1) + .cdsc(10, &[1]) + .build(); + assert_eq!(exif(&f), Some(tiff_with("Fallback"))); + // XMP: only uncompressed `application/rdf+xml` items, the primary image's first + let f = thumb(Heif::new()) + .xmp(20, ("image/jpeg", ""), b"\xff\xd8 not XMP".to_vec()) + .xmp(21, ("application/rdf+xml", "deflate"), b"compressed".to_vec()) + .xmp(22, ("application/rdf+xml", ""), xmp_with("Thumbnail").into_bytes()) + .xmp(23, (" Application/RDF+XML ", ""), xmp_with("Primary").into_bytes()) + .cdsc(22, &[2]) + .cdsc(23, &[1]) + .build(); + assert_eq!(xmp(&f), Some(xmp_with("Primary"))); + // 32-bit ids in `pitm`, `iinf` and `iref` + let mut h = Heif::new().item(70_000, b"Exif", exif_item(&[], &tiff_with("Wide")), Store::File, 1).cdsc(70_000, &[70_001]); + (h.primary, h.items[0].id, h.wide, h.iloc.0) = (70_001, 70_001, true, 2); + assert_eq!(exif(&h.build()), Some(tiff_with("Wide"))); +} + +/// EXIF tied to an image the primary is derived from (`dimg`: an `iden` turn, an `iovl` overlay, +/// a `tmap` tone map, a grid) is the primary image's, through any depth and despite loops. So is +/// EXIF in a file whose `pitm` names no item. A thumbnail's EXIF still isn't. +#[test] +fn metadata_of_the_images_a_primary_is_made_from_is_read() { + let base = |h: Heif| { + let mut h = h + .item(2, b"hvc1", b"thumbnail".to_vec(), Store::File, 1) + .item(3, b"hvc1", b"coded picture".to_vec(), Store::File, 1) + .item(10, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Input")), Store::File, 1) + .cdsc(10, &[2]) + .cdsc(11, &[3]); + h.items[0].kind = b"iden"; + h + }; + // the primary (1) turns item 3 + let f = base(Heif::new()).iref(b"dimg", 1, &[3]).build(); + assert_eq!(exif(&f), Some(tiff_with("Input"))); + // two levels (a tone map of a grid of 3), and a loop back to the primary + let f = + base(Heif::new()).item(4, b"grid", Vec::new(), Store::File, 1).iref(b"dimg", 1, &[4]).iref(b"dimg", 4, &[3]).iref(b"dimg", 3, &[1]).build(); + assert_eq!(exif(&f), Some(tiff_with("Input"))); + // `pitm` names an item that doesn't exist: there is no primary image, so tied items count + let mut h = Heif::new().item(11, b"Exif", exif_item(&[], &tiff_with("Orphan")), Store::File, 1).cdsc(11, &[1]); + h.primary = 99; + assert_eq!(exif(&h.build()), Some(tiff_with("Orphan"))); + // the thumbnail is not an input of the primary: without the `dimg`, nothing is the photo's + assert_eq!(exif(&base(Heif::new()).build()), None); +} + +/// HEIF, HEIC and AVIF brands are read; other files built of the same boxes are not HEIF. +#[test] +fn heif_and_avif_brands() { + let with = |ftyp: &[u8]| { + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(2, &[1]); + h.ftyp = ftyp.to_vec(); + h.build() + }; + for ftyp in [&b"heic\0\0\0\0mif1heic"[..], b"mif1\0\0\0\0mif1", b"heix\0\0\0\0mif1heix", b"avif\0\0\0\0avifmif1miaf", b"msf1\0\0\0\0msf1hevc"] { + assert!(is_heif(&with(ftyp)), "{}", String::from_utf8_lossy(ftyp)); + assert_eq!(exif(&with(ftyp)).as_deref(), Some(SWEEP_TIFF.as_slice()), "{}", String::from_utf8_lossy(ftyp)); + } + // MP4 and QuickTime video, JPEG XL, Canon CR3 + for ftyp in [&b"isom\0\0\x02\0isomiso2mp41"[..], b"qt \0\0\0\0qt ", b"jxl \0\0\0\0jxl ", b"crx \0\0\0\x01crx isom", b"mif1\0\0\0\0crx "] { + assert!(!is_heif(&with(ftyp)), "{}", String::from_utf8_lossy(ftyp)); + assert!(read(&with(ftyp)).is_err() && scan(&with(ftyp)).is_err()); + } + assert!(!is_heif(b"\0\0\0\x0cftyp"), "no brand"); + assert!(!is_heif(&[0xff, 0xd8, 0xff, 0xe0, 0, 0x10, b'J', b'F', b'I', b'F', 0, 1]), "JPEG"); + // a HEIF file without a `meta` box has no metadata + let bare = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + assert!(matches!(read(&bare), Err(Error::Unsupported(_)))); + assert_eq!(sure(&bare), Some(Vec::new())); +} + +/// Damaged structure: an out-of-range box, an `iinf` or `iref` that claims more than it holds, +/// extents that overlap to gather more than [`MAX_ITEM`], an item count far past the box. +#[test] +fn malformed_bounds_are_refused() { + let good = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::File, 1).cdsc(2, &[1]).build(); + // the `meta` box says it is longer than the file: nothing is read + let mut f = good.clone(); + let at = u32::from_be_bytes(f[0..4].try_into().unwrap()) as usize; // `meta` follows `ftyp` + assert_eq!(&f[at + 4..at + 8], b"meta"); + f[at..at + 4].copy_from_slice(&u32::MAX.to_be_bytes()); + assert_eq!(exif(&f), None); + assert_eq!(sure(&f), None); + // an extent past the end of the file + let mut f = good.clone(); + f.truncate(f.len() - 1); + assert_eq!(exif(&f), None); + // 65,535 extents over the same 64 KiB: refused at MAX_ITEM, quickly + let file = vec![0u8; 64 << 10]; + let mut l = vec![1, 0, 0, 0, 0x44, 0]; + l.extend_from_slice(&1u16.to_be_bytes()); + l.extend_from_slice(&7u16.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0]); + l.extend_from_slice(&u16::MAX.to_be_bytes()); + for _ in 0..u16::MAX { + l.extend_from_slice(&0u32.to_be_bytes()); + l.extend_from_slice(&(file.len() as u32).to_be_bytes()); + } + assert_eq!(item_bytes(&file, &l, None, 7), None); + // an item count of 2^32 - 1 in a box holding one entry + let mut l = vec![2, 0, 0, 0, 0x44, 0]; + l.extend_from_slice(&u32::MAX.to_be_bytes()); + l.extend_from_slice(&1u32.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0, 0, 0]); + assert_eq!(item_bytes(&file, &l, None, 7), None); + // a `cdsc` claiming 65,535 targets with none there, an `infe` cut short + let mut iref = vec![0, 0, 0, 0]; + iref.extend(bx(b"cdsc", &[0, 2, 0xff, 0xff])); + let iref = bx(b"iref", &iref); + let mut items = vec![Candidate { id: 2, kind: Kind::Exif, describes: false, describes_primary: false }]; + let mut budget = MAX_BOXES; + let b = boxes(&iref, 0, iref.len(), &mut budget); + link(&iref, &b[0], Some(1), &mut items, &mut budget); + assert!(!items[0].describes); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 0, b'E', b'x']), None, "cut short: the item type is unknown"); + assert_eq!(item_info(&[4, 0, 0, 0, 0, 2, 0, 0, b'E', b'x', b'i', b'f', 0]), None, "unknown infe version"); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x', b'i', b'f', 0]), Some((2, None)), "protected"); + // a full box's version is its own first byte, never the next box's + let two = [bx(b"iref", &[]), bx(b"free", &[1, 2, 3])].concat(); + let mut budget = MAX_BOXES; + let b = boxes(&two, 0, two.len(), &mut budget); + assert_eq!((version(&two, &b[0]), version(&two, &b[1])), (None, Some(1))); +} + +/// Box headers that lie: a 64-bit size, a `uuid` box too short for its extended type, a size +/// smaller than the header, a size of 0 (to the end). +#[test] +fn box_headers() { + let mut large = 1u32.to_be_bytes().to_vec(); + large.extend_from_slice(b"free"); + large.extend_from_slice(&20u64.to_be_bytes()); + large.extend_from_slice(b"abcd"); + let mut budget = MAX_BOXES; + let b = boxes(&large, 0, large.len(), &mut budget); + assert_eq!((b.len(), b[0].body, b[0].end), (1, 16, 20)); + large[8..16].copy_from_slice(&u64::MAX.to_be_bytes()); + assert!(boxes(&large, 0, large.len(), &mut budget).is_empty(), "a 64-bit size past the end"); + let short_uuid = bx(b"uuid", &[0; 8]); + assert!(boxes(&short_uuid, 0, short_uuid.len(), &mut budget).is_empty()); + let uuid = bx(b"uuid", &[0; 20]); + assert_eq!(boxes(&uuid, 0, uuid.len(), &mut budget)[0].body, 24); + assert!(boxes(&[0, 0, 0, 4, b'f', b'r', b'e', b'e'], 0, 8, &mut budget).is_empty(), "smaller than its header"); + let to_end = [&[0u8, 0, 0, 0][..], b"mdat", b"payload"].concat(); + assert_eq!(boxes(&to_end, 0, to_end.len(), &mut budget)[0].end, to_end.len()); + assert!(boxes(&to_end, 9, 4, &mut budget).is_empty(), "an empty range"); + let mut none = 0; + assert!(boxes(&to_end, 0, to_end.len(), &mut none).is_empty(), "no budget left"); +} + +/// Every cut-short or damaged file is read without a panic. +#[test] +fn truncated_and_damaged_files_never_panic() { + let mut h = Heif::new() + .item(2, b"Exif", exif_item(b"Exif\0\0", &SWEEP_TIFF), Store::Idat, 2) + .xmp(3, ("application/rdf+xml", ""), xmp_with("t").into_bytes()) + .cdsc(2, &[1]) + .cdsc(3, &[1]); + h.items[2].extents = 3; + h.iloc = (1, [4, 8, 4, 4]); + let f = h.build(); + assert!(matches!(read(&f), Ok((Some(_), Some(_))))); + for n in 0..f.len() { + let _ = read(&f[..n]); + let _ = scan(&f[..n]).map(Iterator::count); + } + for i in 0..f.len() { + for v in [0x00, 0xff, 0x7f, 0x01] { + let mut g = f.clone(); + g[i] = v; + let _ = read(&g); + let _ = scan(&g).map(Iterator::count); + } + } +} + +/// [`scan`] returns every EXIF and XMP item, not only the photo's own first EXIF: a thumbnail's +/// EXIF and XMP, the primary image's second EXIF item, a compressed XMP item. +#[test] +fn the_scan_returns_every_metadata_item() { + let plain = tiff_with("Primary"); + let thumb = |h: Heif| h.item(2, b"hvc1", b"thumbnail".to_vec(), Store::File, 1); + let ids = |f: &[u8]| sure(f).map(|items| items.into_iter().map(|(id, kind, _)| (id, kind)).collect::>()); + // the thumbnail's EXIF + let f = thumb(Heif::new()) + .item(10, b"Exif", exif_item(&[], &plain), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Thumbnail")), Store::File, 1) + .cdsc(10, &[1]) + .cdsc(11, &[2]) + .build(); + assert_eq!(exif(&f), Some(plain.clone()), "the photo's own EXIF"); + let all = sure(&f).unwrap(); + assert_eq!(all[1], (11, Kind::Exif, exif_item(&[], &tiff_with("Thumbnail")))); + // the primary image's second EXIF item + let f = Heif::new() + .item(10, b"Exif", exif_item(&[], &plain), Store::File, 1) + .item(11, b"Exif", exif_item(&[], &tiff_with("Second")), Store::File, 1) + .cdsc(10, &[1]) + .cdsc(11, &[1]) + .build(); + assert_eq!(exif(&f), Some(plain.clone())); + assert_eq!(ids(&f), Some(vec![(10, Kind::Exif), (11, Kind::Exif)])); + // a thumbnail's XMP (with place names, say) is not the photo's, but the scan has it + let f = thumb(Heif::new()) + .item(10, b"Exif", exif_item(&[], &plain), Store::File, 1) + .cdsc(10, &[1]) + .xmp(20, ("application/rdf+xml", ""), xmp_with("Thumbnail").into_bytes()) + .cdsc(20, &[2]) + .build(); + assert_eq!(xmp(&f), None, "the thumbnail's packet is not the primary image's"); + assert_eq!(sure(&f).unwrap()[1], (20, Kind::Xmp, xmp_with("Thumbnail").into_bytes())); + // a compressed XMP item comes back as stored, for the caller to judge + let f = Heif::new().xmp(20, ("application/rdf+xml", "deflate"), b"compressed".to_vec()).build(); + assert_eq!(sure(&f), Some(vec![(20, Kind::EncodedXmp, b"compressed".to_vec())])); + // an EXIF item cut off by the end of the file, one larger than the reader takes, more items + // than it looks at: not sure + let mut f = Heif::new().item(10, b"Exif", exif_item(&[], &plain), Store::File, 1).build(); + f.truncate(f.len() - 1); + assert_eq!(sure(&f), None, "cut off"); + let f = Heif::new().item(10, b"Exif", exif_item(&[], &vec![0; MAX_ITEM]), Store::File, 1).build(); + assert_eq!(scan(&f).unwrap().next().map(|it| it.data), Some(Err(Unreadable::TooLarge)), "too large"); + let mut h = Heif::new(); + for id in 0..(MAX_SCANNED as u32 + 1) { + h = h.item(10 + id, b"Exif", exif_item(&[], &plain), Store::File, 1); + } + let f = h.build(); + assert!(!scan(&f).unwrap().complete(), "too many items"); + assert_eq!(scan(&f).unwrap().count(), MAX_SCANNED); + assert_eq!(exif(&f), Some(plain), "read still finds the photo's EXIF"); +} + +/// Replace only the catalog; the real metadata remains in `idat` with unchanged `iloc`. +fn with_iinf(h: &Heif, iinf: Option<&[u8]>) -> Vec { + assert!(h.items.iter().filter(|it| it.kind == b"Exif" || it.kind == b"mime").all(|it| it.store == Store::Idat)); + let meta = h.meta(0); + let mut budget = MAX_BOXES; + let children: Vec = boxes(&meta, 12, meta.len(), &mut budget) + .iter() + .flat_map(|b| if &b.kind == b"iinf" { iinf.map(|data| bx(b"iinf", data)).unwrap_or_default() } else { bx(&b.kind, &meta[b.body..b.end]) }) + .collect(); + [bx(b"ftyp", &h.ftyp), full_box(b"meta", 0, &children)].concat() +} + +fn catalog(version: u8, count: u32, entries: &[u8]) -> Vec { + let mut data = vec![version, 0, 0, 0]; + put(&mut data, u64::from(count), if version == 0 { 2 } else { 4 }); + data.extend_from_slice(entries); + data +} + +fn catalog_entry(version: u8, id: u32, kind: &[u8; 4], fields: &[u8]) -> Vec { + let mut data = vec![version, 0, 0, 0]; + put(&mut data, u64::from(id), if version == 3 { 4 } else { 2 }); + data.extend_from_slice(&[0, 0]); + if version >= 2 { + data.extend_from_slice(kind); + } + data.extend_from_slice(fields); + data +} + +/// An `infe` cut anywhere, even one that keeps the id and part of the type, makes the scan unsure. +#[test] +fn item_catalog_truncated_type_is_uncertain() { + let tiff = tiff_with("Located"); + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff), Store::Idat, 1); + for version in [2, 3] { + let entry = catalog_entry(version, 2, b"Exif", b"\0"); + let intact = with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry)))); + assert_eq!(exif(&intact), Some(tiff.clone()), "infe v{version}"); + assert_eq!(sure(&intact), Some(vec![(2, Kind::Exif, exif_item(&[], &tiff))]), "infe v{version}"); + for end in 0..entry.len() { + let damaged = with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry[..end])))); + assert_eq!(sure(&damaged), None, "infe v{version}, cut at {end}"); + } + } +} + +/// An XMP entry cut in its fields or strings makes the scan unsure, in every `infe` and `iinf` version. +#[test] +fn item_catalog_truncated_fields_and_strings_are_uncertain() { + let packet = xmp_with("Located").into_bytes(); + let mut h = Heif::new().xmp(2, ("application/rdf+xml", ""), packet.clone()); + h.items[1].store = Store::Idat; + for version in 0..=3 { + // The optional content encoding is absent; name and content type are terminated. + let entry = catalog_entry(version, 2, b"mime", b"name\0application/rdf+xml\0"); + for table_version in [0, 1] { + let intact = with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry)))); + assert_eq!(sure(&intact), Some(vec![(2, Kind::Xmp, packet.clone())]), "infe v{version}, iinf v{table_version}"); + for end in 0..entry.len() { + let damaged = with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry[..end])))); + assert_eq!(sure(&damaged), None, "infe v{version}, iinf v{table_version}, cut at {end}"); + } + } + } +} + +/// A missing or cut catalog, unknown versions, unknown entry boxes, a count that doesn't match +/// the entries and unterminated strings all make the scan unsure. +#[test] +fn item_catalog_incomplete_walks_counts_and_versions_are_uncertain() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + let entry = catalog_entry(2, 2, b"Exif", b"\0"); + let intact = catalog(0, 1, &bx(b"infe", &entry)); + assert!(sure(&with_iinf(&h, Some(&intact))).is_some()); + let mut cases = vec![("missing catalog".to_string(), None)]; + for end in 0..intact.len() { + cases.push((format!("catalog cut at {end}"), Some(intact[..end].to_vec()))); + } + cases.push(("unsupported table version".into(), Some(catalog(2, 1, &bx(b"infe", &entry))))); + let mut unsupported = entry.clone(); + unsupported[0] = 4; + cases.push(("unsupported entry version".into(), Some(catalog(0, 1, &bx(b"infe", &unsupported))))); + cases.push(("unknown entry box".into(), Some(catalog(0, 1, &bx(b"free", &entry))))); + // A valid image entry cannot explain a declared but absent second entry. + let image = bx(b"infe", &catalog_entry(2, 1, b"hvc1", b"\0")); + for version in [0, 1] { + for count in [0, 2] { + cases.push((format!("iinf v{version}, count {count}"), Some(catalog(version, count, &image)))); + } + } + for (kind, fields) in [(b"hvc1", b"unterminated".as_slice()), (b"uri ", b"name\0unterminated"), (b"mime", b"name\0image/jpeg\0gzip")] { + cases.push((format!("unterminated {kind:?} field"), Some(catalog(0, 1, &bx(b"infe", &catalog_entry(2, 2, kind, fields)))))); + } + for (label, data) in cases { + assert_eq!(sure(&with_iinf(&h, data.as_deref())), None, "{label}"); + } +} + +/// An unreadable catalog entry doesn't stop [`read`] from returning the EXIF it could read. +#[test] +fn item_catalog_uncertainty_keeps_readable_exif() { + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Readable")), Store::Idat, 1).xmp( + 3, + ("application/rdf+xml", ""), + xmp_with("Located").into_bytes(), + ); + h.items[2].store = Store::Idat; + assert!(sure(&h.build()).is_some()); + let exif_entry = bx(b"infe", &catalog_entry(2, 2, b"Exif", b"\0")); + let broken = bx(b"infe", &catalog_entry(2, 3, b"mime", b"name\0application/rdf+")); + for entries in [[exif_entry.clone(), broken.clone()], [broken, exif_entry]] { + let f = with_iinf(&h, Some(&catalog(0, 2, &entries.concat()))); + assert_eq!(exif(&f), Some(tiff_with("Readable"))); + assert_eq!(sure(&f), None, "unreadable XMP after or before readable EXIF"); + } +} + +/// Catalogs without metadata items, and protected items, leave a complete, empty scan. +#[test] +fn item_catalog_benign_entries_and_empty_tables_are_complete() { + let h = Heif::new(); + assert_eq!(sure(&h.build()), Some(Vec::new()), "image only"); + for table_version in [0, 1] { + assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 0, &[])))), Some(Vec::new()), "empty catalog"); + for version in 0..=3 { + for fields in [b"\0image/jpeg\0".as_slice(), b"name\0image/jpeg\0\0", b"name\0image/jpeg\0gzip\0"] { + let entry = catalog_entry(version, 1, b"mime", fields); + assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry))))), Some(Vec::new())); + } + } + for kind in [b"hvc1", b"av01", b"zzzz", b"uri "] { + let fields = if kind == b"uri " { b"name\0https://example.invalid/item\0".as_slice() } else { b"name\0" }; + let entry = catalog_entry(2, 1, kind, fields); + assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry))))), Some(Vec::new())); + } + } + // A protected (encrypted) item is not a metadata item this reader can read. + let mut entry = catalog_entry(2, 2, b"Exif", b"\0"); + entry[7] = 1; + let h = h.item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + assert_eq!(sure(&with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry))))), Some(Vec::new())); + // Complete top-level files without an item meta box have no item catalog to inspect. + assert_eq!(sure(&bx(b"ftyp", b"msf1\0\0\0\0msf1")), Some(Vec::new())); +} + +/// Running out of box budget, or a walk that stops before the end of its box, never makes a +/// scan complete. +#[test] +fn item_catalog_box_budget_and_enclosing_walks_cannot_clear_uncertainty() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + let f = h.build(); + let ftyp = bx(b"ftyp", &h.ftyp); + let mut top_cut = f.clone(); + top_cut[ftyp.len()..ftyp.len() + 4].copy_from_slice(&u32::MAX.to_be_bytes()); + assert_eq!(sure(&top_cut), None, "meta box cut short"); + let hidden = [ftyp.clone(), bx(b"free", &[]).repeat(MAX_BOXES), h.meta(0)].concat(); + assert_eq!(sure(&hidden), None, "top-level budget hides meta"); + let hidden = [ftyp.clone(), full_box(b"meta", 0, &[bx(b"free", &[]).repeat(MAX_BOXES), h.meta(0)[12..].to_vec()].concat())].concat(); + assert_eq!(sure(&hidden), None, "meta budget hides catalog"); + let image = bx(b"infe", &catalog_entry(2, 1, b"hvc1", b"\0")); + let data = catalog(1, MAX_BOXES as u32, &image.repeat(MAX_BOXES)); + assert_eq!(sure(&with_iinf(&h, Some(&data))), None, "catalog budget"); + let hidden = [ftyp, full_box(b"meta", 0, &[vec![0; 3], h.meta(0)[12..].to_vec()].concat())].concat(); + assert_eq!(sure(&hidden), None, "incomplete meta child walk"); +} + +/// Replace `iloc` in a builder fixture. Metadata stays in `idat`, so changing the box sizes +/// cannot change its offsets. The coded picture is not used by these metadata tests. +fn with_iloc(h: &Heif, iloc: Option<&[u8]>) -> Vec { + assert!(h.items.iter().filter(|it| it.kind == b"Exif" || it.kind == b"mime").all(|it| it.store == Store::Idat)); + let meta = h.meta(0); + let mut budget = MAX_BOXES; + let children: Vec = boxes(&meta, 12, meta.len(), &mut budget) + .iter() + .flat_map(|b| if &b.kind == b"iloc" { iloc.map(|data| bx(b"iloc", data)).unwrap_or_default() } else { bx(&b.kind, &meta[b.body..b.end]) }) + .collect(); + [bx(b"ftyp", &h.ftyp), full_box(b"meta", 0, &children)].concat() +} + +/// The `iloc` bytes of a builder fixture. +fn iloc_of(f: &[u8]) -> Vec { + Container::read(f, MAX_SCANNED).unwrap().iloc.unwrap().data.to_vec() +} + +/// An `iloc` cut after a readable EXIF entry leaves the later XMP unresolved: [`read`] still +/// returns the EXIF, and the scan reports the XMP as unreadable. +#[test] +fn iloc_truncation_after_readable_exif_leaves_xmp_unreadable() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("First")), Store::Idat, 1); + assert!(sure(&h.build()).is_some(), "readable EXIF alone"); + let mut h = h.xmp(3, ("application/rdf+xml", ""), xmp_with("Located").into_bytes()); + h.items[2].store = Store::Idat; + let f = h.build(); + assert_eq!(sure(&f).map(|v| v.len()), Some(2), "the intact XMP"); + let iloc = iloc_of(&f); + let cut = with_iloc(&h, Some(&iloc[..iloc.len() - 1])); + assert_eq!(exif(&cut), Some(tiff_with("First")), "the first metadata item still reads"); + let found: Vec = scan(&cut).unwrap().collect(); + assert_eq!(found[1], Item { id: 3, kind: Kind::Xmp, data: Err(Unreadable::Placement) }, "the unresolved XMP isn't skipped"); +} + +/// A missing, cut or unsupported `iloc` leaves every metadata item unreadable. +#[test] +fn iloc_unresolved_metadata_is_unreadable() { + for kind in [b"Exif", b"mime"] { + let mut h = Heif::new().item(2, kind, b"unread metadata".to_vec(), Store::Idat, 1); + h.items[1].mime = ("application/rdf+xml", ""); + let iloc = iloc_of(&h.build()); + assert_eq!(sure(&with_iloc(&h, None)), None, "missing iloc: {kind:?}"); + // Every cut leaves the metadata entry unresolved, including cuts in its last extent. + for end in 0..iloc.len() { + assert_eq!(sure(&with_iloc(&h, Some(&iloc[..end]))), None, "{kind:?}: iloc cut at {end}"); + } + // Unsupported version or any one of the four field sizes. + for (at, value) in [(0, 3), (4, 0x24), (4, 0x42), (5, 0x20), (5, 0x02)] { + let mut bad = iloc.clone(); + bad[at] = value; + assert_eq!(sure(&with_iloc(&h, Some(&bad))), None, "{kind:?}: field {at} = {value}"); + } + } +} + +/// A partial `iloc` walk that placed one item doesn't make another, unplaced item absent. +#[test] +fn iloc_partial_walk_does_not_clear_unresolved_metadata() { + let h = Heif::new().item(2, b"Exif", Vec::new(), Store::Idat, 1).item(3, b"Exif", b"unread metadata".to_vec(), Store::Idat, 1); + let iloc = iloc_of(&h.build()); + // Picture: 16 bytes; empty EXIF: 8 bytes; final EXIF: 16 bytes. Keep the first EXIF + // intact while cutting the second entry at every byte, including its extent fields. + for end in 32..iloc.len() { + let cut = with_iloc(&h, Some(&iloc[..end])); + let partial = Container::read(&cut, MAX_SCANNED).unwrap(); + assert!(matches!(partial.gather(0, MAX_ITEM), Gathered::Bytes(b) if b.is_empty())); + assert_eq!(sure(&cut), None, "iloc cut at {end}"); + } +} + +/// A complete `iloc` that places no entry for an item, or one with no extents, is sure: the +/// item has no bytes. +#[test] +fn iloc_complete_walk_allows_unplaced_and_empty_items() { + let h = Heif::new().item(2, b"Exif", Vec::new(), Store::Idat, 1); + assert_eq!(sure(&h.build()), Some(vec![(2, Kind::Exif, Vec::new())]), "placed EXIF with no extents"); + // A well-formed empty table, or a complete table placing only a different item. + for version in 0..=2 { + let mut iloc = vec![version, 0, 0, 0, 0, 0]; + put(&mut iloc, 0, if version == 2 { 4 } else { 2 }); + assert_eq!(sure(&with_iloc(&h, Some(&iloc))), Some(Vec::new()), "empty iloc v{version}"); + let count_at = iloc.len() - 1; + iloc[count_at] = 1; + put(&mut iloc, 9, if version == 2 { 4 } else { 2 }); + if version > 0 { + put(&mut iloc, 0, 2); // construction method + } + iloc.extend_from_slice(&[0, 0, 0, 0]); // this file, no extents + assert_eq!(sure(&with_iloc(&h, Some(&iloc))), Some(Vec::new()), "absent item in complete iloc v{version}"); + } + // No metadata candidates: there is nothing to resolve, even without a usable iloc. + assert_eq!(sure(&Heif::new().build()), Some(Vec::new())); + for iloc in [None, Some([3, 0, 0, 0, 0, 0].as_slice())] { + ILOC_ENTRIES.with(|n| n.set(0)); + assert_eq!(sure(&with_iloc(&Heif::new(), iloc)), Some(Vec::new())); + assert_eq!(ILOC_ENTRIES.with(std::cell::Cell::get), 0); + } +} + +/// The `iloc` walk ends once every metadata item is placed, before a damaged later entry. +#[test] +fn iloc_stops_after_all_metadata_is_placed() { + let h = Heif::new().item(2, b"Exif", Vec::new(), Store::Idat, 1).item(3, b"hvc1", vec![1], Store::File, 1); + let iloc = iloc_of(&h.build()); + // The last picture entry is truncated. The only metadata entry is already complete. + let cut = with_iloc(&h, Some(&iloc[..32])); + ILOC_ENTRIES.with(|n| n.set(0)); + assert_eq!(sure(&cut), Some(vec![(2, Kind::Exif, Vec::new())])); + assert_eq!(ILOC_ENTRIES.with(std::cell::Cell::get), 2, "stop after the picture and the EXIF entry"); +} + +/// A placed item whose extents leave its data, or pass the limit, can't be read. +#[test] +fn iloc_resolved_extents_still_obey_bounds_and_budget() { + let h = Heif::new().item(2, b"Exif", b"abcd".to_vec(), Store::Idat, 1); + let f = h.build(); + let c = Container::read(&f, MAX_SCANNED).unwrap(); + assert!(matches!(c.gather(0, 4), Gathered::Bytes(b) if b == b"abcd")); + assert!(matches!(c.gather(0, 3), Gathered::TooLarge)); + let iloc = iloc_of(&f); + for (offset, length) in [(0u32, 5u32), (5, 0), (u32::MAX, 1)] { + let mut bad = iloc.clone(); + let end = bad.len(); + bad[end - 8..end - 4].copy_from_slice(&offset.to_be_bytes()); + bad[end - 4..].copy_from_slice(&length.to_be_bytes()); + let f = with_iloc(&h, Some(&bad)); + let c = Container::read(&f, MAX_SCANNED).unwrap(); + assert!(matches!(c.gather(0, MAX_ITEM), Gathered::Unreadable)); + assert_eq!(sure(&f), None); + } +} + +/// `iloc` is walked once, however many metadata items there are to place (one walk per item +/// took over a second on a 48 MB `iloc` with 64 items). +#[test] +fn iloc_is_walked_once() { + // 64 metadata items, none placed by `iloc`, and 20,000 entries for other items + let mut iinf = vec![0u8, 0, 0, 0]; + iinf.extend_from_slice(&64u16.to_be_bytes()); + for id in 0..64u16 { + let mut e = vec![2u8, 0, 0, 0]; + e.extend_from_slice(&(1000 + id).to_be_bytes()); + e.extend_from_slice(&[0, 0]); + e.extend_from_slice(if id % 2 == 0 { b"Exif\0" } else { b"mime\0application/rdf+xml\0" }); + iinf.extend(bx(b"infe", &e)); + } + let entries = 20_000usize; + let mut iloc = vec![2u8, 0, 0, 0, 0, 0]; + iloc.extend_from_slice(&(entries as u32).to_be_bytes()); + for _ in 0..entries { + iloc.extend_from_slice(&[0, 0, 0, 1, 0, 0, 0, 0, 0, 0]); // item 1, method 0, this file, no extents + } + let meta = full_box(b"meta", 0, &[bx(b"iinf", &iinf), bx(b"iloc", &iloc)].concat()); + let f = [bx(b"ftyp", b"heic\0\0\0\0mif1heic"), meta].concat(); + let walked = |run: &dyn Fn(&[u8])| { + ILOC_ENTRIES.with(|n| n.set(0)); + run(&f); + ILOC_ENTRIES.with(std::cell::Cell::get) + }; + let n = walked(&|f| assert_eq!(read(f).unwrap(), (None, None))); + assert!(n <= entries, "read walked {n} entries of {entries}"); + let n = walked(&|f| assert_eq!(sure(f), Some(Vec::new()))); + assert!(n <= entries, "scan walked {n} entries of {entries}"); +} + +proptest::proptest! { + /// Arbitrary bytes behind a HEIF `ftyp`, or inside its `meta` box, never panic. + #[test] + fn arbitrary_boxes_never_panic(body in proptest::collection::vec(proptest::prelude::any::(), 0..512)) { + for f in [[bx(b"ftyp", b"heic\0\0\0\0mif1heic"), body.clone()].concat(), [bx(b"ftyp", b"heic\0\0\0\0mif1heic"), full_box(b"meta", 0, &body)].concat()] { + let _ = read(&f); + let _ = scan(&f).map(Iterator::count); + } + } +} From 402e686c7a002a8b686afa5b4ea34c13d3fd14b8 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 21:57:59 +0100 Subject: [PATCH 035/349] craft-heif: document items::read, scan and exif_tiff --- crates/heif/README.md | 21 +++++++++++++++++---- 1 file changed, 17 insertions(+), 4 deletions(-) diff --git a/crates/heif/README.md b/crates/heif/README.md index d5adf6fdd..6842dcc0d 100644 --- a/crates/heif/README.md +++ b/crates/heif/README.md @@ -36,11 +36,24 @@ Errors are `Error::Unsupported` (image sequences, overlays, 4:2:2/4:4:4, …), ` `Error::Malformed`. It never panics: every call into heic-rs runs under `catch_unwind`, and a panic inside it (PhotoCraft's fuzzing found two in 0.1.1) becomes `Error::Malformed`. -Features: `decode` (default) is the decoder above. `metadata` adds `craft_heif::items::read`: the -first `Exif` item and XMP packet from the box structure alone (`iinf`, `iloc`, `idat`; at most 4096 -boxes, 1024 items, 1024 extents per item, 32 MiB per item), without heic-rs. A build with +Features: `decode` (default) is the decoder above. `metadata` adds `craft_heif::items`, which reads +the `Exif` and XMP items from the box structure alone (`pitm`, `iinf`, `iref`, `iloc`, `idat`), +without heic-rs: + +- `items::read` returns the photo's own EXIF and XMP: the items `cdsc` ties to the primary image or + to an image it is made from (`dimg`: grid tiles, `iden`, `iovl`, `tmap`), else those tied to no + image. A thumbnail's or depth map's metadata is not the photo's. +- `items::scan` returns every EXIF and XMP item, whichever image it describes, and says when it + can't be sure it saw them all: `Scan::complete` is false for an incomplete or damaged item + catalog, and an item whose bytes can't be read comes back as `Unreadable`. An app that must + prove a file has no location (before an export that removes it) refuses when unsure. +- `items::exif_tiff` finds the TIFF stream in an `Exif` item, with or without a correct offset + field or an `Exif\0\0` prefix. + +The reader walks at most 65,536 boxes and walks `iloc` once. It gathers at most 16 MiB per item, +and a scan gathers at most 64 MiB in all. A build with `default-features = false, features = ["metadata"]` has no heic-rs dependency, and its -`read_metadata` is that reader. With both features, a test checks that the two readers agree. +`read_metadata` is `items::read`. With both features, a test checks that the two readers agree. Feature `testdata` exposes `craft_heif::testdata`: lossless synthetic HEIF files (PCM-coded 32 × 32 HEVC pictures, grids, every property above) for the tests of the crates above. From 376fa26e4c4349e95363abf3d21bc76e8ee4d86e Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 22:01:59 +0100 Subject: [PATCH 036/349] rtf: read paragraph direction from stylesheet entries A style's \rtlpar/\ltrpar (and \rtldir/\ltrdir) is stored with the style and found through \sbasedon. A paragraph in the style gets it unless it sets its own direction; \pard drops the direct direction and the style's stays. Co-Authored-By: Claude Sonnet 5.5 --- crates/rtf/src/doc/state.rs | 4 ++-- crates/rtf/src/doc/styles.rs | 6 +++++- crates/rtf/src/doc/tests.rs | 12 ++++++++++++ crates/rtf/src/doc/word.rs | 6 ++++-- 4 files changed, 23 insertions(+), 5 deletions(-) diff --git a/crates/rtf/src/doc/state.rs b/crates/rtf/src/doc/state.rs index 1f5d8d2e6..c27758d05 100644 --- a/crates/rtf/src/doc/state.rs +++ b/crates/rtf/src/doc/state.rs @@ -149,7 +149,7 @@ pub(super) struct St { // Paragraph properties. pub(super) align: Option, /// `\rtlpar`: the paragraph reads right to left. - pub(super) rtldir: bool, + pub(super) rtldir: Option, pub(super) style: i32, pub(super) intbl: bool, pub(super) ls: Option, @@ -187,7 +187,7 @@ impl Default for St { uc: 1, hidden: false, align: None, - rtldir: false, + rtldir: None, style: 0, intbl: false, ls: None, diff --git a/crates/rtf/src/doc/styles.rs b/crates/rtf/src/doc/styles.rs index dd42f3b87..e8eb9904c 100644 --- a/crates/rtf/src/doc/styles.rs +++ b/crates/rtf/src/doc/styles.rs @@ -30,6 +30,7 @@ impl Reader { out.italic = out.italic.or(d.italic); out.size = out.size.or(d.size); out.font = out.font.or(d.font); + out.rtl = out.rtl.or(d.rtl); cur = d.based_on; } out @@ -87,7 +88,8 @@ impl Reader { pub(super) fn para_props(&self, st: &St) -> Para { let mut p = Para::new(self.para_kind(st)); p.align = st.align; - p.rtl = st.rtldir; + // Direct `\rtlpar`/`\ltrpar` wins over the style's direction. + p.rtl = st.rtldir.or_else(|| self.file_style(st.style).rtl).unwrap_or(false); p.page_break = st.pagebb; p.spacing = spacing(st); p.borders = st.borders.any_visible().then_some(st.borders); @@ -136,6 +138,8 @@ pub(super) struct StyleDef { pub(super) size: Option, /// A `\fonttbl` index, named when it's used (the table may follow). pub(super) font: Option, + /// `\rtlpar` (`Some(true)`) or `\ltrpar`: the paragraph direction the style sets. + pub(super) rtl: Option, } /// Clear from `f` the formatting a paragraph of kind `kind` gets from its style, whose diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index 9274104ab..30fc8127c 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -68,6 +68,18 @@ fn rtl_paragraphs_read_and_write_their_direction() { assert_eq!(bidi(&import(out.as_bytes()).unwrap()), [true, false, false]); } +#[test] +fn rtl_paragraph_styles_carry_their_direction() { + // Word often writes the direction in the style: `{\s1\rtlpar RTL;}` then `\pard\s1`. + let rtf = br#"{\rtf1\ansi{\stylesheet{\s0 Normal;}{\s1\rtlpar RTL;}{\s2\sbasedon1 Child;}{\s3\sbasedon1\ltrpar Back;}} +\pard\s1 A\par\pard\s2 B\par\pard\s3 C\par\pard\s1\ltrpar D\par\pard\s0\rtlpar E\par\pard F\par}"#; + let flow = parse(rtf).unwrap(); + let rtl: Vec = flow.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some(p.rtl) } else { None }).collect(); + // A: style. B: inherited from the base style. C: the style overrides its base. D: direct + // \ltrpar beats the style. E: direct \rtlpar on Normal. F: \pard drops direct formatting. + assert_eq!(rtl, [true, true, false, false, true, false]); +} + #[test] fn stylesheet_names_take_unicode_escapes() { // \u116?=t \u105?=i \u116?=t \u108?=l \u101?=e — how Word writes a non-Latin style name. diff --git a/crates/rtf/src/doc/word.rs b/crates/rtf/src/doc/word.rs index bf163db0c..0a346ef93 100644 --- a/crates/rtf/src/doc/word.rs +++ b/crates/rtf/src/doc/word.rs @@ -173,8 +173,8 @@ impl Reader { "qd" => self.st.align = Some(Align::Distribute), // `\rtldir`/`\ltrdir` are not paragraph words (they set a table's or section's // direction in RTF); some writers used them for paragraphs, so they are read too. - "rtlpar" | "rtldir" => self.st.rtldir = true, - "ltrpar" | "ltrdir" => self.st.rtldir = false, + "rtlpar" | "rtldir" => self.st.rtldir = Some(true), + "ltrpar" | "ltrdir" => self.st.rtldir = Some(false), "s" => self.st.style = pv, "outlinelevel" => self.st.outline = Some(pv.clamp(0, 9) as u8), "pagebb" => self.st.pagebb = on, @@ -421,6 +421,8 @@ impl Reader { "i" => def.italic = Some(on), "fs" => def.size = (value > 0).then(|| (value as f32 / 2.0).clamp(1.0, 1638.0)), "f" => def.font = Some(value), + "rtlpar" | "rtldir" => def.rtl = Some(true), + "ltrpar" | "ltrdir" => def.rtl = Some(false), _ => {} } true From d869560911f5e14914314ebaddd97b8acfa87805 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sat, 14 Nov 2026 22:01:59 +0100 Subject: [PATCH 037/349] rtf: keep direction words in old paragraph formatting \rtlpar, \ltrpar, \rtldir and \ltrdir are paragraph formatting words, so \oldpprops holds them and a tracked direction change keeps the old direction. Co-Authored-By: Claude Sonnet 5.5 --- crates/rtf/src/doc/styles.rs | 4 ++++ crates/rtf/src/doc/tests.rs | 14 ++++++++++++++ 2 files changed, 18 insertions(+) diff --git a/crates/rtf/src/doc/styles.rs b/crates/rtf/src/doc/styles.rs index e8eb9904c..6047bf3c4 100644 --- a/crates/rtf/src/doc/styles.rs +++ b/crates/rtf/src/doc/styles.rs @@ -208,6 +208,10 @@ pub(super) fn is_format_word(w: &str) -> bool { | "s" | "outlinelevel" | "pagebb" + | "rtlpar" + | "ltrpar" + | "rtldir" + | "ltrdir" | "intbl" | "ls" | "ilvl" diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index 30fc8127c..8ba6294ae 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -80,6 +80,20 @@ fn rtl_paragraph_styles_carry_their_direction() { assert_eq!(rtl, [true, true, false, false, true, false]); } +#[test] +fn oldpprops_keep_the_old_paragraph_direction() { + // A tracked change of direction: now LTR, before RTL (`\rtlpar` in the old properties). + let rtf = br"{\rtf1\ansi{\*\revtbl {Unknown;}{Alice;}} +\pard\ltrpar\prauth1\prdate-2014675576{\*\oldpprops \pard \rtlpar}A\par}"; + let flow = parse(rtf).unwrap(); + let Some(FBlock::Para(p)) = flow.blocks.first() else { panic!("no paragraph") }; + assert!(!p.rtl); + assert!(p.fmt_change.as_deref().expect("paragraph change").old.rtl, "old direction is RTL"); + let doc = import(rtf).unwrap(); + let c = doc_paras(&doc)[0].props.fmt_change.as_deref().expect("change"); + assert_eq!(c.old.bidi, Some(true)); +} + #[test] fn stylesheet_names_take_unicode_escapes() { // \u116?=t \u105?=i \u116?=t \u108?=l \u101?=e — how Word writes a non-Latin style name. From 2caa7deba14a39465de8fc5a24cceabd3fc71275 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sat, 14 Nov 2026 23:28:51 +0100 Subject: [PATCH 038/349] craft-heif: record the proptest dev-dependency in Cargo.lock --- Cargo.lock | 1 + 1 file changed, 1 insertion(+) diff --git a/Cargo.lock b/Cargo.lock index 52b28f0bd..34837eec4 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1785,6 +1785,7 @@ name = "craft-heif" version = "0.1.0" dependencies = [ "heic-rs", + "proptest", "rayon", ] From 7ad164ff8a8938965774fc2581e6545404839b6a Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sun, 15 Nov 2026 00:26:42 +0100 Subject: [PATCH 039/349] craft-heif: refuse a too-large item before copying any of it `Iloc::gather` copied extents until it passed its limit and then returned `TooLarge`, and `scan` charges its byte budget only for items it returns. So 1,024 items, each naming one 64 KiB region 257 times, copied 16 GiB from a 2 MiB file, and `read` up to 1 GiB. Check every extent and sum the lengths first, and copy only when the total fits. The new test counts the bytes copied over the full 1,024-gather scan and `read`'s 64 candidates; it copied 16 GiB before. --- crates/heif/src/items.rs | 39 ++++++++++++++++++----- crates/heif/src/items/tests.rs | 57 ++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+), 7 deletions(-) diff --git a/crates/heif/src/items.rs b/crates/heif/src/items.rs index d00dbdf06..2d86b3027 100644 --- a/crates/heif/src/items.rs +++ b/crates/heif/src/items.rs @@ -589,7 +589,9 @@ impl<'a> Iloc<'a> { } /// An item's bytes, its extents in order from the file (construction method 0) or from the - /// `meta` box's `idat` (method 1), at most `limit` of them. + /// `meta` box's `idat` (method 1), at most `limit` of them. Every extent is checked and the + /// lengths summed before anything is copied, so an item that is too large (say, the same + /// region named by thousands of extents) costs no copying. fn gather(&self, file: &[u8], idat: Option<&[u8]>, place: &Place, limit: usize) -> Gathered { // data reference 0 is this file let source = match (place.data_reference, place.method, idat) { @@ -597,14 +599,25 @@ impl<'a> Iloc<'a> { (0, 1, Some(idat)) => idat, _ => return Gathered::Unreadable, }; - let mut out = Vec::new(); - let mut at = place.extents_at; - for _ in 0..place.extents { - let Some((piece, next)) = self.extent(source, place.base, at) else { return Gathered::Unreadable }; - at = next; - if out.len().saturating_add(piece.len()) > limit { + let pieces = || { + let mut at = place.extents_at; + (0..place.extents).map(move |_| { + let (piece, next) = self.extent(source, place.base, at)?; + at = next; + Some(piece) + }) + }; + let mut total = 0usize; + for piece in pieces() { + let Some(piece) = piece else { return Gathered::Unreadable }; + total = total.saturating_add(piece.len()); + if total > limit { return Gathered::TooLarge; } + } + let mut out = Vec::with_capacity(total); + for piece in pieces().flatten() { + bytes_copied(piece.len()); out.extend_from_slice(piece); } Gathered::Bytes(out) @@ -635,6 +648,18 @@ fn iloc_entry_visited() { ILOC_ENTRIES.with(|n| n.set(n.get().saturating_add(1))); } +#[cfg(test)] +thread_local! { + /// Item bytes copied on this thread, for the tests that bound the work. + static COPIED: std::cell::Cell = const { std::cell::Cell::new(0) }; +} + +#[cfg_attr(not(test), allow(unused_variables))] +fn bytes_copied(n: usize) { + #[cfg(test)] + COPIED.with(|c| c.set(c.get().saturating_add(n))); +} + /// A big-endian unsigned field of `size` bytes (0 reads as 0). fn uint(b: &[u8], at: usize, size: usize) -> Option { match size { diff --git a/crates/heif/src/items/tests.rs b/crates/heif/src/items/tests.rs index 49cc9d789..6f73ff6c1 100644 --- a/crates/heif/src/items/tests.rs +++ b/crates/heif/src/items/tests.rs @@ -1128,6 +1128,63 @@ fn iloc_resolved_extents_still_obey_bounds_and_budget() { } } +/// A file whose MAX_SCANNED `Exif` items each name one 64 KiB region 257 times: every item is +/// too large, and finding that out copies nothing, for [`scan`] (all 1,024 gathers) and for +/// [`read`] (its MAX_CANDIDATES). Before, each gather copied MAX_ITEM bytes before giving up, +/// about 16 GiB for the scan of a 2 MiB file. +#[test] +fn too_large_items_are_refused_before_copying() { + const REGION: u32 = 64 << 10; + const REPEATS: u16 = 257; + let count = MAX_SCANNED as u16; + let mut iinf = count.to_be_bytes().to_vec(); + for id in 1..=count { + let mut e = vec![2u8, 0, 0, 0]; + e.extend_from_slice(&id.to_be_bytes()); + e.extend_from_slice(&[0, 0]); + e.extend_from_slice(b"Exif\0"); + iinf.extend(bx(b"infe", &e)); + } + let iloc = |region_at: u32| { + let mut l = vec![0x44, 0x00]; + l.extend_from_slice(&count.to_be_bytes()); + for id in 1..=count { + l.extend_from_slice(&id.to_be_bytes()); + l.extend_from_slice(&[0, 0, 0, 0]); // method 0, this file + l.extend_from_slice(&REPEATS.to_be_bytes()); + for _ in 0..REPEATS { + l.extend_from_slice(®ion_at.to_be_bytes()); + l.extend_from_slice(®ION.to_be_bytes()); + } + } + full_box(b"iloc", 1, &l) + }; + let ftyp = bx(b"ftyp", b"heic\0\0\0\0mif1heic"); + let meta = |region_at| full_box(b"meta", 0, &[full_box(b"iinf", 0, &iinf), iloc(region_at)].concat()); + let region_at = (ftyp.len() + meta(0).len() + 8) as u32; + let f = [ftyp, meta(region_at), bx(b"mdat", &vec![0; REGION as usize])].concat(); + + COPIED.with(|c| c.set(0)); + let s = scan(&f).unwrap(); + assert!(s.complete()); + let found: Vec = s.collect(); + assert_eq!(found.len(), MAX_SCANNED); + assert!(found.iter().all(|it| it.data == Err(Unreadable::TooLarge))); + assert_eq!(COPIED.with(std::cell::Cell::get), 0, "scan copied bytes of items it refused"); + + COPIED.with(|c| c.set(0)); + assert_eq!(read(&f).unwrap(), (None, None)); + assert_eq!(COPIED.with(std::cell::Cell::get), 0, "read copied bytes of items it refused"); + + // an item that fits is copied once, extent by extent + let mut h = Heif::new().item(2, b"Exif", exif_item(&[], &SWEEP_TIFF), Store::Idat, 3); + h.iloc = (1, [4, 4, 4, 0]); + let f = h.build(); + COPIED.with(|c| c.set(0)); + assert_eq!(sure(&f), Some(vec![(2, Kind::Exif, exif_item(&[], &SWEEP_TIFF))])); + assert_eq!(COPIED.with(std::cell::Cell::get), SWEEP_TIFF.len() + 4); +} + /// `iloc` is walked once, however many metadata items there are to place (one walk per item /// took over a second on a 48 MB `iloc` with 64 items). #[test] From ed70d09162f4f932876536cd4bfc0905fc070605 Mon Sep 17 00:00:00 2001 From: Alex Chambers Date: Sun, 15 Nov 2026 00:28:28 +0100 Subject: [PATCH 040/349] craft-heif: a protected Exif or XMP item is unreadable, not absent A nonzero protection index made `item_info` return before it read the item type, so a protected `Exif` or XMP item vanished: `scan` was complete and empty, as if the file held no metadata. The protection index doesn't hide the type, so read it, and return the item from `scan` as `Unreadable::Protected`. `read` still leaves it out. --- crates/heif/src/items.rs | 29 ++++++++++++++++++++--------- crates/heif/src/items/tests.rs | 33 +++++++++++++++++++++++++++------ 2 files changed, 47 insertions(+), 15 deletions(-) diff --git a/crates/heif/src/items.rs b/crates/heif/src/items.rs index 2d86b3027..e0b2d2c93 100644 --- a/crates/heif/src/items.rs +++ b/crates/heif/src/items.rs @@ -145,6 +145,7 @@ impl Iterator for Scan<'_> { Gathered::NotPlaced => continue, Gathered::Unreadable => Err(Unreadable::Placement), Gathered::TooLarge => Err(Unreadable::TooLarge), + Gathered::Protected => Err(Unreadable::Protected), }; return Some(Item { id, kind, data }); } @@ -184,6 +185,9 @@ pub enum Unreadable { Placement, /// More than [`MAX_ITEM`] bytes, or more than [`scan`] has left of [`MAX_SCANNED_BYTES`]. TooLarge, + /// The item is protected (encrypted): its `infe` entry names a protection scheme, so its + /// stored bytes are not the metadata in the clear. + Protected, } /// The TIFF stream of an `Exif` item: past its 4-byte offset field and the bytes that offset @@ -214,6 +218,8 @@ struct Candidate { describes: bool, /// Tied to the primary image or an image it is made from. describes_primary: bool, + /// Protected (encrypted): there, but not readable. + protected: bool, } impl Candidate { @@ -308,6 +314,9 @@ impl<'a> Container<'a> { /// The bytes of `items[i]`, at most `limit` of them. fn gather(&self, i: usize, limit: usize) -> Gathered { + if self.items.get(i).is_some_and(|c| c.protected) { + return Gathered::Protected; + } match (&self.iloc, self.places.get(i)) { (Some(iloc), Some(Some(place))) => iloc.gather(self.file, self.idat, place, limit), _ if self.iloc_complete => Gathered::NotPlaced, @@ -326,6 +335,8 @@ enum Gathered { Unreadable, /// More than the limit. TooLarge, + /// A protected (encrypted) item. + Protected, } /// A full box's version: the first byte of its own payload (`None` for an empty box). @@ -370,14 +381,14 @@ fn item_infos(bytes: &[u8], iinf: &BoxRef, cap: usize, budget: &mut usize) -> It catalog.complete = entries.last().map_or(first, |b| b.end) == iinf.end && u32::try_from(entries.len()).ok() == Some(count); for b in &entries { let info = bytes.get(b.body..b.end).filter(|_| &b.kind == b"infe").and_then(item_info); - let Some((id, kind)) = info else { + let Some((id, kind, protected)) = info else { catalog.complete = false; continue; }; catalog.ids.push(id); match kind { Some(_) if catalog.items.len() >= cap => catalog.more = true, - Some(kind) => catalog.items.push(Candidate { id, kind, describes: false, describes_primary: false }), + Some(kind) => catalog.items.push(Candidate { id, kind, describes: false, describes_primary: false, protected }), None => {} } } @@ -386,9 +397,11 @@ fn item_infos(bytes: &[u8], iinf: &BoxRef, cap: usize, budget: &mut usize) -> It catalog } -/// An `infe` entry's item id, and its kind when it is an unprotected `Exif` or XMP item (`mime`, -/// `application/rdf+xml`). `None` when the entry can't be read to its last field. -fn item_info(infe: &[u8]) -> Option<(u32, Option)> { +/// An `infe` entry's item id, its kind when it is an `Exif` or XMP item (`mime`, +/// `application/rdf+xml`), and whether it is protected (encrypted). A protected entry still names +/// its type in the clear, so protected metadata is found too. `None` when the entry can't be read +/// to its last field. +fn item_info(infe: &[u8]) -> Option<(u32, Option, bool)> { let version = *infe.first()?; // version and flags, the item id (32 bits in version 3), the protection index let (id, at) = match version { @@ -396,9 +409,7 @@ fn item_info(infe: &[u8]) -> Option<(u32, Option)> { 3 => (be32(infe, 4)?, 8usize), _ => return None, }; - if be16(infe, at)? != 0 { - return Some((id, None)); // protected (encrypted) - } + let protected = be16(infe, at)? != 0; let at = at.checked_add(2)?; // versions 0 and 1 have no item type and describe MIME items; 2 and 3 name the type let (kind, at) = if version >= 2 { (infe.get(at..at.checked_add(4)?)?, at.checked_add(4)?) } else { (b"mime".as_slice(), at) }; @@ -421,7 +432,7 @@ fn item_info(infe: &[u8]) -> Option<(u32, Option)> { } _ => None, }; - Some((id, kind)) + Some((id, kind, protected)) } /// The NUL-terminated string at `at` and where the next field starts. diff --git a/crates/heif/src/items/tests.rs b/crates/heif/src/items/tests.rs index 6f73ff6c1..35a193613 100644 --- a/crates/heif/src/items/tests.rs +++ b/crates/heif/src/items/tests.rs @@ -707,14 +707,15 @@ fn malformed_bounds_are_refused() { let mut iref = vec![0, 0, 0, 0]; iref.extend(bx(b"cdsc", &[0, 2, 0xff, 0xff])); let iref = bx(b"iref", &iref); - let mut items = vec![Candidate { id: 2, kind: Kind::Exif, describes: false, describes_primary: false }]; + let mut items = vec![Candidate { id: 2, kind: Kind::Exif, describes: false, describes_primary: false, protected: false }]; let mut budget = MAX_BOXES; let b = boxes(&iref, 0, iref.len(), &mut budget); link(&iref, &b[0], Some(1), &mut items, &mut budget); assert!(!items[0].describes); assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 0, b'E', b'x']), None, "cut short: the item type is unknown"); assert_eq!(item_info(&[4, 0, 0, 0, 0, 2, 0, 0, b'E', b'x', b'i', b'f', 0]), None, "unknown infe version"); - assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x', b'i', b'f', 0]), Some((2, None)), "protected"); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x', b'i', b'f', 0]), Some((2, Some(Kind::Exif), true)), "protected"); + assert_eq!(item_info(&[2, 0, 0, 0, 0, 2, 0, 1, b'E', b'x']), None, "protected and cut short"); // a full box's version is its own first byte, never the next box's let two = [bx(b"iref", &[]), bx(b"free", &[1, 2, 3])].concat(); let mut budget = MAX_BOXES; @@ -946,7 +947,7 @@ fn item_catalog_uncertainty_keeps_readable_exif() { } } -/// Catalogs without metadata items, and protected items, leave a complete, empty scan. +/// Catalogs without metadata items leave a complete, empty scan. #[test] fn item_catalog_benign_entries_and_empty_tables_are_complete() { let h = Heif::new(); @@ -965,15 +966,35 @@ fn item_catalog_benign_entries_and_empty_tables_are_complete() { assert_eq!(sure(&with_iinf(&h, Some(&catalog(table_version, 1, &bx(b"infe", &entry))))), Some(Vec::new())); } } - // A protected (encrypted) item is not a metadata item this reader can read. - let mut entry = catalog_entry(2, 2, b"Exif", b"\0"); + // A protected (encrypted) image item is no metadata item. + let mut entry = catalog_entry(2, 1, b"hvc1", b"\0"); entry[7] = 1; - let h = h.item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); assert_eq!(sure(&with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry))))), Some(Vec::new())); // Complete top-level files without an item meta box have no item catalog to inspect. assert_eq!(sure(&bx(b"ftyp", b"msf1\0\0\0\0msf1")), Some(Vec::new())); } +/// A protected (encrypted) `Exif` or XMP item is in the scan, as unreadable: the file holds +/// metadata that can't be checked. [`read`] leaves it out. +#[test] +fn protected_metadata_is_unreadable_not_absent() { + let h = Heif::new().item(2, b"Exif", exif_item(&[], &tiff_with("Located")), Store::Idat, 1); + for (kind, fields, expected) in [(b"Exif", b"\0".as_slice(), Kind::Exif), (b"mime", b"name\0application/rdf+xml\0", Kind::Xmp)] { + for version in [2, 3] { + let mut entry = catalog_entry(version, 2, kind, fields); + let protection_at = if version == 3 { 9 } else { 7 }; + entry[protection_at] = 1; + let f = with_iinf(&h, Some(&catalog(0, 1, &bx(b"infe", &entry)))); + let s = scan(&f).unwrap(); + assert!(s.complete(), "{kind:?} v{version}"); + let found: Vec = s.collect(); + assert_eq!(found, [Item { id: 2, kind: expected, data: Err(Unreadable::Protected) }], "{kind:?} v{version}"); + assert_eq!(sure(&f), None, "{kind:?} v{version}"); + assert_eq!(read(&f).unwrap(), (None, None), "{kind:?} v{version}"); + } + } +} + /// Running out of box budget, or a walk that stops before the end of its box, never makes a /// scan complete. #[test] From 537d61a60f84a92675b2391a6e912067c810d0b9 Mon Sep 17 00:00:00 2001 From: vangel76 <271991477+vangel76@users.noreply.github.com> Date: Sun, 15 Nov 2026 01:05:40 +0100 Subject: [PATCH 041/349] rtf: read \ql and \qr after \rtlpar as start and end The model's paragraph alignment is logical (start/end) in right-to-left paragraphs, but the reader mapped \ql/\qr straight to left/right. For a \rtlpar paragraph that mirrored the alignment compared to Word. Word reads a side word that follows \rtlpar as start/end, and one that comes before it as plain left/right (checked black-box by saving RTF variants to DOCX). So \rtlpar\qr is start (no explicit alignment), \rtlpar\ql is end, and \qr\rtlpar is end. The writer already puts the alignment before \rtlpar, so its output keeps its meaning and is unchanged. Co-Authored-By: Claude Sonnet 5.5 --- crates/rtf/src/doc/tests.rs | 43 +++++++++++++++++++++++++++++++++++++ crates/rtf/src/doc/word.rs | 16 ++++++++++++-- 2 files changed, 57 insertions(+), 2 deletions(-) diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index 8ba6294ae..8313ad5b8 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -1886,3 +1886,46 @@ fn compound_borders_round_trip() { let back = import(export(&d).as_bytes()).unwrap(); assert_eq!(tops(&back), want); } + +fn para_aligns(flow: &Flow) -> Vec<(bool, Option)> { + flow.blocks.iter().filter_map(|b| if let FBlock::Para(p) = b { Some((p.rtl, p.align)) } else { None }).collect() +} + +#[test] +fn alignment_words_after_rtlpar_mean_start_and_end() { + // Word reads `\ql`/`\qr` that follow `\rtlpar` as start/end (the model's alignment is + // logical), so `\rtlpar\qr` sits at the right edge and `\rtlpar\ql` at the left edge. + // Words written before `\rtlpar` keep their plain meaning (checked in Word by saving to DOCX: + // `\qr\rtlpar` gives jc=right, i.e. end, in the bidi paragraph; `\ql\rtlpar` gives no jc). + let rtf = br#"{\rtf1\ansi\deff0{\fonttbl{\f0 Arial;}}\pard LTR one.\par \pard\rtlpar\qr A.\par \pard\rtlpar B.\par \pard\ltrpar Back.\par \pard\rtlpar\ql C.\par \pard\rtlpar\qc D.\par \pard\ql\rtlpar E.\par \pard\qr\rtlpar F.\par \pard\rtlpar\ltrpar\qr G.\par}"#; + let got = para_aligns(&parse(rtf).unwrap()); + assert_eq!( + got, + [ + (false, None), + (true, Some(Align::Left)), + (true, None), + (false, None), + (true, Some(Align::Right)), + (true, Some(Align::Center)), + (true, Some(Align::Left)), + (true, Some(Align::Right)), + (false, Some(Align::Right)), + ] + ); +} + +#[test] +fn alignment_survives_an_export_import_round_trip() { + let rtf = br#"{\rtf1\ansi\pard\ql L.\par \pard\qr R.\par \pard\qc C.\par \pard\rtlpar\qr start.\par \pard\rtlpar\ql end.\par \pard\rtlpar\qc mid.\par \pard\rtlpar plain.\par}"#; + let first = para_aligns(&parse(rtf).unwrap()); + let doc = import(rtf).unwrap(); + let out = export(&doc); + let second = para_aligns(&parse(out.as_bytes()).unwrap()); + let norm = |v: Vec<(bool, Option)>| v.into_iter().map(|(r, a)| (r, a.filter(|a| *a != Align::Left))).collect::>(); + assert_eq!(norm(first), norm(second.clone()), "{out}"); + // `\rtlpar\qr` is start (no explicit alignment in the model) and `\rtlpar\ql` is end. + assert_eq!(norm(second)[3..5], [(true, None), (true, Some(Align::Right))], "{out}"); + // The export writes the alignment before the direction, which Word reads as logical start/end. + assert!(out.contains("\\qr\\rtlpar"), "{out}"); +} diff --git a/crates/rtf/src/doc/word.rs b/crates/rtf/src/doc/word.rs index 0a346ef93..2eb86692f 100644 --- a/crates/rtf/src/doc/word.rs +++ b/crates/rtf/src/doc/word.rs @@ -3,6 +3,18 @@ use super::styles::{StyleDef, is_char_format_word, is_format_word}; use super::{Align, Fmt, Reader, VAlign, model}; impl Reader { + /// The logical alignment for a side word (`Left` for `\ql`, `Right` for `\qr`). The model's + /// alignment is logical (start/end), and Word reads a side word that comes after `\rtlpar` as + /// start/end: the sides swap in a paragraph already marked right to left. Before `\rtlpar` + /// the side keeps its plain meaning, which is why the writer puts the alignment first. + fn side_align(&self, side: Align) -> Align { + match (self.st.rtldir, side) { + (Some(true), Align::Left) => Align::Right, + (Some(true), Align::Right) => Align::Left, + _ => side, + } + } + pub(super) fn word(&mut self, w: &str, p: Option, starred: bool, first_in_group: bool) { // Every control word ends a multibyte run: the code page it is read in may change here // (`\f`, `\fcharset`, `\cpg`, `\ansicpg`, `\pard`), and `\par` must see the text before it. @@ -166,9 +178,9 @@ impl Reader { "cf" => self.st.fmt.color = self.colors.get(pv.max(0) as usize).copied().flatten(), "highlight" | "chcbpat" | "cb" => self.st.fmt.background = self.colors.get(pv.max(0) as usize).copied().flatten(), "v" => self.st.hidden = on, - "ql" => self.st.align = Some(Align::Left), + "ql" => self.st.align = Some(self.side_align(Align::Left)), "qc" => self.st.align = Some(Align::Center), - "qr" => self.st.align = Some(Align::Right), + "qr" => self.st.align = Some(self.side_align(Align::Right)), "qj" => self.st.align = Some(Align::Justify), "qd" => self.st.align = Some(Align::Distribute), // `\rtldir`/`\ltrdir` are not paragraph words (they set a table's or section's From 396402940c557fa41e7f9d6bf74cc89cf54d3222 Mon Sep 17 00:00:00 2001 From: vangel76 <271991477+vangel76@users.noreply.github.com> Date: Sun, 15 Nov 2026 01:06:12 +0100 Subject: [PATCH 042/349] docx charts: marker symbols and sizes, data label formats, upward axis titles A chart file carried three things that were read but not drawn like Word: - c:marker/c:symbol was ignored (every marker was a circle): squares, diamonds, triangles, x, plus, star, dash and dot are drawn now, in the series' c:size; unknown names fall back to a circle, sizes are clamped to 2..72 points. - c:dLbls/c:numFmt (not linked to the source) now formats the data labels, on the series or on the chart type; over-long codes are ignored. - The vertical axis title is turned -90 degrees (reading upwards) as Word does, or 90 when the file's bodyPr rot says so. It was always +90. Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/read/chart/model.rs | 41 +++++++++++++ crates/docx/src/read/chart/parse.rs | 53 +++++++++++++++- crates/docx/src/read/chart/plot.rs | 57 ++++++++++++++---- crates/docx/src/read/chart/polar.rs | 4 +- crates/docx/src/read/chart/tests.rs | 93 +++++++++++++++++++++++++++++ crates/wordmodel/src/graphic.rs | 2 +- 6 files changed, 232 insertions(+), 18 deletions(-) diff --git a/crates/docx/src/read/chart/model.rs b/crates/docx/src/read/chart/model.rs index fd2760db0..61d5d32d0 100644 --- a/crates/docx/src/read/chart/model.rs +++ b/crates/docx/src/read/chart/model.rs @@ -64,11 +64,46 @@ pub(crate) struct Axis { pub(crate) fmt: Option, /// The axis title, when the file gives it one. pub(crate) title: Option, + /// The title's `a:bodyPr/@rot` in degrees clockwise (`-5400000` is 90° counter-clockwise), + /// when the file gives one. + pub(crate) title_rot: Option, /// Tick labels, as `c:tickLblPos` says (`none` hides them; a file that says nothing shows /// them, as Word does). pub(crate) labels: bool, } +/// The shape of a series' point markers (`ST_MarkerStyle`, ECMA-376 §21.2.3.28). +#[derive(Clone, Copy, Default, PartialEq, Eq, Debug)] +pub(super) enum Symbol { + #[default] + Circle, + Square, + Diamond, + Triangle, + X, + Plus, + Star, + Dash, + Dot, +} + +impl Symbol { + /// The symbol a `c:symbol` value names; anything unknown (`auto`, `picture`) is a circle. + pub(super) fn parse(name: &str) -> Symbol { + match name { + "square" => Symbol::Square, + "diamond" => Symbol::Diamond, + "triangle" => Symbol::Triangle, + "x" => Symbol::X, + "plus" => Symbol::Plus, + "star" => Symbol::Star, + "dash" => Symbol::Dash, + "dot" => Symbol::Dot, + _ => Symbol::Circle, + } + } +} + pub(super) struct Series { pub(super) name: String, /// The series' `c:idx` (an `xsd:unsignedInt`), which picks its automatic colour; `None` @@ -84,6 +119,10 @@ pub(super) struct Series { pub(super) no_fill: bool, /// Markers on the series' points, when the file says. pub(super) markers: Option, + /// The marker shape (`c:marker/c:symbol`; a circle when missing or unknown) and its size in + /// points (`c:marker/c:size`), when the file gives one. + pub(super) symbol: Symbol, + pub(super) marker_size: Option, /// Draw the series' line as a smooth curve (`c:smooth`). pub(super) smooth: bool, pub(super) values: Vec>, @@ -96,6 +135,8 @@ pub(super) struct Series { pub(super) x_fmt: Option, /// Data labels on or off for this series (`c:dLbls` of its own), when it says. pub(super) labels: Option, + /// The labels' own number format (`c:dLbls/c:numFmt` not linked to the source), if any. + pub(super) label_fmt: Option, /// The values as the file has them, for data labels (`values` become shares in a 100% /// stacked chart); empty when the series shows no labels. pub(super) raw: Vec>, diff --git a/crates/docx/src/read/chart/parse.rs b/crates/docx/src/read/chart/parse.rs index 6b20879c6..ec1508154 100644 --- a/crates/docx/src/read/chart/parse.rs +++ b/crates/docx/src/read/chart/parse.rs @@ -1,5 +1,5 @@ use super::format::{date_text, excel_stamp, format_value, is_date_code}; -use super::model::{Axis, Grouping, Kind, Pos, Series}; +use super::model::{Axis, Grouping, Kind, Pos, Series, Symbol}; use super::plot::label; use super::{Chart, El, FONT, MAX_CELLS, MAX_POINTS, MAX_RADAR_SERIES, MAX_SERIES, MAX_SPOKES, Rgb, fill_colour, int, measure, slot}; @@ -39,10 +39,14 @@ impl Chart { cats.resize(n, String::new()); let radar_style = ty.child("c:radarStyle").and_then(|r| r.attr("val")); let type_labels = show_values(ty.child("c:dLbls")); + let type_fmt = label_format(ty.child("c:dLbls")); for s in &mut series { s.values.resize(n, None); s.xs.resize(n, None); s.labels = Some(s.labels.or(type_labels).unwrap_or(false)); + if s.label_fmt.is_none() { + s.label_fmt.clone_from(&type_fmt); + } if s.labels == Some(true) { s.raw = s.values.clone(); } @@ -180,6 +184,15 @@ fn show_values(d: Option<&El>) -> Option { d.child("c:showVal").map(|v| v.attr("val").is_none_or(truthy)) } +/// The number format of data labels (`c:dLbls/c:numFmt`) when it is not linked to the source. +fn label_format(d: Option<&El>) -> Option { + d?.child("c:numFmt") + .filter(|f| f.attr("sourceLinked") != Some("1")) + .and_then(|f| f.attr("formatCode")) + .filter(|f| f.chars().count() <= craft_wordmodel::chart::MAX_FMT) + .map(str::to_string) +} + fn legend_pos(chart: &El) -> Option { chart.child("c:legend").map(|l| match l.child("c:legendPos").and_then(|p| p.attr("val")).unwrap_or("r") { "l" => Pos::Left, @@ -213,7 +226,15 @@ impl Series { // `c:marker/c:symbol`: which symbol each point gets (`none` for no markers). Scatter // series show markers unless the file says not; line series only when it says so. let symbol = ser.child("c:marker").and_then(|m| m.child("c:symbol")).and_then(|s| s.attr("val")).map(str::to_string); - let markers = symbol.map(|s| s != "none").or_else(|| scatter.then_some(true)); + let markers = symbol.as_deref().map(|s| s != "none").or_else(|| scatter.then_some(true)); + let symbol = symbol.as_deref().map_or(Symbol::Circle, Symbol::parse); + let marker_size = ser + .child("c:marker") + .and_then(|m| m.child("c:size")) + .and_then(|s| s.attr("val")) + .and_then(|v| v.trim().parse::().ok()) + .filter(|v| v.is_finite()) + .map(|v| v.clamp(2.0, 72.0)); let smooth = ser.child("c:smooth").and_then(|s| s.attr("val")).is_some_and(truthy); let (values, fmt) = numbers(ser.child(if scatter { "c:yVal" } else { "c:val" }), cap); let (mut xs, x_fmt) = if scatter { numbers(ser.child("c:xVal"), cap) } else { (Vec::new(), None) }; @@ -229,7 +250,27 @@ impl Series { } } let labels = show_values(ser.child("c:dLbls")); - Series { name, idx, color, line_w, line, no_fill, markers, smooth, values, xs, points, fmt, x_fmt, labels, raw: Vec::new() } + let label_fmt = label_format(ser.child("c:dLbls")); + Series { + name, + idx, + color, + line_w, + line, + no_fill, + markers, + symbol, + marker_size, + smooth, + values, + xs, + points, + fmt, + x_fmt, + labels, + label_fmt, + raw: Vec::new(), + } } } @@ -314,6 +355,12 @@ pub(super) fn axis(a: Option<&El>) -> Axis { .filter(|f| f.chars().count() <= craft_wordmodel::chart::MAX_FMT) .map(str::to_string), title: a.child("c:title").and_then(title_text), + title_rot: a + .child("c:title") + .and_then(|t| t.find("a:bodyPr")) + .and_then(|b| b.attr("rot")) + .and_then(|v| v.trim().parse::().ok()) + .map(|v| (v as f64 / 60_000.0).clamp(-360.0, 360.0) as f32), labels: a.child("c:tickLblPos").and_then(|p| p.attr("val")) != Some("none"), } } diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index eae203546..775d24eb2 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -1,10 +1,13 @@ use super::canvas::{Rect, clip_text, fill, rect_segs, runs, seg, stroke, text, text_angle, text_at, text_w, widest, wrap}; use super::format::format_value; -use super::model::{DataLabel, Grouping, Kind, Series}; +use super::model::{DataLabel, Grouping, Kind, Series, Symbol}; use super::parse::category_text; use super::polar::{draw_data_labels, label_of}; use super::{AXIS, Chart, El, GAP, GRID, GraphicItem, LINE, LINE_W, MAX_LABEL, MAX_TICKS, PathSeg, Rgb, ShapeKind, TextAlign, fill_colour, measure}; +/// Line width of the stroked marker symbols (x, plus, star), points. +const MARKER_STROKE: f32 = 1.5; + pub(super) fn label(s: &str) -> String { s.chars().take(MAX_LABEL).collect() } @@ -243,18 +246,21 @@ pub(super) fn cartesian(out: &mut Vec, c: &Chart, area: Rect) { } /// The axis titles, one line: the title of the vertical axis (the value axis for columns, the -/// category axis for bars) is rotated 90° on the plot's left; the horizontal axis's title sits +/// category axis for bars) is turned 90° on the plot's left; the horizontal axis's title sits /// under the plot. fn draw_axis_titles(out: &mut Vec, c: &Chart, g: &Frame, area: Rect) { let lh = c.text_size * LINE; // The axis drawn along the plot's left (the value axis for columns, the category axis for // bars) gets its title rotated there; the other axis's title sits under the plot. let (left, bottom) = if c.horizontal { (&c.cat, &c.val) } else { (&c.val, &c.cat) }; + // Word turns the vertical axis's title counter-clockwise (reading upwards) unless the file + // turns it the other way; a title with any other rotation would not fit the strip. + let up = if left.title_rot.is_some_and(|r| (r.rem_euclid(360.0) - 90.0).abs() < 1.0) { 90.0 } else { -90.0 }; if !left.deleted && let Some(t) = &left.title { let t = clip_text(t, g.plot.h, c.text_size); - text_angle(out, Rect { x: area.x, y: g.plot.y, w: lh, h: g.plot.h }, &t, c.text_size, TextAlign::Center, false, 90.0); + text_angle(out, Rect { x: area.x, y: g.plot.y, w: lh, h: g.plot.h }, &t, c.text_size, TextAlign::Center, false, up); } if !bottom.deleted && let Some(t) = &bottom.title @@ -481,18 +487,48 @@ fn lines(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, pts: impl Iterator, colour: Rgb) { +/// A series' point markers in the series' symbol and size (`colour` fills or strokes them), for +/// lines and scatter charts. +fn markers(out: &mut Vec, pts: impl Iterator, colour: Rgb, s: &Series) { const MARKER: f32 = 6.0; + let size = s.marker_size.filter(|v| v.is_finite()).unwrap_or(MARKER).clamp(2.0, 72.0); + let h = size / 2.0; + let shape = |out: &mut Vec, rect: [f32; 4], kind: ShapeKind| { + out.push(GraphicItem::Shape { rect, kind, fill: Some(colour), stroke: None, stroke_width: 0.0 }); + }; + let mut strokes = Vec::new(); for (x, y) in pts { - let rect = [x - MARKER / 2.0, y - MARKER / 2.0, MARKER, MARKER]; - out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(colour), stroke: None, stroke_width: 0.0 }); + match s.symbol { + Symbol::Circle => shape(out, [x - h, y - h, size, size], ShapeKind::Ellipse), + Symbol::Square => shape(out, [x - h, y - h, size, size], ShapeKind::Rectangle), + Symbol::Dot => shape(out, [x - h / 2.0, y - h / 2.0, h, h], ShapeKind::Ellipse), + Symbol::Dash => shape(out, [x - h, y - size / 6.0, size, size / 3.0], ShapeKind::Rectangle), + Symbol::Diamond => fill( + out, + vec![PathSeg::Move(x, y - h), PathSeg::Line(x + h, y), PathSeg::Line(x, y + h), PathSeg::Line(x - h, y), PathSeg::Close], + colour, + ), + Symbol::Triangle => { + fill(out, vec![PathSeg::Move(x, y - h), PathSeg::Line(x + h, y + h), PathSeg::Line(x - h, y + h), PathSeg::Close], colour) + } + Symbol::X | Symbol::Plus | Symbol::Star => { + if s.symbol != Symbol::Plus { + strokes.extend(seg(x - h, y - h, x + h, y + h)); + strokes.extend(seg(x - h, y + h, x + h, y - h)); + } + if s.symbol != Symbol::X { + strokes.extend(seg(x - h, y, x + h, y)); + strokes.extend(seg(x, y - h, x, y + h)); + } + } + } } + stroke(out, strokes, colour, MARKER_STROKE); } /// A polyline through `pts`, a smooth curve (Catmull-Rom pieces) when `smooth` and there are at @@ -582,10 +618,7 @@ fn draw_scatter(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut V stroke(out, curve(pts.iter().copied(), s.smooth), c.series_colour(j), s.line_w.unwrap_or(LINE_W)); } if s.markers != Some(false) { - for (x, y) in pts.iter().flatten() { - let rect = [x - MARKER / 2.0, y - MARKER / 2.0, MARKER, MARKER]; - out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(c.series_colour(j)), stroke: None, stroke_width: 0.0 }); - } + markers(out, pts.iter().flatten().copied(), c.series_colour(j), s); } } } diff --git a/crates/docx/src/read/chart/polar.rs b/crates/docx/src/read/chart/polar.rs index ec7768d5c..dbbe390db 100644 --- a/crates/docx/src/read/chart/polar.rs +++ b/crates/docx/src/read/chart/polar.rs @@ -134,13 +134,13 @@ pub(super) fn radar(out: &mut Vec, c: &Chart, area: Rect) { } /// The data label of point `i` of series `s`, when it shows one: the value as the file has it, -/// in the series' number format. +/// in the labels' own number format, else the series' one. pub(super) fn label_of(s: &Series, i: usize) -> Option { if s.labels != Some(true) { return None; } let v = s.raw.get(i).copied().flatten()?; - let fmt = s.fmt.as_deref().filter(|f| !f.eq_ignore_ascii_case("General")); + let fmt = s.label_fmt.as_deref().or(s.fmt.as_deref()).filter(|f| !f.eq_ignore_ascii_case("General")); Some(match fmt { Some(f) => format_value(v, f, 1.0), None => general_value(v), diff --git a/crates/docx/src/read/chart/tests.rs b/crates/docx/src/read/chart/tests.rs index 74573b5d8..b156817d2 100644 --- a/crates/docx/src/read/chart/tests.rs +++ b/crates/docx/src/read/chart/tests.rs @@ -656,3 +656,96 @@ fn category_gridlines_follow_the_points_when_the_axis_crosses_mid() { assert!(grid.iter().zip(&pts).all(|(g, p)| (g - p).abs() < 1e-3), "{cross}: grid {grid:?} points {pts:?}"); } } + +/// A line chart with one series; `extra` goes into the series (`c:marker`, `c:dLbls`), `axes` +/// into the value axis. +fn line_with(extra: &str, val_axis: &str) -> Vec { + let s = ser(0, "S", Some("FF0000"), &["Q1", "Q2", "Q3"], &["3.2", "4.1", "5"]).replace("", &format!("{extra}")); + let plot = format!( + r#"{s}{val_axis}"# + ); + chart_items(&space(&plot), &theme(), 300.0, 200.0) +} + +fn marker_xml(symbol: &str, size: u32) -> String { + format!(r#""#) +} + +#[test] +fn marker_symbols_are_drawn_as_their_shape() { + let shapes = |items: &[GraphicItem], kind: ShapeKind| { + items + .iter() + .filter(|it| matches!(it, GraphicItem::Shape { kind: k, rect, .. } if *k == kind && rect[2] > 3.0 && rect[2] < 20.0 && rect[3] > 1.0)) + .count() + }; + let paths = |items: &[GraphicItem], filled: bool| { + items + .iter() + .filter(|it| matches!(it, GraphicItem::Path { fill, segs, .. } if fill.is_some() == filled && segs.len() <= 12 && segs.len() >= 3)) + .count() + }; + // One marker per point, in the series' size. + let circle = line_with(&marker_xml("circle", 9), ""); + assert_eq!(shapes(&circle, ShapeKind::Ellipse), 3); + assert!(circle.iter().any(|it| matches!(it, GraphicItem::Shape { kind: ShapeKind::Ellipse, rect, .. } if (rect[2] - 9.0).abs() < 1e-3))); + let square = line_with(&marker_xml("square", 7), ""); + assert_eq!(shapes(&square, ShapeKind::Rectangle) - shapes(&circle, ShapeKind::Rectangle), 3, "a square per point"); + assert_eq!(shapes(&square, ShapeKind::Ellipse), 0, "no circles"); + // Diamonds and triangles are filled polygons; x, plus and star are strokes. + let base = paths(&line_with("", ""), true); + assert_eq!(paths(&line_with(&marker_xml("diamond", 7), ""), true) - base, 3); + assert_eq!(paths(&line_with(&marker_xml("triangle", 7), ""), true) - base, 3); + for symbol in ["x", "plus", "star"] { + let items = line_with(&marker_xml(symbol, 7), ""); + assert!(items.iter().any(|it| matches!(it, GraphicItem::Path { fill: None, stroke: Some(_), segs, .. } if segs.len() >= 6)), "{symbol}"); + assert_eq!(shapes(&items, ShapeKind::Ellipse), 0, "{symbol} is not a circle"); + } + // Dash and dot are small shapes; `none` and unknown names never crash (unknown: a circle). + assert_eq!(shapes(&line_with(&marker_xml("dash", 7), ""), ShapeKind::Rectangle) - shapes(&circle, ShapeKind::Rectangle), 3); + assert_eq!(shapes(&line_with(&marker_xml("dot", 7), ""), ShapeKind::Ellipse), 3); + assert_eq!(shapes(&line_with(&marker_xml("none", 7), ""), ShapeKind::Ellipse), 0); + assert_eq!(shapes(&line_with(&marker_xml("wibble", 7), ""), ShapeKind::Ellipse), 3); + // Hostile sizes are clamped. + for size in ["0", "99999999999", "-4", "x"] { + let items = line_with(&format!(r#""#), ""); + assert!(items.iter().all(|it| match it { + GraphicItem::Shape { rect, .. } => rect.iter().all(|v| v.is_finite()) && rect[2] <= 300.0, + _ => true, + })); + } +} + +#[test] +fn data_labels_use_their_own_format_code() { + let dl = |num: &str| format!(r#"{num}"#); + let shown = |items: &[GraphicItem]| -> Vec { + items.iter().filter_map(|it| if let GraphicItem::Text { text, .. } = it { Some(text.clone()) } else { None }).collect() + }; + let own = shown(&line_with(&dl(r#""#), "")); + assert!(own.contains(&"3.20".to_string()) && own.contains(&"5.00".to_string()), "{own:?}"); + // Linked to the source: the series' format (General here). + let linked = shown(&line_with(&dl(r#""#), "")); + assert!(linked.contains(&"3.2".to_string()) && linked.contains(&"5".to_string()), "{linked:?}"); + // A format code beyond the cap is ignored, not applied. + let long = "0".repeat(craft_wordmodel::chart::MAX_FMT + 1); + let capped = shown(&line_with(&dl(&format!(r#""#)), "")); + assert!(capped.contains(&"3.2".to_string()), "{capped:?}"); +} + +#[test] +fn value_axis_title_turns_counter_clockwise_like_word() { + let title = |body: &str| format!(r#"{body}Revenue"#); + let angle = |items: &[GraphicItem]| { + items.iter().find_map(|it| if let GraphicItem::Text { text, angle, .. } = it { (text == "Revenue").then_some(*angle) } else { None }) + }; + // The file's rotation (`-5400000` is 90° counter-clockwise), or Word's default when it says none. + assert_eq!(angle(&line_with("", &title(r#""#))), Some(-90.0)); + assert_eq!(angle(&line_with("", &title(""))), Some(-90.0)); + assert_eq!(angle(&line_with("", &title(r#""#))), Some(90.0)); + // A horizontal title has no room beside the plot: it stays turned up. + assert_eq!(angle(&line_with("", &title(r#""#))), Some(-90.0)); + // Hostile values stay finite. + let odd = angle(&line_with("", &title(r#""#))); + assert!(odd.is_some_and(f32::is_finite)); +} diff --git a/crates/wordmodel/src/graphic.rs b/crates/wordmodel/src/graphic.rs index f4a7bcf2e..cba7e766a 100644 --- a/crates/wordmodel/src/graphic.rs +++ b/crates/wordmodel/src/graphic.rs @@ -117,7 +117,7 @@ pub enum GraphicItem { }, /// One line of text in `rect`, aligned horizontally by `align`, centred vertically; `angle` /// degrees clockwise turns the text about `rect`'s centre as it is drawn (chart axis titles - /// use 90° for the vertical axis). + /// turn the vertical axis's title -90°, reading upwards, as Word does). Text { rect: [f32; 4], text: String, From 8761999c9b7c7144f58a1493529a857e31c19287 Mon Sep 17 00:00:00 2001 From: vangel76 <271991477+vangel76@users.noreply.github.com> Date: Sun, 15 Nov 2026 01:19:18 +0100 Subject: [PATCH 043/349] docx charts: automatic marker colour, data label positions, horizontal axis titles Word draws markers without their own fill in the automatic palette colour of the series index, not the explicit line colour. Line and scatter data labels sit to the right of the point unless c:dLblPos says t, b, l, r or ctr. A vertical-axis title with rot="0" stays horizontal, wrapped into a strip of at most a quarter of the chart width, instead of being forced to -90 degrees. Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/read/chart/model.rs | 31 +++++++++++ crates/docx/src/read/chart/parse.rs | 13 ++++- crates/docx/src/read/chart/plot.rs | 73 ++++++++++++++++++++----- crates/docx/src/read/chart/polar.rs | 15 ++++- crates/docx/src/read/chart/tests.rs | 85 ++++++++++++++++++++++++++++- 5 files changed, 198 insertions(+), 19 deletions(-) diff --git a/crates/docx/src/read/chart/model.rs b/crates/docx/src/read/chart/model.rs index 61d5d32d0..37d06e31f 100644 --- a/crates/docx/src/read/chart/model.rs +++ b/crates/docx/src/read/chart/model.rs @@ -7,6 +7,33 @@ pub(super) struct DataLabel { pub(super) y: f32, pub(super) text: String, pub(super) inside: bool, + /// Where a label that is not `inside` sits relative to (`x`, `y`). + pub(super) pos: LabelPos, + /// Distance from (`x`, `y`) to the label for `pos` other than `Center`, points (half the marker). + pub(super) off: f32, +} + +/// Where a data label sits beside its point (`c:dLblPos`: `t`, `b`, `l`, `r`, `ctr`). +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub(super) enum LabelPos { + Above, + Below, + Left, + Right, + Center, +} + +impl LabelPos { + pub(super) fn parse(v: &str) -> Option { + Some(match v.trim() { + "t" => LabelPos::Above, + "b" => LabelPos::Below, + "l" => LabelPos::Left, + "r" => LabelPos::Right, + "ctr" => LabelPos::Center, + _ => return None, + }) + } } #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -137,6 +164,10 @@ pub(super) struct Series { pub(super) labels: Option, /// The labels' own number format (`c:dLbls/c:numFmt` not linked to the source), if any. pub(super) label_fmt: Option, + /// The data labels' `c:dLblPos`, when the file gives a known one. + pub(super) label_pos: Option, + /// The marker's own fill (`c:marker/c:spPr`); without it markers take the automatic colour. + pub(super) marker_color: Option, /// The values as the file has them, for data labels (`values` become shares in a 100% /// stacked chart); empty when the series shows no labels. pub(super) raw: Vec>, diff --git a/crates/docx/src/read/chart/parse.rs b/crates/docx/src/read/chart/parse.rs index ec1508154..67b09d795 100644 --- a/crates/docx/src/read/chart/parse.rs +++ b/crates/docx/src/read/chart/parse.rs @@ -1,5 +1,5 @@ use super::format::{date_text, excel_stamp, format_value, is_date_code}; -use super::model::{Axis, Grouping, Kind, Pos, Series, Symbol}; +use super::model::{Axis, Grouping, Kind, LabelPos, Pos, Series, Symbol}; use super::plot::label; use super::{Chart, El, FONT, MAX_CELLS, MAX_POINTS, MAX_RADAR_SERIES, MAX_SERIES, MAX_SPOKES, Rgb, fill_colour, int, measure, slot}; @@ -102,6 +102,13 @@ impl Chart { s.and_then(|s| s.color).unwrap_or_else(|| self.accent(s.and_then(|s| s.idx).unwrap_or(j))) } + /// Colour of series `j`'s markers: the marker's own fill, else the automatic colour of the + /// series index (not the series' explicit line colour, as Word draws them). + pub(super) fn marker_colour(&self, j: usize) -> Rgb { + let s = self.series.get(j); + s.and_then(|s| s.marker_color).unwrap_or_else(|| self.accent(s.and_then(|s| s.idx).unwrap_or(j))) + } + /// Colour of point `i` of series `j`: its `c:dPt` override, else the varied accent (pie) or /// the series colour. pub(super) fn point_colour(&self, j: usize, i: usize) -> Rgb { @@ -219,6 +226,7 @@ impl Series { let sp = ser.child("c:spPr"); let ln = sp.and_then(|p| p.child("a:ln")); let marker = ser.child("c:marker").and_then(|m| m.child("c:spPr")).and_then(|p| fill_colour(p, theme)); + let marker_color = marker; let color = sp.and_then(|p| fill_colour(p, theme)).or_else(|| ln.and_then(|l| fill_colour(l, theme))).or(marker); let no_fill = sp.and_then(|p| p.child("a:noFill")).is_some(); let line_w = ln.and_then(|l| l.attr("w")).and_then(|v| measure(v, 12_700.0)).map(|w| w.clamp(0.0, 20.0)); @@ -251,6 +259,7 @@ impl Series { } let labels = show_values(ser.child("c:dLbls")); let label_fmt = label_format(ser.child("c:dLbls")); + let label_pos = ser.child("c:dLbls").and_then(|d| d.child("c:dLblPos")).and_then(|p| p.attr("val")).and_then(LabelPos::parse); Series { name, idx, @@ -269,6 +278,8 @@ impl Series { x_fmt, labels, label_fmt, + label_pos, + marker_color, raw: Vec::new(), } } diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index 775d24eb2..f671f1d49 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -1,6 +1,6 @@ use super::canvas::{Rect, clip_text, fill, rect_segs, runs, seg, stroke, text, text_angle, text_at, text_w, widest, wrap}; use super::format::format_value; -use super::model::{DataLabel, Grouping, Kind, Series, Symbol}; +use super::model::{DataLabel, Grouping, Kind, LabelPos, Series, Symbol}; use super::parse::category_text; use super::polar::{draw_data_labels, label_of}; use super::{AXIS, Chart, El, GAP, GRID, GraphicItem, LINE, LINE_W, MAX_LABEL, MAX_TICKS, PathSeg, Rgb, ShapeKind, TextAlign, fill_colour, measure}; @@ -164,7 +164,7 @@ fn axis_margins(c: &Chart, ax: &Axes, area: Rect) -> Margins { let scatter = c.kind == Kind::Scatter; let (cat_on, val_on) = (!c.cat.deleted, !c.val.deleted); let (cat_labels, val_labels) = (cat_on && c.cat.labels, val_on && c.val.labels); - let title = title_left(c, cat_on, val_on, lh); + let title = title_left(c, cat_on, val_on, area.w); let left = if c.horizontal { if cat_labels { widest(&c.cats, fs).min(area.w * 0.4) + GAP } else { 0.0 } } else if val_labels { @@ -195,9 +195,28 @@ fn axis_margins(c: &Chart, ax: &Axes, area: Rect) -> Margins { /// Room for the vertical axis title on the plot's left: one line when the axis that sits there /// (the value axis for columns, the category axis for bars) has a title. -fn title_left(c: &Chart, cat_on: bool, val_on: bool, lh: f32) -> f32 { +/// A horizontal title (`rot="0"`) gets a strip as wide as its wrapped lines, at most a quarter of +/// `area_w`, so the plot keeps its room. +fn title_left(c: &Chart, cat_on: bool, val_on: bool, area_w: f32) -> f32 { let side = if c.horizontal { cat_on && c.cat.title.is_some() } else { val_on && c.val.title.is_some() }; - if side { lh } else { 0.0 } + if !side { + return 0.0; + } + match flat_title_lines(c, area_w) { + Some(lines) => widest(&lines, c.text_size).min((area_w * 0.25).max(0.0)) + GAP, + None => c.text_size * LINE, + } +} + +/// The wrapped lines of the left axis's title when the file keeps it horizontal (`rot="0"`). +fn flat_title_lines(c: &Chart, area_w: f32) -> Option> { + let left = if c.horizontal { &c.cat } else { &c.val }; + let r = left.title_rot?.rem_euclid(360.0); + if !(r < 1.0 || r > 359.0) { + return None; + } + let width = if area_w.is_finite() { (area_w * 0.18).max(1.0) } else { 1.0 }; + left.title.as_ref().map(|t| wrap(t, width, c.text_size)) } /// Room for the horizontal axis title under the plot: one line when the axis that sits there @@ -236,7 +255,7 @@ pub(super) fn cartesian(out: &mut Vec, c: &Chart, area: Rect) { draw_axes(out, c, &g); draw_data_labels(out, &labels, c.text_size, g.horiz && c.kind == Kind::Bar); if !c.val.deleted && c.val.labels { - let room = title_left(c, !c.cat.deleted, true, c.text_size * LINE); + let room = title_left(c, !c.cat.deleted, true, area.w); draw_value_labels(out, c, &g, &ax.vticks, Rect { x: area.x + room, w: m.left - room, ..area }); } if !c.cat.deleted && c.cat.labels { @@ -254,9 +273,19 @@ fn draw_axis_titles(out: &mut Vec, c: &Chart, g: &Frame, area: Rect // bars) gets its title rotated there; the other axis's title sits under the plot. let (left, bottom) = if c.horizontal { (&c.cat, &c.val) } else { (&c.val, &c.cat) }; // Word turns the vertical axis's title counter-clockwise (reading upwards) unless the file - // turns it the other way; a title with any other rotation would not fit the strip. + // turns it the other way or keeps it horizontal (`rot="0"`, wrapped in its own strip); any + // other rotation would not fit the strip and is read as counter-clockwise. let up = if left.title_rot.is_some_and(|r| (r.rem_euclid(360.0) - 90.0).abs() < 1.0) { 90.0 } else { -90.0 }; if !left.deleted + && let Some(lines) = flat_title_lines(c, area.w) + { + let strip = (g.plot.x - area.x - GAP).max(1.0); + let top = g.plot.y + g.plot.h / 2.0 - lines.len() as f32 * lh / 2.0; + for (k, l) in lines.iter().enumerate() { + let l = clip_text(l, strip, c.text_size); + text_angle(out, Rect { x: area.x, y: top + k as f32 * lh, w: strip, h: lh }, &l, c.text_size, TextAlign::Center, false, 0.0); + } + } else if !left.deleted && let Some(t) = &left.title { let t = clip_text(t, g.plot.h, c.text_size); @@ -450,7 +479,7 @@ fn bars(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec (if v >= 0.0 { p1 } else { p0 }, mid), (false, false) => (mid, if v >= 0.0 { p0 } else { p1 }), }; - labels.push(DataLabel { x, y, text, inside: stacked }); + labels.push(DataLabel { x, y, text, inside: stacked, pos: LabelPos::Above, off: 0.0 }); } } } @@ -480,20 +509,32 @@ fn lines(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec f32 { + if drawn { s.marker_size.filter(|v| v.is_finite()).unwrap_or(6.0).clamp(2.0, 72.0) / 2.0 } else { 0.0 } +} + fn markers(out: &mut Vec, pts: impl Iterator, colour: Rgb, s: &Series) { const MARKER: f32 = 6.0; let size = s.marker_size.filter(|v| v.is_finite()).unwrap_or(MARKER).clamp(2.0, 72.0); @@ -588,7 +629,7 @@ fn areas(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec) { - const MARKER: f32 = 6.0; for (j, s) in c.series.iter().enumerate() { let pts: Vec> = s.xs.iter() @@ -611,14 +651,21 @@ fn draw_scatter(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut V .collect(); for (i, p) in pts.iter().enumerate() { if let (Some((x, y)), Some(text)) = (p, label_of(s, i)) { - labels.push(DataLabel { x: *x, y: *y - MARKER / 2.0, text, inside: false }); + labels.push(DataLabel { + x: *x, + y: *y, + text, + inside: false, + pos: s.label_pos.unwrap_or(LabelPos::Right), + off: marker_half(s, s.markers != Some(false)) + 2.0, + }); } } if s.line { stroke(out, curve(pts.iter().copied(), s.smooth), c.series_colour(j), s.line_w.unwrap_or(LINE_W)); } if s.markers != Some(false) { - markers(out, pts.iter().flatten().copied(), c.series_colour(j), s); + markers(out, pts.iter().flatten().copied(), c.marker_colour(j), s); } } } diff --git a/crates/docx/src/read/chart/polar.rs b/crates/docx/src/read/chart/polar.rs index dbbe390db..c686e746b 100644 --- a/crates/docx/src/read/chart/polar.rs +++ b/crates/docx/src/read/chart/polar.rs @@ -1,6 +1,6 @@ use super::canvas::{Rect, clip_text, fill, stroke, text, text_w, widest}; use super::format::format_value; -use super::model::{DataLabel, Kind, Series}; +use super::model::{DataLabel, Kind, LabelPos, Series}; use super::plot::{Axes, has_values}; use super::{Chart, FRAC_PI_2, GAP, GRID, GraphicItem, LINE, LINE_W, PathSeg, Rgb, ShapeKind, TAU, TEXT, TextAlign}; @@ -38,7 +38,7 @@ pub(super) fn pie(out: &mut Vec, c: &Chart, area: Rect) { // Halfway across the ring (pie: two thirds out from the centre). let at = if inner > 0.0 { (r + inner) / 2.0 } else { r * 0.65 }; let (x, y) = polar(cx, cy, at, (a + b) / 2.0); - labels.push(DataLabel { x: x as f32, y: y as f32, text, inside: true }); + labels.push(DataLabel { x: x as f32, y: y as f32, text, inside: true, pos: LabelPos::Above, off: 0.0 }); } a = b; } @@ -99,7 +99,7 @@ pub(super) fn radar(out: &mut Vec, c: &Chart, area: Rect) { out.push(GraphicItem::Shape { rect, kind: ShapeKind::Ellipse, fill: Some(col), stroke: None, stroke_width: 0.0 }); } if let Some(text) = label_of(s, i) { - labels.push(DataLabel { x: p.0 as f32, y: p.1 as f32, text, inside: false }); + labels.push(DataLabel { x: p.0 as f32, y: p.1 as f32, text, inside: false, pos: LabelPos::Above, off: 0.0 }); } } } @@ -165,6 +165,15 @@ pub(super) fn draw_data_labels(out: &mut Vec, labels: &[DataLabel], let w = text_w(&l.text, fs) + 4.0; let (rect, align) = if l.inside { (Rect { x: l.x - w / 2.0, y: l.y - lh / 2.0, w, h: lh }, TextAlign::Center) + } else if l.off > 0.0 || l.pos != LabelPos::Above { + let o = l.off; + match l.pos { + LabelPos::Right => (Rect { x: l.x + o, y: l.y - lh / 2.0, w, h: lh }, TextAlign::Left), + LabelPos::Left => (Rect { x: l.x - o - w, y: l.y - lh / 2.0, w, h: lh }, TextAlign::Right), + LabelPos::Below => (Rect { x: l.x - w / 2.0, y: l.y + o, w, h: lh }, TextAlign::Center), + LabelPos::Center => (Rect { x: l.x - w / 2.0, y: l.y - lh / 2.0, w, h: lh }, TextAlign::Center), + LabelPos::Above => (Rect { x: l.x - w / 2.0, y: l.y - o - lh, w, h: lh }, TextAlign::Center), + } } else if beside_right { (Rect { x: l.x + GAP / 2.0, y: l.y - lh / 2.0, w, h: lh }, TextAlign::Left) } else { diff --git a/crates/docx/src/read/chart/tests.rs b/crates/docx/src/read/chart/tests.rs index b156817d2..e5d7e4db6 100644 --- a/crates/docx/src/read/chart/tests.rs +++ b/crates/docx/src/read/chart/tests.rs @@ -743,9 +743,90 @@ fn value_axis_title_turns_counter_clockwise_like_word() { assert_eq!(angle(&line_with("", &title(r#""#))), Some(-90.0)); assert_eq!(angle(&line_with("", &title(""))), Some(-90.0)); assert_eq!(angle(&line_with("", &title(r#""#))), Some(90.0)); - // A horizontal title has no room beside the plot: it stays turned up. - assert_eq!(angle(&line_with("", &title(r#""#))), Some(-90.0)); + // A horizontal title (`rot="0"`) stays horizontal: the plot makes room for it (see below). + assert_eq!(angle(&line_with("", &title(r#""#))), Some(0.0)); // Hostile values stay finite. let odd = angle(&line_with("", &title(r#""#))); assert!(odd.is_some_and(f32::is_finite)); } + +fn first_ellipse(items: &[GraphicItem]) -> Option<([f32; 4], Rgb)> { + items.iter().find_map(|it| match it { + GraphicItem::Shape { kind: ShapeKind::Ellipse, rect, fill: Some(c), .. } if rect[2] > 3.0 && rect[2] < 20.0 => Some((*rect, *c)), + _ => None, + }) +} + +#[test] +fn markers_use_the_automatic_series_colour_not_the_line_colour() { + // The series has an explicit red line/fill but no marker fill: Word draws the markers in the + // palette colour of the series index (accent 1 here). + let items = line_with(&marker_xml("circle", 9), ""); + assert_eq!(first_ellipse(&items).map(|e| e.1), Some(theme()[4])); + // A marker's own fill wins. + let own = + r#""#; + assert_eq!(first_ellipse(&line_with(own, "")).map(|e| e.1), Some(Rgb(0, 0xAA, 0))); +} + +#[test] +fn line_data_labels_default_to_the_right_and_honour_dlblpos() { + let dl = |pos: &str| format!(r#"{}{pos}"#, marker_xml("circle", 9)); + let text_rect = |items: &[GraphicItem]| { + items.iter().find_map(|it| if let GraphicItem::Text { text, rect, .. } = it { (text == "3.2").then_some(*rect) } else { None }) + }; + let at = |pos: &str| { + let items = line_with(&dl(pos), ""); + let (m, _) = first_ellipse(&items).unwrap(); + let t = text_rect(&items).unwrap(); + // Centre of the marker and of the label box. + ((t[0] + t[2] / 2.0) - (m[0] + m[2] / 2.0), (t[1] + t[3] / 2.0) - (m[1] + m[3] / 2.0), t, m) + }; + let (dx, dy, t, m) = at(""); + assert!(t[0] >= m[0] + m[2] && dy.abs() < 1.0, "default is right of the marker: {dx} {dy}"); + let (dx, dy, t, m) = at(r#""#); + assert!(t[0] >= m[0] + m[2] && dy.abs() < 1.0, "{dx} {dy}"); + let (dx, dy, _, _) = at(r#""#); + assert!(dx.abs() < 1.0 && dy < -4.0, "{dx} {dy}"); + let (dx, dy, _, _) = at(r#""#); + assert!(dx.abs() < 1.0 && dy > 4.0, "{dx} {dy}"); + let (dx, dy, t, m) = at(r#""#); + assert!(t[0] + t[2] <= m[0] && dy.abs() < 1.0, "{dx} {dy}"); + let (dx, dy, _, _) = at(r#""#); + assert!(dx.abs() < 1.0 && dy.abs() < 1.0, "{dx} {dy}"); + // Unknown positions fall back to the default. + let (_, _, t, m) = at(r#""#); + assert!(t[0] >= m[0] + m[2]); +} + +#[test] +fn horizontal_value_axis_title_gets_its_own_strip() { + let title = |rot: &str, name: &str| { + format!(r#"{name}"#) + }; + let plot_left = |items: &[GraphicItem]| { + // The first gridline's start is the plot's left edge. + items.iter().find_map(|it| match it { + GraphicItem::Path { segs, stroke: Some(_), fill: None, .. } if segs.len() == 2 => match segs.first() { + Some(PathSeg::Move(x, _)) => Some(*x), + _ => None, + }, + _ => None, + }) + }; + let rect_of = |items: &[GraphicItem], name: &str| { + items.iter().find_map(|it| if let GraphicItem::Text { text, rect, .. } = it { text.starts_with(name).then_some(*rect) } else { None }) + }; + let turned = line_with("", &title(r#" rot="-5400000" vert="horz""#, "Revenue")); + let flat = line_with("", &title(r#" rot="0" vert="horz""#, "Revenue")); + let (a, b) = (plot_left(&turned).unwrap(), plot_left(&flat).unwrap()); + assert!(b > a + 10.0, "a horizontal title takes more room than a turned one: {a} {b}"); + // The title box lies left of the plot and inside the chart. + let r = rect_of(&flat, "Revenue").unwrap(); + assert!(r[0] >= 0.0 && r[0] + r[2] <= b + 0.5, "{r:?} {b}"); + // A hostile title never takes more than a quarter of the width and stays finite. + let long = "Wibble ".repeat(500); + let items = line_with("", &title(r#" rot="0""#, &long)); + let p = plot_left(&items).unwrap(); + assert!(p.is_finite() && p <= 300.0 * 0.3, "{p}"); +} From 6767c7136297160cfca1460943b87f46a236cd8d Mon Sep 17 00:00:00 2001 From: vangel76 <271991477+vangel76@users.noreply.github.com> Date: Sun, 15 Nov 2026 02:26:31 +0100 Subject: [PATCH 044/349] Re-run CI: the Ubuntu gate timed out Co-Authored-By: Claude Sonnet 5.5 From 2e3ff2162bbf0ee24dc225fc54df19eb4e539547 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 11:44:48 +0100 Subject: [PATCH 045/349] craft-image-codecs: SGI image reader and writer Adds Format::Sgi: 8- and 16-bit gray, gray+alpha, RGB and RGBA, verbatim and run-length encoded on read, run-length encoded on write. Palette-mapped files are reported as unsupported. Closes #1559 --- crates/image-codecs/README.md | 1 + crates/image-codecs/src/codecs.rs | 1 + crates/image-codecs/src/codecs/sgi.rs | 345 ++++++++++++++++++++ crates/image-codecs/src/format.rs | 14 +- crates/image-codecs/src/lib.rs | 4 +- crates/image-codecs/tests/it/detect_caps.rs | 17 + 6 files changed, 379 insertions(+), 3 deletions(-) create mode 100644 crates/image-codecs/src/codecs/sgi.rs diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 6e9e11617..135853490 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 | +| SGI (`.sgi`, `.rgb`, `.bw`) | yes | yes (RLE) | U8, U16 | Gray, Gray+A, RGB, RGBA | yes | 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..6f070a290 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -17,6 +17,7 @@ pub(crate) mod jxl; pub(crate) mod pcx; pub(crate) mod png; pub(crate) mod pnm; +pub(crate) mod sgi; pub(crate) mod tga; pub(crate) mod tiff; pub(crate) mod tiff_exif; diff --git a/crates/image-codecs/src/codecs/sgi.rs b/crates/image-codecs/src/codecs/sgi.rs new file mode 100644 index 000000000..1e31b5f0a --- /dev/null +++ b/crates/image-codecs/src/codecs/sgi.rs @@ -0,0 +1,345 @@ +//! SGI image files (`.sgi`, `.rgb`, `.rgba`, `.bw`): 8- and 16-bit gray, gray + alpha, RGB and +//! RGBA, verbatim or run-length encoded. +//! +//! Read and write follow the published SGI image file format description: a 512-byte big-endian +//! header, then one plane per channel with the rows stored bottom to top. Palette-mapped files +//! (colormap ID other than 0) are rejected. The writer uses the run-length encoding. + +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::Sgi; +const HEADER: usize = 512; +const MAGIC: u16 = 474; + +fn bad(reason: impl std::fmt::Display) -> CodecError { + CodecError::malformed(F, reason) +} + +fn be16(b: &[u8], i: usize) -> u16 { + u16::from_be_bytes([b[i], b[i + 1]]) +} + +fn be32(b: &[u8], i: usize) -> u32 { + u32::from_be_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]) +} + +/// The fields of the header that decoding needs, already checked for plausibility. +struct Header { + rle: bool, + wide: bool, + width: u32, + height: u32, + planes: usize, +} + +/// Parse the 512-byte header. `None` when the bytes are not a plausible SGI header. +fn header(b: &[u8]) -> Option
                      { + if b.len() < HEADER || be16(b, 0) != MAGIC { + return None; + } + let (storage, bpc, dimension) = (b[2], b[3], be16(b, 4)); + let (width, height, planes) = (u32::from(be16(b, 6)), u32::from(be16(b, 8)), usize::from(be16(b, 10))); + if storage > 1 || !(1..=2).contains(&bpc) || !(1..=3).contains(&dimension) { + return None; + } + // A one-dimensional image has one row, a two-dimensional one a single plane. + let (height, planes) = match dimension { + 1 => (1, 1), + 2 => (height, 1), + _ => (height, planes), + }; + if width == 0 || height == 0 || !(1..=4).contains(&planes) { + return None; + } + Some(Header { rle: storage == 1, wide: bpc == 2, width, height, planes }) +} + +/// Whether `b` starts with a plausible SGI header (the magic number plus consistent fields). +pub(crate) fn looks_like_sgi(b: &[u8]) -> bool { + header(b).is_some() +} + +fn layout_of(planes: usize) -> ChannelLayout { + match planes { + 1 => ChannelLayout::Gray, + 2 => ChannelLayout::GrayA, + 3 => ChannelLayout::Rgb, + _ => ChannelLayout::Rgba, + } +} + +/// Expand one run-length encoded row into exactly `out.len()` samples. +fn read_rle_row(src: &[u8], wide: bool, out: &mut [u16]) -> Result<(), CodecError> { + let step = if wide { 2 } else { 1 }; + let sample = |pos: usize| -> Result { + let s = src.get(pos..pos + step).ok_or_else(|| bad("truncated RLE row"))?; + Ok(if wide { u16::from_be_bytes([s[0], s[1]]) } else { u16::from(s[0]) }) + }; + let (mut pos, mut n) = (0usize, 0usize); + while n < out.len() { + let code = sample(pos)?; + pos += step; + let count = usize::from(code & 0x7f); + if count == 0 { + return Err(bad("RLE row ends before the image width")); + } + if count > out.len() - n { + return Err(bad("RLE packet runs past the end of the row")); + } + if code & 0x80 != 0 { + for slot in &mut out[n..n + count] { + *slot = sample(pos)?; + pos += step; + } + } else { + let value = sample(pos)?; + pos += step; + out[n..n + count].fill(value); + } + n += count; + } + Ok(()) +} + +pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { + let h = header(b).ok_or_else(|| bad("invalid SGI header"))?; + if be32(b, 104) != 0 { + return Err(CodecError::unsupported(F, "palette-mapped SGI files are not supported")); + } + let layout = layout_of(h.planes); + let sample = if h.wide { SampleType::U16 } else { SampleType::U8 }; + limits.check(h.width, h.height, layout, sample)?; + let (w, ht, planes) = (h.width as usize, h.height as usize, h.planes); + let rows = ht.checked_mul(planes).ok_or_else(|| bad("image size overflow"))?; + let bps = if h.wide { 2 } else { 1 }; + let total = w.checked_mul(rows).ok_or_else(|| bad("image size overflow"))?; + // Reject inputs that cannot hold the declared pixels before allocating anything for them. + let table = if h.rle { rows.checked_mul(8).ok_or_else(|| bad("image size overflow"))? } else { 0 }; + let min_len = if h.rle { + // Every row needs at least a packet and a terminator. + HEADER + table + rows * bps + } else { + HEADER + total.checked_mul(bps).ok_or_else(|| bad("image size overflow"))? + }; + if b.len() < min_len { + return Err(bad("the file is too short for the declared image")); + } + let mut out = Vec::new(); + out.try_reserve_exact(total).map_err(|_| bad("pixel buffer is too large"))?; + out.resize(total, 0u16); + let mut row = vec![0u16; w]; + for z in 0..planes { + for y in 0..ht { + let index = y + z * ht; + if h.rle { + let start = be32(b, HEADER + index * 4) as usize; + let len = be32(b, HEADER + rows * 4 + index * 4) as usize; + let end = start.checked_add(len).filter(|&e| e <= b.len() && start >= HEADER).ok_or_else(|| bad("RLE row lies outside the file"))?; + read_rle_row(&b[start..end], h.wide, &mut row)?; + } else { + let start = HEADER + index * w * bps; + let s = &b[start..start + w * bps]; + for (x, v) in row.iter_mut().enumerate() { + *v = if h.wide { u16::from_be_bytes([s[2 * x], s[2 * x + 1]]) } else { u16::from(s[x]) }; + } + } + // Rows are stored bottom to top; planes are separate. + let top_y = ht - 1 - y; + for (x, &v) in row.iter().enumerate() { + out[(top_y * w + x) * planes + z] = v; + } + } + } + if h.wide { + Image::from_u16(h.width, h.height, layout, &out) + } else { + Image::from_u8(h.width, h.height, layout, out.iter().map(|&v| v as u8).collect()) + } +} + +/// Append one run-length encoded row (one packet list and a terminator). +fn write_rle_row(row: &[u16], wide: bool, out: &mut Vec) { + let put = |out: &mut Vec, v: u16| { + if wide { + out.extend_from_slice(&v.to_be_bytes()); + } else { + out.push(v as u8); + } + }; + let mut i = 0; + while i < row.len() { + let mut run = 1; + while i + run < row.len() && run < 127 && row[i + run] == row[i] { + run += 1; + } + if run >= 2 { + put(out, run as u16); + put(out, row[i]); + i += run; + } else { + // A literal packet extends until the next run of two or more. + let mut end = i + 1; + while end < row.len() && end - i < 127 && !(end + 1 < row.len() && row[end] == row[end + 1]) { + end += 1; + } + put(out, 0x80 | (end - i) as u16); + for &v in &row[i..end] { + put(out, v); + } + i = end; + } + } + put(out, 0); +} + +/// Writes a run-length encoded SGI file: 8 or 16 bits per channel, gray, gray + alpha, RGB or RGBA. +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 wide = match img.sample_type() { + SampleType::U8 => false, + SampleType::U16 => true, + s => return Err(enc(format!("SGI stores 8 or 16 bits per channel, not {s:?}"))), + }; + let planes = img.layout().channels(); + if !matches!(img.layout(), ChannelLayout::Gray | ChannelLayout::GrayA | ChannelLayout::Rgb | ChannelLayout::Rgba) { + return Err(enc(format!("no SGI layout for {:?}", img.layout()))); + } + let (w, ht) = img.dimensions(); + let (Ok(w16), Ok(h16)) = (u16::try_from(w), u16::try_from(ht)) else { + return Err(enc(format!("dimensions exceed 65535x65535: {w}x{ht}"))); + }; + let (w, ht) = (w as usize, ht as usize); + let bps = if wide { 2 } else { 1 }; + let data = img.data(); + if data.len() != w * ht * planes * bps { + return Err(enc("the image has the wrong number of samples".into())); + } + let sample_at = |i: usize| -> u16 { if wide { u16::from_ne_bytes([data[2 * i], data[2 * i + 1]]) } else { u16::from(data[i]) } }; + let rows = ht * planes; + let table = HEADER; + let mut starts = Vec::with_capacity(rows); + let mut lens = Vec::with_capacity(rows); + let mut body = Vec::new(); + let mut row = vec![0u16; w]; + let base = u32::try_from(HEADER + rows * 8).map_err(|_| enc("image too large".into()))?; + for z in 0..planes { + for y in 0..ht { + let src_y = ht - 1 - y; // stored bottom to top + for (x, v) in row.iter_mut().enumerate() { + *v = sample_at((src_y * w + x) * planes + z); + } + let before = body.len(); + write_rle_row(&row, wide, &mut body); + let start = u32::try_from(base as usize + before).map_err(|_| enc("image too large".into()))?; + starts.push(start); + lens.push((body.len() - before) as u32); + } + } + let mut out = Vec::with_capacity(table + rows * 8 + body.len()); + out.extend_from_slice(&MAGIC.to_be_bytes()); + out.push(1); // RLE + out.push(bps as u8); + out.extend_from_slice(&(if planes > 1 { 3u16 } else { 2u16 }).to_be_bytes()); + out.extend_from_slice(&w16.to_be_bytes()); + out.extend_from_slice(&h16.to_be_bytes()); + out.extend_from_slice(&(planes as u16).to_be_bytes()); + out.extend_from_slice(&0u32.to_be_bytes()); // pixmin + out.extend_from_slice(&(if wide { 65535u32 } else { 255 }).to_be_bytes()); // pixmax + out.resize(HEADER, 0); // dummy, image name, colormap 0, padding + for s in &starts { + out.extend_from_slice(&s.to_be_bytes()); + } + for l in &lens { + out.extend_from_slice(&l.to_be_bytes()); + } + out.extend_from_slice(&body); + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn gradient(w: u32, h: u32, layout: ChannelLayout) -> Image { + let ch = layout.channels(); + let data = (0..w as usize * h as usize * ch).map(|i| ((i * 7 + i / 5) % 251) as u8).collect(); + Image::from_u8(w, h, layout, data).unwrap() + } + + #[test] + fn rle_round_trips_every_layout_in_8_bits() { + for layout in [ChannelLayout::Gray, ChannelLayout::GrayA, ChannelLayout::Rgb, ChannelLayout::Rgba] { + let img = gradient(37, 11, layout); + let plan = Plan { layout, sample: SampleType::U8 }; + let bytes = encode(&img, plan).unwrap(); + assert!(looks_like_sgi(&bytes)); + let back = decode(&bytes, &Limits::default()).unwrap(); + assert_eq!(back.layout(), layout); + assert_eq!(back.data(), img.data()); + } + } + + #[test] + fn rle_round_trips_16_bits_with_long_runs() { + let (w, h) = (300u32, 4u32); + let samples: Vec = (0..w * h * 3).map(|i| if (i / 3) % 200 < 150 { 4242 } else { (i * 31) as u16 }).collect(); + let img = Image::from_u16(w, h, ChannelLayout::Rgb, &samples).unwrap(); + let bytes = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U16 }).unwrap(); + let back = decode(&bytes, &Limits::default()).unwrap(); + assert_eq!(back.sample_type(), SampleType::U16); + assert_eq!(back.data(), img.data()); + } + + /// A hand-built verbatim file: two rows, one plane, stored bottom to top. + #[test] + fn verbatim_files_read_bottom_to_top() { + let mut f = vec![0u8; HEADER]; + f[0..2].copy_from_slice(&MAGIC.to_be_bytes()); + f[2] = 0; // verbatim + f[3] = 1; + f[4..6].copy_from_slice(&2u16.to_be_bytes()); + f[6..8].copy_from_slice(&3u16.to_be_bytes()); // x + f[8..10].copy_from_slice(&2u16.to_be_bytes()); // y + f[10..12].copy_from_slice(&1u16.to_be_bytes()); // z + f.extend_from_slice(&[10, 11, 12, 20, 21, 22]); // bottom row first + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!(img.layout(), ChannelLayout::Gray); + assert_eq!(img.data(), &[20, 21, 22, 10, 11, 12]); + } + + #[test] + fn hostile_input_is_an_error_not_a_panic() { + let img = gradient(16, 8, ChannelLayout::Rgb); + let good = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U8 }).unwrap(); + // Every truncation fails cleanly. + for len in 0..good.len() { + let _ = decode(&good[..len], &Limits::default()); + } + // A row table pointing outside the file, and a packet that overruns its row. + let mut bad_table = good.clone(); + bad_table[HEADER..HEADER + 4].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&bad_table, &Limits::default()).is_err()); + let mut overrun = good.clone(); + let start = be32(&overrun, HEADER) as usize; + overrun[start] = 127; // a run longer than the 16-pixel row + assert!(decode(&overrun, &Limits::default()).is_err()); + // A huge declared size is stopped by the limits or the length check, before allocating. + let mut huge = good; + huge[6..8].copy_from_slice(&u16::MAX.to_be_bytes()); + huge[8..10].copy_from_slice(&u16::MAX.to_be_bytes()); + assert!(decode(&huge, &Limits::default()).is_err()); + } + + #[test] + fn palette_mapped_files_are_unsupported() { + let img = gradient(4, 4, ChannelLayout::Gray); + let mut f = encode(&img, Plan { layout: ChannelLayout::Gray, sample: SampleType::U8 }).unwrap(); + f[104..108].copy_from_slice(&1u32.to_be_bytes()); + assert!(matches!(decode(&f, &Limits::default()), Err(CodecError::Unsupported { .. }))); + } +} diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index ecaf945cd..d0d938bb7 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, + /// SGI image files (`.sgi`, `.rgb`, `.bw`): 8- and 16-bit gray, gray + alpha, RGB and RGBA. + Sgi, } /// 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::Sgi, ]; pub fn caps(self) -> FormatCaps { @@ -176,6 +179,7 @@ impl Format { Format::Dicom => "DICOM", Format::Iff => "Amiga IFF", Format::Jp2 => "JPEG 2000", + Format::Sgi => "SGI", } } @@ -207,6 +211,7 @@ impl Format { Format::Dicom => &["dcm", "dicom", "dc3"], Format::Iff => &["iff", "lbm", "ilbm"], Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"], + Format::Sgi => &["sgi", "rgb", "rgba", "bw"], } } @@ -236,13 +241,14 @@ impl Format { Format::Dicom => "application/dicom", Format::Iff => "image/x-iff", Format::Jp2 => "image/jp2", + Format::Sgi => "image/x-sgi", } } /// 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::Sgi => 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::Sgi => FormatCaps { depths: &[S::U8, S::U16], layouts: RGB_GRAY, alpha: true, ..base }, Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base }, } } @@ -388,6 +395,9 @@ pub fn detect(bytes: &[u8]) -> Option { if b.starts_with(b"/* XPM */") || b.starts_with(b"! XPM2\n") || b.starts_with(b"! XPM2\r\n") { return Some(Format::Xpm); } + if crate::codecs::sgi::looks_like_sgi(b) { + return Some(Format::Sgi); + } if crate::codecs::pcx::looks_like_pcx(b) { return Some(Format::Pcx); } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 21130e392..cad63019d 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, jxl, pcx, png, pnm, sgi, 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::Sgi => sgi::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::Sgi => sgi::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..d7d448388 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::Sgi, ]; for f in expected { assert!(caps(f).read && caps(f).write, "{f:?}"); @@ -218,6 +219,22 @@ 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_sgi() { + use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode}; + let img = Image::from_u8(5, 3, ChannelLayout::Rgba, (0..60).collect()).unwrap(); + let bytes = encode(&img, Format::Sgi, &EncodeOptions::default()).unwrap(); + assert_eq!(detect(&bytes), Some(Format::Sgi)); + assert_eq!(from_extension("scan.RGB"), Some(Format::Sgi)); + assert_eq!(from_extension("scan.bw"), Some(Format::Sgi)); + assert_eq!(decode(&bytes).unwrap().data(), img.data()); + assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::Sgi)); + assert_eq!(Format::Sgi.max_dimensions(), Some((65535, 65535))); + // The magic number alone, without a full header, is not SGI. + assert_eq!(detect(&[0x01, 0xda, 0, 1, 0, 2]), None); + assert!(decode_as(Format::Sgi, &[0x01, 0xda]).is_err()); +} + #[test] fn detect_magic_avif() { assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif)); From 5628ad359d8f5bf9778f53edba9b9989b4b61d09 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 11:49:53 +0100 Subject: [PATCH 046/349] craft-image-codecs: Sun Raster image reader and writer Adds Format::SunRaster: 1-, 8- (gray or colour-mapped), 24- and 32-bit files, uncompressed or byte-encoded (RLE) on read, uncompressed on write. Closes #1560 --- crates/image-codecs/README.md | 1 + crates/image-codecs/src/codecs.rs | 1 + crates/image-codecs/src/codecs/sunraster.rs | 237 ++++++++++++++++++++ crates/image-codecs/src/format.rs | 12 +- crates/image-codecs/src/lib.rs | 4 +- crates/image-codecs/tests/it/detect_caps.rs | 14 ++ 6 files changed, 267 insertions(+), 2 deletions(-) create mode 100644 crates/image-codecs/src/codecs/sunraster.rs diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 6e9e11617..f9f5f53e6 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 | +| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, Gray+A, RGB, RGBA | yes | 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..aecf95bbd 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -17,6 +17,7 @@ pub(crate) mod jxl; pub(crate) mod pcx; pub(crate) mod png; pub(crate) mod pnm; +pub(crate) mod sunraster; pub(crate) mod tga; pub(crate) mod tiff; pub(crate) mod tiff_exif; diff --git a/crates/image-codecs/src/codecs/sunraster.rs b/crates/image-codecs/src/codecs/sunraster.rs new file mode 100644 index 000000000..84d60f145 --- /dev/null +++ b/crates/image-codecs/src/codecs/sunraster.rs @@ -0,0 +1,237 @@ +//! Sun Raster files (`.ras`, `.sun`): 1-bit, 8-bit (gray or colour-mapped), 24-bit RGB and 32-bit +//! RGBA, uncompressed or byte-encoded (RLE) on read; uncompressed on write. +//! +//! Follows the published rasterfile format: a 32-byte big-endian header, an optional colour map, +//! then rows padded to an even number of bytes. In the "standard" type (1) 24- and 32-bit pixels +//! are stored blue-first; in the "RGB" type (3) red-first. Other types (TIFF, IFF, experimental) +//! are reported as unsupported. + +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::SunRaster; +const HEADER: usize = 32; +const MAGIC: u32 = 0x59a6_6a95; + +fn bad(reason: impl std::fmt::Display) -> CodecError { + CodecError::malformed(F, reason) +} + +fn be32(b: &[u8], i: usize) -> u32 { + u32::from_be_bytes([b[i], b[i + 1], b[i + 2], b[i + 3]]) +} + +/// Whether `b` starts with a Sun rasterfile header. +pub(crate) fn looks_like_sunraster(b: &[u8]) -> bool { + b.len() >= HEADER && be32(b, 0) == MAGIC && matches!(be32(b, 12), 1 | 8 | 24 | 32) +} + +/// Expand byte-encoded data (`0x80` escapes a run) until `want` bytes are produced. +fn unrle(src: &[u8], want: usize) -> Result, CodecError> { + let mut out = Vec::new(); + out.try_reserve_exact(want).map_err(|_| bad("pixel buffer is too large"))?; + let mut i = 0; + while out.len() < want { + let b = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?; + i += 1; + if b != 0x80 { + out.push(b); + continue; + } + let n = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?; + i += 1; + if n == 0 { + out.push(0x80); + continue; + } + let v = *src.get(i).ok_or_else(|| bad("truncated RLE data"))?; + i += 1; + let count = usize::from(n) + 1; + if count > want - out.len() { + return Err(bad("RLE run passes the end of the image")); + } + out.resize(out.len() + count, v); + } + Ok(out) +} + +pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { + if !looks_like_sunraster(b) { + return Err(bad("invalid Sun raster header")); + } + let (w, h, depth, kind, map_type, map_len) = (be32(b, 4), be32(b, 8), be32(b, 12) as usize, be32(b, 20), be32(b, 24), be32(b, 28) as usize); + if !matches!(kind, 0..=3) { + return Err(CodecError::unsupported(F, format!("Sun raster type {kind} is not supported"))); + } + if map_type > 2 { + return Err(CodecError::unsupported(F, format!("Sun raster map type {map_type} is not supported"))); + } + let layout = match depth { + 1 | 8 if map_type != 1 => ChannelLayout::Gray, + 1 | 8 | 24 => ChannelLayout::Rgb, + _ => ChannelLayout::Rgba, + }; + limits.check(w, h, layout, SampleType::U8)?; + let (wu, hu) = (w as usize, h as usize); + let stride = wu.checked_mul(depth).and_then(|n| n.checked_add(15)).ok_or_else(|| bad("image size overflow"))? / 16 * 2; + let want = stride.checked_mul(hu).ok_or_else(|| bad("image size overflow"))?; + let data_at = HEADER.checked_add(map_len).ok_or_else(|| bad("colour map size overflow"))?; + let map = b.get(HEADER..data_at).ok_or_else(|| bad("truncated colour map"))?; + let rest = &b[data_at..]; + let raw; + let rows: &[u8] = if kind == 2 { + raw = unrle(rest, want)?; + &raw + } else { + rest.get(..want).ok_or_else(|| bad("the file is too short for the declared image"))? + }; + let channels = layout.channels(); + let mut out = Vec::new(); + out.try_reserve_exact(wu * hu * channels).map_err(|_| bad("pixel buffer is too large"))?; + let entries = map_len / 3; + for y in 0..hu { + let row = &rows[y * stride..(y + 1) * stride]; + for x in 0..wu { + match depth { + 1 => { + // A set bit is black. + let bit = (row[x / 8] >> (7 - x % 8)) & 1; + out.push(if bit == 1 { 0 } else { 255 }); + } + 8 if map_type == 1 => { + let i = usize::from(row[x]); + if i >= entries { + return Err(bad("pixel index is outside the colour map")); + } + out.extend_from_slice(&[map[i], map[entries + i], map[2 * entries + i]]); + } + 8 => out.push(row[x]), + 24 => { + let p = &row[3 * x..3 * x + 3]; + out.extend_from_slice(&if kind == 3 { [p[0], p[1], p[2]] } else { [p[2], p[1], p[0]] }); + } + _ => { + let p = &row[4 * x..4 * x + 4]; + out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], p[0]] }); + } + } + } + } + Image::from_u8(w, h, layout, out) +} + +/// Writes an uncompressed rasterfile: 8-bit gray, 24-bit RGB or 32-bit RGBA, in the RGB-ordered type. +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); + if img.sample_type() != SampleType::U8 { + return Err(enc(format!("Sun raster stores 8 bits per channel, not {:?}", img.sample_type()))); + } + let depth: usize = match img.layout() { + ChannelLayout::Gray => 8, + ChannelLayout::Rgb => 24, + ChannelLayout::Rgba => 32, + l => return Err(enc(format!("no Sun raster layout for {l:?}"))), + }; + let (w, h) = img.dimensions(); + let (wu, hu) = (w as usize, h as usize); + let bytes = depth / 8; + let stride = (wu * bytes).next_multiple_of(2); + let len = stride.checked_mul(hu).and_then(|n| u32::try_from(n).ok()).ok_or_else(|| enc("image too large".into()))?; + let data = img.data(); + if data.len() != wu * hu * bytes { + return Err(enc("the image has the wrong number of samples".into())); + } + let mut out = Vec::with_capacity(HEADER + len as usize); + for v in [MAGIC, w, h, depth as u32, len, 3, 0, 0] { + out.extend_from_slice(&v.to_be_bytes()); + } + for y in 0..hu { + let row = &data[y * wu * bytes..(y + 1) * wu * bytes]; + if depth == 32 { + // Stored alpha first. + for p in row.as_chunks::<4>().0 { + out.extend_from_slice(&[p[3], p[0], p[1], p[2]]); + } + } else { + out.extend_from_slice(row); + } + out.resize(HEADER + (y + 1) * stride, 0); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn pattern(w: u32, h: u32, layout: ChannelLayout) -> Image { + let n = w as usize * h as usize * layout.channels(); + Image::from_u8(w, h, layout, (0..n).map(|i| ((i * 13 + i / 3) % 253) as u8).collect()).unwrap() + } + + #[test] + fn round_trips_gray_rgb_and_rgba_with_odd_widths() { + for layout in [ChannelLayout::Gray, ChannelLayout::Rgb, ChannelLayout::Rgba] { + let img = pattern(13, 7, layout); + let bytes = encode(&img, Plan { layout, sample: SampleType::U8 }).unwrap(); + assert!(looks_like_sunraster(&bytes)); + let back = decode(&bytes, &Limits::default()).unwrap(); + assert_eq!((back.layout(), back.data()), (layout, img.data())); + } + } + + fn file(depth: u32, kind: u32, map: &[u8], map_type: u32, w: u32, h: u32, data: &[u8]) -> Vec { + let mut f = Vec::new(); + for v in [MAGIC, w, h, depth, data.len() as u32, kind, map_type, map.len() as u32] { + f.extend_from_slice(&v.to_be_bytes()); + } + f.extend_from_slice(map); + f.extend_from_slice(data); + f + } + + #[test] + fn standard_type_is_blue_first_and_rle_expands() { + let f = file(24, 1, &[], 0, 1, 1, &[1, 2, 3, 0]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[3, 2, 1]); + // 0x80 0x00 is a literal 0x80; 0x80 n v is n + 1 copies of v. The 2x2 image has stride 2. + let f = file(8, 2, &[], 0, 2, 2, &[0x80, 0x00, 0x80, 0x00, 0x80, 0x01, 7]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0x80, 0x80, 7, 7]); + // A run that passes the end of the image is an error. + assert!(decode(&file(8, 2, &[], 0, 2, 2, &[0x80, 0x09, 7]), &Limits::default()).is_err()); + } + + #[test] + fn colour_mapped_and_one_bit_files() { + // Two entries: red plane, green plane, blue plane. + let map = [10, 20, 30, 40, 50, 60]; + let f = file(8, 1, &map, 1, 2, 1, &[0, 1]); + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgb, &[10, 30, 50, 20, 40, 60][..])); + let f = file(8, 1, &map, 1, 1, 1, &[5, 0]); + assert!(decode(&f, &Limits::default()).is_err()); + let f = file(1, 1, &[], 0, 3, 1, &[0b1010_0000, 0]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0, 255, 0]); + } + + #[test] + fn hostile_input_is_an_error_not_a_panic() { + let img = pattern(9, 5, ChannelLayout::Rgb); + let good = encode(&img, Plan { layout: ChannelLayout::Rgb, sample: SampleType::U8 }).unwrap(); + for len in 0..good.len() { + let _ = decode(&good[..len], &Limits::default()); + } + let mut huge = good.clone(); + huge[4..8].copy_from_slice(&u32::MAX.to_be_bytes()); + huge[8..12].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&huge, &Limits::default()).is_err()); + let mut bad_map = good; + bad_map[28..32].copy_from_slice(&u32::MAX.to_be_bytes()); + assert!(decode(&bad_map, &Limits::default()).is_err()); + assert!(matches!(decode(&file(24, 4, &[], 0, 1, 1, &[0; 4]), &Limits::default()), Err(CodecError::Unsupported { .. }))); + } +} diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index ecaf945cd..d4075cc8e 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, + /// Sun Raster (`.ras`): 1-, 8-, 24- and 32-bit, uncompressed or RLE. + SunRaster, } /// 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::SunRaster, ]; pub fn caps(self) -> FormatCaps { @@ -176,6 +179,7 @@ impl Format { Format::Dicom => "DICOM", Format::Iff => "Amiga IFF", Format::Jp2 => "JPEG 2000", + Format::SunRaster => "Sun Raster", } } @@ -207,6 +211,7 @@ impl Format { Format::Dicom => &["dcm", "dicom", "dc3"], Format::Iff => &["iff", "lbm", "ilbm"], Format::Jp2 => &["jp2", "j2k", "j2c", "jpf", "jpx"], + Format::SunRaster => &["ras", "sun"], } } @@ -236,6 +241,7 @@ impl Format { Format::Dicom => "application/dicom", Format::Iff => "image/x-iff", Format::Jp2 => "image/jp2", + Format::SunRaster => "image/x-sun-raster", } } @@ -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::SunRaster => FormatCaps { layouts: &[L::Gray, L::Rgb, L::Rgba], alpha: true, ..base }, Format::Jp2 => FormatCaps { read: true, write: false, layouts: &[L::Gray, L::GrayA, L::Rgb, L::Rgba, L::Cmyk, L::CmykA], icc: true, ..base }, } } @@ -388,6 +395,9 @@ pub fn detect(bytes: &[u8]) -> Option { if b.starts_with(b"/* XPM */") || b.starts_with(b"! XPM2\n") || b.starts_with(b"! XPM2\r\n") { return Some(Format::Xpm); } + if crate::codecs::sunraster::looks_like_sunraster(b) { + return Some(Format::SunRaster); + } if crate::codecs::pcx::looks_like_pcx(b) { return Some(Format::Pcx); } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 21130e392..ab235d2ab 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, jxl, pcx, png, pnm, sunraster, 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::SunRaster => sunraster::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::SunRaster => sunraster::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..17fb20442 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::SunRaster, ]; for f in expected { assert!(caps(f).read && caps(f).write, "{f:?}"); @@ -218,6 +219,19 @@ 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_sun_raster() { + use craft_image_codecs::{ChannelLayout, EncodeOptions, Image, encode}; + let img = Image::from_u8(5, 3, ChannelLayout::Rgb, (0..45).collect()).unwrap(); + let bytes = encode(&img, Format::SunRaster, &EncodeOptions::default()).unwrap(); + assert_eq!(detect(&bytes), Some(Format::SunRaster)); + assert_eq!(from_extension("scan.RAS"), Some(Format::SunRaster)); + assert_eq!(decode(&bytes).unwrap().data(), img.data()); + assert!(!ASYMMETRIC_EXCEPTIONS.iter().any(|(f, _)| *f == Format::SunRaster)); + assert_eq!(detect(&[0x59, 0xa6, 0x6a, 0x95]), None); + assert!(decode_as(Format::SunRaster, &[0x59, 0xa6, 0x6a, 0x95]).is_err()); +} + #[test] fn detect_magic_avif() { assert_eq!(detect(b"\0\0\0\x1cftypavif\0\0\0\0avifmif1miaf"), Some(Format::Avif)); From 51a35cecb7b3d0416f0195032bbcc7f960731688 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 15 Nov 2026 13:27:34 +0100 Subject: [PATCH 047/349] flow: keep the old paragraph direction in the tracked formatting-change snapshot Co-Authored-By: Claude Sonnet 5.5 --- crates/flow/src/from_doc.rs | 5 ++++- crates/rtf/src/doc/tests.rs | 24 ++++++++++++++++++++++++ 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/crates/flow/src/from_doc.rs b/crates/flow/src/from_doc.rs index ea7f6fc92..717283f57 100644 --- a/crates/flow/src/from_doc.rs +++ b/crates/flow/src/from_doc.rs @@ -661,7 +661,10 @@ fn flow_paras_in(doc: &Document, p: &Paragraph, opts: FlowOpts) -> Vec { { (li.list, li.label) = (0, None); } - let old = Para { kind, list, align: c.old.align, page_break: c.old.page_break_before.unwrap_or(false), ..Default::default() }; + // Direction resolved like the current paragraph's: the old properties' own `w:bidi`, else + // the style's. + let rtl = doc.styles.resolve_para(&c.old).bidi; + let old = Para { kind, list, align: c.old.align, rtl, page_break: c.old.page_break_before.unwrap_or(false), ..Default::default() }; Box::new(FmtChange { mark: rev_mark(doc, c.rev), old }) }); } diff --git a/crates/rtf/src/doc/tests.rs b/crates/rtf/src/doc/tests.rs index 8313ad5b8..bf98d190a 100644 --- a/crates/rtf/src/doc/tests.rs +++ b/crates/rtf/src/doc/tests.rs @@ -94,6 +94,30 @@ fn oldpprops_keep_the_old_paragraph_direction() { assert_eq!(c.old.bidi, Some(true)); } +#[test] +fn tracked_rtl_to_ltr_change_from_a_document_keeps_the_old_direction() { + use craft_wordmodel::props::{CharProps, ParaProps, PropChange}; + use craft_wordmodel::{Revision, RevisionKind}; + // Document origin (not RTF): now LTR, before RTL. + let mut p = craft_wordmodel::Paragraph::with_text("A", CharProps::default()); + p.props.bidi = Some(false); + p.props.fmt_change = PropChange::boxed(0, ParaProps { bidi: Some(true), ..Default::default() }); + let doc = doc_with(vec![p], vec![Revision::new(RevisionKind::Format, "Bob", "2025-01-02T08:05:00Z")]); + let flow = model::from_doc_tracked(&doc); + let Some(FBlock::Para(fp)) = flow.blocks.first() else { panic!("no paragraph") }; + assert!(!fp.rtl); + assert!(fp.fmt_change.as_deref().expect("change").old.rtl, "snapshot keeps RTL"); + let rtf = export(&doc); + assert!(rtf.contains("{\\*\\oldpprops"), "{rtf}"); + let back = import(rtf.as_bytes()).unwrap(); + let p = doc_paras(&back)[0]; + assert_ne!(p.props.bidi, Some(true), "current direction is LTR"); + let change = p.props.fmt_change.as_deref().expect("change read back"); + assert_eq!(change.old.bidi, Some(true)); + // Reject restores RTL. + assert_eq!(change.old.formatting().bidi, Some(true)); +} + #[test] fn stylesheet_names_take_unicode_escapes() { // \u116?=t \u105?=i \u116?=t \u108?=l \u101?=e — how Word writes a non-Latin style name. From b4463c620348f649b2907e35aaef901010130842 Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 15 Nov 2026 13:30:44 +0100 Subject: [PATCH 048/349] docx charts: outline unfilled bars, honour no-fill areas, keep source-linked label formats Co-Authored-By: Claude Sonnet 5.5 --- crates/docx/src/read/chart/model.rs | 5 ++- crates/docx/src/read/chart/parse.rs | 17 ++++--- crates/docx/src/read/chart/plot.rs | 10 ++++- crates/docx/src/read/chart/polar.rs | 2 +- crates/docx/src/read/chart/tests.rs | 69 +++++++++++++++++++++++++++++ 5 files changed, 91 insertions(+), 12 deletions(-) diff --git a/crates/docx/src/read/chart/model.rs b/crates/docx/src/read/chart/model.rs index 37d06e31f..13da1d654 100644 --- a/crates/docx/src/read/chart/model.rs +++ b/crates/docx/src/read/chart/model.rs @@ -162,8 +162,9 @@ pub(super) struct Series { pub(super) x_fmt: Option, /// Data labels on or off for this series (`c:dLbls` of its own), when it says. pub(super) labels: Option, - /// The labels' own number format (`c:dLbls/c:numFmt` not linked to the source), if any. - pub(super) label_fmt: Option, + /// The labels' number format (`c:dLbls/c:numFmt`): `None` when not given (the chart type's + /// applies), `Some(None)` when linked to the source, else `Some(Some(code))`. + pub(super) label_fmt: Option>, /// The data labels' `c:dLblPos`, when the file gives a known one. pub(super) label_pos: Option, /// The marker's own fill (`c:marker/c:spPr`); without it markers take the automatic colour. diff --git a/crates/docx/src/read/chart/parse.rs b/crates/docx/src/read/chart/parse.rs index 67b09d795..522d50b3b 100644 --- a/crates/docx/src/read/chart/parse.rs +++ b/crates/docx/src/read/chart/parse.rs @@ -44,6 +44,7 @@ impl Chart { s.values.resize(n, None); s.xs.resize(n, None); s.labels = Some(s.labels.or(type_labels).unwrap_or(false)); + // Absent (`None`) inherits the chart type's; explicitly source-linked (`Some(None)`) does not. if s.label_fmt.is_none() { s.label_fmt.clone_from(&type_fmt); } @@ -191,13 +192,15 @@ fn show_values(d: Option<&El>) -> Option { d.child("c:showVal").map(|v| v.attr("val").is_none_or(truthy)) } -/// The number format of data labels (`c:dLbls/c:numFmt`) when it is not linked to the source. -fn label_format(d: Option<&El>) -> Option { - d?.child("c:numFmt") - .filter(|f| f.attr("sourceLinked") != Some("1")) - .and_then(|f| f.attr("formatCode")) - .filter(|f| f.chars().count() <= craft_wordmodel::chart::MAX_FMT) - .map(str::to_string) +/// The number format of data labels (`c:dLbls/c:numFmt`): `None` when the labels say nothing, +/// `Some(None)` when they are linked to the source (so a chart-level format does not apply), +/// `Some(Some(code))` for their own format code. +fn label_format(d: Option<&El>) -> Option> { + let f = d?.child("c:numFmt")?; + if f.attr("sourceLinked").is_some_and(truthy) { + return Some(None); + } + f.attr("formatCode").filter(|f| f.chars().count() <= craft_wordmodel::chart::MAX_FMT).map(|f| Some(f.to_string())) } fn legend_pos(chart: &El) -> Option { diff --git a/crates/docx/src/read/chart/plot.rs b/crates/docx/src/read/chart/plot.rs index f671f1d49..22d05b554 100644 --- a/crates/docx/src/read/chart/plot.rs +++ b/crates/docx/src/read/chart/plot.rs @@ -468,7 +468,11 @@ fn bars(out: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec, c: &Chart, g: &Frame, labels: &mut Vec Option { return None; } let v = s.raw.get(i).copied().flatten()?; - let fmt = s.label_fmt.as_deref().or(s.fmt.as_deref()).filter(|f| !f.eq_ignore_ascii_case("General")); + let fmt = s.label_fmt.as_ref().map_or(s.fmt.as_deref(), |f| f.as_deref().or(s.fmt.as_deref())).filter(|f| !f.eq_ignore_ascii_case("General")); Some(match fmt { Some(f) => format_value(v, f, 1.0), None => general_value(v), diff --git a/crates/docx/src/read/chart/tests.rs b/crates/docx/src/read/chart/tests.rs index e5d7e4db6..ae80c028e 100644 --- a/crates/docx/src/read/chart/tests.rs +++ b/crates/docx/src/read/chart/tests.rs @@ -830,3 +830,72 @@ fn horizontal_value_axis_title_gets_its_own_strip() { let p = plot_left(&items).unwrap(); assert!(p.is_finite() && p <= 300.0 * 0.3, "{p}"); } + +/// A one-series chart whose series carries `sp` as its `c:spPr`. +fn chart_with_sp(kind: &str, sp: &str) -> Vec { + let s = ser(0, "S", None, &["Q1", "Q2"], &["4", "8"]).replace("", &format!("{sp}")); + let plot = match kind { + "area" => format!( + r#"{s}"# + ), + dir => format!( + r#"{s}"# + ), + }; + chart_items(&space(&plot), &theme(), 300.0, 200.0) +} + +/// The series' closed shapes: (filled, stroked with the given width). +fn series_shapes(items: &[GraphicItem], width: f32) -> (usize, usize) { + let closed = |segs: &[PathSeg]| segs.iter().any(|s| matches!(s, PathSeg::Close)); + let fills = items.iter().filter(|it| matches!(it, GraphicItem::Path { segs, fill: Some(_), .. } if closed(segs))).count(); + let strokes = items + .iter() + .filter(|it| matches!(it, GraphicItem::Path { segs, fill: None, stroke: Some(_), stroke_width, .. } if closed(segs) && (*stroke_width - width).abs() < 0.01)) + .count(); + (fills, strokes) +} + +#[test] +fn unfilled_bars_keep_their_explicit_outline() { + let outlined = r#""#; + let no_line = r#""#; + for dir in ["col", "bar"] { + // Two points, two outlines, no fill. + assert_eq!(series_shapes(&chart_with_sp(dir, outlined), 2.0), (0, 2), "{dir}"); + // Control: no fill and no line draws nothing. + assert_eq!(series_shapes(&chart_with_sp(dir, no_line), 2.0), (0, 0), "{dir}"); + } +} + +#[test] +fn no_fill_area_series_is_not_painted() { + let filled = r#""#; + let none = r#""#; + assert_eq!(series_shapes(&chart_with_sp("area", filled), 2.0).0, 1); + assert_eq!(series_shapes(&chart_with_sp("area", none), 2.0).0, 0); +} + +#[test] +fn source_linked_series_labels_do_not_inherit_the_chart_format() { + let dl = |fmt: &str| format!(r#""#); + let shown = |items: &[GraphicItem]| -> Vec { + items.iter().filter_map(|it| if let GraphicItem::Text { text, .. } = it { Some(text.clone()) } else { None }).collect() + }; + // Chart-level 0%; the series' own labels are `linked` (or have no labels element at all). + let run = |series_dl: &str| { + let s = ser(0, "S", Some("FF0000"), &["Q1", "Q2", "Q3"], &["3.2", "4.1", "5"]).replace("", &format!("{series_dl}")); + let chart_dl = dl("0%").replace("{}", "0"); + let plot = format!( + r#"{s}{chart_dl}"# + ); + shown(&chart_items(&space(&plot), &theme(), 300.0, 200.0)) + }; + for linked in ["1", "true"] { + let own = run(&dl("General").replace("{}", linked)); + assert!(own.contains(&"3.2".to_string()) && !own.contains(&"320%".to_string()), "sourceLinked={linked}: {own:?}"); + } + // Control: a series without a label format still takes the chart's. + let inherited = run(r#""#); + assert!(inherited.contains(&"320%".to_string()), "{inherited:?}"); +} From 425bcbfaba54a72cce2adb854c758809e7f56b2f Mon Sep 17 00:00:00 2001 From: vangel76 Date: Sun, 15 Nov 2026 14:37:01 +0100 Subject: [PATCH 049/349] MXF README: craft-raw decodes the DNG pictures, it does not develop them Co-Authored-By: Claude Opus 5.5 --- crates/media/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/media/README.md b/crates/media/README.md index 7b5e47c0e..6262976bb 100644 --- a/crates/media/README.md +++ b/crates/media/README.md @@ -700,7 +700,7 @@ let pcm = mxf.read_pcm(&file, a, 48_000, 1920)?; // planar f32, sample-exact MPEG-4 visual, JPEG 2000, DV, uncompressed, CinemaDNG (the CinemaDNG container labels, the registered MXF-GC TIFF/EP container and TIFF/EP picture coding labels, a 42h picture element type, or a TIFF header with the DNGVersion tag at the start of the essence; the DNG pictures - themselves are developed by `craft-raw`). + themselves are decoded by `craft-raw`). - **Sound.** PCM chunks (frame- or clip-wrapped) with sample counts; `read_pcm` decodes little-endian 8/16/24/32-bit PCM (wave / AES3 descriptors) and ST 331 AES3 elements (D-10). - **Timecode.** The material package timecode component (start frame count, rounded base, From cdf4a2fa6e23f80e6a8210361a79f6e9600a4056 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 15:11:43 +0100 Subject: [PATCH 050/349] craft-audio: native FLAC decoder (flac-decode) Adds flac::decode for whole files and flac::Decoder for single frames: RFC 9639 subframes (constant, verbatim, fixed, LPC), Rice and escaped partitions, wasted bits, all stereo modes, fixed and variable block sizes, 4 to 32 bits, CRC-8 and CRC-16 checked. Not yet wired into craft_audio::decode, which still uses symphonia for FLAC. Part of #1546 --- crates/audio/Cargo.toml | 6 + crates/audio/README.md | 1 + crates/audio/src/flac_decode.rs | 558 ++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 9 +- crates/audio/tests/flac_decode.rs | 179 ++++++++++ 5 files changed, 751 insertions(+), 2 deletions(-) create mode 100644 crates/audio/src/flac_decode.rs create mode 100644 crates/audio/tests/flac_decode.rs diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index c411a0357..a0d1070bd 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -29,6 +29,8 @@ encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-en lossless-encode = ["pcm-encode", "flac-encode"] # Encode WAV/BWF/RF64 and AIFF/AIFF-C files. pcm-encode = [] +# Decode FLAC files and frames natively (`flac::decode`, `flac::Decoder`). +flac-decode = [] # Encode FLAC files. flac-encode = ["craft-media/bitstream"] # Encode Ogg Vorbis files (desktop only: builds the reference libvorbis from its C sources). @@ -84,6 +86,10 @@ required-features = ["decode", "lossless-encode", "peaks"] name = "codecs" required-features = ["decode", "encode"] +[[test]] +name = "flac_decode" +required-features = ["flac-decode", "flac-encode"] + [[example]] name = "info" required-features = ["decode"] diff --git a/crates/audio/README.md b/crates/audio/README.md index 63251db8d..c336b4b8e 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -32,6 +32,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode` | | `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` | | `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none | +| `flac-decode` | `flac::decode` (whole `.flac` files) and `flac::Decoder` (single frames, for callers that demux FLAC themselves); native, CRC-checked, 4 to 32 bits. `decode` still uses symphonia for FLAC files | none | | `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` | | `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams); with `aac-encode`, `encode`, `FileEncoder` for AAC in M4A | craft-media `bitstream`; `aac-encode` also `isobmff` | | `alac-decode` | `alac::Decoder` | none | diff --git a/crates/audio/src/flac_decode.rs b/crates/audio/src/flac_decode.rs new file mode 100644 index 000000000..dfb6f5fc1 --- /dev/null +++ b/crates/audio/src/flac_decode.rs @@ -0,0 +1,558 @@ +//! A native FLAC decoder (RFC 9639): [`decode`] for whole `.flac` files and [`Decoder`] for single +//! frames (the packets of FLAC in MP4, Matroska or Ogg). +//! +//! Every frame is checked against its CRC-8 and CRC-16. Subframe types constant, verbatim, fixed +//! and LPC; Rice partitions with 4- and 5-bit parameters and escaped partitions; wasted bits; +//! left/side, side/right and mid/side stereo; fixed and variable block sizes; 4 to 32 bits per +//! sample. The STREAMINFO MD5 is not verified. +//! +//! Samples come back as `i32`, one `Vec` per channel, in the FLAC channel order. + +/// What went wrong decoding FLAC. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum DecodeError { + /// The data ends early. + #[error("truncated FLAC data")] + Truncated, + /// The data is not valid FLAC. + #[error("invalid FLAC data: {0}")] + Invalid(&'static str), + /// A frame or header failed its CRC. + #[error("FLAC CRC mismatch in {0}")] + Crc(&'static str), + /// Valid FLAC that is not decoded. + #[error("unsupported FLAC feature: {0}")] + Unsupported(&'static str), + /// The stream is longer than the sample limit. + #[error("FLAC stream exceeds the sample limit")] + TooLarge, +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The STREAMINFO metadata block (RFC 9639 section 8.2). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct StreamInfo { + /// Smallest block size in samples. + pub min_block_size: u16, + /// Largest block size in samples. + pub max_block_size: u16, + /// Smallest frame in bytes, 0 if unknown. + pub min_frame_size: u32, + /// Largest frame in bytes, 0 if unknown. + pub max_frame_size: u32, + /// Sample rate in Hz. + pub sample_rate: u32, + /// Channel count, 1 to 8. + pub channels: u8, + /// Bits per sample, 4 to 32. + pub bits_per_sample: u8, + /// Samples per channel in the stream, 0 if unknown. + pub total_samples: u64, + /// MD5 of the unencoded audio, all zero if not set. + pub md5: [u8; 16], +} + +impl StreamInfo { + /// Parse the 34 bytes of a STREAMINFO block body. + pub fn parse(b: &[u8]) -> Result { + let b = b.get(..34).ok_or(DecodeError::Truncated)?; + let packed = u64::from_be_bytes([b[10], b[11], b[12], b[13], b[14], b[15], b[16], b[17]]); + let info = StreamInfo { + min_block_size: u16::from_be_bytes([b[0], b[1]]), + max_block_size: u16::from_be_bytes([b[2], b[3]]), + min_frame_size: u32::from_be_bytes([0, b[4], b[5], b[6]]), + max_frame_size: u32::from_be_bytes([0, b[7], b[8], b[9]]), + sample_rate: (packed >> 44) as u32, + channels: ((packed >> 41) & 7) as u8 + 1, + bits_per_sample: ((packed >> 36) & 31) as u8 + 1, + total_samples: packed & 0xF_FFFF_FFFF, + md5: b[18..34].try_into().map_err(|_| DecodeError::Truncated)?, + }; + if info.bits_per_sample < 4 { + return Err(DecodeError::Invalid("bits per sample below 4")); + } + if info.min_block_size != 0 + && (info.min_block_size < 16 && info.min_block_size != info.max_block_size || info.max_block_size < info.min_block_size) + { + return Err(DecodeError::Invalid("inconsistent block sizes")); + } + Ok(info) + } +} + +/// One decoded frame. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Frame { + /// Sample rate in Hz. + pub sample_rate: u32, + /// Bits per sample. + pub bits_per_sample: u8, + /// `true` when `number` is the first sample's index (variable block size), `false` when it is + /// the frame's index (fixed block size). + pub variable_block_size: bool, + /// The coded number of the frame header. + pub number: u64, + /// Samples per channel in the frame. + pub block_size: usize, + /// One `Vec` per channel, after undoing any stereo decorrelation. + pub channels: Vec>, + /// Bytes the frame took, including the header and CRC footer. + pub size: usize, +} + +// ---- checksums ---- + +fn crc8(data: &[u8]) -> u8 { + let mut crc = 0u8; + for &b in data { + crc ^= b; + for _ in 0..8 { + crc = if crc & 0x80 != 0 { crc << 1 ^ 0x07 } else { crc << 1 }; + } + } + crc +} + +fn crc16(data: &[u8]) -> u16 { + let mut crc = 0u16; + for &b in data { + crc ^= u16::from(b) << 8; + for _ in 0..8 { + crc = if crc & 0x8000 != 0 { crc << 1 ^ 0x8005 } else { crc << 1 }; + } + } + crc +} + +// ---- bits ---- + +struct Bits<'a> { + data: &'a [u8], + /// Position in bits. + pos: usize, +} + +impl<'a> Bits<'a> { + fn new(data: &'a [u8]) -> Self { + Bits { data, pos: 0 } + } + + fn left(&self) -> usize { + self.data.len() * 8 - self.pos + } + + fn bit(&mut self) -> Result { + let byte = *self.data.get(self.pos / 8).ok_or(DecodeError::Truncated)?; + let v = (byte >> (7 - self.pos % 8)) & 1; + self.pos += 1; + Ok(u32::from(v)) + } + + /// `n` bits (0 to 32) as an unsigned number. + fn bits(&mut self, n: u32) -> Result { + if n as usize > self.left() { + return Err(DecodeError::Truncated); + } + let mut v = 0u64; + let mut n = n as usize; + while n > 0 { + let byte = u64::from(self.data[self.pos / 8]); + let avail = 8 - self.pos % 8; + let take = avail.min(n); + v = v << take | (byte >> (avail - take)) & ((1 << take) - 1); + self.pos += take; + n -= take; + } + Ok(v) + } + + /// `n` bits (0 to 33) as a two's complement number. + fn signed(&mut self, n: u32) -> Result { + if n == 0 { + return Ok(0); + } + let v = self.bits(n)? as i64; + Ok(if v >> (n - 1) & 1 == 1 { v - (1 << n) } else { v }) + } + + /// Zero bits up to the next one bit (which is consumed). + fn unary(&mut self) -> Result { + let mut n = 0u64; + loop { + // Skip whole zero bytes when aligned. + if self.pos.is_multiple_of(8) { + while self.data.get(self.pos / 8) == Some(&0) { + self.pos += 8; + n += 8; + } + } + if self.bit()? == 1 { + return Ok(n); + } + n += 1; + } + } + + fn align(&mut self) { + self.pos = self.pos.div_ceil(8) * 8; + } +} + +// ---- frame ---- + +const BLOCK_SIZES: [usize; 16] = [0, 192, 576, 1152, 2304, 4608, 0, 0, 256, 512, 1024, 2048, 4096, 8192, 16384, 32768]; + +/// A frame decoder. `info` supplies what a frame header leaves to the STREAMINFO. +#[derive(Debug, Clone, Copy, Default)] +pub struct Decoder { + info: Option, +} + +impl Decoder { + /// A decoder with the stream's STREAMINFO (needed for frames whose header defers the sample + /// rate or bit depth to it). + pub fn new(info: StreamInfo) -> Decoder { + Decoder { info: Some(info) } + } + + /// A decoder without STREAMINFO: frames that defer to it are an error. + pub fn without_streaminfo() -> Decoder { + Decoder { info: None } + } + + /// Decode the frame at the start of `data`. + pub fn decode_frame(&self, data: &[u8]) -> Result { + let mut r = Bits::new(data); + if r.bits(15)? != 0x7FFC { + return Err(DecodeError::Invalid("missing frame sync code")); + } + let variable = r.bit()? == 1; + let (bs_code, sr_code) = (r.bits(4)? as usize, r.bits(4)? as usize); + let (ch_code, bps_code) = (r.bits(4)? as usize, r.bits(3)? as usize); + if r.bit()? != 0 { + return Err(DecodeError::Invalid("reserved bit set")); + } + let number = coded_number(&mut r)?; + let block_size = match bs_code { + 0 => return Err(DecodeError::Invalid("reserved block size")), + 6 => r.bits(8)? as usize + 1, + 7 => r.bits(16)? as usize + 1, + c => BLOCK_SIZES[c], + }; + let sample_rate = match sr_code { + 0 => self.info.map(|i| i.sample_rate).ok_or(DecodeError::Invalid("sample rate only in STREAMINFO"))?, + 1 => 88_200, + 2 => 176_400, + 3 => 192_000, + 4 => 8_000, + 5 => 16_000, + 6 => 22_050, + 7 => 24_000, + 8 => 32_000, + 9 => 44_100, + 10 => 48_000, + 11 => 96_000, + 12 => r.bits(8)? as u32 * 1000, + 13 => r.bits(16)? as u32, + 14 => r.bits(16)? as u32 * 10, + _ => return Err(DecodeError::Invalid("forbidden sample rate code")), + }; + let header_len = r.pos.div_ceil(8); + let stored_crc = r.bits(8)? as u8; + if crc8(&data[..header_len]) != stored_crc { + return Err(DecodeError::Crc("a frame header")); + } + let bits = match bps_code { + 0 => self.info.map(|i| u32::from(i.bits_per_sample)).ok_or(DecodeError::Invalid("bit depth only in STREAMINFO"))?, + 1 => 8, + 2 => 12, + 4 => 16, + 5 => 20, + 6 => 24, + 7 => 32, + _ => return Err(DecodeError::Invalid("reserved bit depth")), + }; + let (channels, mode) = match ch_code { + 0..=7 => (ch_code + 1, Stereo::Independent), + 8 => (2, Stereo::LeftSide), + 9 => (2, Stereo::SideRight), + 10 => (2, Stereo::MidSide), + _ => return Err(DecodeError::Invalid("reserved channel assignment")), + }; + let mut out: Vec> = Vec::with_capacity(channels); + for c in 0..channels { + let extra = match (mode, c) { + (Stereo::LeftSide, 1) | (Stereo::SideRight, 0) | (Stereo::MidSide, 1) => 1, + _ => 0, + }; + out.push(subframe(&mut r, block_size, bits + extra)?); + } + r.align(); + let size = r.pos / 8; + let crc = r.bits(16)? as u16; + if crc16(&data[..size]) != crc { + return Err(DecodeError::Crc("a frame")); + } + let size = size + 2; + if mode != Stereo::Independent { + let (first, rest) = out.split_at_mut(1); + let (a, b) = (&mut first[0], &mut rest[0]); + for (x, y) in a.iter_mut().zip(b.iter_mut()) { + match mode { + Stereo::LeftSide => *y = x.wrapping_sub(*y), + Stereo::SideRight => *x = x.wrapping_add(*y), + _ => { + let m = x.wrapping_shl(1) | (*y & 1); + let side = *y; + *x = m.wrapping_add(side) >> 1; + *y = m.wrapping_sub(side) >> 1; + } + } + } + } + let mut chans = Vec::with_capacity(channels); + for c in out { + let v: Result> = + c.into_iter().map(|s| i32::try_from(s).map_err(|_| DecodeError::Invalid("sample outside the bit depth"))).collect(); + chans.push(v?); + } + Ok(Frame { sample_rate, bits_per_sample: bits as u8, variable_block_size: variable, number, block_size, channels: chans, size }) + } +} + +#[derive(Clone, Copy, PartialEq, Eq)] +enum Stereo { + Independent, + LeftSide, + SideRight, + MidSide, +} + +/// The UTF-8-like coded number of a frame header (up to 36 bits, 7 bytes). +fn coded_number(r: &mut Bits) -> Result { + let first = r.bits(8)? as u8; + let extra = match first { + 0x00..=0x7F => return Ok(u64::from(first)), + 0xC0..=0xDF => 1, + 0xE0..=0xEF => 2, + 0xF0..=0xF7 => 3, + 0xF8..=0xFB => 4, + 0xFC..=0xFD => 5, + 0xFE => 6, + _ => return Err(DecodeError::Invalid("bad coded number")), + }; + let mut v = if extra == 6 { 0 } else { u64::from(first & (0x3F >> extra)) }; + for _ in 0..extra { + let b = r.bits(8)?; + if b & 0xC0 != 0x80 { + return Err(DecodeError::Invalid("bad coded number")); + } + v = v << 6 | (b & 0x3F); + } + Ok(v) +} + +/// One subframe: `bits` is the frame bit depth (plus 1 for a side channel). +fn subframe(r: &mut Bits, n: usize, bits: u32) -> Result> { + if r.bit()? != 0 { + return Err(DecodeError::Invalid("subframe header padding bit set")); + } + let kind = r.bits(6)? as u32; + let wasted = if r.bit()? == 1 { r.unary()? as u32 + 1 } else { 0 }; + if wasted >= bits { + return Err(DecodeError::Invalid("wasted bits leave no sample bits")); + } + let bps = bits - wasted; + let mut s = vec![0i64; n]; + match kind { + 0 => { + let v = r.signed(bps)?; + s.fill(v); + } + 1 => { + for v in s.iter_mut() { + *v = r.signed(bps)?; + } + } + 8..=12 => { + let order = (kind - 8) as usize; + warmup(r, &mut s, order, bps)?; + residual(r, &mut s, order)?; + for i in order..n { + let at = |k: usize| s[i - k]; + // Wrapping: hostile residuals can overflow; such samples fail the range check later. + let p = match order { + 0 => 0, + 1 => at(1), + 2 => at(1).wrapping_mul(2).wrapping_sub(at(2)), + 3 => at(1).wrapping_mul(3).wrapping_sub(at(2).wrapping_mul(3)).wrapping_add(at(3)), + _ => at(1).wrapping_mul(4).wrapping_sub(at(2).wrapping_mul(6)).wrapping_add(at(3).wrapping_mul(4)).wrapping_sub(at(4)), + }; + s[i] = s[i].wrapping_add(p); + } + } + 32..=63 => { + let order = (kind - 31) as usize; + warmup(r, &mut s, order, bps)?; + let precision = r.bits(4)? as u32 + 1; + if precision == 16 { + return Err(DecodeError::Invalid("forbidden coefficient precision")); + } + let shift = r.signed(5)?; + if shift < 0 { + return Err(DecodeError::Invalid("negative prediction shift")); + } + let mut coefs = [0i64; 32]; + for c in coefs.iter_mut().take(order) { + *c = r.signed(precision)?; + } + residual(r, &mut s, order)?; + for i in order..n { + let mut sum = 0i64; + for (k, &c) in coefs.iter().take(order).enumerate() { + sum = sum.wrapping_add(c.wrapping_mul(s[i - 1 - k])); + } + s[i] = s[i].wrapping_add(sum >> shift); + } + } + _ => return Err(DecodeError::Invalid("reserved subframe type")), + } + if wasted > 0 { + for v in s.iter_mut() { + *v = v.wrapping_shl(wasted); + } + } + Ok(s) +} + +fn warmup(r: &mut Bits, s: &mut [i64], order: usize, bps: u32) -> Result<()> { + if order > s.len() { + return Err(DecodeError::Invalid("predictor order above the block size")); + } + for v in s.iter_mut().take(order) { + *v = r.signed(bps)?; + } + Ok(()) +} + +/// The coded residual (RFC 9639 section 9.2.7), into `s[order..]`. +fn residual(r: &mut Bits, s: &mut [i64], order: usize) -> Result<()> { + let method = r.bits(2)?; + let (param_bits, escape) = match method { + 0 => (4, 15), + 1 => (5, 31), + _ => return Err(DecodeError::Invalid("reserved residual coding method")), + }; + let part_order = r.bits(4)? as u32; + let n = s.len(); + let parts = 1usize << part_order; + if !n.is_multiple_of(parts) { + return Err(DecodeError::Invalid("partition order does not divide the block size")); + } + let per = n >> part_order; + if per < order { + return Err(DecodeError::Invalid("partition shorter than the predictor order")); + } + let mut i = order; + for p in 0..parts { + let count = if p == 0 { per - order } else { per }; + let k = r.bits(param_bits)? as u32; + if k == escape { + let width = r.bits(5)? as u32; + for v in s[i..i + count].iter_mut() { + *v = r.signed(width)?; + } + } else { + for v in s[i..i + count].iter_mut() { + let q = r.unary()?; + if q > (1 << 32) { + return Err(DecodeError::Invalid("Rice quotient too large")); + } + let low = r.bits(k)?; + let folded = q << k | low; + *v = if folded & 1 == 0 { (folded >> 1) as i64 } else { -((folded >> 1) as i64) - 1 }; + } + } + i += count; + } + Ok(()) +} + +// ---- files ---- + +/// A decoded file. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Decoded { + /// The STREAMINFO block. + pub info: StreamInfo, + /// One `Vec` of samples per channel. + pub channels: Vec>, +} + +/// Most sample values (samples x channels) [`decode`] will produce. +pub const DEFAULT_MAX_VALUES: u64 = 1 << 28; + +/// Decode a whole `.flac` file (an ID3v2 tag in front is skipped). +pub fn decode(bytes: &[u8]) -> Result { + decode_with_limit(bytes, DEFAULT_MAX_VALUES) +} + +/// [`decode`] with a limit on the sample values (samples x channels) produced. +pub fn decode_with_limit(bytes: &[u8], max_values: u64) -> Result { + let mut pos = 0usize; + if bytes.starts_with(b"ID3") { + let size = bytes.get(6..10).ok_or(DecodeError::Truncated)?; + if size.iter().any(|&b| b & 0x80 != 0) { + return Err(DecodeError::Invalid("bad ID3v2 size")); + } + pos = 10 + size.iter().fold(0usize, |a, &b| a << 7 | usize::from(b)); + } + if bytes.get(pos..pos + 4) != Some(b"fLaC") { + return Err(DecodeError::Invalid("missing fLaC marker")); + } + pos += 4; + let mut info: Option = None; + loop { + let head = bytes.get(pos..pos + 4).ok_or(DecodeError::Truncated)?; + let last = head[0] & 0x80 != 0; + let kind = head[0] & 0x7F; + let len = usize::from(head[1]) << 16 | usize::from(head[2]) << 8 | usize::from(head[3]); + let body = bytes.get(pos + 4..pos + 4 + len).ok_or(DecodeError::Truncated)?; + match (kind, &info) { + (0, None) => info = Some(StreamInfo::parse(body)?), + (0, Some(_)) => return Err(DecodeError::Invalid("a second STREAMINFO block")), + (_, None) => return Err(DecodeError::Invalid("STREAMINFO is not the first block")), + (127, _) => return Err(DecodeError::Invalid("forbidden metadata block type")), + _ => {} + } + pos += 4 + len; + if last { + break; + } + } + let info = info.ok_or(DecodeError::Invalid("no STREAMINFO"))?; + let dec = Decoder::new(info); + let mut channels: Vec> = vec![Vec::new(); usize::from(info.channels)]; + let mut total = 0u64; + while pos + 2 <= bytes.len() && bytes[pos] == 0xFF && bytes[pos + 1] & 0xFE == 0xF8 { + let frame = dec.decode_frame(&bytes[pos..])?; + if frame.channels.len() != channels.len() { + return Err(DecodeError::Invalid("the channel count changes inside the stream")); + } + total += frame.block_size as u64; + if total.saturating_mul(channels.len() as u64) > max_values { + return Err(DecodeError::TooLarge); + } + for (dst, src) in channels.iter_mut().zip(frame.channels) { + dst.extend_from_slice(&src); + } + pos += frame.size; + } + if info.total_samples != 0 && total != info.total_samples { + return Err(DecodeError::Truncated); + } + Ok(Decoded { info, channels }) +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..f14530b26 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -27,7 +27,7 @@ //! - 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-decode`: the frame and file decoder; `flac-encode`: the packet encoder). //! //! The shared types below build with no features. @@ -88,10 +88,15 @@ pub use write::{OGG_BITRATES, encode_ogg}; /// assert!(file.len() < 48_000 * 2 * 2 / 2); // well under half of 16-bit PCM /// # Ok::<(), craft_audio::flac::Error>(()) /// ``` -#[cfg(feature = "flac-encode")] +#[cfg(any(feature = "flac-encode", feature = "flac-decode"))] pub mod flac { + #[cfg(feature = "flac-decode")] + pub use crate::flac_decode::{DEFAULT_MAX_VALUES, DecodeError, Decoded, Decoder, Frame, StreamInfo, decode, decode_with_limit}; + #[cfg(feature = "flac-encode")] pub use crate::write::flac::encoder::{Encoder, EncoderConfig, Error, STREAMINFO_OFFSET}; } +#[cfg(feature = "flac-decode")] +mod flac_decode; pub use buffer::AudioBuffer; /// The craft-media this crate is built with, for its containers: using it rather than a separate diff --git a/crates/audio/tests/flac_decode.rs b/crates/audio/tests/flac_decode.rs new file mode 100644 index 000000000..03d6d678e --- /dev/null +++ b/crates/audio/tests/flac_decode.rs @@ -0,0 +1,179 @@ +//! The native FLAC decoder: round trips through this crate's encoder over bit depths, channel +//! counts, block sizes and effort levels; hostile input; and ffmpeg as the reference (oracle; +//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`) for files +//! ffmpeg's encoder writes at every compression level. + +use craft_audio::flac::{DecodeError, Decoder, Encoder, EncoderConfig, STREAMINFO_OFFSET, StreamInfo, decode}; +use std::process::Command; + +fn signal(channels: usize, frames: usize, bits: u32, seed: u32) -> Vec> { + let max = if bits == 32 { i32::MAX as f64 } else { ((1i64 << (bits - 1)) - 1) as f64 }; + let mut s = seed; + (0..channels) + .map(|c| { + (0..frames) + .map(|i| { + s ^= s << 13; + s ^= s >> 17; + s ^= s << 5; + let t = i as f64; + let v = match (i / 3000) % 4 { + 0 => (t * (0.01 + 0.007 * c as f64)).sin() * 0.6 + (t * 0.31).sin() * 0.1, + 1 => (f64::from(s) / f64::from(u32::MAX) - 0.5) * 1.8, + 2 => 0.0, + _ => { + if (i / 40) % 2 == 0 { + 0.99 + } else { + -0.99 + } + } + }; + (v * max).round() as i32 + }) + .collect() + }) + .collect() +} + +fn encode(channels: &[Vec], rate: u32, bits: u8, block: u16, level: u8) -> Vec { + let mut cfg = EncoderConfig::new(rate, channels.len() as u8, bits); + cfg.block_size = block; + cfg.level = level; + let mut enc = Encoder::new(cfg).expect("encoder"); + let mut file = enc.header(&[]); + let refs: Vec<&[i32]> = channels.iter().map(Vec::as_slice).collect(); + file.extend(enc.encode(&refs).expect("encode")); + file.extend(enc.finish()); + let at = STREAMINFO_OFFSET as usize; + file[at..at + 34].copy_from_slice(&enc.streaminfo()); + file +} + +#[test] +fn round_trips_through_the_encoder() { + for (channels, bits) in [(1usize, 8u8), (2, 8), (1, 12), (2, 16), (2, 20), (3, 24), (6, 24), (8, 16), (2, 32), (1, 32)] { + for (block, level) in [(4096u16, 5u8), (16, 0), (1000, 8), (65535, 3), (576, 1)] { + let frames = 9000 + usize::from(block % 97); + let src = signal(channels, frames, u32::from(bits), 0x1234_5679 + u32::from(bits)); + let file = encode(&src, 44_100, bits, block, level); + let got = decode(&file).unwrap_or_else(|e| panic!("{channels}ch {bits}-bit block {block} level {level}: {e}")); + assert_eq!((got.info.channels as usize, got.info.bits_per_sample, got.info.sample_rate), (channels, bits, 44_100)); + assert_eq!(got.channels, src, "{channels}ch {bits}-bit block {block} level {level}"); + } + } +} + +#[test] +fn frames_decode_one_at_a_time() { + let src = signal(2, 10_000, 16, 7); + let file = encode(&src, 48_000, 16, 4096, 5); + let info = StreamInfo::parse(&file[STREAMINFO_OFFSET as usize..]).expect("streaminfo"); + let dec = Decoder::new(info); + // The first frame follows the metadata blocks; find the first position a frame decodes at. + let at = (42..file.len()).find(|&p| dec.decode_frame(&file[p..]).is_ok()).expect("a frame"); + let first = dec.decode_frame(&file[at..]).expect("frame"); + assert_eq!((first.block_size, first.number, first.sample_rate, first.bits_per_sample), (4096, 0, 48_000, 16)); + assert_eq!(first.channels[0], src[0][..4096]); + // Without the STREAMINFO a frame that spells out its own rate and depth still decodes. + let _ = Decoder::without_streaminfo().decode_frame(&file[at..]); +} + +#[test] +fn hostile_input_is_an_error_not_a_panic() { + let src = signal(2, 6000, 16, 11); + let file = encode(&src, 44_100, 16, 1152, 5); + for n in 0..file.len().min(3000) { + let _ = decode(&file[..n]); + } + // A cut file is truncated, not silently shorter. + assert!(decode(&file[..file.len() - 5]).is_err()); + // Every bit flip in the first frames is caught by a CRC or another check, never a panic. + for i in 0..file.len().min(2500) { + for bit in 0..8 { + let mut c = file.clone(); + c[i] ^= 1 << bit; + let _ = decode(&c); + } + } + // A sample limit stops a stream that claims too much. + assert_eq!(craft_audio::flac::decode_with_limit(&file, 1000), Err(DecodeError::TooLarge)); + assert!(decode(b"nope").is_err()); + assert!(decode(b"fLaC").is_err()); +} + +// ---- ffmpeg ---- + +fn ffmpeg_run(ff: &std::path::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 +} + +#[test] +fn ffmpeg_files_decode_to_ffmpegs_samples() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("flac_decode"); + let tones = "aevalsrc=exprs=0.4*sin(2*PI*441*t)+0.2*sin(2*PI*3100*t)|0.3*sin(2*PI*660*t)*sin(2*PI*3*t):s=44100:d=1.3"; + let noise = "anoisesrc=d=1.3:c=white:r=44100:a=0.5:s=3"; + for (src, name) in [(tones, "tones"), (noise, "noise")] { + for channels in [1usize, 2, 6] { + for (fmt, bytes, bits) in [("s16", 2usize, 16u32), ("s32", 4, 24)] { + for level in [0, 3, 5, 8, 12] { + let file = dir.join(format!("ffmpeg_{name}_{channels}ch_{bits}_l{level}.flac")); + let f = file.to_str().expect("path"); + let (ch, lv) = (channels.to_string(), level.to_string()); + ffmpeg_run(&ff, &["-f", "lavfi", "-i", src, "-ac", &ch, "-sample_fmt", fmt, "-compression_level", &lv, "-c:a", "flac", f]); + let theirs = ffmpeg_run(&ff, &["-i", f, "-f", if bits == 16 { "s16le" } else { "s32le" }, "-"]); + let got = + decode(&std::fs::read(&file).expect("read")).unwrap_or_else(|e| panic!("{name} {channels}ch {bits}-bit level {level}: {e}")); + assert_eq!(got.info.channels as usize, channels); + let frames = got.channels[0].len(); + assert_eq!(theirs.len(), frames * channels * bytes, "{name} {channels}ch {bits} l{level}: length"); + let mut ok = true; + for i in 0..frames { + for c in 0..channels { + let at = (i * channels + c) * bytes; + let want = if bytes == 2 { + i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) + } else { + i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) + }; + // ffmpeg returns 24-bit audio left-aligned in 32 bits. + let mine = if bits == 24 { got.channels[c][i] << 8 } else { got.channels[c][i] }; + if mine != want { + ok = false; + } + } + } + assert!(ok, "{name} {channels}ch {bits}-bit level {level}: samples differ from ffmpeg's decode"); + } + } + } + } +} + +#[test] +fn ffmpeg_decodes_our_files_to_our_samples() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("flac_decode"); + for (channels, bits) in [(1usize, 16u8), (2, 16), (2, 24), (6, 16)] { + let src = signal(channels, 20_000, u32::from(bits), 99); + let file = dir.join(format!("ours_{channels}ch_{bits}.flac")); + std::fs::write(&file, encode(&src, 44_100, bits, 4096, 5)).expect("write"); + let theirs = ffmpeg_run(&ff, &["-i", file.to_str().expect("path"), "-f", if bits == 16 { "s16le" } else { "s32le" }, "-"]); + let got = decode(&std::fs::read(&file).expect("read")).expect("decode"); + let bytes = if bits == 16 { 2 } else { 4 }; + for i in 0..20_000 { + for c in 0..channels { + let at = (i * channels + c) * bytes; + let want = if bytes == 2 { + i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) + } else { + i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) >> 8 + }; + assert_eq!(got.channels[c][i], want, "{channels}ch {bits}-bit sample {i} of channel {c}"); + } + } + } +} From 7b4d5f992c98ac8f8bff92505166254bd455ab92 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 15:18:25 +0100 Subject: [PATCH 051/349] craft-captions: ASS and SSA subtitles (Format::Ass) Reads the [Events] section of ASS v4+ and SSA v4 files and writes a minimal ASS v4+ file. Keeps line breaks, the Name field as the speaker and the \i, \b, \u override tags; other override tags and vector drawings are dropped. Closes #1550 --- Cargo.lock | 1 + crates/captions/Cargo.toml | 2 + crates/captions/README.md | 1 + crates/captions/src/ass.rs | 239 +++++++++++++++++++++++++++++++ crates/captions/src/lib.rs | 17 ++- crates/captions/tests/it/ass.rs | 113 +++++++++++++++ crates/captions/tests/it/main.rs | 1 + 7 files changed, 371 insertions(+), 3 deletions(-) create mode 100644 crates/captions/src/ass.rs create mode 100644 crates/captions/tests/it/ass.rs diff --git a/Cargo.lock b/Cargo.lock index 8e12a6995..55552f9f9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1425,6 +1425,7 @@ version = "0.1.0" name = "craft-captions" version = "0.1.0" dependencies = [ + "craft-media-testkit", "craft-timeline", "craft-xml", "proptest", diff --git a/crates/captions/Cargo.toml b/crates/captions/Cargo.toml index df665336d..cd09f7e16 100644 --- a/crates/captions/Cargo.toml +++ b/crates/captions/Cargo.toml @@ -19,3 +19,5 @@ thiserror = { workspace = true } proptest = { workspace = true } # A second XML reader for the tests: checks of written TTML, and the comparison in tests/it/ttml_xml_views.rs. roxmltree = "0.21" +# ffmpeg as the reference for the ASS tests (tests/it/ass.rs). +craft-media-testkit = { workspace = true } diff --git a/crates/captions/README.md b/crates/captions/README.md index 0676d1d72..7380a3ce4 100644 --- a/crates/captions/README.md +++ b/crates/captions/README.md @@ -55,6 +55,7 @@ lists at most 20 characters per stream. | EBU STL `.stl` | yes | yes | EBU Tech 3264-E: GSI block + 128-byte TTI blocks, `STL25.01` (25 fps) or `STL30.01` (read/written as 29.97 fps, non-drop labels), ISO/IEC 6937 Latin text (accents as diacritic + letter), italics / underline codes as `` / ``, extension blocks for long subtitles, start-of-programme (TCP) subtracted. | | TTML `.ttml` (IMSC1) | yes | yes | Writes the IMSC1 Text profile (TTML2 namespaces) with the document's language as `xml:lang` (read back on import): `

                      ` per cue, `
                      `, styled ``s for `` / `` / ``, `ttm:agent` speakers, exact frame times (`123f`) at the sequence rate. Reads any TTML (TTML1, TTML2, the 2006 `ttaf1` drafts): clock / frame / offset / tick times, `dur`, nested time containers (`body` / `div` begins offset and ends clip their contents; `seq` containers are read as `par` with a warning), timed spans, referenced styles. | | DFXP `.dfxp` | yes | yes | TTML1 with the DFXP presentation profile; clock times in milliseconds (frame-exact after `snap_to_frames`). | +| ASS / SSA `.ass`, `.ssa` | yes | yes (ASS v4+) | The `[Events]` section: `Dialogue:` lines through the file's `Format:` line, `Name` as the speaker, `\N`, `\n`, `\h` and the `\i`, `\b`, `\u` override tags kept (as ``, ``, ``); other override tags and drawing lines are dropped. Times are centiseconds. Written files have one `Default` style. | All cue times are exact `Tick`s. Milliseconds convert exactly (1 ms = 254 016 000 ticks); SCC frames map through `FrameRate::FPS_29_97`. `Document::snap_to_frames` snaps cues to a frame grid and diff --git a/crates/captions/src/ass.rs b/crates/captions/src/ass.rs new file mode 100644 index 000000000..3c907c829 --- /dev/null +++ b/crates/captions/src/ass.rs @@ -0,0 +1,239 @@ +//! Advanced SubStation Alpha and SubStation Alpha (`.ass`, `.ssa`). +//! +//! Reading takes the `[Events]` section: its `Format:` line gives the field order (ASS v4+ and SSA +//! v4 differ in the first field only), each `Dialogue:` line becomes a cue; `Comment:` lines and +//! the other sections are skipped. A cue gets the `Name` field as its speaker. The text keeps what +//! the neutral model can show: `\N` and `\n` become a line break and a space, `\h` a no-break +//! space, and the override tags `\i`, `\b` and `\u` become ``, `` and ``. Every other +//! override tag (colours, fonts, positions, karaoke, animation) is dropped, and a line that draws +//! vector shapes (`\p1`) is skipped with a warning. +//! +//! Writing gives a minimal ASS v4+ file: one `Default` style, one `Dialogue:` line per cue with +//! times to the centisecond. Braces in the text, which ASS reads as override blocks, are written +//! as the full-width `{` and `�`. + +use crate::time::{TICKS_PER_SECOND, Tick}; +use crate::{Cue, Document, Error, Result}; + +const TICKS_PER_CS: i64 = TICKS_PER_SECOND / 100; + +/// `H:MM:SS.cc`, the form SSA and ASS use (any number of fraction digits is read). +fn parse_time(s: &str) -> Option { + let s = s.trim(); + let (hms, frac) = s.split_once('.').unwrap_or((s, "")); + let mut parts = hms.split(':'); + let (h, m, sec) = (parts.next()?, parts.next()?, parts.next()?); + if parts.next().is_some() { + return None; + } + let num = |p: &str| -> Option { (!p.is_empty() && p.len() <= 9 && p.bytes().all(|b| b.is_ascii_digit())).then(|| p.parse().ok()).flatten() }; + let (h, m, sec) = (num(h)?, num(m)?, num(sec)?); + if m >= 60 || sec >= 60 || h > 9999 { + return None; + } + let mut ticks = ((h * 60 + m) * 60 + sec) * TICKS_PER_SECOND; + if !frac.is_empty() { + if frac.len() > 9 || !frac.bytes().all(|b| b.is_ascii_digit()) { + return None; + } + let d: i64 = frac.parse().ok()?; + ticks += (i128::from(d) * i128::from(TICKS_PER_SECOND) / 10i128.pow(frac.len() as u32)) as i64; + } + Some(Tick(ticks)) +} + +fn format_time(t: Tick) -> String { + let cs = (i128::from(t.0.max(0)) + i128::from(TICKS_PER_CS) / 2) / i128::from(TICKS_PER_CS); + let (h, m, s, c) = (cs / 360_000, (cs / 6000) % 60, (cs / 100) % 60, cs % 100); + format!("{h}:{m:02}:{s:02}.{c:02}") +} + +/// The Text field of a Dialogue line as cue text; `None` when the line draws shapes. +fn convert_text(raw: &str) -> Option { + let mut out = String::new(); + // Open ``, ``, `` in the order they were opened. + let mut open: Vec = Vec::new(); + let mut chars = raw.chars().peekable(); + let mut drawing = false; + let mut dropped_drawing = false; + while let Some(c) = chars.next() { + match c { + '{' => { + let mut block = String::new(); + let mut closed = false; + for b in chars.by_ref() { + if b == '}' { + closed = true; + break; + } + block.push(b); + } + if !closed { + // An unterminated block is literal text. + out.push('{'); + out.push_str(&block); + continue; + } + for tag in block.split('\\').skip(1) { + let tag = tag.trim_end(); + let (name, val) = tag.split_at(tag.find(|c: char| !c.is_ascii_alphabetic()).unwrap_or(tag.len())); + match name { + "i" | "b" | "u" => { + let letter = name.chars().next().unwrap_or('i'); + let on = val.trim() != "0"; + if on && !open.contains(&letter) { + open.push(letter); + out.push_str(&format!("<{letter}>")); + } else if !on && open.contains(&letter) { + // Close back to it, reopening what was opened after. + let at = open.iter().position(|&o| o == letter).unwrap_or(0); + let after: Vec = open.split_off(at + 1); + for o in after.iter().rev() { + out.push_str(&format!("")); + } + open.pop(); + out.push_str(&format!("")); + for o in after { + open.push(o); + out.push_str(&format!("<{o}>")); + } + } + } + "p" => drawing = val.trim().parse::().unwrap_or(0) != 0, + _ => {} + } + } + } + '\\' => match chars.peek() { + Some('N') => { + chars.next(); + out.push('\n'); + } + Some('n') => { + chars.next(); + out.push(' '); + } + Some('h') => { + chars.next(); + out.push('\u{a0}'); + } + _ => out.push('\\'), + }, + c => { + if drawing { + dropped_drawing = true; + } else { + out.push(c); + } + } + } + } + if dropped_drawing && out.trim().is_empty() { + return None; + } + while let Some(o) = open.pop() { + out.push_str(&format!("")); + } + Some(out) +} + +pub fn parse(text: &str) -> Result { + let text = text.strip_prefix('\u{feff}').unwrap_or(text); + let mut doc = Document::default(); + let mut in_events = false; + let mut saw_events = false; + // Column of each field in a Dialogue line. + let mut cols: Vec = + ["layer", "start", "end", "style", "name", "marginl", "marginr", "marginv", "effect", "text"].map(String::from).to_vec(); + let mut drawings = 0usize; + for (n, line) in text.lines().enumerate() { + let line = line.trim(); + if line.starts_with('[') && line.ends_with(']') { + in_events = line.eq_ignore_ascii_case("[events]"); + saw_events |= in_events; + continue; + } + if !in_events { + continue; + } + let Some((key, rest)) = line.split_once(':') else { continue }; + let rest = rest.trim_start(); + match key.trim().to_ascii_lowercase().as_str() { + "format" => cols = rest.split(',').map(|f| f.trim().to_ascii_lowercase()).collect(), + "dialogue" => { + // The last column (Text) keeps its commas. + let fields: Vec<&str> = rest.splitn(cols.len(), ',').collect(); + let get = |name: &str| cols.iter().position(|c| c == name).and_then(|i| fields.get(i)).copied(); + let (Some(start), Some(end), Some(raw)) = (get("start").and_then(parse_time), get("end").and_then(parse_time), get("text")) else { + doc.warnings.push(format!("line {}: not a Dialogue line this reader understands", n + 1)); + continue; + }; + let Some(text) = convert_text(raw) else { + drawings += 1; + continue; + }; + let name = get("name").map(str::trim).filter(|s| !s.is_empty()); + doc.cues.push(Cue { start, end, text, speaker: name.map(str::to_string), ..Default::default() }); + } + _ => {} + } + } + if !saw_events { + return Err(Error::NotFormat("ASS")); + } + if drawings > 0 { + doc.warnings.push(format!("{drawings} vector drawing line(s) were skipped")); + } + Ok(doc) +} + +fn escape(text: &str) -> String { + let mut out = String::with_capacity(text.len() + 8); + let mut rest = text; + while !rest.is_empty() { + if let Some(r) = rest.strip_prefix("") { + out.push_str("{\\i1}"); + rest = r; + } else if let Some(r) = rest.strip_prefix("") { + out.push_str("{\\i0}"); + rest = r; + } else if let Some(r) = rest.strip_prefix("") { + out.push_str("{\\b1}"); + rest = r; + } else if let Some(r) = rest.strip_prefix("") { + out.push_str("{\\b0}"); + rest = r; + } else if let Some(r) = rest.strip_prefix("") { + out.push_str("{\\u1}"); + rest = r; + } else if let Some(r) = rest.strip_prefix("") { + out.push_str("{\\u0}"); + rest = r; + } else if let Some(c) = rest.chars().next() { + match c { + '\n' => out.push_str("\\N"), + '{' => out.push('\u{ff5b}'), + '}' => out.push('\u{ff5d}'), + '\u{a0}' => out.push_str("\\h"), + c => out.push(c), + } + rest = &rest[c.len_utf8()..]; + } + } + out +} + +pub fn write(doc: &Document) -> String { + let mut out = String::from( + "[Script Info]\n; Written by craft-captions\nScriptType: v4.00+\nWrapStyle: 0\nScaledBorderAndShadow: yes\nPlayResX: 384\nPlayResY: 288\n\n\ + [V4+ Styles]\nFormat: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding\n\ + Style: Default,Arial,16,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,1,0,2,10,10,10,1\n\n\ + [Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n", + ); + for c in &doc.cues { + // A comma in the Name field would shift the columns; the other fields are fixed text. + let name = c.speaker.as_deref().unwrap_or("").replace([',', '\n'], " "); + out.push_str(&format!("Dialogue: 0,{},{},Default,{},0,0,0,,{}\n", format_time(c.start), format_time(c.end), name, escape(&c.text))); + } + out +} diff --git a/crates/captions/src/lib.rs b/crates/captions/src/lib.rs index 0ba9f2ba5..e8a492722 100644 --- a/crates/captions/src/lib.rs +++ b/crates/captions/src/lib.rs @@ -4,7 +4,7 @@ //! - **Files:** [SubRip](srt) (`.srt`), [WebVTT](vtt) (`.vtt`), [Scenarist SCC](scc) (`.scc`, //! CEA-608 pop-on, roll-up and paint-on on read; pop-on on write), [MacCaption MCC](mcc) //! (`.mcc`, SMPTE ST 334-2 packets with CEA-608 and CEA-708), [EBU STL](stl) (`.stl`, EBU -//! Tech 3264) and [TTML](ttml) (`.ttml` IMSC1 Text profile, `.dfxp` DFXP) parse into a +//! Tech 3264), [ASS/SSA](ass) (`.ass`, `.ssa`) and [TTML](ttml) (`.ttml` IMSC1 Text profile, `.dfxp` DFXP) parse into a //! [`Document`] of [`Cue`]s and write back. Readers are forgiving (BOM, UTF-16, Windows-1252 //! fallback, CRLF/CR, missing SRT indexes, `,` or `.` milliseconds, missing hours, no blank //! line between cues); writers are strict. WebVTT cue identifiers, cue settings, `` @@ -32,6 +32,7 @@ #[doc = include_str!("../README.md")] struct ReadmeExamples; +pub mod ass; pub mod cea608; pub mod mcc; pub mod scc; @@ -69,10 +70,12 @@ pub enum Format { Ttml, /// DFXP (TTML1). Dfxp, + /// Advanced SubStation Alpha (also reads SubStation Alpha). + Ass, } impl Format { - pub const ALL: [Format; 7] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp]; + pub const ALL: [Format; 8] = [Format::Srt, Format::WebVtt, Format::Scc, Format::Mcc, Format::Stl, Format::Ttml, Format::Dfxp, Format::Ass]; pub fn name(self) -> &'static str { match self { Format::Srt => "SubRip (SRT)", @@ -82,6 +85,7 @@ impl Format { Format::Stl => "EBU STL", Format::Ttml => "TTML (IMSC1)", Format::Dfxp => "DFXP (TTML1)", + Format::Ass => "Advanced SubStation Alpha (ASS)", } } pub fn extension(self) -> &'static str { @@ -93,6 +97,7 @@ impl Format { Format::Stl => "stl", Format::Ttml => "ttml", Format::Dfxp => "dfxp", + Format::Ass => "ass", } } pub fn from_name(s: &str) -> Option { @@ -104,6 +109,7 @@ impl Format { "stl" | "ebu-stl" | "ebustl" | "ebu" => Some(Format::Stl), "ttml" | "imsc" | "imsc1" | "xml" => Some(Format::Ttml), "dfxp" => Some(Format::Dfxp), + "ass" | "ssa" => Some(Format::Ass), _ => None, } } @@ -251,6 +257,9 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option { if head.starts_with("File Format=MacCaption_MCC") { return Some(Format::Mcc); } + if head.starts_with("[Script Info]") { + return Some(Format::Ass); + } let ext = ext.map(|e| e.trim_start_matches('.').to_ascii_lowercase()); if (head.starts_with('<') && (head.contains("") || head.contains(":tt "))) && (head.contains("ns/ttml") || head.contains("ttaf1")) @@ -262,7 +271,7 @@ pub fn detect(bytes: &[u8], ext: Option<&str>) -> Option { match ext.as_deref() { Some("srt") if has_arrow_timing || head.is_empty() => Some(Format::Srt), Some("vtt") if has_arrow_timing => Some(Format::WebVtt), - Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml") => None, + Some("srt" | "vtt" | "scc" | "mcc" | "stl" | "ttml" | "dfxp" | "xml" | "ass" | "ssa") => None, _ if has_arrow_timing => Some(Format::Srt), _ => None, } @@ -296,6 +305,7 @@ fn parse_unbounded(bytes: &[u8], format: Format) -> Result { Format::Scc => scc::parse(&text), Format::Mcc => mcc::parse(&text), Format::Ttml | Format::Dfxp => ttml::parse(&text), + Format::Ass => ass::parse(&text), Format::Stl => stl::parse(bytes), } } @@ -333,6 +343,7 @@ pub fn write(doc: &Document, format: Format, opts: WriteOptions) -> Vec { Format::Stl => stl::write(doc, opts.rate, opts.program), Format::Ttml => ttml::write(doc, ttml::Flavor::Imsc1, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(), Format::Dfxp => ttml::write(doc, ttml::Flavor::Dfxp, opts.rate, doc.language.as_deref().unwrap_or("")).into_bytes(), + Format::Ass => ass::write(doc).into_bytes(), } } diff --git a/crates/captions/tests/it/ass.rs b/crates/captions/tests/it/ass.rs new file mode 100644 index 000000000..de5d43167 --- /dev/null +++ b/crates/captions/tests/it/ass.rs @@ -0,0 +1,113 @@ +//! SubStation Alpha / Advanced SubStation Alpha: reading, writing, and ffmpeg as the reference +//! (oracle; skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). + +use craft_captions::{Cue, Document, Format, Tick, WriteOptions, detect, parse, write}; +use std::process::Command; + +const T: i64 = craft_captions::TICKS_PER_SECOND; + +fn cs(n: i64) -> Tick { + Tick(n * (T / 100)) +} + +const SAMPLE: &str = "\u{feff}[Script Info]\n; a comment\nTitle: Test\nScriptType: v4.00+\n\n[V4+ Styles]\nFormat: Name, Fontname\nStyle: Default,Arial\n\n[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nComment: 0,0:00:00.00,0:00:01.00,Default,,0,0,0,,not a cue\nDialogue: 0,0:00:01.50,0:00:03.25,Default,Bob,0,0,0,,Hello, {\\i1}world{\\i0}\\Nsecond {\\b1}line{\\b0}\nDialogue: 0,1:02:03.04,1:02:04.5,Default,,0,0,0,,{\\pos(10,20)\\c&H0000FF&}Red\\hspace\\nsoft\nDialogue: 0,0:00:09.00,0:00:10.00,Default,,0,0,0,,{\\p1}m 0 0 l 100 0 100 100{\\p0}\n"; + +#[test] +fn reads_dialogue_lines_with_commas_overrides_and_line_breaks() { + let doc = parse(SAMPLE.as_bytes(), Format::Ass).unwrap(); + assert_eq!(doc.cues.len(), 2); + assert_eq!(doc.cues[0].start, cs(150)); + assert_eq!(doc.cues[0].end, cs(325)); + assert_eq!(doc.cues[0].text, "Hello, world\nsecond line"); + assert_eq!(doc.cues[0].speaker.as_deref(), Some("Bob")); + // 1:02:03.04, a one-digit fraction, an override block dropped, \h and \n. + assert_eq!(doc.cues[1].start, Tick((3600 + 120 + 3) * T + 4 * (T / 100))); + assert_eq!(doc.cues[1].end, Tick((3600 + 120 + 4) * T + T / 2)); + assert_eq!(doc.cues[1].text, "Red\u{a0}space soft"); + assert!(doc.warnings.iter().any(|w| w.contains("vector drawing")), "{:?}", doc.warnings); +} + +#[test] +fn ssa_v4_files_read_through_their_own_format_line() { + let ssa = "[Script Info]\nScriptType: v4.00\n\n[V4 Styles]\nFormat: Name\n\n[Events]\nFormat: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nDialogue: Marked=0,0:00:01.00,0:00:02.00,*Default,,0000,0000,0000,,Old style\n"; + let doc = parse(ssa.as_bytes(), Format::Ass).unwrap(); + assert_eq!((doc.cues[0].start, doc.cues[0].end, doc.cues[0].text.as_str()), (cs(100), cs(200), "Old style")); +} + +#[test] +fn write_then_read_keeps_times_text_and_speaker() { + let cues = vec![ + Cue { start: cs(100), end: cs(250), text: "Line one\nline two".into(), speaker: Some("Ann".into()), ..Default::default() }, + Cue { + start: Tick(7200 * T + 99 * (T / 100)), + end: Tick(7203 * T), + text: "bold and under {braces}".into(), + ..Default::default() + }, + ]; + let doc = Document { cues, ..Default::default() }; + let bytes = write(&doc, Format::Ass, WriteOptions::default()); + assert_eq!(detect(&bytes, Some("ass")), Some(Format::Ass)); + let back = parse(&bytes, Format::Ass).unwrap(); + assert_eq!(back.cues[0], doc.cues[0]); + assert_eq!(back.cues[1].start, doc.cues[1].start); + // Braces are written full-width, as ASS reads `{` as the start of an override block. + assert_eq!(back.cues[1].text, "bold and under \u{ff5b}braces\u{ff5d}"); +} + +#[test] +fn files_without_an_events_section_are_not_ass() { + assert!(parse(b"[Script Info]\nTitle: x\n", Format::Ass).is_err()); + assert!(parse(b"hello", Format::Ass).is_err()); + assert_eq!(detect(b"hello", Some("ass")), None); +} + +#[test] +fn bad_lines_are_skipped_with_a_warning() { + let text = "[Events]\nFormat: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\nDialogue: 0,garbage,0:00:02.00,Default,,0,0,0,,x\nDialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,ok\n"; + let doc = parse(text.as_bytes(), Format::Ass).unwrap(); + assert_eq!(doc.cues.len(), 1); + assert_eq!(doc.warnings.len(), 1); +} + +fn ffmpeg_run(ff: &std::path::Path, args: &[&str]) { + 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)); +} + +const SRT: &str = "1\n00:00:01,500 --> 00:00:03,250\nHello, world\nsecond line\n\n2\n00:00:04,000 --> 00:00:05,990\nPlain, with a comma\n\n3\n01:00:00,010 --> 01:00:02,999\nUnder and italic both\n"; + +#[test] +fn we_read_what_ffmpeg_writes() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("captions_ass"); + let (srt, ass) = (dir.join("in.srt"), dir.join("ffmpeg.ass")); + std::fs::write(&srt, SRT).expect("write"); + ffmpeg_run(&ff, &["-i", srt.to_str().expect("path"), ass.to_str().expect("path")]); + let from_ass = parse(&std::fs::read(&ass).expect("read"), Format::Ass).expect("parse ass"); + let from_srt = parse(SRT.as_bytes(), Format::Srt).expect("parse srt"); + assert_eq!(from_ass.cues.len(), from_srt.cues.len()); + for (a, s) in from_ass.cues.iter().zip(&from_srt.cues) { + // ASS times are centiseconds; the SRT ones round to them. + assert_eq!(a.start, cs((s.start.0 + T / 200) / (T / 100)), "start of {:?}", s.text); + assert_eq!(a.end, cs((s.end.0 + T / 200) / (T / 100)), "end of {:?}", s.text); + assert_eq!(a.text, s.text); + } +} + +#[test] +fn ffmpeg_reads_what_we_write() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("captions_ass"); + let doc = parse(SRT.as_bytes(), Format::Srt).expect("parse srt"); + let (ass, srt) = (dir.join("ours.ass"), dir.join("back.srt")); + std::fs::write(&ass, write(&doc, Format::Ass, WriteOptions::default())).expect("write"); + ffmpeg_run(&ff, &["-i", ass.to_str().expect("path"), srt.to_str().expect("path")]); + let theirs = parse(&std::fs::read(&srt).expect("read"), Format::Srt).expect("parse back"); + assert_eq!(theirs.cues.len(), doc.cues.len()); + for (t, d) in theirs.cues.iter().zip(&doc.cues) { + assert_eq!(t.start, cs((d.start.0 + T / 200) / (T / 100))); + assert_eq!(t.end, cs((d.end.0 + T / 200) / (T / 100))); + assert_eq!(t.text, d.text, "text of the cue at {:?}", d.start); + } +} diff --git a/crates/captions/tests/it/main.rs b/crates/captions/tests/it/main.rs index 16f8fcbb6..be03d2855 100644 --- a/crates/captions/tests/it/main.rs +++ b/crates/captions/tests/it/main.rs @@ -1,3 +1,4 @@ +mod ass; mod limits; mod literal_roundtrips; mod mcc_708_timing; From 2d5f2e4a73eb54326b3192120a7a4457ad79b07f Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 15:25:56 +0100 Subject: [PATCH 052/349] craft-audio: flac_decode tests without index loops (CI clippy) --- crates/audio/tests/flac_decode.rs | 49 ++++++++++++++----------------- 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/crates/audio/tests/flac_decode.rs b/crates/audio/tests/flac_decode.rs index 03d6d678e..c35267b08 100644 --- a/crates/audio/tests/flac_decode.rs +++ b/crates/audio/tests/flac_decode.rs @@ -104,6 +104,21 @@ fn hostile_input_is_an_error_not_a_panic() { // ---- ffmpeg ---- +/// Little-endian 16- or 32-bit samples of raw PCM. +fn pcm_values(raw: &[u8], bytes: usize) -> Vec { + if bytes == 2 { + raw.as_chunks::<2>().0.iter().map(|b| i32::from(i16::from_le_bytes(*b))).collect() + } else { + raw.as_chunks::<4>().0.iter().map(|b| i32::from_le_bytes(*b)).collect() + } +} + +/// Planar channels as interleaved samples. +fn interleave(channels: &[Vec]) -> Vec { + let frames = channels.first().map_or(0, Vec::len); + (0..frames).flat_map(|i| channels.iter().map(move |c| c[i])).collect() +} + fn ffmpeg_run(ff: &std::path::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)); @@ -130,22 +145,10 @@ fn ffmpeg_files_decode_to_ffmpegs_samples() { assert_eq!(got.info.channels as usize, channels); let frames = got.channels[0].len(); assert_eq!(theirs.len(), frames * channels * bytes, "{name} {channels}ch {bits} l{level}: length"); - let mut ok = true; - for i in 0..frames { - for c in 0..channels { - let at = (i * channels + c) * bytes; - let want = if bytes == 2 { - i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) - } else { - i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) - }; - // ffmpeg returns 24-bit audio left-aligned in 32 bits. - let mine = if bits == 24 { got.channels[c][i] << 8 } else { got.channels[c][i] }; - if mine != want { - ok = false; - } - } - } + // ffmpeg returns 24-bit audio left-aligned in 32 bits. + let shift = if bits == 24 { 8 } else { 0 }; + let mine: Vec = interleave(&got.channels).into_iter().map(|v| v << shift).collect(); + let ok = mine == pcm_values(&theirs, bytes); assert!(ok, "{name} {channels}ch {bits}-bit level {level}: samples differ from ffmpeg's decode"); } } @@ -164,16 +167,8 @@ fn ffmpeg_decodes_our_files_to_our_samples() { let theirs = ffmpeg_run(&ff, &["-i", file.to_str().expect("path"), "-f", if bits == 16 { "s16le" } else { "s32le" }, "-"]); let got = decode(&std::fs::read(&file).expect("read")).expect("decode"); let bytes = if bits == 16 { 2 } else { 4 }; - for i in 0..20_000 { - for c in 0..channels { - let at = (i * channels + c) * bytes; - let want = if bytes == 2 { - i32::from(i16::from_le_bytes([theirs[at], theirs[at + 1]])) - } else { - i32::from_le_bytes([theirs[at], theirs[at + 1], theirs[at + 2], theirs[at + 3]]) >> 8 - }; - assert_eq!(got.channels[c][i], want, "{channels}ch {bits}-bit sample {i} of channel {c}"); - } - } + let shift = if bytes == 4 { 8 } else { 0 }; + let want: Vec = pcm_values(&theirs, bytes).into_iter().map(|v| v >> shift).collect(); + assert!(interleave(&got.channels) == want, "{channels}ch {bits}-bit: samples differ from ffmpeg's decode"); } } From b850981f835f39859077cf62ff4e76462e76167c Mon Sep 17 00:00:00 2001 From: FredApps <153173854+FredApps@users.noreply.github.com> Date: Sun, 15 Nov 2026 15:29:08 +0100 Subject: [PATCH 053/349] craft-audio: port EffectCraft's later Opus encoder speed-ups The shared encoder was imported from storytold/effectcraft@c618429. EffectCraft's copy has since gained @vangel76's speed-ups (effectcraft #2394, #2398, #2399, #2402, #2403, #2404) and the strict-Clippy CELT stage refactor. Port them so EffectCraft can drop crates/opusenc without slowing WebM export. Packets are byte-identical to effectcraft-opusenc at d6c9ad66 (2100 packets across SILK, hybrid and CELT, mono and stereo, 10-320 kb/s). The shared Error API is unchanged. Refs #778 --- crates/audio/src/opus/encoder/bands.rs | 341 +++++++++++++++--- crates/audio/src/opus/encoder/energy.rs | 25 +- crates/audio/src/opus/encoder/mdct.rs | 95 ++++- crates/audio/src/opus/encoder/mod.rs | 67 ++-- crates/audio/src/opus/encoder/rate.rs | 88 ++--- crates/audio/src/opus/encoder/resample.rs | 31 +- .../audio/src/opus/encoder/silk/analysis.rs | 112 +++++- crates/audio/src/opus/encoder/silk/mod.rs | 168 ++++++++- 8 files changed, 748 insertions(+), 179 deletions(-) diff --git a/crates/audio/src/opus/encoder/bands.rs b/crates/audio/src/opus/encoder/bands.rs index 604aab595..697332eb2 100644 --- a/crates/audio/src/opus/encoder/bands.rs +++ b/crates/audio/src/opus/encoder/bands.rs @@ -8,7 +8,8 @@ use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog}; use crate::opus::encoder::rate::{Mode, QTHETA_OFFSET, get_pulses}; -use crate::opus::encoder::tables::{EBANDS, NB_EBANDS}; +use crate::opus::encoder::tables::EBANDS; +use crate::opus::encoder::{CeltFrame, rate::Allocation}; pub const SPREAD_NORMAL: usize = 2; @@ -55,7 +56,7 @@ fn exp_rotation1_inv(x: &mut [f32], len: usize, stride: usize, c: f32, s: f32) { if len <= stride { return; } - if len >= 2 * stride + 1 { + if len > 2 * stride { for i in 0..=len - 2 * stride - 1 { let x1 = x[i]; let x2 = x[i + stride]; @@ -96,12 +97,24 @@ pub fn exp_rotation_inv(x: &mut [f32], len: usize, k: usize, spread: usize) { } } +/// Relative slack for the pulse-candidate filter in [`pvq_search`]: far above the f32 rounding of +/// the filter score (a few 1e-7), far below the spread of real scores. +const PVQ_SCORE_SLACK: f32 = 1e-5; + /// Greedy PVQ search: the integer vector `y` with `sum |y| = k` closest in direction to `x`. pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) { let n = x.len(); y[..n].fill(0); - let abs: Vec = x.iter().map(|v| v.abs()).collect(); - let sum: f32 = abs.iter().sum(); + // `abs`, `dy` (2 y + 1, infinite in the padding) and the per-pass scores `score`, each padded to + // whole 8-lane chunks. + let np = n.next_multiple_of(8); + let mut buf = vec![0f32; 3 * np]; + let (abs, rest) = buf.split_at_mut(np); + let (dy, score) = rest.split_at_mut(np); + for (a, v) in abs.iter_mut().zip(x) { + *a = v.abs(); + } + let sum: f32 = abs[..n].iter().sum(); if !sum.is_finite() || sum <= 1e-15 { y[0] = k as i32; return; @@ -113,30 +126,69 @@ pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) { // Pre-project onto the pyramid (rounding down) and place the rest greedily. let r = (k as f32 - 1.0) / sum; for j in 0..n { - let p = (abs[j] * r).floor() as i32; + // Non-negative and at most k, so the truncating cast is the floor. + let p = (abs[j] * r) as i32; y[j] = p; placed += p as usize; xy += abs[j] * p as f32; yy += (p * p) as f32; } } + for j in 0..np { + dy[j] = if j < n { 2.0 * y[j] as f32 + 1.0 } else { f32::INFINITY }; + } while placed < k { + // Vectorisable scores (xy + |x_j|)^2 / (yy + 2 y_j + 1) and their maximum. + for ((sc, &a), &d) in score.iter_mut().zip(abs.iter()).zip(dy.iter()) { + let t = xy + a; + *sc = t * t / (yy + d); + } + let mut lane_max = [0f32; 8]; + for c in score.as_chunks::<8>().0 { + for i in 0..8 { + lane_max[i] = if c[i] > lane_max[i] { c[i] } else { lane_max[i] }; + } + } + let top = lane_max.iter().fold(0f32, |m, &v| if v > m { v } else { m }); + // The exact cross-multiplied test below, in index order with the first maximum winning, only + // matters for entries within rounding distance of the top score: every other entry is beaten + // by the top one whenever it is reached and never beats it afterwards. Running the test on + // those alone therefore picks the same pulse as running it on all of them. + let filter = top > 1e-30 && top.is_finite(); + let lo = top * (1.0 - PVQ_SCORE_SLACK); + // Usually exactly one entry qualifies; its index falls out of a lane-wise count. + let mut count = [0u32; 8]; + let mut index = [0u32; 8]; + for (ci, c) in score.as_chunks::<8>().0.iter().enumerate() { + for i in 0..8 { + let hit = u32::from(c[i] >= lo); + count[i] += hit; + index[i] += hit * (ci * 8 + i) as u32; + } + } let mut best = 0usize; - let mut best_num = -1f32; - let mut best_den = 1f32; - for j in 0..n { - let num = xy + abs[j]; - let num = num * num; - let den = yy + 2.0 * y[j] as f32 + 1.0; - if num * best_den > best_num * den { - best_num = num; - best_den = den; - best = j; + if filter && count.iter().sum::() == 1 { + best = index.iter().sum::() as usize; + } else { + let mut best_num = -1f32; + let mut best_den = 1f32; + for j in 0..n { + if !filter || score[j] >= lo { + let num = xy + abs[j]; + let num = num * num; + let den = yy + 2.0 * y[j] as f32 + 1.0; + if num * best_den > best_num * den { + best_num = num; + best_den = den; + best = j; + } + } } } xy += abs[best]; yy += 2.0 * y[best] as f32 + 1.0; y[best] += 1; + dy[best] = 2.0 * y[best] as f32 + 1.0; placed += 1; } for j in 0..n { @@ -146,25 +198,45 @@ pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) { } } -/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps -/// back to `y`. -pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec) { - let n = y.len(); - let w = k + 1; - v.clear(); - v.resize((n + 1) * w, 0); +/// Largest band width and pulse count the encoder codes (176 coefficients, `get_pulses(40)` = 128). +const PVQ_MAX_N: usize = 176; +const PVQ_MAX_K: usize = 128; + +/// Row-major `V(n, k)` for `n <= max_n`, `k <= max_k` with row stride `max_k + 1`, saturated at +/// `u32::MAX` (a codebook that large is never coded, see `rate::fits_in32`). +fn build_pvq_table(max_n: usize, max_k: usize) -> Vec { + let w = max_k + 1; + let mut v = vec![0u32; (max_n + 1) * w]; v[0] = 1; - for nn in 1..=n { + for nn in 1..=max_n { v[nn * w] = 1; - for kk in 1..=k { - let a = v[(nn - 1) * w + kk]; - let b = v[nn * w + kk - 1]; - let c = v[(nn - 1) * w + kk - 1]; - v[nn * w + kk] = a.saturating_add(b).saturating_add(c); + for kk in 1..=max_k { + let sum = v[(nn - 1) * w + kk] as u64 + v[nn * w + kk - 1] as u64 + v[(nn - 1) * w + kk - 1] as u64; + v[nn * w + kk] = sum.min(u32::MAX as u64) as u32; } } - let total = v[n * w + k]; - let vv = |nn: usize, kx: usize| v[nn * w + kx]; + v +} + +fn pvq_table() -> &'static [u32] { + static TABLE: std::sync::OnceLock> = std::sync::OnceLock::new(); + TABLE.get_or_init(|| build_pvq_table(PVQ_MAX_N, PVQ_MAX_K)) +} + +/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps +/// back to `y`. +pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder) { + let n = y.len(); + // Shapes outside the coded range (never produced by the band layout) get a local table. + let local; + let (v, w) = if n <= PVQ_MAX_N && k <= PVQ_MAX_K { + (pvq_table(), PVQ_MAX_K + 1) + } else { + local = build_pvq_table(n, k); + (&local[..], k + 1) + }; + let row = |nn: usize| &v[nn * w..(nn + 1) * w]; + let total = row(n)[k] as u64; let mut index = 0u64; let mut kk = k; for j in 0..n { @@ -173,10 +245,11 @@ pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec { pub i: usize, pub spread: usize, pub remaining_bits: i32, - pvq_v: Vec, iy: Vec, tmp: Vec, } @@ -217,7 +289,7 @@ impl BandEnc<'_, '_> { let q = qn as u32; let half = q >> 1; let ft = (half + 1) * (half + 1); - let (fl, fs) = if it <= half { (it * (it + 1) >> 1, it + 1) } else { (ft - ((q + 1 - it) * (q + 2 - it) >> 1), q + 1 - it) }; + let (fl, fs) = if it <= half { ((it * (it + 1)) >> 1, it + 1) } else { (ft - (((q + 1 - it) * (q + 2 - it)) >> 1), q + 1 - it) }; self.enc.encode(fl, fl + fs, ft); itheta = ((it * 16384) / q) as i32; } @@ -287,36 +359,29 @@ impl BandEnc<'_, '_> { iy.clear(); iy.resize(n, 0); pvq_search(&tmp, k, &mut iy); - encode_pulses(&iy, k, self.enc, &mut self.pvq_v); + encode_pulses(&iy, k, self.enc); self.iy = iy; self.tmp = tmp; } } } -/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds `c` channels -/// of `n` normalised MDCT coefficients each. -#[allow(clippy::too_many_arguments)] -pub fn quant_all_bands( - m: &Mode, - start: usize, - end: usize, - x: &[f32], - n_total: usize, - c: usize, - pulses: &[i32; NB_EBANDS], - spread: usize, - dual_stereo: bool, - intensity: usize, - total_bits: i32, - mut balance: i32, - enc: &mut RangeEncoder, - lm: usize, - coded_bands: usize, -) { +/// Shape-coding controls, independent of the selected band allocation. +pub struct BandCoding { + pub spread: usize, + pub total_bits: i32, +} + +/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds +/// `frame.channels` channels of `n_total` normalised MDCT coefficients each. +pub fn quant_all_bands(m: &Mode, frame: CeltFrame, x: &[f32], n_total: usize, allocation: &Allocation, coding: BandCoding, enc: &mut RangeEncoder) { + let CeltFrame { start, end, channels: c, lm } = frame; + let Allocation { pulses, dual_stereo, intensity, coded_bands, balance, .. } = allocation; + let (dual_stereo, intensity, coded_bands, mut balance) = (*dual_stereo, *intensity, *coded_bands, *balance); + let BandCoding { spread, total_bits } = coding; let mm = 1usize << lm; debug_assert!(c == 1 || dual_stereo || intensity <= start, "stereo frames are coded as dual stereo"); - let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, pvq_v: Vec::new(), iy: Vec::new(), tmp: Vec::new() }; + let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, iy: Vec::new(), tmp: Vec::new() }; for i in start..end { ctx.i = i; let xo = mm * EBANDS[i] as usize; @@ -362,7 +427,7 @@ mod tests { x[i + stride] = c * x2 + s * x1; x[i] = c * x1 + ms * x2; } - if len >= 2 * stride + 1 { + if len > 2 * stride { for i in (0..=len - 2 * stride - 1).rev() { let x1 = x[i]; let x2 = x[i + stride]; @@ -466,12 +531,11 @@ mod tests { #[test] fn pvq_index_roundtrip_exhaustive() { - let mut v = Vec::new(); for n in 1..6usize { for k in 1..6usize { for y in all_codewords(n, k) { let mut e = RangeEncoder::new(); - encode_pulses(&y, k, &mut e, &mut v); + encode_pulses(&y, k, &mut e); let buf = e.done(16); let mut d = RangeDecoder::new(&buf); assert_eq!(decode_pulses(n, k, &mut d), y, "n={n} k={k}"); @@ -480,6 +544,165 @@ mod tests { } } + /// The per-call table encoder this module used before the shared table. + fn encode_pulses_reference(y: &[i32], k: usize, enc: &mut RangeEncoder) { + let n = y.len(); + let w = k + 1; + let mut v = vec![0u64; (n + 1) * w]; + v[0] = 1; + for nn in 1..=n { + v[nn * w] = 1; + for kk in 1..=k { + let a = v[(nn - 1) * w + kk]; + let b = v[nn * w + kk - 1]; + let c = v[(nn - 1) * w + kk - 1]; + v[nn * w + kk] = a.saturating_add(b).saturating_add(c); + } + } + let total = v[n * w + k]; + let vv = |nn: usize, kx: usize| v[nn * w + kx]; + let mut index = 0u64; + let mut kk = k; + for j in 0..n { + if kk == 0 { + break; + } + let rem = n - j; + let t = y[j].unsigned_abs() as usize; + let mut base: u64 = (0..kk - t).map(|m| vv(rem - 1, m)).sum(); + if y[j] < 0 { + base += (vv(rem - 1, kk) + vv(rem, kk)) / 2; + } + index += base; + kk -= t; + } + if total >= 2 { + enc.uint(index as u32, total as u32); + } + } + + #[test] + fn pvq_table_encode_matches_per_call_table() { + let mut seed = 0x9E37_79B9_7F4A_7C15u64; + let mut next = move |m: u64| { + seed ^= seed << 13; + seed ^= seed >> 7; + seed ^= seed << 17; + seed % m + }; + let mut checked = 0; + for n in (1..=PVQ_MAX_N).step_by(5).chain([PVQ_MAX_N]) { + for k in (1..=PVQ_MAX_K).step_by(3).chain([PVQ_MAX_K]) { + if crate::opus::encoder::rate::pvq_v(n, k) > u32::MAX as u128 { + continue; + } + for _ in 0..4 { + let mut y = vec![0i32; n]; + for _ in 0..k { + let at = next(n as u64) as usize; + y[at] += if next(2) == 0 { 1 } else { -1 }; + } + // Opposite pulses cancel; top up so that sum |y| = k again. + let mut have: usize = y.iter().map(|v| v.unsigned_abs() as usize).sum(); + while have < k { + let at = next(n as u64) as usize; + y[at] += if y[at] < 0 { -1 } else { 1 }; + have += 1; + } + let (mut a, mut b) = (RangeEncoder::new(), RangeEncoder::new()); + encode_pulses(&y, k, &mut a); + encode_pulses_reference(&y, k, &mut b); + assert_eq!(a.done(16), b.done(16), "n={n} k={k}"); + checked += 1; + } + } + } + assert!(checked > 100, "{checked}"); + } + + /// The scalar greedy search the vectorised one replaced. + fn pvq_search_ref(x: &[f32], k: usize, y: &mut [i32]) { + let n = x.len(); + y[..n].fill(0); + let abs: Vec = x.iter().map(|v| v.abs()).collect(); + let sum: f32 = abs.iter().sum(); + if !sum.is_finite() || sum <= 1e-15 { + y[0] = k as i32; + return; + } + let mut placed = 0usize; + let mut xy = 0f32; + let mut yy = 0f32; + if k > n / 2 { + let r = (k as f32 - 1.0) / sum; + for j in 0..n { + let p = (abs[j] * r).floor() as i32; + y[j] = p; + placed += p as usize; + xy += abs[j] * p as f32; + yy += (p * p) as f32; + } + } + while placed < k { + let mut best = 0usize; + let mut best_num = -1f32; + let mut best_den = 1f32; + for j in 0..n { + let num = xy + abs[j]; + let num = num * num; + let den = yy + 2.0 * y[j] as f32 + 1.0; + if num * best_den > best_num * den { + best_num = num; + best_den = den; + best = j; + } + } + xy += abs[best]; + yy += 2.0 * y[best] as f32 + 1.0; + y[best] += 1; + placed += 1; + } + for j in 0..n { + if x[j] < 0.0 { + y[j] = -y[j]; + } + } + } + + #[test] + fn pvq_search_matches_scalar_reference() { + let mut state = 0x9e3779b97f4a7c15u64; + let mut rnd = move || { + state ^= state << 13; + state ^= state >> 7; + state ^= state << 17; + (state >> 40) as f32 / (1u64 << 24) as f32 * 2.0 - 1.0 + }; + let mut a = vec![0i32; 200]; + let mut b = vec![0i32; 200]; + let mut cases = 0; + for round in 0..6000 { + let n = 1 + (round * 37 + (rnd().abs() * 176.0) as usize) % 176; + let k = 1 + (rnd().abs() * 127.0) as usize; + let scale = [1.0f32, 1e-9, 1e6, 3e-3][round % 4]; + let x: Vec = (0..n) + .map(|_| match round % 6 { + 0 => rnd(), + 1 => if rnd() > 0.8 { rnd() } else { 0.0 }, + 2 => (rnd() * 4.0).round() / 4.0, + 3 => if rnd() > 0.0 { 1.0 } else { -1.0 }, + 4 => rnd().powi(5), + _ => if rnd() > 0.95 { 3.0 * rnd() } else { 1e-4 * rnd() }, + } * scale) + .collect(); + pvq_search(&x, k, &mut a); + pvq_search_ref(&x, k, &mut b); + assert_eq!(a[..n], b[..n], "n={n} k={k} round={round}"); + cases += 1; + } + assert_eq!(cases, 6000); + } + #[test] fn pvq_search_finds_good_direction() { let x: Vec = (0..32).map(|i| ((i as f32) * 0.7).sin()).collect(); diff --git a/crates/audio/src/opus/encoder/energy.rs b/crates/audio/src/opus/encoder/energy.rs index 8d4f357d0..fb5cc5a4b 100644 --- a/crates/audio/src/opus/encoder/energy.rs +++ b/crates/audio/src/opus/encoder/energy.rs @@ -4,8 +4,9 @@ //! The quantised energies are updated with exactly the decoder's arithmetic so the prediction //! state never drifts between encoder and decoder. +use crate::opus::encoder::CeltFrame; use crate::opus::encoder::range::RangeEncoder; -use crate::opus::encoder::rate::MAX_FINE_BITS; +use crate::opus::encoder::rate::{Allocation, MAX_FINE_BITS}; use crate::opus::encoder::tables::{BETA_COEF, BETA_INTRA, E_PROB_MODEL, NB_EBANDS, PRED_COEF, SMALL_ENERGY_ICDF}; const LAPLACE_MINP: u32 = 1; @@ -56,18 +57,15 @@ pub fn laplace_encode(enc: &mut RangeEncoder, value: i32, mut fs: u32, decay: u3 /// `quant_coarse_energy` for one prediction mode. `e` holds the target log2 energies (relative /// to `E_MEANS`), `old_e` the quantised energies, updated in place. `budget` is the frame size in /// bits. -#[allow(clippy::too_many_arguments)] pub fn quant_coarse_energy( - start: usize, - end: usize, + frame: CeltFrame, e: &[f32; 2 * NB_EBANDS], old_e: &mut [f32; 2 * NB_EBANDS], intra: bool, enc: &mut RangeEncoder, - c: usize, - lm: usize, budget: i32, ) { + let CeltFrame { start, end, channels: c, lm } = frame; let prob = &E_PROB_MODEL[lm][intra as usize]; let (coef, beta) = if intra { (0.0, BETA_INTRA) } else { (PRED_COEF[lm], BETA_COEF[lm]) }; let mut prev = [0f32; 2]; @@ -112,14 +110,13 @@ pub fn quant_coarse_energy( /// `quant_fine_energy`: raw bits refining each band's quantised energy. pub fn quant_fine_energy( - start: usize, - end: usize, + frame: CeltFrame, e: &[f32; 2 * NB_EBANDS], old_e: &mut [f32; 2 * NB_EBANDS], fine_quant: &[i32; NB_EBANDS], enc: &mut RangeEncoder, - c: usize, ) { + let CeltFrame { start, end, channels: c, .. } = frame; for i in start..end { let fq = fine_quant[i]; if fq <= 0 { @@ -139,18 +136,16 @@ pub fn quant_fine_energy( /// `quant_energy_finalise`: spends the bits left at the end of the frame on one more bit of /// energy resolution per band, in priority order. -#[allow(clippy::too_many_arguments)] pub fn quant_energy_finalise( - start: usize, - end: usize, + frame: CeltFrame, e: &[f32; 2 * NB_EBANDS], old_e: &mut [f32; 2 * NB_EBANDS], - fine_quant: &[i32; NB_EBANDS], - fine_priority: &[i32; NB_EBANDS], + allocation: &Allocation, mut bits_left: i32, enc: &mut RangeEncoder, - c: usize, ) { + let CeltFrame { start, end, channels: c, .. } = frame; + let Allocation { fine_quant, fine_priority, .. } = allocation; for prio in 0..2 { let mut i = start; while i < end && bits_left >= c as i32 { diff --git a/crates/audio/src/opus/encoder/mdct.rs b/crates/audio/src/opus/encoder/mdct.rs index 6a42cce96..fa5624514 100644 --- a/crates/audio/src/opus/encoder/mdct.rs +++ b/crates/audio/src/opus/encoder/mdct.rs @@ -24,6 +24,10 @@ impl Cpx { fn add(self, o: Cpx) -> Cpx { Cpx { re: self.re + o.re, im: self.im + o.im } } + #[inline] + fn sub(self, o: Cpx) -> Cpx { + Cpx { re: self.re - o.re, im: self.im - o.im } + } } /// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled (decimation in time, recursive). @@ -71,18 +75,64 @@ impl Fft { self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p); } } - let big = self.n; - let mut t = [Cpx::default(); 5]; - for k in 0..m { - for (q, tq) in t.iter_mut().enumerate().take(p) { - *tq = out[q * m + k].mul(self.twiddle[(q * k * tw_stride) % big]); + // The twiddle index q * k * tw_stride is always below n, so no modulo is needed. + let tw = &self.twiddle; + match p { + 2 => { + for k in 0..m { + let a0 = out[k]; + let a1 = out[m + k].mul(tw[k * tw_stride]); + out[k] = a0.add(a1); + out[m + k] = a0.sub(a1); + } } - for q2 in 0..p { - let mut acc = Cpx::default(); - for (q, tq) in t.iter().enumerate().take(p) { - acc = acc.add(tq.mul(self.twiddle[((q * q2) % p) * (big / p)])); + 4 => { + for k in 0..m { + let t0 = out[k]; + let t1 = out[m + k].mul(tw[k * tw_stride]); + let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]); + let t3 = out[3 * m + k].mul(tw[3 * k * tw_stride]); + let (s0, d0) = (t0.add(t2), t0.sub(t2)); + let (s1, d1) = (t1.add(t3), t1.sub(t3)); + out[k] = s0.add(s1); + out[2 * m + k] = s0.sub(s1); + // The odd outputs combine d0 with -j * d1 = (d1.im, -d1.re) and its negative. + out[m + k] = Cpx { re: d0.re + d1.im, im: d0.im - d1.re }; + out[3 * m + k] = Cpx { re: d0.re - d1.im, im: d0.im + d1.re }; + } + } + 3 => { + // Imaginary part of exp(-2 pi i / 3) = -sqrt(3) / 2. + let h = tw[self.n / 3].im; + for k in 0..m { + let t0 = out[k]; + let t1 = out[m + k].mul(tw[k * tw_stride]); + let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]); + let (s, d) = (t1.add(t2), t1.sub(t2)); + let a = Cpx { re: t0.re - 0.5 * s.re, im: t0.im - 0.5 * s.im }; + out[k] = t0.add(s); + // j * h * d = (-h * d.im, h * d.re) + out[m + k] = Cpx { re: a.re - h * d.im, im: a.im + h * d.re }; + out[2 * m + k] = Cpx { re: a.re + h * d.im, im: a.im - h * d.re }; + } + } + _ => { + // Generic DFT butterfly (radix 5, once per transform). + let roots: [Cpx; 5] = std::array::from_fn(|q| if q < p { tw[q * (self.n / p)] } else { Cpx::default() }); + let mut t = [Cpx::default(); 5]; + for k in 0..m { + t[0] = out[k]; + for q in 1..p { + t[q] = out[q * m + k].mul(tw[q * k * tw_stride]); + } + for q2 in 0..p { + let mut acc = t[0]; + for q in 1..p { + acc = acc.add(t[q].mul(roots[(q * q2) % p])); + } + out[q2 * m + k] = acc; + } } - out[q2 * m + k] = acc; } } } @@ -199,6 +249,31 @@ mod tests { .collect() } + #[test] + fn fft_matches_dft() { + // Every radix combination, including the 480-point size of the 20 ms frame. + for &n in &[2usize, 3, 4, 5, 6, 8, 12, 15, 16, 20, 24, 30, 48, 60, 120, 240, 480] { + let fft = Fft::new(n); + let x: Vec = (0..n).map(|i| Cpx { re: ((i * 37 % 101) as f32 - 50.0) / 7.0, im: ((i * 53 % 89) as f32 - 44.0) / 9.0 }).collect(); + let mut y = x.clone(); + fft.process(&mut y, &mut Vec::new()); + for k in 0..n { + let (mut re, mut im) = (0f64, 0f64); + for (j, v) in x.iter().enumerate() { + let ph = -2.0 * std::f64::consts::PI * ((j * k) % n) as f64 / n as f64; + re += v.re as f64 * ph.cos() - v.im as f64 * ph.sin(); + im += v.re as f64 * ph.sin() + v.im as f64 * ph.cos(); + } + assert!( + (y[k].re as f64 - re).abs() < 2e-3 && (y[k].im as f64 - im).abs() < 2e-3, + "n={n} k={k}: ({}, {}) vs ({re}, {im})", + y[k].re, + y[k].im + ); + } + } + } + #[test] fn matches_direct_formula() { for &n in &[240usize, 960] { diff --git a/crates/audio/src/opus/encoder/mod.rs b/crates/audio/src/opus/encoder/mod.rs index cbb0d7984..a635cce40 100644 --- a/crates/audio/src/opus/encoder/mod.rs +++ b/crates/audio/src/opus/encoder/mod.rs @@ -10,8 +10,9 @@ //! above in the same range-coded frame; constant packet size. //! - **CELT** (fullband): MDCT transform coding; constant packet size. //! -//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429). Public items keep their -//! names, so EffectCraft can re-export this module. +//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429), with its later speed-ups +//! and CELT stage refactor up to storytold/effectcraft@d6c9ad66. Public items keep their names, so +//! EffectCraft can re-export this module. //! //! ``` //! # #[cfg(feature = "opus-encode")] { @@ -26,6 +27,7 @@ //! # } //! ``` +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] // The bit-allocation code mirrors the normative integer arithmetic; keep C-like shift expressions. #![allow(clippy::precedence, clippy::int_plus_one)] @@ -40,15 +42,24 @@ mod tables; use std::sync::OnceLock; -use bands::{SPREAD_NORMAL, quant_all_bands}; +use bands::{BandCoding, SPREAD_NORMAL, quant_all_bands}; use energy::{quant_coarse_energy, quant_energy_finalise, quant_fine_energy}; use mdct::Mdct; use range::{BITRES, RangeEncoder}; -use rate::{Mode as CeltMode, compute_allocation}; +use rate::{AllocationInput, Mode as CeltMode, compute_allocation}; use resample::Downsampler; use silk::SilkEncoder; use tables::{E_MEANS, EBANDS, NB_EBANDS, OVERLAP, PREEMPH, SPREAD_ICDF, TF_SELECT_TABLE, TRIM_ICDF}; +/// Band range, channel count and transform size shared by CELT coding stages. +#[derive(Clone, Copy)] +struct CeltFrame { + start: usize, + end: usize, + channels: usize, + lm: usize, +} + /// Samples per channel in one 20 ms frame at 48 kHz. const N: usize = 960; /// LM of a 20 ms frame (8 short blocks). @@ -338,7 +349,7 @@ impl Encoder { Mode::Celt => { let (log_e, silence) = self.celt_analysis(pcm); let len = self.frame_bytes; - packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0, NB_EBANDS, &log_e, silence)); + packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0..NB_EBANDS, &log_e, silence)); } Mode::Silk => { let x = self.silk_input(pcm); @@ -368,7 +379,7 @@ impl Encoder { } let (log_e, _) = self.celt_analysis(pcm); let end = if self.bandwidth == Bandwidth::SuperWideband { 19 } else { NB_EBANDS }; - packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND, end, &log_e, false)); + packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND..end, &log_e, false)); } } Ok(packet) @@ -430,10 +441,18 @@ impl Encoder { /// Codes one CELT frame (RFC 6716 §4.3, in bitstream order) of `len` bytes into `enc` /// (which already holds the SILK frame in hybrid mode), coding bands `start..end`, and /// finalises the frame. - #[allow(clippy::too_many_arguments)] - fn encode_celt(&mut self, mut enc: RangeEncoder, len: usize, start: usize, end: usize, log_e: &[f32; 2 * NB_EBANDS], silence: bool) -> Vec { + fn encode_celt( + &mut self, + mut enc: RangeEncoder, + len: usize, + bands: std::ops::Range, + log_e: &[f32; 2 * NB_EBANDS], + silence: bool, + ) -> Vec { let m = celt_mode(); let c = self.channels; + let frame = CeltFrame { start: bands.start, end: bands.end, channels: c, lm: LM }; + let CeltFrame { start, end, .. } = frame; if c == 1 { for i in 0..NB_EBANDS { self.old_band_e[i] = self.old_band_e[i].max(self.old_band_e[NB_EBANDS + i]); @@ -462,10 +481,10 @@ impl Encoder { let mut enc_intra = enc.clone(); let mut old_intra = self.old_band_e; enc_intra.bit_logp(true, 3); - quant_coarse_energy(start, end, log_e, &mut old_intra, true, &mut enc_intra, c, LM, total_bits_raw); + quant_coarse_energy(frame, log_e, &mut old_intra, true, &mut enc_intra, total_bits_raw); enc.bit_logp(false, 3); let mut old_inter = self.old_band_e; - quant_coarse_energy(start, end, log_e, &mut old_inter, false, &mut enc, c, LM, total_bits_raw); + quant_coarse_energy(frame, log_e, &mut old_inter, false, &mut enc, total_bits_raw); if enc_intra.tell_frac() < enc.tell_frac() { enc = enc_intra; self.old_band_e = old_intra; @@ -473,14 +492,14 @@ impl Encoder { self.old_band_e = old_inter; } } else { - quant_coarse_energy(start, end, log_e, &mut self.old_band_e, false, &mut enc, c, LM, total_bits_raw); + quant_coarse_energy(frame, log_e, &mut self.old_band_e, false, &mut enc, total_bits_raw); } // TF resolution: no changes. { let mut budget = total_bits_raw; let mut tell = enc.tell(); let mut logp = 4; - let tf_select_rsv = LM > 0 && tell + logp + 1 <= budget; + let tf_select_rsv = LM > 0 && tell + logp < budget; budget -= tf_select_rsv as i32; for _ in start..end { if tell + logp <= budget { @@ -512,27 +531,11 @@ impl Encoder { enc.icdf(alloc_trim as usize, &TRIM_ICDF, 7); } let bits = (total_bits_raw << BITRES) - enc.tell_frac() - 1; - let alloc = compute_allocation(m, start, end, &offsets, &cap, alloc_trim, bits, c, LM, &mut enc); - quant_fine_energy(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc, c); - quant_all_bands( - m, - start, - end, - &self.freq, - N, - c, - &alloc.pulses, - SPREAD_NORMAL, - alloc.dual_stereo, - alloc.intensity, - total_bits_raw << BITRES, - alloc.balance, - &mut enc, - LM, - alloc.coded_bands, - ); + let alloc = compute_allocation(m, frame, AllocationInput { offsets: &offsets, cap: &cap, trim: alloc_trim, bits }, &mut enc); + quant_fine_energy(frame, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc); + quant_all_bands(m, frame, &self.freq, N, &alloc, BandCoding { spread: SPREAD_NORMAL, total_bits: total_bits_raw << BITRES }, &mut enc); let bits_left = total_bits_raw - enc.tell(); - quant_energy_finalise(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &alloc.fine_priority, bits_left, &mut enc, c); + quant_energy_finalise(frame, log_e, &mut self.old_band_e, &alloc, bits_left, &mut enc); debug_assert!(enc.tell() <= total_bits_raw, "frame overflow: {} > {}", enc.tell(), total_bits_raw); if c == 1 { let (a, b) = self.old_band_e.split_at_mut(NB_EBANDS); diff --git a/crates/audio/src/opus/encoder/rate.rs b/crates/audio/src/opus/encoder/rate.rs index c360f9da7..58349bbd7 100644 --- a/crates/audio/src/opus/encoder/rate.rs +++ b/crates/audio/src/opus/encoder/rate.rs @@ -4,6 +4,7 @@ //! spec-derived `filmcraft-opus` decoder (first-party, MIT OR Apache-2.0) step by step; the only //! difference is that the encoder *writes* the band-skip, intensity and dual-stereo symbols. +use crate::opus::encoder::CeltFrame; use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog}; use crate::opus::encoder::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS}; @@ -127,7 +128,7 @@ impl Mode { let mut cap = [0i32; NB_EBANDS]; for (i, cp) in cap.iter_mut().enumerate() { let n = (EBANDS[i + 1] - EBANDS[i]) << lm; - *cp = (self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n >> 2; + *cp = ((self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n) >> 2; } cap } @@ -200,7 +201,7 @@ fn compute_caps(m: &Mode) -> Vec { let mut n0 = EBANDS[j + 1] - EBANDS[j]; let max_bits = if n0 << i == 1 { - c * (1 + MAX_FINE_BITS) << BITRES + (c * (1 + MAX_FINE_BITS)) << BITRES } else { let mut lm0 = 0; if n0 > 2 { @@ -240,7 +241,7 @@ fn compute_caps(m: &Mode) -> Vec { let num = mb + ndof * offset; let den = (ndof - 1) << BITRES; let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS); - mb += c * qb << BITRES; + mb += (c * qb) << BITRES; mb }; let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i); @@ -263,21 +264,19 @@ pub struct Allocation { pub fine_priority: [i32; NB_EBANDS], } +/// Per-band limits, boosts and available budget for the allocation search. +pub struct AllocationInput<'a> { + pub offsets: &'a [i32; NB_EBANDS], + pub cap: &'a [i32; NB_EBANDS], + pub trim: i32, + pub bits: i32, +} + /// `clt_compute_allocation`, encoder side. Stereo frames are always coded as dual (L/R) stereo /// with no intensity bands, and no band is skipped voluntarily. -#[allow(clippy::too_many_arguments)] -pub fn compute_allocation( - m: &Mode, - start: usize, - end: usize, - offsets: &[i32; NB_EBANDS], - cap: &[i32; NB_EBANDS], - alloc_trim: i32, - total: i32, - c: usize, - lm: usize, - enc: &mut RangeEncoder, -) -> Allocation { +pub fn compute_allocation(m: &Mode, frame: CeltFrame, input: AllocationInput<'_>, enc: &mut RangeEncoder) -> Allocation { + let CeltFrame { start, end, channels: c, lm } = frame; + let AllocationInput { offsets, cap, trim: alloc_trim, bits: total } = input; let ci = c as i32; let lmi = lm as i32; let mut total = total.max(0); @@ -302,8 +301,8 @@ pub fn compute_allocation( let mut trim_offset = [0i32; NB_EBANDS]; for j in start..end { let w = EBANDS[j + 1] - EBANDS[j]; - thresh[j] = (ci << BITRES).max((3 * w << lmi << BITRES) >> 4); - trim_offset[j] = ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32)) >> 6; + thresh[j] = (ci << BITRES).max(((3 * w) << lmi << BITRES) >> 4); + trim_offset[j] = (ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32))) >> 6; if w << lmi == 1 { trim_offset[j] -= ci << BITRES; } @@ -317,7 +316,7 @@ pub fn compute_allocation( let mid = (lo + hi) >> 1; for j in (start..end).rev() { let n = EBANDS[j + 1] - EBANDS[j]; - let mut bitsj = ci * n * (ALLOC[mid as usize][j] as i32) << lmi >> 2; + let mut bitsj = (ci * n * (ALLOC[mid as usize][j] as i32)) << lmi >> 2; if bitsj > 0 { bitsj = (bitsj + trim_offset[j]).max(0); } @@ -342,8 +341,8 @@ pub fn compute_allocation( lo -= 1; for j in start..end { let n = EBANDS[j + 1] - EBANDS[j]; - let mut bits1j = ci * n * (ALLOC[lo as usize][j] as i32) << lmi >> 2; - let mut bits2j = if hi >= nb_alloc { cap[j] } else { ci * n * (ALLOC[hi as usize][j] as i32) << lmi >> 2 }; + let mut bits1j = (ci * n * (ALLOC[lo as usize][j] as i32)) << lmi >> 2; + let mut bits2j = if hi >= nb_alloc { cap[j] } else { (ci * n * (ALLOC[hi as usize][j] as i32)) << lmi >> 2 }; if bits1j > 0 { bits1j = (bits1j + trim_offset[j]).max(0); } @@ -361,27 +360,28 @@ pub fn compute_allocation( bits1[j] = bits1j; bits2[j] = bits2j; } - interp_bits2pulses(m, start, end, skip_start, &bits1, &bits2, &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv, c, lm, enc) + let interpolation = + AllocationInterpolation { skip_start, bits1: &bits1, bits2: &bits2, thresh: &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv }; + interp_bits2pulses(m, frame, interpolation, enc) } -#[allow(clippy::too_many_arguments)] -fn interp_bits2pulses( - m: &Mode, - start: usize, - end: usize, +/// Bracketing allocation vectors and signalling reserves for the interpolation stage. +struct AllocationInterpolation<'a> { skip_start: usize, - bits1: &[i32; NB_EBANDS], - bits2: &[i32; NB_EBANDS], - thresh: &[i32; NB_EBANDS], - cap: &[i32; NB_EBANDS], - mut total: i32, + bits1: &'a [i32; NB_EBANDS], + bits2: &'a [i32; NB_EBANDS], + thresh: &'a [i32; NB_EBANDS], + cap: &'a [i32; NB_EBANDS], + total: i32, skip_rsv: i32, - mut intensity_rsv: i32, - mut dual_stereo_rsv: i32, - c: usize, - lm: usize, - enc: &mut RangeEncoder, -) -> Allocation { + intensity_rsv: i32, + dual_stereo_rsv: i32, +} + +fn interp_bits2pulses(m: &Mode, frame: CeltFrame, interpolation: AllocationInterpolation<'_>, enc: &mut RangeEncoder) -> Allocation { + let CeltFrame { start, end, channels: c, lm } = frame; + let AllocationInterpolation { skip_start, bits1, bits2, thresh, cap, mut total, skip_rsv, mut intensity_rsv, mut dual_stereo_rsv } = + interpolation; let ci = c as i32; let alloc_floor = ci << BITRES; let stereo = (c > 1) as i32; @@ -393,7 +393,7 @@ fn interp_bits2pulses( let mut psum = 0; let mut done = false; for j in (start..end).rev() { - let tmp = bits1[j] + (mid * bits2[j] >> ALLOC_STEPS); + let tmp = bits1[j] + ((mid * bits2[j]) >> ALLOC_STEPS); if tmp >= thresh[j] || done { done = true; psum += tmp.min(cap[j]); @@ -411,7 +411,7 @@ fn interp_bits2pulses( let mut psum = 0; let mut done = false; for j in (start..end).rev() { - let mut tmp = bits1[j] + (lo * bits2[j] >> ALLOC_STEPS); + let mut tmp = bits1[j] + ((lo * bits2[j]) >> ALLOC_STEPS); if tmp < thresh[j] && !done { tmp = if tmp >= alloc_floor { alloc_floor } else { 0 }; } else { @@ -500,9 +500,9 @@ fn interp_bits2pulses( if n == 2 { offset += (den << BITRES) >> 2; } - if bits[j] + offset < den * 2 << BITRES { + if bits[j] + offset < (den * 2) << BITRES { offset += nclogn >> 2; - } else if bits[j] + offset < den * 3 << BITRES { + } else if bits[j] + offset < (den * 3) << BITRES { offset += nclogn >> 3; } let mut eb = (bits[j] + offset + (den << (BITRES - 1))).max(0); @@ -513,7 +513,7 @@ fn interp_bits2pulses( eb = eb.min(MAX_FINE_BITS); ebits[j] = eb; fine_priority[j] = (eb * (den << BITRES) >= bits[j] + offset) as i32; - bits[j] -= ci * eb << BITRES; + bits[j] -= (ci * eb) << BITRES; } else { excess = (bit - (ci << BITRES)).max(0); bits[j] = bit - excess; @@ -523,7 +523,7 @@ fn interp_bits2pulses( if excess > 0 { let extra_fine = (excess >> (stereo + BITRES as i32)).min(MAX_FINE_BITS - ebits[j]); ebits[j] += extra_fine; - let extra_bits = extra_fine * ci << BITRES; + let extra_bits = (extra_fine * ci) << BITRES; fine_priority[j] = (extra_bits >= excess - balance) as i32; excess -= extra_bits; } diff --git a/crates/audio/src/opus/encoder/resample.rs b/crates/audio/src/opus/encoder/resample.rs index 9045cb86d..1acc9a4e7 100644 --- a/crates/audio/src/opus/encoder/resample.rs +++ b/crates/audio/src/opus/encoder/resample.rs @@ -45,6 +45,25 @@ fn design(fc: f64, beta: f64, delay: usize) -> Vec { h.iter().map(|&v| v as f32).collect() } +/// Dot product with eight independent partial sums, which the compiler can vectorise (a single +/// running sum is bound by the latency of the float addition). The sums are combined pairwise. +#[inline] +fn dot8(a: &[f32], b: &[f32]) -> f32 { + let mut s = [0f32; 8]; + let (ca, ra) = a.as_chunks::<8>(); + let (cb, rb) = b.as_chunks::<8>(); + for (x, y) in ca.iter().zip(cb) { + for l in 0..8 { + s[l] += x[l] * y[l]; + } + } + let mut acc = ((s[0] + s[4]) + (s[1] + s[5])) + ((s[2] + s[6]) + (s[3] + s[7])); + for (x, y) in ra.iter().zip(rb) { + acc += x * y; + } + acc +} + /// Decimates one channel of 48 kHz audio by 3, 4 or 6. #[derive(Clone)] pub struct Downsampler { @@ -77,7 +96,7 @@ impl Downsampler { let t = taps - 1 + self.factor * j; let win = &self.buf[t + 1 - taps..=t]; // h is symmetric, so the window can be taken in forward order. - out.push(win.iter().zip(&self.h).map(|(a, b)| a * b).sum()); + out.push(dot8(win, &self.h)); } let n = self.buf.len(); self.buf.copy_within(n - (taps - 1).., 0); @@ -97,6 +116,16 @@ mod tests { (x.iter().map(|&v| (v as f64).powi(2)).sum::() / x.len() as f64).sqrt() } + #[test] + fn dot8_matches_sequential_sum() { + for len in [0usize, 1, 7, 8, 9, 63, 167, 251] { + let a: Vec = (0..len).map(|i| ((i * 37 % 101) as f32 - 50.0) / 50.0).collect(); + let b: Vec = (0..len).map(|i| ((i * 53 % 89) as f32 - 44.0) / 44.0).collect(); + let exact: f64 = a.iter().zip(&b).map(|(&x, &y)| x as f64 * y as f64).sum(); + assert!((dot8(&a, &b) as f64 - exact).abs() < 1e-4, "len {len}"); + } + } + #[test] fn passes_band_and_rejects_aliases() { for &(fs, pass, stop) in &[(16_000u32, 6_000.0, 8_600.0), (12_000, 4_500.0, 6_500.0), (8_000, 3_000.0, 4_500.0)] { diff --git a/crates/audio/src/opus/encoder/silk/analysis.rs b/crates/audio/src/opus/encoder/silk/analysis.rs index 439331076..d80052046 100644 --- a/crates/audio/src/opus/encoder/silk/analysis.rs +++ b/crates/audio/src/opus/encoder/silk/analysis.rs @@ -69,28 +69,55 @@ pub fn levinson(r: &[f64], order: usize) -> Vec { } /// Evaluates the symmetric polynomial `p` (length `d + 1`, `d` even) as the cosine series -/// `e^{jωd/2} P(e^{jω})`. -fn cos_series(p: &[f64], w: f64) -> f64 { +/// `e^{jωd/2} P(e^{jω})`, with `cos_m(m)` giving `cos(m ω)`. +#[inline] +fn cos_series_with(p: &[f64], cos_m: impl Fn(usize) -> f64) -> f64 { let h = (p.len() - 1) / 2; let mut s = p[h]; for k in 0..h { - s += 2.0 * p[k] * ((h - k) as f64 * w).cos(); + s += 2.0 * p[k] * cos_m(h - k); } s } +fn cos_series(p: &[f64], w: f64) -> f64 { + cos_series_with(p, |m| (m as f64 * w).cos()) +} + +/// Number of grid intervals the root search scans over `[0, π]`. +const GRID: usize = 1024; +/// Largest multiple of ω in the series (half the LPC order, at most 16 / 2). +const MAX_H: usize = 8; +/// Bisection steps per root: the bracket shrinks to 3e-9 rad, far below one Q15 NLSF step (9.6e-5 rad). +const BISECT_STEPS: usize = 20; + +/// `cos(m · π g / GRID)` for every grid point `g` and `m` in `0..=MAX_H`, computed with the same +/// expression as [`cos_series`], so the table values are bit-identical to calling `cos` there. +fn grid_cos() -> &'static [[f64; MAX_H + 1]] { + static TABLE: std::sync::OnceLock> = std::sync::OnceLock::new(); + TABLE.get_or_init(|| { + (0..=GRID) + .map(|g| { + let w = std::f64::consts::PI * g as f64 / GRID as f64; + std::array::from_fn(|m| (m as f64 * w).cos()) + }) + .collect() + }) +} + fn roots(p: &[f64], out: &mut Vec) { - const GRID: usize = 1024; + let grid = grid_cos(); + let at_grid = |g: usize| cos_series_with(p, |m| grid[g][m]); let mut w0 = 0.0; - let mut f0 = cos_series(p, w0); + let mut f0 = at_grid(0); for g in 1..=GRID { let w1 = std::f64::consts::PI * g as f64 / GRID as f64; - let f1 = cos_series(p, w1); + let f1 = at_grid(g); if f0 == 0.0 { out.push(w0); } else if f0 * f1 < 0.0 { let (mut lo, mut hi, mut flo) = (w0, w1, f0); - for _ in 0..40 { + for _ in 0..BISECT_STEPS { let mid = 0.5 * (lo + hi); let fm = cos_series(p, mid); if fm * flo <= 0.0 { @@ -111,6 +138,9 @@ fn roots(p: &[f64], out: &mut Vec) { /// when the root search fails (unstable or degenerate filter). pub fn a2nlsf(a: &[f64]) -> Option> { let d = a.len(); + if d > 2 * MAX_H { + return None; + } let mut c = vec![0f64; d + 2]; c[0] = 1.0; for k in 0..d { @@ -199,9 +229,20 @@ pub fn pitch_search(x: &[f32], start: usize, len: usize, fs_khz: usize) -> Pitch let score = full[(lag - min_lag) as usize]; // Contour: per-subframe lag offsets around the chosen lag. let cb: &[[i32; 4]] = if fs_khz == 8 { &CB_NB_20 } else { &CB_WB_20 }; + // The contour search revisits the same (subframe, lag) pairs for neighbouring base lags and + // codebook entries, so each correlation is computed once. + let span = (18 * fs - min_lag + 1) as usize; + let memo = std::cell::RefCell::new(vec![f64::NAN; 4 * span]); let sub_score = |k: usize, l: i32| -> f64 { let l = l.clamp(min_lag, 18 * fs); - ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize) + let slot = k * span + (l - min_lag) as usize; + let cached = memo.borrow()[slot]; + if !cached.is_nan() { + return cached; + } + let v = ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize); + memo.borrow_mut()[slot] = v; + v }; let mut best = (f64::MIN, lag, 0usize); for l0 in (lag - 2).max(min_lag)..=(lag + 2).min(max_lag) { @@ -319,4 +360,59 @@ mod tests { } } } + + /// The root search as it was before the grid table: `cos` called for every evaluation. + fn roots_reference(p: &[f64], out: &mut Vec) { + let mut w0 = 0.0; + let mut f0 = cos_series(p, w0); + for g in 1..=GRID { + let w1 = std::f64::consts::PI * g as f64 / GRID as f64; + let f1 = cos_series(p, w1); + if f0 == 0.0 { + out.push(w0); + } else if f0 * f1 < 0.0 { + let (mut lo, mut hi, mut flo) = (w0, w1, f0); + for _ in 0..BISECT_STEPS { + let mid = 0.5 * (lo + hi); + let fm = cos_series(p, mid); + if fm * flo <= 0.0 { + hi = mid; + } else { + lo = mid; + flo = fm; + } + } + out.push(0.5 * (lo + hi)); + } + w0 = w1; + f0 = f1; + } + } + + #[test] + fn grid_table_roots_are_bit_identical_to_direct_cos() { + let mut seed = 7u64; + let mut rnd = move || { + seed ^= seed << 13; + seed ^= seed >> 7; + seed ^= seed << 17; + (seed >> 11) as f64 / (1u64 << 53) as f64 * 2.0 - 1.0 + }; + let mut found = 0; + for len in [11usize, 17] { + for _ in 0..300 { + let mut p = vec![0f64; len]; + for k in 0..len / 2 + 1 { + p[k] = rnd(); + p[len - 1 - k] = p[k]; + } + let (mut a, mut b) = (Vec::new(), Vec::new()); + roots(&p, &mut a); + roots_reference(&p, &mut b); + assert_eq!(a.iter().map(|v| v.to_bits()).collect::>(), b.iter().map(|v| v.to_bits()).collect::>()); + found += a.len(); + } + } + assert!(found > 1000, "{found}"); + } } diff --git a/crates/audio/src/opus/encoder/silk/mod.rs b/crates/audio/src/opus/encoder/silk/mod.rs index d82e537e0..0fda4f59a 100644 --- a/crates/audio/src/opus/encoder/silk/mod.rs +++ b/crates/audio/src/opus/encoder/silk/mod.rs @@ -129,6 +129,48 @@ struct Coded { pulses: Vec, } +/// Noise-feedback history (decoded − input), most recent first, as a double-length ring: each +/// sample is stored at `pos` and `pos + MAX_LPC_ORDER`, so `buf[pos..pos + MAX_LPC_ORDER]` is +/// always the contiguous window and a push costs two stores instead of a shift. +struct NfRing { + buf: [f64; 2 * MAX_LPC_ORDER], + /// Index of the most recent sample, always below `MAX_LPC_ORDER`. + pos: usize, +} + +impl NfRing { + fn new(hist: &[f64; MAX_LPC_ORDER]) -> Self { + let mut buf = [0.0; 2 * MAX_LPC_ORDER]; + buf[..MAX_LPC_ORDER].copy_from_slice(hist); + buf[MAX_LPC_ORDER..].copy_from_slice(hist); + NfRing { buf, pos: 0 } + } + + /// The history, most recent first. + fn window(&self) -> &[f64] { + self.buf.get(self.pos..self.pos + MAX_LPC_ORDER).unwrap_or(&[]) + } + + /// Makes `v` the most recent sample and drops the oldest. + fn push(&mut self, v: f64) { + self.pos = self.pos.checked_sub(1).unwrap_or(MAX_LPC_ORDER - 1); + for i in [self.pos, self.pos + MAX_LPC_ORDER] { + if let Some(slot) = self.buf.get_mut(i) { + *slot = v; + } + } + } + + /// The history as a plain array, most recent first. + fn to_array(&self) -> [f64; MAX_LPC_ORDER] { + let mut out = [0.0; MAX_LPC_ORDER]; + for (o, v) in out.iter_mut().zip(self.window()) { + *o = *v; + } + out + } +} + #[derive(Clone)] struct Channel { fs_khz: usize, @@ -237,7 +279,7 @@ impl Channel { let sub = self.sub; let order = self.order; let st = &mut self.dec; - let nf = &mut self.nf; + let mut ring = NfRing::new(&self.nf); let off = if p.signal_type == 0 { offset + INACTIVE_OFFSET } else { offset }; let gamma = nf_gamma(off); let mut nf_c = [0f64; MAX_LPC_ORDER]; @@ -355,7 +397,7 @@ impl Channel { } let lpc_q14 = lpc_pred.saturating_mul(16); // Target excitation (Q14) for this sample. - let fb: f64 = (0..order).map(|j| nf_c[j] * nf[j]).sum(); + let fb: f64 = nf_c.iter().zip(ring.window()).take(order).map(|(c, e)| c * e).sum(); let tgt = (x[n] as f64 + fb).clamp(-32768.0, 32767.0) * inv_g - lpc_q14 as f64 - ltp_q14 as f64; let sgn = if seed_v < 0 { -1.0 } else { 1.0 }; let u = sgn * tgt; @@ -394,11 +436,11 @@ impl Channel { let v = res.saturating_add(lpc_q14); s_lpc[MAX_LPC_ORDER + i] = v; xq[n] = sat16(rshift_round(smulww(v, gain_q10), 8)) as i16; - nf.copy_within(0..MAX_LPC_ORDER - 1, 1); - nf[0] = xq[n] as f64 - x[n] as f64; + ring.push(xq[n] as f64 - x[n] as f64); } s_lpc.copy_within(sub..sub + MAX_LPC_ORDER, 0); } + self.nf = ring.to_array(); st.s_lpc_q14.copy_from_slice(&s_lpc[..MAX_LPC_ORDER]); st.out_buf[..l].copy_from_slice(&xq); (Coded { gain_ix, gains_q16, seed, pulses }, xq) @@ -485,6 +527,14 @@ struct Prep { pred_q13: [i32; 2], } +/// One rate-loop trial: the frame coded at gain offset `offset`. +struct Trial { + offset: f64, + bits: i32, + state: SilkEncoder, + coder: RangeEncoder, +} + /// SILK encoder for one mono or stereo (mid/side) stream. #[derive(Clone)] pub struct SilkEncoder { @@ -635,11 +685,20 @@ impl SilkEncoder { pub fn encode(&mut self, input: &[Vec], target_bits: f64, max_bits: i32, enc: &mut RangeEncoder) { let prep = self.prepare(input); let start_bits = enc.tell(); - let trial = |s: &Self, o: f64| -> i32 { - let mut t = s.clone(); - let mut e = enc.clone(); - t.code(&prep, o, &mut e); - e.tell() - start_bits + // Every trial codes the frame into a clone of the encoder and the range coder. The result + // is kept per offset: the hard-limit check below hits the memo for the chosen offset, and + // the final step adopts that trial instead of coding the frame once more. + let mut trials: Vec = Vec::new(); + let mut trial = |s: &Self, o: f64| -> i32 { + if let Some(t) = trials.iter().find(|t| t.offset == o) { + return t.bits; + } + let mut state = s.clone(); + let mut coder = enc.clone(); + state.code(&prep, o, &mut coder); + let bits = coder.tell() - start_bits; + trials.push(Trial { offset: o, bits, state, coder }); + bits }; // Bisection on the gain offset: the smallest offset (finest quantisation) within budget. let target = target_bits.min(max_bits as f64); @@ -701,8 +760,20 @@ impl SilkEncoder { while trial(self, o) > max_bits && o < 12.0 { o += 1.0; } + match trials.iter().position(|t| t.offset == o) { + Some(i) => { + let t = trials.swap_remove(i); + *self = t.state; + *enc = t.coder; + } + None => self.code(&prep, o, enc), + } + self.end_frame(&prep, o); + } + + /// Advances the input history and the frame counter after frame `prep` was coded at `o`. + fn end_frame(&mut self, prep: &Prep, o: f64) { self.last_offset = o; - self.code(&prep, o, enc); for ch in 0..self.channels { self.ch[ch].push_history(&prep.x[ch]); } @@ -712,3 +783,80 @@ impl SilkEncoder { self.frame += 1; } } + +#[cfg(test)] +mod tests { + use super::*; + + /// Deterministic speech-like test input: two harmonics with a moving pitch, a syllable + /// envelope, noise and short silences, at the internal rate and 16-bit scale. + fn signal(len: usize, fs_khz: usize, seed: u32) -> Vec { + let mut s = seed; + let fs = (fs_khz * 1000) as f64; + (0..len) + .map(|i| { + s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + let noise = (s >> 8) as f64 / (1u32 << 24) as f64 - 0.5; + let t = i as f64 / fs; + let f0 = 140.0 + 40.0 * (t * 1.3).sin(); + let env = ((t * 4.0).sin().max(0.0)).powf(0.7); + let voiced = (std::f64::consts::TAU * f0 * t).sin() + 0.5 * (std::f64::consts::TAU * 2.0 * f0 * t).sin(); + (8000.0 * env * voiced + 600.0 * noise) as f32 + }) + .collect() + } + + #[test] + fn nf_ring_matches_a_shifted_history() { + let mut hist = [0f64; MAX_LPC_ORDER]; + for (i, h) in hist.iter_mut().enumerate() { + *h = i as f64 * 0.5 - 3.0; + } + let mut ring = NfRing::new(&hist); + assert_eq!(ring.window(), &hist[..]); + for n in 0..100 { + let v = (n as f64 * 0.37).sin() * 100.0; + hist.copy_within(0..MAX_LPC_ORDER - 1, 1); + hist[0] = v; + ring.push(v); + assert_eq!(ring.window(), &hist[..], "after push {n}"); + } + assert_eq!(ring.to_array(), hist); + } + + /// The rate loop adopts the memoised trial for the chosen offset. A second encoder that codes + /// every frame afresh at that offset (what the loop did before the memo) must produce the + /// same bytes, frame after frame, so the adopted encoder and range-coder states are exact. + #[test] + fn adopting_the_memoised_trial_equals_coding_the_frame_again() { + for (fs_khz, channels, target_bits, max_bits) in + [(8, 1, 200.0, 1000), (12, 1, 320.0, 1000), (16, 1, 480.0, 1000), (16, 2, 640.0, 1000), (16, 1, 900.0, 400), (8, 2, 120.0, 160)] + { + let mut memo = SilkEncoder::new(fs_khz, channels); + let mut fresh = memo.clone(); + let l = memo.frame_len(); + let frames = 40; + let left = signal(l * frames, fs_khz, 7); + let right: Vec = signal(l * frames + 37, fs_khz, 11)[37..].iter().map(|v| v * 0.6).collect(); + for f in 0..frames { + let mut input = vec![left[f * l..(f + 1) * l].to_vec()]; + if channels == 2 { + input.push(right[f * l..(f + 1) * l].to_vec()); + } + let mut enc = RangeEncoder::new(); + memo.encode(&input, target_bits, max_bits, &mut enc); + let o = memo.last_offset; + let prep = fresh.prepare(&input); + let mut enc_fresh = RangeEncoder::new(); + fresh.code(&prep, o, &mut enc_fresh); + fresh.end_frame(&prep, o); + assert_eq!(enc.tell(), enc_fresh.tell(), "{fs_khz} kHz {channels} ch frame {f}"); + assert_eq!(enc.done(1275), enc_fresh.done(1275), "{fs_khz} kHz {channels} ch frame {f}"); + for c in 0..channels { + assert_eq!(memo.ch[c].nf, fresh.ch[c].nf, "noise feedback, channel {c}, frame {f}"); + assert_eq!(memo.ch[c].dec.s_lpc_q14, fresh.ch[c].dec.s_lpc_q14, "LPC state, channel {c}, frame {f}"); + } + } + } + } +} From 1985afe943f2088e56697948638d3286260e6db9 Mon Sep 17 00:00:00 2001 From: nuclearspike Date: Sun, 15 Nov 2026 09:40:41 -0500 Subject: [PATCH 054/349] tga: port metadata payload boundaries and regressions from FilmCraft #1932 Source head e7842f76f887005c460c64a8ab51d59d086e6f27; adapt original decoder guard and synthetic regressions to shared Picture/Error API. --- crates/tga/src/lib.rs | 118 ++++++++- crates/tga/src/metadata_tests.rs | 424 +++++++++++++++++++++++++++++++ 2 files changed, 536 insertions(+), 6 deletions(-) create mode 100644 crates/tga/src/metadata_tests.rs diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index ac9d21497..88f4efe6c 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -18,6 +18,8 @@ //! Input is treated as hostile: the picture size is capped by [`Limits`], and a run-length file //! must be long enough to hold the pixels its header declares before anything is allocated. +#[cfg(test)] +mod metadata_tests; #[cfg(test)] mod tests; @@ -180,6 +182,105 @@ impl Stored { } } +fn metadata_offset(body: &[u8], offset: usize, first_pixel: usize) -> Option { + // Optional metadata cannot replace the header, image ID, or colour map. + (offset >= first_pixel && offset < body.len()).then_some(offset) +} + +/// The start of every developer-directory payload with a nonzero length, from the directory at +/// `directory` in `body` (none when that offset holds no readable directory). +fn developer_payload_starts(body: &[u8], directory: usize) -> Vec { + let Some(count) = + body.get(directory..directory.saturating_add(2)).and_then(|v| v.first_chunk::<2>()).map(|v| usize::from(u16::from_le_bytes(*v))) + else { + return Vec::new(); + }; + let Some(fields) = body.get(directory.saturating_add(2)..) else { return Vec::new() }; + fields + .chunks(10) + .take(count) + .filter_map(|field| { + let start = field.get(2..6).and_then(|v| v.first_chunk::<4>()).map(|v| u32::from_le_bytes(*v) as usize)?; + let length = field.get(6..10).and_then(|v| v.first_chunk::<4>()).map(|v| u32::from_le_bytes(*v))?; + (length != 0).then_some(start) + }) + .collect() +} + +fn image_data_end(bytes: &[u8], first_pixel: usize) -> Result { + if !bytes.ends_with(SIGNATURE) { + return Ok(bytes.len()); + } + // A TGA 2.0 footer cannot begin inside the mandatory header. A legacy image + // may end with the same signature as pixel bytes. + let Some(footer) = bytes.len().checked_sub(SIGNATURE.len() + 8).filter(|&at| at >= HEADER) else { + return Ok(bytes.len()); + }; + let offsets = bytes.get(footer..footer + 8).and_then(|b| b.first_chunk::<8>()).ok_or_else(|| Error::Malformed("truncated footer"))?; + let extension = offsets.first_chunk::<4>().map(|v| u32::from_le_bytes(*v) as usize).ok_or_else(|| Error::Malformed("truncated footer"))?; + let directory = offsets + .get(4..) + .and_then(|v| v.first_chunk::<4>()) + .map(|v| u32::from_le_bytes(*v) as usize) + .ok_or_else(|| Error::Malformed("truncated footer"))?; + let body = bytes.get(..footer).ok_or_else(|| Error::Malformed("truncated footer"))?; + let mut end = footer; + + if let Some(offset) = metadata_offset(body, extension, first_pixel) { + // An in-body reference is a conservative image boundary, even if it overlaps + // required pixels. Those bytes cannot be distinguished from a truncated image + // whose missing pixels are supplied by metadata. + end = end.min(offset); + // TGA 2.0 extension fields at byte offsets 482, 486 and 490 point to the colour + // correction, postage-stamp and scan-line tables. The record's first two bytes give + // its size (495 in TGA 2.0); a shorter record has no such fields, and a record never + // reaches into a developer directory that follows it, so those bytes are not read as + // table offsets. Tables may precede the record. + let declared = + body.get(offset..offset.saturating_add(2)).and_then(|v| v.first_chunk::<2>()).map_or(0, |v| usize::from(u16::from_le_bytes(*v))); + let mut record_end = offset.saturating_add(declared.min(495)); + // The developer directory and its payloads may sit anywhere after the pixels, a payload + // before its directory included; whichever starts first after the extension ends it. + // A directory offset of zero means there is none: the header is not read as one. + let payloads = metadata_offset(body, directory, first_pixel).map(|d| developer_payload_starts(body, d)).unwrap_or_default(); + for next in std::iter::once(directory).chain(payloads) { + if next > offset { + record_end = record_end.min(next); + } + } + if let Some(area) = body.get(offset..record_end.min(body.len())) { + for field in [482, 486, 490] { + if let Some(value) = area.get(field..field + 4).and_then(|v| v.first_chunk::<4>()) + && let Some(table) = metadata_offset(body, u32::from_le_bytes(*value) as usize, first_pixel) + { + end = end.min(table); + } + } + } + } + + if let Some(offset) = metadata_offset(body, directory, first_pixel) { + end = end.min(offset); + if let Some(count) = + body.get(offset..offset.saturating_add(2)).and_then(|v| v.first_chunk::<2>()).map(|v| usize::from(u16::from_le_bytes(*v))) + && let Some(fields) = body.get(offset.saturating_add(2)..) + { + // A corrupt count or final entry does not hide earlier payload offsets. Each + // entry has a 2-byte tag followed by a 4-byte offset and 4-byte length. + for field in fields.chunks(10).take(count) { + if let Some(value) = field.get(2..6).and_then(|v| v.first_chunk::<4>()) + && let Some(length) = field.get(6..10).and_then(|v| v.first_chunk::<4>()) + && u32::from_le_bytes(*length) != 0 + && let Some(payload) = metadata_offset(body, u32::from_le_bytes(*value) as usize, first_pixel) + { + end = end.min(payload); + } + } + } + } + Ok(end) +} + /// Decodes a Targa file to straight-alpha RGBA8, top row first. pub fn decode(bytes: &[u8], limits: &Limits) -> Result { let err = Error::Malformed; @@ -208,13 +309,18 @@ pub fn decode(bytes: &[u8], limits: &Limits) -> Result { } else { None }; - let mut at = HEADER + id_len; - if let Some(l) = map_entry { - let end = at + map_len * l.bytes(); - let map = bytes.get(at..end).ok_or(err("truncated colour map"))?; - palette = map.chunks_exact(l.bytes()).map(|e| l.rgba(e)).collect(); - at = end; + let map_start = HEADER + id_len; + let first_pixel = match map_entry { + Some(layout) => map_start.checked_add(map_len * layout.bytes()).ok_or(err("colour map"))?, + None => map_start, + }; + let end = image_data_end(bytes, first_pixel)?; + let bytes = bytes.get(..end).ok_or(err("truncated image data"))?; + if let Some(layout) = map_entry { + let map = bytes.get(map_start..first_pixel).ok_or(err("truncated colour map"))?; + palette = map.chunks_exact(layout.bytes()).map(|entry| layout.rgba(entry)).collect(); } + let at = first_pixel; let (stored_as, mapped) = match kind & 7 { 1 => { if map_type != 1 || !matches!(depth, 8 | 16) { diff --git a/crates/tga/src/metadata_tests.rs b/crates/tga/src/metadata_tests.rs new file mode 100644 index 000000000..a5c6c0b12 --- /dev/null +++ b/crates/tga/src/metadata_tests.rs @@ -0,0 +1,424 @@ +//! Metadata-boundary regressions ported from FilmCraft #1932 (nuclearspike). +use super::*; +fn header(kind: u8, w: u16, h: u16, depth: u8, descriptor: u8) -> Vec { + let mut b = vec![0, 0, kind, 0, 0, 0, 0, 0, 0, 0, 0, 0]; + b.extend_from_slice(&w.to_le_bytes()); + b.extend_from_slice(&h.to_le_bytes()); + b.extend_from_slice(&[depth, descriptor]); + b +} +fn dec(bytes: &[u8]) -> Result { + decode(bytes, &Limits::default()) +} +#[test] +fn legacy_pixels_that_end_in_signature_are_not_a_footer_before_header() { + for prefix in [0usize, 7] { + let width = (prefix + SIGNATURE.len()) as u16; + let mut file = header(3, width, 1, 8, 0x20); + file.extend(vec![0; prefix]); + file.extend_from_slice(SIGNATURE); + let image = dec(&file).unwrap(); + assert_eq!((image.width, image.height), (u32::from(width), 1)); + let pixels: Vec = std::iter::repeat_n(0, prefix).chain(SIGNATURE.iter().copied()).flat_map(|gray| [gray, gray, gray, 255]).collect(); + assert_eq!(image.rgba, pixels); + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, pixels); + } +} + +#[test] +fn short_extension_followed_by_a_developer_payload_keeps_the_pixels() { + // a 482-byte extension whose size field still says 495, then a developer payload whose + // first bytes land where a full extension keeps its colour-correction offset, then the + // directory that points back at that payload + let mut file = header(2, 1, 1, 24, 0x20); + file.extend_from_slice(&[10, 20, 30]); + let extension = file.len() as u32; + let mut area = vec![0; 482]; + area[..2].copy_from_slice(&495u16.to_le_bytes()); + file.extend_from_slice(&area); + let payload = file.len() as u32; + file.extend_from_slice(&18u32.to_le_bytes()); + file.extend_from_slice(&[0; 14]); + let directory = file.len() as u32; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&0u16.to_le_bytes()); + file.extend_from_slice(&payload.to_le_bytes()); + file.extend_from_slice(&18u32.to_le_bytes()); + file.extend_from_slice(&extension.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + let source = dec(&file).expect("the image decodes"); + assert_eq!((source.width, source.height), (1, 1)); + assert_eq!(source.rgba, vec![30, 20, 10, 255]); +} + +#[test] +fn a_footer_without_a_directory_does_not_read_the_header_as_one() { + // no developer directory (offset 0). Read as one, the header's three-byte image ID + // length is an entry count, and the third "entry" is the first words of a colour + // correction table that sits right after a short pixel area; the extension points at + // that table, so the image is incomplete and must stay so. + let mut file = header(2, 2, 1, 24, 0x20); + file[0] = 3; + file.extend_from_slice(&[7, 8, 9]); + file.extend_from_slice(&[0, 0, 255]); + let table = file.len() as u32; + let mut words = vec![0; 2048]; + words[..4].copy_from_slice(&2074u32.to_le_bytes()); + words[4..8].copy_from_slice(&1u32.to_le_bytes()); + file.extend_from_slice(&words); + let extension = file.len() as u32; + let mut area = vec![0; 495]; + area[..2].copy_from_slice(&495u16.to_le_bytes()); + area[482..486].copy_from_slice(&table.to_le_bytes()); + file.extend_from_slice(&area); + file.extend_from_slice(&extension.to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + let decoded = dec(&file); + assert!(decoded.is_err(), "the second pixel is missing"); +} + +#[test] +fn short_extension_followed_by_a_developer_directory_keeps_the_pixels() { + // a complete 1x1 image, a 482-byte extension (its size says so) and right after it a + // developer directory whose entry's length lands where a full extension keeps its + // scan-line table offset; reading it as one would move the image end into the header + let mut file = header(2, 1, 1, 24, 0x20); + file.extend_from_slice(&[10, 20, 30]); + let extension = file.len() as u32; + let mut area = vec![0; 482]; + area[..2].copy_from_slice(&482u16.to_le_bytes()); + file.extend_from_slice(&area); + let directory = file.len() as u32; + let payload = directory + 2 + 10; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&0u16.to_le_bytes()); + file.extend_from_slice(&payload.to_le_bytes()); + file.extend_from_slice(&18u32.to_le_bytes()); + file.extend_from_slice(&[0; 18]); + file.extend_from_slice(&extension.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + let source = dec(&file).expect("the image decodes"); + assert_eq!((source.width, source.height), (1, 1)); +} + +#[test] +fn importing_truncated_pixels_does_not_consume_tga_footer() { + for (kind, data) in [(2, vec![0, 0, 255]), (10, vec![0x80, 0, 0, 255])] { + for metadata in [None, Some(0usize), Some(1)] { + let mut file = header(kind, 2, 1, 24, 0x20); + file.extend_from_slice(&data); // only the first of two pixels + let mut offsets = [0u8; 8]; + if let Some(field) = metadata { + let offset = file.len() as u32; + offsets[field * 4..field * 4 + 4].copy_from_slice(&offset.to_le_bytes()); + let mut area = vec![0; 495]; + if field == 0 { + area[..2].copy_from_slice(&495u16.to_le_bytes()); + } + file.extend_from_slice(&area); // optional metadata is not pixel data + } + file.extend_from_slice(&offsets); + file.extend_from_slice(SIGNATURE); + let result = dec(&file); + assert!(matches!(result, Err(_)), "kind {kind}, metadata {metadata:?}: metadata is not a second pixel"); + } + } + for kind in [1, 9] { + let mut file = header(kind, 1, 1, 8, 0x20); + file[1] = 1; + file[5] = 1; + file[7] = 24; + file.extend_from_slice(&[0, 0]); // missing third palette byte and the index + file.extend_from_slice(&[0; 8]); + file.extend_from_slice(SIGNATURE); + let result = dec(&file); + assert!(matches!(result, Err(_)), "kind {kind}: the footer is not colour-map data"); + } +} + +#[test] +fn complete_tga_footer_and_metadata_do_not_change_pixels() { + for metadata in [None, Some(0usize), Some(1)] { + let mut file = header(2, 1, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255]); + let mut offsets = [0u8; 8]; + if let Some(field) = metadata { + let offset = file.len() as u32; + offsets[field * 4..field * 4 + 4].copy_from_slice(&offset.to_le_bytes()); + let mut area = vec![0; 495]; + if field == 0 { + area[..2].copy_from_slice(&495u16.to_le_bytes()); + } + file.extend_from_slice(&area); + } + file.extend_from_slice(&offsets); + file.extend_from_slice(SIGNATURE); + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255]); + } +} + +fn preceding_metadata(complete: bool, metadata: usize) -> Vec { + let mut file = header(2, if complete { 1 } else { 2 }, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255]); + let payload_offset = file.len() as u32; + let mut offsets = [0u8; 8]; + if metadata == 0 { + file.extend_from_slice(&[0, 255, 0]); + let directory_offset = file.len() as u32; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&payload_offset.to_le_bytes()); + file.extend_from_slice(&3u32.to_le_bytes()); + offsets[4..].copy_from_slice(&directory_offset.to_le_bytes()); + } else { + match metadata { + 1 => file.extend_from_slice(&[0; 2048]), + 2 => file.extend_from_slice(&[1, 1, 0, 255, 0]), + 3 => file.extend_from_slice(&18u32.to_le_bytes()), + _ => unreachable!(), + } + let extension_offset = file.len() as u32; + let mut extension = [0; 495]; + extension[..2].copy_from_slice(&495u16.to_le_bytes()); + let field = [0, 482, 486, 490][metadata]; + extension[field..field + 4].copy_from_slice(&payload_offset.to_le_bytes()); + file.extend_from_slice(&extension); + offsets[..4].copy_from_slice(&extension_offset.to_le_bytes()); + } + file.extend_from_slice(&offsets); + file.extend_from_slice(SIGNATURE); + file +} + +#[test] +fn preceding_metadata_cannot_supply_missing_pixels() { + let mut accepted = Vec::new(); + for metadata in 0..4 { + let result = dec(&preceding_metadata(false, metadata)); + if !matches!(result, Err(_)) { + accepted.push(metadata); + } + } + assert!(accepted.is_empty(), "metadata payloads supplied missing pixels: {accepted:?}"); +} + +#[test] +fn complete_pixels_before_metadata_keep_their_colour() { + for metadata in 0..4 { + let source = dec(&preceding_metadata(true, metadata)).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255], "metadata {metadata}"); + } + let mut file = preceding_metadata(true, 1); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + file[extension..extension + 2].copy_from_slice(&496u16.to_le_bytes()); + file.insert(footer, 0); + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255], "larger complete extensions preserve pixels"); +} + +#[test] +fn malformed_optional_metadata_keeps_complete_pixels_readable() { + let accept = |file: Vec| { + let source = dec(&file).unwrap(); + assert_eq!(source.rgba, [255, 0, 0, 255]); + }; + for field in [0, 4] { + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + file[footer + field..footer + field + 4].copy_from_slice(&u32::MAX.to_le_bytes()); + accept(file); + } + for metadata in 1..4 { + let mut file = preceding_metadata(true, metadata); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + let field = [0, 482, 486, 490][metadata]; + file[extension + field..extension + field + 4].copy_from_slice(&u32::MAX.to_le_bytes()); + accept(file); + } + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file.drain(directory + 2..footer); + accept(file); + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory + 8..directory + 12].copy_from_slice(&u32::MAX.to_le_bytes()); + accept(file); + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); + accept(file); + // A zero-length entry cannot mark a payload boundary, even if its offset overlaps pixels. + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory + 4..directory + 8].copy_from_slice(&19u32.to_le_bytes()); + file[directory + 8..directory + 12].copy_from_slice(&0u32.to_le_bytes()); + accept(file); + let mut file = preceding_metadata(true, 2); + file[21..23].copy_from_slice(&[255, 255]); + accept(file); + let mut file = preceding_metadata(true, 2); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + file[extension..extension + 2].copy_from_slice(&494u16.to_le_bytes()); + accept(file); + let mut file = preceding_metadata(true, 2); + let footer = file.len() - SIGNATURE.len() - 8; + file.remove(footer - 1); // extension is physically short, but its postage offset remains + accept(file); +} + +#[test] +fn malformed_metadata_offsets_inside_id_or_palette_keep_complete_pixels() { + let mut file = header(1, 1, 1, 8, 0x20); + file[0] = 4; // image ID length + file[1] = 1; // colour map present + file[5..7].copy_from_slice(&1u16.to_le_bytes()); + file[7] = 24; // one BGR palette entry + file.extend_from_slice(&[7, 8, 9, 10]); // image ID + file.extend_from_slice(&[0, 0, 255]); // red palette entry + file.push(0); // palette index + for (field, offset) in [(0, HEADER + 1), (4, HEADER + 4 + 1)] { + let mut candidate = file.clone(); + let mut footer_offsets = [0u8; 8]; + footer_offsets[field..field + 4].copy_from_slice(&(offset as u32).to_le_bytes()); + candidate.extend_from_slice(&footer_offsets); + candidate.extend_from_slice(SIGNATURE); + let image = dec(&candidate).unwrap(); + assert_eq!(image.rgba, [255, 0, 0, 255], "footer field {field}"); + } +} + +#[test] +fn malformed_optional_metadata_cannot_supply_missing_pixels() { + let mut file = preceding_metadata(false, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory + 8..directory + 12].copy_from_slice(&u32::MAX.to_le_bytes()); + assert!(matches!(dec(&file), Err(_))); + + // The declared entry count exceeds the bytes before the footer, but the first entry's + // payload still precedes the directory and cannot be used as a second pixel. + let mut file = preceding_metadata(false, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); + assert!(matches!(dec(&file), Err(_))); + + let mut file = preceding_metadata(false, 2); + let footer = file.len() - SIGNATURE.len() - 8; + let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; + file[extension..extension + 2].copy_from_slice(&494u16.to_le_bytes()); + assert!(matches!(dec(&file), Err(_))); + let mut file = preceding_metadata(false, 2); + let footer = file.len() - SIGNATURE.len() - 8; + file.remove(footer - 1); + assert!(matches!(dec(&file), Err(_))); +} + +#[test] +fn valid_developer_directory_with_overlapping_payload_rejects_pixels() { + let mut file = preceding_metadata(true, 0); + let footer = file.len() - SIGNATURE.len() - 8; + let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; + file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); + let mut extra = [0u8; 10]; + extra[..2].copy_from_slice(&2u16.to_le_bytes()); + extra[2..6].copy_from_slice(&(HEADER as u32).to_le_bytes()); + extra[6..10].copy_from_slice(&1u32.to_le_bytes()); + file.splice(footer..footer, extra); + let moved_footer = file.len() - SIGNATURE.len() - 8; + assert_eq!(u32::from_le_bytes(file[moved_footer + 4..moved_footer + 8].try_into().unwrap()), directory as u32); + assert_eq!(u16::from_le_bytes(file[directory..directory + 2].try_into().unwrap()), 2); + assert_eq!(&file[directory + 12..directory + 22], &extra); + assert!(matches!(dec(&file), Err(_))); +} + +#[test] +fn nonempty_developer_reference_inside_pixels_rejects_the_whole_image() { + let mut file = header(2, 2, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255, 0, 255, 0]); + let directory = file.len() as u32; + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&(HEADER as u32 + 3).to_le_bytes()); + file.extend_from_slice(&1u32.to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + assert!(matches!(dec(&file), Err(_)), "an overlapping reference must not return a partial image"); +} + +#[test] +fn inflated_developer_count_scans_the_next_chunk_as_an_entry_and_rejects_its_pixel_payload() { + // a directory claiming two entries over one real entry: the ten bytes after it, scanned as + // the second entry, name a payload inside the pixels, which is refused like any other + let mut file = header(2, 2, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255, 0, 255, 0]); + let directory = file.len() as u32; + file.extend_from_slice(&2u16.to_le_bytes()); + file.extend_from_slice(&1u16.to_le_bytes()); + file.extend_from_slice(&(directory + 22).to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(&2u16.to_le_bytes()); + file.extend_from_slice(&(HEADER as u32 + 3).to_le_bytes()); + file.extend_from_slice(&1u32.to_le_bytes()); + file.extend_from_slice(&0u32.to_le_bytes()); + file.extend_from_slice(&directory.to_le_bytes()); + file.extend_from_slice(SIGNATURE); + assert!(matches!(dec(&file), Err(_)), "a scanned entry's payload inside the pixels is refused"); +} + +#[test] +fn legacy_pixels_that_end_in_signature_at_or_after_the_header_are_read_as_a_footer() { + // a footerless 36×1 grayscale image whose last 26 bytes happen to be eight zeros and the + // signature: the putative trailer begins at byte 28, so it is taken for a footer and the + // image, left with 10 pixel bytes, is rejected as truncated (the ambiguity the body states) + let prefix = 18usize; + let width = (prefix + SIGNATURE.len()) as u16; + let mut file = header(3, width, 1, 8, 0x20); + file.extend(vec![0; prefix]); + file.extend_from_slice(SIGNATURE); + assert!(matches!(dec(&file), Err(_))); +} + +#[test] +fn mutated_tga_footer_files_never_panic() { + let mut file = header(2, 2, 1, 24, 0x20); + file.extend_from_slice(&[0, 0, 255, 0, 255, 0]); + file.extend_from_slice(&[0; 8]); + file.extend_from_slice(SIGNATURE); + for end in 0..file.len() { + assert!(std::panic::catch_unwind(|| dec(&file[..end])).is_ok(), "truncation at {end}"); + } + for at in 0..file.len() { + let mut mutated = file.clone(); + mutated[at] ^= 0xFF; + assert!(std::panic::catch_unwind(|| dec(&mutated)).is_ok(), "mutation at {at}"); + } + for metadata in 0..4 { + let file = preceding_metadata(true, metadata); + assert!(dec(&file).is_ok()); + let footer = file.len() - SIGNATURE.len() - 8; + for end in 0..footer { + let mut truncated = file[..end].to_vec(); + truncated.extend_from_slice(&file[footer..]); + assert!(std::panic::catch_unwind(|| dec(&truncated)).is_ok(), "metadata {metadata}, footer-preserving truncation at {end}"); + } + for at in 0..file.len() { + let mut mutated = file.clone(); + mutated[at] ^= 0xFF; + assert!(std::panic::catch_unwind(|| dec(&mutated)).is_ok(), "metadata {metadata}, mutation at {at}"); + } + } +} From b6b33b6096a247514f5cbd1741633913e7261e91 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:40:41 -0500 Subject: [PATCH 055/349] tga: record original metadata-boundary source attribution --- ATTRIBUTION.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index c087ecda1..e6f928645 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -99,3 +99,5 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso ## Binary Apple property lists `crates/plist` is extracted from `storytold/craft-anything` (`crates/formats/src/plist.rs` and checked byte reads), at source main `88d1d9cac852aec1c7fd97886db451e005e49d2a`. MIT OR Apache-2.0; source license texts are retained in the crate. Primary import Git authors preserve Brandon Thomas, BFlat, RRFZ and Afloat. Regression imports preserve BFlat. XML, JSON projection, calendar formatting and app policy were not imported into the public API. + +`crates/tga/src/metadata_tests.rs` and metadata-boundary helpers in `crates/tga/src/lib.rs` are adapted from nuclearspike's FilmCraft #1932 at `e7842f76f887005c460c64a8ab51d59d086e6f27` (MIT OR Apache-2.0). Synthetic fixtures are original contributor test data; primary Git author retained. From e555cc0afe12d14a3fed4e369e78d45cf084109a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 09:48:49 -0500 Subject: [PATCH 056/349] fix(tga): use eager static footer errors --- crates/tga/src/lib.rs | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index 88f4efe6c..06a9941a0 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -216,14 +216,11 @@ fn image_data_end(bytes: &[u8], first_pixel: usize) -> Result { let Some(footer) = bytes.len().checked_sub(SIGNATURE.len() + 8).filter(|&at| at >= HEADER) else { return Ok(bytes.len()); }; - let offsets = bytes.get(footer..footer + 8).and_then(|b| b.first_chunk::<8>()).ok_or_else(|| Error::Malformed("truncated footer"))?; - let extension = offsets.first_chunk::<4>().map(|v| u32::from_le_bytes(*v) as usize).ok_or_else(|| Error::Malformed("truncated footer"))?; - let directory = offsets - .get(4..) - .and_then(|v| v.first_chunk::<4>()) - .map(|v| u32::from_le_bytes(*v) as usize) - .ok_or_else(|| Error::Malformed("truncated footer"))?; - let body = bytes.get(..footer).ok_or_else(|| Error::Malformed("truncated footer"))?; + let offsets = bytes.get(footer..footer + 8).and_then(|b| b.first_chunk::<8>()).ok_or(Error::Malformed("truncated footer"))?; + let extension = offsets.first_chunk::<4>().map(|v| u32::from_le_bytes(*v) as usize).ok_or(Error::Malformed("truncated footer"))?; + let directory = + offsets.get(4..).and_then(|v| v.first_chunk::<4>()).map(|v| u32::from_le_bytes(*v) as usize).ok_or(Error::Malformed("truncated footer"))?; + let body = bytes.get(..footer).ok_or(Error::Malformed("truncated footer"))?; let mut end = footer; if let Some(offset) = metadata_offset(body, extension, first_pixel) { From 9399c25341289c1d523e64c92a1b95735c81933f Mon Sep 17 00:00:00 2001 From: FredApps <153173854+FredApps@users.noreply.github.com> Date: Sun, 15 Nov 2026 16:10:22 +0100 Subject: [PATCH 057/349] image-codecs: decode AVIF pixels with craft-video's pure-Rust AV1 decoder New optional `avif-decode` feature (native targets) reads still AVIF files: the HEIF/ISOBMFF item graph, grids, clap/irot/imir, alpha auxiliary images (including premultiplied), 8/10/12-bit 4:0:0, 4:2:0, 4:2:2 and 4:4:4, nclx/ICC colour, Exif and XMP, and PQ/HLG to linear F32 through cicp::linearize as the HEIF path does. The container walk follows LightCraft #3017 by @emmertex. Every size is checked against the caller's Limits before the AV1 decoder runs, the decoder's memory budget is capped by max_alloc, and the decode is wrapped in catch_unwind so a decoder panic becomes an error. Fixtures are tiny ffmpeg/libaom files; the 4:2:0 planes match libdav1d bit for bit. Adds a decode_avif fuzz target. Part of storytold/craft-libs#778. --- crates/image-codecs/Cargo.toml | 4 + crates/image-codecs/README.md | 27 +- crates/image-codecs/fuzz/Cargo.toml | 9 +- .../fuzz/fuzz_targets/decode_avif.rs | 14 + crates/image-codecs/src/cicp.rs | 2 +- crates/image-codecs/src/codecs.rs | 2 + crates/image-codecs/src/codecs/avif_decode.rs | 1239 +++++++++++++++++ crates/image-codecs/src/format.rs | 13 +- crates/image-codecs/src/lib.rs | 24 +- .../tests/fixtures/avif/README.md | 12 + .../tests/fixtures/avif/quad-420-bt709.avif | Bin 0 -> 369 bytes .../fixtures/avif/quad-420-bt709.dav1d.yuv | 1 + .../fixtures/avif/quad-444-gbr-lossless.avif | Bin 0 -> 345 bytes .../tests/fixtures/avif/quad-source.rgb | 1 + crates/image-codecs/tests/it/detect_caps.rs | 11 +- 15 files changed, 1335 insertions(+), 24 deletions(-) create mode 100644 crates/image-codecs/fuzz/fuzz_targets/decode_avif.rs create mode 100644 crates/image-codecs/src/codecs/avif_decode.rs create mode 100644 crates/image-codecs/tests/fixtures/avif/README.md create mode 100644 crates/image-codecs/tests/fixtures/avif/quad-420-bt709.avif create mode 100644 crates/image-codecs/tests/fixtures/avif/quad-420-bt709.dav1d.yuv create mode 100644 crates/image-codecs/tests/fixtures/avif/quad-444-gbr-lossless.avif create mode 100644 crates/image-codecs/tests/fixtures/avif/quad-source.rgb diff --git a/crates/image-codecs/Cargo.toml b/crates/image-codecs/Cargo.toml index df71d9860..1b422f912 100644 --- a/crates/image-codecs/Cargo.toml +++ b/crates/image-codecs/Cargo.toml @@ -15,6 +15,9 @@ corpus = [] default = [] avif = ["image/avif", "dep:ravif", "dep:rav1e", "dep:avif-serialize"] heif = ["dep:craft-heif"] +# AVIF decode: craft-video's clean-room pure-Rust AV1 decoder. Native targets only (on wasm32 a +# decoder panic aborts instead of becoming an error), so wasm32 builds leave AVIF unreadable. +avif-decode = ["dep:craft-video", "craft-video/av1-decode"] [dependencies] crc32fast = "1.5" @@ -41,6 +44,7 @@ hayro-jpeg2000 = { version = "=0.3.5", default-features = false, features = ["st [target.'cfg(not(target_arch = "wasm32"))'.dependencies] rayon = { workspace = true } +craft-video = { workspace = true, optional = true } exr = { version = "1.73", default-features = false, features = ["rayon"] } [dev-dependencies] diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index 6e9e11617..1728d8308 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -1,9 +1,10 @@ # craft-image-codecs Codecs for flat raster image formats, written in pure Rust. This crate defines its own `Image` -type and shares its baseline and extended JPEG decoders through `craft-jpeg`, and its optional -HEIF decoder through `craft-heif`. It builds for `wasm32-unknown-unknown` and does no filesystem -I/O: decoders take `&[u8]` and encoders return `Vec`. +type and shares its baseline and extended JPEG decoders through `craft-jpeg`, its optional HEIF +decoder through `craft-heif`, and its optional AVIF decoder through `craft-video`'s AV1 decoder. +It builds for `wasm32-unknown-unknown` and does no filesystem I/O: decoders take `&[u8]` and +encoders return `Vec`. It follows the "Avoiding GIMP's hole" rules in `docs/architecture.md` §1.1: @@ -56,7 +57,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 | -| AVIF | **no** | only with feature `avif` | U8 | RGB, RGBA | yes | no | no | no | no | no | yes | `image` + `ravif` | +| AVIF | with feature `avif-decode` (native only) | only with feature `avif` | U8, U16 (10/12-bit decodes to U16; PQ/HLG to linear F32) | RGB, RGBA | yes (auxiliary alpha) | read (`colr` prof/rICC) | read | read | no | no | yes | `craft-video` AV1 decoder; `image` + `ravif` to write | | 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` | "Native" means the data is stored and read back without conversion. Anything else is converted by @@ -177,10 +178,20 @@ embedded table (and a PNG's transparent entry) so `photocraft-io` can open them decodes to RGB. Image sequences, overlays and identity derivations, multilayer HEVC and some 4:2:2/4:4:4 streams return `CodecError::Unsupported` or `Malformed`, never wrong pixels. Writing needs an HEVC encoder and every mature one is C, so HEIF is listed in `ASYMMETRIC_EXCEPTIONS`. -* **AVIF.** Encoding uses `ravif`, which is pure Rust. Decoding - needs `dav1d`, which is C. AVIF is therefore read-unsupported, and write support is gated - behind the non-default `avif` feature. In a default build it is neither readable nor writable, - so the symmetric guarantee holds. It is listed in `ASYMMETRIC_EXCEPTIONS`. +* **AVIF.** Encoding uses `ravif`, which is pure Rust, behind the non-default `avif` feature. + Decoding (`codecs::avif_decode`, behind the non-default `avif-decode` feature) reads the HEIF + boxes itself and decodes the AV1 pictures with `craft-video`'s clean-room pure-Rust AV1 decoder: + one `av01` image or a `grid`, 8/10/12-bit, 4:2:0/4:2:2/4:4:4/monochrome, the `nclx` colour (or + the sequence header's) and an ICC profile, an `auxl` alpha plane (`prem` too), the Exif and XMP + items, and `clap`/`irot`/`imir`, which are applied unless `keep_orientation` is set, as for HEIF. + PQ and HLG open as linear light in F32, as HEIF does. Image sequences (animated AVIF), depth and + gain-map auxiliary images and layered progressive images aren't read. It is bounded like the + other decoders: the `Limits` are checked against the declared size before any picture decodes, + against every picture and every output buffer, `max_alloc` caps the AV1 decoder's picture store, + box, item and extent counts are capped, item data can't exceed the file, and a decoder panic is + `CodecError::Malformed`. wasm32 builds leave AVIF unreadable, since a panic there aborts. In a + default build AVIF is neither readable nor writable, so the symmetric guarantee holds; a build + with only one of the two features is listed in `ASYMMETRIC_EXCEPTIONS`. * **Lossy WebP.** Lossless (VP8L, via `image-webp`) is the default. `webp_lossless: false` writes a lossy file with our own clean-room VP8 key-frame encoder (`codecs::vp8`, from RFC 6386; `webp_quality` 0–100 on libwebp's scale sets the quantizer). Alpha travels losslessly diff --git a/crates/image-codecs/fuzz/Cargo.toml b/crates/image-codecs/fuzz/Cargo.toml index 3257a3953..30226c76e 100644 --- a/crates/image-codecs/fuzz/Cargo.toml +++ b/crates/image-codecs/fuzz/Cargo.toml @@ -14,7 +14,7 @@ cargo-fuzz = true [dependencies] libfuzzer-sys = "0.4" -craft-image-codecs = { path = "..", features = ["heif"] } +craft-image-codecs = { path = "..", features = ["heif", "avif-decode"] } # Called directly too: the codec turns its panics into errors (see decode_heif.rs). heic-rs = "=0.1.4" @@ -76,3 +76,10 @@ path = "fuzz_targets/decode_webp.rs" test = false doc = false bench = false + +[[bin]] +name = "decode_avif" +path = "fuzz_targets/decode_avif.rs" +test = false +doc = false +bench = false diff --git a/crates/image-codecs/fuzz/fuzz_targets/decode_avif.rs b/crates/image-codecs/fuzz/fuzz_targets/decode_avif.rs new file mode 100644 index 000000000..9a4b8978d --- /dev/null +++ b/crates/image-codecs/fuzz/fuzz_targets/decode_avif.rs @@ -0,0 +1,14 @@ +#![no_main] + +use libfuzzer_sys::fuzz_target; +use craft_image_codecs::{decode_as_with, probe_size, DecodeOptions, Format, Limits}; + +// The AVIF box reader and craft-video's AV1 decoder parse untrusted files: run with `-timeout=10` +// so a hang is reported, not just a panic. The codec turns an AV1 decoder panic into an error, so +// only the box reader's own panics would reach the fuzzer. Both orientation paths are covered. +fuzz_target!(|data: &[u8]| { + let keep_orientation = data.first().is_some_and(|b| b & 1 == 1); + let limits = Limits { max_width: 4096, max_height: 4096, max_pixels: 1 << 22, max_alloc: 256 << 20 }; + let _ = probe_size(data); + let _ = decode_as_with(Format::Avif, data, &DecodeOptions { limits, keep_orientation }); +}); diff --git a/crates/image-codecs/src/cicp.rs b/crates/image-codecs/src/cicp.rs index 290c82bc3..e6911d1b0 100644 --- a/crates/image-codecs/src/cicp.rs +++ b/crates/image-codecs/src/cicp.rs @@ -99,7 +99,7 @@ pub fn linear_to_pq(linear: f32) -> f32 { /// Relative luminance weights of the RGB primaries `code` (BT.2020's for anything else, the /// space BT.2100 defines HLG in). -fn luma_weights(code: u16) -> [f32; 3] { +pub(crate) fn luma_weights(code: u16) -> [f32; 3] { match code { 1 => [0.2126, 0.7152, 0.0722], 12 => [0.2290, 0.6917, 0.0793], diff --git a/crates/image-codecs/src/codecs.rs b/crates/image-codecs/src/codecs.rs index 0288ae22b..71db85f18 100644 --- a/crates/image-codecs/src/codecs.rs +++ b/crates/image-codecs/src/codecs.rs @@ -1,4 +1,6 @@ pub(crate) mod avif; +#[cfg(all(feature = "avif-decode", not(target_arch = "wasm32")))] +pub(crate) mod avif_decode; pub(crate) mod dds; pub(crate) mod dds_bc; pub(crate) mod deep_exr; diff --git a/crates/image-codecs/src/codecs/avif_decode.rs b/crates/image-codecs/src/codecs/avif_decode.rs new file mode 100644 index 000000000..302433661 --- /dev/null +++ b/crates/image-codecs/src/codecs/avif_decode.rs @@ -0,0 +1,1239 @@ +//! AVIF (AV1 Image File Format) decoding, behind the non-default `avif-decode` feature, native +//! targets only. +//! +//! The container is HEIF (ISO/IEC 23008-12) over ISO-BMFF. This module reads the boxes itself +//! (`meta`, `pitm`, `iloc`, `iinf`, `iref`, `iprp`/`ipco`/`ipma`, `idat`), and `craft-video`'s +//! clean-room AV1 decoder (`av1-decode`, pure Rust, no `unsafe`) decodes the AV1 still pictures. +//! The container reader, colour conversion and transforms are adapted from @emmertex's LightCraft +//! AVIF importer (storytold/lightcraft#3017). +//! +//! Supported: the primary item as one `av01` image or a `grid` of them; 8-, 10- and 12-bit; +//! 4:2:0, 4:2:2, 4:4:4 and monochrome; full or limited range; the `nclx` colour description (or the +//! AV1 sequence header's) and an ICC profile (`prof` / `rICC`); an alpha auxiliary image (`auxl`, +//! premultiplied with `prem` too); the primary item's Exif and XMP items. `clap`, `irot` and `imir` +//! are applied unless the caller keeps the stored orientation, as for HEIF. PQ and HLG files +//! open as linear light in 32-bit float, as HEIF does. Not read: image sequences (animated AVIF), +//! depth and gain-map auxiliary images, layered (`lsel`/`a1lx`) progressive images. +//! +//! Bounded for hostile input: box nesting, item, property and extent counts are capped; item data +//! can't add up to more than the file; the [`Limits`] are checked against the declared size +//! before any picture is decoded, against every decoded picture and against each output buffer; +//! the AV1 decoder's picture store is capped by `max_alloc` too; and a panic in the decoder is +//! a malformed-file error. wasm32 builds leave AVIF unreadable: a panic there aborts instead of +//! unwinding. +//! +//! Sources: ISO/IEC 23008-12 (HEIF) and the AV1 Image File Format specification v1.1.0 (box +//! layouts), ITU-T H.273 (colour code points). + +use std::panic::{AssertUnwindSafe, catch_unwind}; + +use craft_video::av1::decode as av1; + +use crate::Format; +use crate::cicp::Cicp; +use crate::error::CodecError; +use crate::image::{ChannelLayout, Image, Metadata, SampleType}; +use crate::options::Limits; + +const F: Format = Format::Avif; +/// Deepest box nesting followed (meta → iprp → ipco → property is 4). +const MAX_DEPTH: u32 = 8; +/// Most boxes, items, properties, associations or extents accepted: far above real files. +const MAX_ITEMS: usize = 1 << 16; +/// The AV1 decoder's own picture-store cap (`craft-video`'s default on 64-bit targets). +const AV1_MEMORY_BUDGET: u64 = 4 << 30; +/// The `auxC` types of an alpha plane (AVIF and the older HEVC-in-HEIF spelling). +const ALPHA_URNS: [&[u8]; 2] = [b"urn:mpeg:mpegB:cicp:systems:auxiliary:alpha", b"urn:mpeg:hevc:2015:auxid:1"]; + +type Result = std::result::Result; + +fn bad(m: impl std::fmt::Display) -> CodecError { + CodecError::malformed(F, m) +} + +/// A big-endian reader over a byte slice that never panics. +struct Rd<'a> { + b: &'a [u8], + p: usize, +} + +impl<'a> Rd<'a> { + fn new(b: &'a [u8]) -> Self { + Rd { b, p: 0 } + } + fn take(&mut self, n: usize) -> Result<&'a [u8]> { + let end = self.p.checked_add(n).ok_or_else(|| bad("box overflows"))?; + let s = self.b.get(self.p..end).ok_or_else(|| bad("box truncated"))?; + self.p = end; + Ok(s) + } + fn u8(&mut self) -> Result { + Ok(self.take(1)?.first().copied().unwrap_or(0)) + } + fn u16(&mut self) -> Result { + Ok(self.uint(2)? as u16) + } + fn u32(&mut self) -> Result { + Ok(self.uint(4)? as u32) + } + /// An unsigned big-endian number of `n` (0 to 8) bytes. + fn uint(&mut self, n: usize) -> Result { + if n > 8 { + return Err(bad("field too wide")); + } + Ok(self.take(n)?.iter().fold(0u64, |a, &x| (a << 8) | u64::from(x))) + } + /// A full box's version, its flags skipped. + fn version(&mut self) -> Result { + let v = self.u8()?; + self.take(3)?; + Ok(v) + } + /// An item ID: 16 bits in version 0 boxes, 32 bits otherwise. + fn id(&mut self, wide: bool) -> Result { + if wide { self.u32() } else { self.u16().map(u32::from) } + } + fn cstr(&mut self) -> Result<&'a [u8]> { + let rest = self.rest(); + let n = rest.iter().position(|&c| c == 0).unwrap_or(rest.len()); + let s = self.take(n)?; + if self.p < self.b.len() { + self.p += 1; + } + Ok(s) + } + fn rest(&self) -> &'a [u8] { + self.b.get(self.p..).unwrap_or(&[]) + } +} + +/// The child boxes of `b`: (type, payload). +fn boxes(b: &[u8]) -> Result> { + let mut out = Vec::new(); + let mut p = 0usize; + while p < b.len() { + let mut r = Rd::new(b.get(p..).unwrap_or(&[])); + if r.b.len() < 8 { + break; // trailing padding + } + let size32 = r.u32()?; + let t = r.take(4)?; + let ty = [t[0], t[1], t[2], t[3]]; + let (hdr, size) = match size32 { + 0 => (8usize, r.b.len() as u64), + 1 => (16, r.uint(8)?), + s => (8, u64::from(s)), + }; + let size = usize::try_from(size).map_err(|_| bad("box too large"))?; + if size < hdr || size > r.b.len() { + return Err(bad(format!("box {} has a bad size", String::from_utf8_lossy(&ty)))); + } + out.push((ty, r.b.get(hdr..size).unwrap_or(&[]))); + if out.len() > MAX_ITEMS { + return Err(bad("too many boxes")); + } + p = p.checked_add(size).ok_or_else(|| bad("box overflows"))?; + } + Ok(out) +} + +#[derive(Clone, Debug, Default)] +struct Extent { + offset: u64, + length: u64, +} + +#[derive(Clone, Debug, Default)] +struct Loc { + method: u8, + base: u64, + extents: Vec, +} + +#[derive(Clone, Copy, Debug)] +enum Transform { + /// Clean aperture: width, height, horizontal and vertical offset of the centre. + Clap { w: f64, h: f64, dx: f64, dy: f64 }, + /// Anticlockwise rotation by `n` × 90°. + Rot(u8), + /// Mirror, as HEIF amendment 2, libheif and libavif read it: 0 = top and bottom exchanged, + /// 1 = left and right exchanged. + Mir(u8), +} + +#[derive(Clone, Debug)] +enum Prop { + Av1c(Vec), + Nclx(Cicp), + Icc(Vec), + Ispe(u32, u32), + AuxC(Vec), + T(Transform), + Other, +} + +struct Item { + id: u32, + kind: [u8; 4], + /// `mime` items: the content type. + content_type: Option>, +} + +#[derive(Default)] +struct Container<'a> { + file: &'a [u8], + primary: u32, + items: Vec, + locs: Vec<(u32, Loc)>, + idat: &'a [u8], + props: Vec, + /// item → 1-based property indices, in order. + assoc: Vec<(u32, Vec)>, + /// (type, from, to…) + refs: Vec<([u8; 4], u32, Vec)>, + /// `iloc` extents read so far, across all items (capped at [`MAX_ITEMS`]). + extents: usize, +} + +fn parse(file: &[u8]) -> Result> { + let top = boxes(file)?; + let meta = top.iter().find(|(t, _)| t == b"meta").map(|(_, b)| *b).ok_or_else(|| { + if top.iter().any(|(t, _)| t == b"moov") { + CodecError::unsupported(F, "AVIF image sequences (animated AVIF) aren't read") + } else { + bad("no meta box") + } + })?; + let mut c = Container { file, ..Default::default() }; + let meta = meta.get(4..).ok_or_else(|| bad("meta box truncated"))?; + for (t, b) in boxes(meta)? { + let mut r = Rd::new(b); + match &t { + b"pitm" => { + let v = r.version()?; + c.primary = r.id(v != 0)?; + } + b"iloc" => parse_iloc(&mut r, &mut c)?, + b"iinf" => parse_iinf(&mut r, &mut c)?, + b"iref" => parse_iref(&mut r, &mut c)?, + b"idat" => c.idat = b, + b"iprp" => parse_iprp(b, &mut c, 0)?, + _ => {} + } + } + if c.primary == 0 { + return Err(bad("no primary item")); + } + Ok(c) +} + +fn parse_iinf(r: &mut Rd, c: &mut Container) -> Result<()> { + let v = r.version()?; + let _count = r.id(v != 0)?; + for (t, b) in boxes(r.rest())? { + if &t != b"infe" { + continue; + } + let mut r = Rd::new(b); + let v = r.version()?; + if v < 2 { + continue; + } + let id = r.id(v != 2)?; + r.u16()?; // protection index + let kind = r.take(4)?; + let kind = [kind[0], kind[1], kind[2], kind[3]]; + let _name = r.cstr()?; + let content_type = (&kind == b"mime").then(|| r.cstr().ok().map(<[u8]>::to_vec)).flatten(); + c.items.push(Item { id, kind, content_type }); + if c.items.len() > MAX_ITEMS { + return Err(bad("too many items")); + } + } + Ok(()) +} + +fn parse_iref(r: &mut Rd, c: &mut Container) -> Result<()> { + let v = r.version()?; + for (t, b) in boxes(r.rest())? { + let mut r = Rd::new(b); + let from = r.id(v != 0)?; + let n = r.u16()?; + let mut to = Vec::with_capacity(usize::from(n).min(r.rest().len() / 2 + 1)); + for _ in 0..n { + to.push(r.id(v != 0)?); + } + c.refs.push((t, from, to)); + if c.refs.len() > MAX_ITEMS { + return Err(bad("too many item references")); + } + } + Ok(()) +} + +fn parse_iloc(r: &mut Rd, c: &mut Container) -> Result<()> { + let v = r.version()?; + if v > 2 { + return Err(CodecError::unsupported(F, "iloc version")); + } + let a = r.u8()?; + let b = r.u8()?; + let (off_size, len_size, base_size) = (usize::from(a >> 4), usize::from(a & 15), usize::from(b >> 4)); + let index_size = if v >= 1 { usize::from(b & 15) } else { 0 }; + let count = if v < 2 { u32::from(r.u16()?) } else { r.u32()? }; + for _ in 0..count { + let id = r.id(v >= 2)?; + let method = if v >= 1 { (r.u16()? & 15) as u8 } else { 0 }; + r.u16()?; // data reference index + let base = r.uint(base_size)?; + let n = r.u16()?; + let mut extents = Vec::with_capacity(usize::from(n).min(64)); + for _ in 0..n { + r.uint(index_size)?; + let offset = r.uint(off_size)?; + let length = r.uint(len_size)?; + extents.push(Extent { offset, length }); + // Zero-width offset and length fields read no bytes, so the file size alone doesn't + // bound this. + c.extents += 1; + if c.extents > MAX_ITEMS { + return Err(bad("too many item extents")); + } + } + c.locs.push((id, Loc { method, base, extents })); + if c.locs.len() > MAX_ITEMS { + return Err(bad("too many items")); + } + } + Ok(()) +} + +fn parse_iprp(b: &[u8], c: &mut Container, depth: u32) -> Result<()> { + if depth > MAX_DEPTH { + return Err(bad("boxes nested too deep")); + } + for (t, b) in boxes(b)? { + match &t { + b"ipco" => { + for (t, b) in boxes(b)? { + c.props.push(parse_prop(&t, b)?); + if c.props.len() > MAX_ITEMS { + return Err(bad("too many properties")); + } + } + } + b"ipma" => parse_ipma(b, c)?, + _ => {} + } + } + Ok(()) +} + +fn parse_ipma(b: &[u8], c: &mut Container) -> Result<()> { + let mut r = Rd::new(b); + let v = r.u8()?; + let flags = r.take(3)?; + let wide = flags.get(2).is_some_and(|f| f & 1 != 0); + let n = r.u32()?; + for _ in 0..n { + let id = r.id(v != 0)?; + let k = r.u8()?; + let mut list = Vec::with_capacity(usize::from(k)); + for _ in 0..k { + let idx = if wide { usize::from(r.u16()? & 0x7fff) } else { usize::from(r.u8()? & 0x7f) }; + list.push(idx); + } + c.assoc.push((id, list)); + if c.assoc.len() > MAX_ITEMS { + return Err(bad("too many property associations")); + } + } + Ok(()) +} + +fn parse_prop(t: &[u8; 4], b: &[u8]) -> Result { + let mut r = Rd::new(b); + Ok(match t { + b"av1C" => Prop::Av1c(b.get(4..).unwrap_or(&[]).to_vec()), + b"colr" => match r.take(4)? { + b"nclx" => Prop::Nclx(Cicp { primaries: r.u16()?, transfer: r.u16()?, matrix: r.u16()?, full_range: r.u8()? & 0x80 != 0 }), + b"prof" | b"rICC" => Prop::Icc(r.rest().to_vec()), + _ => Prop::Other, + }, + b"ispe" => { + r.version()?; + Prop::Ispe(r.u32()?, r.u32()?) + } + b"auxC" => { + r.version()?; + Prop::AuxC(r.cstr()?.to_vec()) + } + b"irot" => Prop::T(Transform::Rot(r.u8()? & 3)), + b"imir" => Prop::T(Transform::Mir(r.u8()? & 1)), + b"clap" => { + let mut q = || -> Result { + let n = r.u32()? as i32; + let d = r.u32()? as i32; + if d == 0 { + return Err(bad("clap with a zero denominator")); + } + Ok(f64::from(n) / f64::from(d)) + }; + let (w, h, dx, dy) = (q()?, q()?, q()?, q()?); + Prop::T(Transform::Clap { w, h, dx, dy }) + } + _ => Prop::Other, + }) +} + +impl Container<'_> { + fn item_type(&self, id: u32) -> Option<[u8; 4]> { + self.items.iter().find(|t| t.id == id).map(|t| t.kind) + } + fn props_of(&self, id: u32) -> impl Iterator { + self.assoc.iter().filter(move |a| a.0 == id).flat_map(|a| a.1.iter()).filter_map(|&i| i.checked_sub(1).and_then(|i| self.props.get(i))) + } + fn data(&self, id: u32) -> Result> { + let loc = self.locs.iter().find(|l| l.0 == id).map(|l| &l.1).ok_or_else(|| bad(format!("item {id} has no location")))?; + let src = match loc.method { + 0 => self.file, + 1 => self.idat, + _ => return Err(CodecError::unsupported(F, "item data by reference to another item")), + }; + let mut out = Vec::new(); + for e in &loc.extents { + let start = loc.base.checked_add(e.offset).ok_or_else(|| bad("item offset overflows"))?; + let start = usize::try_from(start).map_err(|_| bad("item offset out of range"))?; + let end = if e.length == 0 { + src.len() + } else { + usize::try_from(e.length).ok().and_then(|l| start.checked_add(l)).ok_or_else(|| bad("item length overflows"))? + }; + let chunk = src.get(start..end).ok_or_else(|| bad("item data runs past the end of the file"))?; + // Every byte comes from the file, so a real item is never larger than it; repeated or + // overlapping extents that add up to more are refused before they allocate. + if out.len().saturating_add(chunk.len()) > self.file.len() { + return Err(bad("item data is larger than the file")); + } + out.extend_from_slice(chunk); + } + Ok(out) + } + fn refs_from(&self, kind: &[u8; 4], from: u32) -> Vec { + self.refs.iter().filter(|r| &r.0 == kind && r.1 == from).flat_map(|r| r.2.iter().copied()).collect() + } + /// Items with a `kind` reference to `to`. + fn refs_to(&self, kind: &[u8; 4], to: u32) -> impl Iterator { + self.refs.iter().filter(move |r| &r.0 == kind && r.2.contains(&to)).map(|r| r.1) + } + fn ispe(&self, id: u32) -> Option<(u32, u32)> { + self.props_of(id).find_map(|p| if let Prop::Ispe(w, h) = p { Some((*w, *h)) } else { None }) + } + fn transforms(&self, id: u32) -> Vec { + self.props_of(id).filter_map(|p| if let Prop::T(t) = p { Some(*t) } else { None }).collect() + } + fn nclx(&self, id: u32) -> Option { + self.props_of(id).find_map(|p| if let Prop::Nclx(n) = p { Some(*n) } else { None }) + } + fn icc(&self, id: u32) -> Option> { + self.props_of(id).find_map(|p| if let Prop::Icc(b) = p { Some(b.clone()) } else { None }) + } + /// The primary item's alpha plane: an auxiliary image (`auxl`) whose `auxC` says alpha. + fn alpha_item(&self) -> Option { + self.refs_to(b"auxl", self.primary).find(|&id| { + matches!(self.item_type(id), Some(t) if &t == b"av01" || &t == b"grid") + && self.props_of(id).any(|p| matches!(p, Prop::AuxC(urn) if ALPHA_URNS.contains(&urn.as_slice()))) + }) + } + /// The primary item's colour is premultiplied by its alpha (`prem` from colour to alpha). + fn premultiplied(&self, alpha: u32) -> bool { + self.refs_from(b"prem", self.primary).contains(&alpha) + } + /// The first item of a metadata kind that describes (`cdsc`) the primary item. + fn metadata_item(&self, is: impl Fn(&Item) -> bool) -> Option { + let described: Vec = self.refs_to(b"cdsc", self.primary).collect(); + self.items.iter().filter(|i| is(i)).map(|i| i.id).find(|id| described.contains(id)) + } +} + +/// The size of an image item (`av01` or `grid`) before its transforms. +fn item_size(c: &Container, id: u32) -> Result<(u32, u32)> { + let kind = c.item_type(id).ok_or_else(|| bad("an image item is not described"))?; + let (w, h) = match (c.ispe(id), &kind) { + (_, b"grid") => grid_header(&c.data(id)?)?.2, + (Some(s), b"av01") => s, + (None, b"av01") => return Err(bad("an AV1 image item has no size (ispe)")), + _ => return Err(CodecError::unsupported(F, "the image item is not an AV1 image or a grid")), + }; + if w == 0 || h == 0 { + return Err(bad("zero dimension")); + } + Ok((w, h)) +} + +/// The size after `clap` / `irot`, from a stored size. +fn displayed(mut w: u32, mut h: u32, ts: &[Transform]) -> (u32, u32) { + for t in ts { + match *t { + Transform::Clap { w: cw, h: ch, .. } if cw >= 1.0 && ch >= 1.0 && cw.is_finite() && ch.is_finite() => { + w = (cw.round() as u32).clamp(1, w); + h = (ch.round() as u32).clamp(1, h); + } + Transform::Rot(n) if n % 2 == 1 => std::mem::swap(&mut w, &mut h), + _ => {} + } + } + (w, h) +} + +/// (rows, columns, output size) of a `grid` item. +fn grid_header(d: &[u8]) -> Result<(u32, u32, (u32, u32))> { + let mut r = Rd::new(d); + r.u8()?; // version + let flags = r.u8()?; + let rows = u32::from(r.u8()?) + 1; + let cols = u32::from(r.u8()?) + 1; + let n = if flags & 1 != 0 { 4 } else { 2 }; + let w = r.uint(n)? as u32; + let h = r.uint(n)? as u32; + Ok((rows, cols, (w, h))) +} + +/// The upright size [`decode`] returns (`keep_orientation` off), from the boxes alone. +pub(crate) fn probe(bytes: &[u8], limits: &Limits) -> Result<(u32, u32)> { + let c = parse(bytes)?; + let (w, h) = item_size(&c, c.primary)?; + limits.check_size(w, h)?; + Ok(displayed(w, h, &c.transforms(c.primary))) +} + +/// One decoded AV1 picture. +struct Pic { + w: usize, + h: usize, + bits: u8, + ssx: usize, + ssy: usize, + mono: bool, + planes: [Vec; 3], + cicp: Cicp, +} + +fn av1_error(e: av1::Error) -> CodecError { + match e { + av1::Error::Unsupported(w) => CodecError::unsupported(F, format!("AV1: {w}")), + other => bad(format!("AV1: {other}")), + } +} + +/// Decodes the `av01` item `id`, refusing pictures over `limits`. +fn decode_av1(c: &Container, id: u32, limits: &Limits) -> Result { + if c.item_type(id) != Some(*b"av01") { + return Err(CodecError::unsupported(F, "an image tile is not an AV1 image")); + } + // A tile's declared size counts before its picture is decoded too. + if let Some((w, h)) = c.ispe(id) { + limits.check(w, h, ChannelLayout::Rgb, SampleType::U16)?; + } + let data = c.data(id)?; + let config = c.props_of(id).find_map(|p| if let Prop::Av1c(o) = p { Some(o.clone()) } else { None }); + let mut dec = av1::Decoder::new(); + dec.set_memory_budget(limits.max_alloc.min(AV1_MEMORY_BUDGET)); + let mut pics = catch_unwind(AssertUnwindSafe(|| -> std::result::Result, av1::Error> { + let mut pics = Vec::new(); + // The sequence header normally travels in the item too; the av1C copy covers files + // where it doesn't. + if let Some(cfg) = config.filter(|o| !o.is_empty()) { + pics.extend(dec.decode(&cfg)?); + } + pics.extend(dec.decode(&data)?); + pics.extend(dec.flush_result()?); + Ok(pics) + })) + .map_err(|_| bad("the AV1 decoder failed on this file"))? + .map_err(av1_error)?; + if pics.is_empty() { + return Err(bad("the AV1 data holds no picture")); + } + let p = pics.swap_remove(0); + limits.check(p.width, p.height, ChannelLayout::Rgb, SampleType::U16)?; + let (w, h) = (p.width as usize, p.height as usize); + let (ssx, ssy) = (usize::from(p.subsampling_x.min(1)), usize::from(p.subsampling_y.min(1))); + let need = w.checked_mul(h).ok_or_else(|| bad("picture too large"))?; + let cneed = ((w + ssx) >> ssx) * ((h + ssy) >> ssy); + if need == 0 || p.planes[0].len() < need || (!p.mono_chrome && (p.planes[1].len() < cneed || p.planes[2].len() < cneed)) { + return Err(bad("AV1 picture planes are short")); + } + let cicp = Cicp { + primaries: u16::from(p.color_primaries), + transfer: u16::from(p.transfer_characteristics), + matrix: u16::from(p.matrix_coefficients), + full_range: p.full_range, + }; + Ok(Pic { w, h, bits: p.bit_depth.clamp(8, 16), ssx, ssy, mono: p.mono_chrome, planes: p.planes, cicp }) +} + +/// Kr, Kb of an H.273 matrix code point; `None` = identity (GBR). +fn coefficients(matrix: u16, primaries: u16) -> Result> { + Ok(match matrix { + 0 => None, + 1 => Some((0.2126, 0.0722)), + 4 => Some((0.30, 0.11)), + 7 => Some((0.212, 0.087)), + 9 | 10 => Some((0.2627, 0.0593)), + // Chromaticity-derived non-constant luminance. + 12 => { + let [kr, _, kb] = crate::cicp::luma_weights(primaries); + Some((kr, kb)) + } + // 2 (unspecified: AVIF readers assume BT.601), 5, 6 (BT.601) and reserved values. + 2 | 5 | 6 | 3 | 15.. => Some((0.299, 0.114)), + _ => return Err(CodecError::unsupported(F, format!("matrix coefficients {matrix} (YCgCo, constant luminance or ICtCp)"))), + }) +} + +/// A chroma sample at luma position (x, y), bilinear between chroma sites centred on their +/// luma pairs. +#[inline] +fn chroma_at(plane: &[u16], cw: usize, ch: usize, ssx: usize, ssy: usize, x: usize, y: usize) -> f32 { + let pos = |v: usize, ss: usize, n: usize| -> (usize, usize, f32) { + if ss == 0 { + return (v.min(n - 1), v.min(n - 1), 0.0); + } + let f = ((v as f32 + 0.5) / 2.0 - 0.5).max(0.0); + let i = f as usize; + (i.min(n - 1), (i + 1).min(n - 1), f - i as f32) + }; + let (x0, x1, fx) = pos(x, ssx, cw); + let (y0, y1, fy) = pos(y, ssy, ch); + let s = |xx: usize, yy: usize| f32::from(plane.get(yy * cw + xx).copied().unwrap_or(0)); + let top = s(x0, y0) * (1.0 - fx) + s(x1, y0) * fx; + let bot = s(x0, y1) * (1.0 - fx) + s(x1, y1) * fx; + top * (1.0 - fy) + bot * fy +} + +/// The sample scaling of a picture: luma offset and range, chroma range and midpoint. +struct Levels { + yoff: f32, + yrange: f32, + crange: f32, + mid: f32, +} + +impl Levels { + fn new(bits: u8, full_range: bool) -> Self { + let max = ((1u32 << bits) - 1) as f32; + let scale = f32::from(1u16 << (bits - 8).min(8)); + let (yoff, yrange, crange) = if full_range { (0.0, max, max) } else { (16.0 * scale, 219.0 * scale, 224.0 * scale) }; + Levels { yoff, yrange, crange, mid: f32::from(1u16 << (bits - 1).min(15)) } + } +} + +fn to_u16(v: f32) -> u16 { + (v.clamp(0.0, 1.0) * 65535.0 + 0.5) as u16 +} + +/// Where a decoded picture goes: an interleaved 16-bit canvas of `ch` channels. +struct Canvas { + w: usize, + h: usize, + ch: usize, + data: Vec, +} + +impl Canvas { + fn new(w: u32, h: u32, layout: ChannelLayout, limits: &Limits) -> Result { + limits.check(w, h, layout, SampleType::U16)?; + let (w, h, ch) = (w as usize, h as usize, layout.channels()); + let len = w.checked_mul(h).and_then(|n| n.checked_mul(ch)).ok_or_else(|| bad("image too large"))?; + Ok(Canvas { w, h, ch, data: vec![0; len] }) + } + + /// The picture's YCbCr as non-linear R'G'B' into channels 0..3, its top-left at (x0, y0). + fn put_colour(&mut self, p: &Pic, cicp: Cicp, x0: usize, y0: usize) -> Result<()> { + let lv = Levels::new(p.bits, cicp.full_range); + let k = coefficients(cicp.matrix, cicp.primaries)?; + let (cw, chh) = ((p.w + p.ssx) >> p.ssx, (p.h + p.ssy) >> p.ssy); + for y in 0..p.h.min(self.h.saturating_sub(y0)) { + for x in 0..p.w.min(self.w.saturating_sub(x0)) { + let luma = (f32::from(p.planes[0][y * p.w + x]) - lv.yoff) / lv.yrange; + let (cb, cr) = if p.mono { + (lv.mid, lv.mid) + } else { + (chroma_at(&p.planes[1], cw, chh, p.ssx, p.ssy, x, y), chroma_at(&p.planes[2], cw, chh, p.ssx, p.ssy, x, y)) + }; + let rgb = match k { + // Identity (GBR): Y = G, Cb = B, Cr = R, all three at the luma levels. + None => [(cr - lv.yoff) / lv.yrange, luma, (cb - lv.yoff) / lv.yrange], + Some((kr, kb)) => { + let (cb, cr) = ((cb - lv.mid) / lv.crange, (cr - lv.mid) / lv.crange); + let r = luma + 2.0 * (1.0 - kr) * cr; + let b = luma + 2.0 * (1.0 - kb) * cb; + [r, (luma - kr * r - kb * b) / (1.0 - kr - kb), b] + } + }; + let o = ((y0 + y) * self.w + x0 + x) * self.ch; + for (d, v) in self.data[o..o + 3].iter_mut().zip(rgb) { + *d = to_u16(v); + } + } + } + Ok(()) + } + + /// The picture's luma as alpha into channel 3, its top-left at (x0, y0). + fn put_alpha(&mut self, p: &Pic, x0: usize, y0: usize) { + let lv = Levels::new(p.bits, p.cicp.full_range); + for y in 0..p.h.min(self.h.saturating_sub(y0)) { + for x in 0..p.w.min(self.w.saturating_sub(x0)) { + let a = (f32::from(p.planes[0][y * p.w + x]) - lv.yoff) / lv.yrange; + self.data[((y0 + y) * self.w + x0 + x) * self.ch + 3] = to_u16(a); + } + } + } +} + +/// Decodes the image item `id` (one `av01` or a `grid` of them) into `canvas`, through `put`. +/// Returns the first picture's bit depth and colour description. +fn render( + c: &Container, + id: u32, + limits: &Limits, + canvas: &mut Canvas, + put: &mut dyn FnMut(&mut Canvas, &Pic, usize, usize) -> Result<()>, +) -> Result<(u8, Cicp)> { + if c.item_type(id) != Some(*b"grid") { + let p = decode_av1(c, id, limits)?; + if (p.w, p.h) != (canvas.w, canvas.h) { + return Err(bad("the AV1 picture's size differs from its item's")); + } + put(canvas, &p, 0, 0)?; + return Ok((p.bits, p.cicp)); + } + let (rows, cols, _) = grid_header(&c.data(id)?)?; + let tiles = c.refs_from(b"dimg", id); + if tiles.is_empty() || tiles.len() as u64 != u64::from(rows) * u64::from(cols) { + return Err(bad("grid tile count doesn't match its rows and columns")); + } + let mut first: Option<(usize, usize, u8, Cicp)> = None; + for (i, &t) in tiles.iter().enumerate() { + let p = decode_av1(c, t, limits)?; + let (tw, th, ..) = *first.get_or_insert((p.w, p.h, p.bits, p.cicp)); + if (p.w, p.h) != (tw, th) { + return Err(bad("grid tiles differ in size")); + } + if tw.saturating_mul(cols as usize) < canvas.w || th.saturating_mul(rows as usize) < canvas.h { + return Err(bad("grid tiles don't cover the grid")); + } + put(canvas, &p, (i % cols as usize) * tw, (i / cols as usize) * th)?; + } + first.map(|(_, _, bits, cicp)| (bits, cicp)).ok_or_else(|| bad("grid without tiles")) +} + +/// Applies the container's transforms in order to an interleaved canvas. +fn apply_transforms(mut cv: Canvas, ts: &[Transform]) -> Canvas { + for t in ts { + cv = match *t { + Transform::Clap { w, h, dx, dy } => clap(cv, w, h, dx, dy), + Transform::Rot(n) => (0..n).fold(cv, |cv, _| rotate(cv)), + Transform::Mir(axis) => mirror(cv, axis), + }; + } + cv +} + +fn clap(cv: Canvas, cw: f64, chh: f64, dx: f64, dy: f64) -> Canvas { + if !(cw >= 1.0 && chh >= 1.0 && cw.is_finite() && chh.is_finite() && dx.is_finite() && dy.is_finite()) { + return cv; + } + let (w, h, ch) = (cv.w, cv.h, cv.ch); + let nw = (cw.round() as usize).clamp(1, w); + let nh = (chh.round() as usize).clamp(1, h); + // The centre of the aperture is the image centre plus the offset. + let x0 = ((w as f64 - 1.0) / 2.0 + dx - (nw as f64 - 1.0) / 2.0).round().clamp(0.0, (w - nw) as f64) as usize; + let y0 = ((h as f64 - 1.0) / 2.0 + dy - (nh as f64 - 1.0) / 2.0).round().clamp(0.0, (h - nh) as f64) as usize; + let mut data = Vec::with_capacity(nw * nh * ch); + for y in y0..y0 + nh { + data.extend_from_slice(&cv.data[(y * w + x0) * ch..(y * w + x0 + nw) * ch]); + } + Canvas { w: nw, h: nh, ch, data } +} + +/// 90° anticlockwise: (x, y) → (y, w - 1 - x), the new size h × w. +fn rotate(cv: Canvas) -> Canvas { + let (w, h, ch) = (cv.w, cv.h, cv.ch); + let mut data = vec![0u16; cv.data.len()]; + for y in 0..h { + for x in 0..w { + let d = ((w - 1 - x) * h + y) * ch; + let s = (y * w + x) * ch; + data[d..d + ch].copy_from_slice(&cv.data[s..s + ch]); + } + } + Canvas { w: h, h: w, ch, data } +} + +fn mirror(mut cv: Canvas, axis: u8) -> Canvas { + let (w, h, ch) = (cv.w, cv.h, cv.ch); + if axis == 0 { + for y in 0..h / 2 { + let (top, bottom) = cv.data.split_at_mut((h - 1 - y) * w * ch); + top[y * w * ch..(y + 1) * w * ch].swap_with_slice(&mut bottom[..w * ch]); + } + } else { + for row in cv.data.chunks_exact_mut(w * ch) { + for x in 0..w / 2 { + for c in 0..ch { + row.swap(x * ch + c, (w - 1 - x) * ch + c); + } + } + } + } + cv +} + +/// Straight colour from colour premultiplied by alpha. +fn unpremultiply(cv: &mut Canvas) { + for px in cv.data.as_chunks_mut::<4>().0 { + let a = u32::from(px[3]); + if a == 0 { + continue; + } + for v in &mut px[..3] { + *v = (u32::from(*v) * 65535 / a).min(65535) as u16; + } + } +} + +/// The primary item's Exif (TIFF structure, its offset prefix dropped) and XMP. +fn read_metadata(c: &Container) -> (Option>, Option) { + let exif = c.metadata_item(|i| &i.kind == b"Exif").and_then(|id| c.data(id).ok()).and_then(|d| { + let offset = usize::try_from(u32::from_be_bytes(d.get(..4)?.try_into().ok()?)).ok()?; + let tiff = d.get(4usize.checked_add(offset)?..)?; + (tiff.starts_with(b"II*\0") || tiff.starts_with(b"MM\0*")).then(|| tiff.to_vec()) + }); + let xmp = c + .metadata_item(|i| &i.kind == b"mime" && i.content_type.as_deref() == Some(b"application/rdf+xml")) + .and_then(|id| c.data(id).ok()) + .map(|d| String::from_utf8_lossy(&d).trim_end_matches('\0').to_owned()); + (exif, xmp) +} + +/// Decodes the primary image. `keep_orientation` leaves the container's `clap`, `irot` and +/// `imir` unapplied (the stored pixels), as for HEIF. +pub(crate) fn decode(bytes: &[u8], limits: &Limits, keep_orientation: bool) -> Result { + let c = parse(bytes)?; + let id = c.primary; + let (w, h) = item_size(&c, id)?; + let alpha = c.alpha_item().filter(|&a| item_size(&c, a).is_ok_and(|s| s == (w, h))); + let layout = if alpha.is_some() { ChannelLayout::Rgba } else { ChannelLayout::Rgb }; + // The declared size, before any picture is decoded. + let mut canvas = Canvas::new(w, h, layout, limits)?; + let file_cicp = c.nclx(id); + let mut colour = |cv: &mut Canvas, p: &Pic, x: usize, y: usize| cv.put_colour(p, file_cicp.unwrap_or(p.cicp), x, y); + let (bits, stream_cicp) = render(&c, id, limits, &mut canvas, &mut colour)?; + if let Some(a) = alpha { + render(&c, a, limits, &mut canvas, &mut |cv, p, x, y| { + cv.put_alpha(p, x, y); + Ok(()) + })?; + if c.premultiplied(a) { + unpremultiply(&mut canvas); + } + } + if !keep_orientation { + canvas = apply_transforms(canvas, &c.transforms(id)); + } + let (w, h) = (canvas.w as u32, canvas.h as u32); + let image = Image::from_u16(w, h, layout, &canvas.data)?; + drop(canvas); + let mut img = if bits > 8 { image } else { image.convert(layout, SampleType::U8) }; + let cicp = file_cicp.unwrap_or(stream_cicp); + img.icc = c.icc(id); + img.cicp = Some(cicp); + let (exif, xmp) = read_metadata(&c); + img.meta = Metadata { + exif: exif.map(|e| if keep_orientation { e } else { crate::orientation::upright_exif(&e).into_owned() }), + xmp: xmp.map(|x| if keep_orientation { x } else { crate::orientation::upright_xmp(&x).into_owned() }), + ..Default::default() + }; + // PQ or HLG: linear light in 32-bit float, as for HEIF. + if cicp.is_hdr() { + limits.check(w, h, layout, SampleType::F32)?; + return crate::cicp::linearize(img, cicp); + } + Ok(img) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::DecodeOptions; + + const QUAD_420: &[u8] = include_bytes!("../../tests/fixtures/avif/quad-420-bt709.avif"); + const QUAD_420_DAV1D: &[u8] = include_bytes!("../../tests/fixtures/avif/quad-420-bt709.dav1d.yuv"); + const QUAD_GBR_LOSSLESS: &[u8] = include_bytes!("../../tests/fixtures/avif/quad-444-gbr-lossless.avif"); + const QUAD_SOURCE: &[u8] = include_bytes!("../../tests/fixtures/avif/quad-source.rgb"); + + fn rgb8(img: &Image) -> Vec { + img.to_rgba8().as_chunks::<4>().0.iter().flat_map(|p| [p[0], p[1], p[2]]).collect() + } + + fn mean_abs_diff(a: &[u8], b: &[u8]) -> f64 { + assert_eq!(a.len(), b.len()); + a.iter().zip(b).map(|(&x, &y)| (f64::from(x) - f64::from(y)).abs()).sum::() / a.len() as f64 + } + + /// A box of type `t` around `body`. + fn bx(t: &[u8; 4], body: &[u8]) -> Vec { + let mut v = ((body.len() + 8) as u32).to_be_bytes().to_vec(); + v.extend_from_slice(t); + v.extend_from_slice(body); + v + } + + /// A full box: version 0, no flags. + fn fbx(t: &[u8; 4], body: &[u8]) -> Vec { + let mut b = vec![0, 0, 0, 0]; + b.extend_from_slice(body); + bx(t, &b) + } + + /// An `infe` (version 2) for item `id` of `kind`. + fn infe(id: u16, kind: &[u8; 4]) -> Vec { + let mut b = vec![2, 0, 0, 0]; + b.extend_from_slice(&id.to_be_bytes()); + b.extend_from_slice(&[0, 0]); + b.extend_from_slice(kind); + b.push(0); + bx(b"infe", &b) + } + + fn ispe(w: u32, h: u32) -> Vec { + let mut b = w.to_be_bytes().to_vec(); + b.extend_from_slice(&h.to_be_bytes()); + fbx(b"ispe", &b) + } + + /// The AV1 data and `av1C` of an encoded file's primary item. + fn av1_of(file: &[u8]) -> (Vec, Vec) { + let c = parse(file).unwrap(); + let cfg = c.props_of(c.primary).find_map(|p| if let Prop::Av1c(o) = p { Some(o.clone()) } else { None }).unwrap(); + (c.data(c.primary).unwrap(), cfg) + } + + /// An AVIF of `items` (id, type, data, property indices) with `props`, `refs` and primary 1. + /// All item data sits in `idat` (construction method 1). + /// An item: ID, type, data and 1-based property indices. + type TestItem<'a> = (u16, &'a [u8; 4], &'a [u8], &'a [u8]); + /// An item reference: type, from, to. + type TestRef<'a> = (&'a [u8; 4], u16, &'a [u16]); + + fn build(items: &[TestItem], props: &[Vec], refs: &[TestRef]) -> Vec { + let mut iinf = vec![0, 0, 0, 0]; + iinf.extend_from_slice(&(items.len() as u16).to_be_bytes()); + let mut iloc = vec![1, 0, 0, 0, 0x44, 0x00]; + iloc.extend_from_slice(&(items.len() as u16).to_be_bytes()); + let mut ipma = vec![0, 0, 0, 0]; + ipma.extend_from_slice(&(items.len() as u32).to_be_bytes()); + let mut idat = Vec::new(); + for &(id, kind, data, assoc) in items { + iinf.extend(infe(id, kind)); + iloc.extend_from_slice(&id.to_be_bytes()); + iloc.extend_from_slice(&[0, 1, 0, 0, 0, 1]); // method 1, data ref 0, one extent + iloc.extend_from_slice(&(idat.len() as u32).to_be_bytes()); + iloc.extend_from_slice(&(data.len() as u32).to_be_bytes()); + idat.extend_from_slice(data); + ipma.extend_from_slice(&id.to_be_bytes()); + ipma.push(assoc.len() as u8); + ipma.extend(assoc.iter().map(|&p| p | 0x80)); + } + let mut iref = vec![0, 0, 0, 0]; + for &(kind, from, to) in refs { + let mut b = from.to_be_bytes().to_vec(); + b.extend_from_slice(&(to.len() as u16).to_be_bytes()); + to.iter().for_each(|t| b.extend_from_slice(&t.to_be_bytes())); + iref.extend(bx(kind, &b)); + } + let mut meta = vec![0, 0, 0, 0]; + meta.extend(fbx(b"hdlr", b"\0\0\0\0pict\0\0\0\0\0\0\0\0\0\0\0\0\0")); + meta.extend(fbx(b"pitm", &[0, 1])); + meta.extend(bx(b"iinf", &iinf)); + meta.extend(bx(b"iloc", &iloc)); + meta.extend(bx(b"iref", &iref)); + meta.extend(bx(b"iprp", &[bx(b"ipco", &props.concat()), bx(b"ipma", &ipma)].concat())); + meta.extend(bx(b"idat", &idat)); + let mut file = bx(b"ftyp", b"avif\0\0\0\0avifmif1miaf"); + file.extend(bx(b"meta", &meta)); + file + } + + #[test] + fn libaom_420_limited_range_matches_dav1d() { + let img = crate::decode(QUAD_420).unwrap(); + assert_eq!((img.width(), img.height(), img.layout(), img.sample_type()), (33, 17, ChannelLayout::Rgb, SampleType::U8)); + assert_eq!(img.cicp.map(|c| (c.matrix, c.full_range)), Some((1, false)), "BT.709 matrix, limited range"); + assert_eq!(crate::probe_size(QUAD_420).unwrap(), (33, 17)); + // The AV1 picture is libdav1d's, sample for sample. + let c = parse(QUAD_420).unwrap(); + let p = decode_av1(&c, c.primary, &Limits::default()).unwrap(); + assert_eq!((p.w, p.h, p.bits, p.ssx, p.ssy, p.mono), (33, 17, 8, 1, 1, false)); + let planes: Vec = p.planes.iter().flatten().map(|&v| v as u8).collect(); + assert_eq!(planes, QUAD_420_DAV1D); + let ours = rgb8(&img); + // The quadrant centres are the source's colours, give or take the lossy coding. + for (x, y) in [(5usize, 4usize), (27, 4), (5, 13), (27, 13)] { + let i = (y * 33 + x) * 3; + let d = mean_abs_diff(&ours[i..i + 3], &QUAD_SOURCE[i..i + 3]); + assert!(d < 12.0, "({x}, {y}): {:?} vs {:?}", &ours[i..i + 3], &QUAD_SOURCE[i..i + 3]); + } + } + + #[test] + fn libaom_lossless_identity_matrix_is_exact() { + let img = crate::decode(QUAD_GBR_LOSSLESS).unwrap(); + assert_eq!((img.width(), img.height(), img.sample_type()), (33, 17, SampleType::U8)); + assert_eq!(img.cicp.map(|c| (c.matrix, c.full_range)), Some((0, true))); + assert_eq!(rgb8(&img), QUAD_SOURCE); + } + + #[test] + fn limits_are_checked_before_decoding() { + let tight = |max_pixels, max_alloc| DecodeOptions { limits: Limits { max_pixels, max_alloc, ..Limits::default() }, ..Default::default() }; + assert!(matches!(crate::decode_with(QUAD_420, &tight(33 * 17 - 1, u64::MAX)), Err(CodecError::LimitExceeded(_)))); + // The 16-bit intermediate counts: 33 × 17 RGB at 2 bytes. + assert!(matches!(crate::decode_with(QUAD_420, &tight(u64::MAX, 33 * 17 * 6 - 1)), Err(CodecError::LimitExceeded(_)))); + assert!(crate::decode_with(QUAD_420, &tight(33 * 17, Limits::default().max_alloc)).is_ok()); + // `max_alloc` is the AV1 decoder's picture-store budget too. + assert!(crate::decode_with(QUAD_420, &tight(33 * 17, 33 * 17 * 6)).is_err()); + // A declared size over the limits fails from the boxes alone. + let (av1, cfg) = av1_of(QUAD_420); + let huge = build(&[(1, b"av01", &av1, &[1, 2])], &[ispe(1 << 20, 1 << 20), bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat())], &[]); + assert!(matches!(crate::decode(&huge), Err(CodecError::LimitExceeded(_)))); + assert!(matches!(crate::probe_size(&huge), Err(CodecError::LimitExceeded(_)))); + } + + #[test] + fn a_picture_that_differs_from_its_ispe_is_refused() { + let (av1, cfg) = av1_of(QUAD_420); + let file = build(&[(1, b"av01", &av1, &[1, 2])], &[ispe(32, 17), bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat())], &[]); + assert!(matches!(crate::decode(&file), Err(CodecError::Malformed { .. }))); + } + + #[test] + fn a_grid_is_assembled_from_its_tiles_and_cropped() { + // Two copies of the 33 × 17 picture side by side, cropped to 60 × 15 by the grid. + let (av1, cfg) = av1_of(QUAD_GBR_LOSSLESS); + let av1c = bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat()); + let grid = [0u8, 0, 0, 1, 0, 60, 0, 15]; + let file = build( + &[(1, b"grid", &grid, &[1]), (2, b"av01", &av1, &[2, 3]), (3, b"av01", &av1, &[2, 3])], + &[ispe(60, 15), ispe(33, 17), av1c, fbx(b"pixi", &[3, 8, 8, 8])], + &[(b"dimg", 1, &[2, 3])], + ); + assert_eq!(crate::probe_size(&file).unwrap(), (60, 15)); + let img = crate::decode(&file).unwrap(); + assert_eq!((img.width(), img.height()), (60, 15)); + let got = rgb8(&img); + for y in 0..15 { + for x in 0..60 { + let s = (y * 33 + x % 33) * 3; + assert_eq!(&got[(y * 60 + x) * 3..][..3], &QUAD_SOURCE[s..s + 3], "({x}, {y})"); + } + } + // Tiles that can't cover the grid are refused. + let wide = [0u8, 0, 0, 1, 0, 70, 0, 15]; + let file = build( + &[(1, b"grid", &wide, &[1]), (2, b"av01", &av1, &[2, 3]), (3, b"av01", &av1, &[2, 3])], + &[ispe(70, 15), ispe(33, 17), bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat())], + &[(b"dimg", 1, &[2, 3])], + ); + assert!(matches!(crate::decode(&file), Err(CodecError::Malformed { .. }))); + } + + #[test] + fn container_rotation_and_mirror_are_applied_unless_kept() { + let (av1, cfg) = av1_of(QUAD_GBR_LOSSLESS); + let av1c = bx(b"av1C", &[&[0x81, 0, 0, 0][..], &cfg].concat()); + let file = build(&[(1, b"av01", &av1, &[1, 2, 3, 4])], &[ispe(33, 17), av1c, bx(b"irot", &[1]), bx(b"imir", &[0])], &[]); + assert_eq!(crate::probe_size(&file).unwrap(), (17, 33)); + let img = crate::decode(&file).unwrap(); + assert_eq!((img.width(), img.height()), (17, 33)); + let got = rgb8(&img); + // Rotated 90° anticlockwise, then top and bottom exchanged: a transpose, (x, y) from (y, x). + for y in 0..33 { + for x in 0..17 { + let s = (x * 33 + y) * 3; + assert_eq!(&got[(y * 17 + x) * 3..][..3], &QUAD_SOURCE[s..s + 3], "({x}, {y})"); + } + } + let kept = crate::decode_with(&file, &DecodeOptions { keep_orientation: true, ..Default::default() }).unwrap(); + assert_eq!((kept.width(), kept.height(), rgb8(&kept)), (33, 17, QUAD_SOURCE.to_vec())); + } + + #[test] + fn transforms_rotate_mirror_and_crop() { + // 3 × 2, one channel, value = index + let cv = || Canvas { w: 3, h: 2, ch: 1, data: (0..6).collect() }; + let r = apply_transforms(cv(), &[Transform::Rot(1)]); + // anticlockwise: the right column becomes the top row + assert_eq!((r.w, r.h, r.data), (2, 3, vec![2, 5, 1, 4, 0, 3])); + // axis 0 exchanges top and bottom, axis 1 left and right (libheif's and libavif's reading) + assert_eq!(apply_transforms(cv(), &[Transform::Mir(0)]).data, vec![3, 4, 5, 0, 1, 2]); + assert_eq!(apply_transforms(cv(), &[Transform::Mir(1)]).data, vec![2, 1, 0, 5, 4, 3]); + let c = apply_transforms(cv(), &[Transform::Clap { w: 1.0, h: 1.0, dx: 1.0, dy: 0.0 }]); + assert_eq!((c.w, c.h), (1, 1)); + assert!(c.data == [2] || c.data == [5]); + assert_eq!(displayed(3, 2, &[Transform::Rot(3)]), (2, 3)); + // A non-finite or empty aperture is ignored. + assert_eq!(apply_transforms(cv(), &[Transform::Clap { w: f64::NAN, h: 1.0, dx: 0.0, dy: 0.0 }]).data.len(), 6); + } + + #[test] + fn hostile_files_are_errors_not_panics() { + for file in [QUAD_420, QUAD_GBR_LOSSLESS] { + // every truncation + for n in 0..file.len() { + let _ = crate::probe_size(&file[..n]); + let _ = crate::decode(&file[..n]); + } + // byte flips through the container and the AV1 data + for i in 0..file.len() { + for x in [0x01u8, 0x80, 0xff] { + let mut m = file.to_vec(); + m[i] ^= x; + let _ = crate::probe_size(&m); + let _ = crate::decode(&m); + } + } + } + // box sizes that point far outside the file + let mut b = bx(b"ftyp", b"avif\0\0\0\0avif"); + b.extend_from_slice(b"\xff\xff\xff\xffmeta\0\0\0\0"); + assert!(crate::decode(&b).is_err()); + let mut b = bx(b"ftyp", b"avif\0\0\0\0avif"); + b.extend_from_slice(b"\0\0\0\x01meta\xff\xff\xff\xff\xff\xff\xff\xff"); + assert!(crate::probe_size(&b).is_err()); + } + + #[test] + fn an_animated_avif_is_unsupported() { + let mut b = bx(b"ftyp", b"avis\0\0\0\0avis"); + b.extend(bx(b"moov", &[])); + assert!(matches!(crate::decode(&b), Err(CodecError::Unsupported { format: Format::Avif, .. }))); + } + + #[test] + fn zero_width_iloc_extents_are_capped() { + // iloc v2 with zero-byte offset/length/base/index fields: each extent costs no input bytes + let mut iloc = vec![2, 0, 0, 0, 0, 0]; + iloc.extend_from_slice(&3u32.to_be_bytes()); + for id in 1..=3u32 { + iloc.extend_from_slice(&id.to_be_bytes()); + iloc.extend_from_slice(&[0, 0, 0, 0, 0xff, 0xff]); // method, data ref, 65535 extents + } + let mut meta = vec![0, 0, 0, 0]; + meta.extend(bx(b"iloc", &iloc)); + let mut b = bx(b"ftyp", b"avif\0\0\0\0avif"); + b.extend(bx(b"meta", &meta)); + assert!(matches!(crate::decode(&b), Err(CodecError::Malformed { message, .. }) if message.contains("extents"))); + } + + #[test] + fn item_data_larger_than_the_file_is_refused() { + // one item whose 1000 extents each repeat the whole file (length 0 = to the end) + let mut iloc = vec![1, 0, 0, 0, 0x44, 0]; + iloc.extend_from_slice(&1u16.to_be_bytes()); + iloc.extend_from_slice(&[0, 1, 0, 0, 0, 0]); // id 1, method 0, data ref 0 + iloc.extend_from_slice(&1000u16.to_be_bytes()); + for _ in 0..1000 { + iloc.extend_from_slice(&[0; 8]); + } + let mut meta = vec![0, 0, 0, 0]; + meta.extend(fbx(b"pitm", &[0, 1])); + meta.extend(bx(b"iloc", &iloc)); + let mut b = bx(b"ftyp", b"avif\0\0\0\0avif"); + b.extend(bx(b"meta", &meta)); + let c = parse(&b).unwrap(); + assert!(matches!(c.data(1), Err(CodecError::Malformed { message, .. }) if message.contains("larger than the file"))); + } + + #[test] + fn unsupported_matrices_are_errors() { + for m in [8u16, 11, 13, 14] { + assert!(matches!(coefficients(m, 1), Err(CodecError::Unsupported { .. })), "{m}"); + } + assert_eq!(coefficients(0, 1).unwrap(), None); + assert!(coefficients(12, 9).unwrap().is_some()); + } + + #[cfg(feature = "avif")] + mod with_the_encoder { + use super::*; + use crate::codecs::avif::{HdrTransfer, encode_avif_hdr, encode_avif_with_speed}; + + /// A smooth test card with a saturated band. + fn card(w: usize, h: usize, ch: usize) -> Vec { + (0..w * h) + .flat_map(|i| { + let (x, y) = (i % w, i / w); + let px = + [(x * 255 / (w - 1)) as u8, (y * 255 / (h - 1)) as u8, if x < w / 4 { 230 } else { 40 }, (255 - x * 200 / (w - 1)) as u8]; + px.into_iter().take(ch) + }) + .collect() + } + + #[test] + fn ravif_rgb_round_trip_is_10_bit() { + let (w, h) = (48, 32); + let src = Image::from_u8(w as u32, h as u32, ChannelLayout::Rgb, card(w, h, 3)).unwrap(); + let file = encode_avif_with_speed(&src, 95, 10).unwrap(); + let img = crate::decode(&file).unwrap(); + assert_eq!((img.width(), img.height(), img.layout(), img.sample_type()), (48, 32, ChannelLayout::Rgb, SampleType::U16)); + let diff = mean_abs_diff(&rgb8(&img), &card(w, h, 3)); + assert!(diff < 2.5, "mean difference {diff}"); + } + + #[test] + fn ravif_alpha_round_trips() { + let (w, h) = (40, 24); + let src = Image::from_u8(w as u32, h as u32, ChannelLayout::Rgba, card(w, h, 4)).unwrap(); + let file = encode_avif_with_speed(&src, 95, 10).unwrap(); + let img = crate::decode(&file).unwrap(); + assert_eq!(img.layout(), ChannelLayout::Rgba); + let got = img.to_rgba8(); + let want = card(w, h, 4); + let alpha = |v: &[u8]| v.iter().skip(3).step_by(4).copied().collect::>(); + let diff = mean_abs_diff(&alpha(&got), &alpha(&want)); + assert!(diff < 2.0, "alpha mean difference {diff}"); + } + + #[test] + fn exif_is_read_from_its_item() { + let mut src = Image::from_u8(16, 8, ChannelLayout::Rgb, card(16, 8, 3)).unwrap(); + let exif = b"II*\0\x08\0\0\0\0\0\0\0\0\0".to_vec(); + src.meta.exif = Some(exif.clone()); + let file = encode_avif_with_speed(&src, 80, 10).unwrap(); + let img = crate::decode_with(&file, &DecodeOptions { keep_orientation: true, ..Default::default() }).unwrap(); + assert_eq!(img.meta.exif.as_deref(), Some(exif.as_slice())); + } + + #[test] + fn hdr_round_trips_keep_highlights_above_white() { + let (w, h) = (32usize, 16usize); + // linear BT.2020: left half grey 0.18, right half 4 × SDR white + let rgb: Vec = (0..w * h).flat_map(|i| if i % w < w / 2 { [0.18f32; 3] } else { [4.0; 3] }).collect(); + for t in [HdrTransfer::Pq, HdrTransfer::Hlg] { + let file = encode_avif_hdr(w as u32, h as u32, &rgb, 98, 10, None, t).unwrap(); + let img = crate::decode(&file).unwrap(); + assert_eq!(img.sample_type(), SampleType::F32, "{t:?}"); + assert_eq!(img.cicp.map(|c| c.transfer), Some(Cicp::TRANSFER_LINEAR), "{t:?}"); + let v = img.to_f32_samples().unwrap(); + let at = |x: usize| v[(8 * w + x) * 3 + 1]; + assert!((at(4) / 0.18 - 1.0).abs() < 0.08, "{t:?}: grey {}", at(4)); + assert!((at(w - 4) / 4.0 - 1.0).abs() < 0.08, "{t:?}: highlight {}", at(w - 4)); + } + } + } +} diff --git a/crates/image-codecs/src/format.rs b/crates/image-codecs/src/format.rs index ecaf945cd..fbdb412b1 100644 --- a/crates/image-codecs/src/format.rs +++ b/crates/image-codecs/src/format.rs @@ -26,7 +26,8 @@ pub enum Format { OpenExr, /// Radiance RGBE. Hdr, - /// Encode-only behind the `avif` feature; see [`ASYMMETRIC_EXCEPTIONS`]. + /// Encoded behind the `avif` feature and decoded behind `avif-decode` (native targets); see + /// [`ASYMMETRIC_EXCEPTIONS`] for a build with only one of them. Avif, /// HEIF/HEIC (HEVC-coded): read-only; see [`ASYMMETRIC_EXCEPTIONS`]. Heif, @@ -89,8 +90,10 @@ pub const ASYMMETRIC_EXCEPTIONS: &[(Format, &str)] = &[ ), ( Format::Avif, - "AVIF encode uses ravif (pure Rust) but decoding requires dav1d (C); read stays unsupported \ - until a pure-Rust AV1 decoder is viable. Only enabled with the non-default `avif` feature.", + "AVIF encode (ravif and rav1e, pure Rust) is behind the non-default `avif` feature and AVIF \ + decode (craft-video's clean-room pure-Rust AV1 decoder) behind the non-default \ + `avif-decode` feature, native targets only (on wasm32 a decoder panic would abort). A build \ + with only one of them reads or writes AVIF, not both.", ), (Format::Jxl, "Lossless JPEG XL export uses the pure-Rust zune-jpegxl encoder; JPEG XL reading is tracked separately and is not yet available."), ( @@ -298,7 +301,9 @@ pub fn caps(format: Format) -> FormatCaps { Format::Qoi => base, Format::OpenExr => FormatCaps { depths: &[S::F16, S::F32], layouts: RGB_GRAY, ..base }, Format::Hdr => FormatCaps { depths: &[S::F32], layouts: &[L::Rgb], alpha: false, lossy: true, ..base }, - Format::Avif => FormatCaps { read: false, write: cfg!(feature = "avif"), lossy: true, ..base }, + Format::Avif => { + FormatCaps { read: cfg!(all(feature = "avif-decode", not(target_arch = "wasm32"))), write: cfg!(feature = "avif"), lossy: true, ..base } + } Format::Heif => { FormatCaps { read: cfg!(feature = "heif"), write: false, depths: &[S::U8, S::U16], icc: true, exif: true, xmp: true, lossy: true, ..base } } diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 6516b9ff2..a4480b2b8 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -106,7 +106,11 @@ pub fn decode_as_with(format: Format, bytes: &[u8], opts: &DecodeOptions) -> Res Format::Heif => heif::decode(bytes, l, opts.keep_orientation), Format::Jp2 => jp2::decode(bytes, l), Format::Jxl => Err(CodecError::unsupported(format, "JPEG XL reading is not yet available; export is supported")), - Format::Gif | Format::Bmp | Format::Tga | Format::Ico | Format::Qoi | Format::Hdr | Format::Avif => via_image::decode(format, bytes, l), + #[cfg(all(feature = "avif-decode", not(target_arch = "wasm32")))] + Format::Avif => codecs::avif_decode::decode(bytes, l, opts.keep_orientation), + #[cfg(not(all(feature = "avif-decode", not(target_arch = "wasm32"))))] + Format::Avif => via_image::decode(format, bytes, l), + Format::Gif | Format::Bmp | Format::Tga | Format::Ico | Format::Qoi | Format::Hdr => via_image::decode(format, bytes, l), }?; finish_format(format, bytes, img, opts) } @@ -163,10 +167,11 @@ fn finish_format(format: Format, bytes: &[u8], mut img: Image, opts: &DecodeOpti } // Turn the pixels upright, like Photoshop: a TIFF records it in the decoded page's own // directory, the others in their EXIF block. The metadata is rewritten to Orientation = 1 - // on the way. HEIF keeps it in its container, and its decoder has already applied it. + // on the way. HEIF and AVIF keep it in their container, and their decoders have already + // applied it. let o = match format { Format::Tiff => tiff::orientation(bytes, None), - Format::Heif => 1, + Format::Heif | Format::Avif => 1, Format::Dpx => dpx::orientation(bytes), Format::Cineon => dpx::cineon_orientation(bytes), _ => img.meta.exif.as_deref().map_or(1, exif_orientation), @@ -195,10 +200,11 @@ pub fn decode_png_rows>( } /// The upright pixel size [`decode`] would return, read from the file's header without decoding -/// pixels, for WebP, OpenEXR (flat) and the GIF/BMP/TGA/ICO/QOI/HDR family. It runs the same +/// pixels, for WebP, OpenEXR (flat), AVIF (with `avif-decode`) and the GIF/BMP/TGA/ICO/QOI/HDR family. It runs the same /// header reads and size checks as the decoder (default [`Limits`]) and swaps the size for an -/// EXIF orientation of 5–8, so wherever [`decode`] succeeds the two agree. Other formats (and -/// deep EXR or AVIF) return [`CodecError::Unsupported`]: decode those to learn their size. +/// EXIF orientation of 5–8 (AVIF: its container's `clap` and `irot`), so wherever [`decode`] +/// succeeds the two agree. Other formats (and deep EXR) return [`CodecError::Unsupported`]: decode +/// those to learn their size. pub fn probe_size(bytes: &[u8]) -> Result<(u32, u32), CodecError> { let format = detect(bytes).ok_or(CodecError::UnknownFormat)?; if !caps(format).read { @@ -208,7 +214,11 @@ pub fn probe_size(bytes: &[u8]) -> Result<(u32, u32), CodecError> { let (w, h, exif) = match format { Format::WebP => webp::probe(bytes, l)?, Format::OpenExr => exr::probe(bytes, l).map(|(w, h)| (w, h, None))?, - Format::Gif | Format::Bmp | Format::Tga | Format::Ico | Format::Qoi | Format::Hdr | Format::Avif => via_image::probe(format, bytes, l)?, + #[cfg(all(feature = "avif-decode", not(target_arch = "wasm32")))] + Format::Avif => codecs::avif_decode::probe(bytes, l).map(|(w, h)| (w, h, None))?, + #[cfg(not(all(feature = "avif-decode", not(target_arch = "wasm32"))))] + Format::Avif => via_image::probe(format, bytes, l)?, + Format::Gif | Format::Bmp | Format::Tga | Format::Ico | Format::Qoi | Format::Hdr => via_image::probe(format, bytes, l)?, _ => return Err(CodecError::unsupported(format, "no header-only size probe")), }; let o = exif.as_deref().map_or(1, exif_orientation); diff --git a/crates/image-codecs/tests/fixtures/avif/README.md b/crates/image-codecs/tests/fixtures/avif/README.md new file mode 100644 index 000000000..b8b3a8c2a --- /dev/null +++ b/crates/image-codecs/tests/fixtures/avif/README.md @@ -0,0 +1,12 @@ +# AVIF decode fixtures + +Small AVIF files from an independent encoder (libaom through FFmpeg 7.1), for `src/codecs/avif_decode.rs`. + +- `quad-source.rgb`: the 33×17 source, raw RGB24 four-colour quadrants (red, green, blue, near-white). +- `quad-420-bt709.avif`: 8-bit 4:2:0, limited range, BT.709 matrix, odd size (FFmpeg leaves the primaries and transfer unspecified): + `ffmpeg -f rawvideo -pix_fmt rgb24 -s 33x17 -i quad-source.rgb -c:v libaom-av1 -crf 12 -still-picture 1 -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc iec61966-2-1 -color_range tv quad-420-bt709.avif` +- `quad-420-bt709.dav1d.yuv`: that file's AV1 picture as libdav1d decodes it, planar 8-bit 4:2:0 (Y, then Cb, then Cr): + `ffmpeg -c:v libdav1d -i quad-420-bt709.avif -f rawvideo -pix_fmt yuv420p quad-420-bt709.dav1d.yuv` +- `quad-444-gbr-lossless.avif`: lossless 8-bit 4:4:4 with the identity (GBR) matrix, full range: + `ffmpeg -f rawvideo -pix_fmt rgb24 -s 33x17 -i quad-source.rgb -c:v libaom-av1 -crf 0 -still-picture 1 -pix_fmt gbrp -colorspace rgb -color_range pc quad-444-gbr-lossless.avif`. + It decodes to `quad-source.rgb` exactly. diff --git a/crates/image-codecs/tests/fixtures/avif/quad-420-bt709.avif b/crates/image-codecs/tests/fixtures/avif/quad-420-bt709.avif new file mode 100644 index 0000000000000000000000000000000000000000..419196cb178743782cf147ea50d111e2b8642d42 GIT binary patch literal 369 zcmZQzU{FXasVqn=%S>Yc0uY^>nP!-qnV9D5Xy^nK`k9+rk_eIm0{x7XoFWL5fuSHX zxdg@r(E&hyX;G?2VqQv4Dp(a?L1sxVSP3JLl*`P?PX_T^7#J9V5JWOCDgx;MAlAst z%mX_CEF%Tvq%r}8LA=B=14HNhoP4mES(ybz1we7{%!1^6AT5$vT#yP<2m~Or1c6wf zAhRM9B*4tU!2zUr63Yyo8yR>&Lc+=UIYoKNITZ{{KnOIQfk8a8AU6@j00N-HSQwd_ zS%A!l+?2!;E=~zih2|6v4i*6;XO{y&vw`U4k2c-I-AWygkL2ynp7_}AP4*4enEOQm q)z5b1%rN?KQ|H$?;i_Mo{+`I#w8y3Pf9fWWdacYc0uY^>nP!-qnV9D5Xy^zO`k9+rk_eIm0{x7XoFWL5fuSHX zxdg@r(E&hyX;G?2VqQv4Dp(a?L1sxVSP3JLl*`P?PX_T^7#J9V5JWOCDgtQ>AlAst z%mX_CEF%Tvq%r}8LA=B=14HNhoP4mES(ybz1we7{%!1^6AT5$vT#yP<2m~Or1c6wf zAhRM9B*4tU!2zUr63Yyo8x?>o1_t5e{G6h^jRAvYzlgp0#MRG~S8BZJXM2k7n(sn>EClKWl Date: Sun, 15 Nov 2026 10:14:40 -0500 Subject: [PATCH 058/349] fix(tga): bound aggregate decoder storage and reserve fallibly --- crates/tga/src/lib.rs | 36 +++++++++++++++++++++++++------- crates/tga/src/metadata_tests.rs | 22 +++++++++---------- crates/tga/src/tests.rs | 33 +++++++++++++++++++++++++++-- 3 files changed, 70 insertions(+), 21 deletions(-) diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index 06a9941a0..5174a8093 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -59,11 +59,13 @@ pub type Result = std::result::Result; pub struct Limits { /// Most pixels (width × height) a picture may have. Default 2^28 (16384 × 16384). pub max_pixels: u64, + /// Maximum combined palette, stored-pixel and RGBA allocation bytes. Default 256 MiB. + pub max_decoded_bytes: usize, } impl Default for Limits { fn default() -> Self { - Self { max_pixels: 1 << 28 } + Self { max_pixels: 1 << 28, max_decoded_bytes: 256 << 20 } } } @@ -313,10 +315,6 @@ pub fn decode(bytes: &[u8], limits: &Limits) -> Result { }; let end = image_data_end(bytes, first_pixel)?; let bytes = bytes.get(..end).ok_or(err("truncated image data"))?; - if let Some(layout) = map_entry { - let map = bytes.get(map_start..first_pixel).ok_or(err("truncated colour map"))?; - palette = map.chunks_exact(layout.bytes()).map(|entry| layout.rgba(entry)).collect(); - } let at = first_pixel; let (stored_as, mapped) = match kind & 7 { 1 => { @@ -335,14 +333,35 @@ pub fn decode(bytes: &[u8], limits: &Limits) -> Result { }; let data = bytes.get(at..).unwrap_or_default(); let bpp = stored_as.bytes(); + let stored_bytes = pixels.checked_mul(bpp).ok_or(Error::LimitExceeded("image size"))?; + let rgba_bytes = pixels.checked_mul(4).ok_or(Error::LimitExceeded("image size"))?; + let palette_bytes = if map_entry.is_some() { map_len * 4 } else { 0 }; + let aggregate = + stored_bytes.checked_add(rgba_bytes).and_then(|n| n.checked_add(palette_bytes)).ok_or(Error::LimitExceeded("decode allocation bytes"))?; + if aggregate > limits.max_decoded_bytes { + return Err(Error::LimitExceeded("decode allocation bytes")); + } + if let Some(layout) = map_entry { + let map = bytes.get(map_start..first_pixel).ok_or(err("truncated colour map"))?; + palette.try_reserve_exact(map_len).map_err(|_| Error::LimitExceeded("allocation failed"))?; + palette.extend(map.chunks_exact(layout.bytes()).map(|entry| layout.rgba(entry))); + } // The stored values, in file order. let stored: Vec = if rle { unpack_rle(data, pixels, bpp)? } else { let n = pixels.checked_mul(bpp).ok_or(Error::LimitExceeded("image size"))?; - data.get(..n).ok_or(err("truncated pixel data"))?.to_vec() + { + let source = data.get(..n).ok_or(err("truncated pixel data"))?; + let mut values = Vec::new(); + values.try_reserve_exact(n).map_err(|_| Error::LimitExceeded("allocation failed"))?; + values.extend_from_slice(source); + values + } }; - let mut rgba = vec![0u8; pixels.checked_mul(4).ok_or(Error::LimitExceeded("image size"))?]; + let mut rgba = Vec::new(); + rgba.try_reserve_exact(rgba_bytes).map_err(|_| Error::LimitExceeded("allocation failed"))?; + rgba.resize(rgba_bytes, 0u8); for (i, v) in stored.chunks_exact(bpp).enumerate().take(pixels) { let (x, y) = (i % w, i / w); let x = if right_to_left { w - 1 - x } else { x }; @@ -386,7 +405,8 @@ fn unpack_rle(mut data: &[u8], pixels: usize, bpp: usize) -> Result> { return Err(short); } let total = pixels.checked_mul(bpp).ok_or(Error::LimitExceeded("image size"))?; - let mut out = Vec::with_capacity(total); + let mut out = Vec::new(); + out.try_reserve_exact(total).map_err(|_| Error::LimitExceeded("allocation failed"))?; while out.len() < total { let (&head, rest) = data.split_first().ok_or(short.clone())?; let count = usize::from(head & 0x7F) + 1; diff --git a/crates/tga/src/metadata_tests.rs b/crates/tga/src/metadata_tests.rs index a5c6c0b12..583f5d691 100644 --- a/crates/tga/src/metadata_tests.rs +++ b/crates/tga/src/metadata_tests.rs @@ -124,7 +124,7 @@ fn importing_truncated_pixels_does_not_consume_tga_footer() { file.extend_from_slice(&offsets); file.extend_from_slice(SIGNATURE); let result = dec(&file); - assert!(matches!(result, Err(_)), "kind {kind}, metadata {metadata:?}: metadata is not a second pixel"); + assert!(result.is_err(), "kind {kind}, metadata {metadata:?}: metadata is not a second pixel"); } } for kind in [1, 9] { @@ -136,7 +136,7 @@ fn importing_truncated_pixels_does_not_consume_tga_footer() { file.extend_from_slice(&[0; 8]); file.extend_from_slice(SIGNATURE); let result = dec(&file); - assert!(matches!(result, Err(_)), "kind {kind}: the footer is not colour-map data"); + assert!(result.is_err(), "kind {kind}: the footer is not colour-map data"); } } @@ -200,7 +200,7 @@ fn preceding_metadata_cannot_supply_missing_pixels() { let mut accepted = Vec::new(); for metadata in 0..4 { let result = dec(&preceding_metadata(false, metadata)); - if !matches!(result, Err(_)) { + if result.is_ok() { accepted.push(metadata); } } @@ -305,7 +305,7 @@ fn malformed_optional_metadata_cannot_supply_missing_pixels() { let footer = file.len() - SIGNATURE.len() - 8; let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; file[directory + 8..directory + 12].copy_from_slice(&u32::MAX.to_le_bytes()); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); // The declared entry count exceeds the bytes before the footer, but the first entry's // payload still precedes the directory and cannot be used as a second pixel. @@ -313,17 +313,17 @@ fn malformed_optional_metadata_cannot_supply_missing_pixels() { let footer = file.len() - SIGNATURE.len() - 8; let directory = u32::from_le_bytes(file[footer + 4..footer + 8].try_into().unwrap()) as usize; file[directory..directory + 2].copy_from_slice(&2u16.to_le_bytes()); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); let mut file = preceding_metadata(false, 2); let footer = file.len() - SIGNATURE.len() - 8; let extension = u32::from_le_bytes(file[footer..footer + 4].try_into().unwrap()) as usize; file[extension..extension + 2].copy_from_slice(&494u16.to_le_bytes()); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); let mut file = preceding_metadata(false, 2); let footer = file.len() - SIGNATURE.len() - 8; file.remove(footer - 1); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); } #[test] @@ -341,7 +341,7 @@ fn valid_developer_directory_with_overlapping_payload_rejects_pixels() { assert_eq!(u32::from_le_bytes(file[moved_footer + 4..moved_footer + 8].try_into().unwrap()), directory as u32); assert_eq!(u16::from_le_bytes(file[directory..directory + 2].try_into().unwrap()), 2); assert_eq!(&file[directory + 12..directory + 22], &extra); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); } #[test] @@ -356,7 +356,7 @@ fn nonempty_developer_reference_inside_pixels_rejects_the_whole_image() { file.extend_from_slice(&0u32.to_le_bytes()); file.extend_from_slice(&directory.to_le_bytes()); file.extend_from_slice(SIGNATURE); - assert!(matches!(dec(&file), Err(_)), "an overlapping reference must not return a partial image"); + assert!(dec(&file).is_err(), "an overlapping reference must not return a partial image"); } #[test] @@ -376,7 +376,7 @@ fn inflated_developer_count_scans_the_next_chunk_as_an_entry_and_rejects_its_pix file.extend_from_slice(&0u32.to_le_bytes()); file.extend_from_slice(&directory.to_le_bytes()); file.extend_from_slice(SIGNATURE); - assert!(matches!(dec(&file), Err(_)), "a scanned entry's payload inside the pixels is refused"); + assert!(dec(&file).is_err(), "a scanned entry's payload inside the pixels is refused"); } #[test] @@ -389,7 +389,7 @@ fn legacy_pixels_that_end_in_signature_at_or_after_the_header_are_read_as_a_foot let mut file = header(3, width, 1, 8, 0x20); file.extend(vec![0; prefix]); file.extend_from_slice(SIGNATURE); - assert!(matches!(dec(&file), Err(_))); + assert!(dec(&file).is_err()); } #[test] diff --git a/crates/tga/src/tests.rs b/crates/tga/src/tests.rs index 06109a179..76472075f 100644 --- a/crates/tga/src/tests.rs +++ b/crates/tga/src/tests.rs @@ -116,8 +116,8 @@ fn hostile_headers_fail_without_allocating() { fn the_pixel_limit_is_checked() { let mut f = header(3, 2, 2, 8, 0); f.extend_from_slice(&[0; 4]); - assert!(decode(&f, &Limits { max_pixels: 4 }).is_ok()); - assert_eq!(decode(&f, &Limits { max_pixels: 3 }), Err(Error::LimitExceeded("pixel count"))); + assert!(decode(&f, &Limits { max_pixels: 4, ..Limits::default() }).is_ok()); + assert_eq!(decode(&f, &Limits { max_pixels: 3, ..Limits::default() }), Err(Error::LimitExceeded("pixel count"))); } #[test] @@ -235,3 +235,32 @@ fn written_files_read_back() { assert_eq!(r.rgba, want, "{layout:?}"); } } + +#[test] +fn aggregate_decode_budget_applies_before_rle_expansion() { + let mut file = header(10, 16, 16, 32, 0x28); + file.extend_from_slice(&[255, 0, 0, 255, 255, 255, 0, 0, 255, 255]); + let mut limits = Limits::default(); + limits.max_decoded_bytes = 2047; + assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); + limits.max_decoded_bytes = 2048; + assert_eq!(decode(&file, &limits).unwrap().rgba.len(), 1024); +} +#[test] +fn default_budget_rejects_large_rle_header_without_large_fixture() { + let file = header(10, 16384, 16384, 32, 0x28); + assert_eq!(decode(&file, &Limits::default()), Err(Error::LimitExceeded("decode allocation bytes"))); +} +#[test] +fn aggregate_decode_budget_counts_raw_and_palette_storage() { + let mut file = header(1, 1, 1, 8, 0x20); + file[1] = 1; + file[5] = 1; + file[7] = 24; + file.extend_from_slice(&[0, 0, 255, 0]); + let mut limits = Limits::default(); + limits.max_decoded_bytes = 8; + assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); + limits.max_decoded_bytes = 9; + assert_eq!(decode(&file, &limits).unwrap().rgba, [255, 0, 0, 255]); +} From a33a81b1f19b348deab1ec5bc3942cb26095e692 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:15:49 -0500 Subject: [PATCH 059/349] test(tga): initialize custom decode limits directly --- crates/tga/src/tests.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/crates/tga/src/tests.rs b/crates/tga/src/tests.rs index 76472075f..887c2915a 100644 --- a/crates/tga/src/tests.rs +++ b/crates/tga/src/tests.rs @@ -240,8 +240,7 @@ fn written_files_read_back() { fn aggregate_decode_budget_applies_before_rle_expansion() { let mut file = header(10, 16, 16, 32, 0x28); file.extend_from_slice(&[255, 0, 0, 255, 255, 255, 0, 0, 255, 255]); - let mut limits = Limits::default(); - limits.max_decoded_bytes = 2047; + let mut limits = Limits { max_decoded_bytes: 2047, ..Limits::default() }; assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); limits.max_decoded_bytes = 2048; assert_eq!(decode(&file, &limits).unwrap().rgba.len(), 1024); @@ -258,8 +257,7 @@ fn aggregate_decode_budget_counts_raw_and_palette_storage() { file[5] = 1; file[7] = 24; file.extend_from_slice(&[0, 0, 255, 0]); - let mut limits = Limits::default(); - limits.max_decoded_bytes = 8; + let mut limits = Limits { max_decoded_bytes: 8, ..Limits::default() }; assert_eq!(decode(&file, &limits), Err(Error::LimitExceeded("decode allocation bytes"))); limits.max_decoded_bytes = 9; assert_eq!(decode(&file, &limits).unwrap().rgba, [255, 0, 0, 255]); From 373d36ea3f66be15b826c861681147e32314b875 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:18:47 +0000 Subject: [PATCH 060/349] Expose bounded stored image dimensions --- crates/image-codecs/src/allocation.rs | 49 +++++++++++++++++++++++++++ crates/image-codecs/src/lib.rs | 2 +- 2 files changed, 50 insertions(+), 1 deletion(-) diff --git a/crates/image-codecs/src/allocation.rs b/crates/image-codecs/src/allocation.rs index fe98122e7..40d55dfc8 100644 --- a/crates/image-codecs/src/allocation.rs +++ b/crates/image-codecs/src/allocation.rs @@ -247,3 +247,52 @@ fn read_le24(bytes: &[u8], at: usize) -> Option { let b = bytes.get(at..at.checked_add(3)?)?; Some(u32::from_le_bytes([b[0], b[1], b[2], 0])) } + +/// Probe the stored dimensions of the first PNG, JPEG, BMP or TIFF image, without decoding +/// pixels or applying orientation. TIFF uses the first directory even if it is a thumbnail. +/// The caller's limits bound both the header decoder and the declared output dimensions. +pub fn probe_stored_size(bytes: &[u8], limits: &crate::Limits) -> Result<(u32, u32), CodecError> { + use std::io::Cursor; + let format = crate::detect(bytes).ok_or(CodecError::UnknownFormat)?; + if !matches!(format, Format::Png | Format::Jpeg | Format::Bmp | Format::Tiff) { + return Err(CodecError::unsupported(format, "stored-size probe is not available for this format")); + } + let mut reader = image::ImageReader::new(Cursor::new(bytes)).with_guessed_format().map_err(|e| CodecError::malformed(format, e))?; + let mut image_limits = image::Limits::default(); + image_limits.max_image_width = Some(limits.max_width); + image_limits.max_image_height = Some(limits.max_height); + image_limits.max_alloc = Some(limits.max_alloc); + reader.limits(image_limits); + let (w, h) = reader.into_dimensions().map_err(|e| CodecError::malformed(format, e))?; + limits.check_size(w, h)?; + Ok((w, h)) +} + +#[cfg(test)] +mod stored_size_tests { + #![allow(clippy::unwrap_used)] + use super::*; + use std::io::Cursor; + + #[test] + fn stored_probe_uses_caller_limits_without_decoding() { + let mut bmp = Cursor::new(Vec::new()); + image::write_buffer_with_format(&mut bmp, &vec![0; 300_000 * 3], 1, 300_000, image::ExtendedColorType::Rgb8, image::ImageFormat::Bmp) + .unwrap(); + let bytes = bmp.into_inner(); + let limits = crate::Limits::new(u32::MAX, u32::MAX, 128_000_000, 2_048_000_000); + assert_eq!(probe_stored_size(&bytes, &limits).unwrap(), (1, 300_000)); + assert!(probe_stored_size(&bytes, &crate::Limits::default()).is_err()); + assert!(probe_stored_size(&bytes[..20], &limits).is_err()); + } + + #[test] + fn common_stored_headers_are_probed() { + let limits = crate::Limits::new(100, 100, 10_000, 1 << 20); + for format in [image::ImageFormat::Png, image::ImageFormat::Jpeg, image::ImageFormat::Bmp, image::ImageFormat::Tiff] { + let mut out = Cursor::new(Vec::new()); + image::write_buffer_with_format(&mut out, &[10; 18], 3, 2, image::ExtendedColorType::Rgb8, format).unwrap(); + assert_eq!(probe_stored_size(&out.into_inner(), &limits).unwrap(), (3, 2), "{format:?}"); + } + } +} diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 6516b9ff2..5cd1b9c60 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -31,7 +31,7 @@ pub mod orientation; pub mod resolution; pub mod source_settings; pub mod web; -pub use crate::allocation::probe_allocation_size; +pub use crate::allocation::{probe_allocation_size, probe_stored_size}; pub use crate::cicp::Cicp; pub use crate::cicp::ContentLightLevel; pub use crate::codecs::avif::{HDR_REFERENCE_WHITE_NITS, HdrTransfer, encode_avif_hdr, encode_avif_with_speed}; From ae5020c1ed922cf7976a3a5545f05b07f466be12 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:23:57 +0000 Subject: [PATCH 061/349] Use a BMP size supported by the baseline decoder --- crates/image-codecs/src/allocation.rs | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/crates/image-codecs/src/allocation.rs b/crates/image-codecs/src/allocation.rs index 40d55dfc8..a31684a33 100644 --- a/crates/image-codecs/src/allocation.rs +++ b/crates/image-codecs/src/allocation.rs @@ -277,12 +277,11 @@ mod stored_size_tests { #[test] fn stored_probe_uses_caller_limits_without_decoding() { let mut bmp = Cursor::new(Vec::new()); - image::write_buffer_with_format(&mut bmp, &vec![0; 300_000 * 3], 1, 300_000, image::ExtendedColorType::Rgb8, image::ImageFormat::Bmp) - .unwrap(); + image::write_buffer_with_format(&mut bmp, &vec![0; 60_000 * 3], 1, 60_000, image::ExtendedColorType::Rgb8, image::ImageFormat::Bmp).unwrap(); let bytes = bmp.into_inner(); let limits = crate::Limits::new(u32::MAX, u32::MAX, 128_000_000, 2_048_000_000); - assert_eq!(probe_stored_size(&bytes, &limits).unwrap(), (1, 300_000)); - assert!(probe_stored_size(&bytes, &crate::Limits::default()).is_err()); + assert_eq!(probe_stored_size(&bytes, &limits).unwrap(), (1, 60_000)); + assert!(probe_stored_size(&bytes, &crate::Limits::new(u32::MAX, 50_000, u64::MAX, 2_048_000_000)).is_err()); assert!(probe_stored_size(&bytes[..20], &limits).is_err()); } From 7b51909d40deb15397ec90695dc611bde5d13e34 Mon Sep 17 00:00:00 2001 From: Francesco BV Date: Sun, 15 Nov 2026 10:28:08 -0500 Subject: [PATCH 062/349] shx: preserve CADCraft shape compiler and errors Original source by Francesco BV in cadcraft52c1e6de, copied from main7064a685. App font lookup, text layout and glyph interpretation are not moved. --- crates/shx/src/compile.rs | 313 ++++++++++++++++++++++++++++++++++++++ crates/shx/src/error.rs | 29 ++++ 2 files changed, 342 insertions(+) create mode 100644 crates/shx/src/compile.rs create mode 100644 crates/shx/src/error.rs diff --git a/crates/shx/src/compile.rs b/crates/shx/src/compile.rs new file mode 100644 index 000000000..2e8cb3c25 --- /dev/null +++ b/crates/shx/src/compile.rs @@ -0,0 +1,313 @@ +//! Shape source (`.shp`) to a compiled SHX file, as COMPILE does. +//! +//! A source is a list of definitions: a header line `*number,defbytes,NAME` followed by its +//! specification bytes (on as many lines as needed, ending with 0). Numbers are decimal, or +//! hexadecimal after a leading `0` (`012`, `08cfb`); parentheses only group; `;` starts a +//! comment. A big font starts with `*BIGFONT nchars,nranges,first,last,…` and a Unicode font +//! with `*UNIFONT,6,name` followed by `above,below,modes,encoding,type,0`. Shape 0 is a text +//! font's record (`above,below,modes,0`). +//! +//! Operands are encoded by what they are: a subshape number takes two bytes in a Unicode font +//! (and after `7,0` in a big font), displacements and bulges are two's complement, and an arc's +//! direction byte (`-043`) keeps its sign in the high bit. `defbytes` is not checked: the +//! program's own length is written. + +use super::ShxError; +use super::parse::{BIGFONT, SHAPES_10, UNIFONT}; + +/// Largest source compiled. +const MAX_SOURCE: usize = 8 << 20; + +#[derive(Clone, Copy, PartialEq)] +enum Kind { + Shapes, + Big, + Uni, +} + +struct Shape { + number: u16, + name: String, + program: Vec, +} + +/// A number token: value (sign included). +fn number(tok: &str, line: usize) -> Result { + let t: String = tok.chars().filter(|c| !matches!(c, '(' | ')') && !c.is_whitespace()).collect(); + let (neg, digits) = match t.strip_prefix('-') { + Some(d) => (true, d), + None => (false, t.strip_prefix('+').unwrap_or(&t)), + }; + let err = || ShxError::Source(line, format!("not a number: {tok:?}")); + let v = if digits.len() > 1 && digits.starts_with('0') { + i64::from_str_radix(digits.get(1..).unwrap_or_default(), 16).map_err(|_| err())? + } else { + digits.parse::().map_err(|_| err())? + }; + if v > 0xFFFF { + return Err(err()); + } + Ok(if neg { -v } else { v }) +} + +/// The comma-separated numbers of a line (comment removed, blank fields skipped). +fn numbers(text: &str, line: usize) -> Result, ShxError> { + text.split(',').map(str::trim).filter(|t| !t.is_empty() && *t != "(" && *t != ")").map(|t| number(t, line)).collect() +} + +/// The spec-byte encoder: walks the tokens as the reader walks the bytes. +struct Enc<'a> { + toks: &'a [i64], + i: usize, + out: Vec, + kind: Kind, + line: usize, +} + +impl Enc<'_> { + fn next(&mut self) -> Result { + let v = self.toks.get(self.i).copied().ok_or_else(|| ShxError::Source(self.line, "the shape ends inside a command".into()))?; + self.i += 1; + Ok(v) + } + fn byte(&mut self) -> Result<(), ShxError> { + let v = self.next()?; + let b = u8::try_from(v).map_err(|_| ShxError::Source(self.line, format!("{v} is not a byte")))?; + self.out.push(b); + Ok(()) + } + /// Two's complement −128..127. + fn signed(&mut self) -> Result { + let v = self.next()?; + let b = i8::try_from(v).map_err(|_| ShxError::Source(self.line, format!("{v} is not −128..127")))?; + self.out.extend(b.to_le_bytes()); + Ok(v) + } + /// Sign in the high bit (an arc's direction byte). + fn sign_magnitude(&mut self) -> Result<(), ShxError> { + let v = self.next()?; + let m = u8::try_from(v.unsigned_abs()) + .ok() + .filter(|m| *m < 0x80) + .ok_or_else(|| ShxError::Source(self.line, format!("{v} is not an octant byte")))?; + self.out.push(if v < 0 { m | 0x80 } else { m }); + Ok(()) + } + fn word(&mut self) -> Result<(), ShxError> { + let v = self.next()?; + let w = u16::try_from(v).map_err(|_| ShxError::Source(self.line, format!("{v} is not a shape number")))?; + self.out.extend(w.to_be_bytes()); + Ok(()) + } + + fn program(mut self) -> Result, ShxError> { + while self.i < self.toks.len() { + let code = self.next()?; + let c = u8::try_from(code).map_err(|_| ShxError::Source(self.line, format!("{code} is not a code")))?; + self.out.push(c); + match c { + 0 => break, + 3 | 4 => self.byte()?, + 7 => match self.kind { + Kind::Uni => self.word()?, + Kind::Big => { + let first = self.toks.get(self.i).copied().unwrap_or(0); + if first == 0 { + self.byte()?; + self.word()?; + for _ in 0..4 { + self.byte()?; + } + } else { + self.byte()?; + } + } + Kind::Shapes => self.byte()?, + }, + 8 => { + self.signed()?; + self.signed()?; + } + 9 => loop { + let (x, y) = (self.signed()?, self.signed()?); + if x == 0 && y == 0 { + break; + } + }, + 10 => { + self.byte()?; + self.sign_magnitude()?; + } + 11 => { + for _ in 0..4 { + self.byte()?; + } + self.sign_magnitude()?; + } + 12 => { + for _ in 0..3 { + self.signed()?; + } + } + 13 => loop { + let (x, y) = (self.signed()?, self.signed()?); + if x == 0 && y == 0 { + break; + } + self.signed()?; + }, + _ => {} + } + } + if self.out.last() != Some(&0) { + self.out.push(0); + } + Ok(self.out) + } +} + +/// Compile shape source into an SHX file (a shape file or text font, a big font, or a Unicode +/// font, as its first definition says). +pub fn compile(source: &str) -> Result, ShxError> { + if source.len() > MAX_SOURCE { + return Err(ShxError::TooLarge); + } + let mut kind = Kind::Shapes; + let mut ranges: Vec<(u16, u16)> = Vec::new(); + let mut uni_info: Option<(String, Vec)> = None; + // Definitions: header (number, name, line) and the numbers that follow it. + let mut defs: Vec<(i64, String, usize, Vec)> = Vec::new(); + let mut uni_header_pending = false; + for (no, raw) in source.lines().enumerate() { + let line = no + 1; + let text = raw.split(';').next().unwrap_or_default().trim(); + if text.is_empty() { + continue; + } + if let Some(head) = text.strip_prefix('*') { + let upper = head.trim_start().to_ascii_uppercase(); + if let Some(rest) = upper.strip_prefix("BIGFONT") { + kind = Kind::Big; + let v = numbers(rest, line)?; + let n = usize::try_from(v.get(1).copied().unwrap_or(0)).unwrap_or(0); + for k in 0..n { + let lo = v.get(2 + 2 * k).copied().unwrap_or(0); + let hi = v.get(3 + 2 * k).copied().unwrap_or(lo); + let to = |x: i64| u16::try_from(x).map_err(|_| ShxError::Source(line, "bad escape range".into())); + ranges.push((to(lo)?, to(hi)?)); + } + continue; + } + if upper.starts_with("UNIFONT") { + kind = Kind::Uni; + let name = head.splitn(3, ',').nth(2).unwrap_or_default().trim().to_string(); + uni_info = Some((name, Vec::new())); + uni_header_pending = true; + continue; + } + uni_header_pending = false; + let mut parts = head.splitn(3, ','); + let num = number(parts.next().unwrap_or_default().trim(), line)?; + let _defbytes = parts.next(); + let name = parts.next().unwrap_or_default().trim().to_string(); + defs.push((num, name, line, Vec::new())); + continue; + } + let v = numbers(text, line)?; + if uni_header_pending { + if let Some((_, info)) = uni_info.as_mut() { + for x in v { + info.push(u8::try_from(x).map_err(|_| ShxError::Source(line, "bad font record".into()))?); + } + } + continue; + } + match defs.last_mut() { + Some(d) => d.3.extend(v), + None => return Err(ShxError::Source(line, "specification bytes before any *number,defbytes,NAME line".into())), + } + } + let mut shapes: Vec = Vec::new(); + for (num, name, line, toks) in defs { + let number = u16::try_from(num).map_err(|_| ShxError::Source(line, format!("shape number {num} out of range")))?; + let program = if number == 0 { + // The font record: plain bytes. + toks.iter().map(|x| u8::try_from(*x).map_err(|_| ShxError::Source(line, "bad font record".into()))).collect::, _>>()? + } else { + Enc { toks: &toks, i: 0, out: Vec::new(), kind, line }.program()? + }; + if shapes.iter().any(|s| s.number == number) { + return Err(ShxError::Source(line, format!("shape {number} is defined twice"))); + } + shapes.push(Shape { number, name, program }); + } + if shapes.is_empty() { + return Err(ShxError::Empty); + } + shapes.sort_by_key(|s| s.number); + let record = |s: &Shape| -> Result, ShxError> { + let mut r: Vec = s.name.bytes().filter(|b| *b != 0).collect(); + r.push(0); + r.extend(&s.program); + if r.len() > usize::from(u16::MAX) { Err(ShxError::TooLarge) } else { Ok(r) } + }; + let count = u16::try_from(shapes.len()).map_err(|_| ShxError::TooLarge)?; + let len16 = |r: &[u8]| u16::try_from(r.len()).unwrap_or(u16::MAX); + let mut out = Vec::new(); + match kind { + Kind::Shapes => { + out.extend(SHAPES_10); + out.extend(shapes.first().map_or(0, |s| s.number).to_le_bytes()); + out.extend(shapes.last().map_or(0, |s| s.number).to_le_bytes()); + out.extend(count.to_le_bytes()); + let recs: Vec> = shapes.iter().map(record).collect::>()?; + for (s, r) in shapes.iter().zip(&recs) { + out.extend(s.number.to_le_bytes()); + out.extend(len16(r).to_le_bytes()); + } + for r in &recs { + out.extend(r); + } + out.extend(b"EOF"); + } + Kind::Big => { + out.extend(BIGFONT); + let nranges = u16::try_from(ranges.len()).map_err(|_| ShxError::TooLarge)?; + out.extend(count.to_le_bytes()); + out.extend(count.to_le_bytes()); + out.extend(nranges.to_le_bytes()); + for (lo, hi) in &ranges { + out.extend(lo.to_le_bytes()); + out.extend(hi.to_le_bytes()); + } + let recs: Vec> = shapes.iter().map(record).collect::>()?; + let mut off = out.len() + 8 * recs.len(); + for (s, r) in shapes.iter().zip(&recs) { + out.extend(s.number.to_le_bytes()); + out.extend(len16(r).to_le_bytes()); + out.extend(u32::try_from(off).map_err(|_| ShxError::TooLarge)?.to_le_bytes()); + off += r.len(); + } + for r in &recs { + out.extend(r); + } + } + Kind::Uni => { + out.extend(UNIFONT); + let (name, info) = uni_info.unwrap_or_default(); + out.extend((u32::from(count) + 1).to_le_bytes()); + let mut rec: Vec = name.bytes().filter(|b| *b != 0).collect(); + rec.push(0); + rec.extend(&info); + out.extend(len16(&rec).to_le_bytes()); + out.extend(&rec); + for s in &shapes { + let r = record(s)?; + out.extend(s.number.to_le_bytes()); + out.extend(len16(&r).to_le_bytes()); + out.extend(r); + } + } + } + Ok(out) +} diff --git a/crates/shx/src/error.rs b/crates/shx/src/error.rs new file mode 100644 index 000000000..0addd1c98 --- /dev/null +++ b/crates/shx/src/error.rs @@ -0,0 +1,29 @@ +/// Why a font file can't be read or a shape source can't be compiled. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum ShxError { + /// Not an SHX file (unknown signature). + NotShx, + /// The file ends inside its header or index. + Truncated, + /// The file is larger, or has more of something, than CADCraft reads. + TooLarge, + /// The file is well-formed but holds no shape. + Empty, + /// Shape source error: line and message. + Source(usize, String), +} + +impl std::fmt::Display for ShxError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + ShxError::NotShx => f.write_str("not an SHX shape or font file"), + ShxError::Truncated => f.write_str("the SHX file is truncated"), + ShxError::TooLarge => f.write_str("the SHX file is too large"), + ShxError::Empty => f.write_str("the SHX file has no shapes"), + ShxError::Source(line, msg) => write!(f, "line {line}: {msg}"), + } + } +} + +impl std::error::Error for ShxError {} + From b3307f7814629961841b80ab907116252e41b34d Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:30:48 -0500 Subject: [PATCH 063/349] shx: expose shared bounded shape compiler with hostile-source tests --- Cargo.lock | 4 ++++ Cargo.toml | 1 + crates/shx/Cargo.toml | 11 +++++++++++ crates/shx/README.md | 8 ++++++++ crates/shx/src/compile.rs | 20 +++++++++++++++++--- crates/shx/src/error.rs | 1 - crates/shx/src/lib.rs | 8 ++++++++ crates/shx/tests/compiler.rs | 30 ++++++++++++++++++++++++++++++ 8 files changed, 79 insertions(+), 4 deletions(-) create mode 100644 crates/shx/Cargo.toml create mode 100644 crates/shx/README.md create mode 100644 crates/shx/src/lib.rs create mode 100644 crates/shx/tests/compiler.rs diff --git a/Cargo.lock b/Cargo.lock index add90f8c2..3e9aeba59 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2610,6 +2610,10 @@ dependencies = [ name = "craft-sheet" version = "0.1.0" +[[package]] +name = "craft-shx" +version = "0.1.0" + [[package]] name = "craft-silhouette-studio" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index eae758e17..b68880781 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,7 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-shx = { path = "crates/shx" } craft-smime = { path = "crates/smime" } craft-ber = { path = "crates/ber" } craft-proto = { path = "crates/proto" } diff --git a/crates/shx/Cargo.toml b/crates/shx/Cargo.toml new file mode 100644 index 000000000..012f9d2f9 --- /dev/null +++ b/crates/shx/Cargo.toml @@ -0,0 +1,11 @@ +[package] +name = "craft-shx" +description = "Bounded SHP shape-source compiler for SHX shape, big-font and Unicode containers" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true diff --git a/crates/shx/README.md b/crates/shx/README.md new file mode 100644 index 000000000..691890447 --- /dev/null +++ b/crates/shx/README.md @@ -0,0 +1,8 @@ +# craft-shx + +Compiles SHP shape source into SHX shapes, big-font and Unicode containers. +Extracted from CADCraft by Francesco BV (cadcraft52c1e6de); no font assets are bundled. +App font discovery, text layout and glyph interpretation are not part of this crate. +The original 8 MiB source and u16 record bounds remain; malformed double signs, +excess escape ranges and oversized Unicode font records are refused. Duplicate +shape detection is linear rather than a repeated whole-list scan. diff --git a/crates/shx/src/compile.rs b/crates/shx/src/compile.rs index 2e8cb3c25..0d91a9545 100644 --- a/crates/shx/src/compile.rs +++ b/crates/shx/src/compile.rs @@ -13,7 +13,9 @@ //! program's own length is written. use super::ShxError; -use super::parse::{BIGFONT, SHAPES_10, UNIFONT}; +const SHAPES_10: &[u8] = b"AutoCAD-86 shapes 1.0\r\n\x1a"; +const BIGFONT: &[u8] = b"AutoCAD-86 bigfont 1.0\r\n\x1a"; +const UNIFONT: &[u8] = b"AutoCAD-86 unifont 1.0\r\n\x1a"; /// Largest source compiled. const MAX_SOURCE: usize = 8 << 20; @@ -44,7 +46,7 @@ fn number(tok: &str, line: usize) -> Result { } else { digits.parse::().map_err(|_| err())? }; - if v > 0xFFFF { + if !(0..=0xFFFF).contains(&v) { return Err(err()); } Ok(if neg { -v } else { v }) @@ -190,6 +192,11 @@ pub fn compile(source: &str) -> Result, ShxError> { kind = Kind::Big; let v = numbers(rest, line)?; let n = usize::try_from(v.get(1).copied().unwrap_or(0)).unwrap_or(0); + // A big font has byte-valued lead ranges. Bound repeated headers too, + // so a tiny declaration cannot amplify into millions of ranges. + if n > 256 || ranges.len().saturating_add(n) > 256 { + return Err(ShxError::TooLarge); + } for k in 0..n { let lo = v.get(2 + 2 * k).copied().unwrap_or(0); let hi = v.get(3 + 2 * k).copied().unwrap_or(lo); @@ -210,6 +217,9 @@ pub fn compile(source: &str) -> Result, ShxError> { let num = number(parts.next().unwrap_or_default().trim(), line)?; let _defbytes = parts.next(); let name = parts.next().unwrap_or_default().trim().to_string(); + if defs.len() >= usize::from(u16::MAX) { + return Err(ShxError::TooLarge); + } defs.push((num, name, line, Vec::new())); continue; } @@ -228,6 +238,7 @@ pub fn compile(source: &str) -> Result, ShxError> { } } let mut shapes: Vec = Vec::new(); + let mut seen = std::collections::HashSet::new(); for (num, name, line, toks) in defs { let number = u16::try_from(num).map_err(|_| ShxError::Source(line, format!("shape number {num} out of range")))?; let program = if number == 0 { @@ -236,7 +247,7 @@ pub fn compile(source: &str) -> Result, ShxError> { } else { Enc { toks: &toks, i: 0, out: Vec::new(), kind, line }.program()? }; - if shapes.iter().any(|s| s.number == number) { + if !seen.insert(number) { return Err(ShxError::Source(line, format!("shape {number} is defined twice"))); } shapes.push(Shape { number, name, program }); @@ -296,6 +307,9 @@ pub fn compile(source: &str) -> Result, ShxError> { out.extend(UNIFONT); let (name, info) = uni_info.unwrap_or_default(); out.extend((u32::from(count) + 1).to_le_bytes()); + if name.len().saturating_add(1).saturating_add(info.len()) > usize::from(u16::MAX) { + return Err(ShxError::TooLarge); + } let mut rec: Vec = name.bytes().filter(|b| *b != 0).collect(); rec.push(0); rec.extend(&info); diff --git a/crates/shx/src/error.rs b/crates/shx/src/error.rs index 0addd1c98..135214f54 100644 --- a/crates/shx/src/error.rs +++ b/crates/shx/src/error.rs @@ -26,4 +26,3 @@ impl std::fmt::Display for ShxError { } impl std::error::Error for ShxError {} - diff --git a/crates/shx/src/lib.rs b/crates/shx/src/lib.rs new file mode 100644 index 000000000..e595e90f5 --- /dev/null +++ b/crates/shx/src/lib.rs @@ -0,0 +1,8 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] +//! SHP source compilation to SHX containers, extracted from CADCraft. +//! Font discovery, glyph execution and text layout remain consumer responsibilities. +mod compile; +mod error; +pub use compile::compile; +pub use error::ShxError; diff --git a/crates/shx/tests/compiler.rs b/crates/shx/tests/compiler.rs new file mode 100644 index 000000000..f558e185a --- /dev/null +++ b/crates/shx/tests/compiler.rs @@ -0,0 +1,30 @@ +use craft_shx::{ShxError, compile}; + +#[test] +fn fixed_shape_bytes() { + let b = compile("*65,2,A\n010,0\n").unwrap(); + let mut expected = b"AutoCAD-86 shapes 1.0\r\n\x1a".to_vec(); + expected.extend([65, 0, 65, 0, 1, 0, 65, 0, 4, 0, b'A', 0, 0x10, 0]); + expected.extend(b"EOF"); + assert_eq!(b, expected); +} +#[test] +fn hostile_sources_are_refused() { + for src in [ + "*1,2,X\n7\n", + "*1,2,X\n9,(1,1)\n", + "*99999,1,X\n0\n", + "*1,1,X\n300,0\n", + "010,0\n", + "*1,1,X\n1,0zz,0\n", + "*1,1,X\n0\n*1,1,Y\n0\n", + "*--9223372036854775808,1,X\n0", + "*BIGFONT 1,65535\n*1,1,X\n0", + ] { + assert!(compile(src).is_err(), "{src:?}"); + } + assert_eq!(compile(""), Err(ShxError::Empty)); + assert_eq!(compile(&" ".repeat((8 << 20) + 1)), Err(ShxError::TooLarge)); + let oversized_header = format!("*UNIFONT,6,{}\n10,2,0,0,0,0\n*65,1,A\n0", "n".repeat(65536)); + assert_eq!(compile(&oversized_header), Err(ShxError::TooLarge)); +} From 8e394d43faae421541892945cc56f10e47ee3be7 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:39:42 +0000 Subject: [PATCH 064/349] audio: share bounded range-backed WAV PCM access --- crates/audio/src/lib.rs | 3 + crates/audio/src/wav_range.rs | 218 ++++++++++++++++++++++++++++++++++ 2 files changed, 221 insertions(+) create mode 100644 crates/audio/src/wav_range.rs diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..8681ce6d8 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -66,6 +66,9 @@ mod wav; feature = "vorbis-encode" ))] mod write; + +/// Range-backed PCM WAVE access and a 16-bit PCM writer. +pub mod wav_range; #[cfg(feature = "vorbis-encode")] pub use write::{OGG_BITRATES, encode_ogg}; diff --git a/crates/audio/src/wav_range.rs b/crates/audio/src/wav_range.rs new file mode 100644 index 000000000..1ced4fb78 --- /dev/null +++ b/crates/audio/src/wav_range.rs @@ -0,0 +1,218 @@ +//! Range-backed PCM WAVE reader and canonical 16-bit writer. +//! +//! Reads chunk headers and only the requested sample range; it never loads a whole file. + +use crate::{AudioError, Result}; +use craft_media::ByteSource; + +const MAX_CHUNKS: usize = 1 << 16; +const IXML_MAX: u64 = 1 << 20; +/// Maximum sample data returned by a single range read. +pub const MAX_RANGE_BYTES: u64 = 4 << 20; + +fn le16(b: &[u8], o: usize) -> u16 { + b.get(o..o.saturating_add(2)).and_then(|s| s.try_into().ok()).map_or(0, u16::from_le_bytes) +} +fn le32(b: &[u8], o: usize) -> u32 { + b.get(o..o.saturating_add(4)).and_then(|s| s.try_into().ok()).map_or(0, u32::from_le_bytes) +} +fn read_range(source: &impl ByteSource, off: u64, len: usize) -> Result> { + let mut bytes = vec![0; len]; + source.read_at(off, &mut bytes)?; + Ok(bytes) +} + +/// A PCM WAVE file held by an arbitrary random-access source. +pub struct WavRange { + source: S, + /// Number of complete sample frames. + pub frames: u64, + /// Channel count. + pub channels: u16, + /// Sample rate in Hz. + pub rate: u32, + /// Container bits per sample. + pub bits: u16, + /// Whether samples are floating point. + pub float: bool, + /// BWF time reference in samples, from bext or iXML. + pub time_reference: Option, + data_off: u64, +} + +impl WavRange { + /// Open with caller-selected bounds on channel count and sample rate. + pub fn open(source: S, max_channels: u32, max_rate: u32) -> Result { + let len = source.len(); + let mut pos: u64 = 12; + let mut fmt = None; + let mut data = None; + let mut bext_tr = None; + let mut ixml_tr = None; + let mut ds64_data = None; + for _ in 0..MAX_CHUNKS { + let Some(body) = pos.checked_add(8).filter(|&b| b <= len) else { break }; + let mut hdr = [0u8; 8]; + source.read_at(pos, &mut hdr)?; + let id = &hdr[0..4]; + let mut clen = u64::from(le32(&hdr, 4)); + let rest = len - body; + if id == b"data" { + if clen == 0xFFFF_FFFF { + clen = ds64_data.unwrap_or(rest); + } + clen = clen.min(rest); + } + if clen > rest { + break; + } + match id { + b"fmt " if clen >= 16 => { + let b = read_range(&source, body, clen.min(40) as usize)?; + let mut tag = le16(&b, 0); + if tag == 0xFFFE && clen >= 40 { + tag = le16(&b, 24); + } + fmt = Some((tag, le16(&b, 2), le32(&b, 4), le16(&b, 14))); + } + b"ds64" if clen >= 16 => { + let b = read_range(&source, body + 8, 8)?; + ds64_data = Some(u64::from(le32(&b, 0)) | u64::from(le32(&b, 4)) << 32); + } + b"data" => data = Some((body, clen)), + b"bext" if clen >= 346 => { + let b = read_range(&source, body + 338, 8)?; + bext_tr = Some(u64::from(le32(&b, 0)) | u64::from(le32(&b, 4)) << 32); + } + b"iXML" => { + let b = read_range(&source, body, clen.min(IXML_MAX) as usize)?; + ixml_tr = ixml_time_reference(&b); + } + _ => {} + } + pos = body.saturating_add(clen).saturating_add(clen & 1); + } + let (tag, channels, rate, bits) = fmt.ok_or_else(|| AudioError::Malformed("missing fmt chunk".into()))?; + let (data_off, dlen) = data.ok_or_else(|| AudioError::Malformed("missing data chunk".into()))?; + let float = tag == 3; + if !(tag == 1 || float) + || channels == 0 + || rate == 0 + || u32::from(channels) > max_channels + || rate > max_rate + || !matches!(bits, 8 | 16 | 24 | 32 | 64) + { + return Err(AudioError::Unsupported(format!("WAV format tag {tag}, {bits} bits"))); + } + let frames = dlen / (u64::from(channels) * u64::from(bits / 8)); + Ok(Self { source, frames, channels, rate, bits, float, time_reference: bext_tr.or(ixml_tr), data_off }) + } + /// Bytes in one whole frame. + pub fn frame_bytes(&self) -> usize { + usize::from(self.channels) * usize::from(self.bits / 8) + } + /// Read the inclusive range of frames, capped to prevent unbounded allocation. + pub fn read_frames(&self, first: u64, last: u64) -> Result> { + if first > last || last >= self.frames { + return Err(AudioError::Malformed("WAV frame range outside data".into())); + } + let n = (last - first + 1).saturating_mul(self.frame_bytes() as u64); + if n > MAX_RANGE_BYTES { + return Err(AudioError::TooLarge("WAV frame range".into())); + } + let off = self.data_off.saturating_add(first.saturating_mul(self.frame_bytes() as u64)); + read_range(&self.source, off, n as usize) + } + /// Decode a channel from a buffer returned by `read_frames`. + pub fn sample(&self, block: &[u8], frame: usize, ch: usize) -> f32 { + if ch >= usize::from(self.channels) { + return 0.0; + } + let bps = usize::from(self.bits / 8); + let Some(o) = frame.checked_mul(usize::from(self.channels)).and_then(|v| v.checked_add(ch)).and_then(|v| v.checked_mul(bps)) else { + return 0.0; + }; + let Some(b) = block.get(o..o.saturating_add(bps)) else { return 0.0 }; + match (self.bits, self.float, b) { + (8, _, &[a]) => (a as f32 - 128.0) / 128.0, + (16, _, &[a, b]) => i16::from_le_bytes([a, b]) as f32 / 32768.0, + (24, _, &[a, b, c]) => (i32::from_le_bytes([0, a, b, c]) >> 8) as f32 / 8_388_608.0, + (32, false, &[a, b, c, d]) => i32::from_le_bytes([a, b, c, d]) as f32 / 2_147_483_648.0, + (32, true, &[a, b, c, d]) => f32::from_le_bytes([a, b, c, d]), + (64, true, b) => f64::from_le_bytes(b.try_into().unwrap_or([0; 8])) as f32, + _ => 0.0, + } + } +} + +fn ixml_time_reference(x: &[u8]) -> Option { + let text = String::from_utf8_lossy(x); + let field = |tag: &str| -> Option { + let open = format!("<{tag}>"); + let a = text.find(&open)? + open.len(); + let b = a + text[a..].find('<')?; + text[a..b].trim().parse().ok() + }; + let low = field("BWF_TIME_REFERENCE_LOW")?; + Some(low | field("BWF_TIME_REFERENCE_HIGH").unwrap_or(0) << 32) +} + +/// Write interleaved samples as 16-bit PCM WAVE, using symmetric 32767 scaling. +#[cfg(feature = "pcm-encode")] +pub fn write_wav16(samples: &[f32], channels: u16, rate: u32) -> Vec { + let data_len = samples.len().saturating_mul(2); + let mut v = crate::pcm_wav_header(u32::try_from(data_len).unwrap_or(u32::MAX), channels, rate, 16); + v.reserve(data_len); + for s in samples { + v.extend_from_slice(&((s.clamp(-1.0, 1.0) * 32767.0).round() as i16).to_le_bytes()); + } + v +} + +#[cfg(all(test, feature = "pcm-encode"))] +mod tests { + use super::*; + use std::sync::{Arc, Mutex}; + + struct Source { + bytes: Vec, + reads: Arc>>, + } + impl ByteSource for Source { + fn len(&self) -> u64 { + self.bytes.len() as u64 + } + fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { + self.reads.lock().unwrap().push((offset, buf.len())); + self.bytes.read_at(offset, buf) + } + } + #[test] + fn bounded_reads_and_pcm_values() { + let bytes = write_wav16(&[-1.0, -0.5, 0.0, 0.5, 1.0], 1, 48_000); + let reads = Arc::new(Mutex::new(Vec::new())); + let wav = WavRange::open(Source { bytes, reads: reads.clone() }, 64, 384_000).unwrap(); + assert_eq!((wav.frames, wav.channels, wav.rate, wav.bits), (5, 1, 48_000, 16)); + assert!(reads.lock().unwrap().iter().all(|(_, n)| *n <= 40)); + let data = wav.read_frames(1, 3).unwrap(); + assert_eq!(wav.sample(&data, 0, 0), -0.5); + assert_eq!(wav.sample(&data, 2, 0), 0.5); + assert!(wav.read_frames(0, 5).is_err()); + assert!(wav.read_frames(3, 1).is_err()); + assert_eq!(reads.lock().unwrap().last(), Some(&(46, 6))); + } + #[test] + fn ixml_fallback_accepts_flat_fields() { + let base = write_wav16(&[0.0], 1, 48_000); + let mut bytes = base[..36].to_vec(); + let xml = b"51"; + bytes.extend_from_slice(b"iXML"); + bytes.extend_from_slice(&(xml.len() as u32).to_le_bytes()); + bytes.extend_from_slice(xml); + if xml.len() % 2 != 0 { + bytes.push(0); + } + bytes.extend_from_slice(&base[36..]); + assert_eq!(WavRange::open(bytes.as_slice(), 64, 384_000).unwrap().time_reference, Some((1 << 32) + 5)); + } +} From badb7904116d518ad84ff1da5a1d99d3cc5e584f Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:40:02 +0000 Subject: [PATCH 065/349] audio: expose WAV signature detection --- crates/audio/src/wav_range.rs | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/crates/audio/src/wav_range.rs b/crates/audio/src/wav_range.rs index 1ced4fb78..d8aea0d54 100644 --- a/crates/audio/src/wav_range.rs +++ b/crates/audio/src/wav_range.rs @@ -5,6 +5,11 @@ use crate::{AudioError, Result}; use craft_media::ByteSource; +/// Whether a prefix identifies a RIFF or RF64 WAVE file. +pub fn sniff(b: &[u8]) -> bool { + b.len() >= 12 && (&b[0..4] == b"RIFF" || &b[0..4] == b"RF64") && &b[8..12] == b"WAVE" +} + const MAX_CHUNKS: usize = 1 << 16; const IXML_MAX: u64 = 1 << 20; /// Maximum sample data returned by a single range read. From ac037cd9413e32fd16e0103628485f7eb011abfa Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:46:32 +0000 Subject: [PATCH 066/349] aaf: expose bounded Bento container access --- crates/aaf/src/omf.rs | 2 +- crates/aaf/src/omf/bento.rs | 25 ++++++++++++++++++------- crates/aaf/tests/bento_api.rs | 17 +++++++++++++++++ 3 files changed, 36 insertions(+), 8 deletions(-) create mode 100644 crates/aaf/tests/bento_api.rs diff --git a/crates/aaf/src/omf.rs b/crates/aaf/src/omf.rs index 57e0f756c..bbd2e8571 100644 --- a/crates/aaf/src/omf.rs +++ b/crates/aaf/src/omf.rs @@ -21,7 +21,7 @@ //! transition's name) are not in the specification; they were first written by FilmCraft and keep //! their names so that existing files read back. -pub(crate) mod bento; +pub mod bento; mod read; mod write; diff --git a/crates/aaf/src/omf/bento.rs b/crates/aaf/src/omf/bento.rs index 00a7e2a26..171196fe1 100644 --- a/crates/aaf/src/omf/bento.rs +++ b/crates/aaf/src/omf/bento.rs @@ -35,8 +35,8 @@ use std::collections::{BTreeMap, HashMap}; -pub(crate) const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; -pub(crate) const LABEL_SIZE: usize = 24; +pub const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; +pub const LABEL_SIZE: usize = 24; // standard object ids const TOC_OBJECT: u32 = 1; @@ -82,7 +82,7 @@ const MAX_VALUE_BYTES: usize = 16 << 20; const MAX_NAME_BYTES: usize = 4 << 20; /// Builds a Bento container. -pub(crate) struct Writer { +pub struct Writer { data: Vec, names: HashMap<(u32, String), u32>, next: u32, @@ -90,6 +90,12 @@ pub(crate) struct Writer { entries: Vec<(u32, u32, u32, Vec)>, } +impl Default for Writer { + fn default() -> Self { + Self::new() + } +} + impl Writer { pub fn new() -> Writer { Writer { data: Vec::new(), names: HashMap::new(), next: MIN_USER_ID, entries: Vec::new() } @@ -217,9 +223,9 @@ pub(crate) struct Prop { } /// A parsed Bento container. -pub(crate) struct Container<'a> { +pub struct Container<'a> { data: &'a [u8], - pub objects: BTreeMap>, + pub(crate) objects: BTreeMap>, names: HashMap, by_name: HashMap, } @@ -229,11 +235,16 @@ fn be32(b: &[u8], at: usize) -> Option { } /// Whether `b` ends with a Bento label. -pub(crate) fn sniff(b: &[u8]) -> bool { +pub fn sniff(b: &[u8]) -> bool { b.len() >= LABEL_SIZE && b[b.len() - LABEL_SIZE..b.len() - LABEL_SIZE + 8] == MAGIC } impl<'a> Container<'a> { + /// Object identifiers in ascending order. + pub fn object_ids(&self) -> impl Iterator + '_ { + self.objects.keys().copied() + } + pub fn open(data: &'a [u8]) -> Result, String> { if !sniff(data) { return Err("no Bento label at the end of the file".into()); @@ -324,7 +335,7 @@ impl<'a> Container<'a> { } /// The bytes of a value. - pub fn value(&self, p: &Prop) -> Result, String> { + pub(crate) fn value(&self, p: &Prop) -> Result, String> { let total = p.segs.iter().try_fold(0usize, |total, s| { let len = match s { Seg::Imm(b) => b.len(), diff --git a/crates/aaf/tests/bento_api.rs b/crates/aaf/tests/bento_api.rs new file mode 100644 index 000000000..9df70c661 --- /dev/null +++ b/crates/aaf/tests/bento_api.rs @@ -0,0 +1,17 @@ +use craft_aaf::omf::bento::{Container, Writer, sniff}; + +#[test] +fn external_consumer_reads_named_values_and_references() { + let mut writer = Writer::new(); + let first = writer.new_object(); + let second = writer.new_object(); + writer.set(first, "test:value", "test:type", b"long value"); + writer.set_references(first, &[second]); + let bytes = writer.finish(); + assert!(sniff(&bytes)); + let container = Container::open(&bytes).unwrap(); + assert!(container.object_ids().any(|id| id == first)); + assert_eq!(container.get(first, "test:value").as_deref(), Some(b"long value".as_slice())); + assert_eq!(container.resolve(first, second), second); + assert!(Container::open(&bytes[..bytes.len() - 1]).is_err()); +} From aa398af9dd312523c8a9fcb3b2711b726a40abdd Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:01 +0000 Subject: [PATCH 067/349] audio: fix range test lint on workspace gates --- crates/audio/src/wav_range.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/audio/src/wav_range.rs b/crates/audio/src/wav_range.rs index d8aea0d54..33762caf2 100644 --- a/crates/audio/src/wav_range.rs +++ b/crates/audio/src/wav_range.rs @@ -188,7 +188,7 @@ mod tests { self.bytes.len() as u64 } fn read_at(&self, offset: u64, buf: &mut [u8]) -> std::io::Result<()> { - self.reads.lock().unwrap().push((offset, buf.len())); + self.reads.lock().unwrap_or_else(std::sync::PoisonError::into_inner).push((offset, buf.len())); self.bytes.read_at(offset, buf) } } @@ -214,7 +214,7 @@ mod tests { bytes.extend_from_slice(b"iXML"); bytes.extend_from_slice(&(xml.len() as u32).to_le_bytes()); bytes.extend_from_slice(xml); - if xml.len() % 2 != 0 { + if xml.len() & 1 != 0 { bytes.push(0); } bytes.extend_from_slice(&base[36..]); From a2541707240580153c8ea9ef3043ec0257468d0a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:40 +0000 Subject: [PATCH 068/349] Share WebP header inspection --- crates/image-codecs/src/lib.rs | 1 + crates/image-codecs/src/webp_probe.rs | 47 +++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 crates/image-codecs/src/webp_probe.rs diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 6516b9ff2..961a04327 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -31,6 +31,7 @@ pub mod orientation; pub mod resolution; pub mod source_settings; pub mod web; +pub mod webp_probe; pub use crate::allocation::probe_allocation_size; pub use crate::cicp::Cicp; pub use crate::cicp::ContentLightLevel; diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs new file mode 100644 index 000000000..8376274df --- /dev/null +++ b/crates/image-codecs/src/webp_probe.rs @@ -0,0 +1,47 @@ +//! Header-only WebP inspection with image-chunk completeness checks. + +use crate::{CodecError, Format}; + +/// Stored width, height and EXIF orientation without decoding pixels. The image payload must +/// fit in the input, but its compressed contents are not validated. Uses the default decode limits. +pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { + let err = |s: &str| CodecError::malformed(Format::WebP, s); + let mut p = 12usize; + let mut has_image = false; + let mut exif = None; + while let Some(h) = bytes.get(p..p.saturating_add(8)) { + let size = u32::from_le_bytes([h[4], h[5], h[6], h[7]]) as usize; + let end = p.saturating_add(8).saturating_add(size); + if matches!(&h[..4], b"VP8 " | b"VP8L" | b"ANMF") { + if end > bytes.len() { + return Err(err("truncated image data")); + } + has_image = true; + } else if &h[..4] == b"EXIF" && end <= bytes.len() && exif.is_none() { + exif = bytes.get(p + 8..end); + } + p = end.saturating_add(size & 1); + } + if !has_image { + return Err(err("no image data")); + } + let (w, h) = crate::probe_size(bytes)?; + let orientation = exif.map_or(1, crate::exif_orientation); + let (w, h) = if (5..=8).contains(&orientation) { (h, w) } else { (w, h) }; + Ok((w, h, orientation)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn rejects_missing_and_truncated_image_chunks() { + let mut bytes = b"RIFF\x00\x00\x00\x00WEBP".to_vec(); + assert!(header(&bytes).is_err()); + bytes.extend_from_slice(b"VP8 "); + bytes.extend_from_slice(&10u32.to_le_bytes()); + bytes.push(0); + assert!(header(&bytes).is_err()); + } +} From 3c5007339754def577b3c5274f523d96384a35c4 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:41 +0000 Subject: [PATCH 069/349] Share bounded SHX container reader --- crates/shx/src/lib.rs | 2 + crates/shx/src/parse.rs | 281 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 283 insertions(+) create mode 100644 crates/shx/src/parse.rs diff --git a/crates/shx/src/lib.rs b/crates/shx/src/lib.rs index e595e90f5..ce330450c 100644 --- a/crates/shx/src/lib.rs +++ b/crates/shx/src/lib.rs @@ -4,5 +4,7 @@ //! Font discovery, glyph execution and text layout remain consumer responsibilities. mod compile; mod error; +pub mod parse; pub use compile::compile; pub use error::ShxError; +pub use parse::{ParsedFont, Record, ShxKind}; diff --git a/crates/shx/src/parse.rs b/crates/shx/src/parse.rs new file mode 100644 index 000000000..9cd4a35ad --- /dev/null +++ b/crates/shx/src/parse.rs @@ -0,0 +1,281 @@ +//! Reading the compiled SHX containers (layouts in the module documentation). Every count and +//! offset comes from the file, so each is checked against its length; records that run past +//! the end are dropped and the rest kept. + +use super::ShxError; +use std::collections::HashMap; + +/// The SHX container kind. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum ShxKind { + Shapes, + BigFont, + Unifont, +} +/// Byte ranges of one shape name and pen program in [`ParsedFont::data`]. +#[derive(Clone, Copy, Debug)] +pub struct Record { + pub name: (usize, usize), + pub program: (usize, usize), +} +/// Decoded container records and metrics; glyph execution remains a caller concern. +pub struct ParsedFont { + pub kind: ShxKind, + pub name: String, + pub header: bool, + pub above: f64, + pub below: f64, + pub dual: bool, + pub encoding: u8, + pub char_width: f64, + pub ranges: Vec<(u16, u16)>, + pub data: Vec, + pub records: HashMap, +} + +pub const SHAPES_10: &[u8] = b"AutoCAD-86 shapes 1.0\r\n\x1a"; +pub const SHAPES_11: &[u8] = b"AutoCAD-86 shapes 1.1\r\n\x1a"; +pub const BIGFONT: &[u8] = b"AutoCAD-86 bigfont 1.0\r\n\x1a"; +pub const UNIFONT: &[u8] = b"AutoCAD-86 unifont 1.0\r\n\x1a"; + +/// Largest file read (the largest big fonts are a few megabytes). +pub const MAX_FILE_BYTES: usize = 32 << 20; +/// Most escape ranges in a big font (lead bytes: at most 256). +const MAX_RANGES: usize = 256; + +/// A checked little-endian reader. +struct Rd<'a> { + b: &'a [u8], + pos: usize, +} + +impl<'a> Rd<'a> { + fn take(&mut self, n: usize) -> Result<&'a [u8], ShxError> { + let end = self.pos.checked_add(n).ok_or(ShxError::Truncated)?; + let s = self.b.get(self.pos..end).ok_or(ShxError::Truncated)?; + self.pos = end; + Ok(s) + } + fn u16(&mut self) -> Result { + match self.take(2)? { + [a, b] => Ok(u16::from_le_bytes([*a, *b])), + _ => Err(ShxError::Truncated), + } + } + fn u32(&mut self) -> Result { + match self.take(4)? { + [a, b, c, d] => Ok(u32::from_le_bytes([*a, *b, *c, *d])), + _ => Err(ShxError::Truncated), + } + } +} + +/// A font being read. +struct Font { + kind: ShxKind, + name: String, + header: bool, + above: f64, + below: f64, + dual: bool, + encoding: u8, + char_width: f64, + ranges: Vec<(u16, u16)>, + records: HashMap, +} + +impl Font { + fn new(kind: ShxKind) -> Font { + Font { + kind, + name: String::new(), + header: false, + above: 0.0, + below: 0.0, + dual: false, + encoding: 0, + char_width: 0.0, + ranges: Vec::new(), + records: HashMap::new(), + } + } + + /// Add the record of shape `number` at `start..end` of `data`: a NUL-terminated name, then + /// the program. Shape 0 is the font record. A record without a name terminator is dropped; + /// the first record of a number wins. + fn record(&mut self, data: &[u8], number: u16, start: usize, end: usize) { + let Some(bytes) = data.get(start..end) else { return }; + let Some(nul) = bytes.iter().position(|b| *b == 0) else { return }; + let name = (start, start + nul); + let program = (start + nul + 1, end); + if number == 0 { + if !self.header { + self.font_record(data.get(program.0..program.1).unwrap_or_default(), data.get(name.0..name.1).unwrap_or_default()); + } + return; + } + self.records.entry(number).or_insert(Record { name, program }); + } + + /// The font record: above, below, modes (and for a unifont encoding and embedding); an + /// extended big font's is character height, 0, modes, character width. + fn font_record(&mut self, info: &[u8], name: &[u8]) { + self.header = true; + self.name = name.iter().take(255).map(|c| char::from(*c)).collect(); + let byte = |i: usize| info.get(i).copied().unwrap_or(0); + self.above = f64::from(byte(0)); + self.below = f64::from(byte(1)); + self.dual = byte(2) == 2; + if self.kind == ShxKind::Unifont { + self.encoding = byte(3); + } + if self.kind == ShxKind::BigFont && info.len() >= 5 && byte(1) == 0 { + // Extended: height, 0, modes, width, 0. + self.below = 0.0; + self.char_width = f64::from(byte(3)); + } + } + + fn finish(self, data: Vec) -> Result { + if self.records.is_empty() { + return Err(ShxError::Empty); + } + Ok(ParsedFont { + kind: self.kind, + name: self.name, + header: self.header, + above: self.above, + below: self.below, + dual: self.dual, + encoding: self.encoding, + char_width: if self.char_width > 0.0 { self.char_width } else { self.above }, + ranges: self.ranges, + data, + records: self.records, + }) + } +} + +pub fn parse(bytes: &[u8]) -> Result { + if bytes.len() > MAX_FILE_BYTES { + return Err(ShxError::TooLarge); + } + if bytes.starts_with(SHAPES_10) || bytes.starts_with(SHAPES_11) { + shapes(bytes) + } else if bytes.starts_with(BIGFONT) { + bigfont(bytes) + } else if bytes.starts_with(UNIFONT) { + unifont(bytes) + } else { + Err(ShxError::NotShx) + } +} + +fn shapes(bytes: &[u8]) -> Result { + let mut r = Rd { b: bytes, pos: SHAPES_10.len() }; + let _first = r.u16()?; + let _last = r.u16()?; + let count = usize::from(r.u16()?); + // The whole index must be there before anything is read from it. + let index = r.take(count.checked_mul(4).ok_or(ShxError::TooLarge)?)?; + let mut f = Font::new(ShxKind::Shapes); + let mut pos = r.pos; + for [a, b, c, d] in index.as_chunks::<4>().0 { + let (number, len) = (u16::from_le_bytes([*a, *b]), usize::from(u16::from_le_bytes([*c, *d]))); + let Some(end) = pos.checked_add(len).filter(|e| *e <= bytes.len()) else { break }; + f.record(bytes, number, pos, end); + pos = end; + } + f.finish(bytes.to_vec()) +} + +fn bigfont(bytes: &[u8]) -> Result { + let mut r = Rd { b: bytes, pos: BIGFONT.len() }; + let index_size = usize::from(r.u16()?); + let count = usize::from(r.u16()?); + let nranges = usize::from(r.u16()?); + if nranges > MAX_RANGES { + return Err(ShxError::TooLarge); + } + let mut f = Font::new(ShxKind::BigFont); + for _ in 0..nranges { + let (lo, hi) = (r.u16()?, r.u16()?); + f.ranges.push((lo.min(hi), lo.max(hi))); + } + // The index has `count` entries of 8 bytes; a file whose count doesn't fit but whose index + // size does is read by that. + let fits = |n: usize| n.checked_mul(8).and_then(|l| r.pos.checked_add(l)).is_some_and(|e| e <= bytes.len()); + let n = if fits(count) { + count + } else if fits(index_size) { + index_size + } else { + return Err(ShxError::Truncated); + }; + let index = r.take(n.checked_mul(8).ok_or(ShxError::TooLarge)?)?; + for [a, b, c, d, o0, o1, o2, o3] in index.as_chunks::<8>().0 { + let number = u16::from_le_bytes([*a, *b]); + let len = usize::from(u16::from_le_bytes([*c, *d])); + let Ok(off) = usize::try_from(u32::from_le_bytes([*o0, *o1, *o2, *o3])) else { continue }; + if len == 0 { + continue; + } + let Some(end) = off.checked_add(len).filter(|e| *e <= bytes.len()) else { continue }; + f.record(bytes, number, off, end); + } + f.finish(bytes.to_vec()) +} + +fn unifont(bytes: &[u8]) -> Result { + let mut r = Rd { b: bytes, pos: UNIFONT.len() }; + let count = r.u32()?; + let info_len = usize::from(r.u16()?); + let info = r.take(info_len)?; + let mut f = Font::new(ShxKind::Unifont); + let nul = info.iter().position(|b| *b == 0).unwrap_or(info.len()); + f.font_record(info.get(nul.saturating_add(1)..).unwrap_or_default(), info.get(..nul).unwrap_or_default()); + // `count` includes the font record; never trusted beyond the data that is there. + let mut left = count.saturating_sub(1); + while left > 0 { + left -= 1; + let Ok(number) = r.u16() else { break }; + let Ok(len) = r.u16().map(usize::from) else { break }; + let start = r.pos; + let Some(end) = start.checked_add(len).filter(|e| *e <= bytes.len()) else { break }; + r.pos = end; + f.record(bytes, number, start, end); + } + f.finish(bytes.to_vec()) +} + +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used)] + use super::*; + #[test] + fn reads_shapes_bigfont_and_unifont_records() { + for (source, kind, shape) in [ + ("*0,4,font\n6,2,2,0\n*65,4,A\n1,064,0\n", ShxKind::Shapes, 65), + ("*BIGFONT 2,1,081,09F\n*0,4,big\n8,0,0,0\n*082A0,4,square\n1,080,0\n", ShxKind::BigFont, 0x82a0), + ("*UNIFONT,6,uni\n6,2,0,0,0,0\n*00041,4,a\n1,064,0\n", ShxKind::Unifont, 65), + ] { + let bytes = crate::compile(source).unwrap(); + let font = parse(&bytes).unwrap(); + assert_eq!(font.kind, kind); + assert!(font.header); + let record = font.records.get(&shape).unwrap(); + assert_eq!(font.data.get(record.program.1 - 1), Some(&0)); + } + } + #[test] + fn truncation_limits_and_unknown_signatures_are_errors() { + assert!(matches!(parse(b"not a font"), Err(ShxError::NotShx))); + assert!(matches!(parse(&vec![0; MAX_FILE_BYTES + 1]), Err(ShxError::TooLarge))); + let mut shapes = SHAPES_10.to_vec(); + shapes.extend([1, 0, 255, 255, 255, 255]); + assert!(matches!(parse(&shapes), Err(ShxError::Truncated))); + let mut big = BIGFONT.to_vec(); + big.extend([255, 255, 255, 255, 255, 255]); + assert!(matches!(parse(&big), Err(ShxError::TooLarge))); + } +} From b919ac40f3873fd3893c7ad97e6351940714c366 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 10:48:46 -0500 Subject: [PATCH 070/349] test(tga): validate metadata fixture selector explicitly --- crates/tga/src/metadata_tests.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/crates/tga/src/metadata_tests.rs b/crates/tga/src/metadata_tests.rs index 583f5d691..85c434bf4 100644 --- a/crates/tga/src/metadata_tests.rs +++ b/crates/tga/src/metadata_tests.rs @@ -163,6 +163,7 @@ fn complete_tga_footer_and_metadata_do_not_change_pixels() { } fn preceding_metadata(complete: bool, metadata: usize) -> Vec { + assert!(metadata <= 3, "test metadata selector must be 0..=3"); let mut file = header(2, if complete { 1 } else { 2 }, 1, 24, 0x20); file.extend_from_slice(&[0, 0, 255]); let payload_offset = file.len() as u32; @@ -180,7 +181,7 @@ fn preceding_metadata(complete: bool, metadata: usize) -> Vec { 1 => file.extend_from_slice(&[0; 2048]), 2 => file.extend_from_slice(&[1, 1, 0, 255, 0]), 3 => file.extend_from_slice(&18u32.to_le_bytes()), - _ => unreachable!(), + _ => {} } let extension_offset = file.len() as u32; let mut extension = [0; 495]; From 8a1bad8c2cc47f71c2a75fb19b67b54762fe8389 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:48:56 +0000 Subject: [PATCH 071/349] Cover WebP stored orientation --- crates/image-codecs/src/webp_probe.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index 8376274df..d70fac38d 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -35,6 +35,14 @@ pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { mod tests { use super::*; + #[test] + fn preserves_stored_dimensions_with_exif_orientation() { + let mut image = crate::Image::from_u8(2, 3, crate::ChannelLayout::Rgb, vec![42; 18]).unwrap(); + image.meta.exif = Some(b"II\x2a\x00\x08\x00\x00\x00\x01\x00\x12\x01\x03\x00\x01\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00".to_vec()); + let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + assert_eq!(header(&bytes).unwrap(), (2, 3, 6)); + } + #[test] fn rejects_missing_and_truncated_image_chunks() { let mut bytes = b"RIFF\x00\x00\x00\x00WEBP".to_vec(); From 82e258ab6eae4f4d6cd9dfe463a8640fd20c96d9 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:50:14 +0000 Subject: [PATCH 072/349] Exercise camera orientation in WebP fixture --- crates/image-codecs/src/webp_probe.rs | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index d70fac38d..8e33a71cf 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -39,7 +39,11 @@ mod tests { fn preserves_stored_dimensions_with_exif_orientation() { let mut image = crate::Image::from_u8(2, 3, crate::ChannelLayout::Rgb, vec![42; 18]).unwrap(); image.meta.exif = Some(b"II\x2a\x00\x08\x00\x00\x00\x01\x00\x12\x01\x03\x00\x01\x00\x00\x00\x06\x00\x00\x00\x00\x00\x00\x00".to_vec()); - let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + let mut bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + // The writer correctly makes exported pixels upright; simulate a camera file carrying orientation 6. + let exif = bytes.windows(4).position(|v| v == b"EXIF").unwrap(); + let tiff = exif + 8; + bytes[tiff + 18] = 6; assert_eq!(header(&bytes).unwrap(), (2, 3, 6)); } From 5ae0c89fdfca73c924db0521e2772e67c6cd49d3 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:50:50 +0000 Subject: [PATCH 073/349] audio: share compatible PCM essence wrappers --- crates/audio/src/essence_pcm.rs | 147 ++++++++++++++++++++++++++++++++ crates/audio/src/lib.rs | 4 + 2 files changed, 151 insertions(+) create mode 100644 crates/audio/src/essence_pcm.rs diff --git a/crates/audio/src/essence_pcm.rs b/crates/audio/src/essence_pcm.rs new file mode 100644 index 000000000..593ebb1c2 --- /dev/null +++ b/crates/audio/src/essence_pcm.rs @@ -0,0 +1,147 @@ +//! Compatibility WAVE and AIFF wrappers for embedded PCM essence in interchange files. +//! PCM inside the model is interleaved little-endian signed integers (8-bit unsigned for WAVE). + +pub use crate::{pcm_aiff_header as aiff_header, pcm_wav_file as wav_file, pcm_wav_header as wav_header}; + +/// PCM, channels, sample rate and bits of a WAVE file (integer PCM only). +pub fn parse_wav(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { + if b.len() < 12 || &b[..4] != b"RIFF" || &b[8..12] != b"WAVE" { + return None; + } + let mut at = 12; + let mut fmt = None; + while at + 8 <= b.len() { + let id = &b[at..at + 4]; + let len = u32::from_le_bytes(b[at + 4..at + 8].try_into().ok()?) as usize; + let body = &b[at + 8..(at + 8).saturating_add(len).min(b.len())]; + if id == b"fmt " && body.len() >= 16 { + let tag = u16::from_le_bytes([body[0], body[1]]); + let ch = u16::from_le_bytes([body[2], body[3]]); + let sr = u32::from_le_bytes(body[4..8].try_into().ok()?); + let bits = u16::from_le_bytes([body[14], body[15]]); + if tag != 1 && tag != 0xFFFE { + return None; + } + if tag == 0xFFFE { + // The first two bytes of the sub-format GUID carry the real format code. + let sub = body.get(24..26)?; + if u16::from_le_bytes([sub[0], sub[1]]) != 1 { + return None; + } + } + fmt = Some((ch, sr, bits)); + } else if id == b"data" { + let (ch, sr, bits) = fmt?; + return Some((body.to_vec(), ch, sr, bits)); + } + at = at.checked_add(8usize.checked_add(len)?.checked_add(len & 1)?)?; + } + None +} + +/// A complete AIFF file (big-endian PCM) from little-endian PCM. +pub fn aiff_file(pcm: &[u8], channels: u16, sample_rate: u32, bits: u16) -> Vec { + let bps = bits.div_ceil(8) as usize; + let frames = pcm.len() / (bps * channels.max(1) as usize).max(1); + let mut v = aiff_header(frames as u32, channels, sample_rate, bits); + for s in pcm.chunks_exact(bps.max(1)) { + if bps == 1 { + v.push(s[0] ^ 0x80); // WAVE 8-bit is unsigned, AIFF signed + } else { + v.extend(s.iter().rev()); + } + } + if (v.len() - 8) & 1 == 1 { + v.push(0); + } + v +} + +/// PCM (converted to little-endian), channels, sample rate and bits of an AIFF / AIFF-C (`NONE` +/// / `twos` / `sowt`) file. +pub fn parse_aiff(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { + if b.len() < 12 || &b[..4] != b"FORM" || !(&b[8..12] == b"AIFF" || &b[8..12] == b"AIFC") { + return None; + } + let mut at = 12; + let mut comm = None; + while at + 8 <= b.len() { + let id = &b[at..at + 4]; + let len = u32::from_be_bytes(b[at + 4..at + 8].try_into().ok()?) as usize; + let body = &b[at + 8..(at + 8).saturating_add(len).min(b.len())]; + if id == b"COMM" && body.len() >= 18 { + let ch = u16::from_be_bytes([body[0], body[1]]); + let bits = u16::from_be_bytes([body[6], body[7]]); + let sr = from_extended(body[8..18].try_into().ok()?).round() as u32; + let little = body.len() >= 22 && &body[18..22] == b"sowt"; + comm = Some((ch, sr, bits, little)); + } else if id == b"SSND" && body.len() >= 8 { + let (ch, sr, bits, little) = comm?; + let off = u32::from_be_bytes(body[..4].try_into().ok()?) as usize; + let data = body.get(8usize.checked_add(off)?..)?; + let bps = bits.div_ceil(8) as usize; + let mut pcm = Vec::with_capacity(data.len()); + for s in data.chunks_exact(bps.max(1)) { + if bps == 1 { + pcm.push(s[0] ^ 0x80); + } else if little { + pcm.extend_from_slice(s); + } else { + pcm.extend(s.iter().rev()); + } + } + return Some((pcm, ch, sr, bits)); + } + at = at.checked_add(8usize.checked_add(len)?.checked_add(len & 1)?)?; + } + None +} + +fn from_extended(b: [u8; 10]) -> f64 { + let e = (u16::from_be_bytes([b[0], b[1]]) & 0x7FFF) as i32; + let m = u64::from_be_bytes(b[2..10].try_into().unwrap_or([0; 8])); + if e == 0 && m == 0 { + return 0.0; + } + m as f64 / (1u64 << 63) as f64 * 2f64.powi(e - 16383) +} + +#[cfg(test)] +mod tests { + /// A mutated EDL whose clip ran for days produced an OMF descriptor for more than 4 GiB of + /// PCM: the RIFF size field overflowed ("attempt to add with overflow"). + #[test] + fn huge_wav_header_saturates() { + let h = super::wav_header(u32::MAX, 2, u32::MAX, 24); + assert_eq!(&h[4..8], &u32::MAX.to_le_bytes()); + } + + use super::*; + + #[test] + fn accepts_truncated_essence_summaries() { + let mut wav = wav_file(&[1, 2, 3, 4], 1, 48_000, 16); + wav.truncate(46); + assert_eq!(parse_wav(&wav), Some((vec![1, 2], 1, 48_000, 16))); + let mut aiff = aiff_file(&[1, 2, 3, 4], 1, 48_000, 16); + aiff.truncate(56); + assert_eq!(parse_aiff(&aiff), Some((vec![1, 2], 1, 48_000, 16))); + } + + #[test] + fn wav_and_aiff_round_trip() { + let pcm: Vec = (0..48u8).collect(); // 8 stereo 24-bit frames + let w = wav_file(&pcm, 2, 48_000, 24); + assert_eq!(parse_wav(&w), Some((pcm.clone(), 2, 48_000, 24))); + let a = aiff_file(&pcm, 2, 44_100, 24); + assert_eq!(parse_aiff(&a), Some((pcm.clone(), 2, 44_100, 24))); + let p16: Vec = (0..32u8).collect(); + assert_eq!(parse_aiff(&aiff_file(&p16, 1, 96_000, 16)), Some((p16, 1, 96_000, 16))); + assert!(parse_wav(b"RIFF").is_none()); + assert!(parse_aiff(&a[..30]).is_none()); + for cut in 0..w.len() { + let _ = parse_wav(&w[..cut]); + let _ = parse_aiff(&a[..cut.min(a.len())]); + } + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..7bbfbbcf5 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -66,6 +66,10 @@ mod wav; feature = "vorbis-encode" ))] mod write; + +/// PCM WAVE and AIFF wrappers for interchange essence. +#[cfg(feature = "pcm-encode")] +pub mod essence_pcm; #[cfg(feature = "vorbis-encode")] pub use write::{OGG_BITRATES, encode_ogg}; From 2f2d1d84e3a36b3f93e81507aeff3f0da97a7162 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:51:27 +0000 Subject: [PATCH 074/349] Share bounded SHX glyph program interpreter --- crates/shx/src/lib.rs | 1 + crates/shx/src/program.rs | 443 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 444 insertions(+) create mode 100644 crates/shx/src/program.rs diff --git a/crates/shx/src/lib.rs b/crates/shx/src/lib.rs index ce330450c..e330e59fd 100644 --- a/crates/shx/src/lib.rs +++ b/crates/shx/src/lib.rs @@ -5,6 +5,7 @@ mod compile; mod error; pub mod parse; +pub mod program; pub use compile::compile; pub use error::ShxError; pub use parse::{ParsedFont, Record, ShxKind}; diff --git a/crates/shx/src/program.rs b/crates/shx/src/program.rs new file mode 100644 index 000000000..9115d1c6d --- /dev/null +++ b/crates/shx/src/program.rs @@ -0,0 +1,443 @@ +//! The shape pen program: vector length/direction bytes and special codes 0–14, run into +//! polylines. Bounded everywhere: subshape depth, location stack, steps, points, coordinates. +//! +//! - A byte with a non-zero high nibble is a vector: length (high nibble) in one of 16 +//! directions (low nibble, counter-clockwise from east in 22.5° steps; the off-axis ones +//! are half-unit or unit steps on the minor axis). +//! - 0 end, 1 pen down, 2 pen up, 3/4 divide/multiply vector lengths by the next byte, +//! 5/6 push/pop the location, 7 subshape (one byte; two bytes high first in a Unicode font; +//! `0`, a two-byte number, base point, width and height in an extended big font), +//! 8 one X-Y displacement, 9 displacements up to (0,0), 10 octant arc (radius, +//! ±0SC: sign = clockwise, S start octant, C octants, 0 = 8), 11 fractional arc (start +//! offset, end offset, high and low radius, ±0SC; offsets in 1/256 of 45° from the octant +//! boundaries), 12 bulge arc (dx, dy, bulge: ±127 = semicircle), 13 bulge arcs up to (0,0), +//! 14 the next command is for vertical text only (dual-orientation fonts). +//! - Displacements and bulges are two's complement bytes; the arc direction byte keeps its +//! sign in the high bit. + +use std::f64::consts::{FRAC_PI_4, TAU}; + +use super::ShxKind; +use std::ops::{Add, Mul, Neg, Sub}; + +/// A point in SHX font units. +#[derive(Clone, Copy, Debug, Default, PartialEq)] +pub struct Point { + pub x: f64, + pub y: f64, +} +impl Point { + pub const ZERO: Self = Self { x: 0.0, y: 0.0 }; + pub const fn new(x: f64, y: f64) -> Self { + Self { x, y } + } + fn is_finite(self) -> bool { + self.x.is_finite() && self.y.is_finite() + } + fn len(self) -> f64 { + self.x.hypot(self.y) + } + fn len2(self) -> f64 { + self.x * self.x + self.y * self.y + } +} +impl Add for Point { + type Output = Self; + fn add(self, rhs: Self) -> Self { + Self::new(self.x + rhs.x, self.y + rhs.y) + } +} +impl Sub for Point { + type Output = Self; + fn sub(self, rhs: Self) -> Self { + Self::new(self.x - rhs.x, self.y - rhs.y) + } +} +impl Mul for Point { + type Output = Self; + fn mul(self, rhs: f64) -> Self { + Self::new(self.x * rhs, self.y * rhs) + } +} +impl Neg for Point { + type Output = Self; + fn neg(self) -> Self { + Self::new(-self.x, -self.y) + } +} + +/// Font records and metrics the bounded shape interpreter needs. +pub trait Font { + fn kind(&self) -> ShxKind; + fn dual(&self) -> bool; + fn above(&self) -> f64; + fn char_width(&self) -> f64; + fn program(&self, number: u16) -> Option<&[u8]>; +} +/// Pen-down strokes and advance in font units. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Glyph { + pub strokes: Vec>, + pub advance: Point, +} + +/// Subshape nesting (a cycle ends here). +const MAX_DEPTH: usize = 16; +/// Location stack (the format promises four). +const MAX_STACK: usize = 64; +/// Bytes run per glyph, subshapes included. +const MAX_STEPS: usize = 200_000; +/// Points per glyph. +const MAX_POINTS: usize = 50_000; +/// Coordinates in font units. +const MAX_COORD: f64 = 1.0e7; +/// Arc segments per full turn. +const ARC_STEPS: f64 = 64.0; + +/// Why a program stops early: the glyph is then not drawn. +#[derive(Debug)] +pub struct Broken; + +type Res = Result<(), Broken>; + +struct Pen<'a> { + font: &'a dyn Font, + vertical: bool, + pos: Point, + down: bool, + /// Vector length factor (codes 3 and 4). + scale: f64, + /// Per-axis factor of an extended big font subshape. + axes: Point, + stack: Vec, + strokes: Vec>, + active: Vec, + steps: usize, + points: usize, +} + +pub fn outline(font: &dyn Font, number: u16, vertical: bool) -> Result { + let mut pen = Pen { + font, + vertical, + pos: Point::ZERO, + down: true, + scale: 1.0, + axes: Point::new(1.0, 1.0), + stack: Vec::new(), + strokes: Vec::new(), + active: Vec::new(), + steps: 0, + points: 0, + }; + pen.run(number, 0)?; + pen.flush(); + Ok(Glyph { strokes: pen.strokes, advance: pen.pos }) +} + +/// The 16 vector directions (unit length on the major axis). +fn direction(d: u8) -> Point { + let (x, y) = match d & 15 { + 0 => (1.0, 0.0), + 1 => (1.0, 0.5), + 2 => (1.0, 1.0), + 3 => (0.5, 1.0), + 4 => (0.0, 1.0), + 5 => (-0.5, 1.0), + 6 => (-1.0, 1.0), + 7 => (-1.0, 0.5), + 8 => (-1.0, 0.0), + 9 => (-1.0, -0.5), + 10 => (-1.0, -1.0), + 11 => (-0.5, -1.0), + 12 => (0.0, -1.0), + 13 => (0.5, -1.0), + 14 => (1.0, -1.0), + _ => (1.0, -0.5), + }; + Point::new(x, y) +} + +/// A two's complement operand byte. +fn signed(b: u8) -> f64 { + f64::from(i8::from_le_bytes([b])) +} + +/// A program being read: its bytes and position. +struct Cur<'p> { + b: &'p [u8], + pos: usize, +} + +impl Cur<'_> { + fn byte(&mut self) -> Result { + let v = self.b.get(self.pos).copied().ok_or(Broken)?; + self.pos += 1; + Ok(v) + } +} + +impl Pen<'_> { + fn step(&mut self) -> Res { + self.steps += 1; + if self.steps > MAX_STEPS { Err(Broken) } else { Ok(()) } + } + + fn flush(&mut self) { + if self.active.len() >= 2 { + self.strokes.push(std::mem::take(&mut self.active)); + } else { + self.active.clear(); + } + } + + /// Move the pen by `d` font units (already scaled), drawing when the pen is down. + fn to(&mut self, target: Point) -> Res { + if !target.is_finite() || target.x.abs().max(target.y.abs()) > MAX_COORD { + return Err(Broken); + } + if self.down { + if self.active.is_empty() { + self.active.push(self.pos); + self.points += 1; + } + self.active.push(target); + self.points += 1; + if self.points > MAX_POINTS { + return Err(Broken); + } + } else { + self.flush(); + } + self.pos = target; + Ok(()) + } + + /// A displacement in vector units (times the length factor and the subshape axes). + fn by(&mut self, d: Point) -> Res { + let k = d * self.scale; + self.to(self.pos + Point::new(k.x * self.axes.x, k.y * self.axes.y)) + } + + /// An arc of `radius` vector units from the pen, starting at angle `start` on its circle + /// and turning `sweep` radians (positive counter-clockwise). + fn arc(&mut self, radius: f64, start: f64, sweep: f64) -> Res { + let r = radius * self.scale; + if !(r.is_finite() && r > 0.0 && sweep.is_finite()) { + return Ok(()); + } + let n = if self.down { (sweep.abs() / TAU * ARC_STEPS).ceil().clamp(1.0, ARC_STEPS) as usize } else { 1 }; + let from = self.pos; + let s0 = Point::new(start.cos(), start.sin()); + for i in 1..=n { + let a = start + sweep * i as f64 / n as f64; + let d = (Point::new(a.cos(), a.sin()) - s0) * r; + self.to(from + Point::new(d.x * self.axes.x, d.y * self.axes.y))?; + } + Ok(()) + } + + /// An arc to the displacement `d` with `bulge` (−127..127, ±127 a semicircle). + fn bulge(&mut self, d: Point, bulge: f64) -> Res { + let b = bulge.clamp(-127.0, 127.0) / 127.0; + if b == 0.0 || !self.down || d.len2() == 0.0 { + return self.by(d); + } + // Centre from the chord midpoint along its left normal; sweep 4·atan(b). + let centre = d * 0.5 + Point::new(-d.y, d.x) * ((1.0 - b * b) / (4.0 * b)); + let rel = -centre; + self.arc(rel.len(), rel.y.atan2(rel.x), 4.0 * b.atan()) + } + + /// The octant byte `±0SC`: (clockwise, start octant, octants with 0 = 8). + fn octants(spec: u8) -> (f64, f64, f64) { + let sign = if spec & 0x80 != 0 { -1.0 } else { 1.0 }; + let s = f64::from((spec >> 4) & 7); + let c = match spec & 7 { + 0 => 8.0, + c => f64::from(c), + }; + (sign, s, c) + } + + /// The vector unit size of an extended big font's subshape cell. + fn cell(&self) -> Point { + let h = if self.font.above() > 0.0 { self.font.above() } else { 1.0 }; + let w = if self.font.char_width() > 0.0 { self.font.char_width() } else { h }; + Point::new(w, h) + } + + fn run(&mut self, number: u16, depth: usize) -> Res { + if depth >= MAX_DEPTH { + return Err(Broken); + } + let program = self.font.program(number).ok_or(Broken)?; + let mut r = Cur { b: program, pos: 0 }; + let mut skip = false; + while r.pos < r.b.len() { + self.step()?; + let code = r.byte()?; + // Code 14: in a dual-orientation font the next command is for vertical text only. + let exec = !skip; + skip = false; + match code { + 0 => return Ok(()), + 1 if exec => self.down = true, + 2 if exec => { + self.down = false; + self.flush(); + } + 3 | 4 => { + let k = f64::from(r.byte()?); + if exec && k > 0.0 { + let s = if code == 3 { self.scale / k } else { self.scale * k }; + if !(1e-9..=MAX_COORD).contains(&s) { + return Err(Broken); + } + self.scale = s; + } + } + 5 if exec => { + if self.stack.len() >= MAX_STACK { + return Err(Broken); + } + self.stack.push(self.pos); + } + 6 if exec => { + self.flush(); + if let Some(p) = self.stack.pop() { + self.pos = p; + } + } + 7 => self.subshape(&mut r, exec, depth)?, + 8 | 9 | 12 | 13 => loop { + self.step()?; + let d = Point::new(signed(r.byte()?), signed(r.byte()?)); + if matches!(code, 9 | 13) && d == Point::ZERO { + break; + } + let bulge = if matches!(code, 12 | 13) { signed(r.byte()?) } else { 0.0 }; + if exec { + self.bulge(d, bulge)?; + } + if matches!(code, 8 | 12) { + break; + } + }, + 10 => { + let radius = f64::from(r.byte()?); + let (sign, s, c) = Self::octants(r.byte()?); + if exec { + self.arc(radius, s * FRAC_PI_4, sign * c * FRAC_PI_4)?; + } + } + 11 => { + let start = f64::from(r.byte()?) / 256.0; + let end = match r.byte()? { + 0 => 1.0, + e => f64::from(e) / 256.0, + }; + let radius = f64::from(u16::from_be_bytes([r.byte()?, r.byte()?])); + let (sign, s, c) = Self::octants(r.byte()?); + if exec { + // From `start` past the first octant boundary to `end` past the last + // octant's. + self.arc(radius, (s + sign * start) * FRAC_PI_4, sign * (c - 1.0 + end - start) * FRAC_PI_4)?; + } + } + 14 => skip = self.font.dual() && !self.vertical && exec, + 1..=15 => {} + v => { + if exec { + self.by(direction(v) * f64::from(v >> 4))?; + } + } + } + } + Ok(()) + } + + /// Code 7 and its operands. + fn subshape(&mut self, r: &mut Cur, exec: bool, depth: usize) -> Res { + match self.font.kind() { + ShxKind::Unifont => { + let n = u16::from_be_bytes([r.byte()?, r.byte()?]); + if exec { + self.run(n, depth + 1)?; + } + } + ShxKind::BigFont => { + let first = r.byte()?; + if first != 0 { + if exec { + self.run(u16::from(first), depth + 1)?; + } + return Ok(()); + } + // Extended: the primitive drawn in the box (x, y, width, height) of the cell. + let n = u16::from_be_bytes([r.byte()?, r.byte()?]); + let (x, y, w, h) = (f64::from(r.byte()?), f64::from(r.byte()?), f64::from(r.byte()?), f64::from(r.byte()?)); + if !exec { + return Ok(()); + } + let (pos, axes, down) = (self.pos, self.axes, self.down); + let cell = self.cell(); + self.flush(); + self.pos = pos + Point::new(x * axes.x, y * axes.y) * self.scale; + self.axes = Point::new(axes.x * w / cell.x, axes.y * h / cell.y); + let res = self.run(n, depth + 1); + self.flush(); + self.axes = axes; + self.pos = pos; + self.down = down; + res?; + } + ShxKind::Shapes => { + let n = u16::from(r.byte()?); + if exec { + self.run(n, depth + 1)?; + } + } + } + Ok(()) + } +} + +impl Font for crate::ParsedFont { + fn kind(&self) -> ShxKind { + self.kind + } + fn dual(&self) -> bool { + self.dual + } + fn above(&self) -> f64 { + self.above + } + fn char_width(&self) -> f64 { + self.char_width + } + fn program(&self, number: u16) -> Option<&[u8]> { + let r = self.records.get(&number)?; + self.data.get(r.program.0..r.program.1) + } +} + +#[cfg(test)] +mod tests { + #![allow(clippy::unwrap_used)] + use super::*; + #[test] + fn executes_shape_vectors_without_app_geometry_types() { + let bytes = crate::compile("*1,3,A\n1,010,0\n").unwrap(); + let font = crate::parse::parse(&bytes).unwrap(); + let glyph = outline(&font, 1, false).unwrap(); + assert_eq!(glyph.strokes, vec![vec![Point::new(0.0, 0.0), Point::new(1.0, 0.0)]]); + assert_eq!(glyph.advance, Point::new(1.0, 0.0)); + } + #[test] + fn recursive_shapes_stop_at_the_depth_bound() { + let bytes = crate::compile("*1,3,A\n7,1,0\n").unwrap(); + let font = crate::parse::parse(&bytes).unwrap(); + assert!(outline(&font, 1, false).is_err()); + } +} From 5a36112af6567a60491c47361a9fdd44ad362979 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 16:51:49 +0100 Subject: [PATCH 075/349] craft-image-codecs: SGI rows may share compressed data and must start after the offset tables Addresses review findings: the RLE size check no longer demands separate payload space for every row, and a row offset inside the offset tables is refused. A row without its trailing zero count still reads, as in ffmpeg. --- crates/image-codecs/src/codecs/sgi.rs | 56 +++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 3 deletions(-) diff --git a/crates/image-codecs/src/codecs/sgi.rs b/crates/image-codecs/src/codecs/sgi.rs index 1e31b5f0a..64c80299c 100644 --- a/crates/image-codecs/src/codecs/sgi.rs +++ b/crates/image-codecs/src/codecs/sgi.rs @@ -120,8 +120,9 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { // Reject inputs that cannot hold the declared pixels before allocating anything for them. let table = if h.rle { rows.checked_mul(8).ok_or_else(|| bad("image size overflow"))? } else { 0 }; let min_len = if h.rle { - // Every row needs at least a packet and a terminator. - HEADER + table + rows * bps + // Both offset tables must fit; rows may share compressed data, so the data itself is + // checked row by row against the offsets below. + HEADER + table } else { HEADER + total.checked_mul(bps).ok_or_else(|| bad("image size overflow"))? }; @@ -138,7 +139,10 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { if h.rle { let start = be32(b, HEADER + index * 4) as usize; let len = be32(b, HEADER + rows * 4 + index * 4) as usize; - let end = start.checked_add(len).filter(|&e| e <= b.len() && start >= HEADER).ok_or_else(|| bad("RLE row lies outside the file"))?; + let end = start + .checked_add(len) + .filter(|&e| e <= b.len() && start >= HEADER + table) + .ok_or_else(|| bad("RLE row lies outside the file"))?; read_rle_row(&b[start..end], h.wide, &mut row)?; } else { let start = HEADER + index * w * bps; @@ -335,6 +339,52 @@ mod tests { assert!(decode(&huge, &Limits::default()).is_err()); } + /// A 1-plane, 8-bit RLE file whose `rows` all start where `starts[i]` says, each `len` bytes long. + fn rle_file(w: u16, starts: &[u32], len: u32, payload: &[u8]) -> Vec { + let mut f = vec![0u8; HEADER]; + f[0..2].copy_from_slice(&MAGIC.to_be_bytes()); + f[2] = 1; + f[3] = 1; + f[4..6].copy_from_slice(&2u16.to_be_bytes()); + f[6..8].copy_from_slice(&w.to_be_bytes()); + f[8..10].copy_from_slice(&(starts.len() as u16).to_be_bytes()); + f[10..12].copy_from_slice(&1u16.to_be_bytes()); + for s in starts { + f.extend_from_slice(&s.to_be_bytes()); + } + for _ in starts { + f.extend_from_slice(&len.to_be_bytes()); + } + f.extend_from_slice(payload); + f + } + + /// The format lets table entries share one compressed row: eight rows, one payload. + #[test] + fn rows_may_share_compressed_data() { + let table = HEADER + 8 * 8; + let f = rle_file(1, &[table as u32; 8], 3, &[0x81, 255, 0]); + assert_eq!(f.len(), table + 3); + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!((img.dimensions(), img.data()), ((1, 8), &[255u8; 8][..])); + } + + /// Compressed rows start after both tables: an offset into a table is refused. + #[test] + fn rows_may_not_start_inside_the_offset_tables() { + // 3x1: the tables end at 520; 515 reads the table's own bytes as a packet list. + let f = rle_file(3, &[515], 3, &[0, 0, 0, 0, 0]); + assert!(decode(&f, &Limits::default()).is_err()); + } + + /// FFmpeg's decoder, run as an oracle, also reads a row that ends with its last packet and no + /// zero terminator; so does this one. + #[test] + fn a_row_without_its_terminator_still_reads() { + let f = rle_file(1, &[520], 2, &[0x81, 42]); + assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[42]); + } + #[test] fn palette_mapped_files_are_unsupported() { let img = gradient(4, 4, ChannelLayout::Gray); From e9eaaf5641640b4e2735b0af79ef589c5a74a88a Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 16:52:35 +0100 Subject: [PATCH 076/349] craft-image-codecs: Sun Raster 1-bit colour maps, opaque standard 32-bit pixels, fallible output buffer Addresses review findings: a 1-bit file with an RGB colour map reads as colour; the unused first byte of standard 32-bit pixels is no longer read as alpha; the writer's buffer is reserved with try_reserve_exact. README lists the native layouts correctly. --- crates/image-codecs/README.md | 2 +- crates/image-codecs/src/codecs/sunraster.rs | 52 +++++++++++++++++++-- 2 files changed, 49 insertions(+), 5 deletions(-) diff --git a/crates/image-codecs/README.md b/crates/image-codecs/README.md index f9f5f53e6..a37760d80 100644 --- a/crates/image-codecs/README.md +++ b/crates/image-codecs/README.md @@ -56,7 +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 | -| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, Gray+A, RGB, RGBA | yes | no | no | no | no | no | no | built in | +| Sun Raster (`.ras`) | yes (incl. RLE and colour maps) | yes (uncompressed) | U8 | Gray, RGB, RGBA | yes | 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/sunraster.rs b/crates/image-codecs/src/codecs/sunraster.rs index 84d60f145..85c24acc5 100644 --- a/crates/image-codecs/src/codecs/sunraster.rs +++ b/crates/image-codecs/src/codecs/sunraster.rs @@ -97,9 +97,18 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { for x in 0..wu { match depth { 1 => { - // A set bit is black. let bit = (row[x / 8] >> (7 - x % 8)) & 1; - out.push(if bit == 1 { 0 } else { 255 }); + if map_type == 1 { + // The bit is an index into the (two-entry or longer) colour map. + let i = usize::from(bit); + if i >= entries { + return Err(bad("pixel index is outside the colour map")); + } + out.extend_from_slice(&[map[i], map[entries + i], map[2 * entries + i]]); + } else { + // A set bit is black. + out.push(if bit == 1 { 0 } else { 255 }); + } } 8 if map_type == 1 => { let i = usize::from(row[x]); @@ -115,7 +124,8 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { } _ => { let p = &row[4 * x..4 * x + 4]; - out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], p[0]] }); + // In the standard types the first byte (X in XBGR) is unused, not alpha. + out.extend_from_slice(&if kind == 3 { [p[1], p[2], p[3], p[0]] } else { [p[3], p[2], p[1], 255] }); } } } @@ -123,6 +133,13 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result { Image::from_u8(w, h, layout, out) } +/// A buffer of `cap` bytes, or an error instead of an abort when the allocation cannot be made. +fn reserve(cap: usize) -> std::result::Result, std::collections::TryReserveError> { + let mut v = Vec::new(); + v.try_reserve_exact(cap)?; + Ok(v) +} + /// Writes an uncompressed rasterfile: 8-bit gray, 24-bit RGB or 32-bit RGBA, in the RGB-ordered type. pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { let enc = |msg: String| CodecError::encode(F, msg); @@ -145,7 +162,8 @@ pub(crate) fn encode(src: &Image, plan: Plan) -> Result, CodecError> { if data.len() != wu * hu * bytes { return Err(enc("the image has the wrong number of samples".into())); } - let mut out = Vec::with_capacity(HEADER + len as usize); + let mut out = reserve(HEADER.checked_add(len as usize).ok_or_else(|| enc("image too large".into()))?) + .map_err(|_| enc("the image is too large to encode".into()))?; for v in [MAGIC, w, h, depth as u32, len, 3, 0, 0] { out.extend_from_slice(&v.to_be_bytes()); } @@ -218,6 +236,32 @@ mod tests { assert_eq!(decode(&f, &Limits::default()).unwrap().data(), &[0, 255, 0]); } + #[test] + fn one_bit_files_with_a_colour_map_read_as_colour() { + // Two entries: red plane, green plane, blue plane; bit 0 is entry 0. + let map = [10, 20, 30, 40, 50, 60]; + let f = file(1, 1, &map, 1, 3, 1, &[0b0100_0000, 0]); + let img = decode(&f, &Limits::default()).unwrap(); + assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgb, &[10, 30, 50, 20, 40, 60, 10, 30, 50][..])); + // A one-entry map has no entry for a set bit. + assert!(decode(&file(1, 1, &[1, 2, 3], 1, 1, 1, &[0b1000_0000, 0]), &Limits::default()).is_err()); + } + + #[test] + fn the_unused_first_byte_of_standard_32_bit_pixels_is_not_alpha() { + let img = decode(&file(32, 1, &[], 0, 1, 1, &[0, 30, 20, 10]), &Limits::default()).unwrap(); + assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgba, &[10, 20, 30, 255][..])); + // In the RGB-ordered type the first byte is the alpha the writer stores there. + let img = decode(&file(32, 3, &[], 0, 1, 1, &[7, 10, 20, 30]), &Limits::default()).unwrap(); + assert_eq!(img.data(), &[10, 20, 30, 7]); + } + + #[test] + fn an_output_buffer_too_large_to_allocate_is_an_error() { + assert!(reserve(usize::MAX).is_err()); + assert!(reserve(16).is_ok()); + } + #[test] fn hostile_input_is_an_error_not_a_panic() { let img = pattern(9, 5, ChannelLayout::Rgb); From 8ce5335e8fc93c4e9546286390a0b0d35897585a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:53:30 +0000 Subject: [PATCH 077/349] aaf: preserve bounded FilmCraft OMF traversal --- crates/aaf/src/lib.rs | 4 + crates/aaf/src/omf/read.rs | 255 +++++++++++++++++++++++++++++++++++-- crates/aaf/src/pcm.rs | 5 - 3 files changed, 248 insertions(+), 16 deletions(-) diff --git a/crates/aaf/src/lib.rs b/crates/aaf/src/lib.rs index ee7448bc0..4968c5b39 100644 --- a/crates/aaf/src/lib.rs +++ b/crates/aaf/src/lib.rs @@ -29,7 +29,11 @@ mod roundtrip_tests; #[cfg(test)] mod testdoc; +/// Diagnostic types used by readers and writers. +pub use craft_timeline::report; pub use craft_timeline::report::Report; +/// Exact time types used by the composition model. +pub use craft_timeline::time; /// Error from a reader or writer. Unsupported *features* never error; they go in the [`Report`]. #[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] diff --git a/crates/aaf/src/omf/read.rs b/crates/aaf/src/omf/read.rs index d45b6ff63..b9c3bd9d1 100644 --- a/crates/aaf/src/omf/read.rs +++ b/crates/aaf/src/omf/read.rs @@ -12,6 +12,10 @@ type Uid = [u8; 12]; const MAX_REFERENCE_VISITS: usize = 65_536; +/// A source-clip search stopped at its work limit. +#[derive(Clone, Copy)] +struct SearchLimit; + struct R<'a, 'b> { c: &'b Container<'a>, report: &'b mut Report, @@ -21,15 +25,43 @@ struct R<'a, 'b> { media: HashMap>, doc: Document, sources: HashMap<(Uid, u32, String), usize>, + /// Component visits left for [`R::segment`] over the whole document. + budget: usize, + /// Outcome of the source-clip search under each segment: deterministic, so it is made once. + clip_search: HashMap, SearchLimit>>, } +/// Components one document may expand into timeline items; a small file can reference the same +/// sequence from many places and would otherwise multiply without bound. +const MAX_COMPONENT_VISITS: usize = 1_000_000; + +/// Reported when the shared component budget runs out. +const BUDGET_WARNING: &str = "OMF composition is too large to import completely (the remaining components are dropped)"; +/// Most visited components, and most queued references, one source-clip search may spend. +const MAX_CLIP_SEARCH_VISITS: usize = 100_000; +const MAX_CLIP_SEARCH_PENDING: usize = 1_000_000; + pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { + read_with_budget(bytes, report, MAX_COMPONENT_VISITS) +} + +fn read_with_budget(bytes: &[u8], report: &mut Report, budget: usize) -> Result { let perr = |m: String| Error::Parse { format: "OMF", message: m }; let c = Container::open(bytes).map_err(perr)?; let class_of = |o: u32| c.get(o, "OMFI:OOBJ:ObjClass").and_then(|v| v.get(..4).map(|b| [b[0], b[1], b[2], b[3]])); let head = c.objects.keys().copied().find(|&o| class_of(o) == Some(*b"HEAD")).ok_or_else(|| perr("no OMF header object".into()))?; let be = c.get(head, "OMFI:HEAD:ByteOrder").is_none_or(|v| v.first() != Some(&0x49)); - let mut r = R { c: &c, report, be, mobs: HashMap::new(), media: HashMap::new(), doc: Document::default(), sources: HashMap::new() }; + let mut r = R { + c: &c, + report, + be, + mobs: HashMap::new(), + media: HashMap::new(), + doc: Document::default(), + sources: HashMap::new(), + budget, + clip_search: HashMap::new(), + }; let mob_list = r.refs(head, "OMFI:HEAD:Mobs"); let mob_list = if mob_list.is_empty() { c.objects.keys().copied().filter(|&o| matches!(class_of(o).as_ref(), Some(b"CMOB" | b"MMOB" | b"SMOB"))).collect() @@ -66,8 +98,14 @@ pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { cmobs.iter().copied().filter(|m| r.uid(*m, "OMFI:MOBJ:MobID").is_none_or(|id| !referenced.contains(&id))).collect() }; for m in top { + // every composition spends from the budget too: a list of up to 65,535 repeated entries must not yield that many + if r.budget == 0 && !r.doc.compositions.is_empty() { + r.report.warn(BUDGET_WARNING); + break; + } let comp = r.composition(m); r.doc.compositions.push(comp); + r.budget = r.budget.saturating_sub(1); } if r.doc.compositions.is_empty() { return Err(Error::Empty); @@ -166,6 +204,13 @@ impl R<'_, '_> { let slots = self.refs(m, "OMFI:MOBJ:Slots"); let mut na = 0; for s in slots { + if self.budget == 0 { + self.report.warn(BUDGET_WARNING); + break; + } + // Every slot spends a unit, skipped ones too: a list of up to 65,535 repeated slots + // must not cost that much work in each of 65,535 repeated compositions. + self.budget -= 1; let Some(seg) = self.r#ref(s, "OMFI:MSLT:Segment") else { continue }; let rate = self.rational(s, "OMFI:MSLT:EditRate").filter(|r| r.0 > 0 && r.1 > 0).unwrap_or((25, 1)); let kind = self.data_kind(seg); @@ -213,9 +258,15 @@ impl R<'_, '_> { fn segment(&mut self, seg: u32, rate: (i64, i64), depth: usize) -> Vec { let len = units_to_ticks(self.len(seg), rate.0, rate.1); - if depth > 32 { + // Depth alone does not bound a graph that references the same component many times at + // every level, so each visit also spends from a per-document budget. + if depth > 32 || self.budget == 0 { + if self.budget == 0 { + self.report.warn(BUDGET_WARNING); + } return vec![CItem::Filler(len)]; } + self.budget -= 1; match &self.class(seg) { b"SEQU" => { let mut out = Vec::new(); @@ -306,12 +357,44 @@ impl R<'_, '_> { .find(|&s| self.r#ref(s, "OMFI:MSLT:TrackDesc").and_then(|t| self.u32(t, "OMFI:TRKD:TrackID")) == Some(track)) } - fn first_clip(&self, seg: u32) -> Option { - match &self.class(seg) { - b"SCLP" => Some(seg), - b"SEQU" => self.refs(seg, "OMFI:SEQU:Components").into_iter().find_map(|c| self.first_clip(c)), - _ => None, + /// First source clip under `seg`, depth-first; a sequence referencing itself (directly or + /// through a cycle) ends the search rather than the stack. `Err` when the search spent its + /// budget of visited components or queued references before finishing (the answer is unknown). + fn first_clip(&mut self, seg: u32) -> std::result::Result, SearchLimit> { + if let Some(found) = self.clip_search.get(&seg) { + return *found; } + let found = self.first_clip_within(seg, MAX_CLIP_SEARCH_VISITS, MAX_CLIP_SEARCH_PENDING); + self.clip_search.insert(seg, found); + found + } + + fn first_clip_within(&self, seg: u32, max_visits: usize, max_pending: usize) -> std::result::Result, SearchLimit> { + let mut visited = HashSet::new(); + let mut todo = vec![seg]; + let mut queued = 1usize; + while let Some(seg) = todo.pop() { + if !visited.insert(seg) { + continue; + } + if visited.len() > max_visits { + return Err(SearchLimit); + } + match &self.class(seg) { + b"SCLP" => return Ok(Some(seg)), + b"SEQU" => { + let comps = self.refs(seg, "OMFI:SEQU:Components"); + // sequences may share one component list, so queued references grow with expansions, not visits + queued = queued.saturating_add(comps.len()); + if queued > max_pending { + return Err(SearchLimit); + } + todo.extend(comps.into_iter().rev()); + } + _ => {} + } + } + Ok(None) } fn resolve(&mut self, id: Uid, track: u32, start: Tick, master: Option, depth: usize) -> Option<(usize, Tick)> { @@ -328,7 +411,13 @@ impl R<'_, '_> { match &self.class(mob) { b"MMOB" => { let key = master.unwrap_or_else(|| id.iter().map(|b| format!("{b:02x}")).collect()); - let clip = self.first_clip(seg)?; + let clip = match self.first_clip(seg) { + Ok(c) => c?, + Err(SearchLimit) => { + self.report.warn("a master mob is too large to search for its source clip (imported as a gap)"); + return None; + } + }; let inner = units_to_ticks(self.i32(clip, "OMFI:SCLP:StartTime").unwrap_or(0), rate.0, rate.1); let next = self.uid(clip, "OMFI:SCLP:SourceID")?; let next_track = self.u32(clip, "OMFI:SCLP:SourceTrackID")?; @@ -353,7 +442,9 @@ impl R<'_, '_> { let file_rate = sr.filter(|r| r.0 > 0 && r.1 > 0).unwrap_or(rate); let length = units_to_ticks(self.i32(desc, "OMFI:MDFL:Length").unwrap_or(0), file_rate.0, file_rate.1); let summary = self.c.get(desc, "OMFI:WAVD:Summary").or_else(|| self.c.get(desc, "OMFI:AIFD:Summary")).unwrap_or_default(); - let fmt = crate::pcm::parse_wav(&summary).or_else(|| crate::pcm::parse_aiff(&summary)).map(|(_, ch, sr, bits)| (ch as u32, sr, bits)); + let fmt = craft_audio::essence_pcm::parse_wav(&summary) + .or_else(|| craft_audio::essence_pcm::parse_aiff(&summary)) + .map(|(_, ch, sr, bits)| (ch as u32, sr, bits)); let mut path = None; for l in self.refs(desc, "OMFI:MDES:Locator") { let p = match &self.class(l) { @@ -373,7 +464,8 @@ impl R<'_, '_> { let (file_channels, sample_rate, bits) = fmt.unwrap_or((1, file_rate.0 as u32, 16)); let channel = (file_channels > 1 && sound_slots > 1).then(|| track.saturating_sub(1).min(file_channels - 1)); // timecode of the physical source - let tc = self.first_clip(seg).and_then(|clip| { + let first = self.first_clip(seg).ok().flatten(); + let tc = first.and_then(|clip| { let tid = self.uid(clip, "OMFI:SCLP:SourceID")?; let tape = *self.mobs.get(&tid)?; let (start_tc, fps, trate) = self.refs(tape, "OMFI:MOBJ:Slots").into_iter().find_map(|s| { @@ -415,7 +507,7 @@ impl R<'_, '_> { nested: None, }; if let Some(d) = self.media.get(&id) { - if let Some((pcm, ch, sr, b)) = crate::pcm::parse_wav(d).or_else(|| crate::pcm::parse_aiff(d)) { + if let Some((pcm, ch, sr, b)) = craft_audio::essence_pcm::parse_wav(d).or_else(|| craft_audio::essence_pcm::parse_aiff(d)) { s.embedded = Some(pcm); s.file_channels = ch as u32; s.channels = if s.channel.is_some() { 1 } else { ch as u32 }; @@ -437,3 +529,144 @@ impl R<'_, '_> { } } } + +#[cfg(test)] +mod tests { + use super::super::bento::Writer; + use super::*; + + fn obj(w: &mut Writer, class: &[u8; 4]) -> u32 { + let id = w.new_object(); + w.set(id, "OMFI:OOBJ:ObjClass", "omfi:ClassID", class); + id + } + fn list(w: &mut Writer, o: u32, p: &str, targets: &[u32]) { + let mut v = (targets.len() as u16).to_be_bytes().to_vec(); + for t in targets { + v.extend_from_slice(&t.to_be_bytes()); + } + w.set(o, p, "omfi:ObjRefArray", &v); + } + + fn search(max_visits: usize, max_pending: usize, build: impl FnOnce(&mut Writer) -> u32) -> std::result::Result, SearchLimit> { + let mut w = Writer::new(); + let root = build(&mut w); + let bytes = w.finish(); + let c = Container::open(&bytes).unwrap(); + let mut report = Report::default(); + let r = R { + c: &c, + report: &mut report, + be: true, + mobs: HashMap::new(), + media: HashMap::new(), + doc: Document::default(), + sources: HashMap::new(), + budget: 0, + clip_search: HashMap::new(), + }; + r.first_clip_within(root, max_visits, max_pending) + } + + #[test] + fn clip_search_reports_its_limits() { + // found within the limits + assert!(matches!( + search(10, 10, |w| { + let (s, c) = (obj(w, b"SEQU"), obj(w, b"SCLP")); + list(w, s, "OMFI:SEQU:Components", &[c]); + s + }), + Ok(Some(_)) + )); + // too many distinct components before any clip + assert!( + search(5, 1000, |w| { + let (s, f) = (obj(w, b"SEQU"), (0..20).map(|_| obj(w, b"FILL")).collect::>()); + list(w, s, "OMFI:SEQU:Components", &f); + s + }) + .is_err() + ); + // few visits, but sequences that each queue a long list of references + assert!( + search(1000, 500, |w| { + let f = obj(w, b"FILL"); + let inner: Vec = (0..20).map(|_| obj(w, b"SEQU")).collect(); + for &i in &inner { + list(w, i, "OMFI:SEQU:Components", &[f; 100]); + } + let s = obj(w, b"SEQU"); + list(w, s, "OMFI:SEQU:Components", &inner); + s + }) + .is_err() + ); + // a search that ends without a clip is not a limit + assert!(matches!(search(10, 10, |w| obj(w, b"FILL")), Ok(None))); + } + + #[test] + fn skipped_slots_spend_the_budget() { + let mut w = Writer::new(); + let head = obj(&mut w, b"HEAD"); + let cm = obj(&mut w, b"CMOB"); + let slot = obj(&mut w, b"MSLT"); + list(&mut w, cm, "OMFI:MOBJ:Slots", &[slot; 200]); + list(&mut w, head, "OMFI:HEAD:Mobs", &[cm]); + list(&mut w, head, "OMFI:HEAD:PrimaryMobs", &[cm]); + let bytes = w.finish(); + let mut report = Report::default(); + read_with_budget(&bytes, &mut report, 50).unwrap(); + assert!(report.mentions(BUDGET_WARNING), "slots with no segment cost nothing before"); + } + + #[test] + fn a_source_clip_search_is_made_once_per_segment() { + let mut w = Writer::new(); + let (s, c) = (obj(&mut w, b"SEQU"), obj(&mut w, b"SCLP")); + list(&mut w, s, "OMFI:SEQU:Components", &[c]); + let bytes = w.finish(); + let c = Container::open(&bytes).unwrap(); + let mut report = Report::default(); + let mut r = R { + c: &c, + report: &mut report, + be: true, + mobs: HashMap::new(), + media: HashMap::new(), + doc: Document::default(), + sources: HashMap::new(), + budget: 0, + clip_search: HashMap::new(), + }; + let first = r.first_clip(s).ok(); + assert!(matches!(first, Some(Some(_)))); + assert_eq!(r.clip_search.len(), 1); + assert_eq!(r.first_clip(s).ok(), first); + assert_eq!(r.clip_search.len(), 1); + } + + #[test] + fn repeated_slots_and_compositions_spend_the_budget() { + let mut w = Writer::new(); + let head = obj(&mut w, b"HEAD"); + let cm = obj(&mut w, b"CMOB"); + let dd = obj(&mut w, b"DDEF"); + w.set(dd, "OMFI:DDEF:DataKindID", "omfi:UniqueName", b"omfi:data:Sound\0"); + let fill = obj(&mut w, b"FILL"); + w.set(fill, "OMFI:CPNT:DataKind", "omfi:ObjRef", &dd.to_be_bytes()); + let slot = obj(&mut w, b"MSLT"); + w.set(slot, "OMFI:MSLT:Segment", "omfi:ObjRef", &fill.to_be_bytes()); + list(&mut w, cm, "OMFI:MOBJ:Slots", &[slot; 200]); + list(&mut w, head, "OMFI:HEAD:Mobs", &[cm]); + list(&mut w, head, "OMFI:HEAD:PrimaryMobs", &[cm; 200]); + let bytes = w.finish(); + let mut report = Report::default(); + let doc = read_with_budget(&bytes, &mut report, 50).unwrap(); + let tracks: usize = doc.compositions.iter().map(|c| c.tracks.len()).sum(); + assert!(tracks <= 50, "{tracks} tracks from a budget of 50"); + assert!(doc.compositions.len() <= 2, "{} compositions", doc.compositions.len()); + assert!(report.has_warnings()); + } +} diff --git a/crates/aaf/src/pcm.rs b/crates/aaf/src/pcm.rs index 789c976a8..9992b2d3b 100644 --- a/crates/aaf/src/pcm.rs +++ b/crates/aaf/src/pcm.rs @@ -4,8 +4,3 @@ pub(crate) fn parse_wav(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { craft_audio::wav_pcm(b).map(|p| (p.data, p.channels, p.sample_rate, p.bits)) } - -/// The same for an AIFF / AIFF-C (`NONE`, `twos`, `sowt`) file. -pub(crate) fn parse_aiff(b: &[u8]) -> Option<(Vec, u16, u32, u16)> { - craft_audio::aiff_pcm(b).map(|p| (p.data, p.channels, p.sample_rate, p.bits)) -} From 52a6dd6aa7aadf7a57f715135ec1dcbc51088515 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:46:32 +0000 Subject: [PATCH 078/349] aaf: expose bounded Bento container access --- crates/aaf/src/omf.rs | 2 +- crates/aaf/src/omf/bento.rs | 25 ++++++++++++++++++------- crates/aaf/tests/bento_api.rs | 17 +++++++++++++++++ 3 files changed, 36 insertions(+), 8 deletions(-) create mode 100644 crates/aaf/tests/bento_api.rs diff --git a/crates/aaf/src/omf.rs b/crates/aaf/src/omf.rs index 57e0f756c..bbd2e8571 100644 --- a/crates/aaf/src/omf.rs +++ b/crates/aaf/src/omf.rs @@ -21,7 +21,7 @@ //! transition's name) are not in the specification; they were first written by FilmCraft and keep //! their names so that existing files read back. -pub(crate) mod bento; +pub mod bento; mod read; mod write; diff --git a/crates/aaf/src/omf/bento.rs b/crates/aaf/src/omf/bento.rs index 00a7e2a26..171196fe1 100644 --- a/crates/aaf/src/omf/bento.rs +++ b/crates/aaf/src/omf/bento.rs @@ -35,8 +35,8 @@ use std::collections::{BTreeMap, HashMap}; -pub(crate) const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; -pub(crate) const LABEL_SIZE: usize = 24; +pub const MAGIC: [u8; 8] = [0xA4, b'C', b'M', 0xA5, b'H', b'd', b'r', 0xD7]; +pub const LABEL_SIZE: usize = 24; // standard object ids const TOC_OBJECT: u32 = 1; @@ -82,7 +82,7 @@ const MAX_VALUE_BYTES: usize = 16 << 20; const MAX_NAME_BYTES: usize = 4 << 20; /// Builds a Bento container. -pub(crate) struct Writer { +pub struct Writer { data: Vec, names: HashMap<(u32, String), u32>, next: u32, @@ -90,6 +90,12 @@ pub(crate) struct Writer { entries: Vec<(u32, u32, u32, Vec)>, } +impl Default for Writer { + fn default() -> Self { + Self::new() + } +} + impl Writer { pub fn new() -> Writer { Writer { data: Vec::new(), names: HashMap::new(), next: MIN_USER_ID, entries: Vec::new() } @@ -217,9 +223,9 @@ pub(crate) struct Prop { } /// A parsed Bento container. -pub(crate) struct Container<'a> { +pub struct Container<'a> { data: &'a [u8], - pub objects: BTreeMap>, + pub(crate) objects: BTreeMap>, names: HashMap, by_name: HashMap, } @@ -229,11 +235,16 @@ fn be32(b: &[u8], at: usize) -> Option { } /// Whether `b` ends with a Bento label. -pub(crate) fn sniff(b: &[u8]) -> bool { +pub fn sniff(b: &[u8]) -> bool { b.len() >= LABEL_SIZE && b[b.len() - LABEL_SIZE..b.len() - LABEL_SIZE + 8] == MAGIC } impl<'a> Container<'a> { + /// Object identifiers in ascending order. + pub fn object_ids(&self) -> impl Iterator + '_ { + self.objects.keys().copied() + } + pub fn open(data: &'a [u8]) -> Result, String> { if !sniff(data) { return Err("no Bento label at the end of the file".into()); @@ -324,7 +335,7 @@ impl<'a> Container<'a> { } /// The bytes of a value. - pub fn value(&self, p: &Prop) -> Result, String> { + pub(crate) fn value(&self, p: &Prop) -> Result, String> { let total = p.segs.iter().try_fold(0usize, |total, s| { let len = match s { Seg::Imm(b) => b.len(), diff --git a/crates/aaf/tests/bento_api.rs b/crates/aaf/tests/bento_api.rs new file mode 100644 index 000000000..9df70c661 --- /dev/null +++ b/crates/aaf/tests/bento_api.rs @@ -0,0 +1,17 @@ +use craft_aaf::omf::bento::{Container, Writer, sniff}; + +#[test] +fn external_consumer_reads_named_values_and_references() { + let mut writer = Writer::new(); + let first = writer.new_object(); + let second = writer.new_object(); + writer.set(first, "test:value", "test:type", b"long value"); + writer.set_references(first, &[second]); + let bytes = writer.finish(); + assert!(sniff(&bytes)); + let container = Container::open(&bytes).unwrap(); + assert!(container.object_ids().any(|id| id == first)); + assert_eq!(container.get(first, "test:value").as_deref(), Some(b"long value".as_slice())); + assert_eq!(container.resolve(first, second), second); + assert!(Container::open(&bytes[..bytes.len() - 1]).is_err()); +} From a88aab72c4620d1956196ec51107c3ca9c241a52 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:58:28 +0000 Subject: [PATCH 079/349] aaf: bound duplicate property detection work --- crates/aaf/src/aaf/hostile_tests.rs | 16 ++++++++++++++++ crates/aaf/src/aaf/store.rs | 4 +++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/crates/aaf/src/aaf/hostile_tests.rs b/crates/aaf/src/aaf/hostile_tests.rs index 853b0000c..527e50da8 100644 --- a/crates/aaf/src/aaf/hostile_tests.rs +++ b/crates/aaf/src/aaf/hostile_tests.rs @@ -108,3 +108,19 @@ fn objects_nested_too_deeply_are_an_error() { let e = store::read(&chain(250)).unwrap_err(); assert!(e.contains("nested too deeply"), "{e}"); } + +/// Many distinct property IDs still reject a duplicate without quadratic scanning. +#[test] +fn duplicate_after_many_distinct_properties_is_rejected() { + let mut props = vec![0x4C, 0x20]; + props.extend_from_slice(&8193u16.to_le_bytes()); + for id in (0..8192u16).chain(std::iter::once(7)) { + props.extend_from_slice(&id.to_le_bytes()); + props.extend_from_slice(&0x82u16.to_le_bytes()); + props.extend_from_slice(&0u16.to_le_bytes()); + } + let mut writer = Writer::new(Version::V3); + writer.stream(Writer::ROOT, "properties", props).unwrap(); + let e = store::read(&writer.finish()).unwrap_err(); + assert!(e.contains("duplicate property id"), "{e}"); +} diff --git a/crates/aaf/src/aaf/store.rs b/crates/aaf/src/aaf/store.rs index 69b14fcf2..859c0ea77 100644 --- a/crates/aaf/src/aaf/store.rs +++ b/crates/aaf/src/aaf/store.rs @@ -461,11 +461,13 @@ impl R<'_> { if at > props.len() { return Err(bad("truncated property index")); } + // A properties stream can name tens of thousands of ids: do not rescan all earlier ids. + let mut seen = std::collections::HashSet::with_capacity(n); for i in 0..n { let (Some(pid), Some(sf), Some(len)) = (rd_u16(&props, 4 + i * 6), rd_u16(&props, 6 + i * 6), rd_u16(&props, 8 + i * 6)) else { return Err(bad("truncated property index")); }; - if o.props.iter().any(|(previous, _)| *previous == pid) { + if !seen.insert(pid) { return Err(bad("duplicate property id")); } let v = props.get(at..at + len as usize).ok_or_else(|| bad("truncated property value"))?; From 6345459e1297ee85a7ca62b428a440691bd062c1 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:59:23 +0000 Subject: [PATCH 080/349] Share MTEXT Unicode and MIF escape decoding --- crates/dxf/src/lib.rs | 1 + crates/dxf/src/mtext.rs | 103 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+) create mode 100644 crates/dxf/src/mtext.rs diff --git a/crates/dxf/src/lib.rs b/crates/dxf/src/lib.rs index 4cf3e46e9..9c912613b 100644 --- a/crates/dxf/src/lib.rs +++ b/crates/dxf/src/lib.rs @@ -11,6 +11,7 @@ use std::io::Write as _; pub mod model; +pub mod mtext; pub mod paths; mod version; pub use version::Version; diff --git a/crates/dxf/src/mtext.rs b/crates/dxf/src/mtext.rs new file mode 100644 index 000000000..9b113aa6c --- /dev/null +++ b/crates/dxf/src/mtext.rs @@ -0,0 +1,103 @@ +//! MTEXT inline-escape handling independent of drawing and text layout. +//! +//! Unicode and MIF escapes are decoded to literal characters, with markup-significant +//! characters re-escaped so subsequent MTEXT parsers cannot treat them as commands. + +/// Whether an inline command takes an argument terminated by `;`. +pub fn takes_arg(code: char) -> bool { + matches!(code, 'f' | 'F' | 'H' | 'W' | 'Q' | 'T' | 'A' | 'C' | 'c' | 'p') +} + +/// Four hex digits at `chars[at..at + 4]`. +fn hex4(chars: &[char], at: usize) -> Option { + let digits = chars.get(at..at.checked_add(4)?)?; + digits.iter().try_fold(0u32, |acc, c| Some(acc * 16 + c.to_digit(16)?)) +} + +/// Push a decoded character so that the tokenizers read it as text, never as markup. +fn push_literal(out: &mut String, c: char) { + if matches!(c, '\\' | '{' | '}') { + out.push('\\'); + } + out.push(c); +} + +/// Decode `\U+hhhh` (one UTF-16 unit; a surrogate pair gives one character, a lone surrogate +/// U+FFFD) and `\M+nhhhh` (double-byte East Asian characters) to the characters they stand +/// for. Malformed escapes remain unchanged for the caller to interpret. +/// An escaped backslash (`\\U+0041`) is not an escape. +pub fn unescape_codes(s: &str) -> std::borrow::Cow<'_, str> { + if !s.contains("\\U+") && !s.contains("\\M+") { + return std::borrow::Cow::Borrowed(s); + } + let chars: Vec = s.chars().collect(); + let mut out = String::with_capacity(s.len()); + let mut i = 0; + while let Some(&c) = chars.get(i) { + if c != '\\' { + out.push(c); + i += 1; + continue; + } + let (n, plus) = (chars.get(i + 1).copied(), chars.get(i + 2).copied()); + if n == Some('U') && plus == Some('+') { + if let Some(unit) = hex4(&chars, i + 3) { + i += 7; + let low = |at: usize| { + (chars.get(at) == Some(&'\\') && chars.get(at + 1) == Some(&'U') && chars.get(at + 2) == Some(&'+')) + .then(|| hex4(&chars, at + 3)) + .flatten() + .filter(|u| (0xDC00..0xE000).contains(u)) + }; + let ch = if (0xD800..0xDC00).contains(&unit) { + match low(i) { + Some(lo) => { + i += 7; + char::from_u32(0x10000 + ((unit - 0xD800) << 10) + (lo - 0xDC00)) + } + None => None, + } + } else { + char::from_u32(unit) + }; + push_literal(&mut out, ch.unwrap_or('\u{fffd}')); + continue; + } + } else if n == Some('M') && plus == Some('+') && chars.get(i + 3).is_some_and(char::is_ascii_digit) && hex4(&chars, i + 4).is_some() { + push_literal(&mut out, crate::mif_escape_at(&chars, i).unwrap_or('\u{fffd}')); + i += 8; + continue; + } + // Any other backslash pair stays as it is (and an escaped backslash stays one). + out.push('\\'); + i += 1; + if let Some(&next) = chars.get(i) { + out.push(next); + i += 1; + } + } + std::borrow::Cow::Owned(out) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn unicode_and_mif_escapes_remain_literal_markup() { + assert_eq!(unescape_codes(r"a\U+0041\U+D83D\U+DE00"), "aA😀"); + assert_eq!(unescape_codes(r"\M+5BCFE"), "件"); + assert_eq!(unescape_codes(r"\U+005C\U+007B\U+007D"), r"\\\{\}"); + assert_eq!(unescape_codes(r"\\U+0041"), r"\\U+0041"); + assert_eq!(unescape_codes(r"\U+12"), r"\U+12"); + assert_eq!(unescape_codes(r"\U+D800"), "�"); + } + #[test] + fn parameterized_commands_are_classified_without_relaxing_others() { + for c in "fFHWQTACcp".chars() { + assert!(takes_arg(c)); + } + for c in ['S', 'P', 'Z', '\\'] { + assert!(!takes_arg(c)); + } + } +} From 99e448d9199191e86a7dddc6b39a5a1e29aad24c Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 15:58:28 +0000 Subject: [PATCH 081/349] aaf: bound duplicate property detection work --- crates/aaf/src/aaf/hostile_tests.rs | 16 ++++++++++++++++ crates/aaf/src/aaf/store.rs | 4 +++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/crates/aaf/src/aaf/hostile_tests.rs b/crates/aaf/src/aaf/hostile_tests.rs index 853b0000c..527e50da8 100644 --- a/crates/aaf/src/aaf/hostile_tests.rs +++ b/crates/aaf/src/aaf/hostile_tests.rs @@ -108,3 +108,19 @@ fn objects_nested_too_deeply_are_an_error() { let e = store::read(&chain(250)).unwrap_err(); assert!(e.contains("nested too deeply"), "{e}"); } + +/// Many distinct property IDs still reject a duplicate without quadratic scanning. +#[test] +fn duplicate_after_many_distinct_properties_is_rejected() { + let mut props = vec![0x4C, 0x20]; + props.extend_from_slice(&8193u16.to_le_bytes()); + for id in (0..8192u16).chain(std::iter::once(7)) { + props.extend_from_slice(&id.to_le_bytes()); + props.extend_from_slice(&0x82u16.to_le_bytes()); + props.extend_from_slice(&0u16.to_le_bytes()); + } + let mut writer = Writer::new(Version::V3); + writer.stream(Writer::ROOT, "properties", props).unwrap(); + let e = store::read(&writer.finish()).unwrap_err(); + assert!(e.contains("duplicate property id"), "{e}"); +} diff --git a/crates/aaf/src/aaf/store.rs b/crates/aaf/src/aaf/store.rs index 69b14fcf2..859c0ea77 100644 --- a/crates/aaf/src/aaf/store.rs +++ b/crates/aaf/src/aaf/store.rs @@ -461,11 +461,13 @@ impl R<'_> { if at > props.len() { return Err(bad("truncated property index")); } + // A properties stream can name tens of thousands of ids: do not rescan all earlier ids. + let mut seen = std::collections::HashSet::with_capacity(n); for i in 0..n { let (Some(pid), Some(sf), Some(len)) = (rd_u16(&props, 4 + i * 6), rd_u16(&props, 6 + i * 6), rd_u16(&props, 8 + i * 6)) else { return Err(bad("truncated property index")); }; - if o.props.iter().any(|(previous, _)| *previous == pid) { + if !seen.insert(pid) { return Err(bad("duplicate property id")); } let v = props.get(at..at + len as usize).ok_or_else(|| bad("truncated property value"))?; From f751827790237ed116980c3f981f2e2b72d788a1 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:01:42 +0000 Subject: [PATCH 082/349] audio: share streaming PCM export encoding --- crates/audio/src/lib.rs | 3 + crates/audio/src/pcm_export.rs | 264 +++++++++++++++++++++++++++++++++ 2 files changed, 267 insertions(+) create mode 100644 crates/audio/src/pcm_export.rs diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index 33dcdee3b..4a5f352d1 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -66,6 +66,9 @@ mod wav; feature = "vorbis-encode" ))] mod write; + +/// Streaming WAVE and AIFF headers and sample packing. +pub mod pcm_export; #[cfg(feature = "vorbis-encode")] pub use write::{OGG_BITRATES, encode_ogg}; diff --git a/crates/audio/src/pcm_export.rs b/crates/audio/src/pcm_export.rs new file mode 100644 index 000000000..c8456d785 --- /dev/null +++ b/crates/audio/src/pcm_export.rs @@ -0,0 +1,264 @@ +//! Audio-only files: WAV (RIFF, little-endian PCM; RF64 past 4 GiB) and AIFF (big-endian PCM), +//! 16, 24 or 32-bit integer or 32-bit float ([`SampleFormat`]), for streaming export. +//! Float WAV is `WAVE_FORMAT_IEEE_FLOAT` with a `fact` chunk; float AIFF is AIFF-C (`fl32`). +//! +//! The header is written first from the known length ([`header`]), then the samples in chunks +//! ([`encode`]) and the pad byte ([`pad`]), so an export streams to disk instead of building the +//! file in memory. + +/// PCM representation in an exported file. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum SampleFormat { + /// 16-bit signed integer. + Int16, + /// 24-bit signed integer. + Int24, + /// 32-bit signed integer. + Int32, + /// 32-bit IEEE float. + Float32, +} + +impl SampleFormat { + /// Bits per sample. + pub fn bits(self) -> u16 { + match self { + Self::Int16 => 16, + Self::Int24 => 24, + Self::Int32 | Self::Float32 => 32, + } + } + /// Bytes per sample. + pub fn bytes(self) -> usize { + usize::from(self.bits() / 8) + } + /// Whether this is a floating point format. + pub fn is_float(self) -> bool { + self == Self::Float32 + } + /// Clip and quantize one sample with symmetric integer full scale; NaN becomes silence. + pub fn quantise(self, s: f32) -> i32 { + let s = s.clamp(-1.0, 1.0); + match self { + Self::Int16 => (s * 32_767.0).round() as i32, + Self::Int24 => (s * 8_388_607.0).round() as i32, + Self::Int32 => (f64::from(s) * 2_147_483_647.0).round() as i32, + Self::Float32 => 0, + } + } + /// Sanitize a floating sample: NaN becomes silence, infinity becomes the largest finite value. + pub fn float(s: f32) -> f32 { + if s.is_nan() { 0.0 } else { s.clamp(f32::MIN, f32::MAX) } + } +} + +/// The container of an audio-only export. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PcmContainer { + /// RIFF/WAVE or RF64. + Wav, + /// AIFF or AIFF-C. + Aiff, +} + +/// Bytes of sample data for `frames` frames, or None when that does not fit 64 bits. +fn data_len(frames: u64, channels: u16, format: SampleFormat) -> Option { + frames.checked_mul(u64::from(channels))?.checked_mul(format.bytes() as u64) +} + +/// The pad byte after an odd-sized data chunk (RIFF and AIFF chunks are word-aligned). +pub fn pad(frames: u64, channels: u16, format: SampleFormat) -> &'static [u8] { + if data_len(frames, channels, format).is_some_and(|n| n & 1 == 1) { &[0] } else { &[] } +} + +/// `KSDATAFORMAT_SUBTYPE_PCM` / `_IEEE_FLOAT` after their first two bytes (the format tag). +const SUBTYPE_TAIL: [u8; 14] = [0x00, 0x00, 0x00, 0x00, 0x10, 0x00, 0x80, 0x00, 0x00, 0xAA, 0x00, 0x38, 0x9B, 0x71]; + +/// AIFF-C format version 1 (`FVER`). +const AIFC_VERSION_1: u32 = 0xA280_5140; + +/// The AIFF-C compression name of `fl32`, as a Pascal string of even length. +const FL32_NAME: &[u8] = b"\x1532-bit floating point"; + +/// Everything before the samples of a file of `frames` frames. A WAV whose RIFF size would not +/// fit 32 bits (4 GiB: 24-bit 5.1 at 96 kHz after about 41 minutes) is written as RF64 (EBU Tech +/// 3306), with the 64-bit sizes in a `ds64` chunk. AIFF has no 64-bit form, so a longer AIFF is +/// an error naming WAV instead. +pub fn header(container: PcmContainer, channels: u16, sample_rate: u32, format: SampleFormat, frames: u64) -> Result, String> { + let too_long = || "the audio is too long to write".to_string(); + let bits = format.bits(); + let bps = bits / 8; + let float = format.is_float(); + let data = data_len(frames, channels, format).ok_or_else(too_long)?; + let block_align = channels.checked_mul(bps).ok_or("too many audio channels")?; + match container { + PcmContainer::Wav => { + let byte_rate = + u32::try_from(u64::from(sample_rate) * u64::from(block_align)).map_err(|_| "the audio sample rate is too high".to_string())?; + let ext = channels > 2; + // plain PCM has no cbSize; IEEE float has an empty one + let fmt_len: u32 = if ext { + 40 + } else if float { + 18 + } else { + 16 + }; + // every format but integer PCM has a `fact` chunk (the frame count; RF64: in `ds64`) + let fact_len: u64 = if float { 12 } else { 0 }; + let padded = data.checked_add(data & 1).ok_or_else(too_long)?; + // "WAVE" + fmt chunk + fact chunk + data chunk header + samples + let riff = (4 + 8 + u64::from(fmt_len) + fact_len + 8).checked_add(padded).ok_or_else(too_long)?; + let rf64 = riff > u64::from(u32::MAX); + let mut v = Vec::with_capacity(100); + if rf64 { + const DS64: u64 = 8 + 28; + v.extend_from_slice(b"RF64"); + v.extend_from_slice(&u32::MAX.to_le_bytes()); + v.extend_from_slice(b"WAVEds64"); + v.extend_from_slice(&28u32.to_le_bytes()); + v.extend_from_slice(&riff.checked_add(DS64).ok_or_else(too_long)?.to_le_bytes()); + v.extend_from_slice(&data.to_le_bytes()); + v.extend_from_slice(&frames.to_le_bytes()); + v.extend_from_slice(&0u32.to_le_bytes()); // no table entries + } else { + v.extend_from_slice(b"RIFF"); + v.extend_from_slice(&(riff as u32).to_le_bytes()); + v.extend_from_slice(b"WAVE"); + } + let tag: u16 = if float { 3 } else { 1 }; + v.extend_from_slice(b"fmt "); + v.extend_from_slice(&fmt_len.to_le_bytes()); + v.extend_from_slice(&(if ext { 0xFFFE } else { tag }).to_le_bytes()); + v.extend_from_slice(&channels.to_le_bytes()); + v.extend_from_slice(&sample_rate.to_le_bytes()); + v.extend_from_slice(&byte_rate.to_le_bytes()); + v.extend_from_slice(&block_align.to_le_bytes()); + v.extend_from_slice(&bits.to_le_bytes()); + if ext { + // cbSize, valid bits, channel mask, KSDATAFORMAT_SUBTYPE_PCM / _IEEE_FLOAT + v.extend_from_slice(&22u16.to_le_bytes()); + v.extend_from_slice(&bits.to_le_bytes()); + let mask: u32 = if channels == 6 { 0x3F } else { 0 }; + v.extend_from_slice(&mask.to_le_bytes()); + v.extend_from_slice(&tag.to_le_bytes()); + v.extend_from_slice(&SUBTYPE_TAIL); + } else if float { + v.extend_from_slice(&0u16.to_le_bytes()); + } + if float { + v.extend_from_slice(b"fact"); + v.extend_from_slice(&4u32.to_le_bytes()); + v.extend_from_slice(&(if rf64 { u32::MAX } else { u32::try_from(frames).unwrap_or(u32::MAX) }).to_le_bytes()); + } + v.extend_from_slice(b"data"); + v.extend_from_slice(&(if rf64 { u32::MAX } else { data as u32 }).to_le_bytes()); + Ok(v) + } + PcmContainer::Aiff => { + let aiff_too_long = || "AIFF holds at most 4 GB of audio: export WAV, which has no such limit".to_string(); + let frames32 = u32::try_from(frames).map_err(|_| aiff_too_long())?; + // SSND: offset + block size + samples + let ssnd = u32::try_from(data.checked_add(8).ok_or_else(aiff_too_long)?).map_err(|_| aiff_too_long())?; + // floats need AIFF-C: a version chunk, and the compression type and name in COMM + let comm: u32 = if float { 18 + 4 + FL32_NAME.len() as u32 } else { 18 }; + let fver: u32 = if float { 8 + 4 } else { 0 }; + let form = (4u32 + fver + (8 + comm)) + .checked_add(8) + .and_then(|n| n.checked_add(ssnd)) + .and_then(|n| n.checked_add(ssnd & 1)) + .ok_or_else(aiff_too_long)?; + let mut v = Vec::with_capacity(90); + v.extend_from_slice(b"FORM"); + v.extend_from_slice(&form.to_be_bytes()); + if float { + v.extend_from_slice(b"AIFCFVER"); + v.extend_from_slice(&4u32.to_be_bytes()); + v.extend_from_slice(&AIFC_VERSION_1.to_be_bytes()); + } else { + v.extend_from_slice(b"AIFF"); + } + v.extend_from_slice(b"COMM"); + v.extend_from_slice(&comm.to_be_bytes()); + v.extend_from_slice(&channels.to_be_bytes()); + v.extend_from_slice(&frames32.to_be_bytes()); + v.extend_from_slice(&bits.to_be_bytes()); + v.extend_from_slice(&extended(sample_rate)); + if float { + v.extend_from_slice(b"fl32"); + v.extend_from_slice(FL32_NAME); + } + v.extend_from_slice(b"SSND"); + v.extend_from_slice(&ssnd.to_be_bytes()); + v.extend_from_slice(&0u32.to_be_bytes()); // offset + v.extend_from_slice(&0u32.to_be_bytes()); // block size + Ok(v) + } + } +} + +/// Append interleaved samples in `format` (little-endian for WAV, big-endian for AIFF). +pub fn encode(container: PcmContainer, interleaved: &[f32], format: SampleFormat, out: &mut Vec) { + let bps = format.bytes(); + out.reserve(interleaved.len().saturating_mul(bps)); + for &s in interleaved { + let q = if format.is_float() { SampleFormat::float(s).to_bits() as i32 } else { format.quantise(s) }; + match container { + PcmContainer::Wav => out.extend_from_slice(q.to_le_bytes().get(..bps).unwrap_or_default()), + PcmContainer::Aiff => out.extend_from_slice(q.to_be_bytes().get(4 - bps..).unwrap_or_default()), + } + } +} + +/// A whole file in memory (short audio; exports stream with [`header`] and [`encode`]). +fn write_whole(container: PcmContainer, interleaved: &[f32], channels: u16, sample_rate: u32, format: SampleFormat) -> Result, String> { + let frames = (interleaved.len() / usize::from(channels.max(1))) as u64; + let mut v = header(container, channels, sample_rate, format, frames)?; + encode(container, interleaved, format, &mut v); + v.extend_from_slice(pad(frames, channels, format)); + Ok(v) +} + +/// A RIFF/WAVE file of interleaved samples. More than two channels are written as +/// `WAVE_FORMAT_EXTENSIBLE` with the speaker mask of the layout (6 channels: L, R, C, LFE, Ls, Rs +/// = `0x3F`). +pub fn write_wav(interleaved: &[f32], channels: u16, sample_rate: u32, format: SampleFormat) -> Result, String> { + write_whole(PcmContainer::Wav, interleaved, channels, sample_rate, format) +} + +/// IEEE 754 80-bit extended encoding of a sample rate (AIFF `COMM`). +pub fn extended(rate: u32) -> [u8; 10] { + let mut out = [0u8; 10]; + if rate == 0 { + return out; + } + let shift = rate.leading_zeros(); + let mant = (rate as u64) << (32 + shift); + let exp = 16383 + 31 - shift as u16; + out[..2].copy_from_slice(&exp.to_be_bytes()); + out[2..].copy_from_slice(&mant.to_be_bytes()); + out +} + +/// An AIFF file (`FORM`/`AIFF`, `COMM` + `SSND`; AIFF-C for floats) of interleaved samples. +pub fn write_aiff(interleaved: &[f32], channels: u16, sample_rate: u32, format: SampleFormat) -> Result, String> { + write_whole(PcmContainer::Aiff, interleaved, channels, sample_rate, format) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn streaming_formats_preserve_samples_and_bounds() { + let samples = [1.0, -1.0, f32::NAN]; + let wav = write_wav(&samples, 1, 48_000, SampleFormat::Int24).unwrap(); + assert_eq!(&wav[..4], b"RIFF"); + assert_eq!(&wav[44..53], &[255, 255, 127, 1, 0, 128, 0, 0, 0]); + let h = header(PcmContainer::Wav, 6, 96_000, SampleFormat::Int24, 96_000 * 3600).unwrap(); + assert_eq!(&h[..4], b"RF64"); + assert!(header(PcmContainer::Aiff, 2, 48_000, SampleFormat::Int24, u64::MAX).is_err()); + let aiff = write_aiff(&[0.25, -3.0], 1, 44_100, SampleFormat::Float32).unwrap(); + assert_eq!(&aiff[8..12], b"AIFC"); + assert_eq!(&aiff[aiff.len() - 8..], [0.25f32.to_be_bytes(), (-3.0f32).to_be_bytes()].concat()); + } +} From b1d4c67196ee7c6b668428c8d211e7d5171dff88 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:02:52 +0000 Subject: [PATCH 083/349] Add streaming MTEXT lexical tokens --- crates/dxf/src/lib.rs | 1 + crates/dxf/src/mtext_tokens.rs | 132 +++++++++++++++++++++++++++++++++ 2 files changed, 133 insertions(+) create mode 100644 crates/dxf/src/mtext_tokens.rs diff --git a/crates/dxf/src/lib.rs b/crates/dxf/src/lib.rs index 9c912613b..7543fb28b 100644 --- a/crates/dxf/src/lib.rs +++ b/crates/dxf/src/lib.rs @@ -12,6 +12,7 @@ use std::io::Write as _; pub mod model; pub mod mtext; +pub mod mtext_tokens; pub mod paths; mod version; pub use version::Version; diff --git a/crates/dxf/src/mtext_tokens.rs b/crates/dxf/src/mtext_tokens.rs new file mode 100644 index 000000000..b07a9c2e0 --- /dev/null +++ b/crates/dxf/src/mtext_tokens.rs @@ -0,0 +1,132 @@ +//! Streaming lexical tokens for MTEXT inline markup. +//! +//! Apply [`crate::mtext::unescape_codes`] first when Unicode/MIF escapes should become literal +//! characters. Tokens borrow their source and scanning allocates no memory. The consumer owns +//! formatting, line layout, paragraph policy and how unknown commands are displayed. + +/// How a stacked-text argument finds its closing semicolon. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum StackMode { + /// The first semicolon ends the stack, as plain-text extraction historically did. + Plain, + /// A backslash quotes the next character, as the structured layout parser does. + Structured, +} +/// One lexical unit. Unknown commands retain their letter so the caller chooses compatibility. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Token<'a> { + Char(char), + OpenGroup, + CloseGroup, + Control(char), + Argument(char, &'a str), + Stack(&'a str), + Unknown(char), +} +/// A bounded-memory walk of UTF-8 MTEXT markup. +pub struct Tokens<'a> { + source: &'a str, + offset: usize, + stack_mode: StackMode, +} +impl<'a> Tokens<'a> { + pub fn new(source: &'a str, stack_mode: StackMode) -> Self { + Self { source, offset: 0, stack_mode } + } + fn next_char(&mut self) -> Option { + let c = self.source.get(self.offset..)?.chars().next()?; + self.offset += c.len_utf8(); + Some(c) + } + fn argument(&mut self, structured: bool) -> &'a str { + let start = self.offset; + let mut end = start; + while let Some(c) = self.next_char() { + if c == ';' { + return self.source.get(start..end).unwrap_or_default(); + } + if structured && c == '\\' { + let _ = self.next_char(); + } + end = self.offset; + } + self.source.get(start..end).unwrap_or_default() + } +} +impl<'a> Iterator for Tokens<'a> { + type Item = Token<'a>; + fn next(&mut self) -> Option { + let c = self.next_char()?; + Some(match c { + '{' => Token::OpenGroup, + '}' => Token::CloseGroup, + '\\' => { + let code = self.next_char()?; + match code { + 'S' => Token::Stack(self.argument(self.stack_mode == StackMode::Structured)), + c if crate::mtext::takes_arg(c) => Token::Argument(c, self.argument(false)), + c @ ('P' | 'N' | '~' | '\\' | '{' | '}' | 'L' | 'l' | 'O' | 'o' | 'K' | 'k') => Token::Control(c), + c => Token::Unknown(c), + } + } + c => Token::Char(c), + }) + } +} +/// Split a structured stack into top, bottom and separator, unquoting escaped characters. +pub fn split_stack(raw: &str) -> (String, String, Option) { + let (mut top, mut bottom, mut separator) = (String::new(), String::new(), None); + let mut chars = raw.chars(); + while let Some(c) = chars.next() { + if c == '\\' { + if let Some(c) = chars.next() { + if separator.is_none() { + top.push(c); + } else { + bottom.push(c); + } + } + } else if separator.is_none() && matches!(c, '/' | '#' | '^') { + separator = Some(c); + } else if separator.is_none() { + top.push(c); + } else { + bottom.push(c); + } + } + (top, bottom, separator) +} +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn tokens_borrow_text_and_preserve_unknown_commands() { + let got: Vec<_> = Tokens::new(r"A\Z\P{\H2x;x}\S1/2;", StackMode::Structured).collect(); + assert_eq!( + got, + [ + Token::Char('A'), + Token::Unknown('Z'), + Token::Control('P'), + Token::OpenGroup, + Token::Argument('H', "2x"), + Token::Char('x'), + Token::CloseGroup, + Token::Stack("1/2") + ] + ); + assert_eq!(split_stack("1/2"), ("1".into(), "2".into(), Some('/'))); + } + #[test] + fn stacked_text_uses_the_requested_terminator_rules() { + let text = r"\Sa\;b/c;X"; + assert_eq!(Tokens::new(text, StackMode::Plain).next(), Some(Token::Stack(r"a\"))); + assert_eq!(Tokens::new(text, StackMode::Structured).next(), Some(Token::Stack(r"a\;b/c"))); + assert_eq!(split_stack(r"a\;b/c"), ("a;b".into(), "c".into(), Some('/'))); + } + #[test] + fn missing_terminator_and_trailing_backslash_are_bounded() { + assert_eq!(Tokens::new("\\H2x", StackMode::Structured).collect::>(), [Token::Argument('H', "2x")]); + assert_eq!(Tokens::new("a\\", StackMode::Structured).collect::>(), [Token::Char('a')]); + } +} From 6b82b6a77c995847084311402d27a6361b6491ed Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:05:22 +0000 Subject: [PATCH 084/349] aaf: support legacy reference and locator conventions --- crates/aaf/src/aaf.rs | 47 +++++++++++++++++++++++++++++++++++-- crates/aaf/src/aaf/read.rs | 32 +++++++++++++++++++------ crates/aaf/src/aaf/tests.rs | 29 +++++++++++++++++++++++ crates/aaf/src/aaf/write.rs | 18 ++++++++++---- 4 files changed, 113 insertions(+), 13 deletions(-) diff --git a/crates/aaf/src/aaf.rs b/crates/aaf/src/aaf.rs index 05894f94e..efa618fb3 100644 --- a/crates/aaf/src/aaf.rs +++ b/crates/aaf/src/aaf.rs @@ -57,13 +57,56 @@ pub struct WriteOptions<'a> { /// reported. pub fn write(doc: &Document, opts: &WriteOptions<'_>, report: &mut Report) -> Result> { let version = if opts.small_sectors { craft_cfb::Version::V3 } else { craft_cfb::Version::V4 }; - write::write(doc, version, &opts.identity, report) + write::write(doc, version, &opts.identity, &ReferenceOptions::default(), report) +} + +/// Optional interpretation choices for applications retaining older interchange behavior. +#[derive(Clone, Copy, Debug)] +pub struct ReadOptions { + /// Interpret a source clip's start using its target slot's edit rate. + pub source_slot_rate: bool, + /// Use the referenced mob name when the clip has no explicit name. + pub infer_clip_name: bool, + /// Decode percent escapes in relative network locators. + pub decode_relative_locator: bool, + /// Report selector and nested-scope flattening. + pub report_flattening: bool, + /// Accept truncated PCM WAVE essence summaries. + pub permissive_pcm: bool, +} +impl Default for ReadOptions { + fn default() -> Self { + Self { source_slot_rate: true, infer_clip_name: true, decode_relative_locator: true, report_flattening: true, permissive_pcm: false } + } +} +/// Read using explicitly selected interpretation choices. +pub fn read_with_options(bytes: &[u8], options: &ReadOptions, report: &mut Report) -> Result { + read::read(bytes, options, report) +} + +/// Optional compatibility choices for writing source references and locators. +#[derive(Clone, Copy, Debug)] +pub struct ReferenceOptions { + /// Write source offsets in target-slot units. + pub source_slot_rate: bool, + /// Percent-encode relative locators. + pub encode_relative_locator: bool, +} +impl Default for ReferenceOptions { + fn default() -> Self { + Self { source_slot_rate: true, encode_relative_locator: true } + } +} +/// Write with explicitly selected reference and locator conventions. +pub fn write_with_references(doc: &Document, opts: &WriteOptions<'_>, references: &ReferenceOptions, report: &mut Report) -> Result> { + let version = if opts.small_sectors { craft_cfb::Version::V3 } else { craft_cfb::Version::V4 }; + write::write(doc, version, &opts.identity, references, report) } /// Read an AAF file: its top-level compositions, the compositions nested in them and their /// sources. What cannot be represented is skipped and named in `report`. pub fn read(bytes: &[u8], report: &mut Report) -> Result { - read::read(bytes, report) + read::read(bytes, &ReadOptions::default(), report) } /// Whether `bytes` look like an AAF file (a compound file whose root has the AAF root class or a diff --git a/crates/aaf/src/aaf/read.rs b/crates/aaf/src/aaf/read.rs index 31c841c5d..9739f87ba 100644 --- a/crates/aaf/src/aaf/read.rs +++ b/crates/aaf/src/aaf/read.rs @@ -67,6 +67,7 @@ fn indirect_f64(d: &[u8]) -> Option { struct R<'a> { report: &'a mut Report, + options: super::ReadOptions, mobs: HashMap, essence: HashMap, doc: Document, @@ -90,7 +91,7 @@ struct NestClip<'a> { /// Compositions nested deeper than this are read as gaps. const MAX_NESTING: usize = 16; -pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { +pub(crate) fn read(bytes: &[u8], options: &super::ReadOptions, report: &mut Report) -> Result { let root = store::read(bytes).map_err(|e| Error::Parse { format: "AAF", message: e })?; let header = root.strong(pid::ROOT_HEADER).ok_or_else(|| Error::Parse { format: "AAF", message: "no header object".into() })?; let content = header.strong(pid::CONTENT).ok_or_else(|| Error::Parse { format: "AAF", message: "no content storage".into() })?; @@ -106,7 +107,8 @@ pub(crate) fn read(bytes: &[u8], report: &mut Report) -> Result { essence.insert(id, d); } } - let mut r = R { report, mobs, essence, doc: Document::default(), sources: HashMap::new(), nests: HashMap::new(), open: Vec::new() }; + let mut r = + R { report, options: *options, mobs, essence, doc: Document::default(), sources: HashMap::new(), nests: HashMap::new(), open: Vec::new() }; // Top-level compositions: those no other composition uses, among the ones tagged top-level // when any are. (Premiere Pro tags a nested sequence's composition top-level too; it is still // only a nested sequence.) Compositions that only use each other in a circle all count. The @@ -331,7 +333,9 @@ impl R<'_> { items } x if x == cls::SELECTOR => { - self.report.info("a selector was flattened to its selected input"); + if self.options.report_flattening { + self.report.info("a selector was flattened to its selected input"); + } match c.strong(pid::SELECTED) { Some(s) => { let mut items = self.segment(s, rate, kind, depth); @@ -342,7 +346,9 @@ impl R<'_> { } } x if x == cls::NESTED_SCOPE => { - self.report.info("a nested scope was flattened to its final input"); + if self.options.report_flattening { + self.report.info("a nested scope was flattened to its final input"); + } match c.objs(pid::NESTED_SLOTS).last() { Some(s) => { let mut items = self.segment(s, rate, kind, depth); @@ -388,7 +394,12 @@ impl R<'_> { let len = units_to_ticks(len_of(c), rate.0, rate.1); let tagged_name = tagged_values(c, pid::COMPONENT_USER_COMMENTS).into_iter().find(|(k, _)| k == "Clip Name").map(|(_, v)| v); let (Some(id), Some(slot)) = (c.mob_id(pid::SOURCE_ID), c.u32(pid::SOURCE_MOB_SLOT_ID)) else { return CItem::Filler(len) }; - let name = tagged_name.or_else(|| self.mobs.get(&id).and_then(|mob| mob.string(pid::MOB_NAME))).unwrap_or_default(); + let name = if self.options.infer_clip_name { + tagged_name.or_else(|| self.mobs.get(&id).and_then(|mob| mob.string(pid::MOB_NAME))) + } else { + tagged_name + } + .unwrap_or_default(); if id == [0; 32] { return CItem::Filler(len); } @@ -401,6 +412,7 @@ impl R<'_> { .and_then(|mob| mob.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(slot))) .and_then(|s| rate_of(s, pid::EDIT_RATE)) .unwrap_or(rate); + let source_rate = if self.options.source_slot_rate { source_rate } else { rate }; let start = units_to_ticks(c.i64(pid::START_TIME).unwrap_or(0), source_rate.0, source_rate.1); match self.resolve(id, slot, start, kind, master_key, 0) { Some((source, t)) => CItem::Clip(CClip { len, source, start: t, gain: None, name }), @@ -506,6 +518,7 @@ impl R<'_> { .and_then(|m| m.objs(pid::SLOTS).iter().find(|s| s.u32(pid::SLOT_ID) == Some(next_slot))) .and_then(|s| rate_of(s, pid::EDIT_RATE)) .unwrap_or(rate); + let source_rate = if self.options.source_slot_rate { source_rate } else { rate }; let inner = units_to_ticks(clip.i64(pid::START_TIME).unwrap_or(0), source_rate.0, source_rate.1); if next == [0; 32] { return None; @@ -545,7 +558,11 @@ impl R<'_> { DataKind::Sound => CKind::Sound, _ => kind, }; - let path = d.objs(pid::LOCATOR).iter().find_map(|l| l.string(pid::URL_STRING)).map(|u| locator_path(&u)); + let path = d + .objs(pid::LOCATOR) + .iter() + .find_map(|l| l.string(pid::URL_STRING)) + .map(|u| if self.options.decode_relative_locator { locator_path(&u) } else { craft_timeline::path::file_url_to_path(&u) }); let file_rate = rate_of(d, pid::SAMPLE_RATE).unwrap_or(rate); let length = d .i64(pid::FILE_LENGTH) @@ -604,7 +621,8 @@ impl R<'_> { if let Some(data) = self.essence.get(&id) { s.embedded = Some(data.to_vec()); // embedded essence may be a whole WAVE / AIFF file - if let Some((pcm, ch, sr, bits)) = crate::pcm::parse_wav(data) { + let pcm = if self.options.permissive_pcm { craft_audio::essence_pcm::parse_wav(data) } else { crate::pcm::parse_wav(data) }; + if let Some((pcm, ch, sr, bits)) = pcm { s.embedded = Some(pcm); s.file_channels = ch as u32; s.channels = if s.channel.is_some() { 1 } else { ch as u32 }; diff --git a/crates/aaf/src/aaf/tests.rs b/crates/aaf/src/aaf/tests.rs index 3e7794471..34eb2bbb3 100644 --- a/crates/aaf/src/aaf/tests.rs +++ b/crates/aaf/src/aaf/tests.rs @@ -557,3 +557,32 @@ fn relative_media_locator_round_trips_escaped_characters() { let got = read_clean(&bytes); assert!(got.sources.iter().any(|s| s.path.as_deref() == Some("Audio Files/100%20 #1.wav"))); } + +#[test] +fn compatibility_options_keep_relative_paths_and_parent_rate() { + let mut doc = crate::testdoc::sound_only(None); + doc.compositions[0].sample_rate = 44_100; + doc.sources[0].path = Some("Audio Files/100%20 #1.wav".into()); + let mut report = Report::default(); + let references = ReferenceOptions { source_slot_rate: false, encode_relative_locator: false }; + let bytes = write_with_references(&doc, &WriteOptions { identity: IDENTITY, small_sectors: false }, &references, &mut report).unwrap(); + let root = store::read(&bytes).unwrap(); + let mut all = Vec::new(); + walk(&root, &mut all); + assert!( + all.iter().filter(|o| o.class == cls::NETWORK_LOCATOR).any(|o| o.string(pid::URL_STRING).as_deref() == Some("Audio Files/100%20 #1.wav")) + ); + let starts: Vec = all.iter().filter(|o| o.class == cls::SOURCE_CLIP).filter_map(|o| o.i64(pid::START_TIME)).collect(); + assert!(starts.contains(&17_640), "parent rate start: {starts:?}"); + let opts = ReadOptions { + source_slot_rate: false, + infer_clip_name: false, + decode_relative_locator: false, + report_flattening: false, + permissive_pcm: true, + }; + let back = read_with_options(&bytes, &opts, &mut report).unwrap(); + assert!(back.sources.iter().any(|s| s.path.as_deref() == Some("Audio Files/100%20 #1.wav"))); + let clip = back.compositions[0].tracks[0].items.iter().find_map(|i| if let CItem::Clip(c) = i { Some(c) } else { None }).unwrap(); + assert_eq!(clip.start, FrameRate::FPS_25.tick_of(10)); +} diff --git a/crates/aaf/src/aaf/write.rs b/crates/aaf/src/aaf/write.rs index 8c9aae88e..1fcc6a332 100644 --- a/crates/aaf/src/aaf/write.rs +++ b/crates/aaf/src/aaf/write.rs @@ -75,6 +75,7 @@ fn definition(class: Auid, id: Auid, name: &str) -> Obj { struct W<'a> { report: &'a mut Report, inexact: bool, + references: super::ReferenceOptions, } struct IdGen { @@ -350,9 +351,15 @@ fn add_tape_mob(first: &Source, tape_id: [u8; 32], timecode: Option<(i64, FrameR } /// Serialise a composition document. -pub(crate) fn write(doc: &Document, version: craft_cfb::Version, identity: &Identity<'_>, report: &mut Report) -> Result> { +pub(crate) fn write( + doc: &Document, + version: craft_cfb::Version, + identity: &Identity<'_>, + references: &super::ReferenceOptions, + report: &mut Report, +) -> Result> { let comp = doc.compositions.first().ok_or(Error::Empty)?; - let mut w = W { report, inexact: false }; + let mut w = W { report, inexact: false, references: *references }; let mut ids = IdGen::for_document(doc, comp); let MediaOutput { mut mobs, essence, master_ref } = write_media(doc, &mut w, &mut ids); let mut used_ops: Vec = Vec::new(); @@ -360,7 +367,8 @@ pub(crate) fn write(doc: &Document, version: craft_cfb::Version, identity: &Iden // ---- nested compositions: a clip refers to one as it does to a master mob, through the // composition's first track of the clip's kind (a broken-out channel: that channel's track) - let mut refs = Refs { mobs: master_ref, rates: doc.sources.iter().enumerate().map(|(i, s)| (i, source_rate(s))).collect() }; + let rates = if references.source_slot_rate { doc.sources.iter().enumerate().map(|(i, s)| (i, source_rate(s))).collect() } else { HashMap::new() }; + let mut refs = Refs { mobs: master_ref, rates }; let nested_ids: Vec<[u8; 32]> = doc.nested.iter().map(|_| ids.next()).collect(); for (si, s) in doc.sources.iter().enumerate() { let Some((comp, id)) = s.nested.and_then(|n| Some((doc.nested.get(n)?, nested_ids.get(n)?))) else { continue }; @@ -795,8 +803,10 @@ fn descriptor(w: &mut W, s: &Source) -> Obj { if let Some(p) = &s.path { let url = if craft_timeline::path::is_absolute(p) { craft_timeline::path::path_to_file_url(p, false) - } else { + } else if w.references.encode_relative_locator { craft_timeline::path::encode_uri_path(p) + } else { + p.clone() }; d.set(pid::LOCATOR, Value::StrongVec(vec![Obj::new(cls::NETWORK_LOCATOR).data_prop(pid::URL_STRING, utf16z(&url))])); } From ad9850f18fadac54048f680d1da7f50f379cd124 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:05:37 -0500 Subject: [PATCH 085/349] fix(audio): validate FLAC stream precision and complete consumption --- crates/audio/src/flac_decode.rs | 49 +++++++++++++++++++++++++++++-- crates/audio/tests/flac_decode.rs | 37 +++++++++++++++++++++++ 2 files changed, 84 insertions(+), 2 deletions(-) diff --git a/crates/audio/src/flac_decode.rs b/crates/audio/src/flac_decode.rs index dfb6f5fc1..bb56e65c5 100644 --- a/crates/audio/src/flac_decode.rs +++ b/crates/audio/src/flac_decode.rs @@ -225,6 +225,11 @@ impl Decoder { /// Decode the frame at the start of `data`. pub fn decode_frame(&self, data: &[u8]) -> Result { + // StreamInfo has public fields: container callers can construct it without + // parse(), so validate before it can control shifts and sample reads. + if self.info.is_some_and(|i| !(4..=32).contains(&i.bits_per_sample) || !(1..=8).contains(&i.channels) || i.sample_rate == 0) { + return Err(DecodeError::Invalid("invalid decoder STREAMINFO")); + } let mut r = Bits::new(data); if r.bits(15)? != 0x7FFC { return Err(DecodeError::Invalid("missing frame sync code")); @@ -315,8 +320,7 @@ impl Decoder { } let mut chans = Vec::with_capacity(channels); for c in out { - let v: Result> = - c.into_iter().map(|s| i32::try_from(s).map_err(|_| DecodeError::Invalid("sample outside the bit depth"))).collect(); + let v: Result> = c.into_iter().map(|s| checked_sample(s, bits)).collect(); chans.push(v?); } Ok(Frame { sample_rate, bits_per_sample: bits as u8, variable_block_size: variable, number, block_size, channels: chans, size }) @@ -542,6 +546,11 @@ pub fn decode_with_limit(bytes: &[u8], max_values: u64) -> Result { if frame.channels.len() != channels.len() { return Err(DecodeError::Invalid("the channel count changes inside the stream")); } + // One file has one sample rate and depth. Otherwise callers would play + // samples under incompatible STREAMINFO metadata. + if frame.sample_rate != info.sample_rate || frame.bits_per_sample != info.bits_per_sample { + return Err(DecodeError::Invalid("frame format differs from STREAMINFO")); + } total += frame.block_size as u64; if total.saturating_mul(channels.len() as u64) > max_values { return Err(DecodeError::TooLarge); @@ -551,8 +560,44 @@ pub fn decode_with_limit(bytes: &[u8], max_values: u64) -> Result { } pos += frame.size; } + // Unknown total_samples must not turn a corrupt/truncated next frame into + // a successfully decoded shorter recording. + if pos != bytes.len() { + return Err(DecodeError::Invalid("trailing data or missing frame sync")); + } if info.total_samples != 0 && total != info.total_samples { return Err(DecodeError::Truncated); } Ok(Decoded { info, channels }) } + +// Validate the advertised precision, not just the storage type. Malformed +// predictors may produce an i32 that is still invalid for 4–24-bit audio. +fn checked_sample(sample: i64, bits: u32) -> Result { + if !(4..=32).contains(&bits) { + return Err(DecodeError::Invalid("invalid sample bit depth")); + } + let bound = 1i64 << (bits - 1); + if !(-bound..bound).contains(&sample) { + return Err(DecodeError::Invalid("sample outside the bit depth")); + } + i32::try_from(sample).map_err(|_| DecodeError::Invalid("sample outside the bit depth")) +} + +#[cfg(test)] +mod sample_bounds_tests { + use super::checked_sample; + + #[test] + fn samples_must_fit_declared_precision() { + for bits in 4..=32 { + let bound = 1i64 << (bits - 1); + assert_eq!(checked_sample(-bound, bits).map(i64::from), Ok(-bound)); + assert_eq!(checked_sample(bound - 1, bits).map(i64::from), Ok(bound - 1)); + assert!(checked_sample(-bound - 1, bits).is_err()); + assert!(checked_sample(bound, bits).is_err()); + } + assert!(checked_sample(0, 0).is_err()); + assert!(checked_sample(0, 255).is_err()); + } +} diff --git a/crates/audio/tests/flac_decode.rs b/crates/audio/tests/flac_decode.rs index c35267b08..a1895789b 100644 --- a/crates/audio/tests/flac_decode.rs +++ b/crates/audio/tests/flac_decode.rs @@ -172,3 +172,40 @@ fn ffmpeg_decodes_our_files_to_our_samples() { assert!(interleave(&got.channels) == want, "{channels}ch {bits}-bit: samples differ from ffmpeg's decode"); } } + +#[test] +fn rejects_unknown_length_corruption_and_streaminfo_format_mismatch() { + let src = signal(1, 100, 16, 7); + let original = encode(&src, 44_100, 16, 4096, 5); + let at = STREAMINFO_OFFSET as usize; + // STREAMINFO is not CRC-covered. Clear only the 36-bit total sample count. + let mut unknown = original.clone(); + unknown[at + 13] &= 0xf0; + unknown[at + 14..at + 18].fill(0); + assert_eq!(decode(&unknown).unwrap().channels, src); + for tail in [vec![0xff], vec![0x00, 0x00]] { + let mut broken = unknown.clone(); + broken.extend(tail); + assert!(decode(&broken).is_err()); + } + // The encoder spells these in frame headers, independent of STREAMINFO. + let mut wrong_rate = original.clone(); + let mut packed = u64::from_be_bytes(wrong_rate[at + 10..at + 18].try_into().unwrap()); + packed = (packed & ((1u64 << 44) - 1)) | (48_000u64 << 44); + wrong_rate[at + 10..at + 18].copy_from_slice(&packed.to_be_bytes()); + assert!(decode(&wrong_rate).is_err()); + let mut wrong_depth = original; + wrong_depth[at + 12] = (wrong_depth[at + 12] & !1) | 1; + wrong_depth[at + 13] = (wrong_depth[at + 13] & 0x0f) | 0x70; + assert!(decode(&wrong_depth).is_err()); +} + +#[test] +fn caller_constructed_streaminfo_is_validated_before_decoding() { + let file = encode(&signal(1, 100, 16, 9), 44_100, 16, 4096, 5); + let info = StreamInfo::parse(&file[STREAMINFO_OFFSET as usize..]).unwrap(); + for bits in [0, 1, 3, 33, 64, 255] { + let invalid = StreamInfo { bits_per_sample: bits, ..info }; + assert!(matches!(Decoder::new(invalid).decode_frame(&[]), Err(DecodeError::Invalid(_)))); + } +} From d3024d0cd5af26edecc04b0a68689436952bd116 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:05:39 -0500 Subject: [PATCH 086/349] fix(captions): preserve literal ASS escapes and normalize newlines --- crates/captions/src/ass.rs | 11 ++++++++--- crates/captions/tests/it/ass.rs | 31 ++++++++++++++++++++++++++++++- 2 files changed, 38 insertions(+), 4 deletions(-) diff --git a/crates/captions/src/ass.rs b/crates/captions/src/ass.rs index 3c907c829..2d0a1df55 100644 --- a/crates/captions/src/ass.rs +++ b/crates/captions/src/ass.rs @@ -191,7 +191,10 @@ fn escape(text: &str) -> String { let mut out = String::with_capacity(text.len() + 8); let mut rest = text; while !rest.is_empty() { - if let Some(r) = rest.strip_prefix("") { + if let Some(r) = rest.strip_prefix("\r\n") { + out.push_str("\\N"); + rest = r; + } else if let Some(r) = rest.strip_prefix("") { out.push_str("{\\i1}"); rest = r; } else if let Some(r) = rest.strip_prefix("") { @@ -211,7 +214,9 @@ fn escape(text: &str) -> String { rest = r; } else if let Some(c) = rest.chars().next() { match c { - '\n' => out.push_str("\\N"), + '\n' | '\r' => out.push_str("\\N"), + // Empty override block separates a literal slash from N/n/h. + '\\' => out.push_str("\\{}"), '{' => out.push('\u{ff5b}'), '}' => out.push('\u{ff5d}'), '\u{a0}' => out.push_str("\\h"), @@ -232,7 +237,7 @@ pub fn write(doc: &Document) -> String { ); for c in &doc.cues { // A comma in the Name field would shift the columns; the other fields are fixed text. - let name = c.speaker.as_deref().unwrap_or("").replace([',', '\n'], " "); + let name = c.speaker.as_deref().unwrap_or("").replace([',', '\n', '\r'], " "); out.push_str(&format!("Dialogue: 0,{},{},Default,{},0,0,0,,{}\n", format_time(c.start), format_time(c.end), name, escape(&c.text))); } out diff --git a/crates/captions/tests/it/ass.rs b/crates/captions/tests/it/ass.rs index de5d43167..fb6d4e01e 100644 --- a/crates/captions/tests/it/ass.rs +++ b/crates/captions/tests/it/ass.rs @@ -99,7 +99,8 @@ fn we_read_what_ffmpeg_writes() { fn ffmpeg_reads_what_we_write() { let Some(ff) = craft_media_testkit::ffmpeg() else { return }; let dir = craft_media_testkit::fixture_subdir("captions_ass"); - let doc = parse(SRT.as_bytes(), Format::Srt).expect("parse srt"); + let mut doc = parse(SRT.as_bytes(), Format::Srt).expect("parse srt"); + doc.cues.push(Cue { start: cs(400_000), end: cs(400_100), text: r"C:\New\notes\hello and \N \n \h".into(), ..Default::default() }); let (ass, srt) = (dir.join("ours.ass"), dir.join("back.srt")); std::fs::write(&ass, write(&doc, Format::Ass, WriteOptions::default())).expect("write"); ffmpeg_run(&ff, &["-i", ass.to_str().expect("path"), srt.to_str().expect("path")]); @@ -111,3 +112,31 @@ fn ffmpeg_reads_what_we_write() { assert_eq!(t.text, d.text, "text of the cue at {:?}", d.start); } } + +#[test] +fn literal_backslashes_survive_ass_round_trip() { + let text = r"C:\New\notes\hello and \N \n \h"; + let doc = Document { cues: vec![Cue { start: cs(100), end: cs(200), text: text.into(), ..Default::default() }], ..Default::default() }; + let bytes = write(&doc, Format::Ass, WriteOptions::default()); + assert_eq!(parse(&bytes, Format::Ass).unwrap().cues[0].text, text); +} + +#[test] +fn carriage_returns_cannot_create_dialogue_records() { + let doc = Document { + cues: vec![Cue { + start: cs(100), + end: cs(200), + text: "first\rsecond\r\nthird".into(), + speaker: Some("Ann\rOther".into()), + ..Default::default() + }], + ..Default::default() + }; + let bytes = write(&doc, Format::Ass, WriteOptions::default()); + assert!(!bytes.contains(&b'\r')); + let back = parse(&bytes, Format::Ass).unwrap(); + assert_eq!(back.cues.len(), 1); + assert_eq!(back.cues[0].text, "first\nsecond\nthird"); + assert_eq!(back.cues[0].speaker.as_deref(), Some("Ann Other")); +} From f31e878c6e923748aebae75869e9dd88874d05d3 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:08:57 +0000 Subject: [PATCH 087/349] exr: share ZIP chunk compression --- crates/exr/src/lib.rs | 3 + crates/exr/src/zlib.rs | 796 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 799 insertions(+) create mode 100644 crates/exr/src/zlib.rs diff --git a/crates/exr/src/lib.rs b/crates/exr/src/lib.rs index baaf3d3f1..f1550f8de 100644 --- a/crates/exr/src/lib.rs +++ b/crates/exr/src/lib.rs @@ -18,6 +18,9 @@ //! - [`stream`]: one flat scan-line part read block by block, for pictures larger than memory. //! - [`cryptomatte_samples`]: a file's Cryptomatte layers and their per-pixel (ID, coverage) ranks. +/// RFC 1950/1951 compressor for ZIP-compressed EXR chunks. +pub mod zlib; + pub mod channels; pub mod cryptomatte; #[cfg(feature = "decode")] diff --git a/crates/exr/src/zlib.rs b/crates/exr/src/zlib.rs new file mode 100644 index 000000000..8959a7e89 --- /dev/null +++ b/crates/exr/src/zlib.rs @@ -0,0 +1,796 @@ +//! A small DEFLATE encoder (RFC 1951) in a zlib wrapper (RFC 1950), written from the RFCs for the +//! ZIP-compressed OpenEXR chunks. +//! +//! Greedy LZ77 over a 32 KB window (hash chains of bounded length), then each block of tokens is +//! written as whichever of stored, fixed-Huffman or dynamic-Huffman is smallest. Huffman code +//! lengths are limited (15 bits, 7 for the code-length code) by halving the symbol frequencies +//! until the tree fits. Every code has at least two symbols, so all codes are complete. The +//! output favours simplicity and correctness over ratio; worst-case expansion is the stored-block +//! overhead (5 bytes per 64 KB). + +use std::cmp::Reverse; +use std::collections::BinaryHeap; + +const WINDOW: usize = 32 * 1024; +const MIN_MATCH: usize = 3; +const MAX_MATCH: usize = 258; +/// Hash chain candidates tried per position. +const MAX_CHAIN: usize = 48; +/// Tokens per block (a new set of Huffman codes after this many). +const BLOCK_TOKENS: usize = 1 << 15; +const MAX_STORED: usize = 65_535; + +const LEN_BASE: [u16; 29] = [3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258]; +const LEN_EXTRA: [u8; 29] = [0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0]; +const DIST_BASE: [u16; 30] = + [1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577]; +const DIST_EXTRA: [u8; 30] = [0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13]; +/// Order in which the code-length code's lengths are sent. +const CL_ORDER: [usize; 19] = [16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15]; + +/// `data` compressed as a zlib stream (CMF 0x78: deflate, 32 KB window). `tables` are the match +/// finder's hash tables, kept by the caller across the chunks of a picture; the output does not +/// depend on what they held before. +pub fn zlib(data: &[u8], tables: &mut Tables) -> Vec { + let mut w = Bits { out: Vec::with_capacity(data.len() / 2 + 64), acc: 0, n: 0 }; + w.out.extend_from_slice(&[0x78, 0x9C]); // (0x78 << 8 | 0x9C) % 31 == 0 + deflate(data, &mut w, tables); + w.align(); + w.out.extend_from_slice(&adler32(data).to_be_bytes()); + w.out +} + +/// Adler-32 (RFC 1950 §9); 5552 bytes is the longest run that cannot overflow the sums. +fn adler32(data: &[u8]) -> u32 { + let (mut a, mut b) = (1_u32, 0_u32); + for c in data.chunks(5552) { + for &x in c { + a += u32::from(x); + b += a; + } + a %= 65_521; + b %= 65_521; + } + (b << 16) | a +} + +/// LSB-first bit writer. +struct Bits { + out: Vec, + acc: u64, + n: u32, +} + +impl Bits { + /// The low `n` bits of `v` (n ≤ 32). + fn put(&mut self, v: u32, n: u32) { + let mask = (1_u64 << n) - 1; + self.acc |= (u64::from(v) & mask) << self.n; + self.n += n; + while self.n >= 8 { + self.out.push(self.acc as u8); + self.acc >>= 8; + self.n -= 8; + } + } + + fn align(&mut self) { + if self.n > 0 { + self.out.push(self.acc as u8); + } + self.acc = 0; + self.n = 0; + } +} + +#[derive(Clone, Copy)] +enum Tok { + Lit(u8), + Match { len: u16, dist: u16 }, +} + +/// Index into [`LEN_BASE`] of a match length (3..=258). +fn len_code(len: u16) -> usize { + LEN_BASE.partition_point(|&b| b <= len).saturating_sub(1) +} + +/// Index into [`DIST_BASE`] of a distance (1..=32768). +fn dist_code(dist: u16) -> usize { + DIST_BASE.partition_point(|&b| b <= dist).saturating_sub(1) +} + +/// The match finder's hash heads and chains, reused from one input to the next. +/// +/// A slot holds `base + p + 1` for position `p` of the input that wrote it; anything at or below +/// the current input's `base` was left by an earlier input and reads as empty. So the tables are +/// never cleared between inputs: an OpenEXR ZIPS frame is one input per scan line, and zeroing +/// 256 KiB of tables for each 23 KB UHD line cost more memory traffic than the data itself. +#[derive(Default)] +pub struct Tables { + head: Vec, + prev: Vec, + /// Bytes compressed through these tables since they were last cleared. + base: u32, +} + +/// LZ77 match finder: hash heads and chains over the window. +struct Matcher<'a> { + data: &'a [u8], + head: &'a mut [u32], + prev: &'a mut [u32], + bits: u32, + /// `prev` slots used by this input, minus one (a power of two minus one). + mask: usize, + base: u32, +} + +impl<'a> Matcher<'a> { + /// A matcher over `data` (shorter than `u32::MAX` bytes), or None when it is not. + fn new(data: &'a [u8], t: &'a mut Tables) -> Option { + // hash width and chain span follow the input's size, as they did when every input had + // tables of its own (the output depends on them), so short chunks stay cheap to hash + let span = data.len().clamp(256, WINDOW).next_power_of_two(); + let bits = span.trailing_zeros().clamp(8, 15); + let n = u32::try_from(data.len()).ok().filter(|&n| n < u32::MAX)?; + if t.base.checked_add(n).and_then(|b| b.checked_add(1)).is_none() { + // positions would no longer fit after `base`: start over from empty tables + t.head.fill(0); + t.prev.fill(0); + t.base = 0; + } + // grown slots are 0, which is never above `base`, so they read as empty + if t.head.len() < 1 << bits { + t.head.resize(1 << bits, 0); + } + if t.prev.len() < span { + t.prev.resize(span, 0); + } + let base = t.base; + t.base += n; + let (head, prev) = (t.head.get_mut(..1 << bits)?, t.prev.get_mut(..span)?); + Some(Matcher { data, head, prev, bits, mask: span - 1, base }) + } + + /// Position `p` of this input from a stored slot, or None for an empty or earlier input's slot. + fn pos(&self, slot: u32) -> Option { + slot.checked_sub(self.base)?.checked_sub(1).map(|p| p as usize) + } + + fn hash(&self, p: usize) -> Option { + let b = self.data.get(p..p + MIN_MATCH)?; + let v = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]); + Some((v.wrapping_mul(0x9E37_79B1) >> (32 - self.bits)) as usize) + } + + /// Record position `p` (stored as `p + 1`; 0 = empty). + fn insert(&mut self, p: usize) { + let Some(h) = self.hash(p) else { return }; + let (Some(head), Ok(p32)) = (self.head.get(h).copied(), u32::try_from(p)) else { return }; + if let Some(slot) = self.prev.get_mut(p & self.mask) { + *slot = head; + } + if let Some(slot) = self.head.get_mut(h) { + // `new` reserved `base + len + 1` within u32 + *slot = self.base + p32 + 1; + } + } + + /// The longest earlier match at `p`: (length, distance), length 0 if none. + fn longest(&self, p: usize) -> (usize, usize) { + let Some(h) = self.hash(p) else { return (0, 0) }; + let max = self.data.len().saturating_sub(p).min(MAX_MATCH); + let Some(here) = self.data.get(p..p + max) else { return (0, 0) }; + let (mut best, mut best_dist) = (0, 0); + let mut cand = self.head.get(h).and_then(|&s| self.pos(s)); + for _ in 0..MAX_CHAIN { + let Some(c) = cand else { break }; + if c >= p || p - c > WINDOW { + break; + } + // a candidate that differs at `best` cannot be longer than `best`: skip comparing it + if best == 0 || self.data.get(c + best) == here.get(best) { + let l = self.data.get(c..).unwrap_or_default().iter().zip(here).take_while(|(a, b)| a == b).count(); + if l > best { + (best, best_dist) = (l, p - c); + if l == max { + break; + } + } + } + let Some(next) = self.prev.get(c & self.mask).and_then(|&s| self.pos(s)) else { break }; + // chains only go back; anything else is a stale slot + if next >= c { + break; + } + cand = Some(next); + } + (best, best_dist) + } +} + +/// The deflate blocks of `data`, the last one final. +fn deflate(data: &[u8], w: &mut Bits, tables: &mut Tables) { + if data.is_empty() { + // a final fixed-Huffman block holding only end-of-block (code 0000000) + w.put(1, 1); + w.put(1, 2); + w.put(0, 7); + return; + } + // positions are kept in u32; longer inputs (never an OpenEXR chunk) go out stored + let mut m = Matcher::new(data, tables); + let mut toks = Vec::with_capacity(BLOCK_TOKENS.min(data.len()) + 1); + let (mut start, mut i) = (0, 0); + while i < data.len() { + let (len, dist) = m.as_ref().map_or((0, 0), |m| m.longest(i)); + let step = if len >= MIN_MATCH { + toks.push(Tok::Match { len: len as u16, dist: dist as u16 }); + len + } else { + toks.push(Tok::Lit(data[i])); + 1 + }; + if let Some(m) = m.as_mut() { + for p in i..i + step { + m.insert(p); + } + } + i += step; + if toks.len() >= BLOCK_TOKENS || i == data.len() { + block(w, &toks, &data[start..i], i == data.len()); + toks.clear(); + start = i; + } + } +} + +/// Bits the tokens take with the given code lengths (EOB included). +fn data_bits(lf: &[u32], df: &[u32], ll: &[u8], dl: &[u8]) -> u64 { + let mut n = 0_u64; + for (s, (&f, &l)) in lf.iter().zip(ll).enumerate() { + let extra = s.checked_sub(257).and_then(|k| LEN_EXTRA.get(k)).copied().unwrap_or(0); + n += u64::from(f) * u64::from(l + extra); + } + for (d, (&f, &l)) in df.iter().zip(dl).enumerate() { + n += u64::from(f) * u64::from(l + DIST_EXTRA.get(d).copied().unwrap_or(0)); + } + n +} + +/// One block (split into several stored blocks when stored is smallest and `raw` is long). +fn block(w: &mut Bits, toks: &[Tok], raw: &[u8], last: bool) { + let mut lf = [0_u32; 286]; + let mut df = [0_u32; 30]; + for t in toks { + match *t { + Tok::Lit(b) => lf[b as usize] += 1, + Tok::Match { len, dist } => { + lf[257 + len_code(len)] += 1; + df[dist_code(dist)] += 1; + } + } + } + lf[256] += 1; + + // dynamic codes and their header + let ll = lengths(&lf, 15); + let dl = lengths(&df, 15); + let hlit = ll.iter().rposition(|&l| l > 0).map_or(257, |p| (p + 1).max(257)); + let hdist = dl.iter().rposition(|&l| l > 0).map_or(1, |p| p + 1); + let seq = rle_lengths(&[&ll[..hlit], &dl[..hdist]].concat()); + let mut cf = [0_u32; 19]; + for &(s, _) in &seq { + cf[s as usize] += 1; + } + let cl = lengths(&cf, 7); + let hclen = CL_ORDER.iter().rposition(|&s| cl[s] > 0).map_or(4, |p| (p + 1).max(4)); + let seq_bits: u64 = + seq.iter().map(|&(s, _)| u64::from(cl[s as usize]) + [2_u64, 3, 7].get((s as usize).wrapping_sub(16)).copied().unwrap_or(0)).sum(); + let dyn_bits = 3 + 14 + 3 * hclen as u64 + seq_bits + data_bits(&lf, &df, &ll, &dl); + + let (fll, fdl) = fixed_lengths(); + let fixed_bits = 3 + data_bits(&lf, &df, &fll, &fdl); + // per stored piece: header, at most 7 padding bits, LEN and NLEN + let pieces = raw.len().div_ceil(MAX_STORED).max(1) as u64; + let stored_bits = pieces * (3 + 7 + 32) + 8 * raw.len() as u64; + + if stored_bits <= fixed_bits.min(dyn_bits) { + let n = raw.chunks(MAX_STORED).count(); + for (k, piece) in raw.chunks(MAX_STORED).enumerate() { + w.put(u32::from(last && k + 1 == n), 1); + w.put(0, 2); + w.align(); + let len = piece.len() as u16; + w.out.extend_from_slice(&len.to_le_bytes()); + w.out.extend_from_slice(&(!len).to_le_bytes()); + w.out.extend_from_slice(piece); + } + return; + } + w.put(u32::from(last), 1); + if fixed_bits <= dyn_bits { + w.put(1, 2); + write_tokens(w, toks, &fll, &fdl); + return; + } + w.put(2, 2); + w.put((hlit - 257) as u32, 5); + w.put((hdist - 1) as u32, 5); + w.put((hclen - 4) as u32, 4); + for &s in &CL_ORDER[..hclen] { + w.put(u32::from(cl[s]), 3); + } + let cc = codes(&cl); + for &(s, x) in &seq { + w.put(u32::from(cc[s as usize]), u32::from(cl[s as usize])); + match s { + 16 => w.put(u32::from(x), 2), + 17 => w.put(u32::from(x), 3), + 18 => w.put(u32::from(x), 7), + _ => {} + } + } + write_tokens(w, toks, &ll, &dl); +} + +/// The fixed Huffman code lengths (RFC 1951 §3.2.6). +fn fixed_lengths() -> ([u8; 288], [u8; 30]) { + let mut ll = [8_u8; 288]; + ll[144..256].fill(9); + ll[256..280].fill(7); + (ll, [5; 30]) +} + +fn write_tokens(w: &mut Bits, toks: &[Tok], ll: &[u8], dl: &[u8]) { + let lc = codes(ll); + let dc = codes(dl); + let sym = |w: &mut Bits, s: usize| w.put(u32::from(lc[s]), u32::from(ll[s])); + for t in toks { + match *t { + Tok::Lit(b) => sym(w, b as usize), + Tok::Match { len, dist } => { + let k = len_code(len); + sym(w, 257 + k); + w.put(u32::from(len - LEN_BASE[k]), u32::from(LEN_EXTRA[k])); + let d = dist_code(dist); + w.put(u32::from(dc[d]), u32::from(dl[d])); + w.put(u32::from(dist - DIST_BASE[d]), u32::from(DIST_EXTRA[d])); + } + } + } + sym(w, 256); +} + +/// Canonical Huffman codes for `lens`, bit-reversed for the LSB-first writer. +fn codes(lens: &[u8]) -> Vec { + let mut count = [0_u32; 16]; + for &l in lens { + if (1..16).contains(&l) { + count[l as usize] += 1; + } + } + let mut next = [0_u32; 16]; + let mut code = 0; + for bits in 1..16 { + code = (code + count[bits - 1]) << 1; + next[bits] = code; + } + lens.iter() + .map(|&l| { + if !(1..16).contains(&l) { + return 0; + } + let c = next[l as usize]; + next[l as usize] += 1; + (c.reverse_bits() >> (32 - u32::from(l))) as u16 + }) + .collect() +} + +/// Code lengths for `freq`, none longer than `limit`; at least two symbols always get a code. +fn lengths(freq: &[u32], limit: u8) -> Vec { + let mut f: Vec = freq.iter().map(|&x| u64::from(x)).collect(); + let mut used = f.iter().filter(|&&x| x > 0).count(); + for x in f.iter_mut() { + if used >= 2 { + break; + } + if *x == 0 { + *x = 1; + used += 1; + } + } + // halving converges: once every used frequency is 1 the tree is balanced (depth ≤ 9 here) + for _ in 0..66 { + let l = huffman(&f); + if l.iter().all(|&d| d <= limit) { + return l; + } + for x in f.iter_mut().filter(|x| **x > 0) { + *x = (*x >> 1).max(1); + } + } + huffman(&f) +} + +/// Huffman tree depths of the symbols with non-zero frequency (0 for the rest). +fn huffman(f: &[u64]) -> Vec { + let n = f.len(); + let mut heap: BinaryHeap> = f.iter().enumerate().filter(|(_, w)| **w > 0).map(|(i, &w)| Reverse((w, i))).collect(); + let mut parent = vec![usize::MAX; 2 * n]; + let mut next = n; + while heap.len() > 1 { + let (Some(Reverse((wa, a))), Some(Reverse((wb, b)))) = (heap.pop(), heap.pop()) else { break }; + parent[a] = next; + parent[b] = next; + heap.push(Reverse((wa + wb, next))); + next += 1; + } + // parents always come after their children, so walk down from the root + let mut depth = vec![0_u32; next]; + for i in (0..next).rev() { + if let Some(&p) = parent.get(i).filter(|&&p| p < next) { + depth[i] = depth[p].saturating_add(1); + } + } + depth[..n].iter().map(|&d| d.min(u32::from(u8::MAX)) as u8).collect() +} + +/// Code lengths run-length coded with the code-length alphabet: (symbol, extra-bits value). +fn rle_lengths(lens: &[u8]) -> Vec<(u8, u8)> { + let mut out = Vec::new(); + let mut i = 0; + while i < lens.len() { + let l = lens[i]; + let run = lens[i..].iter().take_while(|&&x| x == l).count(); + let mut r = run; + if l == 0 { + while r >= 11 { + let k = r.min(138); + out.push((18, (k - 11) as u8)); + r -= k; + } + if r >= 3 { + out.push((17, (r - 3) as u8)); + r = 0; + } + } else { + out.push((l, 0)); + r -= 1; + while r >= 3 { + let k = r.min(6); + out.push((16, (k - 3) as u8)); + r -= k; + } + } + out.extend(std::iter::repeat_n((l, 0), r)); + i += run; + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A minimal inflater (RFC 1951), only to check the encoder; returns None on any error. + pub(crate) fn inflate(z: &[u8]) -> Option> { + let (cmf, flg) = (*z.first()?, *z.get(1)?); + if cmf & 0x0F != 8 || (u16::from(cmf) << 8 | u16::from(flg)) % 31 != 0 || flg & 0x20 != 0 { + return None; + } + let mut pos = 16_usize; // bit position + let bit = |pos: &mut usize| -> Option { + let b = (*z.get(*pos / 8)? >> (*pos % 8)) & 1; + *pos += 1; + Some(u32::from(b)) + }; + let bits = |pos: &mut usize, n: u32| -> Option { + let mut v = 0; + for k in 0..n { + v |= bit(pos)? << k; + } + Some(v) + }; + // decode one symbol with canonical lengths (slow but simple) + let decode = |pos: &mut usize, lens: &[u8]| -> Option { + let (mut code, mut first, mut index) = (0_i32, 0_i32, 0_i32); + let mut count = [0_i32; 16]; + for &l in lens { + count[l as usize] += 1; + } + let mut sorted: Vec = (0..lens.len()).filter(|&s| lens[s] > 0).collect(); + sorted.sort_by_key(|&s| (lens[s], s)); + for len in 1..16 { + code |= bit(pos)? as i32; + let c = count[len]; + if code - c < first { + return sorted.get((index + code - first) as usize).copied(); + } + index += c; + first = (first + c) << 1; + code <<= 1; + } + None + }; + let mut out = Vec::new(); + loop { + let last = bit(&mut pos)?; + match bits(&mut pos, 2)? { + 0 => { + pos = pos.div_ceil(8) * 8; + let at = pos / 8; + let len = u16::from_le_bytes([*z.get(at)?, *z.get(at + 1)?]); + let nlen = u16::from_le_bytes([*z.get(at + 2)?, *z.get(at + 3)?]); + if len != !nlen { + return None; + } + out.extend_from_slice(z.get(at + 4..at + 4 + len as usize)?); + pos = (at + 4 + len as usize) * 8; + } + t @ (1 | 2) => { + let (ll, dl) = if t == 1 { + let (a, b) = fixed_lengths(); + (a.to_vec(), b.to_vec()) + } else { + let hlit = bits(&mut pos, 5)? as usize + 257; + let hdist = bits(&mut pos, 5)? as usize + 1; + let hclen = bits(&mut pos, 4)? as usize + 4; + let mut cl = [0_u8; 19]; + for &s in &CL_ORDER[..hclen] { + cl[s] = bits(&mut pos, 3)? as u8; + } + let mut lens = Vec::new(); + while lens.len() < hlit + hdist { + match decode(&mut pos, &cl)? { + s @ 0..=15 => lens.push(s as u8), + 16 => { + let p = *lens.last()?; + lens.extend(std::iter::repeat_n(p, 3 + bits(&mut pos, 2)? as usize)); + } + 17 => lens.extend(std::iter::repeat_n(0, 3 + bits(&mut pos, 3)? as usize)), + _ => lens.extend(std::iter::repeat_n(0, 11 + bits(&mut pos, 7)? as usize)), + } + } + if lens.len() != hlit + hdist { + return None; + } + (lens[..hlit].to_vec(), lens[hlit..].to_vec()) + }; + loop { + let s = decode(&mut pos, &ll)?; + if s < 256 { + out.push(s as u8); + } else if s == 256 { + break; + } else { + let k = s - 257; + let len = *LEN_BASE.get(k)? as usize + bits(&mut pos, u32::from(LEN_EXTRA[k]))? as usize; + let d = decode(&mut pos, &dl)?; + let dist = *DIST_BASE.get(d)? as usize + bits(&mut pos, u32::from(DIST_EXTRA[d]))? as usize; + let from = out.len().checked_sub(dist)?; + for j in 0..len { + out.push(out[from + j]); + } + } + } + } + _ => return None, + } + if last == 1 { + break; + } + } + let at = pos.div_ceil(8); + let sum = u32::from_be_bytes(z.get(at..at + 4)?.try_into().ok()?); + (sum == adler32(&out) && at + 4 == z.len()).then_some(out) + } + + /// A deterministic pseudo-random byte stream. + fn noise(n: usize, seed: u32) -> Vec { + let mut s = seed | 1; + (0..n) + .map(|_| { + s ^= s << 13; + s ^= s >> 17; + s ^= s << 5; + s as u8 + }) + .collect() + } + + #[test] + fn round_trips() { + let mut cases: Vec> = vec![vec![], vec![7], vec![1, 2], vec![0; 1], vec![0; 300_000], b"abcabcabcabcabcabd".to_vec()]; + cases.push(noise(100_000, 9)); // incompressible: stored blocks + cases.push(noise(70_000, 3).iter().map(|b| b % 4).collect()); // few symbols: dynamic + cases.push((0..200_000_u32).map(|i| ((i / 7) % 251) as u8).collect()); // long repeats + // text-like: a small vocabulary repeated at varying distances + let words: [&[u8]; 6] = [b"red ", b"green ", b"blue ", b"alpha ", b"half ", b"linear "]; + cases.push(noise(40_000, 5).iter().flat_map(|b| words[*b as usize % 6].iter().copied()).collect()); + // skewed frequencies: Huffman lengths beyond 15 before limiting + let mut fib = Vec::new(); + let (mut a, mut b) = (1_usize, 1_usize); + for s in 0..25_u8 { + fib.extend(std::iter::repeat_n(s.wrapping_mul(37), a.min(200_000))); + (a, b) = (b, a + b); + } + let r = noise(fib.len() * 4, 11); + for i in (1..fib.len()).rev() { + let j = u32::from_le_bytes(r[i * 4..i * 4 + 4].try_into().unwrap()) as usize % (i + 1); + fib.swap(i, j); + } + cases.push(fib); + for (k, data) in cases.iter().enumerate() { + let z = zlib(data, &mut Tables::default()); + assert_eq!(inflate(&z).as_deref(), Some(data.as_slice()), "case {k}"); + // worst case: stored overhead only + assert!(z.len() <= data.len() + (data.len().div_ceil(BLOCK_TOKENS) + 1) * 5 + 6, "case {k}: {} > {}", z.len(), data.len()); + } + // repetitive data actually compresses + assert!(zlib(&cases[4], &mut Tables::default()).len() < 2_000); + assert!(zlib(&cases[8], &mut Tables::default()).len() < 20_000); + } + + #[test] + fn length_limits_hold() { + // Fibonacci frequencies give the deepest possible Huffman tree + let mut f = vec![0_u32; 286]; + let (mut a, mut b) = (1_u32, 1_u32); + for x in f.iter_mut().take(30) { + *x = a; + (a, b) = (b, a.saturating_add(b)); + } + let l = lengths(&f, 15); + assert!(l.iter().all(|&d| d <= 15)); + // a complete code: Kraft sum exactly 1 + let kraft: f64 = l.iter().filter(|&&d| d > 0).map(|&d| 0.5_f64.powi(i32::from(d))).sum(); + assert!((kraft - 1.0).abs() < 1e-12); + // one used symbol still gets a two-symbol code + let l = lengths(&[0, 5, 0], 7); + assert_eq!(l.iter().filter(|&&d| d == 1).count(), 2); + } + + #[test] + fn adler_matches_rfc_example() { + // the classic test vector for "Wikipedia" + assert_eq!(adler32(b"Wikipedia"), 0x11E6_0398); + assert_eq!(adler32(&[]), 1); + } + + /// The match finder before #4659: tables of its own per input, every chain candidate compared + /// from its first byte. + struct OldMatcher<'a> { + data: &'a [u8], + head: Vec, + prev: Vec, + bits: u32, + } + + impl<'a> OldMatcher<'a> { + /// Tables of its own, sized to `data`. + fn new(data: &'a [u8]) -> Self { + let span = data.len().clamp(256, WINDOW).next_power_of_two(); + let bits = span.trailing_zeros().clamp(8, 15); + OldMatcher { data, head: vec![0; 1 << bits], prev: vec![0; span], bits } + } + + /// The hash of the three bytes at `p`, None near the end. + fn hash(&self, p: usize) -> Option { + let b = self.data.get(p..p + MIN_MATCH)?; + let v = (u32::from(b[0]) << 16) | (u32::from(b[1]) << 8) | u32::from(b[2]); + Some((v.wrapping_mul(0x9E37_79B1) >> (32 - self.bits)) as usize) + } + + /// Record position `p` (stored as `p + 1`; 0 = empty). + fn insert(&mut self, p: usize) { + let Some(h) = self.hash(p) else { return }; + let mask = self.prev.len() - 1; + self.prev[p & mask] = self.head[h]; + self.head[h] = p as u32 + 1; + } + + /// The longest earlier match at `p`: (length, distance), length 0 if none. + fn longest(&self, p: usize) -> (usize, usize) { + let Some(h) = self.hash(p) else { return (0, 0) }; + let max = (self.data.len() - p).min(MAX_MATCH); + let here = &self.data[p..p + max]; + let mask = self.prev.len() - 1; + let (mut best, mut best_dist) = (0, 0); + let mut cand = self.head[h] as usize; + for _ in 0..MAX_CHAIN { + let Some(c) = cand.checked_sub(1) else { break }; + if c >= p || p - c > WINDOW { + break; + } + let l = self.data[c..].iter().zip(here).take_while(|(a, b)| a == b).count(); + if l > best { + (best, best_dist) = (l, p - c); + if l == max { + break; + } + } + let next = self.prev[c & mask] as usize; + if next == 0 || next > c { + break; + } + cand = next; + } + (best, best_dist) + } + } + + /// Inputs shaped like OpenEXR chunks (predicted half-float scan lines, single and 16-line) + /// and the awkward cases: empty, tiny, incompressible, long runs, few symbols. + fn chunk_cases() -> Vec> { + let line: Vec = (0..23_040_u32).map(|i| (128 + ((i / 3) % 7) as i32 - 3 + (i % 5 == 0) as i32) as u8).collect(); + let mut cases = vec![line.clone(), line.iter().rev().copied().collect(), vec![], vec![9], b"abcabcabcabd".to_vec()]; + cases.push(line.iter().cycle().take(16 * 23_040).copied().collect()); // ZIP: 16 lines, longer than the window + cases.push(noise(23_040, 4)); + cases.push(noise(70_000, 3).iter().map(|b| b % 4).collect()); + cases.push(vec![0; 300_000]); + cases.push(line.clone()); + cases.push(noise(300, 7)); + cases + } + + /// The matcher's greedy parse of `data`: what `deflate` codes. + fn parse (usize, usize), G: FnMut(usize)>(data: &[u8], mut longest: F, mut insert: G) -> Vec<(usize, usize)> { + let (mut out, mut i) = (Vec::new(), 0); + while i < data.len() { + let (len, dist) = longest(i); + let step = if len >= MIN_MATCH { len } else { 1 }; + out.push(if len >= MIN_MATCH { (len, dist) } else { (0, 0) }); + for p in i..i + step { + insert(p); + } + i += step; + } + out + } + + /// Shared tables and the candidate skip find exactly the matches the previous matcher found. + #[test] + fn shared_tables_find_the_matches_the_old_per_chunk_tables_found() { + let mut tables = Tables::default(); + for (k, data) in chunk_cases().iter().enumerate() { + let old = std::cell::RefCell::new(OldMatcher::new(data)); + let want = parse(data, |p| old.borrow().longest(p), |p| old.borrow_mut().insert(p)); + let new = std::cell::RefCell::new(Matcher::new(data, &mut tables).expect("fits")); + let got = parse(data, |p| new.borrow().longest(p), |p| new.borrow_mut().insert(p)); + assert!(got == want, "chunk {k}: the parse differs"); + } + } + + /// Shared tables compress to the bytes fresh ones give, also when positions run out and they start over. + #[test] + fn shared_tables_give_the_bytes_of_fresh_ones() { + let mut shared = Tables::default(); + for (k, data) in chunk_cases().iter().enumerate() { + let z = zlib(data, &mut shared); + assert!(z == zlib(data, &mut Tables::default()), "chunk {k}"); + assert_eq!(inflate(&z).as_deref(), Some(data.as_slice()), "chunk {k}"); + } + // positions about to run past u32: the tables start over and the bytes stay the same + for gap in [0_u32, 1, 2, 23_040, 23_041, 1 << 20] { + shared.base = u32::MAX - gap; + for (k, data) in chunk_cases().iter().enumerate() { + assert!(zlib(data, &mut shared) == zlib(data, &mut Tables::default()), "gap {gap}, chunk {k}"); + } + } + } + + /// Later chunks use the same tables instead of allocating new ones. + #[test] + fn the_tables_are_reused_across_chunks() { + let mut tables = Tables::default(); + let line = &chunk_cases()[0]; + zlib(line, &mut tables); + let (head, prev) = (tables.head.as_ptr(), tables.prev.as_ptr()); + for _ in 0..4 { + zlib(line, &mut tables); + assert!(tables.head.as_ptr() == head && tables.prev.as_ptr() == prev, "a chunk allocated new tables"); + } + assert_eq!(tables.base as usize, 5 * line.len()); + } +} From 58854566ed89f6b27f304da15eb8922133fb8924 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:10:39 -0500 Subject: [PATCH 088/349] feat: add craft-format (versioned JSON file formats) Port from solidcraft: versioned JSON file format system with: - Format families with hand-written upgrade steps and folded formats - Pending changes that auto-number on release - Container format: content-addressed blobs (SHA-256) in ZIP packages - Newer file handling: read what you can, keep the rest No external dependencies beyond serde_json and craft-zip. Hostile-input bounded reading: sizes, counts, nesting capped. --- crates/format/Cargo.toml | 20 ++ crates/format/src/build.rs | 100 +++++++ crates/format/src/container.rs | 401 +++++++++++++++++++++++++++ crates/format/src/container_tests.rs | 67 +++++ crates/format/src/lib.rs | 252 +++++++++++++++++ crates/format/src/lib_tests.rs | 134 +++++++++ crates/format/src/newer.rs | 401 +++++++++++++++++++++++++++ crates/format/src/newer_tests.rs | 48 ++++ 8 files changed, 1423 insertions(+) create mode 100644 crates/format/Cargo.toml create mode 100644 crates/format/src/build.rs create mode 100644 crates/format/src/container.rs create mode 100644 crates/format/src/container_tests.rs create mode 100644 crates/format/src/lib.rs create mode 100644 crates/format/src/lib_tests.rs create mode 100644 crates/format/src/newer.rs create mode 100644 crates/format/src/newer_tests.rs diff --git a/crates/format/Cargo.toml b/crates/format/Cargo.toml new file mode 100644 index 000000000..943e0b9b6 --- /dev/null +++ b/crates/format/Cargo.toml @@ -0,0 +1,20 @@ +[package] +name = "craft-format" +description = "Versioned JSON file formats: the format tag, the registry of versions (hand-written steps, then one folder of changes per version, then the pending changes), the upgrade of an older file and the telling of a newer one" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +serde_json = { workspace = true } +# The container: content-addressed blobs (SHA-256) in a ZIP package. +sha2 = { version = "0.10", default-features = false, features = ["std"] } +craft-zip = { workspace = true } + +[dev-dependencies] +proptest = { workspace = true } diff --git a/crates/format/src/build.rs b/crates/format/src/build.rs new file mode 100644 index 000000000..8fb879235 --- /dev/null +++ b/crates/format/src/build.rs @@ -0,0 +1,100 @@ +//! For a build script: the generated lists of a family's changes. Each change is one `.rs` file in +//! the family's folder, in `v/` once a release fixed its number, else in `pending/`; the lists +//! are generated so that a change adds a file and never edits a line another change also edits. +//! +//! The generated code, for the app to `include!`, is per family a `FOLDED` list (each folded +//! format and its parts) and a `PENDING` list, both prefixed by the family's `list_prefix`, then a +//! module per change file. It names the app's `Part` type, which the including module has in scope +//! (`type Part = craft_format::Part;`), and a change file's step as `step` (a +//! `pub fn step(v: &mut Value) -> Result<(), AppError>`, when the file has one). + +use std::fmt::Write as _; +use std::path::{Path, PathBuf}; + +/// A family's change files: their folder (relative to the crate's manifest), the last format +/// before them, and the prefix of the family's lists. +pub struct Family { + pub folder: &'static str, + pub base: u32, + pub list_prefix: &'static str, +} + +/// What [`lists`] made: the code to write, and the folders the build script reruns on. +pub struct Lists { + pub code: String, + pub watch: Vec, +} + +/// The `FOLDED` and `PENDING` lists of every family, and a module for each change file. Refuses +/// versions that are not contiguous from a family's base, a change file not named with lowercase +/// letters, digits and dashes, and one that doesn't start with a `//!` note. +pub fn lists(manifest: &Path, families: &[Family]) -> Result { + let mut code = String::new(); + let mut mods = String::new(); + let mut watch = Vec::new(); + for family in families { + let root = manifest.join(family.folder); + family_lists(family, &root, &mut code, &mut mods)?; + watch.push(root); + } + code.push_str(&mods); + Ok(Lists { code, watch }) +} + +/// A family's `FOLDED` and `PENDING` lists; its folded formats follow on from its base. +fn family_lists(family: &Family, root: &Path, out: &mut String, mods: &mut String) -> Result<(), String> { + let Family { folder, base, list_prefix } = family; + let mut folded: Vec<(u32, PathBuf)> = std::fs::read_dir(root) + .map_err(|e| format!("{}: {e}", root.display()))? + .filter_map(|entry| { + let path = entry.ok()?.path(); + let version = path.file_name()?.to_str()?.strip_prefix('v')?.parse().ok()?; + path.is_dir().then_some((version, path)) + }) + .collect(); + folded.sort(); + for (i, (version, _)) in folded.iter().enumerate() { + let expected = base + 1 + i as u32; + if *version != expected { + return Err(format!("{folder}/: expected v{expected}/ next, found v{version}/ (versions are contiguous)")); + } + } + // Module names start with the family's (`drawing_pending_…`), so two families' changes of one + // name never clash. + let module = list_prefix.to_ascii_lowercase(); + let _ = writeln!( + out, + "/// The changes of each format after the base, oldest first (`{folder}/v/`).\nconst {list_prefix}FOLDED: &[(u32, &[Part])] = &[" + ); + for (version, dir) in &folded { + let _ = writeln!(out, " ({version}, &["); + parts(dir, &format!("{module}v{version}"), out, mods)?; + out.push_str(" ]),\n"); + } + let _ = writeln!(out, "];\n\n/// The changes no release has a number for yet (`{folder}/pending/`).\nconst {list_prefix}PENDING: &[Part] = &["); + parts(&root.join("pending"), &format!("{module}pending"), out, mods)?; + out.push_str("];\n\n"); + Ok(()) +} + +/// The `Part`s of the change files in `dir`, in file-name order, and a module for each. +fn parts(dir: &Path, prefix: &str, out: &mut String, mods: &mut String) -> Result<(), String> { + let Ok(entries) = std::fs::read_dir(dir) else { return Ok(()) }; + let mut files: Vec = entries.filter_map(|e| e.ok().map(|e| e.path())).filter(|p| p.extension().is_some_and(|x| x == "rs")).collect(); + files.sort(); + for path in files { + let name = path.file_stem().and_then(|s| s.to_str()).unwrap_or_default().to_string(); + if name.is_empty() || !name.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-') { + return Err(format!("{}: name a format change file with lowercase letters, digits and dashes", path.display())); + } + let text = std::fs::read_to_string(&path).map_err(|e| format!("{}: {e}", path.display()))?; + if !text.trim_start().starts_with("//!") { + return Err(format!("{}: start a format change with a `//!` note", path.display())); + } + let module = format!("{prefix}_{}", name.replace('-', "_")); + let step = if text.contains("fn step(") { format!("Some({module}::step)") } else { "None".into() }; + let _ = writeln!(out, " Part {{ name: {name:?}, step: {step} }},"); + let _ = writeln!(mods, "#[path = {:?}]\nmod {module};", path.display().to_string()); + } + Ok(()) +} diff --git a/crates/format/src/container.rs b/crates/format/src/container.rs new file mode 100644 index 000000000..a987bb1fb --- /dev/null +++ b/crates/format/src/container.rs @@ -0,0 +1,401 @@ +//! The file container: a ZIP package of named parts (the file's JSON, binary payloads, optional +//! caches), never extracted to filesystem paths. Payloads are content-addressed blobs, +//! `blobs/.`, stored once however often they are referred to. Every size is +//! bounded by the app's [`Limits`]: the file, each part, all parts expanded, the payloads resolved, +//! and the number of entries; a part is read no further than its declared size (a decompression +//! bomb stops there). What a part holds, and how a payload is encoded, is the app's. + +use std::collections::{BTreeMap, BTreeSet}; +use std::io::{Cursor, Read, Seek, SeekFrom, Write}; +use std::sync::Arc; + +use serde_json::Value; +use sha2::{Digest, Sha256}; + +use crate::FormatError; + +/// How hard the payloads are compressed: Fast favours interactive file operations; Compact trades +/// CPU time for space. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Compression { + #[default] + Fast, + Compact, +} + +/// An app's budgets for its containers. The functions are read each time they are needed, so a +/// limit the app lets the user raise takes effect at once. +#[derive(Clone, Copy)] +pub struct Limits { + /// The most entries a container holds. + pub max_entries: usize, + /// The most bytes all parts may expand to, and all payloads may resolve to. + pub max_expanded: fn() -> usize, + /// The most bytes a part of this name may expand to. + pub part_limit: fn(&str) -> usize, + /// The Deflate level of a compressed part of this name and size. + pub level: fn(&str, usize) -> i64, + /// Whether a container of this many bytes may be read, or why not. + pub check_size: fn(u64) -> Result<(), String>, + /// Whether the work is cancelled (a save the person stopped): a long part is written a piece + /// at a time and stops before the next piece when this says so. `None`: it cannot be + /// cancelled here. + pub cancelled: Option bool>, +} + +fn invalid(message: impl std::fmt::Display) -> FormatError { + FormatError::Invalid(message.to_string()) +} + +/// Whether the bytes start as a container does, whatever the file is called. +pub fn is_container(bytes: &[u8]) -> bool { + bytes.starts_with(b"PK\x03\x04") +} + +/// The SHA-256 of the bytes. +pub fn sha256(bytes: &[u8]) -> [u8; 32] { + Sha256::digest(bytes).into() +} + +fn hex(digest: &[u8; 32]) -> String { + use std::fmt::Write as _; + let mut out = String::with_capacity(64); + for byte in digest { + // Writing to a `String` cannot fail. + let _ = write!(&mut out, "{byte:02x}"); + } + out +} + +/// The SHA-256 of the bytes, in lowercase hexadecimal: a blob's name, and how a cache is keyed to +/// the file it was written for. +pub fn digest(bytes: &[u8]) -> String { + hex(&sha256(bytes)) +} + +/// One part a [`Writer`] wrote, with the SHA-256 of its uncompressed content. A caller that signs +/// a container uses these to bind the parts without reading the file back. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct PartDigest { + pub name: String, + pub len: u64, + pub digest: [u8; 32], +} + +/// A container being written. +pub struct Writer { + zip: zip::ZipWriter>>, + names: BTreeSet, + expanded: usize, + resolved: usize, + limits: Limits, + /// Which written parts to record for a signature, and the records so far. + tracked: Option<(fn(&str) -> bool, Vec)>, +} + +impl Writer { + pub fn new(limits: Limits) -> Writer { + Writer { zip: zip::ZipWriter::new(Cursor::new(Vec::new())), names: BTreeSet::new(), expanded: 0, resolved: 0, limits, tracked: None } + } + + /// Record the parts written from now on whose name `include` accepts, with their SHA-256, for + /// [`Writer::take_parts`]. Used by a caller that signs the container. + pub fn track_parts(&mut self, include: fn(&str) -> bool) { + self.tracked = Some((include, Vec::new())); + } + + /// The tracked parts written so far, oldest first, and stop tracking. + pub fn take_parts(&mut self) -> Option> { + self.tracked.take().map(|(_, parts)| parts) + } + + /// The container's bytes. + pub fn finish(self) -> Result, FormatError> { + Ok(self.zip.finish().map_err(invalid)?.into_inner()) + } + + /// Add a part, compressed or stored. A name already written is written once. + pub fn part(&mut self, name: &str, bytes: &[u8], compressed: bool) -> Result<(), FormatError> { + self.part_with_digest(name, bytes, compressed, None) + } + + /// [`Writer::part`] with a digest the caller already worked out (a blob's name is its digest), + /// so a signed save does not hash the same bytes twice. + fn part_with_digest(&mut self, name: &str, bytes: &[u8], compressed: bool, digest: Option<[u8; 32]>) -> Result<(), FormatError> { + if bytes.len() > (self.limits.part_limit)(name) { + return Err(invalid("part too large")); + } + if !self.names.insert(name.to_owned()) { + return Ok(()); + } + self.expanded = self.expanded.checked_add(bytes.len()).ok_or_else(|| invalid("expanded size overflow"))?; + if self.expanded > (self.limits.max_expanded)() || self.names.len() > self.limits.max_entries { + return Err(invalid("package too large")); + } + if let Some((include, parts)) = &mut self.tracked + && include(name) + { + let digest = digest.unwrap_or_else(|| sha256(bytes)); + parts.push(PartDigest { name: name.to_owned(), len: bytes.len() as u64, digest }); + } + let method = if compressed { zip::CompressionMethod::Deflated } else { zip::CompressionMethod::Stored }; + let level = (self.limits.level)(name, bytes.len()); + // A part of 4 GiB or more (only with a raised file limit) needs a ZIP64 entry. + let options = zip::write::SimpleFileOptions::default() + .compression_method(method) + .compression_level(compressed.then_some(level)) + .large_file(bytes.len() as u64 >= u64::from(u32::MAX)); + self.zip.start_file(name, options).map_err(invalid)?; + // A piece at a time: a long compression (a large mesh or model cache) stops on Cancel + // within a piece instead of after the whole part. + for piece in bytes.chunks(1 << 20) { + if self.limits.cancelled.is_some_and(|cancelled| cancelled()) { + return Err(FormatError::Cancelled); + } + self.zip.write_all(piece).map_err(invalid)?; + } + Ok(()) + } + + /// Would `entries` more optional parts of `extra` bytes, stored uncompressed, still keep the + /// file within `budget` and its expanded size within the reader's budget? + pub fn room(&self, entries: usize, extra: usize, budget: usize) -> bool { + self.names.len().saturating_add(entries) <= self.limits.max_entries && extra <= self.space(entries, budget) + } + + /// The bytes `entries` more optional parts may hold together ([`Writer::room`]). + pub fn space(&self, entries: usize, budget: usize) -> usize { + if self.names.len().saturating_add(entries) > self.limits.max_entries { + return 0; + } + // The bytes written so far, plus what the open compressed part may still hold back. + let written = self.zip.get_ref().map_or(usize::MAX, |c| c.get_ref().len()).saturating_add(1 << 20); + let directory = self.names.len().saturating_add(entries).saturating_mul(256).saturating_add(65_536); + budget.saturating_sub(written.saturating_add(directory)).min((self.limits.max_expanded)().saturating_sub(self.expanded)) + } + + /// Add a payload as a blob, `blobs/.`, and say its name, for the JSON that + /// refers to it. + pub fn blob(&mut self, bytes: &[u8], extension: &str, compressed: bool) -> Result { + self.resolved = self + .resolved + .checked_add(bytes.len()) + .filter(|&n| n <= (self.limits.max_expanded)()) + .ok_or_else(|| invalid("resolved payloads too large"))?; + let digest = sha256(bytes); + let name = format!("blobs/{}.{extension}", hex(&digest)); + self.part_with_digest(&name, bytes, compressed, Some(digest))?; + Ok(Value::String(name)) + } +} + +/// A container being read, over a seekable source. Opening checks the directory (the entry count, +/// unique and plain names, every part's declared size), not the parts. +pub struct Reader { + zip: zip::ZipArchive, + blobs: BTreeMap>, + /// The bytes of payloads resolved so far, repeats counted: bounded by the expanded budget. + pub hydrated: usize, + document: Option>, + limits: Limits, +} + +impl Reader { + pub fn new(mut source: R, limits: Limits) -> Result { + let length = source.seek(SeekFrom::End(0)).map_err(invalid)?; + (limits.check_size)(length).map_err(invalid)?; + let tail_length = length.min(65_557) as usize; + source.seek(SeekFrom::Start(length - tail_length as u64)).map_err(invalid)?; + let mut tail = vec![0; tail_length]; + source.read_exact(&mut tail).map_err(invalid)?; + // zip's name index can coalesce duplicate central-directory entries. The bounded format + // does not need ZIP64/multiple disks: verify the declared entry count as well so + // duplicate names cannot silently select a payload. + let eocd = tail.windows(4).rposition(|v| v == b"PK\x05\x06").ok_or_else(|| invalid("missing ZIP directory"))?; + let end = tail.get(eocd..).filter(|v| v.len() >= 22).ok_or_else(|| invalid("truncated ZIP directory"))?; + let u16_at = |offset| -> Result { + let array: [u8; 2] = end.get(offset..offset + 2).ok_or_else(|| invalid("truncated ZIP directory"))?.try_into().map_err(invalid)?; + Ok(u16::from_le_bytes(array)) + }; + let declared = u16_at(10)? as usize; + if declared > limits.max_entries + || u16_at(4)? != 0 + || u16_at(6)? != 0 + || u16_at(8)? as usize != declared + || end.len() != 22 + u16_at(20)? as usize + { + return Err(invalid("too many entries or unsupported ZIP directory")); + } + // A container is a ZIP with nothing in front of it. Saying so skips zip's search for a + // prefix, which reads back through the stored parts and would load a large payload + // before a preview can be shown. + let config = zip::read::Config { archive_offset: zip::read::ArchiveOffset::Known(0) }; + let mut zip = zip::ZipArchive::with_config(config, source).map_err(invalid)?; + if u16_at(4)? != 0 + || u16_at(6)? != 0 + || u16_at(8)? as usize != zip.len() + || u16_at(10)? as usize != zip.len() + || end.len() != 22 + u16_at(20)? as usize + { + return Err(invalid("duplicate entries or unsupported ZIP directory")); + } + let mut names = BTreeSet::new(); + let mut total = 0u64; + for i in 0..zip.len() { + let part = zip.by_index_raw(i).map_err(invalid)?; + let name = part.name().map_err(invalid)?.into_owned(); + if name.is_empty() + || name.contains('\\') + || name.split('/').any(|c| c.is_empty() || c == "." || c == "..") + || !names.insert(name.to_owned()) + { + return Err(invalid("duplicate or invalid archive entry")); + } + total = total.checked_add(part.size()).ok_or_else(|| invalid("expanded size overflow"))?; + let limit = (limits.part_limit)(&name); + if part.size() > limit as u64 || total > (limits.max_expanded)() as u64 { + return Err(invalid("expanded package too large")); + } + } + Ok(Self { zip, blobs: BTreeMap::new(), hydrated: 0, document: None, limits }) + } + + /// The file's own part, `document.json`, read once and kept: provisional caches and the + /// authoritative reading are bound to the same bytes, even if another process overwrites the + /// open file in place. Blobs remain hash-checked. + pub fn document(&mut self, limit: usize) -> Result, FormatError> { + if self.document.is_none() { + self.document = Some(self.limited_part("document.json", limit)?.into()); + } + self.document.as_ref().filter(|d| d.len() <= limit).cloned().ok_or_else(|| invalid("metadata budget")) + } + + /// Whether the container has a part of this name. + pub fn has_part(&self, name: &str) -> bool { + self.zip.index_for_name(name).is_some() + } + + /// The names of every part, in the container's order. + pub fn part_names(&self) -> Vec { + self.zip.file_names().filter_map(|name| name.ok().map(|name| name.into_owned())).collect() + } + + /// The part of this name, at most `limit` bytes. + pub fn limited_part(&mut self, name: &str, limit: usize) -> Result, FormatError> { + let part = self.zip.by_name(name).map_err(|e| invalid(format!("required part `{name}`: {e}")))?; + let expected = part.size(); + if expected > limit as u64 { + return Err(invalid("part too large")); + } + let mut bytes = Vec::new(); + bytes.try_reserve_exact(expected as usize).map_err(|_| invalid("could not reserve required part"))?; + // A compressed part may expand beyond its declared size (a decompression bomb): stop + // one byte past it instead of at the limit. + part.take(expected + 1).read_to_end(&mut bytes).map_err(invalid)?; + if bytes.len() > limit || bytes.len() as u64 != expected { + return Err(invalid("part too large or length mismatch")); + } + Ok(bytes) + } + + /// The blob `value`'s `field` names, of this extension, within its part limit. + pub fn blob(&mut self, value: &Value, field: &str, extension: &str) -> Result<&[u8], FormatError> { + let limit = (self.limits.part_limit)(&format!("blob.{extension}")); + self.limited_blob(value, field, extension, limit) + } + + /// [`Reader::blob`] within `limit` bytes. Its hash is checked when it is first read, and every + /// reference counts against the resolved budget. + pub fn limited_blob(&mut self, value: &Value, field: &str, extension: &str, limit: usize) -> Result<&[u8], FormatError> { + let name = value.get(field).and_then(Value::as_str).ok_or_else(|| invalid(format!("missing `{field}` reference")))?; + let hash = name + .strip_prefix("blobs/") + .and_then(|n| n.strip_suffix(&format!(".{extension}"))) + .filter(|h| h.len() == 64 && h.bytes().all(|b| b.is_ascii_digit() || (b'a'..=b'f').contains(&b))) + .ok_or_else(|| invalid("invalid blob reference"))?; + if !self.blobs.contains_key(name) { + let bytes = self.limited_part(name, limit)?; + if digest(&bytes) != hash { + return Err(invalid(format!("blob hash mismatch: {name}"))); + } + self.blobs.insert(name.to_owned(), bytes); + } + let bytes = self.blobs.get(name).ok_or_else(|| invalid("missing blob"))?; + if bytes.len() > limit { + return Err(invalid("blob exceeds its resource budget")); + } + // Count repeated references too: a tiny archive must not expand into unbounded owned + // strings or arrays when the same blob is referenced repeatedly. + self.hydrated = self + .hydrated + .checked_add(bytes.len()) + .filter(|&n| n <= (self.limits.max_expanded)()) + .ok_or_else(|| invalid("resolved payloads too large"))?; + Ok(bytes) + } +} + +/// A small PNG picture of the file, kept in the container as a disposable cache keyed to the +/// exact file it shows: `cache/thumbnail.json` (its key) and `cache/thumbnail.png`. Reading it +/// never resolves a payload; a picture that isn't one, or is stale, is a miss. +#[derive(Clone, Copy, Debug)] +pub struct Thumbnail { + /// The key's format tag. + pub format: &'static str, + /// The build that wrote it: only the same build reads it back. + pub app: &'static str, + /// Its width and height in pixels. + pub size: [usize; 2], + /// The most bytes it may have. + pub max_bytes: usize, +} + +impl Thumbnail { + /// Whether the bytes start as a PNG of this size within the byte budget (not a decode: a + /// consumer decodes with its own dimension and allocation limits). + pub fn valid(&self, bytes: &[u8]) -> bool { + bytes.len() <= self.max_bytes + && bytes.get(..8) == Some(b"\x89PNG\r\n\x1a\n") + && bytes.get(8..16) == Some(b"\0\0\0\rIHDR") + && bytes.get(16..20) == Some((self.size[0] as u32).to_be_bytes().as_slice()) + && bytes.get(20..24) == Some((self.size[1] as u32).to_be_bytes().as_slice()) + } + + /// Add the picture, keyed to `document` (the file's own part), when it is one and there is + /// room for it within `budget`; otherwise leave it out, never failing the save. + pub fn write(&self, writer: &mut Writer, png: &[u8], document: &[u8], budget: usize) -> Result<(), FormatError> { + if !self.valid(png) { + return Ok(()); + } + let key = + serde_json::to_vec(&serde_json::json!({"format": self.format, "app": self.app, "document": digest(document), "payload": digest(png)})) + .map_err(invalid)?; + if !writer.room(2, key.len().saturating_add(png.len()), budget) { + return Ok(()); + } + writer.part("cache/thumbnail.json", &key, false)?; + writer.part("cache/thumbnail.png", png, false) + } + + /// The picture, when this build wrote it for exactly the file's own part (`document.json`, + /// read within `document_limit`). + pub fn read(&self, reader: &mut Reader, document_limit: usize) -> Result, FormatError> { + let key: Value = serde_json::from_slice(&reader.limited_part("cache/thumbnail.json", 4096)?).map_err(invalid)?; + let document = reader.document(document_limit)?; + if key.get("format").and_then(Value::as_str) != Some(self.format) + || key.get("app").and_then(Value::as_str) != Some(self.app) + || key.get("document").and_then(Value::as_str) != Some(digest(&document).as_str()) + { + return Err(invalid("thumbnail key")); + } + let png = reader.limited_part("cache/thumbnail.png", self.max_bytes)?; + if !self.valid(&png) || key.get("payload").and_then(Value::as_str) != Some(digest(&png).as_str()) { + return Err(invalid("thumbnail payload")); + } + Ok(png) + } +} + +#[cfg(test)] +#[path = "container_tests.rs"] +mod tests; diff --git a/crates/format/src/container_tests.rs b/crates/format/src/container_tests.rs new file mode 100644 index 000000000..bda37d000 --- /dev/null +++ b/crates/format/src/container_tests.rs @@ -0,0 +1,67 @@ +use super::*; + +const LIMITS: Limits = Limits { + max_entries: 8, + max_expanded: || 1 << 20, + part_limit: |name| if name.ends_with(".big") { 1 << 20 } else { 1024 }, + level: |_, _| 1, + check_size: |length| if length <= 1 << 20 { Ok(()) } else { Err("too large".into()) }, + cancelled: None, +}; + +/// Parts and blobs written are read back as they were; a blob is stored once, named by its hash, +/// and checked against it. +#[test] +fn parts_and_blobs_read_back() { + let mut writer = Writer::new(LIMITS); + writer.part("document.json", br#"{"a":1}"#, true).unwrap(); + let first = writer.blob(b"payload", "bin", false).unwrap(); + let again = writer.blob(b"payload", "bin", true).unwrap(); + assert_eq!(first, again, "the same payload is one blob"); + assert_eq!(first, Value::String(format!("blobs/{}.bin", digest(b"payload")))); + let bytes = writer.finish().unwrap(); + assert!(is_container(&bytes)); + let mut reader = Reader::new(Cursor::new(bytes), LIMITS).unwrap(); + assert_eq!(reader.part_names().len(), 2); + assert!(reader.has_part("document.json") && !reader.has_part("other.json")); + assert_eq!(&*reader.document(64).unwrap(), br#"{"a":1}"#); + let reference = serde_json::json!({"blob": first}); + assert_eq!(reader.blob(&reference, "blob", "bin").unwrap(), b"payload"); + assert!(reader.blob(&reference, "blob", "png").is_err(), "another extension"); + assert_eq!(reader.hydrated, 7); + reader.hydrated = (LIMITS.max_expanded)(); + assert!(reader.blob(&reference, "blob", "bin").unwrap_err().to_string().contains("resolved payloads too large")); +} + +/// A part past its limit, or more entries than the limit, are refused as they are written. +#[test] +fn budgets_are_kept_when_writing() { + let mut writer = Writer::new(LIMITS); + assert_eq!(writer.part("small.json", &[0; 1025], false), Err(FormatError::Invalid("part too large".into()))); + assert!(writer.part("large.big", &[0; 1025], true).is_ok()); + for i in 0..7 { + writer.part(&format!("{i}.json"), b"x", false).unwrap(); + } + assert_eq!(writer.part("one-more.json", b"x", false), Err(FormatError::Invalid("package too large".into()))); + assert!(!writer.room(1, 0, 1 << 20), "no room for an entry past the limit"); +} + +/// A thumbnail is kept only for the file it shows. +#[test] +fn a_thumbnail_is_keyed_to_its_file() { + let picture = Thumbnail { format: "app-thumbnail/1", app: "1.0", size: [2, 1], max_bytes: 1024 }; + let mut png = b"\x89PNG\r\n\x1a\n\0\0\0\rIHDR".to_vec(); + png.extend_from_slice(&2u32.to_be_bytes()); + png.extend_from_slice(&1u32.to_be_bytes()); + assert!(picture.valid(&png)); + let mut writer = Writer::new(LIMITS); + writer.part("document.json", b"{}", false).unwrap(); + picture.write(&mut writer, &png, b"{}", 8 << 20).unwrap(); + let mut reader = Reader::new(Cursor::new(writer.finish().unwrap()), LIMITS).unwrap(); + assert_eq!(picture.read(&mut reader, 64).unwrap(), png); + let mut writer = Writer::new(LIMITS); + writer.part("document.json", b"{\"changed\":1}", false).unwrap(); + picture.write(&mut writer, &png, b"{}", 8 << 20).unwrap(); + let mut reader = Reader::new(Cursor::new(writer.finish().unwrap()), LIMITS).unwrap(); + assert!(picture.read(&mut reader, 64).is_err(), "stale"); +} diff --git a/crates/format/src/lib.rs b/crates/format/src/lib.rs new file mode 100644 index 000000000..8eb495417 --- /dev/null +++ b/crates/format/src/lib.rs @@ -0,0 +1,252 @@ +//! Versioned file formats: what an app needs to read every file it ever wrote, and to open a file +//! a newer build of it wrote. +//! +//! A file starts with `"format": "N"`. A [`Family`] is one kind of file (an app's designs, +//! its drawings): its tag, its own numbers, and how a file of an older number is brought up to +//! this build's, step by step (N → N+1 → … → current). The app's code only knows the current +//! format; all translation lives in the steps: +//! - the steps written out by hand for the first formats, one per format ([`Formats::hand`]); +//! - then one folder per format, `v/`, one file per change in it ([`Part`]), each with a step +//! when files from before the change are rewritten as they open ([`Formats::folded`]); +//! - then the changes no release has a number for yet, in `pending/` ([`Formats::pending`]): +//! while there are any, the build writes the next number, with their names in the file's +//! `format_pending`, so a later build runs just the steps a file is missing. A release moves +//! them into the next `v/`. [`build`] lists the folders for a build script. +//! +//! A file a newer build wrote says so by a number past this build's or a change name this build +//! doesn't have ([`Family::newer`]); the app then reads what it can and keeps the rest +//! ([`newer`]). A file is saved as JSON, or in a [`container`] with its binary payloads. +//! +//! Steps are JSON-level (the file's shape) and return the app's own error type; every error this +//! crate makes is a [`FormatError`], which the app's error type takes `From`. + +use serde_json::Value; + +pub mod build; +pub mod container; +pub mod newer; + +/// Why a file is refused: its text says what is wrong, as the user reads it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum FormatError { + /// The file isn't one of the family's, or it is damaged. + Invalid(String), + /// The work was cancelled (a save the person stopped): nothing more was written. + Cancelled, +} + +impl std::fmt::Display for FormatError { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + FormatError::Invalid(why) => f.write_str(why), + FormatError::Cancelled => f.write_str("cancelled"), + } + } +} + +impl std::error::Error for FormatError {} + +/// One JSON-level upgrade step: rewrites a file in place, or says why it can't. +pub type Step = fn(&mut Value) -> Result<(), E>; + +/// One change to a family's file format: a file in its `v/` or `pending/` folder. +pub struct Part { + /// The file's name, which a file written while the change was pending lists. + pub name: &'static str, + /// How a file from before the change is rewritten as it opens, if it is. + pub step: Option>, +} + +/// Another spelling of a change name that a file of one format may carry (a build that named the +/// change otherwise): read as the change it stands for, never written. +#[derive(Clone, Copy, Debug)] +pub struct Alias { + /// The format whose files may say it. + pub format: u32, + /// The spelling in the file. + pub name: &'static str, + /// The change it stands for. + pub known_as: &'static str, +} + +/// A family's upgrade path: the steps written out by hand, the folded formats after them (each a +/// list of changes) and the pending changes, which make the next format. +pub struct Formats<'a, E> { + /// Entry `i` turns format `i + 1` into `i + 2`. + pub hand: &'a [Step], + /// Each format after the hand-written ones, oldest first, and its changes. + pub folded: &'a [(u32, &'a [Part])], + /// The changes no release has a number for yet. + pub pending: &'a [Part], +} + +/// A kind of file whose format is versioned: its own format tag, its own numbers and its own +/// changes. Reading a file's format, telling a file a newer build saved and the upgrade are the +/// same for every family. +pub struct Family<'a, E> { + /// The app, as messages name it. + pub app: &'static str, + /// What a file of the family is called in messages. + pub noun: &'static str, + /// The tag before the number in a file's `format`. + pub prefix: &'static str, + /// The tag files saved under an older name carry: read, never written. + pub legacy_prefix: Option<&'static str>, + /// The format of a file that names none, if such files exist. + pub untagged: Option, + /// Other spellings of change names that files may carry. + pub aliases: &'a [Alias], + /// The upgrade path. + pub formats: Formats<'a, E>, +} + +/// How a file shows a newer build saved it ([`Family::newer`]). +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Newer { + /// The number the file says. + pub format: u32, + /// The number this build reads up to. + pub reads_up_to: u32, + /// The changes the file names that this build doesn't have. + pub unknown_changes: Vec, +} + +impl Formats<'_, E> { + /// The format this build writes: the last folded one, or the next while changes are pending. + pub const fn current(&self) -> u32 { + self.hand.len() as u32 + 1 + self.folded.len() as u32 + if self.pending.is_empty() { 0 } else { 1 } + } + + /// The changes format `version` is made of, if it is made of changes. + fn parts(&self, version: u32) -> Option<&[Part]> { + let after = version.checked_sub(self.hand.len() as u32 + 2)? as usize; + match self.folded.get(after) { + Some((_, parts)) => Some(parts), + None if after == self.folded.len() && !self.pending.is_empty() => Some(self.pending), + None => None, + } + } + + /// Whether a change of this name is anywhere in this build's history. + fn knows_part_name(&self, name: &str) -> bool { + self.folded.iter().flat_map(|(_, parts)| *parts).chain(self.pending).any(|part| part.name == name) + } +} + +impl Family<'_, E> { + /// The format this build writes: the last folded one, or the next while changes are pending. + pub const fn current(&self) -> u32 { + self.formats.current() + } + + /// What a file of the family is called in messages. + pub const fn noun(&self) -> &'static str { + self.noun + } + + /// The names of the pending changes this build writes into a file (`format_pending`). + pub fn pending_names(&self) -> Vec { + self.formats.pending.iter().map(|p| p.name.to_string()).collect() + } + + /// The format tag of format `n`. + pub fn format_string(&self, n: u32) -> String { + format!("{}{n}", self.prefix) + } + + /// The version in one of this family's format tags; `None` for any other tag, another + /// family's included. + pub fn version_of(&self, s: &str) -> Option { + s.strip_prefix(self.prefix).or_else(|| self.legacy_prefix.and_then(|p| s.strip_prefix(p)))?.parse().ok() + } + + /// The change a name a file of format `version` lists stands for: its alias's, or itself. + /// An alias counts only while this build has the change it stands for, so recognising it + /// never grants support to another reader. + fn canonical_applied_name<'name>(&self, version: u32, name: &'name str) -> &'name str { + match self.aliases.iter().find(|a| a.format == version && a.name == name) { + Some(alias) if self.formats.knows_part_name(alias.known_as) => alias.known_as, + _ => name, + } + } + + /// What says a file of format `version` with the changes `applied` came from a newer build: + /// a number past this build's, or a change this build doesn't have anywhere in its history + /// (a branch's pending change may have landed at a later number). A list beside a format that + /// isn't made of changes means nothing (a tool or a test set an older number on a newer file). + /// `None` for a file this build fully knows. + pub fn newer(&self, version: u32, applied: Option<&[String]>) -> Option { + let current = self.current(); + let listed = applied.filter(|_| version > current || self.formats.parts(version).is_some()).unwrap_or_default(); + let unknown_changes: Vec = + listed.iter().filter(|name| !self.formats.knows_part_name(self.canonical_applied_name(version, name))).cloned().collect(); + (version > current || !unknown_changes.is_empty()).then_some(Newer { format: version, reads_up_to: current, unknown_changes }) + } +} + +impl> Family<'_, E> { + /// Read a file's format and take its `format_pending` out of its JSON, before anything else + /// in it is read: a file that isn't this family's is refused here. One a newer build saved is + /// not: [`Family::newer`] says so. + pub fn take_version(&self, v: &mut Value) -> Result<(u32, Option>), E> { + let (app, noun) = (self.app, self.noun); + let not_ours = |what: String| E::from(FormatError::Invalid(format!("not a {app} {noun} ({what})"))); + let Some(obj) = v.as_object() else { return Err(not_ours("expected a JSON object".into())) }; + let version = match obj.get("format") { + None => self.untagged.ok_or_else(|| not_ours("no format".into()))?, + Some(Value::String(f)) => self.version_of(f).ok_or_else(|| not_ours(format!("format `{f}`")))?, + Some(_) => return Err(not_ours("format is not a string".into())), + }; + let applied = take_names(v, "format_pending", noun).map_err(E::from)?; + if version == 0 { + return Err(not_ours("format 0".into())); + } + Ok((version, applied)) + } + + /// Bring a file of format `version` up to this build's; `applied` is its `format_pending` + /// (both from [`Family::take_version`]): the changes of its format it already has, when it + /// was written while they were pending. The others' steps run first, and already-applied + /// changes never run again at their later number. A file past this build's number has no + /// steps to run. + pub fn upgrade(&self, v: &mut Value, version: u32, applied: Option<&[String]>) -> Result<(), E> { + let formats = &self.formats; + if version == 0 { + return Err(E::from(FormatError::Invalid(format!("not a {} {} (format 0)", self.app, self.noun)))); + } + // A list beside a format that isn't made of changes is ignored, like any field an upgrade + // drops. + let applied = applied.filter(|_| formats.parts(version).is_some()); + let already_applied = + |part: &Part| applied.is_some_and(|names| names.iter().any(|name| self.canonical_applied_name(version, name) == part.name)); + if applied.is_some() { + for part in formats.parts(version).unwrap_or_default().iter().filter(|part| !already_applied(part)) { + part.step.map_or(Ok(()), |step| step(v))?; + } + } + for from in version..self.current() { + match formats.hand.get(from as usize - 1) { + Some(step) => step(v)?, + None => { + for part in formats.parts(from + 1).unwrap_or_default().iter().filter(|part| !already_applied(part)) { + part.step.map_or(Ok(()), |step| step(v))?; + } + } + } + } + Ok(()) + } +} + +/// Take a short list of names out of a file's JSON: its `format_pending` (the pending changes it +/// has). +fn take_names(v: &mut Value, key: &str, noun: &str) -> Result>, FormatError> { + let Some(list) = v.as_object_mut().and_then(|o| o.remove(key)) else { return Ok(None) }; + let invalid = || FormatError::Invalid(format!("damaged {noun}: `{key}` is not a short list of names")); + let list = list.as_array().filter(|l| l.len() <= 1000).ok_or_else(invalid)?; + list.iter().map(|n| n.as_str().filter(|n| n.len() <= 128).map(str::to_string).ok_or_else(invalid)).collect::>().map(Some) +} + +#[cfg(test)] +#[path = "lib_tests.rs"] +mod tests; diff --git a/crates/format/src/lib_tests.rs b/crates/format/src/lib_tests.rs new file mode 100644 index 000000000..6874ddbf4 --- /dev/null +++ b/crates/format/src/lib_tests.rs @@ -0,0 +1,134 @@ +use super::*; +use serde_json::json; + +/// The app's error, as an app has one. +#[derive(Debug, PartialEq)] +struct AppError(String); + +impl From for AppError { + fn from(e: FormatError) -> Self { + AppError(e.to_string()) + } +} + +/// Each step appends its name to the file's `log`, so the order steps ran in can be read back. +fn log(v: &mut Value, step: &str) { + if let Some(list) = v.get_mut("log").and_then(Value::as_array_mut) { + list.push(json!(step)); + } +} + +const HAND: [Step; 2] = [ + |v| { + log(v, "1to2"); + Ok(()) + }, + |v| { + log(v, "2to3"); + Ok(()) + }, +]; +const V4: [Part; 2] = [ + Part { + name: "a", + step: Some(|v| { + log(v, "a"); + Ok(()) + }), + }, + Part { name: "b", step: None }, +]; +const V5: [Part; 1] = [Part { + name: "c", + step: Some(|v| { + log(v, "c"); + Ok(()) + }), +}]; +const FOLDED: [(u32, &[Part]); 2] = [(4, &V4), (5, &V5)]; +const PENDING: [Part; 2] = [ + Part { + name: "d", + step: Some(|v| { + log(v, "d"); + Ok(()) + }), + }, + Part { + name: "e", + step: Some(|v| { + log(v, "e"); + Ok(()) + }), + }, +]; +const ALIASES: [Alias; 1] = [Alias { format: 5, name: "old-c", known_as: "c" }]; + +/// Format 1 untagged; hand steps to 3; folded 4 and 5; pending changes make 6. +const FAMILY: Family<'static, AppError> = Family { + app: "App", + noun: "design", + prefix: "app/", + legacy_prefix: Some("old/"), + untagged: Some(1), + aliases: &ALIASES, + formats: Formats { hand: &HAND, folded: &FOLDED, pending: &PENDING }, +}; + +fn steps_run(version: u32, applied: Option<&[String]>) -> Vec { + let mut v = json!({"log": []}); + FAMILY.upgrade(&mut v, version, applied).unwrap(); + v["log"].as_array().unwrap().iter().map(|s| s.as_str().unwrap().to_string()).collect() +} + +#[test] +fn tags_and_numbers() { + assert_eq!(FAMILY.current(), 6); + assert_eq!(FAMILY.format_string(6), "app/6"); + assert_eq!(FAMILY.version_of("app/4"), Some(4)); + assert_eq!(FAMILY.version_of("old/3"), Some(3), "the legacy tag is read"); + assert_eq!(FAMILY.version_of("other/3"), None); + assert_eq!(FAMILY.pending_names(), vec!["d".to_string(), "e".to_string()]); +} + +#[test] +fn a_file_is_taken_apart_or_refused_with_the_apps_words() { + let mut v = json!({"format": "app/6", "format_pending": ["d"], "x": 1}); + assert_eq!(FAMILY.take_version(&mut v), Ok((6, Some(vec!["d".to_string()])))); + assert!(v.get("format_pending").is_none(), "taken out"); + assert_eq!(FAMILY.take_version(&mut json!({})), Ok((1, None)), "untagged"); + let refused = |mut v: Value| FAMILY.take_version(&mut v).unwrap_err().0; + assert_eq!(refused(json!([])), "not a App design (expected a JSON object)"); + assert_eq!(refused(json!({"format": "other/2"})), "not a App design (format `other/2`)"); + assert_eq!(refused(json!({"format": 2})), "not a App design (format is not a string)"); + assert_eq!(refused(json!({"format": "app/0"})), "not a App design (format 0)"); + assert_eq!(refused(json!({"format": "app/2", "format_pending": [1]})), "damaged design: `format_pending` is not a short list of names"); +} + +#[test] +fn every_step_runs_once_in_order() { + assert_eq!(steps_run(1, None), ["1to2", "2to3", "a", "c", "d", "e"]); + assert_eq!(steps_run(4, None), ["c", "d", "e"]); + assert_eq!(steps_run(6, None), Vec::::new()); + // A file written while `d` was pending has it: only `e` runs. + assert_eq!(steps_run(6, Some(&["d".to_string()])), ["e"]); + // A file of format 5 written while `c` was still pending, without it: `c` runs first. + assert_eq!(steps_run(5, Some(&[])), ["c", "d", "e"]); + // Under its other spelling `c` counts as had. + assert_eq!(steps_run(5, Some(&["old-c".to_string()])), ["d", "e"]); + // A list beside a hand-written format means nothing. + assert_eq!(steps_run(2, Some(&["d".to_string()])), ["2to3", "a", "c", "d", "e"]); + let mut v = json!({}); + assert_eq!(FAMILY.upgrade(&mut v, 0, None), Err(AppError("not a App design (format 0)".into()))); +} + +#[test] +fn a_newer_file_is_told_by_its_number_or_an_unknown_change() { + assert_eq!(FAMILY.newer(6, None), None); + assert_eq!(FAMILY.newer(6, Some(&["d".to_string()])), None); + assert_eq!(FAMILY.newer(7, None), Some(Newer { format: 7, reads_up_to: 6, unknown_changes: Vec::new() })); + assert_eq!(FAMILY.newer(6, Some(&["z".to_string()])), Some(Newer { format: 6, reads_up_to: 6, unknown_changes: vec!["z".to_string()] })); + assert_eq!(FAMILY.newer(5, Some(&["old-c".to_string()])), None, "an alias of a known change"); + assert_eq!(FAMILY.newer(4, Some(&["old-c".to_string()])), Some(Newer { format: 4, reads_up_to: 6, unknown_changes: vec!["old-c".to_string()] })); + assert_eq!(FAMILY.newer(2, Some(&["z".to_string()])), None, "a list beside a hand-written format means nothing"); +} diff --git a/crates/format/src/newer.rs b/crates/format/src/newer.rs new file mode 100644 index 000000000..e9cb51eb1 --- /dev/null +++ b/crates/format/src/newer.rs @@ -0,0 +1,401 @@ +//! A file a newer build saved: it opens, with a warning, and saving it loses nothing. +//! +//! A newer format number, or a change the file names that this build doesn't have, says a newer +//! build saved the file ([`crate::Family::newer`]). It may use nothing this build lacks, so the app +//! reads it as usual. When part of it can't be read, that part stays out of the way and the rest +//! opens: the app reads the elements of its lists it can ([`NewerFile::keep_element`]), then any +//! other top-level section it can't read is left out whole ([`leave_out_unreadable`], +//! [`read_around`]), and a field it doesn't know, which typed reading would drop, is noticed by +//! comparing the file with what was read ([`NewerFile::compare`]). +//! +//! All of these are named in [`NewerFile::not_understood`] and go back into the file when it is +//! saved ([`NewerFile::restore_into`]), as they came. What can't be put back because the file was +//! changed around it is what `restore_into` returns. + +use std::collections::BTreeMap; +use std::sync::Arc; + +use serde_json::{Map, Value, json}; + +use crate::Newer; + +/// The most sections left out one at a time to find the one a file can't be read with. +const MAX_SECTION_TRIES: usize = 64; + +/// What the file says and holds that this build doesn't read. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct NewerFile { + /// The app, as the notice names it. + pub app: &'static str, + /// The number the file says. + pub format: u32, + /// The number this build reads up to. + pub reads_up_to: u32, + /// The changes the file names that this build doesn't have. + pub unknown_changes: Vec, + /// What this build couldn't read, by name. + pub not_understood: Vec, + /// Fields known records lost in typed reading. + kept: Option, + /// Top-level sections left out whole. + sections: Vec

                      , + /// Elements left out of a top-level list: its key and the element. + elements: Vec<(String, Value)>, + /// The parts of a container this build has no use for: name and bytes. A blob only one of the + /// kept pieces refers to is one of them. + pub parts: Vec<(String, Arc<[u8]>)>, + /// The file's `container.json`, when this build doesn't know what it says. + pub container: Option, +} + +#[derive(Clone, Debug, PartialEq)] +struct Section { + key: String, + value: Value, + /// This build's record of the section, without the file's: while it is unchanged, the file's + /// goes back. + empty: Option, +} + +/// The fields of a record that typed reading dropped. +#[derive(Clone, Debug, PartialEq)] +enum Kept { + Field(Value), + Fields(BTreeMap), + Items(Vec<(Anchor, Kept)>), +} + +/// Which element of a list some kept fields belong to. +#[derive(Clone, Debug, PartialEq)] +enum Anchor { + Id(u64), + Name(String), + /// Its place, good only while the list keeps its length. + Index { + at: usize, + of: usize, + }, +} + +impl NewerFile { + /// A file of `app` that `newer` says a newer build saved, nothing left out of it yet. + pub fn new(app: &'static str, newer: &Newer) -> NewerFile { + NewerFile { + app, + format: newer.format, + reads_up_to: newer.reads_up_to, + unknown_changes: newer.unknown_changes.clone(), + ..NewerFile::default() + } + } + + /// What to tell the user, whatever else is said. + pub fn notice(&self) -> String { + let (app, reads, format) = (self.app, self.reads_up_to, self.format); + match self.unknown_changes.first() { + Some(change) if format <= reads => { + format!("Saved by a newer {app} (format {format} with `{change}`, which this version doesn't know). If something's missing, update.") + } + _ => format!("Saved by a newer {app} (format {format}, this version reads up to {reads}). If something's missing, update."), + } + } + + /// Every line to report: the notice, then what couldn't be read, by name. + pub fn warnings(&self) -> Vec { + let unread = self.not_understood.iter().map(|what| format!("Not read: {what}. Saving keeps it.")); + std::iter::once(self.notice()).chain(unread).collect() + } + + /// What a reply says about it. + pub fn report(&self) -> Value { + json!({ + "format": self.format, + "reads_up_to": self.reads_up_to, + "unknown_changes": self.unknown_changes, + "not_understood": self.not_understood, + "notice": self.notice(), + }) + } + + /// Whether the next save needs a container to keep what the file holds: plain JSON has no room + /// for parts beside the file's own. + pub fn needs_container(&self) -> bool { + !self.parts.is_empty() + } + + /// Whether anything kept back names this text (a blob's name in a container). + pub fn mentions(&self, text: &str) -> bool { + fn kept(k: &Kept, text: &str) -> bool { + match k { + Kept::Field(v) => value_mentions(v, text), + Kept::Fields(m) => m.values().any(|x| kept(x, text)), + Kept::Items(l) => l.iter().any(|(_, x)| kept(x, text)), + } + } + self.kept.as_ref().is_some_and(|k| kept(k, text)) + || self.sections.iter().any(|s| value_mentions(&s.value, text)) + || self.elements.iter().any(|(_, v)| value_mentions(v, text)) + } + + /// Say that a section the reader couldn't finish reading is left out. `empty` is what the + /// app writes for the section while it holds nothing, if anything. + pub fn keep_section(&mut self, key: &str, value: Value, empty: Option, why: &str) { + self.not_understood.push(format!("section `{key}` ({why})")); + self.sections.push(Section { key: key.into(), value, empty }); + } + + /// Say that an element of the top-level list `key` is left out, as `note` names it; it goes + /// back at the end of the list when the file is saved. + pub fn keep_element(&mut self, key: &str, element: Value, note: String) { + self.not_understood.push(note); + self.elements.push((key.into(), element)); + } + + /// Compare the file as it reads (`file`, after the same upgrade as what was read) with what was + /// read of it (`known`, its typed record written out): what `known` lacks is kept and named. + /// An object whose `type` is `placeholder_tag` (an element the app kept whole) and the fields + /// in `container_only` (what a container adds beside the file's own) are not compared; nor + /// are the top level's `format` and `format_pending`. + pub fn compare(&mut self, file: &Value, known: &Value, placeholder_tag: &str, container_only: &[&str]) { + let mut paths = Vec::new(); + self.kept = vanished(file, known, "", &mut paths, placeholder_tag, container_only); + self.not_understood.extend(paths); + for section in &mut self.sections { + section.empty = known.get(§ion.key).cloned(); + } + } + + /// Write back what was kept of the file into `value`, the file as this build writes it. + /// Returns what couldn't go back, because the file was changed around it. + pub fn restore_into(&self, value: &mut Value) -> Vec { + let mut lost = Vec::new(); + if let Some(kept) = &self.kept { + apply(kept, value, "", &mut lost); + } + if let Some(top) = value.as_object_mut() { + for section in &self.sections { + if top.get(§ion.key) == section.empty.as_ref() { + top.insert(section.key.clone(), section.value.clone()); + } else { + lost.push(format!("section `{}`, replaced by what was edited here", section.key)); + } + } + for (key, element) in &self.elements { + let name = element.get("name"); + match top.entry(key.clone()).or_insert_with(|| json!([])) { + Value::Array(list) if name.is_none() || !list.iter().any(|x| x.get("name") == name) => list.push(element.clone()), + _ => lost.push(format!("`{key}` element {}, replaced by what was made here", name.and_then(Value::as_str).unwrap_or("unnamed"))), + } + } + } + lost + } +} + +fn value_mentions(v: &Value, text: &str) -> bool { + match v { + Value::String(s) => s == text, + Value::Array(a) => a.iter().any(|x| value_mentions(x, text)), + Value::Object(o) => o.values().any(|x| value_mentions(x, text)), + _ => false, + } +} + +/// The first line of a reader's error, without the list of every kind it knows, and without the +/// `" file: "` its reader starts it with. +pub fn short<'a>(why: &'a str, noun: &str) -> &'a str { + let why = why.split(", expected").next().unwrap_or(why); + why.strip_prefix(&format!("{noun} file: ")).unwrap_or(why) +} + +/// Leave a section out and keep it. A section the file needs is left empty. +fn move_out(top: &mut Map, key: &str, why: &str, noun: &str, file: &mut NewerFile) { + let Some(value) = top.remove(key) else { return }; + file.not_understood.push(format!("section `{key}` ({})", short(why, noun))); + file.sections.push(Section { key: key.into(), value, empty: None }); +} + +/// Every top-level section of `top` that doesn't read by itself (`piece`, the app's reading of a +/// file holding just that section) is left out and kept in `file`. `noun` is what a file of the +/// app's is called, which its reader's errors start with. +pub fn leave_out_unreadable( + top: &mut Map, + file: &mut NewerFile, + noun: &str, + piece: impl Fn(&str, &Value) -> Result<(), E>, +) { + let keys: Vec = top.keys().cloned().collect(); + for key in &keys { + let value = top.get(key).cloned().unwrap_or_default(); + if let Err(why) = piece(key, &value) { + move_out(top, key, &why.to_string(), noun, file); + } + } +} + +/// Read `top` with `attempt`, leaving out the sections it can't be read with: if it doesn't read, +/// each section but the `core` ones (which the file can't be read without) is tried left out alone, +/// and as a last resort every one of them is. What is left out is kept in `file`. The error is the +/// first attempt's, when even the core alone doesn't read. +pub fn read_around( + top: &mut Map, + file: &mut NewerFile, + core: &[&str], + noun: &str, + attempt: impl Fn(&Map) -> Result, +) -> Result { + let first = match attempt(top) { + Ok(doc) => return Ok(doc), + Err(why) => why.to_string(), + }; + // Sections that are fine by themselves but not together with the rest. + let keys: Vec = top.keys().filter(|k| !core.contains(&k.as_str())).cloned().collect(); + // Each try reads the whole file: a file of many sections goes straight to the last resort. + for key in keys.iter().filter(|_| keys.len() <= MAX_SECTION_TRIES) { + let mut without = top.clone(); + without.remove(key); + if let Ok(doc) = attempt(&without) { + move_out(top, key, &first, noun, file); + return Ok(doc); + } + } + let mut bare = top.clone(); + bare.retain(|key, _| core.contains(&key.as_str())); + match attempt(&bare) { + Ok(doc) => { + for key in &keys { + move_out(top, key, &first, noun, file); + } + Ok(doc) + } + Err(_) => Err(first), + } +} + +/// A value a writer leaves out without losing anything: not worth telling anyone about. +pub fn looks_default(v: &Value) -> bool { + match v { + Value::Null => true, + Value::Bool(b) => !b, + Value::Number(n) => n.as_f64() == Some(0.0), + Value::String(s) => s.is_empty(), + Value::Array(a) => a.is_empty(), + Value::Object(o) => o.is_empty(), + } +} + +/// What `raw` has that `known`, what was read of it, doesn't. `paths` gets those fields' names. +fn vanished(raw: &Value, known: &Value, path: &str, paths: &mut Vec, placeholder_tag: &str, container_only: &[&str]) -> Option { + match (raw, known) { + (Value::Object(raw), Value::Object(known)) => { + if known.get("type").and_then(Value::as_str) == Some(placeholder_tag) { + return None; + } + let mut kept = BTreeMap::new(); + for (key, value) in raw { + if container_only.contains(&key.as_str()) || (path.is_empty() && matches!(key.as_str(), "format" | "format_pending")) { + continue; + } + let inner = if path.is_empty() { key.clone() } else { format!("{path}.{key}") }; + match known.get(key) { + None => { + if !looks_default(value) { + paths.push(format!("field `{inner}`")); + } + kept.insert(key.clone(), Kept::Field(value.clone())); + } + Some(known) => { + if let Some(k) = vanished(value, known, &inner, paths, placeholder_tag, container_only) { + kept.insert(key.clone(), k); + } + } + } + } + (!kept.is_empty()).then_some(Kept::Fields(kept)) + } + (Value::Array(raw), Value::Array(known)) => { + let mut items = Vec::new(); + for (at, element) in raw.iter().enumerate() { + let anchor = anchor_of(element).unwrap_or(Anchor::Index { at, of: raw.len() }); + let Some(partner) = find(known, &anchor) else { continue }; + let label = match (element.get("name").and_then(Value::as_str), &anchor) { + (Some(name), _) => format!("{path}[{name}]"), + (None, Anchor::Id(id)) => format!("{path}[{id}]"), + _ => format!("{path}[{at}]"), + }; + if let Some(k) = vanished(element, partner, &label, paths, placeholder_tag, container_only) { + items.push((anchor, k)); + } + } + (!items.is_empty()).then_some(Kept::Items(items)) + } + _ => None, + } +} + +fn anchor_of(element: &Value) -> Option { + if let Some(id) = element.get("id").and_then(Value::as_u64) { + return Some(Anchor::Id(id)); + } + element.get("name").and_then(Value::as_str).map(|name| Anchor::Name(name.to_string())) +} + +fn find<'a>(list: &'a [Value], anchor: &Anchor) -> Option<&'a Value> { + match anchor { + Anchor::Id(id) => list.iter().find(|x| x.get("id").and_then(Value::as_u64) == Some(*id)), + Anchor::Name(name) => list.iter().find(|x| x.get("name").and_then(Value::as_str) == Some(name)), + Anchor::Index { at, of } => (list.len() == *of).then(|| list.get(*at)).flatten(), + } +} + +fn find_mut<'a>(list: &'a mut [Value], anchor: &Anchor) -> Option<&'a mut Value> { + match anchor { + Anchor::Id(id) => list.iter_mut().find(|x| x.get("id").and_then(Value::as_u64) == Some(*id)), + Anchor::Name(name) => list.iter_mut().find(|x| x.get("name").and_then(Value::as_str) == Some(name)), + Anchor::Index { at, of } => (list.len() == *of).then(|| list.get_mut(*at)).flatten(), + } +} + +/// Put the kept fields back. An element that is gone was deleted here, its fields with it; one +/// whose place can't be told any more, and a field whose record is gone, go into `lost`. +fn apply(kept: &Kept, value: &mut Value, path: &str, lost: &mut Vec) { + match kept { + Kept::Field(_) => {} + Kept::Fields(fields) => { + let Some(object) = value.as_object_mut() else { + lost.push(format!("field `{path}`")); + return; + }; + for (key, sub) in fields { + let inner = if path.is_empty() { key.clone() } else { format!("{path}.{key}") }; + match (sub, object.get_mut(key)) { + (Kept::Field(v), None) => { + object.insert(key.clone(), v.clone()); + } + (Kept::Field(_), Some(_)) => {} + (sub, Some(inner_value)) => apply(sub, inner_value, &inner, lost), + // The list it was in is empty and not written: its elements were deleted. + (Kept::Items(_), None) => {} + (_, None) => lost.push(format!("field `{inner}`")), + } + } + } + Kept::Items(items) => { + let Some(list) = value.as_array_mut() else { + lost.push(format!("field `{path}`")); + return; + }; + for (anchor, sub) in items { + match (find_mut(list, anchor), anchor) { + (Some(element), _) => apply(sub, element, path, lost), + (None, Anchor::Index { at, .. }) => lost.push(format!("element {at} of `{path}`")), + (None, _) => {} + } + } + } + } +} + +#[cfg(test)] +#[path = "newer_tests.rs"] +mod tests; diff --git a/crates/format/src/newer_tests.rs b/crates/format/src/newer_tests.rs new file mode 100644 index 000000000..90e5b0037 --- /dev/null +++ b/crates/format/src/newer_tests.rs @@ -0,0 +1,48 @@ +use super::*; + +fn newer() -> Newer { + Newer { format: 9, reads_up_to: 8, unknown_changes: Vec::new() } +} + +/// What typed reading dropped is named and goes back on saving, where it was. +#[test] +fn dropped_fields_are_named_and_put_back() { + let file = json!({"name": "A", "format": "app/9", "items": [{"id": 1, "size": 2, "colour": "red"}], "extra": {"x": 1}}); + let known = json!({"name": "A", "items": [{"id": 1, "size": 2}]}); + let mut said = NewerFile::new("App", &newer()); + said.compare(&file, &known, "placeholder", &[]); + assert_eq!(said.not_understood, ["field `extra`", "field `items[1].colour`"]); + let mut saved = json!({"name": "A", "items": [{"id": 1, "size": 3}]}); + assert!(said.restore_into(&mut saved).is_empty()); + assert_eq!(saved, json!({"name": "A", "items": [{"id": 1, "size": 3, "colour": "red"}], "extra": {"x": 1}})); + assert_eq!(said.notice(), "Saved by a newer App (format 9, this version reads up to 8). If something's missing, update."); +} + +/// A section that can't be read is left out, kept, and goes back while it is unchanged here. +#[test] +fn unreadable_sections_are_left_out_and_kept() { + let mut top = match json!({"name": "A", "good": 1, "bad": 2}) { + Value::Object(m) => m, + _ => unreachable!(), + }; + let mut said = NewerFile::new("App", &newer()); + leave_out_unreadable(&mut top, &mut said, "design", |key: &str, _: &Value| if key == "bad" { Err("design file: no") } else { Ok(()) }); + assert!(!top.contains_key("bad")); + assert_eq!(said.not_understood, ["section `bad` (no)"]); + let read = + read_around( + &mut top, + &mut said, + &["name"], + "design", + |top: &Map| { + if top.contains_key("good") { Err("design file: clash") } else { Ok(top.len()) } + }, + ); + assert_eq!(read, Ok(1)); + assert_eq!(said.not_understood, ["section `bad` (no)", "section `good` (clash)"]); + let mut saved = json!({"name": "A"}); + said.compare(&saved.clone(), &saved.clone(), "placeholder", &[]); + assert!(said.restore_into(&mut saved).is_empty()); + assert_eq!(saved, json!({"name": "A", "good": 1, "bad": 2})); +} From d55335423a9719102b2c2f3dfa2f6cbf05e915d3 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:11:32 +0000 Subject: [PATCH 089/349] exr: share scanline RGBA writer --- crates/exr/src/lib.rs | 2 + crates/exr/src/rgba8.rs | 235 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+) create mode 100644 crates/exr/src/rgba8.rs diff --git a/crates/exr/src/lib.rs b/crates/exr/src/lib.rs index f1550f8de..78afd427e 100644 --- a/crates/exr/src/lib.rs +++ b/crates/exr/src/lib.rs @@ -18,6 +18,8 @@ //! - [`stream`]: one flat scan-line part read block by block, for pictures larger than memory. //! - [`cryptomatte_samples`]: a file's Cryptomatte layers and their per-pixel (ID, coverage) ranks. +/// Scanline OpenEXR writer using a caller-supplied linearization table. +pub mod rgba8; /// RFC 1950/1951 compressor for ZIP-compressed EXR chunks. pub mod zlib; diff --git a/crates/exr/src/rgba8.rs b/crates/exr/src/rgba8.rs new file mode 100644 index 000000000..0b26ab8c9 --- /dev/null +++ b/crates/exr/src/rgba8.rs @@ -0,0 +1,235 @@ +//! Single-part scanline OpenEXR output from RGBA8 pixels. + +/// Scanline chunk compression. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Compression { + /// Uncompressed. + None, + /// OpenEXR RLE. + Rle, + /// zlib per scanline. + Zips, + /// zlib per 16 scanlines. + Zip, +} +impl Compression { + fn code(self) -> u8 { + match self { + Self::None => 0, + Self::Rle => 1, + Self::Zips => 2, + Self::Zip => 3, + } + } + fn lines(self) -> usize { + if self == Self::Zip { 16 } else { 1 } + } +} +/// Why a frame cannot be encoded. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum Error { + /// Empty, overflowing or mismatched RGBA dimensions. + FrameSize, + /// Dimensions exceed the OpenEXR signed-size fields. + TooLarge, +} +fn checked_len(rgba: &[u8], w: u32, h: u32) -> Result { + let n = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(4)).ok_or(Error::FrameSize)?; + if w == 0 || h == 0 || rgba.len() != n { + return Err(Error::FrameSize); + } + Ok(n) +} + +/// IEEE 754 binary16 bits of `v`, rounded to nearest even (overflow → infinity, NaN → quiet NaN). +pub fn half(v: f32) -> u16 { + let b = v.to_bits(); + let sign = ((b >> 16) & 0x8000) as u16; + let exp = ((b >> 23) & 0xFF) as i32; + let man = b & 0x7F_FFFF; + if exp == 0xFF { + return sign | 0x7C00 | if man != 0 { 0x200 } else { 0 }; + } + // rounds `m >> shift` to nearest, ties to even (`shift` is 1..=24) + let round = |m: u32, shift: u32| { + let (q, rem, mid) = (m >> shift, m & ((1 << shift) - 1), 1 << (shift - 1)); + if rem > mid || (rem == mid && q & 1 == 1) { q + 1 } else { q } + }; + let e = exp - 127 + 15; + if e >= 0x1F { + sign | 0x7C00 + } else if e <= 0 { + if e < -10 { + return sign; + } + // subnormal half: the 24-bit significand scaled by 2^(e - 14); rounding up may carry + // into the smallest normal, which is the right encoding + sign | round(man | 0x80_0000, (14 - e) as u32) as u16 + } else { + // a carry out of the mantissa bumps the exponent (up to infinity), as it should + sign | round(((e as u32) << 23) | man, 13) as u16 + } +} + +/// An OpenEXR file: half-float scene-linear Rec.709 RGB, or RGBA with `alpha` (premultiplied, as +/// EXR defines alpha; the frame's straight alpha is multiplied in after linearisation). +pub fn write_rgba8(rgba: &[u8], w: u32, h: u32, alpha: bool, compression: Compression, linear: &[f32; 256]) -> Result, Error> { + let n = checked_len(rgba, w, h)?; + let too_large = || Error::TooLarge; + let (Ok(x_max), Ok(y_max)) = (i32::try_from(w - 1), i32::try_from(h - 1)) else { + return Err(too_large()); + }; + // channels in the alphabetical order the file layout requires + let names: &[u8] = if alpha { b"ABGR" } else { b"BGR" }; + let line = (w as usize).checked_mul(names.len() * 2).ok_or_else(|| Error::FrameSize)?; + // a chunk's byte count is a signed 32-bit field + let lines = compression.lines(); + if line.checked_mul(lines).and_then(|c| i32::try_from(c).ok()).is_none() { + return Err(too_large()); + } + + let mut hd = Vec::with_capacity(512); + hd.extend_from_slice(&[0x76, 0x2F, 0x31, 0x01]); // magic number 20000630 + hd.extend_from_slice(&[2, 0, 0, 0]); // version 2, single-part scan-line file, short names + let attr = |hd: &mut Vec, name: &str, ty: &str, value: &[u8]| { + for s in [name, ty] { + hd.extend_from_slice(s.as_bytes()); + hd.push(0); + } + hd.extend_from_slice(&(value.len() as i32).to_le_bytes()); + hd.extend_from_slice(value); + }; + let le = |v: &[f32]| v.iter().flat_map(|f| f.to_le_bytes()).collect::>(); + let mut channels = Vec::new(); + for &c in names { + channels.extend_from_slice(&[c, 0]); + channels.extend_from_slice(&1_i32.to_le_bytes()); // pixel type HALF + channels.extend_from_slice(&[0, 0, 0, 0]); // pLinear 0, reserved + channels.extend_from_slice(&1_i32.to_le_bytes()); // x sampling + channels.extend_from_slice(&1_i32.to_le_bytes()); // y sampling + } + channels.push(0); + let window: Vec = [0, 0, x_max, y_max].iter().flat_map(|v| v.to_le_bytes()).collect(); + attr(&mut hd, "channels", "chlist", &channels); + attr(&mut hd, "chromaticities", "chromaticities", &le(&[0.64, 0.33, 0.30, 0.60, 0.15, 0.06, 0.3127, 0.3290])); + attr(&mut hd, "compression", "compression", &[compression.code()]); + attr(&mut hd, "dataWindow", "box2i", &window); + attr(&mut hd, "displayWindow", "box2i", &window); + attr(&mut hd, "lineOrder", "lineOrder", &[0]); // INCREASING_Y + attr(&mut hd, "pixelAspectRatio", "float", &le(&[1.0])); + attr(&mut hd, "screenWindowCenter", "v2f", &le(&[0.0, 0.0])); + attr(&mut hd, "screenWindowWidth", "float", &le(&[1.0])); + hd.push(0); // end of header + + // offset table (one entry per chunk), then the chunks: first y, data size, data + let chunks = (h as usize).div_ceil(lines); + let table = chunks.checked_mul(8); + let body = (h as usize).checked_mul(line + 8); + let size = table.zip(body).and_then(|(t, b)| hd.len().checked_add(t)?.checked_add(b)).ok_or_else(|| Error::FrameSize)?; + // the uncompressed size: compressed chunks only shrink it + let mut out = Vec::with_capacity(size); + out.extend_from_slice(&hd); + let table_at = out.len(); + out.resize(table_at + chunks * 8, 0); + let lin = linear; + let opaque: [u16; 256] = std::array::from_fn(|i| half(lin[i])); + let row = w as usize * 4; + let wn = w as usize; + let mut px = vec![0_u16; wn * names.len()]; + let mut raw = Vec::with_capacity(line * lines); + // the deflate hash tables, shared by the frame's chunks instead of zeroed for each one + let mut tables = crate::zlib::Tables::default(); + for (k, block) in rgba[..n].chunks(row * lines).enumerate() { + raw.clear(); + for src in block.chunks_exact(row) { + // planar per line: every pixel of the first channel, then the next channel … + for (x, &[r, g, b, a]) in src.as_chunks::<4>().0.iter().enumerate() { + let rgb = [b, g, r]; + if alpha { + let k = f32::from(a) / 255.0; + px[x] = half(k); + for (c, &v) in rgb.iter().enumerate() { + px[(c + 1) * wn + x] = if a == 255 { opaque[v as usize] } else { half(lin[v as usize] * k) }; + } + } else { + for (c, &v) in rgb.iter().enumerate() { + px[c * wn + x] = opaque[v as usize]; + } + } + } + raw.extend(px.iter().flat_map(|v| v.to_le_bytes())); + } + let packed = match compression { + Compression::None => None, + Compression::Rle => Some(rle(&predict(&raw))), + Compression::Zips | Compression::Zip => Some(crate::zlib::zlib(&predict(&raw), &mut tables)), + }; + // a chunk that does not shrink is stored as it is (readers compare the sizes) + let data = packed.as_deref().filter(|p| p.len() < raw.len()).unwrap_or(&raw); + let offset = (out.len() as u64).to_le_bytes(); + out[table_at + k * 8..table_at + k * 8 + 8].copy_from_slice(&offset); + out.extend_from_slice(&((k * lines) as i32).to_le_bytes()); + out.extend_from_slice(&(data.len() as i32).to_le_bytes()); + out.extend_from_slice(data); + } + Ok(out) +} + +/// The OpenEXR RLE / ZIP predictor: bytes split into even and odd halves, then each byte replaced +/// by its difference from the previous one, plus 128. +fn predict(raw: &[u8]) -> Vec { + let half = raw.len().div_ceil(2); + let mut t = vec![0_u8; raw.len()]; + for (i, &b) in raw.iter().enumerate() { + t[if i % 2 == 0 { i / 2 } else { half + i / 2 }] = b; + } + let mut p = t.first().copied().unwrap_or(0); + for v in t.iter_mut().skip(1) { + let d = v.wrapping_sub(p).wrapping_add(128); + p = *v; + *v = d; + } + t +} + +/// OpenEXR run-length coding: a signed count byte, then either `count + 1` copies of one byte +/// (count ≥ 0, runs of 3 to 128) or `-count` literal bytes (1 to 127). +pub fn rle(src: &[u8]) -> Vec { + let mut out = Vec::with_capacity(src.len() + src.len() / 127 + 1); + let mut i = 0; + while i < src.len() { + let b = src[i]; + let run = src[i..].iter().take(128).take_while(|&&x| x == b).count(); + if run >= 3 { + out.extend_from_slice(&[(run - 1) as u8, b]); + i += run; + continue; + } + // literals up to the next run of three (or 127 bytes) + let s = i; + while i < src.len() && i - s < 127 { + if src.get(i..i + 3).is_some_and(|t| t[0] == t[1] && t[1] == t[2]) { + break; + } + i += 1; + } + out.push(((i - s) as u8).wrapping_neg()); + out.extend_from_slice(&src[s..i]); + } + out +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn writes_all_scanline_compressions() { + let linear = std::array::from_fn(|i| i as f32 / 255.0); + for c in [Compression::None, Compression::Rle, Compression::Zips, Compression::Zip] { + let bytes = write_rgba8(&[128; 16 * 16 * 4], 16, 16, true, c, &linear).unwrap(); + assert_eq!(&bytes[..4], &[0x76, 0x2f, 0x31, 1]); + assert!(bytes.len() > 100); + } + assert_eq!(write_rgba8(&[], 1, 1, false, Compression::None, &linear), Err(Error::FrameSize)); + } +} From ee44af6a45c2d12c4e63058db08a9f417002636d Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:14:00 +0000 Subject: [PATCH 090/349] Share first-directory TIFF inspection --- crates/image-codecs/src/lib.rs | 1 + crates/image-codecs/src/tiff_probe.rs | 68 +++++++++++++++++++++++++++ 2 files changed, 69 insertions(+) create mode 100644 crates/image-codecs/src/tiff_probe.rs diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index 6516b9ff2..b94eb6606 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -30,6 +30,7 @@ mod options; pub mod orientation; pub mod resolution; pub mod source_settings; +pub mod tiff_probe; pub mod web; pub use crate::allocation::probe_allocation_size; pub use crate::cicp::Cicp; diff --git a/crates/image-codecs/src/tiff_probe.rs b/crates/image-codecs/src/tiff_probe.rs new file mode 100644 index 000000000..1a542e412 --- /dev/null +++ b/crates/image-codecs/src/tiff_probe.rs @@ -0,0 +1,68 @@ +//! First-directory TIFF inspection without decoding pixels. + +/// A header inspection failure, distinguishing caller limits from unsupported decoder layouts. +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// Dimensions exceed the caller's pixel limit. + #[error("TIFF dimensions {width}x{height} exceed the pixel limit")] + TooLarge { + /// Stored width. + width: u32, + /// Stored height. + height: u32, + }, + /// The shared TIFF decoder does not support this layout. + #[error("unsupported TIFF: {0}")] + Unsupported(&'static str), + /// The file's header, directory or image-data bounds are malformed. + #[error("malformed TIFF: {0}")] + Malformed(String), +} + +/// Stored dimensions and orientation of the first directory, after checking the layouts and +/// image-data bounds required by the TIFF decoder. Compressed strips are not decompressed. +pub fn header(bytes: &[u8], max_pixels: u64) -> Result<(u32, u32, u16), Error> { + let (tiff, complete) = craft_tiff::Tiff::parse_with_status(bytes, &Default::default()).map_err(|e| Error::Malformed(e.to_string()))?; + if !complete { + return Err(Error::Malformed("truncated TIFF".into())); + } + let ifd = tiff.ifds.first().ok_or_else(|| Error::Malformed("no IFD".into()))?; + let info = ifd.image().map_err(|e| Error::Malformed(e.to_string()))?; + if info.width == 0 || info.height == 0 { + return Err(Error::Malformed("zero dimension".into())); + } + if u64::from(info.width) * u64::from(info.height) > max_pixels { + return Err(Error::TooLarge { width: info.width, height: info.height }); + } + let bits = info.bits_per_sample.first().copied().unwrap_or(1); + if bits < 8 && info.planar == 2 && info.samples_per_pixel > 1 { + return Err(Error::Unsupported("planar TIFF with samples narrower than a byte")); + } + if !(matches!(info.photometric, 0 | 1 | 2 | 3 | 5) || info.photometric == 6 && info.compression == 7) { + return Err(Error::Unsupported("colour type")); + } + if !matches!(info.compression, 1 | 4 | 5 | 7 | 8 | 32773 | 32946) { + return Err(Error::Unsupported("compression method")); + } + let len = bytes.len() as u64; + if info.offsets.is_empty() + || info.offsets.iter().zip(&info.byte_counts).any(|(&o, &c)| c > 0 && (o >= len || (info.compression == 1 && o.saturating_add(c) > len))) + { + return Err(Error::Malformed("truncated: image data past the end of the file".into())); + } + let orientation = ifd.u16(craft_tiff::tags::ORIENTATION).filter(|o| (1..=8).contains(o)).unwrap_or(1); + Ok((info.width, info.height, orientation)) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn reads_first_directory_and_enforces_limits_and_bounds() { + let image = crate::Image::from_u8(2, 3, crate::ChannelLayout::Rgb, vec![42; 18]).unwrap(); + let bytes = crate::encode(&image, crate::Format::Tiff, &crate::EncodeOptions::default()).unwrap(); + assert_eq!(header(&bytes, 6).unwrap(), (2, 3, 1)); + assert!(matches!(header(&bytes, 5), Err(Error::TooLarge { width: 2, height: 3 }))); + assert!(header(&bytes[..8], 6).is_err()); + } +} From 939146a5b159a268ee5fc67e26b3dc915b4d4094 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:14:11 +0000 Subject: [PATCH 091/349] tga dpx: share uncompressed RGBA8 export --- crates/dpx/src/lib.rs | 3 + crates/dpx/src/rgba8_dpx10.rs | 105 ++++++++++++++++++++++++++++++++++ crates/tga/src/lib.rs | 3 + crates/tga/src/rgba8_raw.rs | 60 +++++++++++++++++++ 4 files changed, 171 insertions(+) create mode 100644 crates/dpx/src/rgba8_dpx10.rs create mode 100644 crates/tga/src/rgba8_raw.rs diff --git a/crates/dpx/src/lib.rs b/crates/dpx/src/lib.rs index a762566f8..26d9e8656 100644 --- a/crates/dpx/src/lib.rs +++ b/crates/dpx/src/lib.rs @@ -34,6 +34,9 @@ //! Input is treated as hostile: every header read is bounds-checked, the picture size is capped //! by [`Limits`] and the image data must be present in full before anything is allocated. +/// RGBA8-to-10-bit DPX encoding. +pub mod rgba8_dpx10; + #[cfg(test)] mod tests; diff --git a/crates/dpx/src/rgba8_dpx10.rs b/crates/dpx/src/rgba8_dpx10.rs new file mode 100644 index 000000000..6ec5e23b4 --- /dev/null +++ b/crates/dpx/src/rgba8_dpx10.rs @@ -0,0 +1,105 @@ +//! Uncompressed RGB(A) output from top-down RGBA8 pixels. +/// Why the supplied frame cannot be encoded. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Rgba8EncodeError { + /// Empty, overflowing, or mismatched dimensions. + FrameSize, + /// A dimension cannot fit the output format. + TooLarge, +} +fn checked_len(rgba: &[u8], w: u32, h: u32) -> std::result::Result { + let n = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(4)).ok_or(Rgba8EncodeError::FrameSize)?; + if w == 0 || h == 0 || rgba.len() != n { + return Err(Rgba8EncodeError::FrameSize); + } + Ok(n) +} +/// Header size of the DPX files we write (file + image + orientation + film + TV headers). +const DPX_HEADER: usize = 2048; + +/// A DPX file: 10-bit RGB (8-bit values widened by bit replication, so 0 → 0 and 255 → 1023). +pub fn encode_rgba8_dpx10(rgba: &[u8], w: u32, h: u32, creator: &str) -> std::result::Result, Rgba8EncodeError> { + let n = checked_len(rgba, w, h)?; + // one 32-bit word per pixel; `n` is already `w * h * 4` + let size = n.checked_add(DPX_HEADER).ok_or_else(|| Rgba8EncodeError::FrameSize)?; + let file_size = u32::try_from(size).map_err(|_| Rgba8EncodeError::TooLarge)?; + // SMPTE ST 268: undefined numeric fields are all ones, undefined text fields are NUL + let mut hd = vec![0xFF_u8; DPX_HEADER]; + for (a, b) in [ + (36, 660), // file name, creation time, creator, project, copyright + (664, 768), // reserved + (1356, 1408), // reserved + (1432, 1620), // source file name, time, input device, serial number + (1644, 1664), // reserved + (1664, 1712), // film manufacturer, type, offset, prefix, count, format + (1732, 1920), // frame id, slate, reserved + (1972, 2048), // reserved + ] { + hd[a..b].fill(0); + } + for e in 0..8 { + let d = 780 + e * 72 + 40; + hd[d..d + 32].fill(0); // element descriptions + } + let put32 = |hd: &mut Vec, at: usize, v: u32| hd[at..at + 4].copy_from_slice(&v.to_be_bytes()); + let put16 = |hd: &mut Vec, at: usize, v: u16| hd[at..at + 2].copy_from_slice(&v.to_be_bytes()); + // file information header + hd[0..4].copy_from_slice(b"SDPX"); + put32(&mut hd, 4, DPX_HEADER as u32); // offset to the image data + hd[8..16].copy_from_slice(b"V2.0\0\0\0\0"); + put32(&mut hd, 16, file_size); + put32(&mut hd, 20, 1); // ditto key: new frame + put32(&mut hd, 24, 1664); // generic header length + put32(&mut hd, 28, 384); // industry header length + put32(&mut hd, 32, 0); // user data length + let creator = creator.as_bytes(); + let n = creator.len().min(100); + hd[160..160 + n].copy_from_slice(&creator[..n]); + // image information header + put16(&mut hd, 768, 0); // orientation: left to right, top to bottom + put16(&mut hd, 770, 1); // one image element + put32(&mut hd, 772, w); + put32(&mut hd, 776, h); + let el = 780; + put32(&mut hd, el, 0); // unsigned + put32(&mut hd, el + 4, 0); // reference low data code + put32(&mut hd, el + 12, 1023); // reference high data code + hd[el + 20] = 50; // descriptor: RGB + hd[el + 21] = 6; // transfer: ITU-R BT.709 + hd[el + 22] = 6; // colorimetric: ITU-R BT.709 + hd[el + 23] = 10; // bit depth + put16(&mut hd, el + 24, 1); // packing: filled to 32-bit words, method A + put16(&mut hd, el + 26, 0); // no encoding (uncompressed) + put32(&mut hd, el + 28, DPX_HEADER as u32); // offset to the element's data + put32(&mut hd, el + 32, 0); // end-of-line padding + put32(&mut hd, el + 36, 0); // end-of-image padding + // image orientation header: no offset, square pixels + put32(&mut hd, 1408, 0); + put32(&mut hd, 1412, 0); + put32(&mut hd, 1424, w); + put32(&mut hd, 1428, h); + put32(&mut hd, 1628, 1); + put32(&mut hd, 1632, 1); + // television header: progressive + hd[1928] = 0; + let mut out = Vec::with_capacity(size); + out.extend_from_slice(&hd); + let ten = |v: u8| (u32::from(v) << 2) | (u32::from(v) >> 6); + for &[r, g, b, _] in rgba.as_chunks::<4>().0 { + out.extend_from_slice(&((ten(r) << 22) | (ten(g) << 12) | (ten(b) << 2)).to_be_bytes()); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn packed_rgb_and_creator() { + let bytes = encode_rgba8_dpx10(&[255, 0, 128, 255], 1, 1, "FilmCraft").unwrap(); + assert_eq!(&bytes[..4], b"SDPX"); + assert_eq!(&bytes[160..169], b"FilmCraft"); + assert_eq!(&bytes[2048..], &((1023u32 << 22) | (514u32 << 2)).to_be_bytes()); + assert_eq!(encode_rgba8_dpx10(&[], 0, 1, ""), Err(Rgba8EncodeError::FrameSize)); + } +} diff --git a/crates/tga/src/lib.rs b/crates/tga/src/lib.rs index ac9d21497..3a92052ff 100644 --- a/crates/tga/src/lib.rs +++ b/crates/tga/src/lib.rs @@ -18,6 +18,9 @@ //! Input is treated as hostile: the picture size is capped by [`Limits`], and a run-length file //! must be long enough to hold the pixels its header declares before anything is allocated. +/// Uncompressed RGBA8-to-Targa encoding. +pub mod rgba8_raw; + #[cfg(test)] mod tests; diff --git a/crates/tga/src/rgba8_raw.rs b/crates/tga/src/rgba8_raw.rs new file mode 100644 index 000000000..acec4b9bc --- /dev/null +++ b/crates/tga/src/rgba8_raw.rs @@ -0,0 +1,60 @@ +//! Uncompressed RGB(A) output from top-down RGBA8 pixels. +/// Why the supplied frame cannot be encoded. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Rgba8EncodeError { + /// Empty, overflowing, or mismatched dimensions. + FrameSize, + /// A dimension cannot fit the 16-bit Targa header. + Dimensions, +} +fn checked_len(rgba: &[u8], w: u32, h: u32) -> std::result::Result { + let n = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(4)).ok_or(Rgba8EncodeError::FrameSize)?; + if w == 0 || h == 0 || rgba.len() != n { + return Err(Rgba8EncodeError::FrameSize); + } + Ok(n) +} +/// An uncompressed Targa file: 24-bit BGR, or 32-bit BGRA with `alpha` (straight alpha, as the +/// frame carries it). +pub fn encode_rgba8_raw(rgba: &[u8], w: u32, h: u32, alpha: bool) -> std::result::Result, Rgba8EncodeError> { + checked_len(rgba, w, h)?; + let (tw, th) = match (u16::try_from(w), u16::try_from(h)) { + (Ok(tw), Ok(th)) => (tw, th), + _ => return Err(Rgba8EncodeError::Dimensions), + }; + let bpp: usize = if alpha { 4 } else { 3 }; + let row = w as usize * 4; + let mut out = Vec::with_capacity(18 + w as usize * h as usize * bpp + 26); + out.extend_from_slice(&[0, 0, 2]); // no ID, no colour map, uncompressed true-colour + out.extend_from_slice(&[0; 5]); // colour map specification (unused) + out.extend_from_slice(&[0, 0, 0, 0]); // x / y origin + out.extend_from_slice(&tw.to_le_bytes()); + out.extend_from_slice(&th.to_le_bytes()); + out.push(if alpha { 32 } else { 24 }); + out.push(if alpha { 8 } else { 0 }); // attribute bits; bottom-left origin + // bottom-left origin: the last frame row comes first + for line in rgba.chunks_exact(row).rev() { + for &[r, g, b, a] in line.as_chunks::<4>().0 { + out.extend_from_slice(&[b, g, r]); + if alpha { + out.push(a); + } + } + } + // TGA 2.0 footer without extension or developer areas + out.extend_from_slice(&[0; 8]); + out.extend_from_slice(b"TRUEVISION-XFILE.\0"); + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + #[test] + fn raw_round_trip() { + let bytes = encode_rgba8_raw(&[1, 2, 3, 4], 1, 1, true).unwrap(); + assert_eq!(&bytes[18..22], &[3, 2, 1, 4]); + assert_eq!(&bytes[bytes.len() - 18..], b"TRUEVISION-XFILE.\0"); + assert_eq!(encode_rgba8_raw(&[], 0, 1, false), Err(Rgba8EncodeError::FrameSize)); + } +} From 553c86719ce9d57f01bcfb6442ac68ac58cd65de Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:14:57 +0000 Subject: [PATCH 092/349] Share catalog face metrics and glyph outlines --- Cargo.lock | 1 + crates/font-catalog/Cargo.toml | 1 + crates/font-catalog/src/lib.rs | 2 + crates/font-catalog/src/outline.rs | 133 +++++++++++++++++++++++++++++ 4 files changed, 137 insertions(+) create mode 100644 crates/font-catalog/src/outline.rs diff --git a/Cargo.lock b/Cargo.lock index 9fb46057c..9424cf3fe 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1761,6 +1761,7 @@ name = "craft-font-catalog" version = "0.1.0" dependencies = [ "fontique", + "kurbo 0.13.1", "skrifa 0.47.0", "thiserror 2.0.21", "windows-registry", diff --git a/crates/font-catalog/Cargo.toml b/crates/font-catalog/Cargo.toml index a95e1c28f..1f0830a63 100644 --- a/crates/font-catalog/Cargo.toml +++ b/crates/font-catalog/Cargo.toml @@ -15,6 +15,7 @@ default = ["system"] system = ["dep:fontique"] [dependencies] +kurbo = { workspace = true } skrifa = { version = "0.47", default-features = false, features = ["std"] } thiserror = { workspace = true } diff --git a/crates/font-catalog/src/lib.rs b/crates/font-catalog/src/lib.rs index c787d3ece..7da4ca310 100644 --- a/crates/font-catalog/src/lib.rs +++ b/crates/font-catalog/src/lib.rs @@ -23,6 +23,7 @@ mod catalog; mod env; mod fontconfig; +mod outline; mod registry; mod scan; mod suitcase; @@ -31,6 +32,7 @@ pub mod system; pub use catalog::{Catalog, FontData, FontFileError, Limits, Lister, LoadedFace, Match, Watch}; pub use env::{FontEnv, Os, font_dirs, font_store_dir, office_font_dirs}; pub use fontconfig::fontconfig_dirs; +pub use outline::{FontOutline, OutlineError}; pub use scan::{FaceInfo, LocalizedName, Source, is_font_file, style_italic, style_weight, style_width}; #[cfg(test)] diff --git a/crates/font-catalog/src/outline.rs b/crates/font-catalog/src/outline.rs new file mode 100644 index 000000000..cd27e0c53 --- /dev/null +++ b/crates/font-catalog/src/outline.rs @@ -0,0 +1,133 @@ +//! Unhinted glyph outlines and metrics for catalog faces. + +use kurbo::BezPath; +use skrifa::instance::{Location, Size}; +use skrifa::outline::{DrawSettings, OutlinePen}; +use skrifa::{FontRef, GlyphId, MetadataProvider, Tag}; + +use crate::{FontData, LoadedFace}; + +/// A parsed face and its variation location. Coordinates use font design units, with y up. +/// The bytes can come from a catalog or any other source, including a collection face. +pub struct FontOutline<'a> { + font: FontRef<'a>, + location: Location, +} + +/// Why a font or glyph outline could not be read. +#[derive(Debug, thiserror::Error)] +pub enum OutlineError { + /// The face index or font data is invalid. + #[error("invalid font face")] + InvalidFace, + /// The glyph has no outline in this face. + #[error("glyph has no outline")] + MissingGlyph, + /// The glyph's outline is malformed. + #[error("cannot draw glyph outline: {0}")] + Draw(#[from] skrifa::outline::DrawError), +} + +impl<'a> FontOutline<'a> { + /// Parse the given face and select axis values in user units. Unknown axes are ignored and + /// values are clamped to their axis ranges by the font parser. + pub fn new(data: &'a FontData, variations: &[([u8; 4], f32)]) -> Result { + Self::from_bytes(&data.bytes, data.index, variations) + } + + /// Parse borrowed bytes and a collection face index without copying the font. + pub fn from_bytes(bytes: &'a [u8], index: u32, variations: &[([u8; 4], f32)]) -> Result { + let font = FontRef::from_index(bytes, index).map_err(|_| OutlineError::InvalidFace)?; + let location = font.axes().location(variations.iter().map(|(tag, value)| (Tag::new(tag), *value))); + Ok(Self { font, location }) + } + + /// Parse a catalog face, retaining the axis settings of a named instance. + pub fn from_loaded(face: &'a LoadedFace) -> Result { + Self::new(&face.data, &face.info.variations) + } + + /// Font-wide metrics in unscaled design units at this variation location. + pub fn metrics(&self) -> skrifa::metrics::Metrics { + self.font.metrics(Size::unscaled(), &self.location) + } + + /// Resolve a Unicode scalar to a glyph identifier. + pub fn glyph_for(&self, character: char) -> Option { + self.font.charmap().map(character).map(|id| id.to_u32()) + } + + /// Draw a glyph in design units. Empty glyphs such as spaces can produce an empty path. + pub fn outline(&self, glyph: u32) -> Result { + let outline = self.font.outline_glyphs().get(GlyphId::new(glyph)).ok_or(OutlineError::MissingGlyph)?; + let mut pen = PathPen(BezPath::new()); + outline.draw(DrawSettings::unhinted(Size::unscaled(), &self.location), &mut pen)?; + Ok(pen.0) + } +} + +struct PathPen(BezPath); +impl OutlinePen for PathPen { + fn move_to(&mut self, x: f32, y: f32) { + self.0.move_to((f64::from(x), f64::from(y))); + } + fn line_to(&mut self, x: f32, y: f32) { + self.0.line_to((f64::from(x), f64::from(y))); + } + fn quad_to(&mut self, x1: f32, y1: f32, x: f32, y: f32) { + self.0.quad_to((f64::from(x1), f64::from(y1)), (f64::from(x), f64::from(y))); + } + fn curve_to(&mut self, x1: f32, y1: f32, x2: f32, y2: f32, x: f32, y: f32) { + self.0.curve_to((f64::from(x1), f64::from(y1)), (f64::from(x2), f64::from(y2)), (f64::from(x), f64::from(y))); + } + fn close(&mut self) { + self.0.close_path(); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use kurbo::PathEl; + use std::sync::Arc; + + #[test] + fn rejects_invalid_face_and_collection_index() { + let data = FontData { bytes: Arc::from(&b"not a font"[..]), index: 0 }; + assert!(matches!(FontOutline::new(&data, &[]), Err(OutlineError::InvalidFace))); + } + + #[test] + fn pen_preserves_geometry_and_upward_y() { + let mut pen = PathPen(BezPath::new()); + pen.move_to(1.0, 2.0); + pen.line_to(3.0, 4.0); + pen.quad_to(5.0, 6.0, 7.0, 8.0); + pen.curve_to(9.0, 10.0, 11.0, 12.0, 13.0, 14.0); + pen.close(); + assert_eq!( + pen.0.elements(), + &[ + PathEl::MoveTo((1.0, 2.0).into()), + PathEl::LineTo((3.0, 4.0).into()), + PathEl::QuadTo((5.0, 6.0).into(), (7.0, 8.0).into()), + PathEl::CurveTo((9.0, 10.0).into(), (11.0, 12.0).into(), (13.0, 14.0).into()), + PathEl::ClosePath, + ] + ); + } + + #[test] + fn reads_craft_font_when_available() { + let Ok(dir) = std::env::var("CRAFT_FONTS_DIR") else { return }; + let bytes = std::fs::read(std::path::Path::new(&dir).join("fonts/noto-sans-hebrew/NotoSansHebrew-Regular.ttf")).unwrap(); + let data = FontData { bytes: bytes.into(), index: 0 }; + let face = FontOutline::new(&data, &[]).unwrap(); + assert!(face.metrics().units_per_em > 0); + let glyph = face.glyph_for('×�').unwrap(); + assert!(!face.outline(glyph).unwrap().elements().is_empty()); + assert!(matches!(face.outline(u32::MAX), Err(OutlineError::MissingGlyph))); + let invalid_index = FontData { bytes: data.bytes.clone(), index: u32::MAX }; + assert!(matches!(FontOutline::new(&invalid_index, &[]), Err(OutlineError::InvalidFace))); + } +} From fb6cb780061c6744ed6886e7dd1a80ccf449e655 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:15:21 +0000 Subject: [PATCH 093/349] Depend on shared TIFF directory parser --- Cargo.lock | 1 + crates/image-codecs/Cargo.toml | 1 + 2 files changed, 2 insertions(+) diff --git a/Cargo.lock b/Cargo.lock index 9fb46057c..23cdde361 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1927,6 +1927,7 @@ dependencies = [ "craft-heif", "craft-jpeg", "craft-metadata", + "craft-tiff", "craft-video", "crc32fast", "exr", diff --git a/crates/image-codecs/Cargo.toml b/crates/image-codecs/Cargo.toml index df71d9860..f697610a6 100644 --- a/crates/image-codecs/Cargo.toml +++ b/crates/image-codecs/Cargo.toml @@ -32,6 +32,7 @@ zune-core = "0.5" jpeg-encoder = "0.6" craft-jpeg = { workspace = true } craft-metadata = { workspace = true } +craft-tiff = { workspace = true } zune-jpegxl = { version = "=0.5.2", default-features = false, features = ["std"] } craft-heif = { workspace = true, optional = true } ravif = { version = "0.13", default-features = false, optional = true } From b616d590e862d9a2c63d67aaadb59dcae2e6d054 Mon Sep 17 00:00:00 2001 From: Brandon Thomas Date: Sun, 15 Nov 2026 11:15:32 -0500 Subject: [PATCH 094/349] Port XML property-list reader from Craft Anything Source: storytold/craft-anything at 8f3b775157d331dd31cfa4da911e26d8856b8c77, crates/formats/src/plist.rs and bytes.rs. Preserve original contributor fixes for document boundaries, UTF-16, numeric references, quoted attributes and line endings. Co-authored-by: Afloat Co-authored-by: BFlat Co-authored-by: Rahul Co-authored-by: RRFZ <247457381+Plastic-time@users.noreply.github.com> Co-authored-by: NetterSilver <133535268+Silvertree2010@users.noreply.github.com> --- crates/plist/src/xml.rs | 432 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 432 insertions(+) create mode 100644 crates/plist/src/xml.rs diff --git a/crates/plist/src/xml.rs b/crates/plist/src/xml.rs new file mode 100644 index 000000000..7b41ecc91 --- /dev/null +++ b/crates/plist/src/xml.rs @@ -0,0 +1,432 @@ +//! XML property-list reader ported from Craft Anything at 8f3b7751. +use crate::{DateValue, FormatError, Value}; +const MAX_NODES: usize = 100_000; +const MAX_DEPTH: usize = 64; +fn decode_base64(text: &str, url_safe: bool) -> Option> { + let mut out = Vec::with_capacity(text.len() / 4 * 3); + let mut acc = 0u32; + let mut bits = 0u32; + let mut digits = 0usize; + let mut padding = 0usize; + for c in text.bytes() { + match c { + b' ' | b'\t' | b'\r' | b'\n' => continue, + b'=' => { + padding += 1; + if padding > 2 { + return None; + } + continue; + } + _ if padding != 0 => return None, + _ => {} + } + 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'+' => 62, + b'/' => 63, + b'-' if url_safe => 62, + b'_' if url_safe => 63, + _ => return None, + }; + acc = (acc << 6) | u32::from(value); + bits += 6; + digits += 1; + if bits >= 8 { + bits -= 8; + out.push((acc >> bits) as u8); + acc &= (1 << bits) - 1; + } + } + let remainder = digits % 4; + if remainder == 1 || (padding != 0 && !matches!((remainder, padding), (2, 2) | (3, 1))) { + return None; + } + Some(out) +} + +fn base64_decode(s: &str) -> Option> { decode_base64(s, false) } +#[derive(Debug, Clone, PartialEq)] +enum Tok { + Open(String), + Close(String), + Empty(String), + Text(String), +} + +fn decode_entities(s: &str) -> String { + if !s.contains('&') { + return s.to_string(); + } + let mut out = String::with_capacity(s.len()); + let mut rest = s; + while let Some(p) = rest.find('&') { + out.push_str(rest.get(..p).unwrap_or("")); + let after = rest.get(p..).unwrap_or(""); + let Some(end) = after.find(';').filter(|&e| e <= 12) else { + out.push('&'); + rest = after.get(1..).unwrap_or(""); + continue; + }; + let ent = after.get(1..end).unwrap_or(""); + let rep = match ent { + "lt" => Some('<'), + "gt" => Some('>'), + "amp" => Some('&'), + "quot" => Some('"'), + "apos" => Some('\''), + e if e.starts_with("#x") || e.starts_with("#X") => { + let d = e.get(2..).unwrap_or(""); + if d.bytes().all(|b| b.is_ascii_hexdigit()) { u32::from_str_radix(d, 16).ok().and_then(char::from_u32) } else { None } + } + e if e.starts_with('#') => { + let d = e.get(1..).unwrap_or(""); + if d.bytes().all(|b| b.is_ascii_digit()) { d.parse::().ok().and_then(char::from_u32) } else { None } + } + _ => None, + }; + match rep { + Some(c) => { + out.push(c); + rest = after.get(end + 1..).unwrap_or(""); + } + None => { + out.push('&'); + rest = after.get(1..).unwrap_or(""); + } + } + } + out.push_str(rest); + out +} + +/// Skip a declaration without interpreting or fetching any entity. A DOCTYPE's +/// internal subset can itself contain declarations, quoted delimiters, comments and PIs. +fn after_declaration(mut rest: &str) -> Result<&str, FormatError> { + let mut quote = None; + let mut brackets = 0usize; + while let Some(ch) = rest.chars().next() { + if quote.is_none() { + if let Some(comment) = rest.strip_prefix("").ok_or_else(|| FormatError::Truncated("comment in declaration".into()))?.1; + continue; + } + if let Some(pi) = rest.strip_prefix("").ok_or_else(|| FormatError::Truncated("processing instruction in declaration".into()))?.1; + continue; + } + } + rest = rest.get(ch.len_utf8()..).unwrap_or(""); + match (quote, ch) { + (Some(q), c) if q == c => quote = None, + (None, '\'' | '"') => quote = Some(ch), + (None, '[') => brackets += 1, + (None, ']') => brackets = brackets.saturating_sub(1), + (None, '>') if brackets == 0 => return Ok(rest), + _ => {} + } + } + Err(FormatError::Truncated("declaration".into())) +} + +fn tokenize(text: &str) -> Result, FormatError> { + let mut toks = Vec::new(); + let mut rest = text; + while !rest.is_empty() { + if toks.len() > MAX_NODES { + return Err(FormatError::TooLarge("too many XML tokens".into())); + } + match rest.find('<') { + None => { + if !rest.is_empty() { + toks.push(Tok::Text(decode_entities(rest))); + } + break; + } + Some(p) => { + let t = rest.get(..p).unwrap_or(""); + if !t.is_empty() { + toks.push(Tok::Text(decode_entities(t))); + } + rest = rest.get(p..).unwrap_or(""); + } + } + if let Some(r) = rest.strip_prefix("").ok_or_else(|| FormatError::Truncated("comment".into()))?; + rest = r.get(e + 3..).unwrap_or(""); + continue; + } + if let Some(r) = rest.strip_prefix("").ok_or_else(|| FormatError::Truncated("CDATA".into()))?; + toks.push(Tok::Text(r.get(..e).unwrap_or("").to_string())); + rest = r.get(e + 3..).unwrap_or(""); + continue; + } + if let Some(r) = rest.strip_prefix("").ok_or_else(|| FormatError::Truncated("processing instruction".into()))?; + rest = r.get(end + 2..).unwrap_or(""); + continue; + } + if let Some(declaration) = rest.strip_prefix(" { + quote = None; + false + } + (None, '\'' | '"') => { + quote = Some(ch); + false + } + (None, '>') => true, + _ => false, + }) + .ok_or_else(|| FormatError::Truncated("tag".into()))?; + let inner = rest.get(1..e).unwrap_or("").trim(); + rest = rest.get(e + 1..).unwrap_or(""); + if let Some(name) = inner.strip_prefix('/') { + toks.push(Tok::Close(name.trim().to_string())); + } else if let Some(body) = inner.strip_suffix('/') { + toks.push(Tok::Empty(body.split_whitespace().next().unwrap_or("").to_string())); + } else { + toks.push(Tok::Open(inner.split_whitespace().next().unwrap_or("").to_string())); + } + } + Ok(toks) +} + +struct Xml { + toks: Vec, + pos: usize, + nodes: usize, +} + +impl Xml { + fn next(&mut self) -> Option { + let t = self.toks.get(self.pos).cloned(); + self.pos += 1; + t + } + + fn peek(&self) -> Option<&Tok> { + self.toks.get(self.pos) + } + + /// Text up to the closing tag `name`. + fn text_until(&mut self, name: &str) -> Result { + let mut s = String::new(); + loop { + match self.next() { + Some(Tok::Text(t)) => s.push_str(&t), + Some(Tok::Close(n)) if n == name => return Ok(s), + Some(other) => return Err(FormatError::Malformed(format!("unexpected {other:?} inside <{name}>"))), + None => return Err(FormatError::Truncated(format!("<{name}> is not closed"))), + } + } + } + + fn skip_space(&mut self) { + while matches!(self.peek(), Some(Tok::Text(t)) if t.bytes().all(|b| matches!(b, b' ' | b'\t' | b'\r' | b'\n'))) { + self.pos += 1; + } + } + + fn value(&mut self, depth: usize) -> Result { + self.nodes += 1; + if depth > MAX_DEPTH || self.nodes > MAX_NODES { + return Err(FormatError::TooLarge("plist nesting or size limit".into())); + } + self.skip_space(); + match self.next() { + Some(Tok::Empty(n)) => Ok(match n.as_str() { + "true" => Value::Bool(true), + "false" => Value::Bool(false), + "dict" => Value::Dict(Vec::new()), + "array" => Value::Array(Vec::new()), + "string" => Value::String(String::new()), + "data" => Value::Data(Vec::new()), + other => return Err(FormatError::Malformed(format!("unexpected <{other}/>"))), + }), + Some(Tok::Open(n)) => match n.as_str() { + "string" => Ok(Value::String(self.text_until("string")?)), + "integer" => { + let t = self.text_until("integer")?; + let t = t.trim(); + let v = if let Some(h) = t.strip_prefix("0x").or_else(|| t.strip_prefix("0X")) { + i128::from_str_radix(h, 16).ok() + } else { + t.parse::().ok() + }; + v.map(Value::Integer).ok_or_else(|| FormatError::Malformed(format!("bad integer {t:?}"))) + } + "real" => { + let t = self.text_until("real")?; + t.trim().parse::().map(Value::Real).map_err(|_| FormatError::Malformed(format!("bad real {t:?}"))) + } + "date" => Ok(Value::Date(DateValue::Text(self.text_until("date")?.trim().to_string()))), + "data" => { + let t = self.text_until("data")?; + base64_decode(&t).map(Value::Data).ok_or_else(|| FormatError::Malformed("bad base64 in ".into())) + } + "true" | "false" => { + if !self.text_until(&n)?.is_empty() { + return Err(FormatError::Malformed(format!("<{n}> must be empty"))); + } + Ok(Value::Bool(n == "true")) + } + "array" => { + let mut out = Vec::new(); + loop { + self.skip_space(); + if matches!(self.peek(), Some(Tok::Close(c)) if c == "array") { + self.pos += 1; + return Ok(Value::Array(out)); + } + if self.peek().is_none() { + return Err(FormatError::Truncated(" is not closed".into())); + } + out.push(self.value(depth + 1)?); + } + } + "dict" => { + let mut out = Vec::new(); + loop { + self.skip_space(); + match self.next() { + Some(Tok::Close(c)) if c == "dict" => return Ok(Value::Dict(out)), + Some(Tok::Open(k)) if k == "key" => { + let key = self.text_until("key")?; + let v = self.value(depth + 1)?; + out.push((key, v)); + } + Some(Tok::Empty(k)) if k == "key" => { + let v = self.value(depth + 1)?; + out.push((String::new(), v)); + } + Some(other) => return Err(FormatError::Malformed(format!("expected in , found {other:?}"))), + None => return Err(FormatError::Truncated(" is not closed".into())), + } + } + } + other => Err(FormatError::Malformed(format!("unknown plist element <{other}>"))), + }, + Some(other) => Err(FormatError::Malformed(format!("expected a value, found {other:?}"))), + None => Err(FormatError::Truncated("expected a value".into())), + } + } +} + +/// Decode a UTF-16 XML property list after its byte-order mark into UTF-8 text. +/// Surrogate pairs join normally; a lone surrogate fails as malformed rather +/// than turning into replacement characters that tokenize into garbage element +/// names. +fn decode_utf16_xml(data: &[u8], big_endian: bool) -> Result { + if !data.len().is_multiple_of(2) { + return Err(FormatError::Truncated("UTF-16 code unit".into())); + } + let units: Vec = data.chunks_exact(2).map(|b| if big_endian { u16::from_be_bytes([b[0], b[1]]) } else { u16::from_le_bytes([b[0], b[1]]) }).collect(); + String::from_utf16(&units).map_err(|_| FormatError::Malformed("invalid UTF-16 in XML plist".into())) +} + +/// Parse an XML property list. +pub fn parse_xml(data: &[u8]) -> Result { + // Apple's Core Foundation reader accepts XML plists in UTF-16 as well as + // UTF-8: it recognises both byte-order marks. `from_utf8_lossy` turns a + // UTF-16 byte stream into NUL-separated text, so the encoding is settled + // here, before tokenizing. + let text = match data { + [0xFF, 0xFE, rest @ ..] => decode_utf16_xml(rest, false)?, + [0xFE, 0xFF, rest @ ..] => decode_utf16_xml(rest, true)?, + _ => std::str::from_utf8(data.strip_prefix(b"\xef\xbb\xbf").unwrap_or(data)) + .map_err(|_| FormatError::Malformed("invalid UTF-8 in XML plist".into()))? + .to_owned(), + }; + // XML normalizes literal line endings before parsing; character references such as + // must still decode to a carriage return afterwards. + let text = if text.contains('\r') { text.replace("\r\n", "\n").replace('\r', "\n") } else { text }; + let toks = tokenize(&text)?; + let mut x = Xml { toks, pos: 0, nodes: 0 }; + x.skip_space(); + let wrapped = matches!(x.peek(), Some(Tok::Open(n)) if n == "plist"); + if wrapped { + x.pos += 1; + } + let value = x.value(0)?; + x.skip_space(); + if wrapped { + if !matches!(x.next(), Some(Tok::Close(n)) if n == "plist") { + return Err(FormatError::Malformed("expected after its value".into())); + } + x.skip_space(); + } + if x.peek().is_some() { + return Err(FormatError::Malformed("unexpected content after the plist value".into())); + } + Ok(value) +} + + +#[cfg(test)] +mod tests { +use super::*; + #[test] + fn xml_has_one_complete_root_with_only_markup_space_around_values() { + for invalid in [ + "", + "", + "", + "", + "junk", + "text", + "junk", + "xgarbage", + "no", + "yes", + "", + ] { + assert!(parse_xml(invalid.as_bytes()).is_err(), "{invalid}"); + } + let xml = b" ?>\n "; + assert_eq!(parse_xml(xml).unwrap().get("").and_then(Value::as_str), Some(" ")); + assert_eq!(parse_xml(b" ").unwrap(), Value::Bool(true)); + } + + #[test] + fn xml_rejects_partial_code_units_and_preserves_the_utf8_bom() { + assert_eq!(parse_xml(b"\xef\xbb\xbfok").unwrap().as_str(), Some("ok")); + assert!(parse_xml(b"\xff").is_err()); + for be in [false, true] { + let mut bytes = if be { vec![0xfe, 0xff] } else { vec![0xff, 0xfe] }; + for unit in "".encode_utf16() { + bytes.extend(if be { unit.to_be_bytes() } else { unit.to_le_bytes() }); + } + bytes.push(0); + assert!(parse_xml(&bytes).is_err()); + } + } + + #[test] + fn a_doctype_internal_subset_is_skipped_as_one_declaration() { + let doc = br#"y"> ?>]>ok"#; + assert_eq!(parse_xml(doc).unwrap().as_str(), Some("ok")); + assert!(parse_xml(b"").is_err()); + } + + #[test] + fn xml_char_refs_require_plain_digits() { + let text = |s: &str| { + let doc = format!("{s}"); + parse_xml(doc.as_bytes()).unwrap().as_str().map(str::to_string) + }; + assert_eq!(text("a&#+65;b&#x+41;").as_deref(), Some("a&#+65;b&#x+41;")); + assert_eq!(text("AA").as_deref(), Some("AA")); + assert_eq!(text("&#;&#x;").as_deref(), Some("&#;&#x;")); + } + +} From 4c4ad5d20f03b2d566bab89678712b6eb9231194 Mon Sep 17 00:00:00 2001 From: gmrmad1 Date: Sun, 15 Nov 2026 11:15:51 -0500 Subject: [PATCH 095/349] Reject nonfinite XML property-list reals Port storytold/craft-anything#1905 at d85e104f093a334961048881bf003351e1ac4992. Retain typed-value tests; app JSON projection remains outside this codec. --- crates/plist/src/xml.rs | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/crates/plist/src/xml.rs b/crates/plist/src/xml.rs index 7b41ecc91..54fd9f895 100644 --- a/crates/plist/src/xml.rs +++ b/crates/plist/src/xml.rs @@ -267,7 +267,7 @@ impl Xml { } "real" => { let t = self.text_until("real")?; - t.trim().parse::().map(Value::Real).map_err(|_| FormatError::Malformed(format!("bad real {t:?}"))) + t.trim().parse::().ok().filter(|v| v.is_finite()).map(Value::Real).ok_or_else(|| FormatError::Malformed(format!("bad real {t:?}"))) } "date" => Ok(Value::Date(DateValue::Text(self.text_until("date")?.trim().to_string()))), "data" => { @@ -429,4 +429,16 @@ use super::*; assert_eq!(text("&#;&#x;").as_deref(), Some("&#;&#x;")); } + #[test] + fn xml_real_must_be_finite() { + for bad in ["NaN", "1e999"] { + let doc = format!("k{bad}"); + assert!(parse_xml(doc.as_bytes()).is_err(), "{bad}"); + } + for (text, want) in [("1.5", 1.5), ("-2", -2.0), ("0", 0.0)] { + let doc = format!("k{text}"); + let v = parse_xml(doc.as_bytes()).unwrap_or_else(|e| panic!("{text} should parse: {e}")); + assert_eq!(v.get("k"), Some(&Value::Real(want)), "{text}"); + } + } } From c714810569eab85751713bea62c5833ae10af9b9 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:15:51 +0000 Subject: [PATCH 096/349] Test outlines at variable font weights --- crates/font-catalog/src/outline.rs | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/crates/font-catalog/src/outline.rs b/crates/font-catalog/src/outline.rs index cd27e0c53..1f550f983 100644 --- a/crates/font-catalog/src/outline.rs +++ b/crates/font-catalog/src/outline.rs @@ -130,4 +130,18 @@ mod tests { let invalid_index = FontData { bytes: data.bytes.clone(), index: u32::MAX }; assert!(matches!(FontOutline::new(&invalid_index, &[]), Err(OutlineError::InvalidFace))); } + + #[test] + fn variation_changes_glyph_geometry() { + let Ok(dir) = std::env::var("CRAFT_FONTS_DIR") else { return }; + let bytes = std::fs::read(std::path::Path::new(&dir).join("fonts/noto-sans-arabic/NotoSansArabic.ttf")).unwrap(); + let data = FontData { bytes: bytes.into(), index: 0 }; + let light = FontOutline::new(&data, &[(*b"wght", 100.0)]).unwrap(); + let bold = FontOutline::new(&data, &[(*b"wght", 900.0)]).unwrap(); + let glyph = light.glyph_for('ب').unwrap(); + let light_path = light.outline(glyph).unwrap(); + let bold_path = bold.outline(glyph).unwrap(); + assert!(!light_path.elements().is_empty()); + assert_ne!(light_path, bold_path); + } } From 9c3c82e1c63e53248f99531a71cb8401f5c76150 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:16:04 +0000 Subject: [PATCH 097/349] audio: fix PCM export module documentation --- crates/audio/src/pcm_export.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/audio/src/pcm_export.rs b/crates/audio/src/pcm_export.rs index c8456d785..14e45783b 100644 --- a/crates/audio/src/pcm_export.rs +++ b/crates/audio/src/pcm_export.rs @@ -2,8 +2,8 @@ //! 16, 24 or 32-bit integer or 32-bit float ([`SampleFormat`]), for streaming export. //! Float WAV is `WAVE_FORMAT_IEEE_FLOAT` with a `fact` chunk; float AIFF is AIFF-C (`fl32`). //! -//! The header is written first from the known length ([`header`]), then the samples in chunks -//! ([`encode`]) and the pad byte ([`pad`]), so an export streams to disk instead of building the +//! The header is written first from the known length (`header`), then the samples in chunks +//! (`encode`) and the pad byte (`pad`), so an export streams to disk instead of building the //! file in memory. /// PCM representation in an exported file. From ab37b756cc86dfc552eeb351b0b407e546ec4d9e Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:16:31 +0000 Subject: [PATCH 098/349] exr: fix compressor test helper lint --- crates/exr/src/zlib.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/exr/src/zlib.rs b/crates/exr/src/zlib.rs index 8959a7e89..a38bd0b46 100644 --- a/crates/exr/src/zlib.rs +++ b/crates/exr/src/zlib.rs @@ -501,9 +501,8 @@ mod tests { } let mut sorted: Vec = (0..lens.len()).filter(|&s| lens[s] > 0).collect(); sorted.sort_by_key(|&s| (lens[s], s)); - for len in 1..16 { + for &c in count.iter().skip(1) { code |= bit(pos)? as i32; - let c = count[len]; if code - c < first { return sorted.get((index + code - first) as usize).copied(); } From b2edb7ed80d8c8fac639050a3ea02f6e0ecaff30 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:16:31 +0000 Subject: [PATCH 099/349] exr: fix compressor test helper lint --- crates/exr/src/zlib.rs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/crates/exr/src/zlib.rs b/crates/exr/src/zlib.rs index 8959a7e89..a38bd0b46 100644 --- a/crates/exr/src/zlib.rs +++ b/crates/exr/src/zlib.rs @@ -501,9 +501,8 @@ mod tests { } let mut sorted: Vec = (0..lens.len()).filter(|&s| lens[s] > 0).collect(); sorted.sort_by_key(|&s| (lens[s], s)); - for len in 1..16 { + for &c in count.iter().skip(1) { code |= bit(pos)? as i32; - let c = count[len]; if code - c < first { return sorted.get((index + code - first) as usize).copied(); } From c339a9e4715bb0856603de7af897efcb43430f59 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:16:52 +0000 Subject: [PATCH 100/349] Share TIFF decode preflight fields --- crates/image-codecs/src/tiff_probe.rs | 36 +++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/crates/image-codecs/src/tiff_probe.rs b/crates/image-codecs/src/tiff_probe.rs index 1a542e412..05bd1e4db 100644 --- a/crates/image-codecs/src/tiff_probe.rs +++ b/crates/image-codecs/src/tiff_probe.rs @@ -19,6 +19,42 @@ pub enum Error { Malformed(String), } +/// First-directory values needed to preflight decoding. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct DecodeInfo { + /// Stored width. + pub width: u32, + /// Stored height. + pub height: u32, + /// First sample's bit depth, defaulting to eight. + pub bit_depth: u8, + /// Raw orientation tag, if present. + pub orientation: Option, +} + +/// Parse the first directory and enforce the pixel limit before decoding. +/// Unlike [`header`], this does not impose layout or strip checks ahead of the decoder. +pub fn decode_info(bytes: &[u8], max_pixels: u64) -> Result { + let (tiff, complete) = craft_tiff::Tiff::parse_with_status(bytes, &Default::default()).map_err(|e| Error::Malformed(e.to_string()))?; + if !complete { + return Err(Error::Malformed("truncated TIFF".into())); + } + let ifd = tiff.ifds.first().ok_or_else(|| Error::Malformed("no IFD".into()))?; + let info = ifd.image().map_err(|e| Error::Malformed(e.to_string()))?; + if info.width == 0 || info.height == 0 { + return Err(Error::Malformed("zero dimension".into())); + } + if u64::from(info.width) * u64::from(info.height) > max_pixels { + return Err(Error::TooLarge { width: info.width, height: info.height }); + } + Ok(DecodeInfo { + width: info.width, + height: info.height, + bit_depth: info.bits_per_sample.first().copied().unwrap_or(8) as u8, + orientation: ifd.u16(craft_tiff::tags::ORIENTATION), + }) +} + /// Stored dimensions and orientation of the first directory, after checking the layouts and /// image-data bounds required by the TIFF decoder. Compressed strips are not decompressed. pub fn header(bytes: &[u8], max_pixels: u64) -> Result<(u32, u32, u16), Error> { From b16c5908ae777f81fa33a9e9ad0e22b09b37a383 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:17:27 +0000 Subject: [PATCH 101/349] Cover TIFF decode preflight limits --- crates/image-codecs/src/tiff_probe.rs | 3 +++ 1 file changed, 3 insertions(+) diff --git a/crates/image-codecs/src/tiff_probe.rs b/crates/image-codecs/src/tiff_probe.rs index 05bd1e4db..6aaf5c21a 100644 --- a/crates/image-codecs/src/tiff_probe.rs +++ b/crates/image-codecs/src/tiff_probe.rs @@ -98,6 +98,9 @@ mod tests { let image = crate::Image::from_u8(2, 3, crate::ChannelLayout::Rgb, vec![42; 18]).unwrap(); let bytes = crate::encode(&image, crate::Format::Tiff, &crate::EncodeOptions::default()).unwrap(); assert_eq!(header(&bytes, 6).unwrap(), (2, 3, 1)); + let info = decode_info(&bytes, 6).unwrap(); + assert_eq!((info.width, info.height, info.bit_depth), (2, 3, 8)); + assert!(matches!(decode_info(&bytes, 5), Err(Error::TooLarge { width: 2, height: 3 }))); assert!(matches!(header(&bytes, 5), Err(Error::TooLarge { width: 2, height: 3 }))); assert!(header(&bytes[..8], 6).is_err()); } From ada2188786fd646443c4fb3326e68e52ce84c90d Mon Sep 17 00:00:00 2001 From: RRFZ <247457381+Plastic-time@users.noreply.github.com> Date: Sun, 15 Nov 2026 11:17:46 -0500 Subject: [PATCH 102/349] Preserve XML quoted-attribute and line-ending regression tests Imported from storytold/craft-anything #1738 and #1726 at 8f3b7751, adapted only to shared parse_xml entry point. --- crates/plist/tests/plist_line_endings.rs | 17 ++++++++++++++ crates/plist/tests/plist_quoted_attributes.rs | 22 +++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 crates/plist/tests/plist_line_endings.rs create mode 100644 crates/plist/tests/plist_quoted_attributes.rs diff --git a/crates/plist/tests/plist_line_endings.rs b/crates/plist/tests/plist_line_endings.rs new file mode 100644 index 000000000..3f8f82b50 --- /dev/null +++ b/crates/plist/tests/plist_line_endings.rs @@ -0,0 +1,17 @@ +use craft_plist::{self as plist, Value}; + +/// Literal line endings normalize before entities, including keys and CDATA. +#[test] +fn xml_line_endings_follow_xml_rules() { + let xml = "a\rba\r\nb\rc\nd e"; + for encoding in 0..3 { + let bytes = match encoding { + 1 => [vec![0xff, 0xfe], xml.encode_utf16().flat_map(u16::to_le_bytes).collect()].concat(), + 2 => [vec![0xfe, 0xff], xml.encode_utf16().flat_map(u16::to_be_bytes).collect()].concat(), + _ => xml.as_bytes().to_vec(), + }; + let value = plist::parse_xml(&bytes).unwrap(); + assert_eq!(value.get("a\nb").and_then(Value::as_str), Some("a\nb\nc\nd\ref\ng")); + } + assert!(plist::parse_xml(b"a\r\nb").is_err()); +} diff --git a/crates/plist/tests/plist_quoted_attributes.rs b/crates/plist/tests/plist_quoted_attributes.rs new file mode 100644 index 000000000..54cd042ef --- /dev/null +++ b/crates/plist/tests/plist_quoted_attributes.rs @@ -0,0 +1,22 @@ +use craft_plist::{self as plist, Value}; + +/// Quoted delimiters belong to attributes, including on empty elements. +#[test] +fn quoted_tag_delimiters_preserve_values() { + for quote in ['\'', '"'] { + let xml = format!( + "b{quote}>界{quote}>key/{quote}>valueempty/{quote}/>" + ); + let value = plist::parse_xml(xml.as_bytes()).unwrap(); + assert_eq!(value.get("key").and_then(Value::as_str), Some("value")); + assert_eq!(value.get("empty").and_then(Value::as_str), Some("")); + } +} + +/// A quote that never closes must not turn later markup into a value. +#[test] +fn unterminated_attribute_quotes_are_rejected() { + for xml in ["value", " 0, + b'G' => 1, + b'B' => 2, + 0 => break, + _ => continue, + }; + if depths[index] != 0 || pair[1] == 0 { + return 0; + } + depths[index] = pair[1]; + } + if depths[0] != 0 && depths.iter().all(|&depth| depth == depths[0]) { u32::from(depths[0]) } else { 0 } +} + fn picture_info(d: &Set) -> PictureInfo { let u = |t| d.u(t).unwrap_or(0) as u32; + let rgba = d.kind() == Some(st::RGBA_DESCRIPTOR); PictureInfo { stored_width: u(tag::STORED_WIDTH), stored_height: u(tag::STORED_HEIGHT), @@ -581,13 +605,13 @@ fn picture_info(d: &Set) -> PictureInfo { frame_layout: u(tag::FRAME_LAYOUT) as u8, field_dominance: u(tag::FIELD_DOMINANCE) as u8, aspect_ratio: d.rational(tag::ASPECT_RATIO).unwrap_or_default(), - component_depth: u(tag::COMPONENT_DEPTH), + component_depth: if rgba { d.get(tag::PIXEL_LAYOUT).map_or(0, rgba_component_depth) } else { u(tag::COMPONENT_DEPTH) }, horizontal_subsampling: u(tag::HORIZONTAL_SUBSAMPLING), vertical_subsampling: u(tag::VERTICAL_SUBSAMPLING), - black_ref_level: d.u(tag::BLACK_REF_LEVEL).map(|v| v as u32), - white_ref_level: d.u(tag::WHITE_REF_LEVEL).map(|v| v as u32), + black_ref_level: d.u(if rgba { tag::COMPONENT_MIN_REF } else { tag::BLACK_REF_LEVEL }).map(|v| v as u32), + white_ref_level: d.u(if rgba { tag::COMPONENT_MAX_REF } else { tag::WHITE_REF_LEVEL }).map(|v| v as u32), alpha_depth: u(tag::ALPHA_SAMPLE_DEPTH), - rgba: d.kind() == Some(st::RGBA_DESCRIPTOR), + rgba, picture_coding: d.ul(tag::PICTURE_ESSENCE_CODING), transfer_characteristic: d.ul(tag::TRANSFER_CHARACTERISTIC), coding_equations: d.ul(tag::CODING_EQUATIONS), @@ -1343,3 +1367,24 @@ mod fallback_tracks_tests { assert_eq!(tracks.len(), 1); } } + +#[cfg(test)] +mod rgba_layout_tests { + use super::rgba_component_depth; + + #[test] + fn only_complete_uniform_rgb_layouts_have_one_depth() { + let mut layout = [0; 16]; + layout[..8].copy_from_slice(&[b'B', 16, b'G', 16, b'R', 16, b'A', 8]); + assert_eq!(rgba_component_depth(&layout), 16); + assert_eq!(rgba_component_depth(&layout[..15]), 0); + layout[3] = 8; + assert_eq!(rgba_component_depth(&layout), 0); + layout[3] = 16; + layout[4] = b'G'; + assert_eq!(rgba_component_depth(&layout), 0); + layout[4] = 0; + assert_eq!(rgba_component_depth(&layout), 0); + assert_eq!(rgba_component_depth(&[0; 16]), 0); + } +} diff --git a/crates/media/src/mxf/meta.rs b/crates/media/src/mxf/meta.rs index d02afdd71..2b649d099 100644 --- a/crates/media/src/mxf/meta.rs +++ b/crates/media/src/mxf/meta.rs @@ -204,6 +204,8 @@ pub mod tag { pub const WHITE_REF_LEVEL: u16 = 0x3305; pub const ALPHA_SAMPLE_DEPTH: u16 = 0x3309; pub const PIXEL_LAYOUT: u16 = 0x3401; + pub const COMPONENT_MAX_REF: u16 = 0x3406; + pub const COMPONENT_MIN_REF: u16 = 0x3407; pub const AUDIO_SAMPLING_RATE: u16 = 0x3D03; pub const LOCKED: u16 = 0x3D02; pub const CHANNEL_COUNT: u16 = 0x3D07; diff --git a/crates/media/src/mxf/write/tests.rs b/crates/media/src/mxf/write/tests.rs index eac50a0e9..bc60423e9 100644 --- a/crates/media/src/mxf/write/tests.rs +++ b/crates/media/src/mxf/write/tests.rs @@ -434,6 +434,10 @@ fn cinemadng_op1a_reads_back() { assert_eq!(t.samples.len(), 6); let p = t.picture.as_ref().unwrap(); assert!(p.rgba, "RGBA picture essence descriptor (§7.2.2)"); + assert_eq!(p.component_depth, 16); + assert_eq!(p.black_ref_level, Some(0)); + assert_eq!(p.white_ref_level, Some(65_535)); + assert!(p.full_range()); assert_eq!((p.frame_width(), p.frame_height()), (64, 36)); assert!(p.picture_coding.is_none()); for i in 0..6 { From f78b0ac48439354229827c50c25a50fc19c71ea8 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:18:07 -0500 Subject: [PATCH 104/349] Expose bounded XML plist parsing and cap malformed entity scans --- ATTRIBUTION.md | 2 + crates/plist/Cargo.toml | 2 +- crates/plist/README.md | 12 +++++- crates/plist/src/lib.rs | 6 ++- crates/plist/src/xml.rs | 91 ++++++++++++++++++++++++++++++++++------- 5 files changed, 93 insertions(+), 20 deletions(-) diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index ef3b98f31..43d543062 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -100,3 +100,5 @@ and the exact transfer revision are recorded in each vendored crate's SOURCE.jso ## Binary Apple property lists `crates/plist` is extracted from `storytold/craft-anything` (`crates/formats/src/plist.rs` and checked byte reads), at source main `88d1d9cac852aec1c7fd97886db451e005e49d2a`. MIT OR Apache-2.0; source license texts are retained in the crate. Primary import Git authors preserve Brandon Thomas, BFlat, RRFZ and Afloat. Regression imports preserve BFlat. XML, JSON projection, calendar formatting and app policy were not imported into the public API. + +The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper are ported from Craft Anything `8f3b775157d331dd31cfa4da911e26d8856b8c77` (same MIT OR Apache-2.0 source licenses). Brandon Thomas is the primary import author; retained hardening credits include Afloat, BFlat, Rahul, RRFZ and NetterSilver. The finite-real fix preserves gmrmad1 as author from Craft Anything #1905 (`d85e104f`); quoted-attribute/line-ending regressions preserve RRFZ. Bounds/adaptation and bounded entity scanning are subsequent Dylan M. Taylor changes. App-specific JSON projections and keyed-archive interpretation remain outside this crate. diff --git a/crates/plist/Cargo.toml b/crates/plist/Cargo.toml index 7ae95aae0..7ffaf3480 100644 --- a/crates/plist/Cargo.toml +++ b/crates/plist/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "craft-plist" -description = "Bounded cross-platform binary Apple property-list reader" +description = "Bounded cross-platform binary and XML Apple property-list reader" version.workspace = true edition.workspace = true license.workspace = true diff --git a/crates/plist/README.md b/crates/plist/README.md index dc5c52007..5621ef96a 100644 --- a/crates/plist/README.md +++ b/crates/plist/README.md @@ -4,8 +4,16 @@ A cross-platform bounded binary (`bplist00`) reader, extracted from Craft Anythi `parse_binary_with_limits` accepts explicit input, object, expanded-node, nesting and decoded-byte limits. Recursion always has a hard ceiling of 256 even if a caller supplies a larger depth. Counts are checked before container reservation; allocations can return a resource error. Limits are per parse, not a promise of a precise process RSS cap. -This first PR contains reading only. XML parsing/writing and keyed-archive interpretation are not implemented. JSON projection, date formatting, OS file access and preference/locale selection are not part of this crate. Existing updater/Photo streaming `plist` users remain unchanged. +This crate contains reading only. Writing and keyed-archive interpretation are not implemented. JSON projection, date formatting, OS file access and preference/locale selection are not part of this crate. Existing updater/Photo streaming `plist` users remain unchanged. -Initial consumers: PhotoCraft's AppleLanguages binary-reader path; later Craft Anything binary parsing and LightCraft XML presets (after XML support/parity). Photo must retain its 4 MiB input policy and first-language selection. +Initial consumers: PhotoCraft's AppleLanguages binary-reader path; later Craft Anything binary parsing and LightCraft XML presets (after consumer parity). Photo must retain its 4 MiB input policy and first-language selection. Source: `storytold/craft-anything` at `88d1d9cac852aec1c7fd97886db451e005e49d2a`, `crates/formats/src/plist.rs` and checked byte reader. Source license files retained. Imported changes retain Brandon Thomas, BFlat, RRFZ and Afloat as primary Git authors; imported regression tests are BFlat's. No external specification implementation copied. + +## XML reader + +`parse_xml` and `parse_xml_with_limits` now read UTF-8 and BOM-tagged UTF-16 XML into the same `Value` tree. XML input/decoded-text size, tokens, values, nesting and cumulative key/leaf text are bounded. The independent token ceiling is eight times the smaller node/object allowance plus eight; unusually fragmented text can exhaust it before the value limit. This is not a precise RSS limit. The decoded-XML limit also includes markup; `` consumes its encoded text allowance, including whitespace. XML `max_objects` and `max_nodes` both cap values. + +The attributed Craft Anything reader includes its complete-document, declaration-skipping (no external entity fetching), quoted-tag and normalized-line-ending behavior. Nonfinite reals are refused using contributor PR #1905. Unknown or malformed character references retain legacy literal behavior; scanning is bounded before searching for a terminator. Base64 retains that reader's legacy optional-padding/ASCII-whitespace behavior, including unused trailing bits; it is not a signature/key-validation API. No writer, JSON projection, keyed-archive interpretation or app policy is added. + +XML source: Craft Anything `8f3b775157d331dd31cfa4da911e26d8856b8c77`, plus #1905 `d85e104f093a334961048881bf003351e1ac4992`. The import credits Brandon Thomas and the existing hardening contributors; #1905 is authored by gmrmad1 and the quoted-tag/line-ending tests by RRFZ. Consumer cutovers require their own policy/parity tests, especially LightCraft's preset mapping and Craft Anything's projections. diff --git a/crates/plist/src/lib.rs b/crates/plist/src/lib.rs index f3af79ddc..2547e73d8 100644 --- a/crates/plist/src/lib.rs +++ b/crates/plist/src/lib.rs @@ -1,10 +1,12 @@ -//! Bounded binary Apple property lists, independent of operating-system preferences. -//! XML and writing are intentionally not implemented in this first extraction. +//! Bounded binary and XML Apple property lists, independent of operating-system preferences. +//! Writing and application-specific projections remain with callers. //! File discovery, locale selection, bundle validation and application policy stay in callers. #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] mod binary; mod bytes; +mod xml; pub use binary::{DateValue, Value, first_string_in_array, parse_binary, parse_binary_with_limits}; +pub use xml::{parse_xml, parse_xml_with_limits}; /// Caller-selected resource limits. Zero values refuse the corresponding resource. #[derive(Clone, Copy, Debug)] diff --git a/crates/plist/src/xml.rs b/crates/plist/src/xml.rs index 54fd9f895..52f5c4586 100644 --- a/crates/plist/src/xml.rs +++ b/crates/plist/src/xml.rs @@ -1,7 +1,5 @@ //! XML property-list reader ported from Craft Anything at 8f3b7751. -use crate::{DateValue, FormatError, Value}; -const MAX_NODES: usize = 100_000; -const MAX_DEPTH: usize = 64; +use crate::{DateValue, FormatError, Limits, Value}; fn decode_base64(text: &str, url_safe: bool) -> Option> { let mut out = Vec::with_capacity(text.len() / 4 * 3); let mut acc = 0u32; @@ -47,7 +45,9 @@ fn decode_base64(text: &str, url_safe: bool) -> Option> { Some(out) } -fn base64_decode(s: &str) -> Option> { decode_base64(s, false) } +fn base64_decode(s: &str) -> Option> { + decode_base64(s, false) +} #[derive(Debug, Clone, PartialEq)] enum Tok { Open(String), @@ -65,7 +65,7 @@ fn decode_entities(s: &str) -> String { while let Some(p) = rest.find('&') { out.push_str(rest.get(..p).unwrap_or("")); let after = rest.get(p..).unwrap_or(""); - let Some(end) = after.find(';').filter(|&e| e <= 12) else { + let Some(end) = after.as_bytes().iter().take(13).position(|b| *b == b';') else { out.push('&'); rest = after.get(1..).unwrap_or(""); continue; @@ -131,11 +131,11 @@ fn after_declaration(mut rest: &str) -> Result<&str, FormatError> { Err(FormatError::Truncated("declaration".into())) } -fn tokenize(text: &str) -> Result, FormatError> { +fn tokenize(text: &str, max_tokens: usize) -> Result, FormatError> { let mut toks = Vec::new(); let mut rest = text; while !rest.is_empty() { - if toks.len() > MAX_NODES { + if toks.len() >= max_tokens { return Err(FormatError::TooLarge("too many XML tokens".into())); } match rest.find('<') { @@ -198,6 +198,9 @@ fn tokenize(text: &str) -> Result, FormatError> { toks.push(Tok::Open(inner.split_whitespace().next().unwrap_or("").to_string())); } } + if toks.len() > max_tokens { + return Err(FormatError::TooLarge("too many XML tokens".into())); + } Ok(toks) } @@ -205,6 +208,8 @@ struct Xml { toks: Vec, pos: usize, nodes: usize, + limits: Limits, + bytes_left: usize, } impl Xml { @@ -223,7 +228,10 @@ impl Xml { let mut s = String::new(); loop { match self.next() { - Some(Tok::Text(t)) => s.push_str(&t), + Some(Tok::Text(t)) => { + self.bytes_left = self.bytes_left.checked_sub(t.len()).ok_or_else(|| FormatError::TooLarge("XML text/data bytes".into()))?; + s.push_str(&t); + } Some(Tok::Close(n)) if n == name => return Ok(s), Some(other) => return Err(FormatError::Malformed(format!("unexpected {other:?} inside <{name}>"))), None => return Err(FormatError::Truncated(format!("<{name}> is not closed"))), @@ -239,7 +247,7 @@ impl Xml { fn value(&mut self, depth: usize) -> Result { self.nodes += 1; - if depth > MAX_DEPTH || self.nodes > MAX_NODES { + if depth > self.limits.max_depth.min(256) || self.nodes > self.limits.max_nodes.min(self.limits.max_objects) { return Err(FormatError::TooLarge("plist nesting or size limit".into())); } self.skip_space(); @@ -267,7 +275,12 @@ impl Xml { } "real" => { let t = self.text_until("real")?; - t.trim().parse::().ok().filter(|v| v.is_finite()).map(Value::Real).ok_or_else(|| FormatError::Malformed(format!("bad real {t:?}"))) + t.trim() + .parse::() + .ok() + .filter(|v| v.is_finite()) + .map(Value::Real) + .ok_or_else(|| FormatError::Malformed(format!("bad real {t:?}"))) } "date" => Ok(Value::Date(DateValue::Text(self.text_until("date")?.trim().to_string()))), "data" => { @@ -330,12 +343,24 @@ fn decode_utf16_xml(data: &[u8], big_endian: bool) -> Result = data.chunks_exact(2).map(|b| if big_endian { u16::from_be_bytes([b[0], b[1]]) } else { u16::from_le_bytes([b[0], b[1]]) }).collect(); + let units: Vec = data.as_chunks::<2>().0.iter().map(|b| if big_endian { u16::from_be_bytes(*b) } else { u16::from_le_bytes(*b) }).collect(); String::from_utf16(&units).map_err(|_| FormatError::Malformed("invalid UTF-16 in XML plist".into())) } /// Parse an XML property list. pub fn parse_xml(data: &[u8]) -> Result { + parse_xml_with_limits(data, Limits::default()) +} + +/// Parse UTF-8 or BOM-tagged UTF-16 XML with explicit resource allowances. +/// Input and decoded XML text are bounded before tokenization; token count, value count, +/// nesting and cumulative leaf/key text are bounded separately. `max_objects` and +/// `max_nodes` both cap values. Nesting never exceeds 256 even with a larger caller limit. +/// Data text consumes its encoded size, conservatively including whitespace. +pub fn parse_xml_with_limits(data: &[u8], limits: Limits) -> Result { + if data.len() > limits.max_input_bytes { + return Err(FormatError::TooLarge("input bytes".into())); + } // Apple's Core Foundation reader accepts XML plists in UTF-16 as well as // UTF-8: it recognises both byte-order marks. `from_utf8_lossy` turns a // UTF-16 byte stream into NUL-separated text, so the encoding is settled @@ -347,11 +372,14 @@ pub fn parse_xml(data: &[u8]) -> Result { .map_err(|_| FormatError::Malformed("invalid UTF-8 in XML plist".into()))? .to_owned(), }; + if text.len() > limits.max_expanded_bytes { + return Err(FormatError::TooLarge("decoded XML bytes".into())); + } // XML normalizes literal line endings before parsing; character references such as // must still decode to a carriage return afterwards. let text = if text.contains('\r') { text.replace("\r\n", "\n").replace('\r', "\n") } else { text }; - let toks = tokenize(&text)?; - let mut x = Xml { toks, pos: 0, nodes: 0 }; + let toks = tokenize(&text, limits.max_nodes.min(limits.max_objects).saturating_mul(8).saturating_add(8))?; + let mut x = Xml { toks, pos: 0, nodes: 0, limits, bytes_left: limits.max_expanded_bytes }; x.skip_space(); let wrapped = matches!(x.peek(), Some(Tok::Open(n)) if n == "plist"); if wrapped { @@ -371,10 +399,9 @@ pub fn parse_xml(data: &[u8]) -> Result { Ok(value) } - #[cfg(test)] mod tests { -use super::*; + use super::*; #[test] fn xml_has_one_complete_root_with_only_markup_space_around_values() { for invalid in [ @@ -441,4 +468,38 @@ use super::*; assert_eq!(v.get("k"), Some(&Value::Real(want)), "{text}"); } } + + #[test] + fn malformed_entity_scan_is_bounded_and_preserves_text() { + for n in [4096, 65536, 262144] { + let text = "&".repeat(n); + assert_eq!(decode_entities(&text), text); + assert_eq!(decode_entities(&(text.clone() + ";")), text + ";"); + } + assert_eq!(decode_entities("é&missing; & A"), "é&missing; & \r A"); + } + #[test] + fn caller_limits_refuse_before_unbounded_tree_growth() { + let limits = Limits { max_input_bytes: 3, ..Limits::default() }; + assert!(matches!(parse_xml_with_limits(b"", limits), Err(FormatError::TooLarge(_)))); + let limits = Limits { max_nodes: 1, ..Limits::default() }; + assert!(matches!(parse_xml_with_limits(b"", limits), Err(FormatError::TooLarge(_)))); + let limits = Limits { max_depth: 0, ..Limits::default() }; + assert!(matches!(parse_xml_with_limits(b"", limits), Err(FormatError::TooLarge(_)))); + let limits = Limits { max_expanded_bytes: 8, ..Limits::default() }; + assert!(matches!(parse_xml_with_limits(b"abc", limits), Err(FormatError::TooLarge(_)))); + assert!(parse_xml_with_limits(b"", Limits::default()).is_ok()); + } + #[test] + fn data_preserves_existing_whitespace_padding_and_alphabet_rules() { + for (s, expected) in [(" Z g == ", Some(vec![102])), ("Zg", Some(vec![102])), ("Zg=", None), ("Zg==junk", None), ("_w==", None)] { + let xml = format!("{s}"); + assert_eq!(parse_xml(xml.as_bytes()).ok(), expected.map(Value::Data)); + } + } + #[test] + fn small_node_allowance_accepts_one_dictionary_entry() { + let limits = Limits { max_nodes: 2, max_objects: 2, ..Limits::default() }; + assert!(parse_xml_with_limits(b"kv", limits).is_ok()); + } } From f53ed0c505008412554322fda6d5edba79d9f860 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:18:38 -0500 Subject: [PATCH 105/349] Scope imported XML test assertions to test-only lint policy --- crates/plist/src/xml.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/crates/plist/src/xml.rs b/crates/plist/src/xml.rs index 52f5c4586..c6cc4d022 100644 --- a/crates/plist/src/xml.rs +++ b/crates/plist/src/xml.rs @@ -401,6 +401,7 @@ pub fn parse_xml_with_limits(data: &[u8], limits: Limits) -> Result Date: Sun, 15 Nov 2026 16:18:57 +0000 Subject: [PATCH 106/349] Bound and expose partial glyph outlines --- crates/font-catalog/src/outline.rs | 92 ++++++++++++++++++++++++++---- 1 file changed, 81 insertions(+), 11 deletions(-) diff --git a/crates/font-catalog/src/outline.rs b/crates/font-catalog/src/outline.rs index 1f550f983..10a1ae8ab 100644 --- a/crates/font-catalog/src/outline.rs +++ b/crates/font-catalog/src/outline.rs @@ -26,6 +26,12 @@ pub enum OutlineError { /// The glyph's outline is malformed. #[error("cannot draw glyph outline: {0}")] Draw(#[from] skrifa::outline::DrawError), + /// The glyph emitted more path elements than the safety limit. + #[error("glyph outline exceeds the element limit")] + TooComplex, + /// The outline starts without a move command. + #[error("glyph outline has no initial move")] + InvalidPath, } impl<'a> FontOutline<'a> { @@ -58,30 +64,83 @@ impl<'a> FontOutline<'a> { } /// Draw a glyph in design units. Empty glyphs such as spaces can produce an empty path. + /// A malformed or excessively complex glyph returns an error instead of partial geometry. pub fn outline(&self, glyph: u32) -> Result { + let (path, status) = self.outline_recovering(glyph)?; + status.map(|()| path) + } + + /// Draw a glyph while retaining the bounded prefix produced before a draw error. This is + /// useful for consumers preserving existing rendering of damaged fonts. The inner result + /// reports whether the returned path is complete; the outer error means no glyph was found. + /// Paths stop growing at 100,000 elements, even when the font is untrusted. + pub fn outline_recovering(&self, glyph: u32) -> Result<(BezPath, Result<(), OutlineError>), OutlineError> { let outline = self.font.outline_glyphs().get(GlyphId::new(glyph)).ok_or(OutlineError::MissingGlyph)?; - let mut pen = PathPen(BezPath::new()); - outline.draw(DrawSettings::unhinted(Size::unscaled(), &self.location), &mut pen)?; - Ok(pen.0) + let mut pen = PathPen::new(); + let result = outline.draw(DrawSettings::unhinted(Size::unscaled(), &self.location), &mut pen); + let status = if pen.invalid { + Err(OutlineError::InvalidPath) + } else if pen.truncated { + Err(OutlineError::TooComplex) + } else { + result.map(|_| ()).map_err(OutlineError::Draw) + }; + Ok((pen.path, status)) } } -struct PathPen(BezPath); +const MAX_OUTLINE_ELEMENTS: usize = 100_000; +struct PathPen { + path: BezPath, + truncated: bool, + invalid: bool, +} +impl PathPen { + fn new() -> Self { + Self { path: BezPath::new(), truncated: false, invalid: false } + } + fn has_start(&mut self) -> bool { + if self.path.elements().is_empty() { + self.invalid = true; + false + } else { + true + } + } + fn room(&mut self) -> bool { + if self.path.elements().len() >= MAX_OUTLINE_ELEMENTS { + self.truncated = true; + false + } else { + true + } + } +} impl OutlinePen for PathPen { fn move_to(&mut self, x: f32, y: f32) { - self.0.move_to((f64::from(x), f64::from(y))); + if self.room() { + self.path.move_to((f64::from(x), f64::from(y))); + } } fn line_to(&mut self, x: f32, y: f32) { - self.0.line_to((f64::from(x), f64::from(y))); + if self.has_start() && self.room() { + self.path.line_to((f64::from(x), f64::from(y))); + } } fn quad_to(&mut self, x1: f32, y1: f32, x: f32, y: f32) { - self.0.quad_to((f64::from(x1), f64::from(y1)), (f64::from(x), f64::from(y))); + if self.has_start() && self.room() { + self.path.quad_to((f64::from(x1), f64::from(y1)), (f64::from(x), f64::from(y))); + } } fn curve_to(&mut self, x1: f32, y1: f32, x2: f32, y2: f32, x: f32, y: f32) { - self.0.curve_to((f64::from(x1), f64::from(y1)), (f64::from(x2), f64::from(y2)), (f64::from(x), f64::from(y))); + if self.has_start() && self.room() { + self.path.curve_to((f64::from(x1), f64::from(y1)), (f64::from(x2), f64::from(y2)), (f64::from(x), f64::from(y))); + } } fn close(&mut self) { - self.0.close_path(); + if self.has_start() && self.room() { + self.path.close_path(); + } } } @@ -99,14 +158,14 @@ mod tests { #[test] fn pen_preserves_geometry_and_upward_y() { - let mut pen = PathPen(BezPath::new()); + let mut pen = PathPen::new(); pen.move_to(1.0, 2.0); pen.line_to(3.0, 4.0); pen.quad_to(5.0, 6.0, 7.0, 8.0); pen.curve_to(9.0, 10.0, 11.0, 12.0, 13.0, 14.0); pen.close(); assert_eq!( - pen.0.elements(), + pen.path.elements(), &[ PathEl::MoveTo((1.0, 2.0).into()), PathEl::LineTo((3.0, 4.0).into()), @@ -117,6 +176,17 @@ mod tests { ); } + #[test] + fn pen_caps_path_growth() { + let mut pen = PathPen::new(); + pen.move_to(0.0, 0.0); + for _ in 0..MAX_OUTLINE_ELEMENTS { + pen.line_to(1.0, 2.0); + } + assert_eq!(pen.path.elements().len(), MAX_OUTLINE_ELEMENTS); + assert!(pen.truncated); + } + #[test] fn reads_craft_font_when_available() { let Ok(dir) = std::env::var("CRAFT_FONTS_DIR") else { return }; From c17840e099d7a4237770bca99efb2693f1692a8d Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:21:36 -0500 Subject: [PATCH 107/349] Preserve LightCraft zero-padded entities with linear scanning Reuse LightCraft f786b87533e58c6d31c7f9f2897814904448f39a entity_end implementation and regression. XML numeric references are not arbitrarily length limited. --- crates/plist/README.md | 2 +- crates/plist/src/xml.rs | 9 ++++++++- 2 files changed, 9 insertions(+), 2 deletions(-) diff --git a/crates/plist/README.md b/crates/plist/README.md index 5621ef96a..a7adf6c79 100644 --- a/crates/plist/README.md +++ b/crates/plist/README.md @@ -14,6 +14,6 @@ Source: `storytold/craft-anything` at `88d1d9cac852aec1c7fd97886db451e005e49d2a` `parse_xml` and `parse_xml_with_limits` now read UTF-8 and BOM-tagged UTF-16 XML into the same `Value` tree. XML input/decoded-text size, tokens, values, nesting and cumulative key/leaf text are bounded. The independent token ceiling is eight times the smaller node/object allowance plus eight; unusually fragmented text can exhaust it before the value limit. This is not a precise RSS limit. The decoded-XML limit also includes markup; `` consumes its encoded text allowance, including whitespace. XML `max_objects` and `max_nodes` both cap values. -The attributed Craft Anything reader includes its complete-document, declaration-skipping (no external entity fetching), quoted-tag and normalized-line-ending behavior. Nonfinite reals are refused using contributor PR #1905. Unknown or malformed character references retain legacy literal behavior; scanning is bounded before searching for a terminator. Base64 retains that reader's legacy optional-padding/ASCII-whitespace behavior, including unused trailing bits; it is not a signature/key-validation API. No writer, JSON projection, keyed-archive interpretation or app policy is added. +The attributed Craft Anything reader includes its complete-document, declaration-skipping (no external entity fetching), quoted-tag and normalized-line-ending behavior. Nonfinite reals are refused using contributor PR #1905. Unknown or malformed character references retain legacy literal behavior; scanning stops at the next non-entity byte, preserving LightCraft's valid zero-padded numeric references without suffix rescans. Base64 retains that reader's legacy optional-padding/ASCII-whitespace behavior, including unused trailing bits; it is not a signature/key-validation API. No writer, JSON projection, keyed-archive interpretation or app policy is added. XML source: Craft Anything `8f3b775157d331dd31cfa4da911e26d8856b8c77`, plus #1905 `d85e104f093a334961048881bf003351e1ac4992`. The import credits Brandon Thomas and the existing hardening contributors; #1905 is authored by gmrmad1 and the quoted-tag/line-ending tests by RRFZ. Consumer cutovers require their own policy/parity tests, especially LightCraft's preset mapping and Craft Anything's projections. diff --git a/crates/plist/src/xml.rs b/crates/plist/src/xml.rs index c6cc4d022..be225d3fb 100644 --- a/crates/plist/src/xml.rs +++ b/crates/plist/src/xml.rs @@ -56,6 +56,12 @@ enum Tok { Text(String), } +// Ported from LightCraft f786b875: scan one entity-name run, never the remaining document. +fn entity_end(rest: &str) -> Option { + let n = rest.bytes().skip(1).take_while(|b| b.is_ascii_alphanumeric() || *b == b'#').count(); + (rest.as_bytes().get(n + 1) == Some(&b';')).then_some(n + 1) +} + fn decode_entities(s: &str) -> String { if !s.contains('&') { return s.to_string(); @@ -65,7 +71,7 @@ fn decode_entities(s: &str) -> String { while let Some(p) = rest.find('&') { out.push_str(rest.get(..p).unwrap_or("")); let after = rest.get(p..).unwrap_or(""); - let Some(end) = after.as_bytes().iter().take(13).position(|b| *b == b';') else { + let Some(end) = entity_end(after) else { out.push('&'); rest = after.get(1..).unwrap_or(""); continue; @@ -478,6 +484,7 @@ mod tests { assert_eq!(decode_entities(&(text.clone() + ";")), text + ";"); } assert_eq!(decode_entities("é&missing; & A"), "é&missing; & \r A"); + assert_eq!(decode_entities("Canon A"), "Canon A"); } #[test] fn caller_limits_refuse_before_unbounded_tree_growth() { From 2aa7f7f8d211786650d6cc3a4d3f6be165ddb30a Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:22:05 +0000 Subject: [PATCH 108/349] dpx: fix RGBA writer lint --- crates/dpx/src/rgba8_dpx10.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/dpx/src/rgba8_dpx10.rs b/crates/dpx/src/rgba8_dpx10.rs index 6ec5e23b4..05ce20b15 100644 --- a/crates/dpx/src/rgba8_dpx10.rs +++ b/crates/dpx/src/rgba8_dpx10.rs @@ -21,7 +21,7 @@ const DPX_HEADER: usize = 2048; pub fn encode_rgba8_dpx10(rgba: &[u8], w: u32, h: u32, creator: &str) -> std::result::Result, Rgba8EncodeError> { let n = checked_len(rgba, w, h)?; // one 32-bit word per pixel; `n` is already `w * h * 4` - let size = n.checked_add(DPX_HEADER).ok_or_else(|| Rgba8EncodeError::FrameSize)?; + let size = n.checked_add(DPX_HEADER).ok_or(Rgba8EncodeError::FrameSize)?; let file_size = u32::try_from(size).map_err(|_| Rgba8EncodeError::TooLarge)?; // SMPTE ST 268: undefined numeric fields are all ones, undefined text fields are NUL let mut hd = vec![0xFF_u8; DPX_HEADER]; From 4c17e51335192345d8e508287c26f17fead930ac Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:23:03 +0000 Subject: [PATCH 109/349] exr: fix RGBA writer lint --- crates/exr/src/rgba8.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/crates/exr/src/rgba8.rs b/crates/exr/src/rgba8.rs index 0b26ab8c9..6dc4bde4c 100644 --- a/crates/exr/src/rgba8.rs +++ b/crates/exr/src/rgba8.rs @@ -81,7 +81,7 @@ pub fn write_rgba8(rgba: &[u8], w: u32, h: u32, alpha: bool, compression: Compre }; // channels in the alphabetical order the file layout requires let names: &[u8] = if alpha { b"ABGR" } else { b"BGR" }; - let line = (w as usize).checked_mul(names.len() * 2).ok_or_else(|| Error::FrameSize)?; + let line = (w as usize).checked_mul(names.len() * 2).ok_or(Error::FrameSize)?; // a chunk's byte count is a signed 32-bit field let lines = compression.lines(); if line.checked_mul(lines).and_then(|c| i32::try_from(c).ok()).is_none() { @@ -125,7 +125,7 @@ pub fn write_rgba8(rgba: &[u8], w: u32, h: u32, alpha: bool, compression: Compre let chunks = (h as usize).div_ceil(lines); let table = chunks.checked_mul(8); let body = (h as usize).checked_mul(line + 8); - let size = table.zip(body).and_then(|(t, b)| hd.len().checked_add(t)?.checked_add(b)).ok_or_else(|| Error::FrameSize)?; + let size = table.zip(body).and_then(|(t, b)| hd.len().checked_add(t)?.checked_add(b)).ok_or(Error::FrameSize)?; // the uncompressed size: compressed chunks only shrink it let mut out = Vec::with_capacity(size); out.extend_from_slice(&hd); From 0dab3133a2a58d321ade446f23592e7855b79e78 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 11:24:10 -0500 Subject: [PATCH 110/349] Allow consumers to retain opaque XML date text --- crates/plist/src/lib.rs | 2 +- crates/plist/src/xml.rs | 35 +++++++++++++++++++++++++++++++++-- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/crates/plist/src/lib.rs b/crates/plist/src/lib.rs index 2547e73d8..d668de277 100644 --- a/crates/plist/src/lib.rs +++ b/crates/plist/src/lib.rs @@ -6,7 +6,7 @@ mod binary; mod bytes; mod xml; pub use binary::{DateValue, Value, first_string_in_array, parse_binary, parse_binary_with_limits}; -pub use xml::{parse_xml, parse_xml_with_limits}; +pub use xml::{XmlOptions, parse_xml, parse_xml_with_limits, parse_xml_with_options}; /// Caller-selected resource limits. Zero values refuse the corresponding resource. #[derive(Clone, Copy, Debug)] diff --git a/crates/plist/src/xml.rs b/crates/plist/src/xml.rs index be225d3fb..d30b938d0 100644 --- a/crates/plist/src/xml.rs +++ b/crates/plist/src/xml.rs @@ -1,5 +1,18 @@ //! XML property-list reader ported from Craft Anything at 8f3b7751. use crate::{DateValue, FormatError, Limits, Value}; + +/// XML-specific representation policy, separate from resource allowances. +#[derive(Clone, Copy, Debug)] +pub struct XmlOptions { + /// Trim surrounding whitespace in date text, as the original Craft Anything reader does. + /// Disable for consumers that retain dates as opaque strings, such as Luminar presets. + pub trim_date_text: bool, +} +impl Default for XmlOptions { + fn default() -> Self { + Self { trim_date_text: true } + } +} fn decode_base64(text: &str, url_safe: bool) -> Option> { let mut out = Vec::with_capacity(text.len() / 4 * 3); let mut acc = 0u32; @@ -216,6 +229,7 @@ struct Xml { nodes: usize, limits: Limits, bytes_left: usize, + options: XmlOptions, } impl Xml { @@ -288,7 +302,10 @@ impl Xml { .map(Value::Real) .ok_or_else(|| FormatError::Malformed(format!("bad real {t:?}"))) } - "date" => Ok(Value::Date(DateValue::Text(self.text_until("date")?.trim().to_string()))), + "date" => { + let text = self.text_until("date")?; + Ok(Value::Date(DateValue::Text(if self.options.trim_date_text { text.trim().to_string() } else { text }))) + } "data" => { let t = self.text_until("data")?; base64_decode(&t).map(Value::Data).ok_or_else(|| FormatError::Malformed("bad base64 in ".into())) @@ -364,6 +381,11 @@ pub fn parse_xml(data: &[u8]) -> Result { /// `max_nodes` both cap values. Nesting never exceeds 256 even with a larger caller limit. /// Data text consumes its encoded size, conservatively including whitespace. pub fn parse_xml_with_limits(data: &[u8], limits: Limits) -> Result { + parse_xml_with_options(data, limits, XmlOptions::default()) +} + +/// Parse bounded XML using an explicit date-text representation policy. +pub fn parse_xml_with_options(data: &[u8], limits: Limits, options: XmlOptions) -> Result { if data.len() > limits.max_input_bytes { return Err(FormatError::TooLarge("input bytes".into())); } @@ -385,7 +407,7 @@ pub fn parse_xml_with_limits(data: &[u8], limits: Limits) -> Resultkv", limits).is_ok()); } + #[test] + fn callers_can_preserve_opaque_date_whitespace() { + let xml = b" 2026-01-01T00:00:00Z "; + assert_eq!(parse_xml(xml).unwrap(), Value::Date(DateValue::Text("2026-01-01T00:00:00Z".into()))); + assert_eq!( + parse_xml_with_options(xml, Limits::default(), XmlOptions { trim_date_text: false }).unwrap(), + Value::Date(DateValue::Text(" 2026-01-01T00:00:00Z ".into())) + ); + } } From 159b942defe3613c91a4beec5fadfcb1593f2600 Mon Sep 17 00:00:00 2001 From: "Dylan M. Taylor" Date: Sun, 15 Nov 2026 16:24:27 +0000 Subject: [PATCH 111/349] Share contextual directional text shaping --- Cargo.lock | 1 + crates/font-catalog/Cargo.toml | 1 + crates/font-catalog/src/lib.rs | 2 + crates/font-catalog/src/shape.rs | 150 +++++++++++++++++++++++++++++++ 4 files changed, 154 insertions(+) create mode 100644 crates/font-catalog/src/shape.rs diff --git a/Cargo.lock b/Cargo.lock index 9424cf3fe..3e1487dca 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1761,6 +1761,7 @@ name = "craft-font-catalog" version = "0.1.0" dependencies = [ "fontique", + "harfrust 0.13.3", "kurbo 0.13.1", "skrifa 0.47.0", "thiserror 2.0.21", diff --git a/crates/font-catalog/Cargo.toml b/crates/font-catalog/Cargo.toml index 1f0830a63..c53d871b8 100644 --- a/crates/font-catalog/Cargo.toml +++ b/crates/font-catalog/Cargo.toml @@ -15,6 +15,7 @@ default = ["system"] system = ["dep:fontique"] [dependencies] +harfrust = "0.13" kurbo = { workspace = true } skrifa = { version = "0.47", default-features = false, features = ["std"] } thiserror = { workspace = true } diff --git a/crates/font-catalog/src/lib.rs b/crates/font-catalog/src/lib.rs index 7da4ca310..176a38738 100644 --- a/crates/font-catalog/src/lib.rs +++ b/crates/font-catalog/src/lib.rs @@ -26,6 +26,7 @@ mod fontconfig; mod outline; mod registry; mod scan; +mod shape; mod suitcase; pub mod system; @@ -34,6 +35,7 @@ pub use env::{FontEnv, Os, font_dirs, font_store_dir, office_font_dirs}; pub use fontconfig::fontconfig_dirs; pub use outline::{FontOutline, OutlineError}; pub use scan::{FaceInfo, LocalizedName, Source, is_font_file, style_italic, style_weight, style_width}; +pub use shape::{RunGlyph, RunInput, ShapeRunError, shape_run}; #[cfg(test)] mod tests; diff --git a/crates/font-catalog/src/shape.rs b/crates/font-catalog/src/shape.rs new file mode 100644 index 000000000..7fb0814d3 --- /dev/null +++ b/crates/font-catalog/src/shape.rs @@ -0,0 +1,150 @@ +//! Shape a run with its source clusters and surrounding text context. + +use std::sync::Arc; + +use harfrust::{BufferClusterLevel, Direction, Feature, Language, Script, ShapeOptions, ShapePlan, Shaper, UnicodeBuffer}; + +/// Parameters for a single directional run. Text is in logical order and `source_start` is its +/// byte offset in the complete source. Context influences joining but emits no glyphs. +pub struct RunInput<'a> { + /// Text in this run. + pub text: &'a str, + /// Its byte offset in the complete source. + pub source_start: usize, + /// Text before the run, within the same shaping context. + pub pre_context: &'a str, + /// Text after the run, within the same shaping context. + pub post_context: &'a str, + /// Direction of shaping. + pub direction: Direction, + /// Language used for language-specific forms. + pub language: Option<&'a Language>, + /// OpenType features with ranges in source byte coordinates. + pub features: &'a [Feature], + /// Use character-level instead of monotone grapheme clusters. + pub character_clusters: bool, + /// Uppercase each mapped character without losing its source cluster. + pub uppercase: bool, +} + +/// A glyph in design units, with its source-byte cluster and directional advances and offsets. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct RunGlyph { + pub glyph_id: u32, + pub cluster: u32, + pub x_advance: i32, + pub y_advance: i32, + pub x_offset: i32, + pub y_offset: i32, +} + +/// A run's source offsets cannot fit HarfRust's 32-bit clusters. +#[derive(Debug, thiserror::Error)] +#[error("shaping cluster exceeds the 32-bit source offset range")] +pub struct ShapeRunError; + +/// Shape a run using a caller's face-specific plan cache. `map_character` applies digit or other +/// character mapping before case conversion; expansions retain the original byte cluster. +/// The plan callback receives the guessed script, direction, language and feature set so it can +/// reuse plans for the particular shaper and its variable-font instance. +pub fn shape_run( + shaper: &Shaper<'_>, + input: &RunInput<'_>, + mut map_character: impl FnMut(char) -> char, + plan: impl FnOnce(&Shaper<'_>, Direction, Option