# craft-stream-codecs

Byte-stream and bi-level image codecs that PDF, PostScript and TIFF share. The crate knows no
container: a caller hands it bytes and parameters. A PDF `/Filter` chain (stage order, limits
across stages, Flate, accounting) belongs to `craft-pdf`, which builds on this crate; a TIFF
reader can use the same LZW, predictor, CCITT and JBIG2 code.

- **Licence:** MIT OR Apache-2.0. Written from ISO 32000-2 §7.4, TIFF 6.0 §14 (predictor 2) and
  RFC 2083 §6 (PNG filters). CCITT Group 4 encoding (ITU-T T.6) is the `fax` crate's (MIT). CCITT
  decoding (T.4 and T.6) is `hayro-ccitt`'s (MIT OR Apache-2.0), bounded here: this crate has
  no CCITT decoder of its own, and no JBIG2 decoder (that is `hayro-jbig2`, which the tests
  read the encoder's output back with). JBIG2 encoding
  is written from the public ISO/IEC 14492 Final Committee Draft (WG1 N1359, 1999); Annex H.2
  checks the arithmetic coder byte for byte.
- No `unsafe`. Never panics on input.
- From PdfCraft's `pdfcraft-filters` crate (revision `80e26e674d1aa33078e83c8139875047f3289eb6`):
  its codec modules, moved whole. Its filter chain and Flate stay with the PDF code.

## API

```rust
pub struct Params { predictor, colors, bits_per_component, columns, early_change }  // i64s; Default = 1, 1, 8, 1, 1
pub enum CodecError { Corrupt { filter, detail }, LimitExceeded(usize), Unsupported(String), Spent }
pub struct Failure { error, partial, discarded }   // what a decoder decoded before it failed
pub type Step = Result<Vec<u8>, Failure>;
pay(work: &mut u64, steps) -> Result<(), CodecError>   // an allowance shared across a run of images

lzw::decode(data, early_change, max) -> Step;        lzw::encode(data, early_change) -> Vec<u8>
ascii85::decode(data, max) -> Step;                  ascii85::encode(data) -> Vec<u8>
asciihex::decode(data, max) -> Step;                 asciihex::encode(data) -> Vec<u8>
runlength::decode(data, max) -> Step;                runlength::encode(data) -> Vec<u8>
predictor::decode(&params, data, name, rows) -> Step; predictor::encode(&params, data) -> Result<Vec<u8>, CodecError>

pub struct CcittParams { k, columns, rows, end_of_line, encoded_byte_align, end_of_block, black_is_1 }
decode_ccitt_within(data, &params, max_rows, work: &mut u64) -> Result<Vec<u8>, CodecError>
encode_g4(data, columns, rows) -> Result<Vec<u8>, CodecError>

encode_jbig2_generic(data, columns, rows) -> Result<Vec<u8>, CodecError>
encode_jbig2(data, columns, rows) -> Result<Vec<u8>, CodecError>
encode_jbig2_shared(&[(data, columns, rows)]) -> Result<Option<SharedJbig2>, CodecError>
```

`max` bounds a decoder's output and gives `LimitExceeded`. `Corrupt` names the codec in `filter`
by its PDF filter name. Bi-level images are rows of 1-bit samples, most significant bit first,
each row on a new byte.

## Behaviour

| Codec | Decode | Encode |
|---|---|---|
| LZW | 9–12-bit MSB-first codes, clear (256), end (257), early change on or off; a missing end code or initial clear is tolerated; a full table stops growing | greedy, leading clear, clear when the table fills, end code |
| Predictors | 2 = TIFF (1/2/4/8/16 bits per component), 10–15 = PNG with per-row tags 0–4; partial final rows decoded; bad parameters or tags are `Corrupt`; with `rows`, data that is exactly that many rows without tag bytes is taken as the samples and reported as damage | 2, 10 None, 11 Sub, 12 Up, 13 Average, 14 Paeth, 15 per-row optimum |
| ASCIIHex | white space ignored, odd digit padded with 0, `>` ends (optional), other characters are `Corrupt` | upper case, newline every 64 digits, `>` |
| ASCII85 | `<~` prefix, `z`, white space, `~>` (or bare `~`, or none), final partial group; `z` inside a group, a 1-character final group, overflow or bad characters are `Corrupt` | `z` for zero groups, newline every 75 characters, `~>` |
| RunLength | 0–127 literal, 129–255 repeat, 128 ends (optional); a truncated run is `Corrupt` | runs of 2 or more repeat, literals up to 128, 128 |
| CCITT fax | Group 3 (1-D and 2-D) and Group 4 through `hayro-ccitt`, as rows of 1-bit samples, black 0 unless `black_is_1`, at most `max_rows` rows (fewer with `rows`), the rows before any damage, up to `MAX_CCITT_COLUMNS` (1,048,576) samples a row; the rows are paid for from `work` before they are decoded | `encode_g4`: Group 4 with an end-of-block mark, 0 bits coded black; up to `MAX_G4_COLUMNS` (32,767) samples a row |
| JBIG2 | not here: `hayro-jbig2` | `encode_jbig2_generic`: one immediate lossless generic region (template 0, typical prediction, MQ coder). `encode_jbig2`: the smaller of that and symbol coding (exact copies only, so the stream decodes to the same bits). `encode_jbig2_shared`: a group of images sharing one symbol dictionary (the PDF `/JBIG2Globals` data) |

The limits of the JBIG2 encoder (symbols per plan, instances per text region, marks, runs) are
those `hayro-jbig2` reads back; they are documented on the constants in `src/jbig2/symbols.rs`.

## Tests

- Unit tests per codec with hand-computed vectors (the ISO 32000-2 LZW example, PNG and TIFF rows).
- LZW is cross-checked against `weezl` (dev-dependency) in both directions for both early-change settings.
- `ccitt.rs`: decoding gives back the rows `encode_g4` was given; Group 3 layouts over seeded
  pictures; Group 4 output decoded by `hayro-ccitt` matches the input bits, with property tests
  over bitmaps of noise and of runs; any input returns rather than panics.
- `mq.rs`: the arithmetic coder reproduces Annex H.2's 30 bytes from its 256 decisions.
- `jbig2.rs`, `jbig2/symbols.rs`: output decoded by `hayro-jbig2` matches the input bits for
  every coding, plan and strip size, with property tests; size and limit refusals.

## Not here

A bounded JBIG2 decoding entry (`decode_jbig2_within` in PdfCraft): it needs the caller-owned
work allowance PdfCraft added to its `hayro-jbig2` (`Image::decode_within`, `charge_reading`),
which the copy vendored here does not have yet. Flate (a container's choice of zlib settings and tolerances), DCT and JPEG 2000, CCITT Group 3
encoding.