openpiv

Extract velocity fields from PIV image pairs using cross-correlation analysis.

41.1k|3.8k|Updated Oct 19, 2025
One-click install
npx skills add https://github.com/K-Dense-AI/scientific-agent-skills --skill openpiv
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: openpiv
Source: https://github.com/K-Dense-AI/scientific-agent-skills/tree/main/skills/openpiv
Command: npx skills add https://github.com/K-Dense-AI/scientific-agent-skills --skill openpiv

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires openpiv, numpy, matplotlib, scipy, scikit-image, and includes scripts (resource) and references (resource) components.

What problem does it solve?

Measuring fluid velocity from experimental Particle Image Velocimetry image pairs requires cross-correlation, vector validation, outlier replacement, and unit scaling, which is error-prone to implement from scratch and easy to misconfigure across OpenPIV versions.

Core Features & Use Cases

  • PIV Cross-Correlation: Run single-pass or multi-pass window-deformation analysis on image pairs with tunable window size, overlap, and search area.
  • Vector Validation & Post-Processing: Flag spurious vectors via signal-to-noise, global range, and local median tests, then replace outliers or mask them as NaN.
  • Derived Quantities: Compute vorticity, strain rate, and turbulence statistics from saved velocity fields with correct grid spacing and axis orientation.
  • Use Case: Given a pair of PIV images from a wind tunnel experiment, run the bundled CLI to produce a scaled vector field plot, a vectors.txt file, and a params.npz archive ready for vorticity and turbulence analysis.

Quick Start

Use the openpiv skill to analyze my PIV image pair frame_a.bmp and frame_b.bmp and generate the velocity vector field with vorticity statistics.

Frequently Asked Questions about openpiv

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I extract velocity fields from PIV image pairs in Python?

Use openpiv's pyprocess.extended_search_area_piv to cross-correlate interrogation windows between two frames, then validate vectors with sig2noise_val and replace outliers with filters.replace_outliers. The bundled runner.py script wraps this full pipeline as a CLI.

What window size and overlap should I use for PIV analysis?

A 32x32 pixel window suits most cases, with overlap at 50-75% of window size. Keep the largest displacement under about a quarter of the window size and aim for 5-10 particles per interrogation window.

Does OpenPIV support multi-pass window deformation?

Yes, openpiv.windef.simple_multipass runs multi-pass analysis with decreasing window sizes driven by a PIVSettings dataclass. Note that its output is in pixels per frame, so you must apply dt and scaling factor conversion yourself afterward.

Why does my PIV validation reject all vectors?

Thresholds must match the units of your velocity output. extended_search_area_piv divides by dt, so px/frame thresholds like (-30, 30) reject everything when applied to px/s output; scale thresholds by 1/dt or validate before scaling.

When should I use circular vs linear correlation in OpenPIV?

Use linear correlation whenever search_area_size exceeds window_size, since circular correlation relies on FFT wrap-around and aliases large displacements into small ones. Circular is faster but only safe for small displacements.

Can OpenPIV compute vorticity and turbulence statistics?

Yes, the skill's PIVAnalyzer class computes vorticity, strain rate, and single-frame statistics from a saved params.npz, inferring physical grid spacing and axis orientation from the coordinates. True Reynolds decomposition requires an ensemble of image pairs averaged over time.