solid op• Data kinds: image2d × image2d × flow2d → image2d
• Call: import fullseye as fs; fs.ledger.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray' (implementation को सीधे call करना हो तो import dic; dic.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray', registry से लेना हो तो opspiv.get("correlation_quality"))
दिया गया displacement field कितना अच्छा मेल खाता है, यह हर point पर लौटाने वाला ZNCC map।
Arguments
ref reference image।
cur विकृति (deformation) के बाद की image। ref के समान shape।
flow pivops का flow2d (2, h, w), components (dy, dx) [px]।
info के बिना, (2, H, W) का all-pixel field।
info piv_cross_correlate द्वारा लौटाया गया dict। दिया गया हो तो window-grid flow
को मापने से पहले bilinear रूप से pixels पर फैलाया जाता है।
subset correlation के लिए वर्गाकार subset की भुजा [px]। विषम।
return value इनपुट image के समान shape का float array है। मान [-1, 1] में ZNCC हैं; जिन points को मापा नहीं जा सका वे NaN हैं (किनारे जहाँ subset image से बाहर निकलता है, ऐसे points जिनके विकृत sample points image से बाहर चले जाते हैं, बिना variance वाले subsets)।
★ यह correlator नहीं है —— यह किसी मौजूदा displacement field का scorer है
न piv_cross_correlate, न optical_flow_lk, न demons_register
बताता है कि उसका बनाया displacement सही है या नहीं। यह केवल cur को flow से reference की ओर वापस खींचता है
(bilinear) और subset box में ref के विरुद्ध ZNCC मापता है।
मुद्दा यह है कि किसी भी estimator का आउटपुट एक ही interface से score किया जा सकता है: 1 और correlator जोड़े बिना
केवल quality जोड़ी जाती है।
Mean और standard deviation दोनों हटा दिए जाते हैं, इसलिए यह gain और offset के प्रति invariant है।
बदले हुए exposure वाले जोड़े के लिए भी यह केवल यही देखता है कि "मेल खाते हैं या नहीं"।
★★ ऐसी स्थितियाँ हैं जहाँ मौजूदा info["peak_ratio"] पर्याप्त नहीं है (मापा गया)
peak_ratio (1st peak / 2nd peak) PIV का मानक SN ratio है और
उन विफलताओं को पकड़ता है जिनमें correlation surface पर प्रतिस्पर्धी peaks उठते हैं। जो यह नहीं पकड़ता
वह है "वह जगह कुछ और ही बन गई" प्रकार की विफलता। u=0.37 px वाले जोड़े पर मापा गया, जिसमें केवल 60x60 pixels
को एक असंबंधित pattern से बदल दिया गया था:
metric replaced area healthy area distinction
peak_ratio 1.207 1.304 7.5 % का अंतर (overlapping)
correlation_quality 0.1101 0.9993 9 गुना का अंतर
quality से काटने पर RMS displacement error कैसे बदलता है:
gate kept error RMS [px]
none 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 प्रतिस्पर्धी peaks देखता है, ZNCC
decorrelation देखता है। कोई एक अकेला छेद छोड़ देता है।
★★ जाल —— उच्च quality का अर्थ उच्च accuracy नहीं है
ZNCC subpixel error पर लगभग प्रतिक्रिया नहीं देता। वास्तविक displacement 0.37 px वाले जोड़े पर जानबूझकर डाली गई error वाले fields को score करके मापा गया
(speckle व्यास 3.8 px):
displacement error [px] 0.00 0.05 0.10 0.25 0.50 1.00 2.00
zncc median 0.99945 0.99920 0.99845 0.99330 0.97615 0.90617 0.67655
0.05 px गलत होने पर भी 0.9992 —— पूर्ण मेल 0.99945 से अंतर
केवल 2.5e-4 है। यह metric जो माप सकता है वह है "speckle आकार की तुलना में बड़े offsets,
missing data, किसी और चीज़ से प्रतिस्थापन", न कि 0.01 px सटीकता।
जब एक समान noise (σ=0.15) में सभी points बराबर बिगड़ते हैं, तो gate केवल
21.8 % रखता है और error RMS केवल 1.34 गुना सुधरता है, 0.1736 → 0.1292 ——
यह तभी मदद करता है जब विफलता स्थानीय हो।
★ वापस खींचने में field स्वयं उपयोग होता है, प्रति-subset translation नहीं
सामान्य DIC subset को rigid रूप से खिसकाकर correlate करता है, लेकिन यहाँ cur को प्रति-pixel
flow से warp करके फिर box में correlate किया जाता है। यदि flow smooth है
तो दोनों मेल खाते हैं; यदि नहीं, तो यह वाला अधिक सही है (क्योंकि यह subset के भीतर की
deformation सहित residual देखता है)। लागत केवल O(N) है (256² पर 0.003 seconds)।
fail-closed
• ref / cur 2-D नहीं, अलग shapes, NaN / Inf युक्त।
• flow (2, h, w) नहीं।
• info के बिना, image से अलग shape का flow (सुधार के निर्देशों के साथ अस्वीकार)।
• info में rows / cols नहीं, grid और flow के shapes असहमत, किसी भी axis पर grid 2 से छोटा।
• subset सम / 3 से कम / image से बड़ा।
• piv_displacement family guide
• Sample data catalog (DL URL / license) — 2-D के लिए skimage.data (BSD/public) + synthetic, 3-D के लिए real data sources (Stanford/PDS आदि) के DL URL।
• Operators का स्रोत और संदर्भ — इस op family के मूल research/methods के स्रोत।
• Algorithm का मानक स्रोत (लेखक, वर्ष) और उपयोग ऊपर की family usage guide में दिए गए हैं।
• piv_field_analysis_tour — py -3.11 examples/piv_field_analysis_tour.py
image2d को input के रूप में लेते हैं)piv_cross_correlate · piv_multipass · piv_deform_pass · strain_from_displacement · speckle_quality
solid)strain_from_displacement · speckle_quality
*Provenance: dic.py — PIV operator registry. यह per-op note tools/opdocs.py md से अपने-आप generate होता है (हाथ से edit न करें)।*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.