Skip to content
Get packs

Guide · Agent skill

How to use the OpenPIV agent skill for PIV flow measurement

Updated · written with AI from the project's own documentation and checked against our catalogue data

OpenPIV is an open-source Python library for Particle Image Velocimetry (PIV), a lab method that films tracer particles in a flowing fluid twice in quick succession and measures how far they moved. This OpenPIV skill teaches an AI agent how to run that analysis on your image pairs: choosing window sizes, cross-correlating frames, filtering bad vectors, scaling results to physical units and deriving vorticity or strain rate. This guide shows you how to install the skill, ask for the work in plain language and check the output before you rely on it.

OpenPIV Flow MeasurementK-Dense-AI/scientific-agent-skills · MIT

Quick start

  1. 1Install Python and openpiv. Make sure Python 3.10 or newer is available, then run uv pip install openpiv. numpy, scipy, scikit-image and matplotlib are installed as dependencies.
  2. 2Download the skill ZIP. Download the OpenPIV skill ZIP from this page.
  3. 3Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. The folder should be named openpiv and contain SKILL.md.
  4. 4Or upload it in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP instead.
  5. 5Ask for an analysis in plain language. Describe your image pair, time step dt and physical scale, and say what you want: velocity field, validation, vorticity or strain rate.
  6. 6Check flags and masks. Review the validation flags and masks before using the numbers. Treat replaced vectors as interpolated, not measured.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions and helper files that an AI agent loads when a task matches the skill's description. The main file, SKILL.md, tells the agent what the skill covers and how to carry out the work.

The OpenPIV skill makes the agent work with experimental PIV or flow-visualization image pairs. It covers preprocessing, cross-correlation, vector validation, outlier replacement, smoothing and scaling to physical units. It also covers deriving vorticity, strain rate and turbulence statistics from measured velocity fields. It is for measuring flow, not simulating it: the SKILL.md says to use a CFD skill for simulation.

  • Extracts 2D velocity fields from PIV image pairs with the OpenPIV Python library
  • Helps set interrogation window size, overlap and search area
  • Validates vectors (signal-to-noise, global range, local median) and replaces spurious ones
  • Converts pixel displacements to physical units and derives vorticity, strain rate and turbulence statistics
  • Includes a command-line runner and helper scripts that save results and plots

How do you install the OpenPIV skill?

Download the skill ZIP from this page. You can then install it in one of two ways.

For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. The skill folder should be named openpiv and contain SKILL.md, so the agent can find it.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

The skill needs Python 3.10 or newer with the openpiv package installed. Install it with uv:

  • Personal: unzip into ~/.claude/skills/
  • Project: unzip into .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills → upload the ZIP
uv pip install openpiv

How do you trigger the skill with a natural request?

You do not need to name the skill. The agent loads it when your request matches the skill's description, which covers extracting velocity fields from PIV image pairs, cross-correlating interrogation windows, validating and replacing spurious vectors, and computing vorticity, strain rate or turbulence statistics from measured velocity fields.

Be specific about your data. Say what the images are, where they are, what the time step between frames is and what physical scale applies. The more of this you give, the fewer parameters the agent has to guess.

  • "Compute the velocity field from frame_a.bmp and frame_b.bmp, dt is 0.02 s, and the scale is 96.52 pixels per mm."
  • "Validate the vectors in this PIV result and replace outliers with local means."
  • "Calculate vorticity and strain rate from vectors.txt."
  • "Process these lab PIV pairs with multi-pass windows 64, 32, 16 and save plots."

What does a basic PIV run look like?

The core steps are the same whichever way you run it. The agent reads both frames, runs extended-search-area cross-correlation with a window size and overlap you choose, marks spurious vectors using signal-to-noise, replaces them, then scales and saves the result. Here is the basic OpenPIV pattern the skill is built on:

  • Window size sets the correlation window in pixels; larger windows are more robust but spatially coarser
  • Overlap is the number of pixels shared by adjacent windows and must be smaller than the search area
  • Keep the largest displacement under about a quarter of the window size
