Quick Start

Install PIVTools and start processing in minutes. No compiler required.

Installation

Install in 3 Steps

Requires Python 3.12, 3.13, or 3.14. All C extensions and dependencies are pre-compiled.

# 1. Create a virtual environment
python3.12 -m venv piv

# 2. Activate it
source piv/bin/activate        # macOS/Linux
piv\Scripts\activate           # Windows

# 3. Install
pip install pivtools

Launch the GUI

pivtools-gui

Opens a web interface at localhost:5000. Your browser opens automatically.

On first launch, a default config.yaml is created in the current directory. The GUI and CLI share this file.

CLI Usage

Initialise Workspace

pivtools-cli init

Creates an editable config.yaml in the current directory. Edit this to set image paths, camera setup, and processing parameters.

Instantaneous PIV

pivtools-cli instantaneous

Per-frame cross-correlation. One velocity field per image pair.

Ensemble PIV

pivtools-cli ensemble

Averages correlation planes across all frames before peak detection. Single time-averaged velocity field.

The GUI and CLI share the same config.yaml. Configure visually in the GUI, then run via CLI -- or vice versa. See the CLI Reference for all commands.

System Requirements

Supported Platforms

Python 3.12, 3.13, or 3.14
macOS 15+ (Apple Silicon M1-M4)
Windows 10/11 (x86_64)
Linux (x86_64)

Bundled C Libraries

libbulkxcorr2d

FFT cross-correlation (FFTW3 + OpenMP)

libmarquadt

Gaussian peak fitting (GSL + OpenMP)

macOS Limitation

LaVision formats (.im7,.set) require the lvpyio library, available on Windows and Linux only. macOS users should export calibration images to TIFF.

Ready to Configure?

Set up your image paths, camera configuration, and file formats.

Image Configuration Guide