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.