Skip to main content

PIVPy PIVPy

Python-based post-processing PIV data analysis in the repo: https://github.com/openpiv/pivpy

PyPI version Documentation Status Open in molab

Merging the three packages:

  1. https://github.com/tomerast/Vecpy
  2. https://github.com/alexlib/pivpy/tree/xarray
  3. https://github.com/ronshnapp/vecpy

How do I get set up?

Recommended: use uv (fast, reproducible)

Create a virtualenv and install:

uv venv
uv pip install pivpy

Install this repository (editable / development install):

uv venv
uv pip install -e .

Install with optional dependencies (including lvpyio for LaVision VC7):

uv pip install 'pivpy[full]'

Run in a sandbox (isolated) environment (no persistent venv required):

uv run --isolated --with pivpy python -c "import pivpy; print(pivpy.__version__)"

Or run with optional dependencies in the sandbox:

uv run --isolated --with "pivpy[full]" python -c "from pivpy import io; print(io)"

Run using a specific Python version (uv-managed) in the sandbox:

uv python install 3.14
uv run --isolated --managed-python -p python3.14 --with pivpy python -c "import sys, pivpy; print(sys.version.split()[0], pivpy.__version__)"

Run this repository's tests on Python 3.14 (sandboxed):

uv run --isolated --managed-python -p python3.14 --with-editable . pytest -q

Alternative: use pip:

pip install pivpy

or with optional dependencies:

pip install 'pivpy[full]'

if you use OpenPIV, PIVlab, etc.

Quick start (auto-detect file format):

from pivpy import io
ds = io.read_piv('your_file.vec')

Getting Started

Load experimental PIV data or generate analytical flow fields, and visualize publication-quality flow fields with zero effort:

import matplotlib.pyplot as plt
import pivpy.pivpy  # registers the .piv accessor
from pivpy import synthetic

# 1. Generate an analytical multi-vortex 2D turbulence field (or use io.read_piv)
ds = synthetic.multivortex(n_frames=1, n=128, n_vortices=8, two_d=True, seed=42)

# 2. One call, publication-quality figure: smooth RdBu_r vorticity field with
#    dense black streamlines and small direction arrows, no axes or margins
fig, ax = ds.piv.streamscal()
fig.savefig("flow.png", dpi=300)

PIVPy streamlines over vorticity

streamscal needs no tuning for a finished figure. Pick another colour quantity with scalar="speed", "u", "divergence" or any dataset variable, and make the figure lighter with density=1.5.

Side-by-side panels

streamscal_panels packs several fields into one figure with a thin white gap and a shared colour scale, so the panels can be compared directly:

from pivpy import graphics

ds = synthetic.vortex_pair(n_frames=24, n=128)
fig, axs = graphics.streamscal_panels(
    [ds.isel(t=0), ds.isel(t=23)], labels=["(a)", "(b)"], figwidth=10
)
fig.savefig("panels.png", dpi=300)

Two streamline panels with a shared colour scale

Dynamic Flow Animations

Animate time-series datasets with in-place vector updates (set_UVC) and dynamic vorticity tracking:

# 1. Generate or load time-series flow data (e.g. interacting vortex pair)
ds = synthetic.vortex_pair(n_frames=24, n=128)

# 2. Animate with one call
anim = ds.piv.animate(interval=80)

# Save as GIF / MP4 or display in Jupyter / Marimo
anim.save("vortex_interaction.gif")

PIVPy Flow Animation

Vectors, backgrounds and other layers with plot()

For velocity vectors, image backgrounds and colorbars use ds.piv.plot(). Every visual layer can be tailored or toggled:

# Velocity magnitude background with vectors only (no streamlines)
fig, ax = ds.piv.plot(
    background="mag",       # 'vorticity' (default), 'mag', 'ke', 'divergence', or None
    streamlines=False,      # toggle flow streamlines
    quiver=True,            # toggle velocity vectors
    blur=1.5,               # smooth fluid color gradient
    arrow_scale=0.75,       # custom vector arrow scale
    title="Velocity Magnitude & Vectors",
)

# Clean vector quiver only (no background)
fig, ax = ds.piv.plot(background=None)

Legacy loaders (still supported):

ds = io.load_vec('your_file.vec')
ds = io.load_openpiv_txt('your_file.txt')

Check whether a newer version is available on PyPI:

import pivpy
res = pivpy.check_update(verbose=True)
# res.status: 0=unavailable, 1=up-to-date, 2=update available, 3=installed newer

PIVMat-inspired methods

PIVPy exposes many post-processing operations via the xarray accessor Dataset.piv. Several common PIVMat toolbox methods are available with similar names/behavior:

import pivpy.pivpy  # registers the .piv accessor
from pivpy import io

ds = io.create_sample_Dataset(n_frames=10)

# Add noise (similar to PIVMat addnoisef)
ds_noisy = ds.copy().piv.addnoisef(eps=0.1, opt='add', nc=0.0, seed=0)

# Ensemble (temporal) average and optional std/rms (similar to PIVMat averf)
avg = ds.piv.averf()
avg, std, rms = ds.piv.averf(return_std_rms=True)

# Spatial averages (similar to PIVMat spaverf)
ds_xy = ds.piv.spaverf('xy')   # excludes zeros by default
ds_x0 = ds.piv.spaverf('x0')   # include zeros

# Subtract ensemble/spatial average (similar to PIVMat subaverf)
fluct = ds.piv.subaverf('e')
fluct_x = ds.piv.subaverf('x0')

# Azimuthal averaging (similar to PIVMat azaverf)
r, ur, ut = ds.isel(t=0).piv.azaverf(0.0, 0.0, return_profiles=True)

