//! Byte-stream and bi-level image codecs that PDF, PostScript and TIFF share. //! //! - [`lzw`]: variable-width LZW, 9 to 12 bits, most significant bit first (PDF `LZWDecode`, //! TIFF compression 5), with or without the early code-width change. //! - [`ascii85`], [`asciihex`], [`runlength`]: the PostScript and PDF text and run-length //! encodings (`ASCII85Decode`, `ASCIIHexDecode`, `RunLengthDecode`; PackBits). //! - [`predictor`]: TIFF horizontal differencing and the PNG row filters. //! - [`ccitt`]: CCITT Group 3 and Group 4 fax decoding, bounded, and Group 4 encoding. //! - [`jbig2`]: JBIG2 decoding through `hayro-jbig2`, bounded, and lossless encoding (generic //! regions, symbol dictionaries, a dictionary shared by a group of images). //! //! The crate knows no container: a caller hands it bytes and parameters. A PDF `/Filter` chain //! (order, limits across stages, Flate) is `craft_pdf::filters`, built on this crate. //! //! Every decoder is bounded by a caller-supplied output limit and never panics on malformed //! input. A decoder that fails returns what it decoded before the damage ([`Failure`]), so a //! caller can choose to keep it. CCITT and JBIG2 decoding spend from an allowance the caller //! shares across a run of images ([`pay`]); neither decodes without one: //! //! ```compile_fail //! let _ = craft_stream_codecs::decode_jbig2(&[], None, 1, 1, 1 << 20); //! ``` //! //! ```compile_fail //! let _ = craft_stream_codecs::decode_ccitt(&[], &craft_stream_codecs::CcittParams::default(), 1); //! ``` //! //! ``` //! let mut work = 1 << 20; //! assert!(craft_stream_codecs::decode_jbig2_within(&[], None, 1, 1, 1 << 20, &mut work).is_err()); //! let p = craft_stream_codecs::CcittParams { columns: 8, ..Default::default() }; //! assert!(craft_stream_codecs::decode_ccitt_within(&[], &p, 1, &mut work).is_ok()); //! ``` #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] pub mod ascii85; pub mod asciihex; pub mod ccitt; pub mod jbig2; pub mod lzw; mod mq; pub mod predictor; pub mod runlength; pub use ccitt::{CcittParams, MAX_CCITT_COLUMNS, MAX_G4_COLUMNS, decode_ccitt_within, encode_g4}; pub use jbig2::{MAX_JBIG2_COLUMNS, MAX_JBIG2_PIXELS, SharedJbig2, decode_jbig2_within, encode_jbig2, encode_jbig2_generic, encode_jbig2_shared}; /// Parameters of the predictors and of LZW, as a PDF `/DecodeParms` dictionary gives them /// (ISO 32000-2 Tables 8–9); TIFF's `Predictor`, `SamplesPerPixel`, `BitsPerSample` and /// `ImageWidth` map onto the same four. #[derive(Clone, Debug, PartialEq)] pub struct Params { /// 1 = none, 2 = TIFF predictor 2, 10–15 = PNG predictors. pub predictor: i64, pub colors: i64, pub bits_per_component: i64, pub columns: i64, /// LZW only: 1 (default) switches code width one code early, 0 does not. pub early_change: i64, } impl Default for Params { fn default() -> Self { Params { predictor: 1, colors: 1, bits_per_component: 8, columns: 1, early_change: 1 } } } /// Errors from decoding or encoding. #[derive(Debug, thiserror::Error)] pub enum CodecError { /// `filter` names the codec, as PDF names its filter (`LZWDecode`, `CCITTFaxDecode`, …). #[error("{filter}: corrupt data: {detail}")] Corrupt { filter: &'static str, detail: String }, #[error("decoded output exceeds the limit of {0} bytes")] LimitExceeded(usize), #[error("unsupported filter: {0}")] Unsupported(String), /// A run of images has nothing left to spend ([`pay`]). #[error("more image decoding than one operation may do")] Spent, } /// A decoder failure carrying whatever was decoded before the error. pub struct Failure { pub error: CodecError, pub partial: Vec, /// Bytes decoded on the way that `partial` doesn't hold: they took as long. pub discarded: usize, } impl Failure { pub fn corrupt(filter: &'static str, detail: impl Into, partial: Vec) -> Self { Failure { error: CodecError::Corrupt { filter, detail: detail.into() }, partial, discarded: 0 } } pub fn limit(max: usize) -> Self { Failure { error: CodecError::LimitExceeded(max), partial: Vec::new(), discarded: 0 } } } /// What a byte-stream decoder returns: the decoded bytes, or the failure with its partial output. pub type Step = Result, Failure>; /// Takes `steps` from `work`, what a run of images may still cost. What it can't pay for spends /// all of it. pub fn pay(work: &mut u64, steps: u64) -> Result<(), CodecError> { match work.checked_sub(steps) { Some(left) => { *work = left; Ok(()) } None => { *work = 0; Err(CodecError::Spent) } } } /// PDF and PostScript white-space characters (ISO 32000-2 Table 1). pub fn is_pdf_whitespace(b: u8) -> bool { matches!(b, 0 | 9 | 10 | 12 | 13 | 32) }