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 & Fernández-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: each dependency carries a minimum version the test suite has been run against. See requirements.txt for one full set of versions known to work.

Testing and feedback are very welcome.

Requirements

• Python >= 3.11 (tested on 3.11, 3.12 and 3.13)
• For the GPU path, a device with OpenCL support (tested on AMD RX 580). The CPU implementation runs without one.

Dependencies (installed automatically via pip): numpy>=1.26.4, scipy>=1.11.4, opencv-python>=4.8.1.78, pyopencl>=2024.1, reikna>=0.8.0, scikit-image>=0.22.0, matplotlib>=3.8.0, PyYAML>=6.0.2, Pillow>=10.1.0, Shapely>=2.0.6, importlib_resources>=5.0.0, networkx>=3.0, scikit-learn>=1.3.2, meshio>=5.3.5, gmsh>=4.13.1, scikit-fem>=10.0.2

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 pinned set of versions known to work:

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 — some of them read and write inside Examples/, which is not writable in a normal site-packages install. 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 stage by stage: grid points, sub-image slicing, normalization, cross-correlation, peak finding, derivatives, interpolation, image deformation
• test_pipeline_wiring — whole-pipeline runs of DPIV.processing and Cl_DPIV.processing on synthetic pairs with a known displacement
• test_window_correction — the window-footprint (Westerweel) correction and its effect on sub-pixel bias
• test_peak_quality — cross-correlation peak ratio Q
• test_median_filters — median and normalized median test
• test_masking — the masking path on both CPU and GPU, including Parameters.load_mask
• test_postprocessing — vorticity, divergence and the peak-locking diagnostic, against closed-form fields
• test_uncertainty — Q-based per-vector uncertainty calibration
• test_stereo_synth — synthetic end-to-end stereo: calibration, Soloff 3C reconstruction, full image+PIV pipeline
• test_cpt_sorting — calibration-target dot detection and lattice sorting
• test_disparity_dz — disparity to Δz conversion and surface-fit regularizer
• test_analytic_flows — the analytic body flows used as force ground truth
• test_forces_analytic — force validation for the impulse method, against Kutta–Joukowski
• test_forces_projection — the same for the projection method
• test_projection_potentials — the FEM auxiliary potentials and their handover to the PIV grid

Some tests skip cleanly when their inputs are missing: the GPU tests need a working OpenCL device, and the real-image part of test_cpt_sorting needs the PIV Challenge case E calibration target, 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