solid op• Datenarten: image2d × image2d × flow2d → image2d
• Aufruf: import fullseye as fs; fs.ledger.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray' (die Implementierung direkt: import dic; dic.correlation_quality(ref: 'Any', cur: 'Any', flow: 'Any', info: 'Optional[dict]' = None, subset: 'int' = 31) -> 'np.ndarray'; aus dem Register: opspiv.get("correlation_quality"))
Eine ZNCC-Karte, die punktweise zurückgibt, wie gut ein gegebenes Verschiebungsfeld passt.
Argumente
ref Referenzbild.
cur Bild nach der Verformung. Gleiche Form wie ref.
flow flow2d (2, h, w) von pivops, Komponenten (dy, dx) [px].
Ohne info ein Feld über alle Pixel der Form (2, H, W).
info das von piv_cross_correlate gelieferte dict. Wird es übergeben, wird das flow des Fenstergitters
vor der Messung bilinear auf Pixel ausgedehnt.
subset Seitenlänge des quadratischen Subsets für die Korrelation [px]. Ungerade.
Der Rückgabewert ist ein float-Array derselben Form wie das Eingabebild. Die Werte sind ZNCC in [-1, 1]; nicht messbare Punkte sind NaN (Ränder, an denen das Subset über das Bild hinausragt, Punkte, deren verformte Abtastpunkte das Bild verlassen, Subsets ohne Varianz).
★ Das ist kein Korrelator —— sondern ein Bewerter für ein bereits vorhandenes Verschiebungsfeld
Weder piv_cross_correlate noch optical_flow_lk noch demons_register
sagt, ob die gelieferte Verschiebung stimmt. Hier wird nur cur mit flow zur Referenzseite
zurückgezogen (bilinear) und die ZNCC mit ref in einer subset-Box gemessen.
Der Kern ist, dass sich die Ausgabe jedes Schätzers über dieselbe Schnittstelle bewerten lässt: ohne
1 weiteren Korrelator wird allein die Qualität hinzugefügt.
Mittelwert und Standardabweichung werden beide herausgerechnet, daher ist es invariant gegenüber Verstärkung und Offset.
Auch bei einem Paar mit geänderter Belichtung zählt nur, "ob es passt".
★★ Es gibt Fälle, in denen das bestehende info["peak_ratio"] nicht reicht (gemessen)
peak_ratio (1. Gipfel / 2. Gipfel) ist das übliche SN-Verhältnis von PIV und
fängt Fehler der Art ab, bei denen auf der Korrelationsfläche konkurrierende Gipfel entstehen. Nicht abgefangen werden
Fehler der Art "diese Stelle ist etwas anderes geworden". Gemessen an einem Paar mit u=0.37 px, in dem nur 60x60 Pixel
durch ein unabhängiges Muster ersetzt wurden:
Kennzahl ersetzt gesund Unterscheidung
peak_ratio 1.207 1.304 7.5 % Abstand (überlappend)
correlation_quality 0.1101 0.9993 9-facher Abstand
Wie sich der RMS-Verschiebungsfehler beim Abschneiden nach Qualität ändert:
Gate verbleibt Fehler-RMS [px]
keines 100.0 % 1.8110
zncc >= 0.8 84.9 % 0.0031 ← 584-fach besser
peak_ratio >= 1.2 81.8 % 1.2183 ← 1.5-fach
peak_ratio >= 1.3 41.6 % 1.4471 ← verwirft 6 Zehntel und wird schlechter
Richtig ist, beides anzusehen. peak_ratio sieht konkurrierende Gipfel, ZNCC sieht
Dekorrelation. Eines allein lässt eine Lücke.
★★ Falle —— hohe Qualität heißt nicht hohe Genauigkeit
ZNCC reagiert kaum auf Subpixel-Fehler. Gemessen durch Bewertung von Feldern mit absichtlich eingefügtem Fehler bei einem Paar mit wahrer Verschiebung 0.37 px
(Speckle-Durchmesser 3.8 px):
Verschiebungsfehler [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
Um 0.05 px falsch und dennoch 0.9992 —— der Abstand zur perfekten Übereinstimmung 0.99945 beträgt
nur 2.5e-4. Messen kann diese Kennzahl "Versätze, die groß gegenüber der Speckle-
größe sind, Fehlstellen, Ersetzung durch etwas anderes", nicht eine Genauigkeit von 0.01 px.
Verschlechtern sich alle Punkte gleichmäßig durch gleichförmiges Rauschen (σ=0.15), behält das Gate nur
21.8 %, und die Fehler-RMS verbessert sich lediglich um das 1.34-fache, 0.1736 → 0.1292 ——
es hilft nur, wenn der Fehlschlag lokal ist.
★ Das Zurückziehen nutzt das Feld selbst, keine Translation pro Subset
Übliches DIC verschiebt das Subset starr und korreliert, hier wird dagegen cur mit dem pixelweisen
flow verzerrt und dann in einer Box korreliert. Ist flow glatt,
stimmen beide überein; sonst ist dieses richtiger (weil das Residuum einschließlich der
Verformung innerhalb des Subsets betrachtet wird). Die Kosten bleiben bei O(N) (0.003 Sekunden bei 256²).
fail-closed
• ref / cur nicht 2-D, verschiedene Formen, enthalten NaN / Inf.
• flow nicht (2, h, w).
• ohne info ein flow mit anderer Form als das Bild (mit Korrekturhinweis abgelehnt).
• info ohne rows / cols, Formen von Gitter und flow passen nicht zusammen, Gitter entlang einer Achse kleiner als 2.
• subset gerade / kleiner als 3 / größer als das Bild.
• Leitfaden zur Familie piv_displacement
• Katalog der Beispieldaten (Download-URLs / Lizenzen) — 2-D nutzt skimage.data (BSD/Public Domain) plus synthetische Bilder, 3-D nennt Download-URLs echter Datenquellen (Stanford, PDS, …).
• Herkunft und Literatur der Operatoren — die Quellen der Forschung/Verfahren, auf denen diese Operatorfamilie beruht.
• Der kanonische Algorithmus (Autor, Jahr) und seine Anwendungen stehen im Familienleitfaden oben.
• piv_field_analysis_tour — py -3.11 examples/piv_field_analysis_tour.py
image2d als Eingabe)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. Diese Notiz wird von tools/opdocs.py md erzeugt (nicht von Hand bearbeiten).*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.