AI-based tool to analyze padel matches from video input. This tool uses computer vision and machine learning models to track players, detect ball positions, automatically identify the padel court, and recognize player actions and shots.
- 🎥 Video Processing: Support for multiple video formats (MP4, MOV, AVI, MKV, etc.)
- 🏃 Player Tracking: Detect and track player movements throughout the match
- 🎾 Ball Tracking: Track ball position and trajectory with high precision
- 🏟️ Field Detection: Automatically identify and map the padel court
- 🦴 Pose Estimation: Detect body keypoints for each player using YOLOv8-Pose
- 🎯 Action Recognition: Classify padel shots (serve, smash, volley, forehand, backhand, bandeja, vibora)
- ⚙️ Configurable: Flexible configuration system for customizing analysis parameters
- 🔄 Batch Processing: Analyze multiple videos in one go
Padel_Analyzer/
├── src/ # Main package directory
│ ├── __init__.py # Package initialization
│ ├── analyzer.py # Main analyzer orchestration
│ ├── video/ # Video processing modules
│ │ ├── __init__.py
│ │ └── video_loader.py # Video loading and preprocessing
│ ├── tracking/ # Tracking modules
│ │ ├── __init__.py
│ │ ├── player_tracker.py # Player detection and tracking
│ │ ├── ball_tracker.py # Ball detection and tracking
│ │ ├── pose_estimator.py # Pose estimation using YOLOv8-Pose
│ │ └── action_recognizer.py # Action/shot classification
│ ├── detection/ # Detection modules
│ │ ├── __init__.py
│ │ └── field_detector.py # Field/court detection
│ └── utils/ # Utility modules
│ ├── __init__.py
│ ├── config.py # Configuration management
│ └── device.py # Device detection (CPU/CUDA/MPS)
├── examples/ # Example usage scripts
│ └── basic_usage.py
├── tests/ # Unit tests
│ ├── __init__.py
│ ├── test_analyzer.py
│ ├── test_config.py
│ ├── test_video_loader.py
│ ├── test_pose_estimator.py
│ └── test_action_recognizer.py
├── config.example.json # Example configuration file
├── requirements.txt # Python dependencies
├── pyproject.toml # Project configuration
├── setup.py # Package setup script
└── README.md # This file
- Clone the repository:
git clone https://github.com/ClaudioPoli/Padel_Analyzer.git
cd Padel_Analyzer- Install dependencies:
pip install -r requirements.txt- Install the package:
pip install -e .For deep learning model support, install optional dependencies:
# For PyTorch-based models
pip install -e ".[pytorch]"
# For TensorFlow-based models
pip install -e ".[tensorflow]"
# For development
pip install -e ".[dev]"from padel_analyzer import PadelAnalyzer
# Initialize analyzer with default configuration
analyzer = PadelAnalyzer()
# Analyze a video
results = analyzer.analyze_video("path/to/match.mp4")
# Access results
print(f"Field detected: {results['field_info']}")
print(f"Players tracked: {len(results['player_tracks'])}")
print(f"Ball positions: {len(results['ball_tracks']['positions'])}")To test the implementation with a synthetic video:
python examples/demo_processing.pyOr with your own video:
python examples/demo_processing.py path/to/your/video.mp4from padel_analyzer import PadelAnalyzer
from padel_analyzer.utils.config import Config
# Create custom configuration
config = Config()
config.model.device = "cuda" # Use GPU
config.tracking.player_detection_confidence = 0.7
config.tracking.ball_detection_confidence = 0.5
# Initialize with custom config
analyzer = PadelAnalyzer(config)
results = analyzer.analyze_video("match.mp4")from padel_analyzer import PadelAnalyzer
analyzer = PadelAnalyzer()
# Process multiple videos
video_paths = ["match1.mp4", "match2.mp4", "match3.mov"]
results = analyzer.analyze_video_batch(video_paths)
for i, result in enumerate(results):
if "error" not in result:
print(f"Video {i+1} analyzed successfully")Configuration can be managed through:
- Python API:
from padel_analyzer.utils.config import Config
config = Config()
config.model.device = "cuda"
config.tracking.player_detection_confidence = 0.8- JSON Configuration File:
config = Config.from_file("my_config.json")See config.example.json for a complete configuration example.
- Video Settings: Format support, FPS, resolution
- Tracking Settings: Detection confidence thresholds, interpolation
- Field Detection: Line detection, corner detection, homography
- Model Settings: Model selection, device (CPU/GPU), batch size
- Pose Settings: Pose model selection, confidence thresholds, frame sampling
- Action Recognition Settings: ML model toggle, action confidence thresholds
✅ Base project structure
✅ Core module architecture
✅ Configuration system
✅ Basic testing framework
✅ Video loading with OpenCV (MP4, MOV, AVI, MKV)
✅ Field detection using Hough Transform
✅ Player tracking with YOLOv8
✅ Ball tracking with YOLO + traditional CV fallback
✅ Cross-platform device detection (CUDA/MPS/CPU)
✅ Pose estimation with YOLOv8-Pose (zero-shot)
✅ Action recognition with rule-based classification
- Fine-tune models for padel-specific detection
- Fine-tune action recognition with ML model (LSTM/Transformer)
- Improve player re-identification
- Enhanced trajectory prediction
- Better team assignment algorithms
- Performance optimization and caching
- Action recognition (serves, volleys, smashes) - Implemented!
- Game statistics extraction
- Point tracking and scoring
- Player heatmaps
- Shot type classification - Implemented!
- Real-time video analysis
- Multi-camera support
- Web interface for visualization
- Integration with LLMs for match commentary
- Advanced analytics dashboard
The project currently uses YOLOv8 as the primary detection framework:
- YOLOv8 (Ultralytics): Fast and accurate person detection with built-in tracking
- Pre-trained on COCO dataset: Works zero-shot without fine-tuning
- Cross-platform: Supports CUDA (Windows/Linux), MPS (Apple Silicon), and CPU
- YOLOv8-Pose: State-of-the-art pose estimation with 17 COCO keypoints
- Zero-shot approach: Pre-trained model works well for padel without fine-tuning
- Keypoints detected: nose, eyes, ears, shoulders, elbows, wrists, hips, knees, ankles
- Use cases: Body angle analysis, swing detection, stance classification
- Current approach: Rule-based classification using geometric analysis of keypoints
- Detected actions: Serve, Smash, Volley, Forehand, Backhand, Lob, Bandeja, Vibora
- Future enhancement: ML-based classification with LSTM/Transformer on pose sequences
- Primary: YOLOv8 sports ball detection (COCO class 32)
- Fallback: Hough Circle Transform for traditional CV-based detection
- Trajectory interpolation: Scipy-based smoothing for missed frames
- Hough Line Transform: For court line detection
- Canny Edge Detection: Preprocessing for line detection
- Homography Estimation: For perspective correction and top-down view
- Future: Semantic segmentation models for more robust court detection
Automatic detection of best available device:
- CUDA: NVIDIA GPUs on Windows/Linux
- MPS: Apple Silicon GPUs on macOS
- CPU: Fallback for systems without GPU
The current implementation uses a zero-shot approach for pose estimation and a rule-based approach for action recognition. Here's the reasoning:
- YOLOv8-Pose is highly accurate: Pre-trained on COCO dataset with diverse human poses
- Padel poses are standard human poses: Serving, hitting, and moving are captured well by general pose models
- No labeled data required: Immediate functionality without annotation effort
- Good generalization: Works across different camera angles, lighting conditions
Fine-tuning is recommended when:
- Higher accuracy is needed for specific padel-related keypoints (e.g., racket position)
- Custom keypoints are required (e.g., racket head, ball contact point)
- Domain-specific challenges arise (e.g., occlusion by glass walls, specific court angles)
Recommended fine-tuning approach:
# For pose estimation fine-tuning:
# 1. Annotate 1000-2000 frames from padel matches with COCO keypoints
# 2. Use CVAT or LabelStudio for annotation
# 3. Fine-tune YOLOv8-pose on the annotated dataset
# 4. Optionally add custom keypoints (racket_head, ball)
- Interpretable: Easy to understand and debug classification logic
- No training data needed: Works immediately with pose keypoints
- Fast iteration: Rules can be adjusted based on feedback
- Baseline for ML: Provides ground truth for training ML models
For production-grade action recognition, consider training an ML model:
# Recommended architecture for action recognition:
# Input: Sequence of 16 frames of 17 COCO keypoints
# Model: Transformer encoder or LSTM
# Output: Action class (serve, smash, volley, forehand, backhand, etc.)
# Dataset requirements:
# - 500-1000 examples per action class
# - Annotate action start/end frames in padel match videos
# - Include variety of player styles and camera angles
# Potential datasets to leverage:
# - Tennis action datasets (similar biomechanics)
# - UCF-Sports, Kinetics (general sports actions)
# - Custom padel dataset (best for padel-specific shots)To enable ML-based action recognition:
from padel_analyzer import PadelAnalyzer
from padel_analyzer.utils.config import Config
config = Config()
config.action_recognition.use_ml_model = True
config.action_recognition.model_path = "path/to/trained_model.pt"
analyzer = PadelAnalyzer(config)Run tests using pytest:
# Run all tests
pytest
# Run with coverage
pytest --cov=src
# Run specific test file
pytest tests/test_analyzer.py
# Run pose estimation tests
pytest tests/test_pose_estimator.py tests/test_action_recognizer.pyContributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
This project is licensed under the MIT License.
- Inspired by sports analytics and computer vision research
- Built on top of OpenCV, PyTorch/TensorFlow ecosystems
- Thanks to the open-source community for various CV tools
For questions or suggestions, please open an issue on GitHub.