PIVTools Manual

A complete Particle Image Velocimetry processing solution with GUI and CLI interfaces. From raw images to publication-ready visualisations.

Processing Pipeline

PIVTools guides you through the complete PIV workflow, from loading raw images to generating statistical analysis and visualisations. Each step is documented with both GUI instructions and CLI commands where available.

Setup & Configuration

Configure image paths, camera setup, and file formats

Masking & Preprocessing

Define exclusion regions and apply image filters

PIV Processing

Run cross-correlation with multi-pass refinement

Calibration

Convert pixels to physical units (planar or stereo)

Post-Processing

Apply transforms, merge cameras, compute statistics

Visualisation

View results and create publication-ready videos

Export

Save MAT files, videos, and statistical outputs

Documentation Sections

Click any card below to access detailed documentation for each feature.

Quick Start

Get PIVTools installed and running in minutes with pip install.

pip install pivtools
Python 3.12/3.13 support
Pre-compiled C extensions

CLI Reference

Complete command-line reference with all 12 commands and options.

12 CLI commands
Batch processing
Workflow examples

Image Configuration

Configure input images, camera setups, and file formats for your experiments.

Multiple image formats
Multi-camera support
Batch processing paths

Masking

Define regions to exclude from PIV processing with interactive tools.

Polygon mask editor
Pixel border mode
Per-camera masks

Preprocessing

Apply temporal and spatial filters to enhance image quality before PIV.

POD background removal
Gaussian/median filters
Live preview

PIV Processing

Run cross-correlation analysis with multi-pass refinement and outlier detection.

Multi-pass windowing
Ensemble averaging
Outlier detection & infilling

Planar Calibration

Convert pixel displacements to physical units using calibration targets.

Scale factor method
Dotboard/ChArUco patterns
LaVision polynomial

Stereo Calibration

Set up stereo PIV for 3D velocity reconstruction from camera pairs.

Intrinsic/extrinsic params
3D reconstruction
Stereo RMS validation

Video Maker

Create MP4 animations of velocity fields with customisable colormaps.

1080p/4K resolution
Multiple variables
Auto color scaling

Results Viewer

Interactively visualise PIV vector fields and derived quantities.

Vector overlays
Colormap controls
Frame navigation

Transforms

Apply geometric transformations like rotation and flipping to vector fields.

Flip/rotate operations
Batch processing
Operation chaining

Merging

Combine vector fields from multiple cameras with smooth blending.

Hanning window blend
Overlap detection
Multi-camera fields

Statistics

Compute mean velocities, Reynolds stresses, vorticity, and more.

Time-averaged stats
Per-frame statistics
TKE & vorticity

Developer Installation

Build PIVTools from source for development and contribution.

Clone & build
C extension compilation
Development setup

CLI vs GUI Comparison

PIVTools offers two interfaces: a command-line interface for scripting and batch processing, and a graphical interface for interactive work. Both use the same underlying processing engine.

Command Line Interface

Best for batch processing, automation, and scripted workflows.

$ pivtools-cli instantaneous

$ pivtools-cli detect-planar

$ pivtools-cli apply-calibration

$ pivtools-cli statistics

Graphical Interface

Best for interactive exploration, visualisation, and configuration.

Visual image preprocessing with live preview
Interactive polygon mask drawing
Real-time vector field visualisation
Point-and-click calibration workflows
Drag-and-drop configuration

Where to Start

Not sure where to begin? Use this guide to find the right documentation for your task.

I'm new to PIVTools

Start with Quick Start for installation, then Image Configuration to set up your data.

Quick Start Image Configuration

I want to run PIV analysis

Head to PIV Processing for cross-correlation settings and multi-pass configuration.

PIV Processing

I need to calibrate my data

Choose Planar Calibration for 2D PIV or Stereo Calibration for 3D reconstruction.

Planar Calibration Stereo Calibration

I want to compute statistics

The Statistics page covers mean velocities, Reynolds stresses, vorticity, and more.

Statistics

I want to create videos

Video Maker explains how to generate MP4 animations with custom colormaps.

Video Maker

I want to automate processing

Use the CLI commands for batch processing. See the CLI Reference for all 12 commands.

CLI Reference Quick Start (CLI)

Ready to Get Started?

Install PIVTools with pip and begin processing your PIV data in minutes. Full documentation is available for every feature.

Quick Start Guide Jump to PIV Processing