Metadata-Version: 2.4
Name: dpivsoft
Version: 0.9.0
Home-page: https://gitlab.com/jacabello/dpivsoft_python
Author: Jorge Aguilar-Cabello
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Natural Language :: English
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy<2,>=1.24
Requires-Dist: reikna>=0.7.6
Requires-Dist: scipy
Requires-Dist: scikit-image>=0.20
Requires-Dist: opencv-python
Requires-Dist: Pillow>=9
Requires-Dist: matplotlib>=3
Requires-Dist: PyYAML>=5.4
Requires-Dist: pyopencl>=2021
Requires-Dist: Shapely<3,>=2
Requires-Dist: importlib_resources>=5
Requires-Dist: meshio==5.3.5
Requires-Dist: gmsh==4.13.1
Requires-Dist: scikit-fem==10.0.2
Requires-Dist: scikit-learn
Provides-Extra: dev
Requires-Dist: pytest>=3.7; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
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.

## 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

```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 exact dependency versions that have been tested:

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

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