How erwinea/player-analysis works
1. Repository shape
- This is a two-tier application: a Next.js + TypeScript frontend at the repo root and a Python FastAPI backend under backend/.
- The system is centered on a single workflow: upload a match video, choose a sport and target-player hints, run analysis, and return movement plus sport-specific stats.
2. Frontend subsystem
- src/app provides the app shell and dashboard page.
- The main UI is composed from panels in src/components: video upload, sport toggle, calibration modal, analysis panel, heatmap panel, player metrics, and sidebar/navigation.
- Frontend state and payload shaping live in src/lib, especially api.ts, analyzeConfig.ts, courtConfig.ts, pitchCalibration.ts, and the type definitions under src/types.
3. Frontend-to-backend boundary
- The browser submits a multipart analysis request: a video file plus a details JSON payload and optional calibration name.
- The frontend also uses backend health/status checks before analysis and calibration workflows before submission.
- This boundary is important: the frontend does not run inference locally; it only collects inputs, triggers requests, and renders the returned results.
4. Backend entrypoints and API layer
- backend/app/main.py is the application entrypoint, with pitch_api.py as the HTTP-facing API layer.
- schemas.py defines request/response contracts, while upload_utils.py and video_store.py handle upload validation, temporary storage, and video lifecycle management.
- cli.py provides a non-HTTP entry path for backend operations and local execution.
5. Core analysis pipeline
- backend/app/pipeline/run.py orchestrates the end-to-end analysis.
- The pipeline combines detection, tracking, target locking, coordinate calibration, metric generation, and optional sport-specific event inference.
- run.py is the main composition point; most other pipeline modules are reusable stages or helpers.
6. Shared vision/tracking primitives
- Common subsystems include person detection and tracking (detector.py, tracker.py, matcher.py, bbox.py), appearance matching (reid.py, reid_extractor.py), jersey recognition (jersey_number.py, ocr.py, easyocr_shared.py), and color-based disambiguation (color.py).
- segmentation.py, sam_weights.py, mask_rle.py, and frame_overlay.py support optional player masks and visualizations.
- pitch_homography.py, heatmap.py, and movement_stats.py convert frame-space tracking into real-world movement and location metrics.
7. Sport-specific branching
- The pipeline branches on details.sport via backend/app/pipeline/sports/config.py and sport helpers.
- Football uses jersey-number locking, optional ReID, and ball-event inference.
- Badminton uses court-side selection plus shirt color to identify the tracked player and avoids football-only logic such as jersey OCR.
8. Football-specific subsystem
- Football logic is concentrated in modules like jersey_number.py, jersey_weights.py, reid.py, ball_events/, and insights.py.
- ball_events models ball detection and event classification, including possession/timeline logic and event resolution.
- scene_cut.py, lock_audit.py, and target_memory.py support robustness when the tracked player is briefly occluded or the scene changes.
9. Badminton-specific subsystem
- Badminton logic lives under backend/app/pipeline/badminton/ and badminton_stats.py.
- Key pieces are shuttle detection, shuttle filtering, and rally tracking, which feed rally counts, durations, and serve/return-style stats.
- sports/badminton_utils.py and sports/config.py encode court-specific defaults and sport gating.
10. Calibration and coordinate system
- Calibration is a first-class dependency for metre-based movement and heatmaps.
- The backend stores and reuses calibration artifacts by name; pitch_homography.py resolves image-to-court/pitch mapping, and the frontend has dedicated calibration preview and save flows.
- Calibration dimensions differ by sport, so the same uploaded video can produce different coordinate mappings depending on whether the analysis is football or badminton.
11. Model assets and runtime configuration
- Large model files are kept in backend/weights/ and are intentionally gitignored.
- weight_paths.py and environment variables control model locations for jersey classification, ReID, ball detection, shuttle detection, and MobileSAM.
- inference_device.py selects the runtime device, which matters for performance and local deployment behavior.
12. Outputs and response shape
- The backend returns a structured analysis result containing target-player trajectory data, movement stats, heatmap data, warnings, and sport-specific metrics.
- The frontend renders those results in the dashboard panels and can also show annotated video or overlay-style outputs where available.
- insights.py and the frontend src/lib/insightsPayload.ts/parseInsightSummary.ts bridge raw pipeline outputs to user-facing summaries.
13. Tooling, scripts, and QA boundary
- backend/tests/ is extensive and exercises both low-level utilities and full pipeline behavior, including calibration, masks, detection, and sport gating.
- Frontend quality is covered by Playwright tests under tests/, plus GitHub Actions workflows for CI and browser checks.
- backend/scripts/ and backend/tools/ are operational helpers for installing weights, rendering overlays, and debugging model behavior rather than part of the runtime path.
14. External dependencies that materially shape the architecture
- The analysis stack relies on computer-vision models: YOLO-style detectors, MobileSAM segmentation, EasyOCR, and a ReID model checkpoint.
- Because these models are optional and heavyweight, the architecture is designed to degrade gracefully when weights are missing: analysis still runs, but some metrics or masks may be unavailable.
Main entry points: run.py Pipeline run · pitch_api.py HTTP API · Dashboard.tsx Dashboard · UploadAnalyzePanel.tsx Upload flow
Components 18
Frontend
Next.js app that collects inputs, calls the backend, and renders analysis results.
- App shell · Root app shell and page composition for the dashboard experience.
src/app - Dashboard · Main page layout that ties together upload, analysis, and result panels.
src/components/Dashboard.tsx - Upload flow · Combines video upload, sport selection, and analysis submission controls.
src/components/UploadAnalyzePanel.tsx - Calibration · Frontend calibration preview and save flow before analysis submission.
src/components/PitchCalibrationModal.tsx - Results panels · Analysis, heatmap, metrics, and sidebar panels that render backend results.
src/components/GameplayAnalysisPanel.tsx - API client · Browser request layer for health checks, uploads, and analysis submission.
src/lib/api.ts - Request config · Analysis payload shaping, court/sport config, and calibration helpers.
src/lib/analyzeConfig.ts - Types · Shared frontend types for analysis, sport selection, and metrics.
src/types/analysis.ts
Backend
FastAPI service plus the analysis pipeline and sport-specific branches.
- App entry · Backend application entrypoint and service bootstrap.
backend/app/main.py - HTTP API · HTTP-facing endpoints for upload, calibration, and analysis workflows.
backend/app/pitch_api.py - Schemas · Request and response schemas used by the API and pipeline boundary.
backend/app/schemas.py - Upload store · Upload validation and temporary video lifecycle management.
backend/app/upload_utils.py - Pipeline run · End-to-end analysis composition point for detection, tracking, calibration, and metrics.
backend/app/pipeline/run.py - Vision core · Shared detection, tracking, matching, and appearance primitives.
backend/app/pipeline/detector.py - Coordinates · Homography, movement stats, heatmaps, and insight generation.
backend/app/pipeline/pitch_homography.py - Football branch · Football-specific jersey locking, ball events, and scene robustness logic.
backend/app/pipeline/ball_events/run_events.py - Badminton branch · Badminton-specific shuttle and rally analysis plus court defaults.
backend/app/pipeline/badminton/rally_tracker.py
Assets & Ops
Weights, scripts, and workflows that support local execution and CI.
- Weights & runtime · Model weight locations and inference device selection for local/runtime behavior.
backend/app/pipeline/weight_paths.py
Connections 21
- App shell → Dashboard: renders · The app shell mounts the dashboard page and shared layout.
- Dashboard → Upload flow: includes · Dashboard composes the upload and analysis controls.
- Dashboard → Calibration: opens · Dashboard exposes the calibration flow before submission.
- Dashboard → Results panels: renders · Dashboard displays analysis outputs in dedicated panels.
- Upload flow → API client: submits · Browser sends multipart analysis requests and health checks through the API client.
- Upload flow → Request config: builds · Upload controls shape details JSON and analysis options.
- Upload flow → Types: uses · UI state and payloads are typed against shared analysis models.
- Calibration → Request config: writes · Calibration UI updates the named calibration payload and preview state.
- API client → HTTP API: calls · Frontend requests the backend HTTP analysis and calibration endpoints.
- App entry → HTTP API: serves · Application startup wires the HTTP API layer.
- HTTP API → Schemas: validates · Endpoint inputs and outputs are defined by shared schemas.
- HTTP API → Upload store: stores · Uploads are validated and staged before analysis.
- HTTP API → Pipeline run: invokes · HTTP requests trigger the core analysis pipeline.
- Pipeline run → Vision core: uses · Pipeline orchestrates detection, tracking, and target identification.
- Pipeline run → Coordinates: derives · Pipeline converts tracks into calibration-aware movement and heatmap outputs.
- Pipeline run → Football branch: branches · Football analyses enable jersey locking and ball-event inference.
- Pipeline run → Badminton branch: branches · Badminton analyses enable shuttle and rally tracking.
- Pipeline run → Weights & runtime: depends on · Pipeline behavior depends on configured model paths and device selection.
- Coordinates → Results panels: feeds · Backend metrics are rendered in the frontend result panels.
- Football branch → Results panels: feeds · Sport-specific football outputs surface in the UI.
- Badminton branch → Results panels: feeds · Sport-specific badminton outputs surface in the UI.