pyptv

Quick Start Guide

Get up and running with PyPTV using the included test dataset in under 10 minutes.

Prerequisites

Environment Setup and Testing

PyPTV uses a modern conda environment (environment.yml) and separates tests into headless (tests/) and GUI (tests_gui/) categories. See the README for details.

Overview

This guide walks you through:

Loading test data - Use the included test_cavity experiment
Running the GUI - Launch and navigate the PyPTV interface
Viewing calibration - Check camera calibration
Processing images - Detect and track particles
Exporting results - Save tracking data

Step 1: Activate PyPTV

Open your terminal (or Anaconda Prompt on Windows) and activate the PyPTV environment:

conda activate pyptv
cd /path/to/pyptv  # Navigate to your PyPTV installation

Step 2: Launch the GUI

Start the PyPTV graphical interface:

python -m pyptv.pyptv_gui

The main PyPTV window should open with a parameter tree on the left and camera views on the right.

Step 3: Load Test Data

The test_cavity experiment is included with PyPTV and provides a complete working example.

Load the experiment:
- In the GUI, go to File → Load Experiment
- Navigate to tests/test_cavity/
- Select parameters_Run1.yaml
- Click Open
Verify loading:
- The parameter tree should now show “Run1” with expandable sections
- You should see 4 camera tabs at the bottom
- Status bar should show “Experiment loaded successfully”

Step 4: Initialize Parameters

Load images and parameters:
- Click “Load images/parameters” button
- This reads all configuration and prepares the cameras
- Camera views should show calibration images
Check the setup:
- Camera count: 4 cameras (cam1, cam2, cam3, cam4)
- Image format: TIFF calibration images
- Parameters: Detection thresholds, tracking parameters loaded

Step 5: Explore Calibration

The test_cavity experiment comes with pre-calculated camera calibrations:

View calibration:
- Go to Calibration → Open Calibration (or click the calibration button)
- The calibration GUI opens showing camera positions and target images
Check calibration quality:
- Click “Load images/parameters” in calibration GUI
- Click “Show initial guess” to see projected calibration points
- Observe how well points align with detected features

Step 6: Detect Particles

Return to the main GUI and detect particles in the sequence:

Go to Sequence Processing:
- In the main GUI, ensure parameters are loaded
- Click “Detection” button
- This detects particles in all camera views for the current frame
Review detection results:
- Blue crosses appear on detected particles
- Check all 4 camera views for reasonable particle detection
- Particles should be clearly marked on the images

Step 7: Find Correspondences

Find matching particles across cameras:

Run correspondence:
- Click “Correspondences” button
- This matches particles between camera views
- Look for colored lines connecting corresponding particles
Check results:
- Good correspondences show consistent particle matches
- Status bar shows number of correspondences found

Step 8: Determine 3D Positions

Calculate 3D particle positions:

Run determination:
- Click “Determination” button
- This triangulates 3D positions from 2D correspondences
- Results are saved to files
View output files:
- Check the experiment directory for result files
- Look for files like rt_is.XXXXX with 3D positions

Step 9: Process Sequence (Optional)

For multiple frames:

Set frame range:
- Adjust sequence parameters if needed
- Set first and last frame numbers
Run sequence:
- Click “Sequence” button
- This processes the entire image sequence
- Progress is shown in the status bar

Understanding the Test Data

The test_cavity experiment includes:

Directory Structure

test_cavity/
├── parameters_Run1.yaml     # Main parameter file
├── cal/                     # Calibration data
│   ├── cam1.tif            # Calibration images
│   ├── cam1.tif.ori        # Camera orientations
│   ├── cam1.tif.addpar     # Additional parameters
│   └── target_on_a_side.txt # Calibration target coordinates
├── img/                     # Image sequences
│   ├── cam1.10000          # Frame images
│   ├── cam1.10001
│   └── ...
└── plugins/                 # Custom processing plugins

Key Parameters

4 cameras in a stereo configuration
Calibration target with known 3D coordinates
Particle detection tuned for dark particles on bright background
Tracking parameters set for moderate particle velocities

Typical Results

After processing, you should see:

~20-50 particles detected per camera per frame
~10-30 correspondences per frame
3D positions with coordinate accuracy of ~0.1 mm
Tracking data suitable for velocity analysis

Next Steps

Now that you’ve successfully run the test case:

Learn calibration: Follow the Calibration Guide
Set up your own experiment: See Parameter Migration
Explore plugins: Check out the Plugins Guide
Use advanced features: Try Splitter Mode

Common Issues

“No images found”

Check file paths in the YAML parameter file
Verify image format (should match what’s in img/ directory)

“Calibration failed”

Calibration files missing - check cal/ directory
Try the calibration GUI to debug calibration issues

“No particles detected”

Adjust detection thresholds in detect_plate parameters
Check image quality - particles should be clearly visible

“Poor correspondences”

Check calibration quality first
Adjust correspondence tolerances in criteria parameters

Performance Tips

RAM usage: Large image sequences require significant memory
Disk space: Allow ~1GB per 1000 frames for results
Processing time: Expect ~1-10 seconds per frame depending on particle count

Success! You’ve completed your first PyPTV analysis. Ready to set up your own experiment? See Parameter Migration to convert your existing setup.

Next: Running the GUI or Calibration Guide

This site is open source. Improve this page.