How aaditya29/dfl---bundesliga-data-shootout-analysis works
Project Type and Purpose
• This is a Python-based computer-vision pipeline for sports analytics (specifically soccer) that ingests video, runs object detection using YOLO, tracks objects, computes metrics (speed, distance, camera motion), and outputs annotated video and data.
• The README confirms: “Detect players and ball in video,” “Track movement,” and “Perform analysis.”
File-Structure Analysis
• Top-level orchestrator:
• main.py – entry point driving the pipeline.
• yolo-inference.py – utilities to launch YOLO model inference.
• Model assets:
• models/*.pt – trained YOLO weights.
• yolov8s.pt – fallback YOLOv8 small weights.
• Modules (each a component in the pipeline):
• camera_movement_estimator/ – computes camera motion between frames.
• player_ball_assigner/ – attaches detection IDs to players vs ball.
• speed_and_distance_estimator/ – calculates movement metrics (speed, distance).
• team_assigner/ – assigns player detections to home/away teams.
• trackers/ – encapsulates multi-object tracker abstraction.
• view_transformer/ – maps image coordinates to pitch/world coordinates.
• utils/ – helper functions (bbox_utils.py, video_utils.py).
• Data directories:
• input-videos/ – source video files.
• output_videos/ – annotated output.
• runs/detect/ – YOLO’s per-run inference outputs.
• Training:
• training/… – YOLO dataset structure for retraining.
Extracted Architecture
• Core pipeline sequence:
Input Video → YOLO Detector → Tracker → Post-Processing & Assignment → Estimators → View Transformer → Output Video & Data.
• External dependencies: OpenCV for frame handling, Ultralytics/YOLO for detection, NumPy/Pandas for data arrays, Matplotlib for plotting, Supervision for annotation.
a. Main Components
• Video Input (input-videos/)
• YOLO Detector (yolo-inference.py + models/*.pt)
• Tracker (trackers/tracker.py)
• Assignment Modules:
• player_ball_assigner
• team_assigner
• Estimators:
• camera_movement_estimator
• speed_and_distance_estimator
• Coordinate Mapper (view_transformer)
• Video/Data Output (output_videos/, CSV, logs)
• Utilities (utils/*.py)
b. Interactions
1. main.py reads raw frames.
3. Tracker ingests detections + previous states → outputs track IDs.
4. Assigners tag each detection as “ball” or “player” and team.
5. Camera Movement Estimator computes global motion from successive frames.
6. Speed & Distance Estimator uses tracked positions + camera motion to compute metrics.
7. View Transformer converts pixel positions to real-world/pitch coordinates.
8. Annotated frames & data streams are written to output.
c. Architectural Patterns
• Modular pipeline: each stage isolated in its own package.
• Single Responsibility per module (detection, tracking, assignment, estimation, transformation).
• Orchestration in main.py using sequential data flow.
d. Technology Stack
• Python 3.x, OpenCV, NumPy, Pandas, Matplotlib
• YOLO (Ultralytics YOLOv5/YOLOv8)
• Supervision (optional annotation library)
• Custom modules for each processing stage.
Essential Details
• Main.py at the center or top as orchestrator.
• How YOLO model weights feed into the detection component.