vtracer-bench 盲保真度基准：用 PSNR、SSIM 与缺失区块检测三轴合成单一保真度评分

• 图像处理
• 图形学
• CLI

导读：本文完整解析 vtracer 工作区中 crates/vtracer-bench 这一「盲保真度」基准工具的设计思想、数学公式、CLI 与 Rust 库用法。它不关心重建结果是如何生成的（任何 tracer、任何格式、任何渲染器），只要求你把矢量输出渲染成与原图同尺寸的像素，即可得到[0, 1] 区间内的单一保真度评分。读完本文，你将掌握三个互补度量轴的原理（PSNR、SSIM/DSSIM、缺失区块检测）、几何均值合成逻辑、命令行参数与库 API，并理解其如何规避传统指标被描摹器「钻空子」的盲区。

1. 为什么还需要另一个指标

每一个经典指标都有盲区，而矢量描摹器恰恰会系统性地利用这些盲区：

• PSNR高估了人眼看不见的噪点，同时低估了小而重要的区域——一个丢掉眼睛但完美还原背景的描摹结果，可以拿到很高的 PSNR。
• SSIM对感知质量跟踪得很好，但它是全局平均：一个完全丢失的小区域几乎不影响分数。
• 两者都无法区分一千个散布的 ±1 像素误差与一个总质量相同的连贯缺失区块——而后者才是真正需要关注的失败模式。

vtracer-bench同时度量三个轴，并以一种「没有单一盲区能够存活」的方式将它们合成：

fidelity = ( psnr¹ · ssim² · patch¹ ) ^ (1/4)—— 一个加权几何均值。用几何而非算术均值，意味着任何一个轴崩塌都会把综合分拖下来：缺失的面部区域无法隐藏在优秀的全局 PSNR 背后。SSIM 承载双倍权重，因为它对视觉精度的跟踪效果最好，也是对「有瑕疵的源图」最稳健的轴。对应权重常量定义在 crates/vtracer-bench/src/lib.rs 中：W_PSNR = 1.0、W_SSIM = 2.0、W_PATCH = 1.0，且均为pub公开常量，可被外部引用。

2. 三个度量轴

2.1 psnr —— 无参数的压缩映射

映射公式1 − log(1+rmse)/log(256)只锚定在 8 位图像天然存在的两个误差尺度上，除此之外没有任何人为设定：

• rmse = 255（满量程——噪声与随机图像不可区分）→0
• rmse ≤ 1（量化步长——8 位图像几乎无法表示的误差）→ 饱和为1

对于rmse ≫ 1的情况，它等价于psnr / 48.13 dB，即仍然与分贝呈线性关系，但不需要手工挑选锚定常量。实现上，PSNR 与 RMSE 以及坏像素二值化在同一趟遍历中完成（见 crates/vtracer-bench/src/lib.rs），RMSE 按√(sse / (w·h·3))计算，PSNR 取20·log10(255 / rmse)。

2.2 ssim —— 感知结构

dssim-core计算多尺度结构不相似度d = 1/SSIM − 1；子分数直接取SSIM = 1/(1+d)，这本身就是一个自然的 0..1 值。人眼察觉不到的差异，无论覆盖多少像素，都计为约 1。底层实现封装在 crates/vtracer-bench/src/lib.rs 的dssim_score中：它把交错的 RGB8 缓冲转换为rgb::RGB<u8>像素序列，再调用dssim_core::Dssim::new()与compare得到原始 DSSIM 值。注意 crates/vtracer-bench/Cargo.toml 中dssim-core被锁定在~3.4（注释说明这是唯一能通过无threads回退编译的版本，3.3 与 3.5 均编译失败）。

2.3 patch —— 缺失区块检测器

这是 PSNR 和 SSIM 共同缺失的轴，实现分为四步（核心逻辑见 crates/vtracer-bench/src/lib.rs）：

