pyptv

Examples and Workflows

This guide provides practical examples and common workflows for using PyPTV effectively.

Test Cavity Example

The test_cavity example is included with PyPTV and demonstrates a complete 4-camera PTV setup.

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.

Location and Setup

cd tests/test_cavity
ls -la

You’ll find:

test_cavity/
├── parameters_Run1.yaml     # Main parameter file
├── cal/                     # Calibration data
│   ├── cam1.tif - cam4.tif # Calibration images
│   ├── *.ori               # Calibration results
│   ├── *.addpar            # Additional parameters
│   └── target_on_a_side.txt # Target coordinates
├── img/                     # Image sequence
│   ├── cam1.10001 - cam1.10004
│   ├── cam2.10001 - cam2.10004
│   ├── cam3.10001 - cam3.10004
│   └── cam4.10001 - cam4.10004
└── plugins/                 # Example plugins
    ├── ext_sequence_*.py
    └── ext_tracker_*.py

Running the Test Cavity Example

1. Navigate to the test directory

   cd tests/test_cavity
   

2. Start PyPTV GUI

   python -m pyptv
   

3. Load the experiment
   • File → Open Experiment
   • Select parameters_Run1.yaml
4. Explore the setup
   • View calibration images: Tools → Calibration
   • Check detection: Tools → Detection
   • Run tracking: Process → Track Particles

Key Learning Points

The test_cavity example demonstrates:

• 4-camera setup with proper calibration
• Correct YAML structure with num_cams: 4
• Plugin system usage
• Complete workflow from calibration to tracking

Common Workflows

Workflow 1: New Experiment Setup

Starting a new PTV experiment from scratch.

Step 1: Create Directory Structure

mkdir my_experiment
cd my_experiment

# Create subdirectories
mkdir cal img results

# Copy template from test_cavity
cp tests/test_cavity/parameters_Run1.yaml parameters_my_experiment.yaml

Step 2: Modify Parameters

Edit parameters_my_experiment.yaml:

num_cams: 3  # Adjust for your camera count

sequence:
  base_name:
    - img/cam1.%d
    - img/cam2.%d  
    - img/cam3.%d
  first: 1
  last: 100

cal_ori:
  img_cal_name:
    - cal/cam1_cal.tif
    - cal/cam2_cal.tif
    - cal/cam3_cal.tif
  fixp_name: cal/my_target.txt

Step 3: Add Your Data

# Copy calibration images
cp /path/to/calibration/cam1.tif cal/cam1_cal.tif
cp /path/to/calibration/cam2.tif cal/cam2_cal.tif
cp /path/to/calibration/cam3.tif cal/cam3_cal.tif

# Copy image sequence
cp /path/to/sequence/cam1_* img/
cp /path/to/sequence/cam2_* img/
cp /path/to/sequence/cam3_* img/

# Create target coordinate file
cat > cal/my_target.txt << EOF
# X     Y     Z     ID
-30.0  -30.0  0.0   1
 30.0  -30.0  0.0   2
 30.0   30.0  0.0   3
-30.0   30.0  0.0   4
EOF

Step 4: Run Calibration

1. Open PyPTV GUI
2. Load your parameter file
3. Tools → Calibration
4. Detect calibration points
5. Run calibration
6. Check residuals

Step 5: Process Sequence

1. Tools → Detection (test on single frame)
2. Process → Correspondences
3. Process → Track Particles
4. Analyze results

Workflow 2: Parameter Optimization

Optimizing parameters for better tracking results.

Detection Optimization

Start with conservative detection parameters:

detect_plate:
  gvth_1: 50    # Start higher, reduce if too few particles
  gvth_2: 50
  gvth_3: 50
  min_npix: 20  # Minimum particle size
  max_npix: 200 # Maximum particle size

Test detection on a representative frame:

1. Tools → Detection
2. Adjust thresholds in real-time
3. Save optimized values to YAML

Tracking Optimization

Adjust tracking parameters based on your flow:

track:
  # For slow flows
  dvxmax: 5.0
  dvxmin: -5.0
  dvymax: 5.0
  dvymin: -5.0
  dvzmax: 2.0
  dvzmin: -2.0
  
  # For fast flows
  dvxmax: 50.0
  dvxmin: -50.0
  # ... etc

Workflow 3: Multi-Plane Calibration

For large measurement volumes or improved accuracy.

Setup Multi-Plane Configuration

multi_planes:
  n_planes: 3
  plane_name:
    - cal/plane_front
    - cal/plane_middle  
    - cal/plane_back

Calibration Process

1. Take calibration images at multiple Z positions
2. Configure plane parameters
3. Run calibration for each plane
4. Combine results for improved 3D accuracy

Workflow 4: Using Plugins

PyPTV supports plugins for extended functionality.

Available Plugins

Check available plugins in your parameter file:

plugins:
  available_tracking:
    - default
    - ext_tracker_splitter    # For splitter systems
  available_sequence:
    - default
    - ext_sequence_rembg      # Background removal
    - ext_sequence_contour    # Contour detection
  selected_tracking: default
  selected_sequence: default

Background Removal Plugin

To use background removal:

1. Install dependencies:

   pip install rembg[cpu]  # or rembg[gpu]
   

2. Enable in parameters:

   plugins:
     selected_sequence: ext_sequence_rembg
   

3. The plugin will automatically remove backgrounds during processing

Splitter System Plugin

For splitter-based stereo systems:

plugins:
  selected_tracking: ext_tracker_splitter

ptv:
  splitter: true

cal_ori:
  cal_splitter: true

Troubleshooting Common Issues

Issue: Poor Calibration Quality

Symptoms: High residuals, tracking errors

Solutions:

1. Check target coordinate file accuracy
2. Improve calibration image quality
3. Use more calibration points
4. Verify camera stability

Issue: Few or No Particles Detected

Symptoms: Empty detection results

Solutions:

1. Lower detection thresholds
2. Check image contrast
3. Verify image file paths
4. Adjust min/max pixel counts

Issue: Poor Tracking Performance

Symptoms: Broken trajectories, false matches

Solutions:

1. Optimize detection parameters first
2. Adjust velocity limits
3. Check correspondence criteria
4. Improve temporal resolution

Issue: Memory or Performance Problems

Symptoms: Slow processing, crashes

Solutions:

1. Process smaller batches
2. Reduce image resolution if possible
3. Use efficient file formats
4. Close unnecessary applications

Data Analysis Examples

Basic Trajectory Analysis

After tracking, analyze results with Python:

import numpy as np
import matplotlib.pyplot as plt

# Load tracking results (format depends on output)
# trajectories = load_trajectories('results/trajectories.txt')

# Example analysis
# velocities = compute_velocities(trajectories)
# plot_velocity_field(velocities)

Statistical Analysis

# Compute flow statistics
# mean_velocity = np.mean(velocities, axis=0)
# velocity_fluctuations = velocities - mean_velocity
# turbulent_intensity = np.std(velocity_fluctuations, axis=0)

Best Practices Summary

Experimental Setup

• Use stable camera mounts
• Ensure good lighting and contrast
• Take high-quality calibration images
• Include sufficient calibration points

Parameter Configuration

• Start with test_cavity as template
• Use only num_cams, never n_img
• Test parameters on single frames first
• Document parameter changes

Processing Workflow

• Always calibrate first
• Validate detection on test frames
• Process in small batches initially
• Monitor intermediate results

Data Management

• Use consistent file naming
• Backup original data
• Document processing parameters
• Archive final results

See Also

• Quick Start Guide
• Calibration Guide
• YAML Parameters Guide
• GUI Usage Guide

This site is open source. Improve this page.