Skip to content

lumen-image: a baseline JPEG decoder (#197) - #273

Draft
flyingrobots wants to merge 1 commit into
mainfrom
feat/lumen-image-jpeg
Draft

flyingrobots wants to merge 1 commit into
mainfrom
feat/lumen-image-jpeg

Conversation

@flyingrobots

Copy link
Copy Markdown
Owner

Closes #197

Draft: work in progress. The description is rewritten with the acceptance evidence and the test plan before this leaves draft.

ADR 0012 puts image decoding in a dependency-free, float-free workspace
crate inside the deterministic core. This creates it with the minimum the
gates need: a manifest that inherits the workspace lints, a root that
denies float arithmetic, and `lumen` declaring the dependency so the
nondeterminism gate derives the crate as deterministic. The JPEG decoder
follows in its own module tree, `jpeg/`.

#195 (inflate) creates the same crate in parallel; the
two meet in Cargo.toml, Cargo.lock, lib.rs and the changelog.

Issue: #197
Agent-Session: A63E8AB9-5A21-43EE-8F27-DF87888B5CE7
Agent-Tool: Claude Code
@coderabbitai

coderabbitai Bot commented Nov 16, 2026

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@flyingrobots

Copy link
Copy Markdown
Owner Author

Handoff (paused)

Paused on the coordinator's instruction. State of the branch feat/lumen-image-jpeg (worktree ~/git/lumen-197): one pushed commit, 2204236; the worktree is clean, nothing is uncommitted. No container run was started and none is in flight; nothing here has been built or tested yet, in the container or by CI's result being read.

Done

  • Read the brief with its addenda, the issue, CONTRIBUTING.md, ADR 0012, decision 04 and the Rust, testing, workflow, locks and resources standards.
  • Commit 2204236: the crate skeleton (crates/lumen-image/Cargo.toml inheriting the workspace lints, src/lib.rs with the crate docs and #![deny(clippy::float_arithmetic)], src/jpeg.rs holding only JPEG_DECODE_ID = "lumen-jpeg-decode/1"), the workspace member and lumen-image workspace dependency, lumen declaring it (so xtask nondeterminism derives the crate as deterministic), Cargo.lock edited by hand, and a work-in-progress changelog line.
  • Looked at lumen-image: an inflate (zlib) decoder #195's worktree once, read-only: it had no lumen-image files and no commit yet, so there was nothing to match. The names here are my own; the comparison must be repeated before this leaves draft.
  • Host tools found: cjpeg, djpeg, jpegtran (libjpeg-turbo 3.2.1, Homebrew), ffmpeg, sips. No PIL.
  • The albedo map is SOF0, 3 components, JFIF, 2 quantization and 4 Huffman tables, one scan (from djpeg -verbose; its sampling factors were not yet read). Roughness and metallic are 1-component SOF0.

Not done

Everything else: the decoder, its tests, the corpus, the documentation, the measurement record, the gate. No acceptance item is met.

Design intended (not yet in code; for whoever resumes to confirm or change)

  • IDCT: the Loeffler-Ligtenberg-Moschytz 11-multiplication transform with 13-bit constants (2446, 3196, 4433, 6270, 7373, 9633, 12299, 15137, 16069, 16819, 20995, 25172), columns first with (w + 1024) >> 11, then rows with (w + 131072) >> 18, sample clamp(s + 128, 0, 255), all in exact 64-bit integers (32 bits can overflow in the second pass on hostile coefficients). This is the arithmetic libjpeg calls "islow".
  • Upsampling: the triangle filter. 4:2:2: (3a + b + 1) >> 2 towards the left neighbour and + 2 towards the right; 4:2:0: v = 3*near + far vertically, then (3v + v' + 8) >> 4 left and + 7 right; a component plane is ceil(W*H_c/Hmax) by ceil(H*V_c/Vmax) with edge replication. Known difference from libjpeg-turbo to state: for a chroma plane one sample wide (image width 1 or 2) libjpeg-turbo reads a padding sample.
  • Colour: 16-bit fixed point, constants 91881, 116130, 22554, 46802, + 32768, floor shift, clamp. Grey is expanded to R = G = B.
  • Reference decoder: djpeg (no colour management) to PPM, committed beside each corpus file. Because the three rules above are the ones libjpeg-turbo documents for its defaults, the bound I intended to state before measuring is 0 per channel, for images wider than 2 pixels; this was not measured.
  • Accepted sampling: three components with luma 1x1, 2x1 or 2x2 and both chroma 1x1; one component with any factors, treated as 1x1. Scans: interleaved, non-interleaved and partly interleaved, each component in exactly one scan; tables latched at each SOS.
  • Totality: a DC value outside -2048..=2047, a DC category over 11 and an AC size over 10 are typed errors, which bounds every intermediate value.
  • Errors: a struct JpegError { kind, offset } with a non-exhaustive JpegErrorKind and an Unsupported enum naming each refused feature.
  • IEEE 1180 oracle: exact arithmetic in the basis 1, 2cos(k*pi/16) for k = 1..7 with integer coefficients (products by 2cos a * 2cos b = 2cos(a+b) + 2cos(a-b)), so ties are detected exactly and other values are rounded from a 2^-59 evaluation that fails loudly if it is ever too close to a half. The standard's random generator is exact in integers.
  • SHA-256 in tests: the crate may not depend on lumen, so the tests would carry their own small SHA-256 checked against a published vector.

Open questions for the coordinator

  1. SOF1 (extended sequential, 8-bit, Huffman) decodes by the same arithmetic as baseline. I intended to refuse it by name, as the issue says baseline; confirm.
  2. Bytes after EOI: I intended to ignore them and say so. Confirm, or refuse them.
  3. Three components whose ids are R, G, B with neither a JFIF nor an Adobe segment: libjpeg reads these as RGB. I intended to refuse them by name instead of converting them as YCbCr.
  4. The memory bound of acceptance item 4 cannot be asserted in a test without an allocator hook, which needs unsafe (forbidden). I intended to derive it (output plus component planes, about 6*W*H bytes for 4:4:4) and measure peak resident memory of a small example program in the container.

Exact next step

Write crates/lumen-image/src/jpeg/ (error.rs, reader.rs, huffman.rs, bits.rs, frame.rs, segments.rs, scan.rs, idct.rs, upsample.rs, color.rs, plane.rs, decoder.rs), then the IEEE 1180 unit test, then build the corpus.

Commands I was about to run

D=~/git/devcontainers/bin/devrun
python3 $D lumen ~/git/lumen-197 --worktree --fetch --cpus 4 --memory 8g --timeout 2400 -- cargo clippy --workspace --all-targets --locked -- -D warnings
python3 $D lumen ~/git/lumen-197 --worktree --cpus 4 --memory 8g --timeout 2400 -- cargo test --locked -p lumen-image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

lumen-image: a baseline JPEG decoder

1 participant