A Deep-SORT (Deep Learning + Simple Online and Realtime Tracking) implementation for tracking football players and the ball in match videos.
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
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
- 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
- Python 3.8+
- pip
cd src/football-analyzer
pip install ultralytics opencv-python numpy scipy torchOr if you have a requirements.txt:
pip install -r requirements.txtRun tracking on the default video:
cd src/football-analyzer
python main.pyThis will:
- Process
media/footballmatch.mp4 - Save output to
output/footballmatch_tracked.mp4
python main.py --input myvideo.mp4 --output myvideo_tracked.mp4python 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 50General:
--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)
python main.py --help- YOLO11x detects persons (class 0) and sports balls (class 32)
- Separate confidence thresholds for each class
- Extracts appearance features from detected objects
- Current: Color histograms (can be replaced with CNN features)
- Kalman Filter: Predicts object motion between frames
- Hungarian Algorithm: Optimally matches detections to tracks
- Track Management: Creates, updates, and removes tracks
- Draws bounding boxes with unique track IDs
- Color-coded: Blue for persons, Green for ball
- Displays FPS and active track counts
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
Represents a detected object with:
- Bounding box (tlwh format)
- Confidence score
- Class name
- Appearance feature vector
8D state space (x, y, aspect ratio, height, velocities):
initiate(): Create new trackpredict(): Predict next stateupdate(): Update with measurementgating_distance(): Compute Mahalanobis distance
Manages individual tracks:
- States: Tentative → Confirmed → Deleted
- Properties: ID, hits, age, time since update
- Features: Appearance history for matching
Main tracking orchestration:
- Manages all tracks
- Runs prediction and update cycle
- Handles track creation and deletion
- Updates distance metrics
Data association:
iou(): Compute intersection over unioniou_cost(): Generate cost matrixmin_cost_matching(): Hungarian algorithm
Appearance-based matching:
- Cosine distance between feature vectors
- Maintains feature history per track
- Nearest neighbor matching
Extract appearance features:
- Current: RGB color histograms
- Can be replaced with deep CNN (ResNet, etc.)
Draw tracking results:
- Bounding boxes with track IDs
- Class-based color coding
- Text overlays
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)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)
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
...Use Tracking Model.ipynb to:
- Explore the tracking algorithm step-by-step
- Visualize detection and tracking
- Test different parameters
- Prototype new features
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
Ensure your video is in the media/ directory or provide absolute path:
python main.py --input /path/to/video.mp4Download YOLO11 models:
# The models should already be in src/football-analyzer/
# If missing, download from: https://github.com/ultralytics/ultralytics- Use a smaller YOLO model:
--model yolo11n.pt - Reduce video resolution before processing
- Ensure GPU acceleration is working
- Adjust confidence thresholds
- Tune IoU distance parameters
- Increase/decrease
max_ageandn_init
This project is for educational and research purposes.
- Support multiple ball tracking
- Balls should be tracked using non CV kalman filters