# ankitk75/football-player-reid architecture

> Architecture diagram of the GitHub repository ankitk75/football-player-reid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ankitk75/football-player-reid
- Repository: https://github.com/ankitk75/football-player-reid

## Overview

##### Project Type and Purpose
- This is a computer‐vision pipeline for video analytics: it ingests football broadcast footage, runs object detection (players, referees, ball) using a fine-tuned YOLOv8 model, and performs visual re-identification to maintain consistent player IDs across frames.
- Key use cases: real-time frame processing, detection visualization, identity tracking across occlusions, and output generation.

##### File Structure
- Top-level scripts:
- detect.py – runs detection and outputs annotated frames/video
- track_with_global_reid.py – runs re-identification and tracking
- assets/ – input video(s) and model weights (best.pt)
- output/ – stores detected_frames/, detected_video_custom_resize.mp4, tracked_frames/, tracked_video_reid_final_resize.mp4
- requirements.txt – lists dependencies (OpenCV, Ultralytics YOLO, Torch, Torchreid, etc.)

##### README for Additional Insights
- Detection threshold and fallback to CPU if no GPU.
- Pipeline stages: Load model → Detect objects → Extract feature embeddings → Compute cosine similarities → Associate IDs → Render outputs.

##### Main Components
a. Video Input Component
- Source: assets/15sec_input_720p.mp4
- Preprocessor: OpenCV frame extraction
b. Object Detection Component
- YOLOv8 model (best.pt) loaded via Ultralytics
c. Feature Embedding / Re-ID Component
- Torchreid module computes feature vectors per detection
- Cosine similarity metric from scikit-learn
d. Tracking & Association Component
- Global tracker that maintains ID assignments across frames
- Handles occlusion, re-entry
e. Output Rendering & Storage
- Annotated frames → output/detected_frames or tracked_frames
- Compiled videos → output/detected_video_custom_resize.mp4, output/tracked_video_reid_final_resize.mp4

##### Relationships & Data Flow
- Optionally, loop back for next frame processing until end of video

##### Architectural Patterns & Principles
- Pipeline model: Each stage is a separate processing module
- Modularity: detection and re-ID are independent stages for easy replacement or upgrade
- GPU acceleration fallback: conditional execution path

##### Technologies, Frameworks, Libraries
- OpenCV for video I/O and frame handling
- Ultralytics YOLOv8 for detection
- PyTorch & TorchVision for model inference
- Torchreid for feature extraction
- scikit-learn for similarity computation
- Pillow, NumPy for image manipulation

##### Final Touches
- Every component is labeled, no overlaps

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    Input["Video Input\nassets/15sec_input_720p.mp4"]:::input
    requirements["requirements.txt"]:::external
    readme["README.md"]:::external

    %% Processing Pipeline
    preproc["Frame Extraction\n(OpenCV)\nsrc/detect.py"]:::core
    detect["YOLOv8 Detection\n(Ultralytics)\nsrc/detect.py"]:::core
    gpuCheck{"GPU Available?"}
    detectionGPU["Detect on GPU"]:::core
    detectionCPU["Detect on CPU"]:::core
    embedding["Feature Embedding\n(Torchreid + cosine)\nsrc/track_with_global_reid.py"]:::core
    tracking["Tracking & Association\n(src/track_with_global_reid.py)"]:::core

    %% Storage Outputs
    out1["Detected Frames\noutput/detected_frames"]:::storage
    out2["Detected Video\noutput/detected_video_custom_resize.mp4"]:::storage
    out3["Tracked Frames\noutput/tracked_frames"]:::storage
    out4["Tracked Video\noutput/tracked_video_reid_final_resize.mp4"]:::storage

    %% Flow
    Input --> preproc --> detect --> gpuCheck
    gpuCheck -->|Yes| detectionGPU --> embedding
    gpuCheck -->|No| detectionCPU -.-> embedding
    embedding --> tracking
    tracking --> out1
    tracking --> out2
    tracking --> out3
    tracking --> out4

    %% Click Events
    click Input "https://github.com/ankitk75/football-player-reid/blob/main/assets/15sec_input_720p.mp4"
    click preproc "https://github.com/ankitk75/football-player-reid/blob/main/src/detect.py"
    click detect "https://github.com/ankitk75/football-player-reid/blob/main/src/detect.py"
    click embedding "https://github.com/ankitk75/football-player-reid/blob/main/src/track_with_global_reid.py"
    click tracking "https://github.com/ankitk75/football-player-reid/blob/main/src/track_with_global_reid.py"
    click out1 "https://github.com/ankitk75/football-player-reid/tree/main/output/detected_frames"
    click out2 "https://github.com/ankitk75/football-player-reid/blob/main/output/detected_video_custom_resize.mp4"
    click out3 "https://github.com/ankitk75/football-player-reid/tree/main/output/tracked_frames"
    click out4 "https://github.com/ankitk75/football-player-reid/blob/main/output/tracked_video_reid_final_resize.mp4"
    click requirements "https://github.com/ankitk75/football-player-reid/blob/main/requirements.txt"
    click readme "https://github.com/ankitk75/football-player-reid/blob/main/README.md"

    %% Styles
    classDef input fill:#b7e4c7,stroke:#2b9348,color:#1b4332;
    classDef core fill:#ade8f4,stroke:#0096c7,color:#03045e;
    classDef storage fill:#ffd6a5,stroke:#ff7f11,color:#663300;
    classDef external fill:#e5e5e5,stroke:#adb5bd,color:#495057;
```
