Metadata-Version: 2.4
Name: pivtools
Version: 0.6.0
Summary: PIVTOOLs - Particle Image Velocimetry Tools with CLI and GUI
Author-email: Morgan Taylor <m.t.taylor@soton.ac.uk>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/MTT69/python-PIVTOOLs
Project-URL: Repository, https://github.com/MTT69/python-PIVTOOLs
Project-URL: Issues, https://github.com/MTT69/python-PIVTOOLs/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Framework :: Flask
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: dask[distributed]>=2025.7.0
Requires-Dist: dask-jobqueue
Requires-Dist: dask-image
Requires-Dist: loguru>=0.7.3
Requires-Dist: numpy>=2.2
Requires-Dist: opencv-python>=4.12
Requires-Dist: pandas>=2.3
Requires-Dist: pillow>=11.3
Requires-Dist: PyYAML>=6.0
Requires-Dist: scipy>=1.16
Requires-Dist: tifffile>=2025.6.11
Requires-Dist: tqdm>=4.67
Requires-Dist: numba>=0.61
Requires-Dist: psutil>=6.1
Requires-Dist: rawpy>=0.25
Requires-Dist: scikit-image>=0.25
Requires-Dist: bottleneck>=1.6
Requires-Dist: scikit-learn>=1.7
Requires-Dist: threadpoolctl>=3.6
Requires-Dist: Flask>=3.1
Requires-Dist: flask-cors>=6.0
Requires-Dist: flask-compress>=1.15
Requires-Dist: matplotlib>=3.10
Requires-Dist: imagecodecs
Requires-Dist: imageio-ffmpeg>=0.5.0
Requires-Dist: bokeh
Provides-Extra: cine
Requires-Dist: cinereader; extra == "cine"
Provides-Extra: dev
Requires-Dist: pytest>=8.4; extra == "dev"
Dynamic: license-file

# PIVtools

An open-source Python framework for particle image velocimetry (PIV) analysis, integrating planar, stereoscopic, and ensemble PIV pipelines with a React-based GUI and Dask-backed distributed processing.

PIVtools provides an end-to-end workflow: image loading, preprocessing, calibration, correlation, and visualisation driven from a single configuration file. Computationally intensive routines are implemented in C and parallelised with OpenMP and Dask, scaling from workstations to HPC clusters. Validation against synthetic channel flow at Re_τ = 1000 reproduces DNS mean velocity profiles to within 1% down to y⁺ ≈ 10 with instantaneous PIV, and y⁺ ≈ 1 with ensemble PIV.

## Features

- Planar, stereoscopic, and ensemble PIV pipelines
- Direct Reynolds stress extraction from ensemble correlation maps
- React-based GUI for interactive analysis
- Optimised C extensions parallelised with OpenMP and Dask
- Scales from local workstations to HPC clusters
- Complete pipeline from raw image import to vector field visualisation

## Installation

```bash
pip install pivtools
```

This installs the complete toolkit including:
- **Core utilities** for image handling and vector processing
- **Command-line interface** (`pivtools-cli`) for automated workflows
- **React-based GUI** (`pivtools-gui`) for interactive analysis

Pre-compiled C extensions are included for Windows, macOS, and Linux.

## Quick Start

### Initialise a workspace

```bash
pivtools-cli init
```

Creates a default `config.yaml` in the current directory.

### Run PIV analysis (command-line)

```bash
pivtools-cli run
```

Runs the PIV pipeline using `config.yaml` in the current directory.

### Launch the GUI

```bash
pivtools-gui
```

Starts the React-based GUI for interactive configuration and execution.

## Configuration

Both `pivtools-cli` and `pivtools-gui` use `config.yaml` in the current working directory. On first launch, a default `config.yaml` is copied from the package if none exists.

For detailed configuration options, see [piv.tools/manual](https://piv.tools/manual).

## Reproducing the paper

Validation data, benchmark scripts, synthetic image generator configs, calibration images, and pre-computed figures are deposited in the University of Southampton Pure repository:

> **DOI:** *[pending]*

This includes everything needed to reproduce the figures in the accompanying SoftwareX paper, including ground-truth statistics, CSV data for independent replotting, and scripts for end-to-end regeneration from PIVtools output.

## Requirements

- Python 3.12+

## Citation

If you use PIVtools in your research, please cite:

> Taylor, M. T., Lawson, J. M., & Ganapathisubramani, B. (2026). PIVtools: A comprehensive open source software for particle image velocimetry. *SoftwareX*. *[DOI pending]*

## License

GNU General Public License v3.0 or later (`GPL-3.0-or-later`) — see [LICENSE](LICENSE) for the full text.

**Note:** Redistribution of PIVtools, modified or unmodified, must be under the same licence and must make the corresponding source available. The compiled C libraries (`libbulkxcorr2d`, `libfusedwarp`, `libkspacefit`) are original work built from sources shipped in the sdist and link only OpenMP and libm — no third-party numerical library is bundled or linked. See the [LICENSE](LICENSE) and [NOTICE](NOTICE) files for details.

## Contributing

Contributions are welcome. Please see the GitHub repository for issues and pull requests.
