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.