Quick Start

From pip install to your first velocity field in four steps. No compiler required.

Install

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

Create a virtual environment

python3.12 -m venv piv

Activate it

source piv/bin/activatemacOS / Linux

piv\Scripts\activateWindows

Install

pip install pivtools

Launch

Start with the GUI, the CLI, or both — they are two front ends to the same tool.

GUI

pivtools-gui

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

CLI

pivtools-cli init

Sets up a workspace in the current directory, ready for the terminal-only workflow.

Either way, a default config.yaml is created in the current directory. The GUI and CLI share this file — configure visually, run from the terminal, or the other way round.

Point it at your data

Edit config.yaml to set the image source path, the number of cameras, and the file format. In the GUI this is the Image Configuration tab.

Image Configuration guide →

Run PIV

Pick the processing mode. Both read the same config.yaml.

pivtools-cli instantaneous

Cross-correlates each image pair. One velocity field per pair.

pivtools-cli ensemble

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

Every command, flag, and workflow — including calibration — is in the CLI Reference.

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