match_pose op• 資料種類:voxel × voxel → shift
• 呼叫: import fullseye as fs; fs.ledger.match_phase_3d(a, b, device='cpu', window='tukey', whitening=0.25)(要直接呼叫實作,import match3d; match3d.match_phase_3d(a, b, device='cpu', window='tukey', whitening=0.25);從台帳取用則 ops3d.get("match_phase_3d"))
• GPU:該運算子有 GPU 路徑(device="cuda")
3D 相位相關(FFT)。回傳把 b 對齊到 a 的整數位移 (dz,dy,dx)。
Reddy & Chatterji 的 3D 版。將互功率譜 R = A·conj(B) 除以 |R|^whitening 後做逆 FFT,其峰值 = 平移量。不需樣板、作用於整個 volume、O(N log N)。旋轉/縮放需另行處理(PCA / log-polar)。
引數:a、b 為同形狀的 3-D 陣列(不同則 ValueError)。轉為 float32 後做 FFT。window:"tukey"(預設,α 0.5)、"hann"、None(不加視窗)—— 視窗在減去平均值後套用,長度小於 8 的軸不加視窗。whitening:|R| 的指數(0〜1, 1 = 經典相位相關的完全白化,0 = 單純互相關,預設 0.25)。
回傳值:int 的 tuple (dz, dy, dx),各軸已折回到 (−N/2, N/2]。意義為 np.roll(b, (dz,dy,dx), axis=(0,1,2)) ≈ a(把 b 移動這麼多就與 a 重合)。
★更改預設值的理由(2026-10-06,與 filters_freq.phase_correlation_fft 相同的陷阱):0.4.0 之前的「無視窗 + 完全白化(eps 1e-9)」, 對頻帶受限 volume 的 非週期性裁切(2 次取像只部分重疊這種一般用法),無訊號的頻率 bin (裁切邊緣不連續造成的洩漏與捨入)經白化後與有訊號的 bin 權重相同,因而回傳不了正確的位移 —— 對低通濾波後的 32³ 裁切,10 種位移命中 0 / 10,64³ 也是 0 / 10。對 np.roll 的週期性位移則是精確的,所以只靠這種情況的門檻看不出來。在 3 維中,比起 2 維(預設 Hann + 0.5),視窗更會削減重疊,白化也更容易抬高雜訊 bin:實測命中數(10 種位移 × 3 組種子)中, 32³、位移 ±6 的低通裁切:Hann + 0.5 為 11 / 30,Hann + 0.25 為 19 / 30,Tukey + 0.25 為 28 / 30;週期性位移分別為 9 / 30、18 / 30、27 / 30(舊版 30 / 30)。在 64³ 與 (1, 256, 256) 上 3 種全部命中(舊版在低通裁切上為 0)。頻帶更低(截止 0.10)的 32³ 每種都在 6 / 10 以下,這裡仍然困難。因此預設為 Tukey(α 0.5)+ 0.25。舊行為為 window=None, whitening=1.0(數值也走同一路徑)。
• 由於是循環相關,超出的部分會從對側繞回。位移超過 volume 的一半時看起來正負號相反。使用帶視窗的預設值時,小 volume(32³)上大的週期性位移(邊長的 2/10)可能失準(即上面的 27 / 30)—— 若已知是週期性位移,請用 window=None, whitening=1.0。
• 全 0 的 volume 結果為 0,回傳 index 0。
• 整數精度。次體素請交給 refine_translation_lk / refine_peak_newton。
• 有旋轉、縮放時無效(順序為 match_logpolar_z → 旋轉校正 → 本 op)。
Raises ValueError:形狀不同、window 拼寫錯誤、whitening 在 [0, 1] 之外、沒有 torch 的環境中 device 不是 cpu。
• 範例資料目錄(下載 URL / 授權) —— 2-D 用 skimage.data(BSD/公有領域)加合成圖,3-D 給出真實資料源(Stanford/PDS 等)的下載 URL。
• 運算子來歷與參考文獻 —— 該運算子族所依據的研究/方法出處。
• shape_desc_pose — py -3.11 examples_3d/shape_desc_pose.py
shift 作為輸入)match_pose)match_pca · moment_axes · match_logpolar_z
*Provenance: match3d.py — 3D 運算子登記表。本條目由 tools/opdocs.py md 自動產生(請勿手動編輯)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.