estimate op• データ種: image2d × image2d → flow2d
• 呼び出し: 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"))
窓ごとの相互相関で変位場を出す。返りは `(flow, info)`。
各窓で `FFT` を 2 回とって共役積の逆変換を取り(循環相関)、最大値の
位置を整数変位、その周りの 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: :data:PEAK_MODES。
window_func: :data: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。
• サンプルデータ カタログ(DL URL / ライセンス) — 2-D は skimage.data(BSD/public)+ 合成、3-D は実データ源(Stanford/PDS 等)の DL URL。
• 演算子の来歴・参考文献 — この op 族の元になった研究/手法の出典。
• アルゴリズムの正典(著者・年)と用途は上記ファミリ使い方ガイドに記載。
• piv_flow_from_particles — py -3.11 examples/piv_flow_from_particles.py
• poc_dic_strain — py -3.11 examples/poc_dic_strain.py
• poc_strain_history — py -3.11 examples/poc_strain_history.py
• poc_superresolution_limits — py -3.11 examples/poc_superresolution_limits.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 operator registry. この per-op ノートは tools/opdocs.py md が自動生成(手編集しない)。*
© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.