# Temporal resampling and phase average (similar to PIVMat resamplef/phaseaverf)
ds_r = ds.piv.resamplef(tini=range(ds.sizes['t']), tfin=[0.5, 1.5, 2.5])
phased = ds.piv.phaseaverf(12)

Additional PIVMat-inspired utilities:

# Correlation along a dimension (similar to PIVMat corrm/corrx)
cu = ds.piv.corrm(variable='u', dim='x')        # returns DataArray with a 'lag' dimension
cv = ds.piv.corrm(variable='v', dim='y', half=True)

# Spatial correlation function + integral scales (similar to PIVMat corrf)
cor = ds.piv.corrf(variable='u', dim='x', normalize=True)
# correlation curve: cor['f'] over cor['r']
# integral scales: cor['isinf'], cor['is5'], cor['is2'], cor['is1'], cor['is0']

# Fill holes encoded as zeros (similar to PIVMat interpolat.m behavior)
ds_filled = ds.piv.fill_zeros(max_iter=10)

# Extract a rectangular region (similar to PIVMat extractf)
sub = ds.piv.extractf([0.0, 0.0, 10.0, 5.0], 'phys')   # [x1,y1,x2,y2] in physical units
sub = ds.piv.extractf([10, 5, 50, 40], 'mesh')         # 1-based mesh indices (MATLAB-like)

# Spatial convolution filter (similar to PIVMat filterf)
ds_smooth = ds.piv.filterf(1.0, 'gauss', 'same')   # keep same size
ds_smooth_valid = ds.piv.filterf(1.0, 'gauss')     # smaller (conv2(...,'valid') behavior)

# Flip field (similar to PIVMat flipf)
ds_lr = ds.piv.flipf('x')     # left-right mirror (negates u)
ds_tb = ds.piv.flipf('y')     # top-bottom mirror (negates v)
ds_xy = ds.piv.flipf('xy')    # both

# 2D Butterworth filter (similar to PIVMat bwfilterf)
ds_low = ds.piv.bwfilterf(filtsize=3.0, order=8.0, mode='low', trunc=True)
ds_high = ds.piv.bwfilterf(filtsize=3.0, order=8.0, mode='high')

# PIVMat-style option wrapper: opts can include 'high'/'low'/'trunc'
ds_high2 = ds.piv.bwfilterf_pm(3.0, 8.0, 'high', 'trunc')

# Batch processing over filename series (similar to PIVMat batchf)
# fun can be a callable (fun(ds, ...)) or an accessor method name (e.g. 'averf', 'bwfilterf')
from pivpy.io import batchf
results = batchf('pivpy/data/day2/day2a00500[0:5].T000.D000.P003.H001.L.vec', 'averf')

For developers, local use:

Using uv (recommended):

git clone https://github.com/alexlib/pivpy .
cd pivpy
uv venv
uv pip install -e .

Editable install with optional dependencies:

uv pip install -e '.[full]'

Alternative (conda):

git clone https://github.com/alexlib/pivpy .
cd pivpy
conda create -n pivpy python=3.11
conda activate pivpy
conda install pip
pip install -e .

What packages are required and which are optional

  1. lvpyio by Lavision Inc. if you use vc7 files
  2. netcdf4 if you want to store NetCDF4 files by xarray
  3. pyarrow if you want to store parquet files
  4. vortexfitting if you want to do vortex analysis ($\lambda_2$ and $Q$ criterions, vortex fitting)
  5. numpy, scipy, matplotlib, xarray are must and installed with the pivpy

Contributors

  1. @alexlib
  2. @ronshnapp - original steps
  3. @liorshig - LVreader and great visualizaiton for Lavision
  4. @nepomnyi - connection to VortexFitting and new algorithms

How to get started?

Look into the getting started marimo notebook (open it with uv run marimo edit examples/notebooks/Getting_Started.py, or click the "Open in molab" badge above to run it in your browser)

and additional notebooks: Notebooks

How to test?

From a command line just use:

pytest

With uv:

uv run pytest -q

Documentation

How to help?

Read the ToDo file and pick one item to program. Use Fork-Develop-Pull Request model to contribute

How to write tutorials and add those to the documentation

Tutorials live as marimo notebooks (.py files) in docs/source/. The docs are built with MkDocs (mkdocs.yml, pages under docs_mkdocs/); the mkdocs-marimo plugin embeds them live (editable, running in the browser via Pyodide) -- no separate conversion step needed:

uv pip install -r docs_mkdocs/requirements.txt
uv run mkdocs build

generates a site/ directory with the documentation. uv run mkdocs serve runs a live-reloading local preview.

Metadata

Release files for pivpy 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pivpy 0.4.0
File Size Uploaded Provenance Actions
pivpy-0.4.0.tar.gz 6.9 MB Without provenance Details for pivpy-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pivpy 0.4.0
File Interpreter ABI Platform Actions
pivpy-0.4.0-py3-none-any.whl Python 3 none any Details for pivpy-0.4.0-py3-none-any.whl

Total release size: 13.7 MB

Release files / pivpy-0.4.0.tar.gz

Download URL pivpy-0.4.0.tar.gz
Size 6.9 MB
Tags Source
SHA-256 checksum
How to use checksums
900aa9abef91a284f07221327d32986f4a9a70b960a9491fea796ea1a9de7f18
BLAKE2b-256 checksum
How to use checksums
30c1fdb0a3c6ada7d9d84ac56745b777f580c3c237f2e976cd649bc2a7c1d0f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / pivpy-0.4.0-py3-none-any.whl

Download URL pivpy-0.4.0-py3-none-any.whl
Size 6.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
0de26a373d06a163a631ec7f93f80b926fd37f6b2122eefe02a0ba2200294255
BLAKE2b-256 checksum
How to use checksums
c7567783c82ac22b150104ff3440d6670443084926bb8acde14dd228287216aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for pivpy 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page