Quick Start

Get PIVTools up and running in minutes with pre-compiled binaries. No compiler required.

Installation

Install PIVTools in 3 Steps

PIVTools is distributed via PyPI with all dependencies pre-compiled. Create a virtual environment using Python 3.12 or 3.13 for compatibility.

# Step 1: Create a virtual environment (Python 3.12 or 3.13 required) python3.12 -m venv piv # or: python3.13 -m venv piv # Step 2: Activate it # On Windows: piv\Scripts\activate # On macOS/Linux: source piv/bin/activate # Step 3: Install PIVTools pip install pivtools

That's it! PIVTools is now ready to use with both GUI and CLI interfaces.

What's Included

On pip install, you get:

  • Pre-compiled C extensions for cross-correlation and peak fitting
  • FFTW3 and GSL libraries bundled for all platforms
  • Web-based GUI (React) served via Flask
  • Command-line interface for batch processing
  • Default configuration file ready to edit

Launch the GUI

pivtools-gui

Opens a web-based interface at localhost:5000. Your browser will open automatically.

Default Configuration: On first launch, PIVTools creates a defaultconfig.yamlin the current directory. Use the GUI to configure file locations, image formats, and processing settings - your changes are automatically saved.

CLI Usage

pivtools-cli init

Creates an editable config.yaml in your current directory for command-line processing.

Shared Configuration

Both the GUI and CLI share the same config.yaml file. Changes made in the GUI are automatically available when you run the CLI, and vice versa. This allows you to configure complex setups visually with the option to run via the command line or the GUI.

System Requirements

Supported Platforms

  • Python 3.12 or 3.13 (required)
  • macOS 15+ (Apple Silicon M1/M2/M3/M4)
  • Windows 10/11 (x86_64)
  • Linux (x86_64)

Pre-compiled Libraries

libbulkxcorr2d

FFT-based cross-correlation using FFTW3

libmarquadt

Gaussian peak fitting using GSL

libpeak_locate_lm

Levenberg-Marquardt peak localization

macOS Limitation

LaVision proprietary formats (.im7,.set) are not supported on macOS due to library limitations. These formats require Windows-specific DLLs from LaVision DaVis. Use standard image formats (.tif,.png) on macOS, or run PIVTools on Windows/Linux for LaVision files.

Ready to Configure?

Learn how to set up your image paths, camera configuration, and file formats.

Image Configuration Guide