WALDO Object Tracker - Standalone PyQt5 Application

A standalone PyQt5 desktop application for advanced single-object tracking in videos and RTSP streams using YOLO deep learning models. Features an intuitive grid-based interface with real-time dual video display, automated object detection, and customizable tracking parameters. Scans video frames or live streams to detect all objects, allows selection of target object, then tracks it throughout with bounding box annotations, trajectory trails, and comprehensive statistics.

Key Features

Advanced Tracking

Single Object Tracking: Focus on one object with high precision
YOLO + DeepSORT Integration: State-of-the-art detection and tracking
Motion Prediction: Anticipate object movement for robust tracking
Lost Object Recovery: Automatically reacquire lost tracks

Dual Input Support

Video Files: MP4, AVI, MOV, MKV formats
RTSP Streams: Live camera feeds with connection testing
Flexible Sources: Switch between file and stream modes

Rich Visualization

Dual Video Panels: Side-by-side input/output display
Trajectory Trails: Fading path visualization
Bounding Boxes: Corner markers and center crosshairs
Real-time Statistics: Speed, distance, tracking status
Zoom Mode: Keep tracked object centered

Data Export

Tracked Videos: MP4 output with annotations
JSON Data: Complete tracking information
Statistics: Distance traveled, speed metrics
Trajectory Coordinates: Full position history

User-Friendly Interface

Grid Layout: Organized three-column design
File Selection: Easy input source management
Object Selection Table: Visual object picker
Live Processing Log: Real-time status updates
Progress Tracking: Visual progress indicators

Python Dependencies

PyQt5>=5.15.0
ultralytics>=8.0.0
opencv-python>=4.5.0
opencv-contrib-python>=4.5.0
deep-sort-realtime>=1.3.0
numpy>=1.19.0
Pillow>=8.0.0

Quick Start

1. Installation

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

# Create virtual environment (recommended)
python3 -m venv waldo_env
source waldo_env/bin/activate  # On Windows: waldo_env\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Using Installation Script

Linux/macOS:

chmod +x install.sh
./install.sh

Windows:

python -m pip install -r requirements.txt
python waldo_tracker/main.py

3. Launch Application

# From project root
python3 waldo_tracker/main.py

# Or from waldo_tracker directory
cd waldo_tracker
python3 main.py

Usage Guide

Step-by-Step Workflow

1. Launch Application

cd GUI_WALDO_TRACKER
python3 waldo_tracker/main.py

The application will open in maximized window mode.

2. Select Input Source

Option A: Video File

Ensure "Video File" button is selected (blue)
Click "Browse Video" button
Select your video file (MP4, AVI, MOV, MKV)
File name appears in the display field

Option B: RTSP Stream

Click "RTSP Stream" button
Enter RTSP URL in format: rtsp://username:password@ip:port/stream
Click "Test Connection" to verify stream
Wait for success confirmation

3. Select WALDO Model

Click "Browse Model" button
Select your WALDO model file (.pt extension)
Default: WALDO30_yolov8n_640x640.pt
Model name appears in display field

4. Configure Tracking Settings

Confidence Threshold (0.10 - 0.90)

Default: 0.25
Lower value: More detections (may include false positives)
Higher value: Fewer detections (more precise)

Scan Frames (10 - 500)

Default: 100
Number of initial frames to analyze
More frames = better object detection (slower scan)

Zoom Mode (Optional)

Enable to keep tracked object centered
Creates focused view of target object
Useful for detailed analysis

5. Scan for Objects

Click "Scan Initial Frames" button
Wait for scanning progress (progress bar shown)
Detected objects appear in the table with:
- ID: Unique object identifier
- Class: Object type (LightVehicle, Person, Truck, etc.)
- First Frame: First frame where object appears
- Last Frame: Last frame where object appears
- Position: Bounding box coordinates

6. Select Target Object

Click on any row in the "Detected Objects" table
Selected object is highlighted
Confirmation appears in Processing Log
"Start Tracking" button becomes enabled

7. Start Tracking

