Metadata-Version: 2.4
Name: dpivsoft
Version: 0.14.0
Home-page: https://dpivsoft-python.readthedocs.io
Author: Jorge Aguilar-Cabello
Project-URL: Source, https://gitlab.com/jacabello/dpivsoft_python
Project-URL: Changelog, https://dpivsoft-python.readthedocs.io/en/latest/changelog.html
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.26.4
Requires-Dist: reikna>=0.8.0
Requires-Dist: scipy>=1.11.4
Requires-Dist: scikit-image>=0.22.0
Requires-Dist: opencv-python>=4.8.1.78
Requires-Dist: Pillow>=10.1.0
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: PyYAML>=6.0.2
Requires-Dist: pyopencl>=2024.1
Requires-Dist: Shapely>=2.0.6
Requires-Dist: importlib_resources>=5.0.0
Requires-Dist: networkx>=3.0
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: meshio>=5.3.5
Requires-Dist: gmsh>=4.13.1
Requires-Dist: scikit-fem>=10.0.2
Provides-Extra: dev
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: furo; extra == "docs"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python

# 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

```bash
pip install dpivsoft
```


### Build from source

Install `setuptools` if needed:

```bash
pip install setuptools
```

Clone the repository:

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

Build and install:

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

To install the pinned set of versions known to work:

```bash
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](#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:

```bash
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:

```bash
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](https://gitlab.com/jacabello)

## Acknowledgements

1. Patrice Meunier
2. Thomas Leweke
3. [Raul Infante-Sainz](https://gitlab.com/infantesainz)
4. [Luis Parras](https://gitlab.com/lparras)
5. Carlos del Pino

## How to cite this work

[https://doi.org/10.1016/j.softx.2022.101256](https://www.softxjournal.com/article/S2352-7110(22)00174-1/fulltext)
