How abdullahtarek/tennis_analysis works
Project Type and Purpose
• This is a standalone Python-based computer-vision pipeline (not a web app) that processes tennis match videos. It performs video input → court keypoint detection → player and ball detection → tracking → statistical analysis → annotated video output.
• Key use cases: measure player speed, ball speed, shot count; produce annotated videos.
Top‐Level Components
• Video Input/Output (input_videos/, output_videos/)
• Model Inference
• YOLO v8/v5 for player and ball detection (yolo_inference.py)
• CNN for court keypoints (court_line_detector/)
• Tracking
• ball_tracker.py
• player_tracker.py
• Analysis
• ball_analysis.ipynb & analysis/ball_analysis.ipynb
• mini_court.py (court coordinate transform)
• Utilities
• utils/video_utils.py, bbox_utils.py, conversions.py, player_stats_drawer_utils.py
• constants/ (configuration)
• Orchestration
• Training (not part of runtime flow but crucial for model updates)
• training/*.ipynb and training dataset directories.
Relationships and Data Flow
1. Video Input component reads raw .mp4.
2. Court Keypoint Detector computes homography and court layout.
4. Tracker stubs or real trackers consume detections to maintain IDs and trajectories.
5. Analysis module computes speeds and shot counts using trajectories and court geometry.
6. Drawer utilities annotate frames.
7. Video Output writes an .avi annotated file and optionally CSV or JSON stats.
8. Configuration (constants/) and utils are shared across all components.
Important Patterns and Principles
• Modular pipeline: each stage is a separate module.
• Single-process orchestration (main.py) that sequentially invokes stages.
• Separation of concerns: detection vs. tracking vs. analysis vs. drawing.
• File‐system based data flow: intermediate results aren’t persisted to a DB, but passed in memory.
Technologies, Frameworks, Libraries
• ultralytics YOLO v8/v5 for detection
• OpenCV for video I/O, drawing, homography
• PyTorch for court keypoint CNN
• pandas, numpy for analysis
• Jupyter notebooks for training and exploratory analysis