How hoangviet252006/tennis-analysis works
Main Components
• Input / Data Acquisition:
• The project accepts an input video (located in the input_videos directory) and outputs processed videos (in the output_video directory).
• Preprocessing and Core Processing Flow:
• main.py acts as the entry point, orchestrating the processing workflow.
• Detection and Tracking:
• Player and ball detection are performed using pretrained models (instructions mention YOLOv8x and YOLOv5, although training scripts and model files are external).
• The trackers (found under the trackers directory) contain ball_tracker.py and player_tracker.py to maintain tracking across frames.
• Tracker stubs (in tracker_stubs) are likely used either as sample data or for testing purposes.
• Analysis & Visualization:
• The analysis directory (with ball_analysis.py) processes data such as player statistics (player.csv) and bounce events (e.g. bounce directory with bounce.py and related CSVs).
• The mini_court module generates a minimap visualization of court events.
• Court Boundary Detection:
• The court_line_detector module detects court lines which might be essential for understanding positions relative to the court layout.
• Constants and Utility Modules:
• The constants module provides configuration values and parameters.
Interactions and Data Flow
• The video input is first read into main.py.
• Frames are processed and detection modules (in trackers and court_line_detector) are applied to detect players, ball, and court lines.
• These detections are passed to tracking modules which maintain consistent IDs and generate positional data over time.
• Analysis modules then compute speeds, distances, and ball bounces.
• The mini_court module uses outputs from the tracking and analysis modules to create a minimap visualization.
• Finally, the processed frames and visual overlays are written to the output video.
Architectural Patterns
• Modularity: The code is organized into several modules (detection, tracking, analysis, visualization, audio) so that each responsibility is cleanly separated.
• Pipeline Pattern: The design follows a sequential pipeline where video data flows through multiple processing stages (detection → tracking → analysis → visualization).
• Extensibility: Training scripts in the training directory allow for re-training models, thus indicating that detection components are pluggable and can be updated independently of the main pipeline.
Specify Key Technologies and Libraries
• Python is the primary language.
• Utilizes deep learning models (YOLO-based models - as mentioned in the README – for detection tasks).
• Likely uses OpenCV or similar libraries for video processing within utils/video_utils.py.
• Data handling: CSV files for storing analysis outputs (e.g., player.csv, df_bounce.csv).
• Other libraries may include NumPy, possibly Matplotlib or similar for visualization – check requirements.txt for further details.
• Within this, create three layers:
• Data Ingestion: "Input Video", "Video Utils", and "main.py".
• Processing Chain: Show branches from "main.py" connecting to (a) Detection Modules (players/ball via trackers, YOLO model integration info), (b) Court Detection Module ("court_line_detector"), (c) Analysis Modules (ball_analysis.py in analysis, bounce processing from bounce/).
• Visualization & Output: "Mini Court Visualization (mini_court)" and "Output Video".
• Additionally, include a side module for "Training" where you show:
• "Training Data (Tennis datasets)" → "Training Scripts (training/tennis_court_keypoints_training.py, potentially train.py for player detection)" → updates feeding back into the Detection Modules.
• To include constants and utilities supporting every stage.