Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Football Analyzer - Deep-SORT Tracking

A Deep-SORT (Deep Learning + Simple Online and Realtime Tracking) implementation for tracking football players and the ball in match videos.

Demo Results

Sample Detection

Detection Results

Tracked Video Output

Watch the full tracked video: footballmatch_tracked.mp4

The tracking system successfully identifies and tracks:

  • Players: Blue bounding boxes with persistent IDs
  • Ball: Green bounding box with unique ID
  • Real-time FPS and track count overlays

Project Structure

src/football-analyzer/
├── main.py                          # Main entry point for running tracking
├── media/                           # Input video directory
│   └── footballmatch.mp4           # Sample input video
├── output/                          # Output video directory
│   └── footballmatch_tracked.mp4   # Tracked output videos
├── src/
│   └── football-analyzer/
│       ├── tracking/                # Core tracking modules
│       │   ├── __init__.py         # Package initialization
│       │   ├── detection.py        # Detection class
│       │   ├── kalman_filter.py    # Kalman filter for motion prediction
│       │   ├── track.py            # Track management
│       │   ├── tracker.py          # Main tracker class
│       │   ├── matching.py         # IoU and Hungarian matching
│       │   ├── distance_metric.py  # Appearance-based distance
│       │   ├── feature_extractor.py # Appearance feature extraction
│       │   └── visualization.py    # Drawing tracked boxes
│       ├── video_processor.py      # Video processing pipeline
│       ├── Tracking Model.ipynb    # Interactive notebook for exploration
│       └── yolo11x.pt             # YOLO model weights
├── tests/                          # Unit tests
└── README.md                       # This file

Features

  • Dual Tracking: Separate trackers for players and ball with optimized parameters
  • Deep-SORT Algorithm: Combines detection, Kalman filtering, and appearance features
  • YOLO11x Detection: State-of-the-art object detection
  • Customizable Parameters: Fine-tune tracking for your use case
  • GPU Acceleration: Supports CUDA, MPS (Apple Silicon), and CPU

Installation

Prerequisites

  • Python 3.8+
  • pip

Install Dependencies

cd src/football-analyzer
pip install ultralytics opencv-python numpy scipy torch

Or if you have a requirements.txt:

pip install -r requirements.txt

Usage

Basic Usage

Run tracking on the default video:

cd src/football-analyzer
python main.py

This will:

  • Process media/footballmatch.mp4
  • Save output to output/footballmatch_tracked.mp4

Custom Input/Output

python main.py --input myvideo.mp4 --output myvideo_tracked.mp4

Advanced Options

python main.py \
    --input myvideo.mp4 \
    --output myvideo_tracked.mp4 \
    --model yolo11x.pt \
    --conf-threshold 0.6 \
    --ball-conf-threshold 0.15 \
    --max-age 40 \
    --ball-max-age 50

All Available Options

General:

  • --input, -i: Input video file (relative to media/ or absolute path)
  • --output, -o: Output video file (relative to output/ or absolute path)
  • --model: YOLO model weights file (default: yolo11x.pt)

Person Tracking:

  • --conf-threshold: Detection confidence threshold (default: 0.5)
  • --max-age: Max frames to keep track alive without detection (default: 30)
  • --n-init: Detections needed to confirm track (default: 3)
  • --max-iou-distance: Max IoU distance for matching (default: 0.7)

Ball Tracking:

  • --ball-conf-threshold: Detection confidence threshold (default: 0.2)
  • --ball-max-age: Max frames to keep track alive (default: 45)
  • --ball-n-init: Detections needed to confirm track (default: 1)
  • --ball-max-iou-distance: Max IoU distance for matching (default: 0.95)

Help

python main.py --help

How It Works

1. Detection

  • YOLO11x detects persons (class 0) and sports balls (class 32)
  • Separate confidence thresholds for each class

2. Feature Extraction

  • Extracts appearance features from detected objects
  • Current: Color histograms (can be replaced with CNN features)

3. Tracking

  • Kalman Filter: Predicts object motion between frames
  • Hungarian Algorithm: Optimally matches detections to tracks
  • Track Management: Creates, updates, and removes tracks

4. Visualization

  • Draws bounding boxes with unique track IDs
  • Color-coded: Blue for persons, Green for ball
  • Displays FPS and active track counts

