Particle Image Velocimetry (PIV) analysis with OpenPIV. Use when extracting velocity fields from PIV image pairs, analyzing fluid dynamics or flow visualization experiments, cross-correlating interrogation windows, validating and replacing spurious PIV vectors, or computing vorticity, strain rate, a

OpenPIV Overview OpenPIV (Open Particle Image Velocimetry) analyzes fluid flow from PIV image pairs. It covers preprocessing, cross correlation, vector validation, outlier replacement, smoothing, and scaling to physical units. Everything below is verified against openpiv 0.25.4 . The API moves between releases — check inspect.signature() before trusting a snippet against a different version. When to use Use this skill when working with experimental PIV or flow visualization image pairs: measuring 2D velocity fields, tuning interrogation window parameters, validating vectors, or deriving vorticity, strain rate, and turbulence statistics. For simulating flow rather than measuring it, use a CFD skill instead. Quick Start Install OpenPIV: Run PIV analysis on an image pair: Or use the bundled CLI, which wraps exactly that pipeline: Core Concepts PIV Fundamentals Particle Image Velocimetry is an optical method for measuring fluid velocity by tracking illuminated tracer particles between two images. Process flow: 1. Capture an image pair ( frame a , frame b ) separated by a known time dt . 2. Divide the images into interrogation windows. 3. Cross correlate matching windows to find peak displacement. 4. Validate vectors (signal to noise, global range, local median). 5. Replace spurious vectors with interpolated values. 6. Scale pixel displacements to physical units. Interrogation Window Parameters window size — correlation window in pixels (typically 16–128). Larger windows give better correlation but coarser spatial resolution. overlap — pixels shared between adjacent windows (typically 50–75% of window size ). Higher overlap raises vector density and cost, but adjacent vectors become correlated rather than independent. search area size — the window searched in the second frame. Must be ≥ window size ; a few pixels larger accommodates larger displacements. Pair an extended search area with correlation method="linear" — the default "circular" relies on FFT wrap around and aliases large displacements into small ones. See references/advanced algorithms.md . Rules of thumb: keep the largest displacement under about a quarter of window size , and aim for 5–10 particles per window. Signal to Noise Ratio s2n measures how distinct the correlation peak is. sig2noise method controls how it is computed — "peak2mean" (the function default) or "peak2peak" . The two are on different scales , so a threshold tuned for one is meaningless for the other. Typical peak2peak thresholds are 1.05–1.3. Common Operations Dynamic Masking Masking lives in openpiv.preprocess , not in an openpiv.masking module. It returns an (image, mask) tuple and expects a float image. Feed the returned image into the correlation step — it already has the masked region zeroed. Do not multiply the original frame by mask : masking is already applied, and for method="edges" the mask comes back as uint8 0/255 rather than boolean, so multiplying rescales the image by 255. Multi Pass Processing Multi pass (window deformation) lives in openpiv.windef , driven by a PIVSettings dataclass. pyprocess has no multi pass entry point. simple multipass already validates, replaces outliers, fills remaining NaNs with zeros, and calls transform coordinates — do not repeat those steps. Units trap: PIVSettings has dt and scaling factor fields, but windef never uses either — first pass calls extended search area piv without dt , so the whole multi pass chain works in pixels per frame. Setting settings.dt = 0.02 changes nothing about the returned values. Convert after the fact, as above. For control over individual passes, windef.first pass and windef.multipass img deform are the lower level building blocks. Validation and Post Processing Validation Methods Every validator returns a boolean array where True marks a spurious vector . Set these thresholds in the units of u and v , not in pixels per frame. extended search area piv divides by dt , so with dt=0.02 a 3 px/frame displacement arrives as 150 px/s. The thresholds above suit that case; the ( 30, 30) figure that PIV literature and PIVSettings.min max u disp use is a px/frame limit, and applying it to px/s output rejects the entire field. Either validate before scaling, or scale the thresholds by 1/dt too. Outlier Replacement method accepts "localmean" , "disk" , or "distance" — and only those three. An unrecognized name is not rejected; it falls through to an all zero kernel and silently returns a useless field. Note that replacement fills the flagged positions with interpolated values — if you then overwrite them with NaN, the replacement was wasted. Choose one or the other: Smoothing Smoothing is openpiv.smoothn.smoothn ; there is no openpiv.smooth module. It returns a tuple whose first element is the smoothed field, and it does not accept NaN input. Visualization Vector Field Plotting display vector field reads a saved vectors file and calls plt.show() internally, so select a non interactive backend for batch runs. Custom Visualization Analysis Functions scripts/analyze.py bundles these against a params.npz written by runner.py . It infers the physical grid spacing from the saved coordinates, so the derivatives come out per unit length: The standalone forms, if you would rather compute them inline: Vorticity The grid spacing is (window size overlap) / scaling factor in physical units, so leaving dx=1.0 yields vorticity per grid cell, not per unit length. Sign convention: runner.py ends with transform coordinates , which relabels the grid into a right handed y up frame but leaves the rows in image order, so the saved y decreases as the row index grows. The standalone forms above assume the opposite, so on a params.npz field they return du/dy and flip the sign of the vorticity and the shear strain — negate the axis=0 derivatives, or use PIVAnalyzer , which reads the orientation off the saved coordinates. Strain Rate Turbulence Statistics Caveat: subtracting the spatial mean of one frame measures spatial variance, which equals turbulent intensity only for a homogeneous field. Genuine Reynolds decomposition needs an ensemble of image pairs: average over the time axis, then subtract that mean field from each realization. CLI Usage CLI Options Option Default Description image required Image file; specify exactly twice for the pair output dir results Output directory (created if absent) window size 32 Interrogation window size (px) overlap 12 Window overlap (px) search area 38 Search area size (px), must be ≥ window size dt 0.02 Time between frames (s) scaling 96.52 Scaling factor, pixels per physical unit (e.g. px/mm) threshold 1.05 peak2peak signal to noise threshold mask none none or dynamic ( openpiv.preprocess.dynamic masking ) mask method intensity edges or intensity , used only with mask dynamic drop invalid off NaN out flagged vectors instead of keeping interpolated values verbose off Print progress messages Verify an install end to end against OpenPIV's own bundled image pair: Output Files vectors.txt — tab delimited, %.4e formatted, with a x y u v flags mask comment header params.npz — NumPy archive with x , y , u , v , flags arrays vector field.png — vector field drawn over the first frame flags is written as a float, 0 for a valid vector and 1 for a flagged one. Best Practices Parameter Selection 1. Window size — 32×32 suits most cases. 64/128 for better correlation at coarser resolution; 16/24 for finer resolution at the cost of noise. 2. Overlap — 50–75% of window size. 3. Threshold — raise it to reject more vectors; always re tune after switching sig2noise method . 4. Scaling factor — calibrate against a known reference such as a calibration grid, and keep the units straight ( 96.52 in OpenPIV's test1 tutorial data is px/mm). Image Quality Particles visible and evenly distributed, 5–10 per interrogation window No saturated or overexposed regions Minimal background noise; consider background subtraction across a run Processing Tips 1. Start from the defaults, then tune against the vector field you get. 2. Inspect the s2n distribution — a low median means poor correlation, not a bad threshold. 3. Visualize early; obvious problems (uniform vectors, edge artifacts) show up immediately. 4. Use multi pass ( windef ) for flows with large velocity gradients or displacements. 5. Mask reflections and solid boundaries rather than letting them generate vectors. Resources references/ advanced algorithms.md — correlation and subpixel methods, multi pass window deformation, PIVSettings fields, 3D and phase separation modules Load the reference when detailed algorithm or settings information is needed.