Quick Start

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

Quick Recipe

opinionated defaults — full reference below
  1. 1.Create a virtual environment with Python 3.12–3.14 and run pip install pivtools.
  2. 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. 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

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, arm64)
  • Windows 10/11 (x86_64)
  • Linux (x86_64)

Bundled C Libraries

libbulkxcorr2d

FFT cross-correlation (FFTW3 + OpenMP)

libmarquadt

Gaussian peak fitting (GSL + OpenMP)

libfusedwarp

Fused image warping (OpenMP)

libkspace

K-space transfer function fitting (FFTW3 + GSL + OpenMP)

LaVision Format Support

LaVision formats (.im7,.set) are read by PIVTools' built-in pure-Python readers. No external dependencies required — works on macOS, Windows, and Linux.

Ready to Configure?

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

Image Configuration Guide