Developer Guide

Build from source, modify the GUI, and contribute to PIVTools.

Getting the Source

PIVTools is split across two repositories.

Backend + Processing

Flask server, PIV processing engine, C extensions, and CLI.

git clone https://github.com/MTT69/python-PIVTOOLs.git
cd python-PIVTOOLs

Frontend (React)

Next.js web interface. Only needed if you want to modify the GUI.

git clone https://github.com/MTT69/PIVTOOLs-GUI.git
cd PIVTOOLs-GUI

Building C Extensions

PIVTools includes two C libraries compiled via setup.py. Pre-compiled static libraries for FFTW3 and GSL are bundled for all platforms in static_fftw/ and static_gsl/.

libbulkxcorr2d

FFT-based cross-correlation (FFTW3 + OpenMP)

libmarquadt

Gaussian peak fitting (GSL + OpenMP)

Build Steps

Install the package in editable mode, then compile the C extensions separately:

# Install dependencies in editable mode
pip install -e .

# Compile C extensions
python setup.py build

Platform Requirements

Platform	Compiler	Setup
macOS	`gcc-15` (Homebrew)	`brew install gcc`
Windows	MSVC (`cl`)	Visual Studio with "Desktop development with C++" workload
Linux	`gcc`	`sudo apt install build-essential`

Windows: x64 Native Tools Command Prompt Required

All commands (pip install -e . and python setup.py build) must be run from the x64 Native Tools Command Prompt for VS. The standard Command Prompt, PowerShell, and VS Code terminal will not work.

Find it in Start Menu → Visual Studio → x64 Native Tools Command Prompt for VS 2022.

End Users: No Compiler Needed

PyPI wheels ship with pre-compiled .dll/.so files. Running pip install pivtools just works.

GUI Development

The GUI is a Next.js React app served as static files by the Flask backend.

# Clone and install
git clone https://github.com/MTT69/PIVTOOLs-GUI.git
cd PIVTOOLs-GUI
npm install

# Development server with hot reload
npm run dev

# Build for production
npm run build

Deploying GUI Changes

After building, deploy the compiled output to the backend:

Run npm run build to create the out/ folder
Copy out/ to python-PIVTOOLs/pivtools_gui/
Rename it to static (replacing the existing folder)
Run pivtools-gui to see your changes

AI-Assisted Development

The repository includes CLAUDE.md, a comprehensive reference file that serves as the single source of truth for the entire codebase architecture.

What CLAUDE.md Contains

At ~1200 lines, it documents:

Feature-to-file map (backend modules, frontend hooks, components)

All REST API routes with parameters and return types

Every config.yaml property with types and defaults

Processing pipeline architecture (Dask, sliding window I/O)

C extension function signatures and array conventions

Data formats (.mat structure, directory layout)

Build system details (setup.py, static libraries, CI/CD)

Code conventions and architectural patterns

Point-and-Shoot Development

Give any AI coding assistant (Claude Code, Cursor, Copilot, etc.) access to the codebase and it can understand the full architecture immediately. No onboarding needed.

The file maps every feature to its exact files, every route to its handler, and every config key to its purpose. An AI assistant can navigate the codebase, add features, fix bugs, and refactor code with full context from the start.

Keep It Updated

When making changes to the codebase, update CLAUDE.md to reflect new routes, config keys, or architectural changes. It is the documentation that makes AI-assisted development work.

Running the Code

After building from source, PIVTools provides two interfaces. Both use the same config.yaml.

GUI

pivtools-gui
# or
python pivtools_gui/app.py

Opens at localhost:5000

CLI

pivtools-cli <command>
# e.g. instantaneous, ensemble,
# detect-planar, statistics, etc.

See CLI Reference for all commands

Changes made in the GUI are saved to config.yaml. The CLI reads from the same file, so you can configure in the GUI and 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