solid op• 数据种类:image2d × image2d × flow2d → image2d
• 调用: import fullseye as fs; fs.ledger.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray'(要直接调用实现,import dic; dic.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray';从台账取用则 opspiv.get("correlation_quality"))
逐点返回给定位移场吻合程度的 ZNCC 图。
参数
ref 基准图像。
cur 变形后图像。与 ref 同形。
flow pivops 的 flow2d (2, h, w)，分量为 (dy, dx) [px]。
不传 info 时为 (2, H, W) 的全像素场。
info piv_cross_correlate 返回的 dict。传入时，把窗口网格的 flow
双线性扩展到像素后再测量。
subset 取相关的正方子区的边长 [px]。奇数。
返回值是与输入图像同形的 float 数组。值为 [-1, 1] 的 ZNCC，测不到的点为 NaN(子区超出图像的边缘、变形后的采样点落到图像外的点、没有方差的子区)。
★ 这不是相关器 —— 而是对已有位移场的评分员
piv_cross_correlate、optical_flow_lk、demons_register 都
不返回所给位移是否正确。这里只是用 flow 把 cur 拉回基准侧
(双线性)，再用 subset 的箱测量与 ref 的 ZNCC。
要点是任何估计器的输出都能用同一个接口评分，无需
再增加 1 个相关器就能只补上质量。
平均和标准差两者都被扣除，因此对增益和偏移不变。
即使是曝光变化的图像对，也只看“是否吻合”。
★★ 存在仅凭现有 info["peak_ratio"] 不够的场合(实测)
peak_ratio(第 1 峰 / 第 2 峰)是 PIV 的标准 SN 比，
能捕捉相关面上出现竞争峰这类失败。捕捉不到的是
“那个地方变成了别的东西”这类失败。在 u=0.37 px 的图像对中只把 60x60 像素
替换为无关图案的实测：
指标 替换区域 健全区域 区分
peak_ratio 1.207 1.304 相差 7.5 %(重叠)
correlation_quality 0.1101 0.9993 相差 9 倍
用质量截断后位移误差 RMS 如何变化：
门禁 保留比例 误差 RMS [px]
无 100.0 % 1.8110
zncc >= 0.8 84.9 % 0.0031 ← 改善 584 倍
peak_ratio >= 1.2 81.8 % 1.2183 ← 1.5 倍
peak_ratio >= 1.3 41.6 % 1.4471 ← 丢掉 6 成反而恶化
两者都看才是正确的。 peak_ratio 看竞争峰，ZNCC 看
去相关。只看一个就会留下漏洞。
★★ 陷阱 —— 质量高不等于精度高
ZNCC 对亚像素误差几乎没有反应。对真实位移 0.37 px 的图像对
故意加入误差的场进行评分的实测(斑点直径 3.8 px)：
位移误差 [px] 0.00 0.05 0.10 0.25 0.50 1.00 2.00
zncc 中位数 0.99945 0.99920 0.99845 0.99330 0.97615 0.90617 0.67655
错了 0.05 px 仍为 0.9992 —— 与完全吻合的 0.99945 之差
只有 2.5e-4。这个指标能测的是“相对斑点大小较大的
偏移、缺测、被替换成别的东西”，而不是 0.01 px 的精度。
在均匀噪声使所有点同等劣化的情况(σ=0.15)下，用门禁截断后保留
21.8 %，误差 RMS 只从 0.1736 → 0.1292，改善 1.34 倍 ——
只有在失败是局部的时候才有效。
★ 拉回用的不是逐子区的平移，而是场本身
普通的 DIC 刚性地错开子区来取相关，这里则用逐像素的
flow 扭曲 cur 后再用箱取相关。flow 平滑时
两者一致，否则这边更正确(因为连子区内的
变形也一并看残差)。费用也只需 O(N)(256² 时 0.003 秒)。
fail-closed
• ref / cur 不是 2 维、形状不同、含 NaN、Inf。
• flow 不是 (2, h, w)。
• 没有 info 而 flow 与图像形状不同(附带修正方法拒绝)。
• info 中没有 rows / cols、网格与 flow 的形状不符、网格在任一轴上小于 2。
• subset 为偶数、小于 3、比图像还大。
• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。
• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。
• 算法的正典(作者、年份)与用途见上面的族使用指南。
• piv_field_analysis_tour — py -3.11 examples/piv_field_analysis_tour.py
image2d 作为输入)piv_cross_correlate · piv_multipass · piv_deform_pass · strain_from_displacement · speckle_quality
solid)strain_from_displacement · speckle_quality
*Provenance: dic.py — PIV 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.