DPIVSoft Python

DPIVSoft is an open-source PIV (Particle Image Velocimetry) algorithm originally developed by Thomas Leweke and Patrice Munier for MATLAB. The original MATLAB source is available at https://www.irphe.fr/~meunier/. This project migrates the original code to Python and adds GPU acceleration via OpenCL.

Full documentation (user guide and API reference): https://dpivsoft-python.readthedocs.io

Features

• 2D PIV cross-correlation with iterative window deformation — both GPU (OpenCL) and CPU implementations; FFT-based and direct cross-correlation supported
• Stereo PIV: two-camera setup with calibration GUI, backprojection to world coordinates, and disparity correction for 3-component velocity reconstruction
• Synthetic particle image generation for testing: analytical flow fields and custom velocity fields (e.g. from CFD) to generate image pairs
• Post-processing: vorticity, divergence, and other derived fields
• Force calculation from 2D-PIV data using two methods:
  • Mesh-free vorticity-based method — Martín-Alcántara & Fernandez-Feria, Phys. Rev. Fluids 4, 024702 (2019)
  • Mesh-based projection method — Chang, Proc. R. Soc. A 437:517–525 (1992)
• Calibration GUI (StereoCalibrationApp) supporting TSI and LaVision calibration targets

Status

DPIVSoft is still in beta. The core 2D PIV pipeline is stable and tested. The stereo PIV pipeline is functional but newer and not yet widely validated on experimental data — treat it as experimental. The API may change between versions.

To keep the package maintainable as a side project, supported Python and dependency versions are intentionally constrained. See requirements.txt for the exact versions that have been tested.

Testing and feedback are very welcome.

Requirements

• Python >= 3.12
• GPU with OpenCL support (tested on AMD RX 580)

Dependencies (installed automatically via pip): numpy>=1.24,<2, scipy, opencv-python, pyopencl>=2021, reikna>=0.7.6, scikit-image>=0.20, matplotlib>=3, PyYAML>=5.4, Pillow>=9, Shapely>=2,<3, importlib_resources>=5, meshio==5.3.5, gmsh==4.13.1, scikit-fem==10.0.2, scikit-learn

Installing

Using PyPI

pip install dpivsoft

Build from source

Install setuptools if needed:

pip install setuptools

Clone the repository:

git clone https://gitlab.com/jacabello/dpivsoft_python.git

Build and install:

cd dpivsoft_python
python setup.py sdist
pip install dist/dpivsoft-*.tar.gz

To install the exact dependency versions that have been tested:

pip install -r requirements.txt

Examples

Example scripts are in the dpivsoft/Examples/ folder:

• simple_tutorial.py — basic 2D PIV run
• stereo_tutorial.py — stereo PIV with calibration and 3C velocity reconstruction
• forces_tutorial.py — force calculation from 2D-PIV data
• mesh_tutorial.py — build a FEM mesh from PIV data and compute the Laplacian using finite differences (prerequisite for the mesh-based force method)
• uncertainty_tutorial.py — calibrate per-vector uncertainty against the correlation peak ratio Q and check the coverage of the resulting intervals
• performance.py — GPU vs CPU benchmarking

Testing

Tests are for developers working from a cloned repository — they depend on the Examples/ directory and are not shipped when installing from PyPI. Clone the repository first (see Build from source).

The suite is plain unittest, so no extra dependencies are needed. From the repo root, with the environment where DPIVSoft is installed active:

python -m unittest discover dpivsoft/tests -v

-v prints one line per test with its name and result (ok, FAIL, skipped). To run a single suite instead:

python -m unittest dpivsoft.tests.test_GPUconsistency -v

Available suites:

• test_GPUconsistency — GPU/CPU consistency: grid points, sub-image slicing, normalization, cross-correlation, peak finding, derivatives, interpolation, image deformation (requires a working OpenCL device)
• test_stereo_synth — synthetic end-to-end stereo: calibration, Soloff 3C reconstruction, full image+PIV pipeline
• test_cpt_sorting — calibration-target dot sorting
• test_disparity_dz — disparity to Δz conversion and surface-fit regularizer
• test_peak_locking — peak-locking diagnostic
• test_median_filters — normalized median test
• test_peak_quality — cross-correlation peak ratio Q
• test_uncertainty — Q-based per-vector uncertainty calibration

Some tests skip cleanly when their optional inputs are missing (the real-data stereo tests need the PIV Challenge case E dataset, downloaded by stereo_tutorial.py).

Contributors

1. Jorge Aguilar-Cabello

Acknowledgements

1. Patrice Meunier
2. Thomas Leweke
3. Raul Infante-Sainz
4. Luis Parras
5. Carlos del Pino

How to cite this work

https://doi.org/10.1016/j.softx.2022.101256