Quick Start

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

Quick Recipe

opinionated defaults -- full reference below

1.Create a virtual environment with Python 3.12–3.14 and run pip install pivtools.
2.Launch the GUI with pivtools-gui, or initialise a CLI workspace with pivtools-cli init. Either way you get a default config.yaml in your current directory.
3.Point the config at your data (Image Configuration), run PIV, calibrate. The GUI and CLI share the same config file, so switch between them freely.

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

# Optional: Phantom .cine file support
pip install "pivtools[cine]"

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.

Seed Calibration Settings

pivtools-cli init-settings --source /data/experiment/calibration

Writes <source>/calibration/settings.yaml, which holds the calibration image format, board geometry, and rig dt. Fill it in before calibrating. The image format is required when the settings are read andrig.dt is required when a model is generated, so a missing value fails loudly rather than defaulting.

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, AVX2 CPU: Intel 2013+ / AMD 2015+)
Linux (x86_64, AVX2 CPU: Intel 2013+ / AMD 2015+, glibc 2.28+: RHEL/Alma 8+, Ubuntu 20.04+, Debian 10+)

Older x86 CPUs are refused with a clear error at load time, and on older Linux distros (e.g. CentOS 7, Ubuntu 18.04) pip falls back to the source distribution -- both cases compile from source instead (see the Developer Guide).

Bundled C Libraries

libbulkxcorr2d

SIMD codelet FFT cross-correlation + LM peak fitting (OpenMP)

libfusedwarp

Fused symmetric image warping for multipass deformation (OpenMP)

libkspacefit

k-space transfer-function LM fitter for ensemble PIV, one fit per window (OpenMP)

LaVision Formats (.im7 / .set)

LaVision formats (.im7,.set) are read by a built-in pure-Python reader with no lvpyio dependency, so they work on macOS, Linux, and Windows alike.

Ready to Configure?

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

Image Configuration Guide