How alvaronovillo/ds_padel works
Project type and purpose
• This is a specialized computer‐vision pipeline (a Python framework) for automatically tracking padel games in two dimensions from a single camera feed.
• Its goal is to detect the court, players, and ball; compute a homography to map detections onto a standardized 2D court; and output player/ball trajectories.
File structure
• Top‐level orchestrator:
• main.py – entry point that ties modules together.
• Core packages:
• minicourt/mini_court.py – court detection and homography calculation.
• trackers/ – three tracker modules:
– court_tracker.py (court contours & homography)
– player_tracker.py (YOLOv8 detection + homography transform)
– ball_tracknet.py (TrackNet-based ball detection)
• Support code:
• models/model.py – definitions or wrappers for loading detection models.
• tracker_stubs/ – serialized detection results for demo/testing.
• Configuration & data artifacts:
• .pkl files in tracker_stubs for offline demos.
• Potential external config (YOLO weights, TrackNet weights) referenced but not in repo.
README for additional insights
• The three‐block methodology: Court Detection → Player Detection → Ball Detection.
• Uses OpenCV for preprocessing/contours, YOLOv8 for players, TrackNet for balls.
• Outputs 2D court‐aligned positions via homography.
a. Main components
1. Video Input
2. Image Preprocessing
3. Court Detection Module
4. Homography Calculator
5. Player Detection & Tracker
6. Ball Detection & Tracker
7. Data Fusion & Output (overlay, trajectory export)
8. Model Loader (YOLOv8, TrackNet)
9. Utility Layer (bbox_utils, video_utils, conversions)
b. Relationships & interactions
• Video Input → Image Preprocessing → Court Detection → Homography Calculator
• Homography feeds into Player Tracker (to map player bbox → 2D court)
• Image Preprocessing also feeds Player Tracker and Ball Tracker directly for raw frame detections
• Model Loader is invoked by each tracker to load weights
• Utility functions are imported by all modules for I/O and conversions
• Tracker outputs (player positions, ball positions) go to Data Fusion, which generates final visualizations or data exports
c. Architectural patterns & design principles
• Pipeline pattern: clear flow from raw input through detection, transformation, and output
• Modular separation: each detection/tracking task is in its own module
• Single‐responsibility: utils vs. core logic vs. orchestration
• Use of dependency injection: main.py configures models and passes them to trackers
d. Key technologies & libraries
• Python 3.x, OpenCV, NumPy
• YOLOv8 (via ultralytics or custom wrapper)
• TrackNet
• pickle for stubs; standard Python logging