pivtools 0.4.8

PIVTOOLs - Particle Image Velocimetry Tools with CLI and GUI

PIVTOOLs

Particle Image Velocimetry Tools - A comprehensive toolkit for PIV analysis with both command-line and GUI interfaces.

We present PIVTOOLS, an open-source Python framework built for community expansion with a React-based GUI, which integrates planar, stereoscopic, and ensemble PIV pipelines into a single end-to-end environment. Computationally intensive routines are implemented in optimised C and parallelised with Dask, enabling datasets of large scale datasets to be processed efficiently on both workstations and distributed HPC clusters.

The framework provides a complete pipeline from raw image import to image preprocessing, parallel vector computation, calibration, and interactive visualisation. Ensemble extensions allow direct estimation of Reynolds stresses from correlation maps, offering statistical fidelity beyond what is achievable with instantaneous methods. Validation against synthetic channel flow demonstrates mean velocity profiles accurate to within 1% of DNS reference down to ( y^+ \approx 40-50 ) with instantaneous PIV, and to ( y^+ \approx 5 ) with ensemble methods.

Features

• Planar, stereoscopic, and ensemble PIV pipelines
• React-based GUI for interactive analysis
• Optimized C extensions for performance
• Parallel processing with Dask
• Support for terabyte-scale datasets
• Complete pipeline from image import to visualization

Installation

Install PIVTOOLs with a single command:

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

The package includes pre-compiled C extensions for optimal performance on Windows, macOS, and Linux.

Quick Start

Initialize a new PIVTOOLs workspace

pivtools-cli init

This creates a default config.yaml file in your current directory that you can edit to configure your PIV analysis.

Run PIV analysis (command-line)

pivtools-cli run

This runs the PIV analysis using the config.yaml in your current directory.

Launch the GUI

pivtools-gui

This starts the React-based GUI where you can interactively configure and run PIV analysis.

Configuration

Both pivtools-cli and pivtools-gui applications use config.yaml in the current working directory.

When you run either pivtools-cli init or start pivtools-gui for the first time, if no config.yaml exists in the current directory, it automatically copies the default config from the package to config.yaml in your current working directory.

For detailed configuration options, see piv.tools/manual.

Requirements

• Python 3.12+

License

BSD 3-Clause License - See LICENSE for details.

Note: Pre-built binaries link against GPL-licensed libraries (FFTW3, GSL). Binary distributions must comply with GPL terms unless these dependencies are replaced with alternatively-licensed implementations. See the LICENSE and NOTICE files for complete details.

Contributing

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