openptv2 Documentation¶

Welcome to the openptv2 documentation.

Documentation Index¶

Getting Started¶

Installation & Platform Setup - Installing on Linux, macOS, Windows, VMs, and WSL
First Steps - Basic programmatic usage, GUI navigation, and command-line batching
End-to-End Tutorial - Step-by-step 3D particle tracking tutorial

User Documentation¶

Tracking Pipeline & Results Guide - Pipeline workflow, parameter guide, multi-pass tracking, and ptv_is.# output format
Auto-Calibration with openptv warmup - Standalone parameter/engine auto-tuning before tracking
Quality 3D Tracking & Kalman Guide - Constant-acceleration Kalman filter state estimation, parameters, formulas, and benchmark results
Command-Line Batch Processing - Running openptv2-batch headlessly
Sequence & Tracking Plugins - Built-in plugins, selecting one, writing your own
Tracking Visualization - Preview tracking results
Tracking Debug Visualization - Debug tracking parameters interactively
Running Tests - Command-line test suite, excluding slow tests, running native C and virtual wheel pipelines
Algorithm Documentation - Algorithm explanations
Burgers Case Study - Detailed analysis of tracking deviation and recovery

Developer Documentation¶

Building from Source - Detailed build instructions
Cython & Pure Python Modes - Switch between high-performance Cython and debuggable Pure Python
Documentation Workflow - Editing documentation and deploying to GitHub Pages
Packaging & Releases - Building binary wheels and releasing them on PyPI and GitHub
GUI Testing Guide - How to test the GUI
Development Workflow - How to develop

Migration¶

From optv/pyptv - Migrating from legacy packages

Quick Links¶

Documentation Structure¶

docs/
├── index.md                 # This file
├── HOW_TO_TEST_GUI.md       # GUI testing guide
├── BUILDING_BINARY_WHEELS.md # Wheel building guide
├── developer_guide/
│   └── building.md          # Build instructions
├── algorithms/
│   └── tracking.md          # Tracking algorithm documentation
├── sphinx/                  # API reference (TODO)
└── tutorials/               # User tutorials (TODO)

Available Documentation¶

Algorithms¶

Tracking Algorithms - Explanation of track.c vs track3d.c

Developer Guide¶

Building from Source - Full build instructions
Cython & Pure Python Modes - Seamlessly switch between C-level speed and pure python debugging
Building Binary Wheels - manylinux/macOS/Windows wheels

GUI¶

Testing the GUI - How to test the GUI

Scripts¶

scripts/build_wheel.sh - Build binary wheel
scripts/install_wheel.sh - Install wheel in clean venv
scripts/run_tests.sh - Run test suite

For Users¶

Installation: See README.md
Basic Usage: See README.md
GUI Usage: Launch openptv2-gui and explore the interface

For Developers¶

Build Setup: See building.md
Cython & Pure Python modes: See cython_and_pure_python.md
Development Workflow: See building.md#development-workflow
Testing: See building.md#testing

For Contributors¶

Fork the repository
Set up development environment: uv sync --extra dev
Make changes and run tests: pytest
Submit a pull request

Last updated: March 2026