E5C0 pyptv/docs at master · alexlib/pyptv · GitHub
[go: up one dir, main page]
Skip to content

Latest commit

 

History

History

docs

README.md

PyPTV is the GUI and batch processing software for 3D Particle Tracking Velocimetry (PTV)

Using PyPTV

PyPTV Documentation Index

Welcome to the PyPTV documentation! This index provides an organized overview of all available guides and resources. Use this page as your starting point for learning, troubleshooting, and reference.

Getting Started

Core Usage

Advanced Features

System Administration

Additional Resources

How to use this documentation:

  • Click any link above to jump to the relevant guide.
  • Use your browser's search to find keywords or topics.
  • For troubleshooting, check the FAQ sections in each guide.
  • For community help, visit GitHub Issues or Discussions.

Documentation last updated: August 2025 for PyPTV 2025

Welcome to PyPTV - the open-source 3D Particle Tracking Velocimetry software.

Table of Contents

Getting Started

Using PyPTV

Additional Resources

What is PyPTV?

PyPTV is a Python-based implementation of 3D Particle Tracking Velocimetry (PTV), enabling you to:

  • Track particles in 3D space from multiple camera views
  • Measure fluid velocities in experimental setups
  • Calibrate camera systems for accurate 3D reconstruction
  • Process image sequences with customizable algorithms
  • Export tracking data for further analysis

Key Features

✅ Modern YAML Configuration - Single-file parameter management
✅ Graphical User Interface - Intuitive operation and visualization
✅ Multi-Camera Support - 2-4 camera systems with flexible setup
✅ Plugin Architecture - Extend functionality with custom algorithms
✅ Cross-Platform - Runs on Linux, macOS, and Windows
✅ Open Source - MIT license with active community development

System Requirements

  • Operating System: Linux (Ubuntu/Debian recommended), macOS, or Windows 10/11
  • Python: 3.11 or newer
  • Memory: 8GB RAM minimum (16GB+ recommended for large datasets)
  • Storage: 2GB free space (plus space for your experimental data)

Quick Installation

For most users, follow these steps:

# Clone the repository
git clone https://github.com/openptv/pyptv
cd pyptv

# Run the installation script (Linux/macOS)
./install_pyptv.sh

# Or use conda directly
conda env create -f environment.yml
conda activate pyptv
pip install -e .

For detailed installation instructions, see the Installation Guide.

Testing: Headless vs GUI

PyPTV separates tests into two categories:

  • Headless tests (no GUI): Located in tests/. These run in CI (GitHub Actions) and Docker, and do not require a display.
  • GUI-dependent tests: Located in tests_gui/. These require a display and are run locally or with Xvfb.

To run all tests locally:

bash run_tests.sh

To run only headless tests (recommended for CI/Docker):

bash run_headless_tests.sh

Environment Setup

PyPTV uses a modern environment.yml and requirements-dev.txt for reproducible environments. Most dependencies are installed via conda, but some (e.g., optv, rembg, flowtracks) are installed via pip in the conda environment.

See PYPTV_ENVIRONMENT_GUIDE.md for details.

Docker Usage

For headless testing and reproducible builds, you can use Docker:

docker build -t pyptv-test .
docker run --rm pyptv-test

This runs only headless tests in a minimal environment, mimicking CI.

Getting Help

Contributing

PyPTV is an open-source project and welcomes contributions! See our contributing guidelines for more information.

Ready to get started? Begin with the Installation Guide or jump to Quick Start if you already have PyPTV installed.

Complete Documentation Overview

The PyPTV documentation is organized into the following sections:

1. Getting Started

2. Running PyPTV

3. Parameter Management

4. Camera Calibration

5. Specialized Features

6. Examples and Workflows

7. System Administration

Key Improvements

This documentation has been completely restructured to provide:

✅ Modern YAML Focus - All examples use the current YAML parameter system
✅ Correct num_cams Usage - No references to obsolete n_img field
✅ test_cavity Reference - Consistent examples using the included test dataset
✅ Modular Structure - Each topic in its own focused guide
✅ Practical Workflows - Step-by-step procedures for common tasks
✅ Cross-Referenced - Links between related topics
✅ Up-to-Date - Reflects current PyPTV 2025 functionality

Quick Navigation

I want to... Go to...
Install PyPTV Installation Guide or Windows Install
Get started quickly Quick Start Guide
Run the software Running the GUI
Convert old parameters Parameter Migration
Understand YAML format YAML Parameters Reference
Calibrate cameras Calibration Guide
See examples Examples and Workflows
Use splitter cameras Splitter Mode
Create custom plugins Plugins System
Troubleshoot issues Check individual guides for troubleshooting sections

Documentation last updated: July 2025 for PyPTV 2025
0