Skip to main content

openreadout_codecs/
lib.rs

1//! Pure-Rust decoders used by the format readers. No C toolchain is needed, which keeps
2//! the musl static builds simple. Every function returns owned bytes in the caller's
3//! expected layout; nothing here knows about file formats.
4//!
5//! Every decoder is bounded: output never grows past the caller's expected size (plus one
6//! byte to detect overlong streams), and size hints are only trusted up to
7//! [`MAX_PREALLOC`] for up-front allocation.
8//!
9//! Decoding failures are reported as [`CodecError`] values, never by exiting the process.
10//!
11//! # Cargo features
12//!
13//! All enabled by default. A disabled codec's functions still exist and return
14//! [`CodecError::NotCompiled`].
15//!
16//! | feature | codecs |
17//! | --- | --- |
18//! | `zstd` | [`zstd_decode`], [`zstd1_decode`] (Zstandard, via `ruzstd`) |
19//! | `jpeg` | [`jpeg_decode`], [`jpeg_decode_tiff`] and their `_limited` forms (baseline, progressive, lossless) |
20//! | `jpegxr` | [`jpegxr_decode`] (JPEG XR, as in CZI files; `openreadout-jpegxr`, a safe port of jxrlib) |
21//! | `jpegls` | [`jpegls_decode_limited`] (JPEG-LS lossless and near-lossless, single component; `pure_jpegls`) |
22//! | `jpeg2000` | [`jpeg2000_decode`] and [`jpeg2000_decode_limited`] (`rust-j2k`, fallback `dicom-toolkit-jpeg2000`) |
23//! | `lzw` | [`lzw_decode`] (TIFF LZW) |
24//! | `deflate` | [`zlib_decode`] |
25//! | `lz4` | [`lz4_block_decode`], [`lz4_sized_decode`], [`hdf5_lz4_decode`] and LZ4 inside Blosc |
26//!
27//! [`chunked_decode`] (CZI chunked compression) uses the `zstd` and `lz4` features.
28//!
29//! [`unshuffle_hilo`], [`packbits_decode`], [`lzf_decode`], [`blosc_decode`], [`blosclz_decode`] and
30//! [`lzma2_decode`] (raw LZMA2 chunks) need no feature.
31//!
32//! # Example
33//!
34//! ```
35//! use openreadout_codecs::{packbits_decode, unshuffle_hilo};
36//!
37//! // PackBits: a literal run of 2 bytes, then the byte 0xAA repeated 3 times.
38//! let raw = packbits_decode(&[0x01, 0x10, 0x20, 0xFE, 0xAA], 5)?;
39//! assert_eq!(raw, [0x10, 0x20, 0xAA, 0xAA, 0xAA]);
40//!
41//! // "HiLo": all low bytes of 16-bit samples, then all high bytes.
42//! assert_eq!(unshuffle_hilo(&[0x01, 0x02, 0xA0, 0xB0]), [0x01, 0xA0, 0x02, 0xB0]);
43//! # Ok::<(), openreadout_codecs::CodecError>(())
44//! ```
45#![forbid(unsafe_code)]
46#![warn(missing_docs)]
47
48mod blosc;
49mod chunked;
50#[cfg(feature = "jpeg2000")]
51mod j2k;
52#[cfg(feature = "jpegls")]
53mod jls;
54#[cfg(feature = "jpeg")]
55mod jpeg12;
56#[cfg(feature = "jpegxl")]
57mod jxl;
58#[cfg(feature = "lerc")]
59mod lerc;
60mod lzma;
61#[cfg(feature = "webp")]
62mod webp;
63
64pub use blosc::{
65    BloscCompressor, BloscHeader, bitshuffle_decode, blosc_decode, blosc_header, blosclz_decode,
66    hdf5_lz4_decode, lz4_block_decode, lz4_sized_decode, snappy_decode,
67};
68pub use chunked::chunked_decode;
69pub use lzma::lzma2_decode;
70
71/// Codec failure.
72#[derive(Debug, thiserror::Error)]
73#[non_exhaustive]
74pub enum CodecError {
75    /// The data is not a valid stream for this codec.
76    #[error("{codec}: {detail}")]
77    Decode {
78        /// Codec name.
79        codec: &'static str,
80        /// What is wrong with the stream.
81        detail: String,
82    },
83    /// The codec was left out at build time.
84    #[error("{codec} support was not compiled in (feature `{feature}`)")]
85    NotCompiled {
86        /// Codec name.
87        codec: &'static str,
88        /// Cargo feature that enables it.
89        feature: &'static str,
90    },
91    /// A valid stream that uses a feature this decoder does not implement.
92    #[error("{codec}: {detail} is not supported")]
93    Unsupported {
94        /// Codec name.
95        codec: &'static str,
96        /// The feature.
97        detail: String,
98    },
99    /// The stream decoded, but not to the expected number of bytes.
100    #[error("decoded {codec} data is {got} bytes, expected {expected}")]
101    SizeMismatch {
102        /// Codec name.
103        codec: &'static str,
104        /// Bytes decoded.
105        got: usize,
106        /// Bytes the caller expected.
107        expected: usize,
108    },
109}
110
111/// Result alias of this crate.
112pub type Result<T> = std::result::Result<T, CodecError>;
113
114/// Largest buffer a decoder pre-allocates from a caller-supplied size hint (64 MiB). Output
115/// beyond this grows on demand, so a lying size field cannot force a huge up-front allocation.
116pub const MAX_PREALLOC: usize = 64 << 20;
117
118/// Output cap for streams whose decoded size is unknown (`expected_len == 0`): 1 GiB.
119pub const MAX_UNSIZED_OUTPUT: usize = 1 << 30;
120
121/// How many bytes a decoder may produce: one more than expected (so "too long" is
122/// detectable without decoding a bomb to the end), or the unsized cap.
123fn output_limit(expected_len: usize) -> usize {
124    if expected_len == 0 {
125        MAX_UNSIZED_OUTPUT
126    } else {
127        expected_len.saturating_add(1)
128    }
129}
130
131/// Decompress a plain zstd frame. `expected_len` is a sanity bound (0 = unknown); decoding
132/// stops one byte past it, so a decompression bomb costs at most `expected_len + 1` bytes.
133pub fn zstd_decode(data: &[u8], expected_len: usize) -> Result<Vec<u8>> {
134    #[cfg(feature = "zstd")]
135    {
136        use std::io::Read;
137        // Fast path when the size is known: decode straight into a buffer of that size (no
138        // `Read` adapter). Any failure, including trailing bytes after the frame or a size
139        // other than expected, falls through to the streaming decoder below, which produces
140        // the same results and errors.
141        if expected_len != 0 && expected_len <= MAX_PREALLOC {
142            let mut out = vec![0u8; expected_len];
143            let mut fd = ruzstd::decoding::FrameDecoder::new();
144            if let Ok(n) = fd.decode_all(data, &mut out)
145                && n == expected_len
146            {
147                return Ok(out);
148            }
149        }
150        let dec =
151            ruzstd::decoding::StreamingDecoder::new(data).map_err(|e| CodecError::Decode {
152                codec: "zstd",
153                detail: e.to_string(),
154            })?;
155        let limit = output_limit(expected_len);
156        let mut out = Vec::with_capacity(expected_len.min(MAX_PREALLOC));
157        dec.take(limit as u64)
158            .read_to_end(&mut out)
159            .map_err(|e| CodecError::Decode {
160                codec: "zstd",
161                detail: e.to_string(),
162            })?;
163        if (expected_len != 0 && out.len() != expected_len) || out.len() >= MAX_UNSIZED_OUTPUT {
164            return Err(CodecError::SizeMismatch {
165                codec: "zstd",
166                got: out.len(),
167                expected: expected_len,
168            });
169        }
170        Ok(out)
171    }
172    #[cfg(not(feature = "zstd"))]
173    {
174        let _ = (data, expected_len);
175        Err(CodecError::NotCompiled {
176            codec: "zstd",
177            feature: "zstd",
178        })
179    }
180}
181
182/// Parsed "zstd1" prefix used by CZI compression id 6: `header_size`, `chunk_kind`, flags.
183#[derive(Debug, Clone, Copy, PartialEq, Eq)]
184pub struct Zstd1Header {
185    /// Size of the header in bytes (byte 0).
186    pub header_size: u8,
187    /// Kind of the first header chunk (byte 1).
188    pub chunk_kind: u8,
189    /// Bit 0 of the flags byte: samples were byte-shuffled into low-byte and high-byte halves.
190    pub hilo: bool,
191}
192
193/// Parse the zstd1 header; returns the header and the offset of the zstd frame.
194pub fn zstd1_header(data: &[u8]) -> Result<(Zstd1Header, usize)> {
195    if data.len() < 2 {
196        return Err(CodecError::Decode {
197            codec: "zstd1",
198            detail: "buffer shorter than the header".into(),
199        });
200    }
201    let header_size = data[0] as usize;
202    if header_size < 1 || header_size > data.len() {
203        return Err(CodecError::Decode {
204            codec: "zstd1",
205            detail: format!("implausible header_size {header_size}"),
206        });
207    }
208    let chunk_kind = data.get(1).copied().unwrap_or(0);
209    let flags = if header_size >= 3 { data[2] } else { 0 };
210    Ok((
211        Zstd1Header {
212            header_size: header_size as u8,
213            chunk_kind,
214            hilo: flags & 1 != 0,
215        },
216        header_size,
217    ))
218}
219
220/// Decode a zstd1 payload into interleaved samples of `bytes_per_sample` bytes.
221pub fn zstd1_decode(data: &[u8], expected_len: usize, bytes_per_sample: usize) -> Result<Vec<u8>> {
222    let (h, off) = zstd1_header(data)?;
223    let raw = zstd_decode(data.get(off..).unwrap_or_default(), expected_len)?;
224    if h.hilo && bytes_per_sample == 2 {
225        Ok(unshuffle_hilo(&raw))
226    } else {
227        Ok(raw)
228    }
229}
230
231/// Undo the `HiLo` byte shuffle: input is all low bytes followed by all high bytes of
232/// 16-bit little-endian samples; output is the interleaved samples.
233pub fn unshuffle_hilo(shuffled: &[u8]) -> Vec<u8> {
234    let n = shuffled.len() / 2;
235    let (lo, rest) = shuffled.split_at(n);
236    let hi = &rest[..n];
237    let mut out = vec![0u8; shuffled.len()];
238    // Zipped fixed-size chunks: no per-byte capacity or bounds checks in the loop.
239    for (pair, (&l, &h)) in out.as_chunks_mut::<2>().0.iter_mut().zip(lo.iter().zip(hi)) {
240        *pair = [l, h];
241    }
242    if shuffled.len() % 2 == 1 {
243        out[shuffled.len() - 1] = shuffled[shuffled.len() - 1];
244    }
245    out
246}
247
248/// A decoded raster: interleaved samples, no row padding.
249#[derive(Debug, Clone)]
250pub struct Raster {
251    /// Width in pixels.
252    pub width: u32,
253    /// Height in pixels.
254    pub height: u32,
255    /// Samples per pixel (1 for grayscale, 3 for colour).
256    pub channels: u32,
257    /// Bits per sample.
258    pub bits_per_sample: u32,
259    /// True for floating-point samples.
260    pub float: bool,
261    /// True when the codestream declares B,G,R sample order (the caller may want R,G,B).
262    pub bgr: bool,
263    /// The samples, interleaved, `width × channels × bits_per_sample / 8` bytes per row.
264    pub data: Vec<u8>,
265}
266
267/// Decode a JPEG XR codestream (as embedded in CZI subblocks).
268pub fn jpegxr_decode(data: &[u8]) -> Result<Raster> {
269    jpegxr_decode_expect(data, None)
270}
271
272/// Decode a JPEG XR codestream, refusing before any pixel allocation when the codestream's
273/// own dimensions differ from `expect` (width, height), e.g. the geometry a CZI directory
274/// entry declares. Without an expectation the decoded size is capped at
275/// [`MAX_UNSIZED_OUTPUT`].
276///
277/// Backed by `openreadout-jpegxr`, our `forbid(unsafe_code)` port of the decoder path of
278/// Microsoft's jxrlib (bit-exact with it). Features that decoder does not implement (alpha
279/// planes, CMYK, packed formats, ...) are [`CodecError::Unsupported`].
280pub fn jpegxr_decode_expect(data: &[u8], expect: Option<(u32, u32)>) -> Result<Raster> {
281    #[cfg(feature = "jpegxr")]
282    {
283        use openreadout_jpegxr as jxr;
284        let map = |e: jxr::Error| match e {
285            jxr::Error::Unsupported(m) => CodecError::Unsupported {
286                codec: "jpeg-xr",
287                detail: m,
288            },
289            other => CodecError::Decode {
290                codec: "jpeg-xr",
291                detail: other.to_string(),
292            },
293        };
294        let info = jxr::probe(data).map_err(map)?;
295        if let Some((ew, eh)) = expect
296            && (ew, eh) != (info.width, info.height)
297        {
298            return Err(CodecError::Decode {
299                codec: "jpeg-xr",
300                detail: format!(
301                    "codestream is {}x{} but {ew}x{eh} was declared",
302                    info.width, info.height
303                ),
304            });
305        }
306        let limit = match expect {
307            // The declared geometry at the widest sample layout (4 x 32-bit per pixel).
308            Some((w, h)) => {
309                (u64::from(w) * u64::from(h) * 16).min(MAX_UNSIZED_OUTPUT as u64) as usize
310            }
311            None => MAX_UNSIZED_OUTPUT,
312        };
313        let img = jxr::decode(data, limit).map_err(map)?;
314        let (bits, float) = match img.sample {
315            jxr::SampleType::U8 => (8, false),
316            jxr::SampleType::U16 => (16, false),
317            jxr::SampleType::F32 => (32, true),
318            other => {
319                return Err(CodecError::Unsupported {
320                    codec: "jpeg-xr",
321                    detail: format!("{other:?} samples (signed fixed point or half float)"),
322                });
323            }
324        };
325        Ok(Raster {
326            width: img.width,
327            height: img.height,
328            channels: img.channels,
329            bits_per_sample: bits,
330            float,
331            bgr: img.bgr,
332            data: img.data,
333        })
334    }
335    #[cfg(not(feature = "jpegxr"))]
336    {
337        let _ = (data, expect);
338        Err(CodecError::NotCompiled {
339            codec: "jpeg-xr",
340            feature: "jpegxr",
341        })
342    }
343}
344
345/// `io::Write` sink that refuses to grow past `limit` bytes (decompression-bomb guard).
346#[cfg(feature = "lzw")]
347struct LimitedWriter {
348    buf: Vec<u8>,
349    limit: usize,
350}
351
352#[cfg(feature = "lzw")]
353impl std::io::Write for LimitedWriter {
354    fn write(&mut self, data: &[u8]) -> std::io::Result<usize> {
355        let room = self.limit - self.buf.len();
356        if room == 0 && !data.is_empty() {
357            return Err(std::io::Error::other(
358                "decoded data exceeds the declared size",
359            ));
360        }
361        let n = data.len().min(room);
362        self.buf.extend_from_slice(&data[..n]);
363        Ok(n)
364    }
365    fn flush(&mut self) -> std::io::Result<()> {
366        Ok(())
367    }
368}
369
370/// Decode a JPEG stream (ITU-T T.81): baseline and progressive 8-bit, sequential 12-bit
371/// (extended process, Huffman coding, no chroma subsampling), lossless (SOF3) up to 16 bit.
372/// Returns gray (`channels == 1`) or R,G,B (`channels == 3`) samples; samples above 8 bits
373/// come back as little-endian u16. Progressive or subsampled 12-bit streams and CMYK are
374/// rejected with an error.
375pub fn jpeg_decode(data: &[u8]) -> Result<Raster> {
376    jpeg_decode_with(data, None, MAX_UNSIZED_OUTPUT, 0)
377}
378
379/// [`jpeg_decode`], refusing (before decoding anything) a frame whose decoded size would
380/// exceed `max_bytes`. Callers that know the tile or plane size pass a bound derived from it,
381/// so a few-byte stream declaring 60000 x 15000 pixels costs nothing.
382pub fn jpeg_decode_limited(data: &[u8], max_bytes: usize) -> Result<Raster> {
383    jpeg_decode_with(data, None, max_bytes.min(MAX_UNSIZED_OUTPUT), 0)
384}
385
386/// [`jpeg_decode_limited`] at a reduced size: `shift` 1, 2 or 3 decodes at 1/2, 1/4 or 1/8 of
387/// the width and height (rounded up) with jpeg-decoder's reduced inverse DCT, as slide readers
388/// do for levels the file does not store. 8-bit streams only.
389pub fn jpeg_decode_reduced(data: &[u8], shift: u32, max_bytes: usize) -> Result<Raster> {
390    jpeg_decode_with(data, None, max_bytes.min(MAX_UNSIZED_OUTPUT), shift)
391}
392
393/// `color`: `None` keeps the decoder's default (Adobe/JFIF markers, else YCbCr for three
394/// components); `Some` forces the transform. `max_bytes`: largest decoded frame accepted.
395fn jpeg_decode_with(
396    data: &[u8],
397    color: Option<JpegColor>,
398    max_bytes: usize,
399    shift: u32,
400) -> Result<Raster> {
401    #[cfg(feature = "jpeg")]
402    {
403        if shift > 3 {
404            return Err(CodecError::Decode {
405                codec: "jpeg",
406                detail: format!("reduction 1/{} (at most 1/8)", 1u64 << shift.min(63)),
407            });
408        }
409        // jpeg-decoder stops at 8-bit DCT samples; 12-bit sequential streams have their own
410        // decoder (`jpeg12`).
411        if jpeg12::frame_precision(data) == Some(12) {
412            if shift > 0 {
413                return Err(CodecError::Decode {
414                    codec: "jpeg",
415                    detail: "reduced-size decoding of a 12-bit stream".into(),
416                });
417            }
418            return jpeg12::decode(data, color, max_bytes);
419        }
420        let mut dec = jpeg_decoder::Decoder::new(data);
421        // A frame header can declare 65535 x 65535 x 4 samples; cap what the decoder allocates.
422        dec.set_max_decoding_buffer_size(MAX_UNSIZED_OUTPUT);
423        dec.read_info().map_err(|e| CodecError::Decode {
424            codec: "jpeg",
425            detail: e.to_string(),
426        })?;
427        // That cap applies to the output only: the decoder sizes its per-component planes
428        // from the frame header before checking it (a 342-byte stream made it allocate 4 GB).
429        if let Some(i) = dec.info() {
430            let bytes =
431                u64::from(i.width) * u64::from(i.height) * i.pixel_format.pixel_bytes() as u64;
432            if bytes > max_bytes as u64 {
433                return Err(CodecError::Decode {
434                    codec: "jpeg",
435                    detail: format!(
436                        "frame header declares {} x {} pixels ({bytes} bytes decoded)",
437                        i.width, i.height
438                    ),
439                });
440            }
441        }
442        if shift > 0
443            && let Some(i) = dec.info()
444        {
445            let (w, h) = (i.width.div_ceil(1 << shift), i.height.div_ceil(1 << shift));
446            dec.scale(w, h).map_err(|e| CodecError::Decode {
447                codec: "jpeg",
448                detail: e.to_string(),
449            })?;
450        }
451        if let Some(color) = color {
452            // Only three-component streams have a colour transform to choose.
453            if dec
454                .info()
455                .is_some_and(|i| i.pixel_format == jpeg_decoder::PixelFormat::RGB24)
456            {
457                dec.set_color_transform(match color {
458                    // "RGB" in jpeg-decoder: the components already are R, G, B (no conversion).
459                    JpegColor::AsCoded => jpeg_decoder::ColorTransform::RGB,
460                    JpegColor::ToRgb => jpeg_decoder::ColorTransform::YCbCr,
461                });
462            }
463        }
464        let px = dec.decode().map_err(|e| CodecError::Decode {
465            codec: "jpeg",
466            detail: e.to_string(),
467        })?;
468        let info = dec.info().ok_or_else(|| CodecError::Decode {
469            codec: "jpeg",
470            detail: "stream has no frame header".into(),
471        })?;
472        let (channels, bits_per_sample, data) = match info.pixel_format {
473            jpeg_decoder::PixelFormat::L8 => (1, 8, px),
474            jpeg_decoder::PixelFormat::RGB24 => (3, 8, px),
475            // jpeg-decoder hands back native-endian u16; normalize to little-endian.
476            jpeg_decoder::PixelFormat::L16 => (
477                1,
478                16,
479                px.as_chunks::<2>()
480                    .0
481                    .iter()
482                    .flat_map(|c| u16::from_ne_bytes(*c).to_le_bytes())
483                    .collect(),
484            ),
485            jpeg_decoder::PixelFormat::CMYK32 => {
486                return Err(CodecError::Decode {
487                    codec: "jpeg",
488                    detail: "CMYK JPEG streams are not supported".into(),
489                });
490            }
491        };
492        let (width, height) = (u32::from(info.width), u32::from(info.height));
493        let need =
494            width as usize * height as usize * channels as usize * (bits_per_sample as usize / 8);
495        if data.len() < need {
496            return Err(CodecError::SizeMismatch {
497                codec: "jpeg",
498                got: data.len(),
499                expected: need,
500            });
501        }
502        Ok(Raster {
503            width,
504            height,
505            channels,
506            bits_per_sample,
507            float: false,
508            bgr: false,
509            data,
510        })
511    }
512    #[cfg(not(feature = "jpeg"))]
513    {
514        let _ = (data, color, max_bytes, shift);
515        Err(CodecError::NotCompiled {
516            codec: "jpeg",
517            feature: "jpeg",
518        })
519    }
520}
521
522/// Decode a JPEG 2000 codestream (raw J2K `FF 4F FF 51…` or a JP2 file) at its native bit depth.
523/// Samples are interleaved; precisions above 8 bits come back as little-endian u16. Used for the
524/// frames of legacy (NIS-Elements 2.x) ND2 files, VSI/ETS tiles and Aperio SVS tiles. Backed by
525/// `rust-j2k` (pure Rust, no `unsafe`, OpenJPEG-style mid-point reconstruction), with
526/// `dicom-toolkit-jpeg2000` for codestreams it does not support (see `j2k.rs`). The caller
527/// converts colour: components come back as coded (after the codestream's own RCT/ICT).
528/// Signed components (DICOM CT) come back as the two's-complement bit pattern of i8 or i16.
529pub fn jpeg2000_decode(data: &[u8]) -> Result<Raster> {
530    jpeg2000_decode_limited(data, MAX_UNSIZED_OUTPUT)
531}
532
533/// [`jpeg2000_decode`], refusing (before decoding) an image that would decode to more than
534/// `max_bytes` (counted at 2 bytes per sample).
535pub fn jpeg2000_decode_limited(data: &[u8], max_bytes: usize) -> Result<Raster> {
536    #[cfg(feature = "jpeg2000")]
537    {
538        j2k::decode(data, max_bytes)
539    }
540    #[cfg(not(feature = "jpeg2000"))]
541    {
542        let _ = (data, max_bytes);
543        Err(CodecError::NotCompiled {
544            codec: "jpeg2000",
545            feature: "jpeg2000",
546        })
547    }
548}
549
550/// Decode a JPEG-LS stream (ITU-T T.87: lossless and near-lossless, one component), refusing
551/// (before decoding) an image that would decode to more than `max_bytes` (counted at 2 bytes
552/// per sample). Precisions up to 8 bits come back as u8, above as little-endian u16. Colour
553/// (multi-component) streams are refused with [`CodecError::Unsupported`].
554pub fn jpegls_decode_limited(data: &[u8], max_bytes: usize) -> Result<Raster> {
555    #[cfg(feature = "jpegls")]
556    {
557        jls::decode(data, max_bytes)
558    }
559    #[cfg(not(feature = "jpegls"))]
560    {
561        let _ = (data, max_bytes);
562        Err(CodecError::NotCompiled {
563            codec: "jpeg-ls",
564            feature: "jpegls",
565        })
566    }
567}
568
569/// Decode a WebP file (lossy VP8 or lossless VP8L; TIFF compression 50001) to 8-bit R,G,B, or
570/// R,G,B,A when the file has alpha, refusing (before decoding) an image larger than
571/// `max_bytes`. Backed by `image-webp` (pure Rust, no `unsafe`).
572pub fn webp_decode_limited(data: &[u8], max_bytes: usize) -> Result<Raster> {
573    #[cfg(feature = "webp")]
574    {
575        webp::decode(data, max_bytes)
576    }
577    #[cfg(not(feature = "webp"))]
578    {
579        let _ = (data, max_bytes);
580        Err(CodecError::NotCompiled {
581            codec: "webp",
582            feature: "webp",
583        })
584    }
585}
586
587/// Decode a JPEG XL codestream or container (TIFF compression 50002/52546): the first frame,
588/// colour channels then extra channels (alpha, ...), interleaved; u8 up to 8 bits per sample,
589/// little-endian u16 up to 16, f32 for float images. Refuses (before rendering) an image larger
590/// than `max_bytes`. Backed by `jxl-oxide`.
591pub fn jpegxl_decode_limited(data: &[u8], max_bytes: usize) -> Result<Raster> {
592    #[cfg(feature = "jpegxl")]
593    {
594        jxl::decode(data, max_bytes)
595    }
596    #[cfg(not(feature = "jpegxl"))]
597    {
598        let _ = (data, max_bytes);
599        Err(CodecError::NotCompiled {
600            codec: "jpeg-xl",
601            feature: "jpegxl",
602        })
603    }
604}
605
606/// Decode a LERC2 blob (TIFF compression 34887, after any deflate/zstd wrapping is removed) to
607/// interleaved little-endian samples of the blob's type (`channels` = depth x bands); pixels
608/// its mask marks invalid are 0. Refuses (before decoding) an image larger than `max_bytes`.
609/// Backed by `lerc-rs`.
610pub fn lerc_decode_limited(data: &[u8], max_bytes: usize) -> Result<Raster> {
611    #[cfg(feature = "lerc")]
612    {
613        lerc::decode(data, max_bytes)
614    }
615    #[cfg(not(feature = "lerc"))]
616    {
617        let _ = (data, max_bytes);
618        Err(CodecError::NotCompiled {
619            codec: "lerc",
620            feature: "lerc",
621        })
622    }
623}
624
625/// TIFF-flavoured LZW (MSB-first, 8-bit symbols), as used by CZI compression id 2.
626pub fn lzw_decode(data: &[u8], expected_len: usize) -> Result<Vec<u8>> {
627    #[cfg(feature = "lzw")]
628    {
629        let mut dec = weezl::decode::Decoder::with_tiff_size_switch(weezl::BitOrder::Msb, 8);
630        let mut out = LimitedWriter {
631            buf: Vec::with_capacity(expected_len.min(MAX_PREALLOC)),
632            limit: output_limit(expected_len),
633        };
634        // Reuse a small per-thread staging buffer across TIFF strips. The bounded writer
635        // still stops decompression bombs, without zeroing weezl's default 16 MiB per strip.
636        thread_local! {
637            static BUFFER: std::cell::RefCell<Vec<u8>> =
638                std::cell::RefCell::new(vec![0; 64 << 10]);
639        }
640        BUFFER
641            .with_borrow_mut(|buffer| {
642                let mut stream = dec.into_stream(&mut out);
643                stream.set_buffer(buffer);
644                stream.decode_all(data).status
645            })
646            .or_else(|e| {
647                // A strip that ends without the end-of-information code (libtiff: "Strip not
648                // terminated with EOI code") keeps what it decoded, as libtiff and tifffile do;
649                // a short result is caught by the caller's length check.
650                if e.kind() == std::io::ErrorKind::UnexpectedEof && !out.buf.is_empty() {
651                    Ok(())
652                } else {
653                    Err(e)
654                }
655            })
656            .map_err(|e| CodecError::Decode {
657                codec: "lzw",
658                detail: e.to_string(),
659            })?;
660        let out = out.buf;
661        if (expected_len != 0 && out.len() != expected_len) || out.len() >= MAX_UNSIZED_OUTPUT {
662            return Err(CodecError::SizeMismatch {
663                codec: "lzw",
664                got: out.len(),
665                expected: expected_len,
666            });
667        }
668        Ok(out)
669    }
670    #[cfg(not(feature = "lzw"))]
671    {
672        let _ = (data, expected_len);
673        Err(CodecError::NotCompiled {
674            codec: "lzw",
675            feature: "lzw",
676        })
677    }
678}
679
680/// zlib/deflate (used by some ND2 chunks and by OME-TIFF). With a nonzero `expected_len`
681/// at most that many bytes are inflated (callers only use that prefix).
682pub fn zlib_decode(data: &[u8], expected_len: usize) -> Result<Vec<u8>> {
683    #[cfg(feature = "deflate")]
684    {
685        use std::io::Read;
686        let limit = if expected_len == 0 {
687            MAX_UNSIZED_OUTPUT
688        } else {
689            expected_len
690        };
691        let mut out = Vec::with_capacity(expected_len.min(MAX_PREALLOC));
692        flate2::read::ZlibDecoder::new(data)
693            .take(limit as u64)
694            .read_to_end(&mut out)
695            .map_err(|e| CodecError::Decode {
696                codec: "zlib",
697                detail: e.to_string(),
698            })?;
699        if expected_len == 0 && out.len() >= MAX_UNSIZED_OUTPUT {
700            return Err(CodecError::SizeMismatch {
701                codec: "zlib",
702                got: out.len(),
703                expected: expected_len,
704            });
705        }
706        Ok(out)
707    }
708    #[cfg(not(feature = "deflate"))]
709    {
710        let _ = (data, expected_len);
711        Err(CodecError::NotCompiled {
712            codec: "zlib",
713            feature: "deflate",
714        })
715    }
716}
717
718/// How [`jpeg_decode_tiff`] treats the colour components of the codestream.
719#[derive(Debug, Clone, Copy, PartialEq, Eq)]
720#[non_exhaustive]
721pub enum JpegColor {
722    /// Return the components exactly as coded (no colour conversion). Used when the
723    /// container says the components already are R, G, B (e.g. TIFF photometric RGB).
724    AsCoded,
725    /// Convert three YCbCr-coded components to R, G, B (e.g. TIFF photometric YCbCr).
726    ToRgb,
727}
728
729/// What a JPEG stream's markers say about its colour coding, read up to the first scan
730/// (`SOS`) without decoding anything. See [`jpeg_markers`].
731#[derive(Debug, Clone, Default, PartialEq, Eq)]
732#[non_exhaustive]
733pub struct JpegMarkers {
734    /// An `APP0` segment starting `JFIF\0` is present (JFIF implies Y, Cb, Cr components).
735    pub jfif: bool,
736    /// The transform byte of an `APP14` `Adobe` segment: 0 = components as coded (RGB or
737    /// CMYK), 1 = YCbCr, 2 = YCCK.
738    pub adobe_transform: Option<u8>,
739    /// Component identifiers of the frame header (`SOF`), in coding order.
740    pub component_ids: Vec<u8>,
741    /// Horizontal and vertical sampling factors per component (1 = full resolution).
742    pub sampling: Vec<(u8, u8)>,
743    /// The coding process of the frame: the low nibble of its `SOF` marker (0 baseline,
744    /// 1 extended sequential, 2 progressive, 3 lossless, 9 and up arithmetic coding).
745    pub process: u8,
746    /// Sample precision of the frame in bits (8 or 12 for DCT, 2 to 16 for lossless).
747    pub precision: u8,
748}
749
750impl JpegMarkers {
751    /// The colour coding of a three-component stream by the rules libjpeg applies when the
752    /// container says nothing (JFIF, then Adobe, then component ids `R`,`G`,`B`, else
753    /// YCbCr). `None` for streams that are not three-component.
754    #[must_use]
755    pub fn coded_color(&self) -> Option<JpegColor> {
756        if self.component_ids.len() != 3 {
757            return None;
758        }
759        Some(if self.jfif {
760            JpegColor::ToRgb
761        } else if let Some(t) = self.adobe_transform {
762            if t == 0 {
763                JpegColor::AsCoded
764            } else {
765                JpegColor::ToRgb
766            }
767        } else if self.component_ids == *b"RGB" {
768            JpegColor::AsCoded
769        } else {
770            JpegColor::ToRgb
771        })
772    }
773}
774
775/// Scan the marker segments of a JPEG stream (`tables` first when given, as for a TIFF
776/// `JPEGTables` tag) up to the first `SOS`. Only segment lengths are followed; nothing is
777/// decoded. Fails when the stream does not start with `SOI` or a segment runs past the end
778/// before a frame header was seen.
779pub fn jpeg_markers(data: &[u8], tables: Option<&[u8]>) -> Result<JpegMarkers> {
780    let mut m = JpegMarkers::default();
781    let mut frame_seen = false;
782    for s in tables.into_iter().chain(std::iter::once(data)) {
783        if s.len() < 2 || s[..2] != [0xFF, 0xD8] {
784            return Err(CodecError::Decode {
785                codec: "jpeg",
786                detail: "stream lacks an SOI marker".into(),
787            });
788        }
789        let mut i = 2usize;
790        while let Some(&b) = s.get(i) {
791            if b != 0xFF {
792                break;
793            }
794            let Some(&mk) = s.get(i + 1) else { break };
795            if mk == 0xFF {
796                i += 1; // fill byte
797                continue;
798            }
799            if mk == 0xD8 || mk == 0x01 || (0xD0..=0xD7).contains(&mk) {
800                i += 2;
801                continue;
802            }
803            if mk == 0xD9 || mk == 0xDA {
804                break;
805            }
806            let Some(len) = s
807                .get(i + 2..i + 4)
808                .map(|l| usize::from(u16::from_be_bytes([l[0], l[1]])))
809            else {
810                break;
811            };
812            let Some(seg) = len.checked_sub(2).and_then(|n| s.get(i + 4..i + 4 + n)) else {
813                break;
814            };
815            match mk {
816                0xE0 if seg.starts_with(b"JFIF\0") => m.jfif = true,
817                0xEE if seg.starts_with(b"Adobe") && seg.len() >= 12 => {
818                    m.adobe_transform = Some(seg[11]);
819                }
820                0xC0..=0xCF if !matches!(mk, 0xC4 | 0xC8 | 0xCC) => {
821                    m.process = mk & 0x0F;
822                    m.precision = seg.first().copied().unwrap_or(0);
823                    if let Some(&n) = seg.get(5) {
824                        let comps = seg.get(6..6 + 3 * usize::from(n)).unwrap_or_default();
825                        m.component_ids = comps.as_chunks::<3>().0.iter().map(|c| c[0]).collect();
826                        m.sampling = comps
827                            .as_chunks::<3>()
828                            .0
829                            .iter()
830                            .map(|c| (c[1] >> 4, c[1] & 0x0F))
831                            .collect();
832                        frame_seen = true;
833                    }
834                }
835                _ => {}
836            }
837            i += 2 + len;
838        }
839    }
840    if !frame_seen {
841        return Err(CodecError::Decode {
842            codec: "jpeg",
843            detail: "no frame header (SOF) before the first scan".into(),
844        });
845    }
846    Ok(m)
847}
848
849/// Decode a JPEG chunk of a TIFF (compression 7). `tables` is the abbreviated
850/// table-specification stream of the `JPEGTables` tag (`SOI`, DQT/DHT segments, `EOI`), spliced
851/// in front of the chunk; `color` says whether the components are already R, G, B (TIFF
852/// photometric RGB, decoded as coded) or YCbCr (photometric YCbCr, converted to R, G, B).
853/// Same decoder and output conventions as [`jpeg_decode`].
854pub fn jpeg_decode_tiff(data: &[u8], tables: Option<&[u8]>, color: JpegColor) -> Result<Raster> {
855    jpeg_decode_tiff_limited(data, tables, color, MAX_UNSIZED_OUTPUT)
856}
857
858/// [`jpeg_decode_tiff`] with the frame-size bound of [`jpeg_decode_limited`].
859pub fn jpeg_decode_tiff_limited(
860    data: &[u8],
861    tables: Option<&[u8]>,
862    color: JpegColor,
863    max_bytes: usize,
864) -> Result<Raster> {
865    let stream: std::borrow::Cow<'_, [u8]> = match tables {
866        Some(t) if t.len() >= 4 && data.len() >= 2 => {
867            if t[..2] != [0xFF, 0xD8] || data[..2] != [0xFF, 0xD8] {
868                return Err(CodecError::Decode {
869                    codec: "jpeg",
870                    detail: "JPEG tables or image stream lack an SOI marker".into(),
871                });
872            }
873            let t_end = if t[t.len() - 2..] == [0xFF, 0xD9] {
874                t.len() - 2
875            } else {
876                t.len()
877            };
878            let mut v = Vec::with_capacity(t_end + data.len());
879            v.extend_from_slice(&t[..t_end]);
880            v.extend_from_slice(&data[2..]);
881            std::borrow::Cow::Owned(v)
882        }
883        _ => std::borrow::Cow::Borrowed(data),
884    };
885    jpeg_decode_with(&stream, Some(color), max_bytes.min(MAX_UNSIZED_OUTPUT), 0)
886}
887
888/// Apple/TIFF PackBits run-length decoding (TIFF compression 32773). Stops when
889/// `expected_len` bytes have been produced (0 = decode the whole input).
890pub fn packbits_decode(data: &[u8], expected_len: usize) -> Result<Vec<u8>> {
891    let mut out = Vec::with_capacity(expected_len.min(MAX_PREALLOC));
892    let mut i = 0usize;
893    while i < data.len() && (expected_len == 0 || out.len() < expected_len) {
894        let n = data[i] as i8;
895        i += 1;
896        if n >= 0 {
897            let count = n as usize + 1;
898            let end = i
899                .checked_add(count)
900                .filter(|&e| e <= data.len())
901                .ok_or_else(|| CodecError::Decode {
902                    codec: "packbits",
903                    detail: format!("literal run of {count} bytes runs past the input"),
904                })?;
905            out.extend_from_slice(&data[i..end]);
906            i = end;
907        } else if n != -128 {
908            let count = (1 - i16::from(n)) as usize;
909            let b = *data.get(i).ok_or_else(|| CodecError::Decode {
910                codec: "packbits",
911                detail: "repeat run without a value byte".into(),
912            })?;
913            i += 1;
914            out.extend(std::iter::repeat_n(b, count));
915        }
916    }
917    if expected_len != 0 {
918        out.truncate(expected_len);
919    }
920    Ok(out)
921}
922
923/// LZF decompression (the public liblzf scheme, as in Agilent `MSProfile.bin` and early
924/// Bruker TDF frames): a control byte below 32 copies that many plus one literal bytes;
925/// otherwise its top three bits are a back-reference length (an extra length byte follows
926/// when all three are set) and its low five bits, with the next byte, the distance back.
927/// `max_len` caps the output (0 = [`MAX_UNSIZED_OUTPUT`]); a stream that would produce more
928/// is an error.
929pub fn lzf_decode(data: &[u8], max_len: usize) -> Result<Vec<u8>> {
930    let limit = if max_len == 0 {
931        MAX_UNSIZED_OUTPUT
932    } else {
933        max_len
934    };
935    let bad = |detail: &str| CodecError::Decode {
936        codec: "lzf",
937        detail: detail.into(),
938    };
939    let mut out: Vec<u8> = Vec::with_capacity(limit.min(MAX_PREALLOC).min(data.len() * 4));
940    let mut i = 0usize;
941    while i < data.len() {
942        let c = usize::from(data[i]);
943        i += 1;
944        if c < 32 {
945            let n = c + 1;
946            let lit = data
947                .get(i..i + n)
948                .ok_or_else(|| bad("literal run past the end of the input"))?;
949            if out.len() + n > limit {
950                return Err(bad("output exceeds the expected size"));
951            }
952            out.extend_from_slice(lit);
953            i += n;
954        } else {
955            let mut len = c >> 5;
956            if len == 7 {
957                len += usize::from(*data.get(i).ok_or_else(|| bad("length byte missing"))?);
958                i += 1;
959            }
960            let lo = usize::from(*data.get(i).ok_or_else(|| bad("distance byte missing"))?);
961            i += 1;
962            let back = ((c & 0x1f) << 8) + lo + 1;
963            let from = out
964                .len()
965                .checked_sub(back)
966                .ok_or_else(|| bad("back-reference before the start of the output"))?;
967            let n = len + 2;
968            if out.len() + n > limit {
969                return Err(bad("output exceeds the expected size"));
970            }
971            // Overlapping copies repeat bytes written by this very reference.
972            for k in 0..n {
973                let v = out[from + k];
974                out.push(v);
975            }
976        }
977    }
978    Ok(out)
979}
980
981#[cfg(test)]
982mod tests {
983    use super::*;
984
985    #[test]
986    fn lzf_literals_and_overlapping_references() {
987        // literal "ab", then a back-reference of length 4 at distance 2 ("abab"), then "c"
988        let s = [0x01, b'a', b'b', 0x40, 0x01, 0x00, b'c'];
989        assert_eq!(lzf_decode(&s, 0).unwrap(), b"abababc");
990        assert!(lzf_decode(&s, 3).is_err(), "output cap");
991        assert!(lzf_decode(&[0x05, b'a'], 0).is_err(), "short literal");
992        assert!(
993            lzf_decode(&[0x20, 0x05], 0).is_err(),
994            "reference before start"
995        );
996        assert!(lzf_decode(&[0xE0], 0).is_err(), "missing length byte");
997    }
998
999    /// SOI, optional APP0 JFIF / APP14 Adobe, SOF0 with the given component ids (sampling of
1000    /// the first 2x2, others 1x1), SOS.
1001    fn jpeg_head(jfif: bool, adobe: Option<u8>, ids: &[u8]) -> Vec<u8> {
1002        let mut v = vec![0xFF, 0xD8];
1003        if jfif {
1004            v.extend_from_slice(&[0xFF, 0xE0, 0, 16]);
1005            v.extend_from_slice(b"JFIF\0\x01\x01\0\0\x01\0\x01\0\0");
1006        }
1007        if let Some(t) = adobe {
1008            v.extend_from_slice(&[0xFF, 0xEE, 0, 14]);
1009            v.extend_from_slice(b"Adobe\0\x64\0\0\0\0");
1010            v.push(t);
1011        }
1012        let n = u8::try_from(ids.len()).unwrap();
1013        let len = 8 + 3 * u16::from(n);
1014        v.extend_from_slice(&[0xFF, 0xC0]);
1015        v.extend_from_slice(&len.to_be_bytes());
1016        v.extend_from_slice(&[8, 0, 16, 0, 16, n]);
1017        for (k, id) in ids.iter().enumerate() {
1018            v.extend_from_slice(&[*id, if k == 0 { 0x22 } else { 0x11 }, 0]);
1019        }
1020        v.extend_from_slice(&[0xFF, 0xDA, 0, 8, 1, 1, 0, 0, 63, 0]);
1021        v
1022    }
1023
1024    #[test]
1025    fn jpeg_markers_and_libjpeg_colour_rules() {
1026        let m = jpeg_markers(&jpeg_head(true, None, &[1, 2, 3]), None).unwrap();
1027        assert!(m.jfif);
1028        assert_eq!(m.component_ids, [1, 2, 3]);
1029        assert_eq!(m.sampling, [(2, 2), (1, 1), (1, 1)]);
1030        assert_eq!(m.coded_color(), Some(JpegColor::ToRgb));
1031        // JFIF wins over R,G,B ids (libjpeg 6b)
1032        let m = jpeg_markers(&jpeg_head(true, None, b"RGB"), None).unwrap();
1033        assert_eq!(m.coded_color(), Some(JpegColor::ToRgb));
1034        // Adobe transform 0 / 1 without JFIF
1035        let m = jpeg_markers(&jpeg_head(false, Some(0), &[1, 2, 3]), None).unwrap();
1036        assert_eq!(
1037            (m.adobe_transform, m.coded_color()),
1038            (Some(0), Some(JpegColor::AsCoded))
1039        );
1040        let m = jpeg_markers(&jpeg_head(false, Some(1), b"RGB"), None).unwrap();
1041        assert_eq!(m.coded_color(), Some(JpegColor::ToRgb));
1042        // ids only
1043        let m = jpeg_markers(&jpeg_head(false, None, b"RGB"), None).unwrap();
1044        assert_eq!(m.coded_color(), Some(JpegColor::AsCoded));
1045        let m = jpeg_markers(&jpeg_head(false, None, &[0, 1, 2]), None).unwrap();
1046        assert_eq!(m.coded_color(), Some(JpegColor::ToRgb));
1047        let m = jpeg_markers(&jpeg_head(false, None, &[1]), None).unwrap();
1048        assert_eq!(m.coded_color(), None);
1049        // tables stream (JPEGTables) scanned first; the frame header is in the chunk
1050        let tables = [0xFF, 0xD8, 0xFF, 0xD9];
1051        let m = jpeg_markers(&jpeg_head(true, None, &[1, 2, 3]), Some(&tables)).unwrap();
1052        assert!(m.jfif);
1053        // malformed: no SOI, truncated segment, no frame header
1054        assert!(jpeg_markers(&[0, 1, 2], None).is_err());
1055        let mut t = jpeg_head(true, None, &[1, 2, 3]);
1056        t.truncate(12);
1057        assert!(jpeg_markers(&t, None).is_err());
1058        assert!(jpeg_markers(&[0xFF, 0xD8, 0xFF, 0xDA, 0, 2], None).is_err());
1059        assert!(jpeg_markers(&[0xFF, 0xD8, 0xFF, 0xC0, 0, 1], None).is_err());
1060    }
1061
1062    /// A lossless WebP whose Huffman code counts overflow image-webp's u16 arithmetic: an error,
1063    /// not a panic, in every build (the workspace turns off overflow checks for image-webp).
1064    #[cfg(feature = "webp")]
1065    #[test]
1066    fn webp_huffman_overflow_is_an_error() {
1067        let p = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
1068            .join("../../fuzz/known-upstream/image-webp-0.2.4-huffman-overflow.webp");
1069        let Ok(d) = std::fs::read(p) else {
1070            return;
1071        };
1072        assert!(webp_decode_limited(&d, 1 << 20).is_err());
1073    }
1074
1075    /// JPEG-LS streams whose sample errors overflow pure_jpegls' i32 arithmetic: no panic in any
1076    /// build (the workspace turns off overflow checks for pure_jpegls).
1077    #[cfg(feature = "jpegls")]
1078    #[test]
1079    fn jpegls_overflows_do_not_panic() {
1080        let dir =
1081            std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("../../fuzz/known-upstream");
1082        for name in [
1083            "pure_jpegls-2.0.0-run-mode-overflow.jls",
1084            "pure_jpegls-2.0.0-context-overflow.jls",
1085        ] {
1086            let Ok(d) = std::fs::read(dir.join(name)) else {
1087                continue;
1088            };
1089            let _ = jpegls_decode_limited(&d, 1 << 20);
1090        }
1091    }
1092
1093    /// OpenJPEG-encoded fixtures (imagecodecs 2026.8.16) and OpenJPEG's own decodes of them:
1094    /// lossless 14-bit grey (exact), a JP2-wrapped lossless RGB (exact) and an irreversible
1095    /// 9/7 + ICT RGB (within one grey level).
1096    #[cfg(feature = "jpeg2000")]
1097    #[test]
1098    fn jpeg2000_matches_openjpeg() {
1099        let dir = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/j2k");
1100        for (name, channels, bits, tol) in [
1101            ("gray16-lossless", 1, 16, 0),
1102            ("rgb8-lossless-jp2", 3, 8, 0),
1103            ("rgb8-lossy-ict", 3, 8, 1),
1104        ] {
1105            let cs = std::fs::read(dir.join(format!("{name}.j2k"))).unwrap();
1106            let want = std::fs::read(dir.join(format!("{name}.openjpeg.raw"))).unwrap();
1107            let r = jpeg2000_decode(&cs).unwrap();
1108            assert_eq!(
1109                (r.width, r.height, r.channels, r.bits_per_sample),
1110                (37, 21, channels, bits),
1111                "{name}"
1112            );
1113            assert_eq!(r.data.len(), want.len(), "{name}");
1114            if bits == 16 {
1115                assert_eq!(r.data, want, "{name}");
1116            } else {
1117                let worst = r.data.iter().zip(&want).map(|(a, b)| a.abs_diff(*b)).max();
1118                assert!(worst <= Some(tol), "{name}: off by {worst:?}");
1119            }
1120            assert!(
1121                jpeg2000_decode(&cs[..cs.len() / 3]).is_err(),
1122                "{name}: truncated"
1123            );
1124            assert!(jpeg2000_decode_limited(&cs, 100).is_err(), "{name}: limit");
1125        }
1126        assert!(jpeg2000_decode(b"not a codestream").is_err());
1127    }
1128
1129    #[test]
1130    fn hilo_roundtrip() {
1131        // samples 0x0201, 0x0403 -> lo bytes [01,03], hi bytes [02,04]
1132        assert_eq!(
1133            unshuffle_hilo(&[0x01, 0x03, 0x02, 0x04]),
1134            vec![0x01, 0x02, 0x03, 0x04]
1135        );
1136    }
1137
1138    /// 4x4 lossless (SOF3) 16-bit JPEG of `i * 1000`, written by libjpeg-turbo via imagecodecs.
1139    #[cfg(feature = "jpeg")]
1140    #[test]
1141    fn jpeg_lossless_16bit_is_exact() {
1142        let data = [
1143            0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10, 0x4a, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x00,
1144            0x00, 0x01, 0x00, 0x01, 0x00, 0x00, 0xff, 0xc3, 0x00, 0x0b, 0x10, 0x00, 0x04, 0x00,
1145            0x04, 0x01, 0x01, 0x11, 0x00, 0xff, 0xc4, 0x00, 0x16, 0x00, 0x01, 0x01, 0x01, 0x00,
1146            0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0a, 0x0c,
1147            0x10, 0xff, 0xda, 0x00, 0x08, 0x01, 0x01, 0x00, 0x01, 0x00, 0x00, 0xcf, 0xa1, 0xf4,
1148            0x3e, 0x8b, 0xe8, 0x1f, 0x43, 0xe8, 0x7d, 0x17, 0xd0, 0x3e, 0x87, 0xd0, 0xfa, 0x2f,
1149            0xa0, 0x7d, 0x0f, 0xa1, 0xf4, 0x7f, 0xff, 0xd9,
1150        ];
1151        let r = jpeg_decode(&data).unwrap();
1152        assert_eq!(
1153            (r.width, r.height, r.channels, r.bits_per_sample),
1154            (4, 4, 1, 16)
1155        );
1156        let want: Vec<u8> = (0..16u16).flat_map(|i| (i * 1000).to_le_bytes()).collect();
1157        assert_eq!(r.data, want);
1158    }
1159
1160    #[cfg(feature = "jpeg")]
1161    #[test]
1162    fn jpeg_rejects_garbage_cleanly() {
1163        assert!(jpeg_decode(&[0xFF, 0xD8, 0xFF, 0x00, 0x01]).is_err());
1164        assert!(jpeg_decode(&[]).is_err());
1165    }
1166
1167    #[test]
1168    fn packbits_spec_example() {
1169        // The example from the TIFF 6.0 specification, section 9.
1170        let packed = [
1171            0xFE, 0xAA, 0x02, 0x80, 0x00, 0x2A, 0xFD, 0xAA, 0x03, 0x80, 0x00, 0x2A, 0x22, 0xF7,
1172            0xAA,
1173        ];
1174        let expected = [
1175            0xAA, 0xAA, 0xAA, 0x80, 0x00, 0x2A, 0xAA, 0xAA, 0xAA, 0xAA, 0x80, 0x00, 0x2A, 0x22,
1176            0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA, 0xAA,
1177        ];
1178        assert_eq!(packbits_decode(&packed, 0).unwrap(), expected);
1179        assert_eq!(packbits_decode(&packed, 5).unwrap(), expected[..5]);
1180        assert!(packbits_decode(&[0x05, 0x01], 0).is_err());
1181    }
1182
1183    #[cfg(feature = "jpeg")]
1184    #[test]
1185    fn jpeg_tiff_rejects_garbage() {
1186        assert!(jpeg_decode_tiff(&[0xFF, 0xD8, 0x00, 0x01], None, JpegColor::AsCoded).is_err());
1187        assert!(
1188            jpeg_decode_tiff(
1189                &[0xFF, 0xD8, 0x00, 0x01],
1190                Some(&[0, 0, 0, 0]),
1191                JpegColor::ToRgb
1192            )
1193            .is_err()
1194        );
1195    }
1196
1197    #[test]
1198    fn zstd1_header_parses() {
1199        let (h, off) = zstd1_header(&[3, 1, 1, 0x28, 0xB5, 0x2F, 0xFD]).unwrap();
1200        assert_eq!(off, 3);
1201        assert!(h.hilo);
1202        assert_eq!(h.chunk_kind, 1);
1203    }
1204
1205    #[cfg(feature = "deflate")]
1206    #[test]
1207    fn zlib_output_is_capped_at_expected_len() {
1208        use std::io::Write;
1209        let mut enc = flate2::write::ZlibEncoder::new(Vec::new(), flate2::Compression::default());
1210        enc.write_all(&vec![0u8; 1 << 20]).unwrap();
1211        let bomb = enc.finish().unwrap();
1212        assert_eq!(zlib_decode(&bomb, 100).unwrap().len(), 100);
1213    }
1214
1215    #[cfg(feature = "lzw")]
1216    #[test]
1217    fn lzw_reused_buffer_preserves_output_and_enforces_limit() {
1218        let raw: Vec<u8> = (0..200_000).map(|i| (i % 251) as u8).collect();
1219        let packed = weezl::encode::Encoder::with_tiff_size_switch(weezl::BitOrder::Msb, 8)
1220            .encode(&raw)
1221            .unwrap();
1222        // Multiple staging-buffer fills, an overlong stream, then reuse after that error.
1223        assert_eq!(lzw_decode(&packed, raw.len()).unwrap(), raw);
1224        assert!(lzw_decode(&packed, 100).is_err());
1225        assert!(lzw_decode(&packed, raw.len() - 1).is_err());
1226        assert!(lzw_decode(&packed, raw.len() + 1).is_err());
1227        assert_eq!(lzw_decode(&packed, 0).unwrap(), raw);
1228        assert!(lzw_decode(&packed[..packed.len() / 2], raw.len()).is_err());
1229        assert_eq!(lzw_decode(&packed, raw.len()).unwrap(), raw);
1230        // A stream without its end-of-information code keeps what it decoded (libtiff and
1231        // tifffile accept such strips; the Harmony corpus has one); the length check still
1232        // rejects it when a size is expected.
1233        let head = lzw_decode(&packed[..packed.len() / 2], 0).unwrap();
1234        assert!(!head.is_empty() && raw.starts_with(&head));
1235    }
1236
1237    #[cfg(feature = "zstd")]
1238    #[test]
1239    fn zstd_fast_path_and_fallback_enforce_size() {
1240        let raw = vec![42; 4096];
1241        let packed = ruzstd::encoding::compress_to_vec(
1242            &raw[..],
1243            ruzstd::encoding::CompressionLevel::Fastest,
1244        );
1245        assert_eq!(zstd_decode(&packed, raw.len()).unwrap(), raw);
1246        assert_eq!(zstd_decode(&packed, 0).unwrap(), raw);
1247        assert!(zstd_decode(&packed, 100).is_err());
1248        assert!(zstd_decode(&packed, raw.len() + 1).is_err());
1249        // A bogus hint must not cause a hint-sized allocation in the fast path.
1250        assert!(zstd_decode(&packed, usize::MAX).is_err());
1251    }
1252
1253    #[test]
1254    fn garbage_is_a_clean_error() {
1255        let junk = [0xFFu8; 64];
1256        assert!(zstd_decode(&junk, 16).is_err());
1257        assert!(zstd1_decode(&junk, 16, 2).is_err());
1258        assert!(zlib_decode(&junk, 16).is_err());
1259        assert!(zstd1_decode(&[], 16, 2).is_err());
1260    }
1261}