OpenPIV consists in a Python and Cython modules for scripting and executing the analysis of a set of PIV image pairs. In addition, a Qt and Tk graphical user interfaces are in development, to ease the use for those users who don't have python skills.
The OpenPIV python version is still in its beta state. This means that it still might have some bugs and the API may change. However, testing and contributing is very welcome, especially if you can contribute with new algorithms and features.
Click the link - thanks to BinderHub, Jupyter and Conda you can now get it in your browser with zero installation:
uv is a fast Python package installer and resolver written in Rust:
pip install uv
uv pip install openpiv
Use PyPI: https://pypi.python.org/pypi/OpenPIV:
pip install openpiv
Or with uv
uv add openpiv
If you previously installed OpenPIV via conda, you can migrate to pip or uv:
# Remove the conda package
conda remove openpiv
# Install with pip or uv
pip install openpiv
# or
uv pip install openpiv
Clone using git:
git clone https://github.com/OpenPIV/openpiv-python.git
cd openpiv-python
To build the Rust acceleration extension locally (requires Rust toolchain and maturin):
pip install maturin
maturin develop --release -m crates/openpiv_rust/Cargo.toml
pip install -e .
OpenPIV features a parallel dual-backend architecture designed for high throughput without sacrificing numerical reproducibility:
- ⚡ Parallel Rust Backend (
openpiv_rust): Multithreaded execution across all CPU cores using Rayon and real-to-complex FFTW/RustFFT routines. Delivers up to 580x faster outlier validation, 19x faster subpixel peak interpolation and SNR calculation, 4-6x faster windowing and FFT cross-correlation, and 3.7x faster end-to-end PIV pipelines. - 🐍 Pure Python / SciPy Backend: Complete, zero-dependency reference implementation that runs everywhere without a compiler.
When you install OpenPIV from PyPI via pip or uv, pre-compiled binary wheels with the Rust acceleration backend are installed automatically.
All core processing functions accept a backend parameter:
backend Option |
Behavior |
|---|---|
"auto" (default) |
Automatically selects the parallel Rust backend if available; cleanly and transparently falls back to pure Python/SciPy if not. |
"rust" |
Enforces the parallel Rust backend. Raises an informative ImportError if the Rust extension is not compiled. |
"scipy" (or "python") |
Enforces the pure Python/SciPy reference path. |
Both backends produce identical numerical results (diff = 0.0).
from openpiv import piv
# Default: auto-selects fast Rust backend with fallback
x, y, u, v, s2n = piv.simple_piv("exp1_001_a.bmp", "exp1_001_b.bmp", backend="auto")
# Explicitly force the parallel Rust backend
x, y, u, v, s2n = piv.simple_piv("exp1_001_a.bmp", "exp1_001_b.bmp", backend="rust")
# Explicitly force the SciPy reference backend
x, y, u, v, s2n = piv.simple_piv("exp1_001_a.bmp", "exp1_001_b.bmp", backend="scipy")from openpiv import pyprocess, tools
frame_a = tools.imread("exp1_001_a.bmp")
frame_b = tools.imread("exp1_001_b.bmp")
# Run with parallel Rust acceleration
u, v, s2n = pyprocess.extended_search_area_piv(
frame_a,
frame_b,
window_size=32,
overlap=16,
search_area_size=32,
correlation_method="circular",
backend="rust", # 'auto', 'rust', or 'scipy'
)from openpiv import windef, tools
settings = windef.PIVSettings()
settings.windowsizes = (64, 32, 16)
settings.overlap = (32, 16, 8)
settings.num_iterations = 3
# Choose backend in PIVSettings: 'auto', 'rust', or 'scipy'
settings.backend = "auto"
frame_a = tools.imread("exp1_001_a.bmp")
frame_b = tools.imread("exp1_001_b.bmp")
# Executes all deformation passes with the chosen backend
x, y, u, v, mask = windef.simple_multipass(frame_a, frame_b, settings)The OpenPIV documentation is available on the project web page at http://openpiv.readthedocs.org
- Tutorial Notebook 1
- Tutorial notebook 2
- Dynamic masking tutorial
- Multipass with Windows Deformation
- Multiple sets in one notebook
- 3D PIV
These and many additional examples are in another repository: OpenPIV-Python-Examples
- Alex Liberzon
- Roi Gurka
- Zachary J. Taylor
- David Lasagna
- Mathias Aubert
- Pete Bachant
- Cameron Dallas
- Cecyl Curry
- Theo Käufer
- Andreas Bauer
- David Bohringer
- Erich Zimmer
- Peter Vennemann
- Lento Manickathan
- Yuri Ishizawa
Smoothing: smoothn.py provides scalar field smoothing for velocity fields (1D, 2D, and N-D) with support for missing data (NaNs) and masked arrays using scipy.interpolate and robust penalized spline methods. It is covered under the OpenPIV GPL v3 license. Based on discretized smoothing principles from D. Garcia (2010).
You can configure a PIV run with PIVSettings and optionally store it in YAML:
from openpiv import windef
# 1. Create settings in Python
settings = windef.Settings()
settings.filepath_images = "./images"
settings.frame_pattern_a = "frame_a_*.tif"
settings.frame_pattern_b = "frame_b_*.tif"
settings.windowsizes = (64, 32, 16)
settings.overlap = (32, 16, 8)
# Save to YAML for reuse / sharing
settings.to_yaml("my_settings.yaml")
# Load from YAML later
settings = windef.Settings.from_yaml("my_settings.yaml")
# Run PIV
windef.piv(settings)Without YAML, just instantiate and modify windef.Settings() directly, as shown above.
If you use OpenPIV in your scientific research, please cite the persistent software archive on Zenodo:
@software{openpiv_python,
author = {Liberzon, Alex and K{\"a}ufer, Theo and Bauer, Andreas and Vennemann, Peter and Zimmer, Erich and contributors},
title = {OpenPIV: Python and Rust Acceleration for Particle Image Velocimetry},
year = {2026},
publisher = {Zenodo},
version = {v0.26.1},
doi = {10.5281/zenodo.593157},
url = {https://doi.org/10.5281/zenodo.593157}
}