Autor: Hugo Fernández Gil · 2026
PadelTracker convierte vídeo broadcast de un partido de pádel en métricas tácticas y biomecánicas:
- Tracking de 4 jugadores con estimación de pose (17 keypoints)
- Rastreo de pelota a alta velocidad con modelo fine-tuned en datos de pádel
- Clasificación de golpes (smash, bandeja, víbora, volea) mediante heurísticas geométricas
- Proyección al plano táctico (20 × 10 m) mediante homografía
- Estadísticas y visualizaciones: mapas de calor, distancias recorridas, distribución de golpes
El sistema está diseñado para desarrollo en CPU local y cómputo intensivo en la nube (Google Colab, RunPod).
El aporte técnico central del proyecto es la comparación empírica entre un modelo base COCO y un modelo fine-tuned con datos reales de pádel.
| Modelo | mAP@0.50 | mAP@0.50-0.95 | Precision | Recall |
|---|---|---|---|---|
Baseline COCO (yolov8n.pt, clase 32) |
0.0000 | 0.0000 | 0.0000 | 0.0000 |
Fine-tuned (padel_ball_best.pt) |
0.9103 | 0.6397 | 0.8811 | 0.8625 |
| Modelo | Hit-rate (frames con detección) |
|---|---|
Baseline COCO (yolov8x.pt, 68M params) |
52.81% |
Fine-tuned (padel_ball_best.pt, 3M params) |
75.08% |
El modelo nano fine-tuned (3M parámetros) supera al modelo extra-large genérico (68M parámetros) tanto en mAP como en cobertura por frame.
Se utilizó PadelTracker100, un dataset público de partidos del World Padel Tour:
| Split | Imágenes | Labels no vacías |
|---|---|---|
| Train | 24,780 | 18,365 |
| Val | 3,097 | 2,311 |
| Test | 3,098 | 2,299 |
- Modelo base:
yolov8n.pt(preentrenado COCO) - Hardware: NVIDIA RTX 4090 · 24 GB VRAM (RunPod)
- Épocas: 100 · Batch: 16 · imgsz: 1280
- Optimizador: AdamW · lr₀=0.001 · weight decay=0.0005
- Augmentations: mosaic, mixup, rotación ±10°, flip horizontal, erasing
- Tiempo: ~6.6 h · Coste: < $2 USD
Las curvas de entrenamiento completas (100 épocas) están en runs/padel_ball_v1/results.png.
El paper completo está disponible en docs/paper_PadelTracker.pdf y en formato fuente LaTeX en docs/paper_PadelTracker.tex.
PadelTracker/
├── src/
│ ├── 01_mapear_pista.py # Calibración: homografía 3×3
│ ├── 02_rastrear_jugadores.py # YOLOv8-Pose + ByteTrack
│ ├── 03_rastrear_pelota.py # YOLOv8n fine-tuned (pelota)
│ ├── 04_detectar_impactos.py # Heurísticas de golpes
│ ├── 05_generar_estadisticas.py # Mapas de calor y estadísticas
│ ├── 06_anotar_video.py # Vídeo anotado con overlay
│ ├── 07_preparar_dataset.py # Preparación de PadelTracker100
│ └── 08_comparar_val_baseline_v2.py # Comparación baseline vs fine-tuned
│
├── models/
│ ├── padel_ball_best.pt # ⭐ Modelo fine-tuned (este repo)
│ ├── padel_wpt.onnx # Detector de red/palas/líneas (Roboflow)
│ └── class_names.txt
│
├── runs/
│ ├── padel_ball_v1/ # Resultados del entrenamiento
│ │ ├── results.csv # Métricas por época (100 épocas)
│ │ ├── results.png # Curvas de convergencia
│ │ ├── args.yaml # Hiperparámetros exactos
│ │ ├── BoxPR_curve.png # Curva Precision-Recall (val)
│ │ ├── BoxF1_curve.png # Curva F1 (val)
│ │ └── confusion_matrix_normalized.png
│ └── detect/val/ # Evaluación en test split
│ ├── BoxPR_curve.png
│ ├── BoxF1_curve.png
│ └── confusion_matrix_normalized.png
│
├── notebooks/
│ ├── colab_inferencia.ipynb # Inferencia GPU en Google Colab
│ ├── runpod_entrenamiento.ipynb # Entrenamiento en RunPod
│ └── runpod_comparar_baseline.ipynb # Comparación en RunPod
│
├── docs/
│ ├── paper_PadelTracker.pdf # Paper de investigación
│ ├── paper_PadelTracker.tex # Fuente LaTeX del paper
│ └── EVOLUCION_DEL_PROYECTO.md # Memoria de decisiones
│
├── data/
│ ├── input/ # Vídeos de entrada (no incluidos)
│ └── output/ # Resultados generados (no incluidos)
│
├── tests/ # Tests unitarios
├── .cursorrules # Reglas de vibecoding para el agente IA
├── requirements.txt
└── proyecto.txt # Especificación técnica original
git clone https://github.com/TU_USUARIO/PadelTracker.git
cd PadelTracker
pip install -r requirements.txtEl modelo fine-tuned (models/padel_ball_best.pt) está incluido en el repositorio (~6 MB).
Los modelos base de Ultralytics (yolov8n.pt, yolov8n-pose.pt) se descargan automáticamente la primera vez que se ejecuta el pipeline.
Coloca tu vídeo en data/input/partido.mp4 y ejecuta el pipeline en orden:
# 1. Calibrar la pista (genera matriz_homografia.npy)
python src/01_mapear_pista.py
# 2. Rastrear jugadores y pose (genera datos_jugadores.csv)
python src/02_rastrear_jugadores.py
# 3. Rastrear pelota con el modelo fine-tuned (genera datos_pelota.csv)
python src/03_rastrear_pelota.py
# 4. Detectar impactos y clasificar golpes (genera eventos_golpes.csv)
python src/04_detectar_impactos.py
# 5. Generar estadísticas y mapas de calor
python src/05_generar_estadisticas.py
# 6. (Opcional) Generar vídeo anotado
python src/06_anotar_video.pyPara el paso 3 se recomienda GPU. Usa notebooks/colab_inferencia.ipynb si no dispones de una.
Con acceso a GPU (RunPod, Colab) y el dataset PadelTracker100:
python src/08_comparar_val_baseline_v2.py \
--data /ruta/a/padel_ball_yolo/data.yaml \
--finetuned models/padel_ball_best.pt \
--device 0 \
--split testO usa el notebook notebooks/runpod_comparar_baseline.ipynb para ejecutarlo en RunPod.
El desarrollo siguió una metodología de vibecoding (instrucción a agentes IA mediante lenguaje natural) con restricciones arquitectónicas estrictas definidas en .cursorrules:
- Pipeline modular: cada script hace una sola cosa
- Datos intermedios exclusivamente en CSV (sin JSON, sin RAM acumulada)
- Prohibido generar datos sintéticos
- Separación total CPU (desarrollo) / GPU (inferencia y entrenamiento)
| Componente | Tecnología |
|---|---|
| Detección y pose de jugadores | YOLOv8-Pose (Ultralytics) |
| Seguimiento multipersona | ByteTrack |
| Detección de pelota | YOLOv8n fine-tuned sobre PadelTracker100 |
| Calibración espacial | OpenCV findHomography |
| Clasificación de golpes | Heurísticas geométricas sobre keypoints |
| Entrenamiento | RunPod · RTX 4090 · 24 GB VRAM |
MIT — ver LICENSE si se incluye, o contactar al autor para uso comercial.