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.