Click "Start Tracking" button
Watch real-time tracking in video panels:
- Left Panel: Original input video
- Right Panel: Tracked output with annotations
Monitor progress in:
- Progress bar at bottom
- Processing log (right column)
- Frame counter and statistics

8. View Results

Output video saved to ~/WALDO_Tracking_Output/
JSON tracking data saved to ~/WALDO_Tracking_Output/tracking_data/
Statistics displayed in Processing Log:
- Frames tracked / Total frames
- Distance traveled (pixels)
- Average speed (px/s)
- Maximum speed (px/s)

Interface Layout

Visualization Features

Bounding Box Annotations

Yellow Box: Main bounding box around object
Corner Markers: Enhanced corner visibility
Center Crosshair: Precise center point marker
Thickness: 3-5 pixels for clear visibility

Trajectory Trail

Fading Effect: Recent positions brighter, older fade
Cyan Color: Easy to distinguish from other elements
Variable Thickness: 2-5 pixels based on age
40 Points: Smooth continuous trail

Information Overlay

Status Banner: TRACKING (green) or SEARCHING (red)
Frame Counter: Current frame / Total frames
Speed Display: Current and maximum speed
Distance Counter: Total distance traveled
Track ID: Current tracking identifier

Progress Bar

Bottom Strip: Full-width progress indicator
Green Fill: Visual completion percentage
Frame-accurate: Updates every 5 frames

Output Files

Video Output

~/WALDO_Tracking_Output/
├── input_video_tracking_LightVehicle_20241110_132625.mp4
├── input_video_tracking_Person_20241110_133015.mp4
└── rtsp_stream_tracking_Truck_20241110_134500_zoom.mp4

Filename Format: {source}_tracking_{class}_{timestamp}[_zoom].mp4

Codec: H.264 (MP4V)
Resolution: Same as input
FPS: Same as input
Annotations: Embedded in video

JSON Data

~/WALDO_Tracking_Output/tracking_data/
└── input_video_tracking_LightVehicle_20241110_132625_tracking_data.json

JSON Structure:

{
  "video_info": {
    "input_path": "/path/to/input.mp4",
    "output_path": "/path/to/output.mp4",
    "total_frames": 929,
    "tracked_frames": 856
  },
  "selected_object": {
    "class_name": "LightVehicle",
    "class_id": 0,
    "id": 1
  },
  "statistics": {
    "total_distance": 1452.3,
    "max_speed": 275.2,
    "avg_speed": 158.9,
    "tracking_percent": 92.1
  },
  "trajectory": [
    [320.5, 240.8],
    [322.1, 241.2],
    ...
  ]
}

Advanced Configuration

Supported WALDO Classes

CLASS_NAMES = {
    0: 'LightVehicle',  # Cars, SUVs
    1: 'Person',        # Pedestrians
    2: 'Building',      # Structures
    3: 'UPole',         # Utility poles
    4: 'Boat',          # Watercraft
    5: 'Bike',          # Bicycles, motorcycles
    6: 'Container',     # Shipping containers
    7: 'Truck',         # Trucks, vans
    8: 'Gastank',       # Fuel tanks
    10: 'Digger',       # Construction equipment
    11: 'Solarpanels',  # Solar installations
    12: 'Bus'           # Buses
}

DeepSORT Parameters

tracker = DeepSort(
    max_age=30,              # Frames to keep lost tracks
    n_init=3,                # Frames to confirm track
    nn_budget=100,           # Feature matching budget
    max_iou_distance=0.7     # IoU threshold for matching
)

Tracker Settings

advanced_tracker = AdvancedTracker(
    history_length=50,       # Trajectory points to store
    fps=30                   # Video frame rate
)

Troubleshooting

Common Issues

1. "Module not found" errors

# Activate virtual environment
source waldo_env/bin/activate

# Reinstall dependencies
pip install -r requirements.txt

# Verify installation
python -c "import cv2, ultralytics, PyQt5; print('OK')"

2. "Failed to open video"

# Install FFmpeg
sudo apt install ffmpeg  # Linux
brew install ffmpeg      # macOS

# Convert video format
ffmpeg -i input.mov -c:v libx264 -c:a aac output.mp4

3. RTSP Connection Failed