u, v, s2n = pyprocess.extended_search_area_piv(frame_a.astype(np.float32), frame_b.astype(np.float32), window_size=32, overlap=12, dt=0.02, search_area_size=38, correlation_method="linear", normalized_correlation=True, backend="scipy", sig2noise_method="peak2peak")

How do you use the bundled command-line runner?

The skill includes a runner script that checks inputs, preserves masks and processing parameters, and saves the output. Run it from the root of the folder that contains the skills directory, or adjust the path to where you unzipped the skill. Ask the agent to run it for you, or run it yourself to get reproducible results.

The runner is in scripts/runner.py with a helper analyze.py, a run_example.py script and an __init__.py file. The skill also includes references/advanced_algorithms.md for correlation methods and settings.

  • Inputs: two image files passed with --image
  • Output: a folder given by --output_dir, with --verbose for progress messages
  • Masks are sampled at interrogation centres, saved, and kept as NaN after replacement
python skills/openpiv/scripts/runner.py --image frame_a.bmp --image frame_b.bmp --output_dir results --verbose

How do you check and trust the results?

The skill returns flags that mark spurious vectors. Keep them. Repaired or zero-filled output is not an independent measurement, and a flagged vector should not be reported as a measured value. Signal-to-noise thresholds depend on the method: peak2peak thresholds are typically 1.05 to 1.3, and a threshold for one method is meaningless for the other.

Inspect masks on both frames before analysis. Windows that straddle an object can still be biased, so check the mask for your experiment. Parameters and thresholds need expert review for each experiment before you draw conclusions from the output.

  • Keep the validation flags with every result
  • Check that the signal-to-noise method matches the threshold you use
  • Inspect masks on both frames before running the analysis
  • Review the parameters for each new experiment

What people use it for

  • Measuring the velocity field in a water-channel experiment from seeded particle image pairs
  • Comparing window sizes and overlap to see how they change the resulting vector field, as a teaching exercise
  • Cleaning a measured PIV dataset by validating vectors and replacing outliers with local means
  • Deriving vorticity and strain rate from a measured 2D velocity field for a flow visualization study

Frequently asked questions

Is the OpenPIV skill free to use?

The licence listed for this skill on the page is MIT. The SKILL.md frontmatter, however, names BSD-3-Clause, so check the licence file in the downloaded folder before you rely on either. OpenPIV itself is installed from the openpiv Python package.

What do I need to run the OpenPIV skill?

You need Python 3.10 or newer with the openpiv package installed using uv pip install openpiv. numpy, scipy, scikit-image and matplotlib arrive as dependencies. The source says no network access is needed after install.

Where do I put the skill so Claude can find it?

Unzip it into ~/.claude/skills/ for a personal install, or into .claude/skills/ in a project. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.

Can OpenPIV simulate fluid flow with CFD?

No. The skill is for measured experimental PIV or flow-visualization image pairs. The SKILL.md says that for simulating flow rather than measuring it, you should use a CFD skill instead.

Why does my PIV result have NaN or flagged vectors?

Flagged vectors are spurious by the validation checks, and NaN values appear where the signal-to-noise or outlier checks fail or where a mask applies. Check your window size, overlap, displacement size and signal-to-noise method. Do not treat replaced vectors as measurements.

How does this compare with other PIV tools?

The source does not compare OpenPIV with other PIV tools, so this guide cannot make that comparison. The skill is for running the OpenPIV Python library on measured images, and it includes a command-line runner and helper scripts that save results and plots.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you process measured lab PIV image pairs, want to tune window and validation settings, or are learning how those parameters change a velocity field. Pick a different tool if you need simulated flow from CFD, or if you need safety-critical decisions made from output you have not reviewed with an expert.

Download the skill