pyptv

Running the GUI

Learn how to use the PyPTV graphical user interface for particle tracking analysis.

Launching PyPTV

Command Line Launch

# Activate environment
conda activate pyptv

# Launch GUI from any directory
python -m pyptv.pyptv_gui


## GUI Requirements and Testing

The PyPTV GUI requires a display (X11 on Linux/macOS, or native on Windows). GUI-dependent tests are located in `tests_gui/` and are not run in CI or Docker. Run these tests locally or with Xvfb if needed.

For headless testing, see the main README and installation guide.

# Or from PyPTV source directory
cd pyptv
python -m pyptv.pyptv_gui

From Python Script

from pyptv.pyptv_gui import MainGUI
from pathlib import Path

# Launch with specific experiment
experiment_path = Path("path/to/your/experiment")
gui = MainGUI(experiment_path, Path.cwd())
gui.configure_traits()

GUI Overview

The PyPTV interface consists of several main areas:

1. Parameter Tree (Left Panel)

Experiment structure with parameter sets (Run1, Run2, etc.)
Right-click menus for parameter management
Expandable sections showing parameter groups

2. Camera Views (Center/Right)

Tabbed interface for multiple cameras
Image display with zoom and pan
Overlay graphics for particles, correspondences, and trajectories

3. Control Buttons (Top)

Processing buttons for detection, correspondence, tracking
Parameter editing and calibration access
Sequence processing controls

4. Status Bar (Bottom)

Progress indicators during processing
File information and current frame
Error messages and warnings

Main Workflow

1. Load Experiment

Option A: Load Existing YAML

File → Load Experiment → Select parameters.yaml

Option B: Load Legacy Parameters

File → Load Legacy → Select parameters/ folder
# Automatically converts to YAML format

Option C: Create New Experiment

File → New Experiment → Choose directory
# Creates basic parameter structure

2. Initialize Parameters

After loading an experiment:

Load images/parameters button
- Reads all configuration files
- Loads calibration data
- Prepares camera views
Verify setup:
- Check parameter tree is populated
- Ensure camera tabs are visible
- Confirm calibration images load

3. Single Frame Processing

Process one frame to test setup:

Detection:

Click "Detection" button
→ Blue crosses mark detected particles

Correspondences:

Click "Correspondences" button  
→ Colored lines connect matching particles

Determination:

Click "Determination" button
→ Calculates 3D positions

4. Sequence Processing

Process multiple frames:

Set frame range in sequence parameters
Click “Sequence” button
Monitor progress in status bar
Check output files in experiment directory

Parameter Management

Editing Parameters

Method 1: Right-click in Parameter Tree

Right-click parameter set → "Edit Parameters"
→ Opens parameter editing dialog

Method 2: Direct File Editing

Edit parameters.yaml in text editor
→ Reload experiment in GUI

Method 3: Calibration-specific

Calibration → Open Calibration
→ Specialized calibration interface

Parameter Sets

Create multiple parameter configurations:

Add new set:

Right-click in parameter tree → "Add Parameter Set"
→ Enter name (e.g., "HighSpeed", "LowLight")

Switch between sets:

Right-click parameter set → "Set as Active"

Copy settings:

Right-click → "Duplicate Parameter Set"

Parameter Sections

Key parameter groups:

Section	Purpose	Key Settings
ptv	General PTV settings	Image names, camera count, preprocessing
detect_plate	Particle detection	Gray thresholds, size limits
criteria	Correspondence matching	Search tolerances, minimum matches
track	Particle tracking	Velocity limits, trajectory linking
cal_ori	Calibration	Camera files, calibration images

Camera Views

Zoom: Mouse wheel or zoom tools
Pan: Click and drag
Reset view: Right-click → “Reset zoom”

Overlays

Blue crosses: Detected particles
Colored lines: Correspondences between cameras
Numbers: Particle IDs or point numbers
Trajectories: Particle paths over time

Camera-specific Operations

Right-click particle: Delete detection
Left-click: Add manual detection (in calibration mode)
Tab switching: Move between camera views

Processing Controls

Detection Settings

detect_plate:
  gvth_1: 80     # Primary detection threshold
  gvth_2: 40     # Secondary threshold
  min_npix: 5    # Minimum particle size
  max_npix: 100  # Maximum particle size

Correspondence Settings

criteria:
  eps0: 0.2      # Search radius (mm)
  corrmin: 2     # Minimum cameras for correspondence
  cn: 0.02       # Additional tolerance

Tracking Settings

track:
  dvxmin: -50.0  # Velocity limits (mm/frame)
  dvxmax: 50.0
  dvymin: -50.0
  dvymax: 50.0

File Management

Input Files

Image sequences: img/cam1.XXXXX, img/cam2.XXXXX, etc.
Calibration images: cal/cam1.tif, cal/cam2.tif, etc.
Parameter file: parameters.yaml

Output Files

Detection results: cam1_targets, cam2_targets, etc.
3D positions: rt_is.XXXXX files
Tracking data: ptv_is.XXXXX files
Calibration: Updated .ori and .addpar files

Advanced Features

Plugin Integration

Right-click parameter tree → "Configure Plugins"
→ Select tracking and sequence plugins

Batch Processing

# Script for multiple experiments
for experiment in experiment_list:
    gui.load_experiment(experiment)
    gui.process_sequence()
    gui.export_results()

Custom Visualization

# Add custom overlays
def custom_overlay(camera_view, data):
    camera_view.plot_custom_data(data)

Troubleshooting

Common Issues

“Images not found”

Check file paths in parameters.yaml
Verify image naming convention
Ensure correct working directory

“Calibration errors”

Open calibration GUI to debug
Check .ori and .addpar files exist
Verify calibration target coordinates

“No particles detected”

Adjust detection thresholds
Check image contrast and quality
Try preprocessing options

“Poor correspondences”

Improve calibration accuracy
Adjust search tolerances
Check camera synchronization

Performance Tips

Memory usage: Close unused camera tabs
Processing speed: Reduce image resolution if possible
Disk I/O: Use SSD for image sequences
Parallel processing: Enable multi-threading in plugins

Debugging Mode

Enable verbose output:

python -m pyptv.pyptv_gui --debug

Check log files:

tail -f pyptv.log

Keyboard Shortcuts

Key	Action
`Ctrl+O`	Open experiment
`Ctrl+S`	Save parameters
`F5`	Refresh/reload
`Space`	Process next frame
`Esc`	Cancel current operation

Best Practices

Workflow Organization

Test single frame before sequence processing
Save parameter changes before major operations
Back up original parameters before modifications
Use descriptive parameter set names

Data Management

Keep experiment folders organized
Use consistent naming conventions
Document parameter changes
Archive completed experiments

Quality Control

Regularly check calibration accuracy
Monitor particle detection quality
Validate tracking results
Compare with expected physical behavior

Next: Learn about Camera Calibration or Parameter Migration

This site is open source. Improve this page.