Deep-SORT Architecture

Frame Input
    ↓
┌───────────────┐
│ YOLO Detection│ → Detections (bbox + confidence)
└───────────────┘
    ↓
┌───────────────┐
│Feature Extract│ → Appearance features
└───────────────┘
    ↓
┌───────────────┐
│ Kalman Filter │ → Predicted positions
└───────────────┘
    ↓
┌───────────────┐
│  Hungarian    │ → Detection-Track matches
│  Matching     │
└───────────────┘
    ↓
┌───────────────┐
│Track Update   │ → Updated tracks
└───────────────┘
    ↓
Output Frame with Tracked Objects

Module Details

detection.py

Represents a detected object with:

  • Bounding box (tlwh format)
  • Confidence score
  • Class name
  • Appearance feature vector

kalman_filter.py

8D state space (x, y, aspect ratio, height, velocities):

  • initiate(): Create new track
  • predict(): Predict next state
  • update(): Update with measurement
  • gating_distance(): Compute Mahalanobis distance

track.py

Manages individual tracks:

  • States: Tentative → Confirmed → Deleted
  • Properties: ID, hits, age, time since update
  • Features: Appearance history for matching

tracker.py

Main tracking orchestration:

  • Manages all tracks
  • Runs prediction and update cycle
  • Handles track creation and deletion
  • Updates distance metrics

matching.py

Data association:

  • iou(): Compute intersection over union
  • iou_cost(): Generate cost matrix
  • min_cost_matching(): Hungarian algorithm

distance_metric.py

Appearance-based matching:

  • Cosine distance between feature vectors
  • Maintains feature history per track
  • Nearest neighbor matching

feature_extractor.py

Extract appearance features:

  • Current: RGB color histograms
  • Can be replaced with deep CNN (ResNet, etc.)

visualization.py

Draw tracking results:

  • Bounding boxes with track IDs
  • Class-based color coding
  • Text overlays

Customization

Using Different YOLO Models

Place your model in src/football-analyzer/:

python main.py --model yolo11n.pt  # Nano (faster)
python main.py --model yolo11l.pt  # Large
python main.py --model yolo11x.pt  # Extra large (best accuracy)

Tuning Tracking Parameters

For slower-moving objects (players):

  • Increase --max-age (keep track alive longer)
  • Increase --n-init (require more confirmations)
  • Lower --max-iou-distance (stricter matching)

For fast-moving objects (ball):

  • Decrease --ball-max-age (remove lost tracks quickly)
  • Decrease --ball-n-init (instant confirmation)
  • Increase --ball-max-iou-distance (allow more movement)

Better Feature Extraction

Replace SimpleFeatureExtractor in feature_extractor.py with a CNN:

class DeepFeatureExtractor:
    def __init__(self):
        self.model = torchvision.models.resnet50(pretrained=True)
        # Remove last layer, use features
        self.model = torch.nn.Sequential(*list(self.model.children())[:-1])
    
    def __call__(self, image, boxes):
        # Extract patches and run through CNN
        ...

Interactive Notebook

Use Tracking Model.ipynb to:

  • Explore the tracking algorithm step-by-step
  • Visualize detection and tracking
  • Test different parameters
  • Prototype new features

Performance

Typical performance on Apple Silicon (M1/M2/M3):

  • FPS: 15-25 fps (depends on resolution and number of objects)
  • GPU: MPS acceleration with YOLO11x
  • Memory: ~2-4GB

Troubleshooting

Video not found

Ensure your video is in the media/ directory or provide absolute path:

python main.py --input /path/to/video.mp4

Model not found

Download YOLO11 models:

# The models should already be in src/football-analyzer/
# If missing, download from: https://github.com/ultralytics/ultralytics

Slow processing

  • Use a smaller YOLO model: --model yolo11n.pt
  • Reduce video resolution before processing
  • Ensure GPU acceleration is working

Poor tracking

  • Adjust confidence thresholds
  • Tune IoU distance parameters
  • Increase/decrease max_age and n_init

References

License

This project is for educational and research purposes.

Future Improvements

  • Support multiple ball tracking
  • Balls should be tracked using non CV kalman filters

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages