Getting started

Installation

From PyPI:

pip install dpivsoft

Or from source:

git clone https://gitlab.com/jacabello/dpivsoft_python.git
cd dpivsoft_python
pip install .

Requirements: Python ≥ 3.12. The CPU implementation works out of the box. GPU processing additionally needs an OpenCL runtime for your hardware — any vendor works (AMD, Intel, NVIDIA drivers, or Mesa’s rusticl on Linux); there is no CUDA dependency. The GPU path runs the exact same algorithm as the CPU path, roughly two orders of magnitude faster.

A first PIV run (CPU)

The package can generate its own synthetic test images, so no experimental data is needed to try it:

import dpivsoft.DPIV as DPIV
import dpivsoft.SyIm as SyIm
from dpivsoft.Classes import Parameters

SyIm.Analytic_Syntetic("Images", "Test_Img_")        # synthetic image pair

Parameters.readParameters("simple_tutorial_parameters.yaml")  # or set attributes

Img1, Img2 = DPIV.load_images("Images/Test_Img_1.png",
                              "Images/Test_Img_2.png")
x, y, u, v = DPIV.processing(Img1, Img2)

DPIV.save(x, y, u, v, "result", 'openpiv')           # openpiv-compatible ASCII

All processing options (window sizes, grid, iterations, validation thresholds) live in the global Parameters class — set them as attributes or load a YAML file; the parameters are explained on the PIV algorithm page.

The same run on the GPU

Three set-up calls (once per session), then a processing loop:

import dpivsoft.Cl_DPIV as Cl_DPIV
from dpivsoft.Classes import GPU

thr = Cl_DPIV.select_Platform("selection")   # interactive list; or an index, e.g. 0
Cl_DPIV.compile_Kernels(thr)                 # once per device
Cl_DPIV.initialization(width, height, thr)   # re-run if image size / parameters change

GPU.img1.set(Img1)                           # upload the first pair
GPU.img2.set(Img2)

Cl_DPIV.processing(next_img1_name, next_img2_name, thr)

x, y = GPU.x2.get(), GPU.y2.get()            # results back to NumPy
u, v = GPU.u2_f.get(), GPU.v2_f.get()        # final (median-filtered) field

Note the idiom: processing() takes the file names of the next image pair, so disk I/O overlaps with GPU compute when processing a sequence — see the OpenCL implementation page for details and a full loop.

Tutorials

Runnable, commented end-to-end scripts live in dpivsoft/Examples/ in the repository. None of them require experimental data: images are synthesized in place or downloaded on first run.

script

covers

simple_tutorial.py

synthetic images → CPU PIV → GPU PIV → saving/plotting

stereo_tutorial.py

full stereo pipeline: calibration GUI, PIV per camera, Soloff 3C reconstruction, optional Δz self-calibration (downloads the PIV Challenge case E dataset, ~197 MB)

forces_tutorial.py

force estimation with the vortical impulse method

mesh_tutorial.py

FEM mesh + auxiliary potentials for the projection force method

performance.py

CPU vs GPU benchmark

Where to go next