1. 当且仅当该像素到原图的 RGB 欧氏距离超过--thresh（默认 24，即约每通道 14）时，该像素标记为bad。
2. 对坏像素掩码做开运算（一轮 4 连通腐蚀 + 膨胀）。轻微模糊或被重压缩的源图会使每条边缘偏移，并在所有边界处画上 ≤2 px 的细丝状误差；这些在开运算下消失，而真正的缺失区块则幸存下来——这正是该基准对轻度压缩或模糊原图具有容忍性的原因。源码中腐蚀与膨胀均为单轮 4 连通邻居判断（lib.rs），随后将开运算结果交给visioncortex::BinaryImage::to_clusters(false)做 4 连通聚类。
3. 对幸存掩码做 4 连通聚类。设各聚类面积为aᵢ，patch mass为√(Σ aᵢ²)——一个平方和，因此单个连贯块在总面积相等时压过任意数量的散布噪点。FidelityReport同时暴露clusters（聚类数）与largest（最大聚类面积，px）供诊断。
4. 令P = patch mass / (w·h)，子分数取2^(−P/0.005)：一个占图像质量 0.5% 的连贯块会把分数减半，而散布噪点几乎不影响它。常量PATCH_HALF = 0.005定义于 crates/vtracer-bench/src/lib.rs。

这一步的实现细节在测试中有直接验证（见 crates/vtracer-bench/src/lib.rs）：coherent_patch_scores_below_scattered_dust构造了像素数量相同（各 256 个坏像素）的两种候选——一个 16×16 的连贯块 vs 64×64 网格上间距 4 px 的孤立单点，断言两者 RMSE/PSNR 完全一致，但连贯块的 patch 子分数低于散布噪点的 1/4，综合 fidelity 也更低；edge_shift_filaments_are_tolerated（lib.rs）则证明 2 px 宽的整行细丝（128 px）在开运算后聚类数为 0，patch 子分数为 1。

3. 校准：分数意味着什么

基准在一幅768×1024 的纯色平涂插画上，将原图与其自身的各种失真版本做比较——这既说明了基准对不完美源图的宽容度，也定义了分数上限的含义：

经验法则：≥ 0.95视觉上不可区分；≥ 0.90是忠实描摹；≤ 0.80存在可见的几何或颜色错误；而如果分数崩塌而 PSNR/SSIM 依然很高，说明 patch 轴发现了连贯缺失区域——此时应查看--mask输出。

4. 使用方式

4.1 CLI

vtracer-bench <original> <candidate> [--thresh N] [--mask out.png]

• original、candidate—— 尺寸完全一致的栅格图（imagecrate 能解码的任何格式）。把 SVG 渲染成像素刻意不在本工具范围内：请使用你实际交付给用户的渲染器（resvg、Chromium、librsvg 等）来渲染，这样基准评判的才是用户真正看到的内容。参数解析逻辑见 crates/vtracer-bench/src/main.rs：未知 flag 直接以退出码 2 报错；若候选图与原图尺寸不一致，会通过assert_eq!(cand.dimensions(), orig.dimensions(), ...)直接断言失败。
• --thresh N—— patch 轴的 RGB 欧氏坏像素阈值（默认 24）。
• --mask out.png—— 写出开运算之前的原始坏像素掩码（255 = 坏），供可视化检查。

stdout 的最后一行是机器可读的：

[csv] fidelity,psnr,dssim,rmse,patch_mass,s_psnr,s_ssim,s_patch

（RMSE 仅作参考报告、不参与加权——它与 PSNR 度量的是同一个 MSE，只是线性曲线；两者同时计分等于给同一个误差双重加权。）完整示例输出（来自 crates/vtracer-bench/README.md）：

$ vtracer-bench original.png reconstruction.png psnr 34.77 dB (rmse 4.66) -> 0.6875 ssim 0.99541 (dssim 0.00461) -> 0.9954 patch 157.8 px rms (14503 bad px, 74 clusters, largest 73) -> 0.9726 fidelity 0.9022 [csv] 0.9022,34.77,0.00461,4.66,157.8,0.6875,0.9954,0.9726

