samnoul/Padeliq

PadelIQ analysis worker

Reproducibility contract

Worker 0.8.0 makes the positioning pipeline versioned and deterministic. It:

• —fixes the frame-sampling rate and random seeds;
• —serialises tracking inference to prevent concurrent model-state variation;
• —pins the RT-DETR model revision;
• —calculates the position score on the server;
• —stores full-video, calibration and combined reproducibility hashes;
• —returns the calibration and analysis configuration with every report;
• —rejects crossed, undersized or implausibly ordered court calibration points.

The web app fingerprints uploads using three one-megabyte samples. When the same user uploads identical footage with the active configuration, it reuses the existing calibration and immutable result instead of generating a second score. Trend reporting compares only reports with the same positioning methodology.

An initial commercially friendly video-analysis service for court calibration, selected-player tracking, court positions, movement heatmaps, distance and recovery-position proxies. The tracker supports multiple time-stamped player references, appearance-and-motion identity reacquisition, court-side constraints, short-gap interpolation and a reliability gate. An optional Qwen3-VL layer turns sampled frames and measured metrics into cautious coaching feedback only after the tracking-quality gate passes.

Users may explicitly opt in to 24-hour diagnostic retention. When enabled, the worker keeps the source video and a tracking-overlay copy behind an unguessable temporary token. Expired files are removed automatically; the default remains immediate deletion after analysis. Space storage is ephemeral, so diagnostics are best-effort and may disappear earlier if the worker restarts.

Open-source components

• —OpenCV — Apache 2.0
• —Paddle/RT-DETR model architecture accessed through Transformers — Apache 2.0 code; verify the selected checkpoint card before production
• —ByteTrack through Supervision — MIT
• —PyTorch — BSD-style
• —Transformers — Apache 2.0
• —SmolVLM2-500M-Video-Instruct — Apache 2.0

Keep all dependency licence and notice files in production distributions. Do not substitute Ultralytics models without reviewing their AGPL/commercial terms.

Run locally

docker build -t padeliq-analysis .
docker run --rm -p 8080:8080 \
  -e ALLOWED_ORIGINS=https://your-app.vercel.app \
  -e ENABLE_VIDEO_LLM=true \
  -e OUTCOME_MODEL_ID=HuggingFaceTB/SmolVLM2-500M-Video-Instruct \
  padeliq-analysis

POST /jobs accepts a video file and a JSON calibration form field. Court corners must be ordered top-left, top-right, bottom-right and bottom-left in original video pixel coordinates. player is the selected player's pixel position in the same frame.

The current in-memory job store is suitable for a controlled prototype. Production requires object storage, a persistent queue/database, authentication, file limits and scheduled deletion of raw footage.

The lightweight outcome model is intended for cautious rally-ending estimates. It does not make reliable shot-by-shot calls; those require a labelled padel dataset and a dedicated temporal classifier. Results below the confidence threshold are returned as unknown rather than forced into won/lost.