Advanced OpenPIV Algorithms and Settings

Everything here is checked against openpiv 0.25.4. Confirm with inspect.signature() against other releases — names and defaults have moved between versions.

Correlation methods

pyprocess.extended_search_area_piv(..., correlation_method=...):

Only those two exist in 0.25.4. "direct" appears in the docstrings but the branch is missing — it prints correlation method direct is not implemented and then raises UnboundLocalError: cannot access local variable 'corr'. Do not offer it as an option.

Use "linear" whenever search_area_size > window_size. "circular" accepts an extended search area without complaining but keeps relying on wrap-around, and on OpenPIV's own test1 pair at window_size=32, search_area_size=38 it produced a peak |u| of 255 px/s against 87 px/s for "linear" — the difference is aliased vectors, not physics.

normalized_correlation=True normalizes intensities per window before correlating, making peak heights comparable across windows of differing brightness — useful under uneven illumination. It also shifts the s2n scale, so re-tune the threshold after switching it on.

use_vectorized=True swaps the per-window loop for the batched vectorized_correlation_to_displacements path. Same results, faster on large fields, higher peak memory since all correlation maps exist at once.

Subpixel peak fitting

subpixel_method selects how the integer correlation peak is refined:

Peak locking is a particle-imaging problem, not a fitting problem: aim for 2–3 px particle image diameter rather than switching estimators.

Signal-to-noise measures

pyprocess.sig2noise_ratio(correlation, sig2noise_method="peak2peak", width=2):

• "peak2mean" — first peak divided by the mean of the correlation map. This is the default of both extended_search_area_piv and PIVSettings. Values run higher and depend on map size.
• "peak2peak" — first peak divided by the second-highest peak, excluding a width-pixel neighbourhood around the first. The classic PIV detectability ratio; usable thresholds are ~1.05–1.3.

The two scales are not interchangeable. A threshold copied from one to the other silently rejects everything or nothing.

Multi-pass window deformation (openpiv.windef)

windef.simple_multipass(frame_a, frame_b, settings) runs the full loop:

1. windef.first_pass — coarse correlation on windowsizes[0].
2. validation.typical_validation — applies every enabled check in settings at once.
3. filters.replace_outliers — fills flagged vectors.
4. windef.multipass_img_deform for iterations 1 .. num_iterations-1 — deforms the interrogation windows using the previous pass as a predictor, then re-correlates on the next smaller window.
5. Remaining NaNs filled with zeros; transform_coordinates applied.

It returns (x, y, u, v, flags) in pixels per frame. settings.dt and settings.scaling_factor exist on the dataclass but the windef chain applies neither — first_pass calls extended_search_area_piv without passing dt. Convert afterwards:

x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor=96.52)
u, v = u / dt, v / dt      # scaling.uniform does not divide by dt

The upside of working in px/frame is that the validation defaults (min_max_u_disp=(-30, 30), median_threshold=3) are stated in px/frame and therefore mean what the PIV literature says they mean. The same numbers applied to extended_search_area_piv output, which has been divided by dt, would reject the whole field.

deformation_method="symmetric" (the default) deforms both frames toward the midpoint, which halves the interpolation bias of deforming only the second frame. interpolation_order (default 3) is the spline order used for that deformation.

Window deformation is what makes multi-pass worth the cost: it handles velocity gradients within a window, which a fixed-window single pass cannot.

PIVSettings reference

windef.PIVSettings() is a dataclass; set attributes on an instance.

Input and region

Masking

Correlation

windowsizes and overlap must be at least num_iterations long — each pass reads its own entry.

Scaling

Validation — all consumed by validation.typical_validation

Replacement and smoothing

Smoothing between passes stabilizes the predictor for the next pass. It also propagates smoothing into the final result, so report it as part of the processing chain.

Output

Volumetric PIV (openpiv.pyprocess3D)

from openpiv import pyprocess3D

u, v, w, s2n = pyprocess3D.extended_search_area_piv3D(
    vol_a, vol_b,
    window_size=(32, 32, 32),
    overlap=(16, 16, 16),
    dt=(1.0, 1.0, 1.0),
    search_area_size=(38, 38, 38),
    correlation_method="fft",       # note: "fft" here, not the 2D "circular"/"linear"
    subpixel_method="gaussian",
    sig2noise_method="peak2peak",
)

# Note the extra window_size argument -- this signature differs from pyprocess.get_coordinates.
x, y, z = pyprocess3D.get_coordinates(
    vol_a.shape, search_area_size=(38, 38, 38), window_size=(32, 32, 32), overlap=(16, 16, 16)
)

Inputs are 3D intensity volumes — this module correlates reconstructed volumes; it does not perform the tomographic reconstruction itself. dt is a per-axis tuple. Memory scales with the cube of window size, so 32³ windows on a large volume are already demanding.

Phase separation (openpiv.phase_separation)

For two-phase flows where large particles (droplets, bubbles) must be separated from tracers before correlation:

from openpiv import phase_separation

big, small = phase_separation.khalitov_longmire(
    image,
    big_particles_criteria={"min_size": 20, "min_brightness": 30},
    small_particles_criteria={"max_size": 20, "min_brightness": 5},
    blur_kernel_size=1,
    I_sat=230,
)

Criteria dicts accept min_size, max_size, min_brightness, and max_brightness. min_size is mandatory for the big-particle dict and max_size for the small-particle dict; unrecognized keys are ignored silently, so check spelling.

Also available: median_filter_method(image, kernel_size) (Kiger & Pan) and opening_method(image, kernel_size, iterations=1, thresh_factor=1.1) for simpler size-based separation. Run PIV separately on each returned phase — tracer statistics computed on an unseparated image are contaminated by the dispersed phase.

Choosing an approach