科研 Skill
粒子图像测速分析
openpiv
Extracts velocity fields from PIV image pairs with OpenPIV: cross-correlation, vector validation, vorticity/strain-rate statistics. Use for experimental fluid-flow measurement.
SKILL.md
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:
uv pip install openpiv
# Pin it when the analysis needs to be reproducible -- this is the version every
# snippet below was checked against.
uv pip install "openpiv==0.25.4"
Run PIV analysis on an image pair:
import numpy as np
from openpiv import tools, pyprocess, validation, filters, scaling
frame_a = tools.imread("image_a.bmp")
frame_b = tools.imread("image_b.bmp")
# Cross-correlate. Returns (u, v, s2n) whenever sig2noise_method is not None.
u, v, s2n = pyprocess.extended_search_area_piv(
frame_a.astype(np.int32),
frame_b.astype(np.int32),
window_size=32,
overlap=12,
dt=0.02,
search_area_size=38,
correlation_method="linear", # required for search_area_size > window_size
sig2noise_method="peak2peak",
)
x, y = pyprocess.get_coordinates(
image_size=frame_a.shape,
search_area_size=38,
overlap=12,
)
# flags is a boolean array: True marks a spurious vector.
flags = validation.sig2noise_val(s2n, threshold=1.05)
u, v = filters.replace_outliers(u, v, flags, method="localmean", max_iter=3, kernel_size=2)
# Scale to physical units, then flip to image coordinates for plotting.
x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor=96.52)
x, y, u, v = tools.transform_coordinates(x, y, u, v)
tools.save("vectors.txt", x, y, u, v, flags)
Or use the bundled CLI, which wraps exactly that pipeline:
python skills/openpiv/scripts/runner.py \
--image frame_a.bmp --image frame_b.bmp --output_dir results --verbose
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:
- Capture an image pair (
frame_a,frame_b) separated by a known timedt. - Divide the images into interrogation windows.
- Cross-correlate matching windows to find peak displacement.
- Validate vectors (signal-to-noise, global range, local median).
- Replace spurious vectors with interpolated values.
- 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.
flags = validation.sig2noise_val(s2n, threshold=1.05)
# flags is bool: True == spurious. `~flags` selects the good vectors.
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.
from openpiv import preprocess
# method="edges" for dark, sharp-edged objects; "intensity" for high-contrast objects.
frame_a_masked, mask_a = preprocess.dynamic_masking(
frame_a.astype(np.float64), method="intensity", filter_size=7, threshold=0.005
)
frame_b_masked, mask_b = preprocess.dynamic_masking(
frame_b.astype(np.float64), method="intensity", filter_size=7, threshold=0.005
)
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.
import numpy as np
from openpiv import scaling, windef
settings = windef.PIVSettings()
settings.windowsizes = (64, 32, 16) # one entry per pass, decreasing (this is also the default)
settings.overlap = (32, 16, 8) # same length as windowsizes
settings.num_iterations = 3 # number of passes to actually run
settings.sig2noise_threshold = 1.05
x, y, u, v, flags = windef.simple_multipass(
frame_a.astype(np.int32), frame_b.astype(np.int32), settings
)
# Output is in PIXELS PER FRAME -- convert yourself. scaling.uniform only divides
# by scaling_factor, so apply dt separately.
dt = 0.02
x, y, u, v = scaling.uniform(x, y, u, v, scaling_factor=96.52)
u, v = u / dt, v / dt
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.
# Signal-to-noise
flags = validation.sig2noise_val(s2n, threshold=1.05)
# Global range -- takes (min, max) TUPLES, positionally or as u_thresholds/v_thresholds.
flags = validation.global_val(u, v, (-300, 300), (-300, 300))
# Local median -- u_threshold and v_threshold are REQUIRED; size is the neighbourhood half-width.
flags = validation.local_median_val(u, v, u_threshold=30.0, v_threshold=30.0, size=1)
# Combine with boolean OR (not np.maximum -- these are bool arrays).
flags = (
validation.sig2noise_val(s2n, threshold=1.05)
| validation.global_val(u, v, (-300, 300), (-300, 300))
| validation.local_median_val(u, v, u_threshold=30.0, v_threshold=30.0)
)
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
u, v = filters.replace_outliers(
u, v, flags, method="localmean", max_iter=3, tol=1e-3, kernel_size=2
)
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:
# Keep flagged vectors out of the analysis entirely, instead of interpolating them.
u = np.where(flags, np.nan, u)
v = np.where(flags, np.nan, v)
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.
from openpiv.smoothn import smoothn
u_smooth, *_ = smoothn(np.nan_to_num(u), s=0.5) # s: larger == smoother
v_smooth, *_ = smoothn(np.nan_to_num(v), s=0.5)
u_smooth = np.asarray(u_smooth)
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.
import matplotlib
matplotlib.use("Agg")
import matplotlib.pyplot as plt
from openpiv import tools
fig, ax = plt.subplots(figsize=(8, 8))
tools.display_vector_field(
"vectors.txt",
ax=ax,
scaling_factor=96.52, # same factor used in scaling.uniform, to map back onto the image
scale=50,
width=0.0035,
on_img=True,
image_name="frame_a.bmp",
)
fig.savefig("vector_field.png", dpi=150, bbox_inches="tight")
plt.close(fig)
Custom Visualization
import numpy as np
import matplotlib.pyplot as plt
fig, axes = plt.subplots(1, 3, figsize=(15, 5))
mag = np.sqrt(u**2 + v**2)
for ax, field, title, cmap in [
(axes[0], mag, "Velocity Magnitude", "viridis"),
(axes[1], u, "U Velocity", "RdBu_r"),
(axes[2], v, "V Velocity", "RdBu_r"),
]:
im = ax.imshow(field, cmap=cmap)
ax.set_title(title)
plt.colorbar(im, ax=ax)
fig.tight_layout()
fig.savefig("velocity_components.png")
plt.close(fig)
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:
import sys
sys.path.insert(0, "skills/openpiv/scripts")
from analyze import PIVAnalyzer
piv = PIVAnalyzer("results/params.npz")
vorticity = piv.compute_vorticity() # dv/dx - du/dy
exx, eyy, exy = piv.compute_strain()
stats = piv.compute_statistics() # u_mean, v_mean, rms_u, rms_v, tke
piv.plot_vector_field(save_path="quiver.png")
The standalone forms, if you would rather compute them inline:
Vorticity
def compute_vorticity(u, v, dx=1.0, dy=None):
"""Out-of-plane vorticity dv/dx - du/dy. Pass the physical grid spacing, not 1.0."""
dy = dx if dy is None else dy
return np.gradient(v, dx, axis=1) - np.gradient(u, dy, axis=0)
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
def compute_strain(u, v, dx=1.0, dy=None):
"""Return (exx, eyy, exy) of the 2D strain-rate tensor."""
dy = dx if dy is None else dy
du_dx = np.gradient(u, dx, axis=1)
du_dy = np.gradient(u, dy, axis=0)
dv_dx = np.gradient(v, dx, axis=1)
dv_dy = np.gradient(v, dy, axis=0)
return du_dx, dv_dy, 0.5 * (du_dy + dv_dx)
Turbulence Statistics
def compute_statistics(u, v):
"""Single-frame spatial statistics. NOT Reynolds decomposition."""
u_prime = u - np.nanmean(u)
v_prime = v - np.nanmean(v)
rms_u, rms_v = np.nanstd(u_prime), np.nanstd(v_prime)
return {
"u_mean": np.nanmean(u),
"v_mean": np.nanmean(v),
"rms_u": rms_u,
"rms_v": rms_v,
"tke": 0.5 * (rms_u**2 + rms_v**2),
}
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
# Basic run
python skills/openpiv/scripts/runner.py \
--image img1.bmp --image img2.bmp --output_dir results --verbose
# Tuned parameters with dynamic masking
python skills/openpiv/scripts/runner.py \
--image frame_a.bmp \
--image frame_b.bmp \
--output_dir results \
--window_size 32 \
--overlap 12 \
--search_area 38 \
--dt 0.02 \
--scaling 96.52 \
--threshold 1.05 \
--mask dynamic \
--mask_method intensity \
--verbose
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:
python skills/openpiv/scripts/run_example.py --output_dir /tmp/openpiv-demo
Output Files
- vectors.txt — tab-delimited,
%.4eformatted, with a# x y u v flags maskcomment header - params.npz — NumPy archive with
x,y,u,v,flagsarrays - vector_field.png — vector field drawn over the first frame
# x y u v flags mask
2.1757e-01 3.5226e+00 -6.2220e-02 -2.7081e+00 0.0000e+00 0.0000e+00
4.8695e-01 3.5226e+00 -3.1587e-01 -2.9800e+00 0.0000e+00 0.0000e+00
flags is written as a float, 0 for a valid vector and 1 for a flagged one.
Best Practices
Parameter Selection
- 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.
- Overlap — 50–75% of window size.
- Threshold — raise it to reject more vectors; always re-tune after switching
sig2noise_method. - Scaling factor — calibrate against a known reference such as a calibration grid, and keep the
units straight (
96.52in OpenPIV'stest1tutorial 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
- Start from the defaults, then tune against the vector field you get.
- Inspect the
s2ndistribution — a low median means poor correlation, not a bad threshold. - Visualize early; obvious problems (uniform vectors, edge artifacts) show up immediately.
- Use multi-pass (
windef) for flows with large velocity gradients or displacements. - Mask reflections and solid boundaries rather than letting them generate vectors.
Resources
references/
advanced_algorithms.md— correlation and subpixel methods, multi-pass window deformation,PIVSettingsfields, 3D and phase-separation modules
Load the reference when detailed algorithm or settings information is needed.
Related skills
scvelo: Performs RNA velocity analysis with scVelo on single-cell RNA-seq AnnData objects that have spliced and unspliced layers (from velocyto, ST…
示例提示词
帮我用OpenPIV从这组图像对中提取速度场并计算涡量。
所属插件
安装该插件会一并获得同领域的 22 个 Skill / MCP。
同插件的其他科研 Skill
- 天文星表检索Queries astronomical archives (Gaia, SDSS, VizieR, MAST, NED, SIMBAD) via astroquery/TAP/ADQL and cross-matches results. Use when sourcing or combining survey data by position.
- 天文光谱分析Reduces 1D astronomical spectra with specutils: continuum normalization, line fitting, redshift/radial-velocity measurement, equivalent widths. Use for spectral classification or velocity work.
- 天文观测数据分析Runs applied astronomy pipelines with astropy/astroquery: catalog cross-matching, Gaia/SIMBAD queries, aperture photometry, CMB power spectra. Use for end-to-end data-analysis workflows.
- Astropy天文数据处理Covers core Astropy APIs for units, coordinates, FITS I/O, tables, time systems, WCS, and cosmology. Use as the API reference, before reaching for applied workflows.
- 谷歌量子计算框架Builds noise-aware quantum circuits for Google Quantum AI hardware and runs characterization experiments. Use for Google-hardware targeting; use qiskit for IBM or pennylane for differentiable ML.
- 有限元法求解偏微分方程Solves PDEs with finite elements using FEniCS/dolfinx: weak forms, gmsh meshing, Poisson/elasticity problems, boundary conditions, ParaView export. Use for continuum-physics simulation.
- 计算流体力学模拟Runs pseudospectral CFD simulations in Python: Navier-Stokes, shallow water, stratified flows with FFT-based solvers. Use for turbulence, vortex dynamics, or geophysical flow simulation.
- LAMMPS经典分子动力学Runs classical molecular dynamics with LAMMPS: force field selection, NVT/NPT ensembles, RDF/MSD post-processing, OVITO visualization. Use for atomistic materials or molecular simulation.
- 三维科学可视化Creates 3D scientific visualizations with Mayavi: vector fields, isosurfaces, volume rendering, animated 3D plots. Use for visualizing volumetric or vector-field physics data.
- 蒙特卡洛物理模拟Simulates physical systems with Monte Carlo methods: statistical integration, MCMC sampling, the Ising model, error estimation. Use for stochastic physics simulation.
- 地震学数据处理Analyzes seismological data with ObsPy: FDSN waveform download, response removal, phase picking, moment tensor inversion. Use for earthquake and seismic-waveform analysis.
- 量子机器学习框架Trains quantum circuits with autodiff across IBM/Google/Rigetti/IonQ devices: VQE, QAOA, hybrid models with PyTorch/JAX. Use for gradient-based variational quantum algorithms.
- 恒星测光分析Performs PSF and aperture photometry with photutils: source detection, PSF fitting, background estimation, multi-epoch light curves. Use for precision stellar photometry beyond one aperture sum.
- 物理信息神经网络Builds physics-informed neural networks, neural ODEs, and data-driven force fields with PyTorch, DeepXDE, torchdiffeq. Use for ML-based physics simulation and surrogate modeling.
- IBM量子计算框架Runs IBM Quantum workflows end to end: Runtime primitives, transpilation, hardware backend selection, error mitigation. Use when targeting IBM Quantum hardware or Runtime.
- Qiskit量子线路实验Implements Qiskit algorithms: circuit construction, VQE/QAOA workflows, noise-model simulation, statevector-vs-shot comparisons. Use for algorithm design and local simulation.
- 开放量子系统模拟Simulates open quantum systems with QuTiP: master equations, Lindblad dynamics, decoherence, cavity QED. Use for open-system physics, not circuit-based quantum computing.
- SciPy数值计算工具Solves ODEs/PDEs, runs FFT analysis, optimization, and sparse linear algebra with SciPy for physics problems. Use as the general-purpose numerical-computing toolkit.
- SymPy符号计算Performs symbolic computation for physics with SymPy: algebra, calculus, Lagrangian mechanics, quantum operators, code generation. Use for exact derivations, not numerical solving.
- 物理量纲与不确定度传播Tracks physical units and propagates measurement uncertainty with pint/uncertainties: GUM budgets, Monte Carlo propagation, dimensionless-group checks. Use to sanity-check a result or unit.
- 多维标注数组NetCDF分析Analyzes labeled multi-dimensional arrays with xarray: NetCDF/HDF5 I/O, lazy Dask loading, rechunking, Zarr stores, CF conventions. Use for gridded scientific data handling.
常见问题
粒子图像测速分析能做什么?
Extracts velocity fields from PIV image pairs with OpenPIV: cross-correlation, vector validation, vorticity/strain-rate statistics. Use for experimental fluid-flow measurement。
如何安装粒子图像测速分析?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「粒子图像测速分析」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
粒子图像测速分析需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
粒子图像测速分析经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。