Check network connectivity
Verify RTSP URL format: rtsp://user:pass@192.168.1.100:554/stream1
Test with VLC Player first
Check firewall settings
Ensure camera/NVR is accessible

4. "No objects detected"

Lower confidence: Try 0.15-0.20
Increase scan frames: Try 150-200
Check video quality: Ensure good lighting
Verify model: Use correct WALDO model file
Check object types: Ensure objects are in WALDO class list

5. Slow processing

# Enable GPU acceleration
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

# Verify GPU
python -c "import torch; print(torch.cuda.is_available())"

# Reduce video resolution
ffmpeg -i input.mp4 -vf scale=1280:720 output_720p.mp4

6. Application crashes

Check Python version (3.8+)
Update PyQt5: pip install --upgrade PyQt5
Check system resources (RAM, disk space)
Review error in terminal output

7. Qt platform plugin errors

# Linux
export QT_QPA_PLATFORM=xcb
unset QT_QPA_PLATFORM_PLUGIN_PATH

# Run application
python3 waldo_tracker/main.py

Use Cases

1. Traffic Monitoring

Track specific vehicles
Analyze vehicle speeds
Count vehicle movements
Study traffic patterns

2. Security Surveillance

Track persons of interest
Monitor restricted areas
Analyze movement patterns
Generate activity reports

3. Sports Analysis

Track player movements
Analyze ball trajectory
Study team formations
Calculate player speed

4. Wildlife Monitoring

Track animal movements
Study migration patterns
Calculate travel distances
Analyze behavior

5. Industrial Monitoring

Track equipment movement
Monitor conveyor systems
Analyze workflow efficiency
Safety monitoring

Performance Tips

Optimize Processing Speed

Use GPU Acceleration

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118

Reduce Video Resolution
- Process at 720p instead of 4K
- Use FFmpeg for conversion
Adjust Parameters
- Lower confidence threshold (faster but less accurate)
- Reduce scan frames (50-100 sufficient for most cases)
- Decrease history length (30-40 for shorter trails)
Hardware Recommendations
- CPU: Intel i7/AMD Ryzen 7 or better
- RAM: 16GB minimum
- GPU: NVIDIA GTX 1060 or better
- SSD: For faster I/O operations

Development

Project Structure

GUI_WALDO_TRACKER/
├── README.md
├── requirements.txt
├── install.sh
├── docs/
│   ├── installation.md
│   └── user_guide.md
└── waldo_tracker/
    ├── main.py                        # Application entry point
    ├── waldo_tracker_standalone.py    # Main GUI dialog
    ├── object_scanner_standalone.py   # Scanner & video processor
    ├── advanced_tracker.py            # Tracking algorithms
    ├── rtsp_connection_handler.py     # RTSP utilities (if present)
    ├── rtsp_connection_tester.py      # RTSP testing (if present)
    └── resources/
        └── icon.png                   # Application icon

Extending the Application

Add New Object Classes: Edit object_scanner_standalone.py:

CLASS_NAMES = {
    # ... existing classes ...
    13: 'MyNewClass',
}

Customize Visualization: Edit object_scanner_standalone.py in draw_visualization() method.

Add New Features:

Modify waldo_tracker_standalone.py for UI changes
Modify object_scanner_standalone.py for tracking logic
Modify advanced_tracker.py for algorithms

Additional Resources

Documentation

Installation Guide
User Guide
YOLO Documentation: https://docs.ultralytics.com
DeepSORT Paper: https://arxiv.org/abs/1703.07402

Sample Data

Test videos: Use your own or public datasets
RTSP streams: Set up local test camera

Changelog

Version 1.0.0 (Current)

✅ Initial release
✅ Video file support
✅ RTSP stream support
✅ Dual panel display
✅ Grid-based interface
✅ Advanced tracking with DeepSORT
✅ Trajectory visualization
✅ JSON data export
✅ Zoom mode
✅ Real-time statistics

Name		Name	Last commit message	Last commit date
Latest commit History 36 Commits
docs		docs
waldo_tracker		waldo_tracker
README.md		README.md
install.sh		install.sh
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation