Libwce：独立呈现的小波编解码器熵层

背景

大多数我们熟知的图像编解码器，如 JPEG、JPEG 2000、JPEG XS 和 WebP，其结构往往像“千层蛋糕”：顶层是变换层，底层是熵编码层，中间漂浮着率控制模块，最外层则包裹着元数据层。然而，真正有趣的逻辑细节往往被大量的框架代码、配置文件解析器以及标准基础设施所掩盖。如果你只想直观地观察小波系数是如何转化为比特流的，通常不得不深入这些编解码器的底层核心。

为了解决这一痛点，开发者创建了 libwce。这是一个极简主义的实现，仅由单个 lib.rs 文件组成，代码量约为 500 行。它剥离了所有样板代码和外部依赖，完全基于 Rust 标准库，仅实现了一个专利清洁（patent-clean）的位平面计数（Bit-Plane Count, BPC）风格熵层。其设计灵感源自 JPEG XS，旨在让研究者能够直接观察和理解小波变换后的数据压缩过程，而无需被庞大的编解码器框架所困扰。

核心内容

BPC 编码原理简述

原始视频流本质上是像素网格，相邻像素在颜色和亮度上具有高度相似性。逐个存储每个像素会浪费大量带宽，因为数据中存在大量重复信息。编解码器通过将图像从空间域转换到频率域来压缩这些信息。

• 传统方法（如 JPEG）：将图像切分成方块并应用离散余弦变换（DCT），这导致了众所周知的块状伪影。
• 小波方法：作为一种更新的方法，小波变换一次性应用于整个图像，将信号分解为低频结构数据和高频细节数据，并跨越多个尺度。

经过小波变换后，得到的二维数组由有符号整数系数组成。其中大多数系数接近于零，呈现出长尾的拉普拉斯分布。熵层的任务就是将这些数组压缩为少量显著比特。

BPC 编码的具体实现

libwce 采用每四个系数为一组进行处理：

1. 确定 BPC 值：对于每组系数，确定最小的位平面计数（bpc），使得组内所有系数都能被容纳。BPC 代表了一个索引值，该索引之上的所有系数比特均为零。
2. 数据输出顺序：
   • 首先将所有组的 bpc 值写入比特流。
   • 随后，对于每组，按系数主要顺序（coeff-major）输出四个系数。
   • 每个系数先输出幅度比特，若系数非零，紧接着输出一个符号比特。

预测与压缩策略

为了进一步压缩 bpc 值，libwce 利用了相邻组通常具有相似大小的特性。与其直接写入原始的 6 位 bpc 数值，不如基于邻居进行估计并写入微小的残差。

库中提供了两种预测器，可结合稀疏块标志（sparse-block flag）使用：

• RUNNING (DPCM)：相对于前一组 bpc 的差分预测，经过锯齿形映射并采用 Rice 编码。
• ZERO：针对 lossy_bits 的无符号残差预测。
• 稀疏块标志：1 位/每 8 组，用于短路处理全零区域（all-deadzone blocks）。

这形成了四种预测器与标志的组合。编码器在每个组合内对 Rice 编码参数 k 进行七种值的单遍成本搜索，以选择最佳配置。虽然所有组合解码结果相同，但生成的比特流类型不同，分别适用于纹理区域、平坦部分或主要为零的子带等不同像素分布。

使用示例

该库是无状态的，仅通过调用者提供的缓冲区工作，不使用 I/O 或隐藏的全局变量。以下是一个子带解码的完整示例：

let mut coeffs = vec![0i32; N];
let lossy_bits = decode(buf, &mut coeffs).unwrap();
dequantize_optimal(&mut coeffs, lossy_bits, scale_b);

端到端图像压缩演示

仓库中的 image_compress 演示构建了一个完整的编解码器，流程为：Haar 小波输入 -> libwce 中间处理 -> 逆 Haar 输出。该演示包含四个质量预设，展示了压缩率与峰值信噪比（PSNR）之间的权衡：

| 预设 | 子带 (LL/HL/LH/HH) lossy_bits | 载荷 (bytes) | .wce 文件大小 (bytes) | 压缩比 | PSNR | | :--- | :--- | :--- | :--- | :--- | :--- | | near-lossless | 2 / 4 / 4 / 5 | 146537 | 146597 | 1.52x | 49.06 dB | | balanced | 4 / 6 / 6 / 7 | 92631 | 92691 | 2.40x | 37.54 dB | | aggressive | 6 / 8 / 8 / 9 | 49516 | 49576 | 4.48x | 28.79 dB | | very lossy | 8 / 10 / 10 / 11 | 21923 | 21983 | 10.11x | 21.62 dB |

• 质量退化观察：
  • q1 (near-lossless)：图像与原始图像难以区分。
  • q2 (balanced)：平坦区域出现轻微平滑。
  • q3 (aggressive)：边缘开始出现明显的小波振铃效应。
  • q4 (very lossy)：呈现出可识别的小波块状效应，虽然看起来有些怪异（eldritch），但仍具可读性。

整个包含离散小波变换（DWT）、子带编码、量化和容器写入的过程，代码量不足 500 行。

模式对比与鲁棒性测试

• 模式对比 (mode_shootout)：该演示将合成拉普拉斯子带通过所有预测器与标志组合，并显示获胜者。结果显示，自动选择模式（auto-pick）比强制最佳模式（best forced）节省了 40 字节，主要得益于更优的 Rice k 值选择。这证明了 libwce API 使得在完整编解码器中难以进行的内部仪器调整和率控制禁用变得极其简单。
• 鲁棒性测试 (stream_surgery)：该演示对编码比特流进行了 256 次随机比特翻转、256 次随机字节乱序、300 个覆盖所有 4 字节前缀的截断点测试，以及包括全一“一元炸弹”和伪造坏头部的对抗性案例测试。结果显示，所有案例均成功解码，无挂起或崩溃现象。

关键要点

• 极简主义设计：libwce 仅包含 500 行 Rust 代码，无外部依赖，专注于展示小波编解码器中最具概念吸引力的熵层。
• 专利清洁：实现了 BPC 风格熵层，灵感来自 JPEG XS，但避免了专利问题，适合学习和研究。
• 灵活的预测机制：支持 RUNNING (DPCM) 和 ZERO 两种预测器，结合稀疏块标志，通过单遍成本搜索自动选择最优 Rice 编码参数。
• 无状态 API：库完全基于调用者提供的缓冲区，不依赖 I/O 或全局状态，易于集成和测试。
• 全面的演示套件：
  • image_compress：展示端到端压缩及不同质量预设下的视觉效果。
  • mode_shootout：自动化对比不同预测模式的压缩效率。
  • stream_surgery：验证编解码器在比特错误、截断和对抗性输入下的鲁棒性。
• 教育价值