Unpacking the Entropy Layer of a Wavelet Codec with libwce

Thesis

Most image codecs hide their most intellectually stimulating component—the entropy layer—behind layers of framing, rate‑control logic, and format‑specific plumbing. libwce strips away that surrounding scaffolding, presenting a minimal, std‑only Rust implementation of a Bit‑Plane Count (BPC) entropy coder. By focusing exclusively on the transformation from wavelet coefficients to a compressed bitstream, the library invites developers and researchers to explore, modify, and benchmark the heart of a wavelet codec without the distraction of ancillary code.

Key arguments

1. A single‑file, dependency‑free design clarifies intent

The entire library lives in a lone lib.rs file of roughly 500 lines. No external crates are pulled in, and the API operates purely on caller‑owned buffers. This design choice eliminates hidden state, I/O abstractions, and any reliance on a container format, allowing the reader to trace each byte from coefficient to output directly in the source.

2. BPC coding explained through groups of four coefficients

After a discrete wavelet transform, an image is represented as a 2‑D array of signed integers that cluster near zero with a long Laplacian tail. libwce groups these coefficients in fours. For each group it computes the smallest bit‑plane count (bpc) that can hold the absolute values. The bpc values are emitted first, followed by the magnitude bits of each coefficient and a sign bit when the magnitude is non‑zero. This “coeff‑major” ordering mirrors the approach used in JPEG XS and keeps the decoder logic straightforward.

3. Predictive residual coding reduces the bpc payload

Neighbouring groups tend to share similar bpc values. libwce therefore offers two predictors:

• RUNNING – a DPCM delta against the previous group’s bpc, zig‑zag mapped and Rice‑coded.
• ZERO – an unsigned residual against a user‑specified lossy_bits threshold. Each predictor can be combined with a 1‑bit‑per‑8‑group sparse‑block flag that shortcuts completely zeroed groups. The encoder evaluates all four predictor/flag combos, sweeping a Rice parameter k across seven candidates per band, and selects the combination that yields the lowest estimated cost. Though the decoded data are identical, the resulting bitstreams differ in size depending on texture, flat regions, or sub‑band sparsity.

4. Demonstrations showcase end‑to‑end usage and robustness

The repository ships three demos:

1. image_compress – builds a full codec using a Haar wavelet, libwce, and an inverse Haar for reconstruction. Four quality presets illustrate the trade‑off between compression ratio and PSNR, ranging from near‑lossless (1.5×, 49 dB) to aggressive (10×, 21 dB).
2. mode_shootout – runs a synthetic Laplacian sub‑band through every predictor/flag pair, reporting the byte count for each. The auto‑pick mode achieves the best overall ratio, demonstrating how libwce’s API makes exhaustive mode comparison trivial.
3. stream_surgery – subjects encoded streams to random bit flips, byte scrambles, truncations, and crafted “unary bomb” headers. In every case the decoder returns cleanly without crashes, proving the library’s defensive parsing.

5. The library is intentionally limited to the entropy stage

By omitting container formats, rate control, and higher‑level orchestration, libwce does not claim to be a drop‑in replacement for a full codec. Instead, it serves as a pedagogical tool: developers can plug the entropy layer into their own pipelines, replace the wavelet transform, or experiment with alternative quantization strategies while keeping the core bit‑plane logic untouched.

Implications

• Educational value – Students of image compression can study a complete entropy coder without wading through thousands of lines of ancillary code. The clear separation mirrors the classic textbook model of “transform → quantization → entropy coding.”
• Research agility – Researchers testing new predictors, context models, or adaptive Rice parameters can iterate quickly, as the library’s API accepts custom options per encode call.
• Portability – Because libwce relies only on the Rust standard library, it compiles for bare‑metal targets, WebAssembly, and embedded environments where a full codec would be impractical.
• Open‑source transparency – The source is hosted at github.com/yogthos/libwce, where the author emphasizes readability and includes extensive comments that explain the mathematical reasoning behind each step.

Counter‑perspectives

Critics may argue that a library focused solely on entropy coding is of limited practical use, given that production codecs require sophisticated rate‑control loops and container specifications. While that is true for deployment‑scale applications, the author’s intent is not to provide a ready‑made codec but to expose the conceptual core of wavelet‑based entropy coding. For developers who need a full solution, libwce can be integrated into larger frameworks such as AVIF or JPEG XS implementations, supplying a clean, well‑tested entropy module.

---

The article reflects on the design choices behind libwce, explains the BPC entropy mechanism, and highlights the practical experiments enabled by a stripped‑down implementation.