match_pose op• Datenarten: voxel × voxel → shift
• Aufruf: import fullseye as fs; fs.ledger.match_phase_3d(a, b, device='cpu', window='tukey', whitening=0.25) (die Implementierung direkt: import match3d; match3d.match_phase_3d(a, b, device='cpu', window='tukey', whitening=0.25); aus dem Register: ops3d.get("match_phase_3d"))
• GPU: Dieser Operator hat einen GPU-Pfad (device="cuda")
3-D-Phasenkorrelation (FFT). Liefert die ganzzahlige Verschiebung (dz, dy, dx), die b auf a ausrichtet.
Reddy & Chatterji in 3D. Der Peak der inversen FFT des Kreuzleistungsspektrums R = A·conj(B), geteilt durch |R|^whitening, ist die Translation. Kein Template nötig, ganzes Volume, O(N log N). Rotation/Skalierung werden separat behandelt (PCA / log-polar).
Argumente: a, b sind 3-D-Arrays gleicher Form (sonst ValueError). Für die FFT werden sie nach float32 gewandelt. window: "tukey" (Standard, α 0.5), "hann", None (kein Fenster) —— das Fenster wird nach Abzug des Mittelwerts angewendet, nicht auf Achsen kürzer als 8. whitening: Exponent von |R| (0 bis 1, 1 = volle Whitening der klassischen Phasenkorrelation, 0 = reine Kreuzkorrelation, Standard 0.25).
Rückgabewert: int-Tupel (dz, dy, dx), jede Achse nach (−N/2, N/2] zurückgefaltet. Bedeutung:
np.roll(b, (dz,dy,dx), axis=(0,1,2)) ≈ a (um so viel verschoben deckt sich b mit a).
★Grund für den neuen Standard (2026-10-06, dieselbe Falle wie filters_freq.phase_correlation_fft): Das "kein Fenster + volle Whitening (eps 1e-9)" bis 0.4.0 gab bei nicht-periodischen Ausschnitten bandbegrenzter Volumes (der übliche Fall: 2 Aufnahmen, die sich nur teilweise überlappen) den Frequenz-Bins ohne Signal (Leckage aus der Unstetigkeit am Ausschnittrand und Rundung) durch die Whitening dasselbe Gewicht wie Bins mit Signal und lieferte nicht die richtige Verschiebung —— bei tiefpassgefilterten 32³- Ausschnitten 0 / 10 von 10 Verschiebungen, auch bei 64³ 0 / 10. Für periodische np.roll-Verschiebungen ist es exakt, daher konnte ein Gate nur mit diesen es nicht sehen. In 3 Dimensionen beschneidet das Fenster die Überlappung stärker als in 2 Dimensionen (Standard Hann + 0.5), und die Whitening hebt Rausch-Bins leichter an: gemessene Treffer (10 Verschiebungen × 3 Seeds), tiefpassgefilterte 32³-Ausschnitte mit Verschiebung ±6: Hann + 0.5 erreicht 11 / 30, Hann + 0.25 19 / 30, Tukey + 0.25 28 / 30; periodische Verschiebungen jeweils 9 / 30, 18 / 30 und 27 / 30 (alt 30 / 30). Bei 64³ und (1, 256, 256) treffen alle 3 jeden Fall (alt bei Tiefpass-Ausschnitten 0). Bei noch tieferem Band (Grenze 0.10) bleibt 32³ bei allen bei 6 / 10 oder weniger; das bleibt schwierig. Daher ist der Standard Tukey (α 0.5) + 0.25. Das alte Verhalten ist window=None, whitening=1.0 (auch numerisch derselbe Pfad).
• Zirkuläre Korrelation, daher kommt der überstehende Teil von der Gegenseite wieder herein. Eine Verschiebung über die halbe Volume-Größe erscheint mit umgekehrtem Vorzeichen. Mit dem gefensterten Standard kann ein kleines Volume (32³) bei großer periodischer Verschiebung (2/10 der Kante) danebenliegen (die 27 / 30 oben) —— wenn bekannt ist, dass die Verschiebung periodisch ist, window=None, whitening=1.0 verwenden.
• Ein Volume aus lauter 0 ergibt 0 und liefert Index 0.
• Ganzzahlige Genauigkeit. Für Subvoxel refine_translation_lk / refine_peak_newton verwenden.
• Wirkt nicht bei Rotation oder Skalierung (Reihenfolge match_logpolar_z → Rotationskorrektur → dieser op).
Raises ValueError: Formen verschieden, window falsch geschrieben, whitening außerhalb von [0, 1], device nicht cpu in einer Umgebung ohne torch.
• 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.
• shape_desc_pose — py -3.11 examples_3d/shape_desc_pose.py
shift als Eingabe)match_pose)match_pca · moment_axes · match_logpolar_z
*Provenance: match3d.py — 3D 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.