3.5 KiB
MapLibreParticle QBIN V3 Decoder 与 Block Geometry 实施决策 v1
1. 结论
STEP-086 将 QBV3 / version 3 作为新的压缩天气场容器格式接入 MapLibre Native。生产 Decoder 固定使用 16×16 Block Geometry，不在运行时尝试 16×16 / 32×32 双解码，也不通过启发式猜测块尺寸。
既有 QBV2 解码链继续保留。EncodedFieldIngress 依据 magic 显式分流：QBV2 → QbinV2Decoder，QBV3 → QbinV3Decoder；version 由对应 Decoder 严格校验。解码完成后继续统一进入 FieldProfileValidator，不改变既有 profile contract 分层。
2. Block Geometry 决策依据
使用仓库既有 Current / Rain / Wave / Wind 四类真实 Golden 数据，共 T0/T1 8 帧，按 v2.2 冻结稿规则实现确定性的 C++ benchmark encoder/decoder，对 16×16 与 32×32 做相同输入对比。
| 指标 | 16×16 | 32×32 | 结论 |
|---|---|---|---|
| 数值 payload 总字节 | 2,470,419 | 2,514,288 | 32×32 增加 43,869 字节，约 +1.7758% |
| 总 block 数 | 22,704 | 5,984 | 32×32 block 更少 |
| 非空 block 数 | 19,120 | 5,190 | 32×32 block 更少 |
| C++ encode 总时间 | 218.713 ms | 200.101 ms | 32×32 约快 8.5% |
| C++ decode 总时间 | 104.121 ms | 101.451 ms | 32×32 约快 2.6% |
8 帧合计 decode 差异约 2.67 ms，平均每帧约 0.33 ms；相比之下，32×32 对 payload 尺寸有稳定负收益，Rain 两帧的增幅尤其明显。QBIN V3 的核心目标之一是降低网络、缓存和跨 RN/Native 传输成本，因此选择 16×16。
此决定同时冻结：
QbinV3Decoder::BlockWidth = 16；QbinV3Decoder::BlockHeight = 16；- Golden Fixture manifest 中 blockWidth/blockHeight 均为 16；
- 后续生产 Writer 必须输出相同 ABI，不得自行改为 32×32。
3. Decoder 责任边界
QbinV3Decoder 只负责把已取得的 QBV3 二进制解码成现有 DecodedFieldFrame。它不负责 Weather provider、HTTP、下载、重试、缓存、manifest 获取、路线调度或 React 业务逻辑。
实现包含：
- 固定 Header / Descriptor 布局与 little-endian 读取；
- file size、plane count、cell count、decoded bytes 等硬上限；
- CRC32 校验；
- canonical descriptor 排序、唯一键、16-byte packing 与 padding 校验；
- VALIDITY 唯一性、长度、unused bits 校验；
- Numeric dtype 约束与 all-invalid 零长度编码；
- 16×16 block 的 Predictor + ZigZag + Rice 解码；
- Direction 的 canonical scale、环形预测与 half-circle tie 规则；
- 非法 Rice-K、截断、额外字节、非零 bit padding、残差越界等 fail-closed；
- 解码后构造既有
DecodedFieldFrame，继续使用既有 FieldProfileValidator。
4. Golden Fixtures
正式 QBIN V3 Golden Fixture 位于：
integration/react-native/MapLibreParticleRNTestHost/assets/qbin-v3-golden/
覆盖：
- current：T0 / T1，513×513；
- rain：T0 / T1，513×513；
- wave：T0 / T1，513×769；
- wind：T0 / T1，513×769。
manifest.json 固定每个文件的 bytes、SHA-256、width、height 以及 16×16 Block Geometry。校验脚本为：
integration/react-native/MapLibreParticleRNTestHost/scripts/verify-qbin-v3-golden-fixtures.py
8 个 V3 fixture 已与对应 V2 canonical raw 解码结果做逐 plane / validity byte-for-byte 对比，结果一致。
5. 兼容性与版本
本次不移除 QBV2，不改变 RN submitEncodedField 公共调用形态，不把 V3 压缩细节暴露给 JS/TS。Native / RN 发行版本统一升级为 13.4.1-particle.9。