estimate op• 数据种类:image2d × image2d → flow2d
• 调用: import fullseye as fs; fs.ledger.piv_cross_correlate(a, b, window=32, overlap=0.5, peak='gauss3', window_func='hann', subtract_mean=True, shift=None, normalize='overlap', search_limit=0.25)(要直接调用实现,import pivops; pivops.piv_cross_correlate(a, b, window=32, overlap=0.5, peak='gauss3', window_func='hann', subtract_mean=True, shift=None, normalize='overlap', search_limit=0.25);从台账取用则 opspiv.get("piv_cross_correlate"))
• 经台账调用的返回值: fullseye.ledger.piv_cross_correlate(...) 只返回声明的 out 类型 flow2d 的值(底层函数还会返回辅助信息)。需要被丢弃的部分时,使用 fullseye.ledger.piv_cross_correlate.raw(...),或直接调用 pivops.piv_cross_correlate。
• 底层返回: (flow, info) -> flow2d
通过逐窗口的互相关求出位移场。返回 (flow, info)。
在每个窗口中做 2 次 FFT，取共轭积的逆变换(循环相关)，以最大值的位置为整数位移，用其周围 3 点确定亚像素位移。
向零方向的偏差及其校正(实测)：朴素的互相关会把位移拉向零。因为窗口错开后重叠区域减少，相关值本身随位移下降；实测中偏差也与位移成正比(win=32、Hann，dx 从 0.5 到 6 px 变化，偏差 / (d/N) 为 1.30, 1.29, 1.28, 1.28, 1.28 —— 斜率恒定)。
normalize="overlap" 通过除以窗函数的自相关来校正这一点(等同于用重叠面积归一化)。但在边缘处除数趋近 0，因此与 search_limit 把搜索范围限制在窗口 1/4 必须配对使用。实测：
=============== ========== ========== ==========
dx [px] 无校正 校正 + 1/4 仅校正
=============== ========== ========== ==========
1.0 的偏差 -0.0402 -0.0020 -0.2659
5.0 的偏差 -0.2001 -0.0128 -0.9210
5.0 的 RMS 0.2081 0.0301 4.8881
=============== ========== ========== ==========
最右列是“不限制搜索、只做归一化”的情况，校正使误差恶化 23 倍。“不能只启用其中之一”这一测量结果被直接设为默认。
Args:
a, b: 图像对 (H, W)。
window: 窗口边长 [px]。偶数、8 以上。
overlap: 窗口重叠率 [0, 1)。惯例为 0.5。
peak: PEAK_MODES。
window_func: WINDOW_FUNCS。
subtract_mean: 逐窗口减去平均(防止背景直流分量在中央形成巨大
峰)。关掉则会粘在零位移上。
shift: 预测位移 (2, h, w)(多级用)。把第 2 幅的窗口按这个整数量
错开后切出，测量残差。
normalize: "overlap"(默认)或 "none"。
search_limit: 以相对窗口的比例给出搜索位移的上限(默认 0.25 = PIV 的
“1/4 法则”)。None 为不限制 —— 与 normalize="overlap"
同时使用会如上表所示恶化。
Returns:
(flow (2, h, w), info)。info 是含有 rows / cols(窗口中心的
图像坐标)、peak_ratio(第 1 峰 / 第 2 峰。越接近 1 越
不可靠)、window / overlap / peak 的 dict。
• 示例数据目录(下载 URL / 许可证) —— 2-D 用 skimage.data(BSD/公有领域)加合成图,3-D 给出真实数据源(Stanford/PDS 等)的下载 URL。
• 算子来历与参考文献 —— 该算子族所依据的研究/方法出处。
• 算法的正典(作者、年份)与用途见上面的族使用指南。
• piv_field_analysis_tour — py -3.11 examples/piv_field_analysis_tour.py
• piv_flow_from_particles — py -3.11 examples/piv_flow_from_particles.py
• poc_beam_modal_video — py -3.11 examples/poc_beam_modal_video.py
• poc_change_detection_misreg — py -3.11 examples/poc_change_detection_misreg.py
• poc_dic_strain — py -3.11 examples/poc_dic_strain.py
• poc_print_registration — py -3.11 examples/poc_print_registration.py
• poc_river_surface_velocity — py -3.11 examples/poc_river_surface_velocity.py
• poc_strain_history — py -3.11 examples/poc_strain_history.py
• poc_superresolution_limits — py -3.11 examples/poc_superresolution_limits.py
• poc_tacsim_marker_shear — py -3.11 examples/poc_tacsim_marker_shear.py
flow2d 作为输入)piv_deform_pass · piv_outlier_mask · piv_replace_outliers · piv_vorticity · piv_divergence · piv_flow_magnitude · piv_to_velocity · piv_velocity_gradient
estimate)piv_multipass · piv_deform_pass · piv_ensemble_correlate
*Provenance: pivops.py — PIV 算子登记表。本条目由 tools/opdocs.py md 自动生成(请勿手工编辑)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.