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)
• 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 available when installing from PyPI.

From the repo root:

python -m unittest dpivsoft.tests.test_GPUconsistency -v

The test suite covers GPU/CPU consistency for: grid points, sub-image slicing, normalization, cross-correlation, peak finding, derivatives, interpolation, and image deformation.

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