What this project is about
The Volleyball Performance Analyzer is a local application for turning fixed-camera footage into reviewable player tracks, possible contacts and exported evidence. Its FastAPI backend and JavaScript interface cover uploading footage, calibration, selecting six near-side players and inspecting results. It is an academic and portfolio application, not a validated sports-science measurement system.
The workflow assumes a centred camera behind the analysed team. The user marks the court corners and selects the six near-side players to follow before processing the clip. These are measurement assumptions, not just setup preferences: cuts, pans, zooms and inaccurate corner selections can invalidate the relationship between image positions and real court coordinates.
How it works
- Calibrate + lock six-player roster
- Run inference + review identities
- Review contacts + export video/CSV
Map positions onto the court
Four corners define a homography: a perspective transformation, computed with OpenCV, from the image to the 9-by-18-metre court plane. The bottom centre of each player box approximates a ground position. Distance and speed calculations reject long gaps and implausibly fast movements rather than counting every jump in the tracked position.
Keep player identities stable
YOLO26 Small detects players, with BoT-SORT or ByteTrack following them across frames. The user assigns six near-side identities and can correct observed frames later. Jersey labels are manual, not optical character recognition. Corrections preserve exclusive P1–P6 assignments and rebuild derived outputs without inventing missing detections.
Review possible contacts
A credited third-party pretrained VballNetV4 model supplies ball observations. Candidate contacts require review before they count towards statistics. The interface shows job progress and cancellation; interrupted work can be retried after restart. Completed outputs are published as one generation, so a failed run leaves the last good results intact. Exports include annotated video, CSV tables, plots and ZIP files.
The important design choices
Calibrate before analysing
Ask the user to select court corners and verify the drawn overlay before running analysis.
The trade-offThe setup adds interaction but makes the image-to-court mapping explicit for varied footage. It does not eliminate errors in the user's selections.
Leave uncertain gaps visible
Keep uncertain gaps in a player's track missing instead of automatically assigning another player.
The trade-offThis avoids unjustified claims of continuous tracking, but produces incomplete movement paths and requires a new roster selection for substitutions.
Isolate processing work
Run one processing worker and publish completed output generations atomically.
The trade-offThroughput is limited, but mutable model state is not shared across active sessions and failures preserve the previous usable output.
Review one player's rally
Use a fixed back-view clip with the full court and six near-side teammates visible.
- Select four corners, confirm the court overlay and select the six-player roster.
- Process the clip and inspect the chosen player's trail alongside missing or rejected segments.
- Export the annotated video and tracking CSV, then review possible contacts before interpreting statistics.
What this showsThe outputs expose geometry and tracking assumptions while keeping approximate estimates separate from manually reviewed events.
Illustrative example, not an additional measured result.
How it was tested—and what it shows
The checks
The repository records exploratory public and professional clip checks and a human-labelled session-validation workflow. These are development checks, not an expert-labelled held-out full-match benchmark. Possible overlap with pretrained-model training clips also limits generalisation claims.
Video-separated dataset exports support future evaluation. They are not themselves evidence of validated tracking, contact timing or physical-height accuracy.
What to take from the results
The result is an integrated processing and review workflow with failure recovery. Ball detection uses a credited third-party pretrained model, not a new model trained from scratch for this project.
Floor calibration cannot by itself recover an airborne trajectory. Conditional gravity-based 3D fits are gated and may abstain; they are not validated physical measurements. There is no active jump-height measurement claim. The server is intended for local loopback use, without public-hosting authentication.
What to keep in mind
- Designed for fixed-camera back-view clips, not arbitrary broadcast footage.
- Jersey entries are manual labels; fully missing detections cannot be restored by identity correction.
- The bundled ball model is third-party pretrained. Exploratory clips are not a clean held-out full-match evaluation.
- Single-camera height and flight estimates are conditional and unvalidated against physical 3D measurements. The local service is not ready for direct public hosting.
Technical notes & source
Built with
Python · FastAPI · JavaScript · OpenCV · YOLO · ONNX Runtime
Terms used in this project
- Homography
- A perspective transformation mapping image positions to the flat court.
- Inference
- Running a trained model on new input.
- Reviewed event
- A contact or statistic explicitly checked by a person before it is counted.