Developer Installation

Build PIVTools from source for development, customization, or contribution.

Clone Repository

For developers who want to modify PIVTools or contribute to the project:

# Clone the backend repository
git clone https://github.com/MTT69/python-PIVTOOLs.git
cd python-PIVTOOLs

Included Static Libraries

The repository includes pre-compiled static libraries for FFTW3 and GSLfor all supported operating systems (macOS, Windows, Linux). This means if you have a compiler set up on your system, you can simply run pip install -e . and the C libraries will be compiled automatically in the correct location.

See setup.py in the repository root if you need to modify the build process.

C Extension Modules

The following C libraries are compiled during installation:

libbulkxcorr2d

FFT-based cross-correlation

libmarquadt

Gaussian peak fitting

libpeak_locate_lm

Levenberg-Marquardt peak localization

macOS Setup

Requirements

With Homebrew installed, you only need GCC:

brew install gcc

The build system looks for gcc-15 at/opt/homebrew/bin/gcc-15.

Build from Source

From the default Terminal, navigate to the repository root and run:

# From the repository root directory
pip install -e .

This installs all Python dependencies and compiles the C extension modules using the bundled FFTW3 and GSL static libraries.

Windows Setup

Requirements

Install Visual Studio with C++ build tools (Desktop development with C++).

Visual Studio 2019 or newer
Desktop development with C++ workload
Windows 10/11 SDK

Important: Use x64 Native Tools Command Prompt

You must build from the x64 Native Tools Command Prompt for VS, not the standard Command Prompt or PowerShell. Find it in your Start Menu under Visual Studio.

Build from Source

x64 Native Tools Command Prompt

# Open "x64 Native Tools Command Prompt for VS"
# Navigate to the repository root
cd C:\path\to\python-PIVTOOLs

# Install and build
pip install -e .

The FFTW and GSL binaries are included in the static_fftw andstatic_gsl folders within the repository.

Linux Setup

Requirements

Ensure you have GCC installed. On most distributions:

# Ubuntu/Debian
sudo apt install build-essential

# Fedora/RHEL
sudo dnf install gcc gcc-c++ make

# Arch Linux
sudo pacman -S base-devel

Build from Source

# From the repository root directory
pip install -e .

The bundled static libraries handle FFTW3 and GSL dependencies automatically.

GUI Development

The GUI is built with React/Next.js and served by the Flask backend. To modify the GUI:

# Clone the GUI repository
git clone https://github.com/MTT69/PIVTOOLs-GUI.git
cd PIVTOOLs-GUI

# Install dependencies
npm install

# Development server (hot reload)
npm run dev

# Build for production
npm run build

Deploying GUI Changes

After making changes to the frontend, run npm run build. This creates an out folder containing the compiled static files.

To deploy your changes:

Copy the out folder to python-PIVTOOLs/pivtools_gui/
Rename out to static (replacing the existing static folder)
Run app.py to see your changes in the GUI

Running the Code

After building from source, you have two ways to run PIVTools:

GUI Mode

Run app.py to start the Flask server and open the web-based GUI:

# From the repository root
python pivtools_gui/app.py

Opens at localhost:5000

Command Line Mode

Run example.py to execute PIV processing from the command line:

# From the repository root
python example.py

Uses config.yaml to determine what to run

Configuration File

Both GUI and command line modes use the same config.yaml file to determine processing parameters. Changes made in the GUI are saved to this file, and the command line reads from it. This allows you to configure complex setups visually and then run batch processing from the terminal.

Ready to Configure?

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

Image Configuration Guide