Basket2D — Análisis táctico de baloncesto por visión artificial

Trabajo Fin de Grado. Basket2D analiza vídeos de baloncesto y proyecta lo que ocurre en pista a un mapa 2D de la cancha: detecta jugadores, árbitros y balón, los sigue a lo largo del clip, clasifica equipos, identifica dorsales, estima posesión, reconstruye la trayectoria 3D del tiro y reconoce jugadas (bloqueos). Todo es accesible desde una aplicación web: se sube un clip y se revisa el resultado anotado junto al mapa 2D.

El almacenamiento es por ficheros (sin base de datos): cada trabajo genera un vídeo anotado, el mapa 2D y metadatos JSON por frame.

pipeline/   Etapas de visión (detección → tracking → equipos → dorsal →
            homografía → posesión → tiro 3D → táctica). Orquestadas por
            pipeline/orchestrator.py. CLI en run.py.
backend/    API FastAPI (backend/app/main.py). Sube vídeo, lanza el pipeline
            en subprocess, expone jobs/stats/resultados. Un Lock por GPU.
            Sin Celery ni Redis; almacenamiento por ficheros.
frontend/   Aplicación Vue 3 + Vite. La compila serve.sh y la sirve el backend.
models/     Pesos (no versionados; ver "Modelos").
data/       Vídeos de entrada/salida y datasets (no versionados).
deploy/     Receta Apptainer para un entorno reproducible.

• GPU NVIDIA con CUDA (probado en A100). El tracker por defecto (SAM 3) carga un modelo grande; existe la alternativa ligera --tracker botsort.
• Entorno conda basket2d (Python 3.10). Las dependencias del pipeline están documentadas en requirements.txt.
• Node 20 para el frontend: serve.sh usa un Node portable embebido en frontend/.node/ (el del sistema suele ser demasiado antiguo para Vite 5).

conda activate basket2d

Los pesos no se versionan (varios GB). Se obtienen con:

python scripts/fetch_models.py --copy      # copia física
# o sin --copy para enlazarlos por symlink desde el proyecto original

Modelos usados: RF-DETR (detección, 11 clases), SAM 3 (tracking por máscara), detector de keypoints de cancha, SmolVLM2 afinado (OCR de dorsal), OSNet (ReID para BoT-SORT) y YOLOv8-pose (suelta del tiro).

python run.py data/clip.mp4 -o data/out.mp4                 # análisis básico
python run.py data/clip.mp4 -o data/out.mp4 --metadata      # + metadatos JSON
python run.py data/clip.mp4 -o data/out.mp4 --tracker botsort   # tracker rápido
python run.py data/clip.mp4 -o data/out.mp4 --shot3d --metadata # reconstrucción 3D del tiro
python run.py data/clip.mp4 -o data/out.mp4 --tactics --metadata # reconocer bloqueos
python run.py data/clip.mp4 --no-numbers                    # sin OCR de dorsal

Genera el vídeo anotado, el mapa 2D (*_map.mp4) y, con --metadata, un JSON por frame con posiciones, equipos, dorsales y eventos.

bash serve.sh                 # compila el frontend y arranca FastAPI en :8000

Abre http://localhost:8000, sube un clip o elige uno de ejemplo, y revisa el vídeo anotado, el mapa 2D y las jugadas detectadas.

pytest        # suite de lógica pura (posesión, homografía, tiro 3D, táctica…), sin GPU

deploy/apptainer/ contiene la receta (tfg.def, environment.yml, requirements-lock.txt) para construir una imagen Apptainer con el entorno completo. La imagen construida no se versiona (artefacto pesado).

El reconocimiento de jugadas sigue a Chen et al.; la reconstrucción 3D del tiro, el método de Pirotta; los keypoints de cancha, KaliCalib. Los PDFs están en docs/references/ (no versionados).