# dewolf1/option2_football_player_tracking architecture

> Architecture diagram of the GitHub repository dewolf1/option2_football_player_tracking, 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/dewolf1/option2_football_player_tracking
- Repository: https://github.com/dewolf1/option2_football_player_tracking

## Overview

##### Project Type and Purpose
- This is a standalone computer-vision video-processing pipeline (no traditional “frontend/backend” split).

##### File Structure Highlights
- main.py: orchestrates the entire pipeline
- static/assets/: holds input videos and YOLOv5 model weights (best.pt)
- static/reid_model/: holds pretrained OSNet weights (osnet_x1_0_imagenet.pth)
- requirements.txt: lists dependencies (PyTorch, ultralytics, torchreid, OpenCV, pytesseract, scikit-learn)

##### Main Components
A. Input Source
- Video file reader (OpenCV VideoCapture)
B. Preprocessing Module
C. Detection Module
D. Feature Extraction & Classification
1. ReID feature extractor (OSNet via torchreid)
3. OCR module (pytesseract) for jersey number text
E. ID Assignment Engine
F. Output Writer
- Annotated frames → OpenCV VideoWriter → output_with_consistent_ids.mp4
G. Model Storage
- static/assets/best.pt, static/reid_model/osnet_x1_0_imagenet.pth

##### Relationships & Data Flows
- to ReID extractor
- to HSV classifier
- to OCR module

##### Architectural Patterns & Principles
- Pipeline pattern: clear, linear stages
- Modular separation: detection, feature extraction, classification, tracking logic
- Single responsibility: each block does one core CV task

##### Technology & Libraries Call-outs
- YOLOv5 (ultralytics) for detection
- PyTorch for model inference (CUDA support)
- torchreid for ReID feature extraction
- OpenCV for I/O, preprocessing, annotation, video writing
- pytesseract for OCR
- scikit-learn for spatial heuristics/clustering
- Python 3.8+ runtime

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Pipeline Stages
    VideoReader["Video Reader\n(OpenCV VideoCapture)"]:::processing
    Preprocessor["Preprocessing Module\n(Frame resize, BGR→RGB/HSV)"]:::processing
    Detector["YOLOv5 Detector"]:::inference
    subgraph "Feature Extraction & Classification"
        ReIDExtractor["ReID Feature Extractor\n(OSNet via torchreid)"]:::inference
        HSVClassifier["Team Classification\n(HSV thresholding)"]:::classification
        OCRModule["OCR Module\n(Tesseract)"]:::classification
    end
    IDEngine["ID Assignment Engine\n(spatial heuristics + features)"]:::classification
    Annotator["Annotator\n(overlay boxes, IDs, team, number)"]:::processing
    OutputWriter["Output Writer\n(VideoWriter → output_with_consistent_ids.mp4)"]:::processing

    %% Model Storage
    subgraph "Model Storage"
        ModelStorageYOLO["YOLOv5 Weights\n(best.pt)"]:::storage
        ModelStorageOSNet["OSNet Weights\n(osnet_x1_0_imagenet.pth)"]:::storage
    end

    %% Documentation & Dependencies
    subgraph "Project Docs & Config"
        Dependencies["requirements.txt"]:::docs
        README["README.md"]:::docs
        Report["report.md"]:::docs
    end

    %% Data Flows
    VideoReader -->|"frames"| Preprocessor
    Preprocessor -->|"processed frames"| Detector
    Detector -->|"bboxes"| ReIDExtractor
    Detector -->|"bboxes"| HSVClassifier
    Detector -->|"bboxes"| OCRModule
    ReIDExtractor -->|"feature vectors"| IDEngine
    HSVClassifier -->|"team labels"| IDEngine
    OCRModule -->|"jersey numbers"| IDEngine
    IDEngine -->|"IDs + metadata"| Annotator
    Annotator -->|"annotated frames"| OutputWriter

    %% Weight Storage Links
    Detector --> ModelStorageYOLO
    ReIDExtractor --> ModelStorageOSNet

    %% Click Events
    click VideoReader "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click Preprocessor "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click Detector "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click Detector "https://github.com/dewolf1/option2_football_player_tracking/tree/main/static/assets/"
    click ReIDExtractor "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click ReIDExtractor "https://github.com/dewolf1/option2_football_player_tracking/blob/main/static/reid_model/osnet_x1_0_imagenet.pth"
    click HSVClassifier "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click OCRModule "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click IDEngine "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click Annotator "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click OutputWriter "https://github.com/dewolf1/option2_football_player_tracking/blob/main/main.py"
    click ModelStorageYOLO "https://github.com/dewolf1/option2_football_player_tracking/tree/main/static/assets/"
    click ModelStorageOSNet "https://github.com/dewolf1/option2_football_player_tracking/blob/main/static/reid_model/osnet_x1_0_imagenet.pth"
    click Dependencies "https://github.com/dewolf1/option2_football_player_tracking/blob/main/requirements.txt"
    click README "https://github.com/dewolf1/option2_football_player_tracking/blob/main/README.md"
    click Report "https://github.com/dewolf1/option2_football_player_tracking/blob/main/report.md"

    %% Styles
    classDef processing fill:#9fdfbf,stroke:#2f8531,color:#000
    classDef inference fill:#bfd4fd,stroke:#1f4fa1,color:#000
    classDef classification fill:#ffd9b3,stroke:#a65e00,color:#000
    classDef storage fill:#e0e0e0,stroke:#777,color:#000
    classDef docs fill:#f0c0f0,stroke:#900c90,color:#000
```
