How sahilnayak7702/football-analysis-computervision works
Project Type and Purpose
• This is a standalone, command-line computer-vision pipeline for football match analysis. It ingest videos, runs object detection (players, referees, ball), tracks all objects, computes metrics (speed, distance, team IDs), compensates for camera motion and perspective, and writes an annotated output video.
Main Architectural Components
a. Video I/O & Preprocessing
• Component: Input Video Manager (utils/video_utils.py)
• Reads raw video frames and forwards them downstream.
b. Perspective & Camera Compensation
• Component: View Transformer (view_transformer/view_transformer.py)
• Applies homography/perspective transform to normalize field view.
• Uses precomputed camera motion stubs (stubs/camera_movement_stub.pkl) and optical-flow.
c. Object Detection Engine
• Component: YOLO Inference (yolo_inference.py)
• Loads YOLOv8 weights (yolov8x.pt or training/*.pt).
d. Tracking
• Component: Tracker (trackers/tracker.py)
• Uses Kalman filtering and association logic to maintain object tracks over time.
• Optionally uses stubs/track_stubs.pkl to warm-start or replay.
e. Assigners & Classification
• Player & Ball Assigner (player_ball_assigner/player_ball_assigner.py): distinguishes ball from players and referees.
f. Metric Computation
• Speed & Distance Estimator (speed_and_distance_estimator/speed_and_distance_estimator.py): computes instantaneous speed and total distance per track.
g. Output Rendering
Data & Model Resources
• models/best.pt, models/last.pt: pretrained detection weights.
• stubs/*.pkl: serialized camera/track data for offline testing or warm-start.
• training/…: YOLOv5 training datasets and notebooks (not part of runtime but useful for retraining).
Relationships & Data Flow
1. Input Video → Video I/O
2. → Perspective Transformer → Camera Motion Estimator
3. → YOLO Inference → Tracker
4. Tracker → Player & Ball Assigner
5. → Team Assigner → Speed & Distance Estimator
6. → Output Rendering → Annotated Video file
Architectural Patterns & Principles
• Pipeline / data-flow architecture: each module consumes frames or track data and emits enriched data.
• Modular separation: detection, tracking, assignment, estimation, rendering each live in its own package.
• Reusability: utils contains shared helpers (bbox_utils, video_utils).