piv_ensemble_correlate — PIV estimate op

• Data kinds: images → flow2d

• Call: import fullseye as fs; fs.ledger.piv_ensemble_correlate(images, window=32, overlap=0.5, peak='gauss3', window_func='hann', normalize='overlap', search_limit=0.25) (to call the implementation directly, import pivops; pivops.piv_ensemble_correlate(images, window=32, overlap=0.5, peak='gauss3', window_func='hann', normalize='overlap', search_limit=0.25); from the registry, opspiv.get("piv_ensemble_correlate"))

• Return value through the ledger: fullseye.ledger.piv_ensemble_correlate(...) returns only the declared out type flow2d (the underlying function also returns auxiliary values). When you need what was dropped, use fullseye.ledger.piv_ensemble_correlate.raw(...) or call pivops.piv_ensemble_correlate directly.

• Underlying return: (flow, info) -> flow2d

Usage

Searches for the peak after summing the correlation maps (ensemble correlation).

With few particles or much noise, measuring pair by pair and averaging yields the average of wrong vectors. Adding at the correlation stage lets weak peaks pile up at the same place and stand out. Steady flow (same displacement in all pairs) is a prerequisite.

Args:

images: sequence of 2 or more images. Consecutive pairs (k, k+1) are used.

window / overlap / peak / window_func / normalize / search_limit:

same as piv_cross_correlate.

Returns:

(flow (2, h, w), info). info["pairs"] holds the number of pairs used.

Detailed usage guide

• piv_displacement family guide

References (sample data, literature)

• Sample-data catalog (download URLs / licences) — 2-D uses skimage.data (BSD/public domain) plus synthetic images; 3-D lists download URLs for real data sources (Stanford, PDS, …).

• Operator provenance and references — the sources of the research/methods this op family came from.

• The canonical algorithm (author, year) and its uses are named in the family usage guide above.

Runnable examples (verified samples that actually call this op)

• piv_field_analysis_tour — py -3.11 examples/piv_field_analysis_tour.py

• poc_river_surface_velocity — py -3.11 examples/poc_river_surface_velocity.py

Ops the type connects to (they accept flow2d as input)

piv_deform_pass · piv_outlier_mask · piv_replace_outliers · piv_vorticity · piv_divergence · piv_flow_magnitude · piv_to_velocity · piv_velocity_gradient

Same category (estimate)

piv_cross_correlate · piv_multipass · piv_deform_pass

*Provenance: pivops.py — PIV operator registry. This per-op note is generated by tools/opdocs.py md (do not hand-edit).*

© 2026 Kazufumi Furuse — Fullseye operator documentation. Licensed under Apache-2.0.