4.2 库用法

use vtracer_bench::{fidelity, DEFAULT_THRESH}; // orig 与 cand 为交错 RGB8 缓冲，尺寸均为 w×h let (report, bad_mask) = fidelity(&orig, &cand, w, h, DEFAULT_THRESH); println!("fidelity {:.4} (psnr {:.2} dB, dssim {:.5})", report.fidelity, report.psnr, report.dssim);

FidelityReport暴露全部原始指标与子分数（字段清单见 crates/vtracer-bench/src/lib.rs）：psnr、dssim、rmse、bad_px（开运算前的坏像素数）、clusters、largest、patch_mass，以及s_psnr、s_ssim、s_patch三个子分数和合成后的fidelity。所有调参常量（PATCH_HALF、DEFAULT_THRESH、以及W_PSNR/W_SSIM/W_PATCH权重）都是pub且带文档注释。

该基准完全确定：相同输入必然产生逐字节相同的输出。合成公式的实现见 crates/vtracer-bench/src/lib.rs：s_psnr即无参数映射，s_ssim = 1/(1+dssim)，s_patch = exp(−P/PATCH_HALF·ln2)，最终fidelity = (s_psnr^W_PSNR · s_ssim^W_SSIM · s_patch^W_PATCH)^(1/(W_PSNR+W_SSIM+W_PATCH))。

4.3 构建与特性

crates/vtracer-bench/Cargo.toml 中，vtracer-bench默认启用cli特性（解码 PNG/JPEG/WebP，对应image的 codec feature）。关键设计在于：库本身只与imagecrate 的缓冲区类型打交道，不携带任何编解码器——把指标嵌入自己 tracer 的工程在依赖时关掉默认特性即可零编解码依赖。CLI 二进制vtracer-bench由[[bin]]声明并要求cli特性（Cargo.toml）。核心依赖visioncortex（用于BinaryImage聚类）来自工作区共享依赖（Cargo.toml）。

5. 与 vtracer 生态的配合

vtracer-bench位于 vtracer 工作区（Cargo.toml 的 members 列表），定位是给 vtracer 自身的描摹质量把关。作为对照，vtracer 主 crate 也采用「渲染后对比」的思路做回归验证：crates/vtracer/tests/golden.rs 用usvg解析 SVG、resvg渲染成像素后逐像素比较差异；crates/vtracer/tests/equivalence.rs 同样借助resvg::render验证 stacked 与 cutout 两种模式渲染结果一致。

实际的端到端工作流通常是这样：先用vtracerCLI（参数解析见 crates/vtracer-cli/src/main.rs，如--preset、--mode pixel|polygon|spline、--simplify、--filter-speckle、--max-colors等）把原图转成 SVG，再用 resvg 等渲染器把 SVG 栅格化为与原图同尺寸的候选 PNG，最后交给vtracer-bench打分。这样基准评判的是「用户实际看到的重建结果」，而不是中间矢量数据本身。

6. 小结

vtracer-bench用一个加权几何均值把三条互补的度量轴压成一个可解释的保真度数字：无参数 PSNR 映射保证全局误差的单调性，多尺度 DSSIM 追踪感知质量，而「开运算 + 聚类差分」的 patch 轴专门捕捉 PSNR/SSIM 都会平均掉的连贯缺失区块。它完全确定、对轻度压缩/模糊源图有内建容忍度，且既提供一行命令的 CLI 也提供无编解码依赖的库 API——对于任何做栅格到矢量转换质量验证的团队，都可以直接嵌入到自己的评测管线中。想深入了解实现与测试，可直接阅读 crates/vtracer-bench/src/lib.rs 与 crates/vtracer-bench/src/main.rs。

• 图像处理
• 图形学
• CLI