Advanced OpenPIV Algorithms and Settings

Reviewed against the released openpiv 0.26.1 source and SciPy runtime on 2026-10-01. Hosted documentation can lag the wheel; for example its API listing omits the new backend argument.

Correlation methods

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

Use these two names. "direct" appears in some legacy docstrings but is not implemented by the SciPy extended_search_area_piv correlation path. Do not offer it as an option.

Both methods support extended search; larger extreme velocities alone do not establish aliasing. The bundled CLI chooses "linear" with normalized_correlation=True for extended windows, following the API's normalization requirement. Validate either choice using known displacements.

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 batches peak extraction and signal-to-noise calculations. Both paths already hold the correlation stack; edge/degenerate peak behavior can differ. It remains False in extended_search_area_piv, but PIVSettings.use_vectorized defaults to True since 0.25.5.

backend="scipy" selects the tested reference path. "auto" can use installed Rust components; in 0.26.1 the FFT dispatcher still selects SciPy unless "rust" is explicit. "rust" requires openpiv_rust and raises ImportError when absent. Record backend and package versions; do not assume every wheel contains the extension or infer speed/numerical parity from release notes.

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) with coordinates in pixels and velocities in pixels per frame. simple_multipass (and alias multigrid_windef) ignore settings.dt and settings.scaling_factor; 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

Batch windef.piv(settings) does apply both before saving. The array convenience wrapper always validates/replaces the first pass, does not perform the batch image preprocessing or between-pass smoothing, and discards the final masked-array mask when returning .data. For masks, full switch control, and preserved quality information use the batch pipeline or manage lower-level passes. Always supply settings: the no-settings wrapper resets window lists to two entries but leaves num_iterations=3. Construction checks list lengths and overlap; changing attributes bypasses those checks, and the number of iterations must still match the requested passes.

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. Prefer constructor keywords so its consistency checks run. This table describes batch settings; do not assume the simple array wrapper uses every field.

Input and region

Masking

The 0.26.1 batch dispatcher checks "edge" (singular), while dynamic_masking expects "edges"; the latter also has the uint8-indexing bug described in SKILL.md. Neither spelling is a safe edge masking recipe for this release. Use intensity/static masks and verify excluded regions on outputs.

Correlation

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

Scaling

Validation — thresholds consumed by validation.typical_validation; the batch runner controls whether the first pass is validated

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)
)
# 0.26.1's FFT direction differs from 2D. These components align with
# increasing column, row, depth coordinates (verify on a known translation).
column_velocity, row_velocity, depth_velocity = -u, v, w

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.

The 0.26.1 3D FFT reverses frame B, unlike the 2D path. Positive input translations along (row, column, depth) give raw (u, v, w)=(-dcolumn, +drow, +ddepth)/dt, confirmed for both shift directions. Do not reuse the 2D sign conversion. The mapping above aligns velocities with the increasing column/row/depth coordinates returned by get_coordinates; apply a separately calibrated laboratory-axis transform to both positions and velocities. The grid stride uses window_size-overlap, unlike the 2D extended search stride. sig2noise_method=None returns three arrays here, rather than the 2D API's three arrays with a NaN s2n. The 32³ recipe ran on synthetic volumes; smaller positive and negative translations established the component signs. Real volumetric experiments remain unvalidated.

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. Size cutoffs are segmented region areas in pixels, not particle diameters; strict inequalities exclude equality. Brightness and I_sat must match the input intensity scale (the example is 8-bit).

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

Review sources and verification

• 0.26.1 release and backend notes
• Official API reference
• Released correlation source
• Released settings
• Batch and array multipass source
• Masking source
• Validation, replacement, and smoothing
• 3D correlation and phase separation

Tests use generated particle translations, analytic velocity fields, mask persistence, fractional intensities, multipass units, NaN smoothing, and small volumetric/phase-separation examples. These are API/numerical checks, not validation of a real experiment's calibration, uncertainty, tracer fidelity, time/ensemble convergence, or particle-phase classification. Rust was unavailable in the tested environment; its execution and claimed speedup were not verified. No remote service, authentication, endpoints, or pagination are involved in local OpenPIV processing.