# ramindu-nimex/netlytics architecture

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

- Interactive diagram: https://gitdiagram.com/ramindu-nimex/netlytics
- Repository: https://github.com/ramindu-nimex/netlytics

## Overview

##### Project type and purpose
- Netlytics is an open-source video-analytics tool that measures tennis player speed, shot speed, and shot count by processing input video frames.
- It uses YOLO (v8/v5) for object detection, PyTorch CNNs for court keypoint extraction, OpenCV for image processing, and Python utilities for tracking and statistics.

##### File structure
- Top level:
– main.py (orchestrator)
– yolo_inference.py (YOLO detection wrapper)
– constants/ (configuration values)
– utils/ (shared helpers: bbox manipulation, video I/O, drawing)
– court_line_detector/ (CNN court‐keypoint extraction)
– mini_court/ (court transform / homography)
– trackers/ (ball_tracker.py, player_tracker.py)
– training/ (Jupyter notebooks for model training)
- External artifacts:
– tracker_stubs/ (sample detection pickles)
– Pretrained model links in README

##### README
- Confirms architecture: video→YOLO detectors→CNN keypoints→tracking→metrics→annotated video.
- Lists dependencies: ultralytics (YOLO), PyTorch, OpenCV, pandas, numpy, supervision.

##### Main components and data flows
a. Components:
1. Video Input Module (utils/video_utils.py)
2. YOLO Detection Module (yolo_inference.py)
- Player Detector (YOLOv8)
- Ball Detector (fine-tuned YOLOv5)
3. Court Keypoint Module (court_line_detector/court_line_detector.py)
4. Court Homography Module (mini_court/mini_court.py)
5. Object Trackers (trackers/player_tracker.py, trackers/ball_tracker.py)
6. Analytics & Drawing Module (utils/player_stats_drawer_utils.py)
7. Video Output Module (utils/video_utils.py)
8. Training Notebooks (training/…) – separate sub-pipeline
b. Relationships & interactions:
– The Video Input feeds frames to the YOLO Detection Module and the Court Keypoint Module in parallel.
– Detections + Keypoints flow into the Court Homography Module to map image to court coordinates.
– Trackers consume detection coordinates (and optionally homography results) to maintain object identities across frames.
– The Analytics Module computes speed and shot metrics from tracks.
c. Architectural patterns:
– Pipeline pattern: clear sequential processing stages
– Modular separation: detection, transformation, tracking, analytics, I/O
– Reuse of utility libraries for image ops and data conversion
d. Key technologies:
– Python 3.8
– ultralytics (YOLOv8), PyTorch (CNNs)
– OpenCV (video I/O, drawing, perspective transforms)
– pandas, numpy (data manipulation)
– supervision (optional utilities)

##### Details to capture
– Notes on configuration (constants folder).
– Training workflow separated off the main pipeline but linked for context.
– The main.py orchestrator at the top, connecting all runtime modules in sequence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    main["main.py Orchestrator"]:::orchestrator
    constants["constants/"]:::utils
    VideoInput["Video Input Module\n(utils/video_utils.py)"]:::ingest
    YOLO["YOLO Detection Module\n(yolo_inference.py)"]:::ml
    CourtKP["Court Keypoint Module\n(court_line_detector/court_line_detector.py)"]:::ml
    Homography["Court Homography Module\n(mini_court/mini_court.py)"]:::trans
    PlayerTracker["Player Tracker\n(trackers/player_tracker.py)"]:::track
    BallTracker["Ball Tracker\n(trackers/ball_tracker.py)"]:::track
    Analytics["Analytics & Drawing Module\n(utils/player_stats_drawer_utils.py)"]:::anal
    VideoOutput["Video Output Module\n(utils/video_utils.py)"]:::ingest
    Pretrained["Pretrained Models"]:::storage
    Training["Training Notebooks\n(training/tennis_ball_detector_training.ipynb)"]:::storage

    main --> constants
    main --> VideoInput
    VideoInput --> YOLO
    VideoInput --> CourtKP
    YOLO --> Homography
    CourtKP --> Homography
    Homography --> PlayerTracker
    YOLO -.-> PlayerTracker
    Homography --> BallTracker
    YOLO -.-> BallTracker
    PlayerTracker --> Analytics
    BallTracker --> Analytics
    Analytics --> VideoOutput

    Pretrained -.-> YOLO
    Pretrained -.-> CourtKP
    Training --> Pretrained

    click VideoInput "https://github.com/ramindu-nimex/netlytics/blob/main/utils/video_utils.py"
    click YOLO "https://github.com/ramindu-nimex/netlytics/blob/main/yolo_inference.py"
    click CourtKP "https://github.com/ramindu-nimex/netlytics/blob/main/court_line_detector/court_line_detector.py"
    click Homography "https://github.com/ramindu-nimex/netlytics/blob/main/mini_court/mini_court.py"
    click PlayerTracker "https://github.com/ramindu-nimex/netlytics/blob/main/trackers/player_tracker.py"
    click BallTracker "https://github.com/ramindu-nimex/netlytics/blob/main/trackers/ball_tracker.py"
    click Analytics "https://github.com/ramindu-nimex/netlytics/blob/main/utils/player_stats_drawer_utils.py"
    click VideoOutput "https://github.com/ramindu-nimex/netlytics/blob/main/utils/video_utils.py"
    click constants "https://github.com/ramindu-nimex/netlytics/tree/main/constants/"
    click Training "https://github.com/ramindu-nimex/netlytics/blob/main/training/tennis_ball_detector_training.ipynb"

    classDef ingest fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef ml fill:#90EE90,stroke:#000,stroke-width:1px
    classDef trans fill:#FFA500,stroke:#000,stroke-width:1px
    classDef track fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef anal fill:#FFFF66,stroke:#000,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef orchestrator fill:#FFFFFF,stroke:#000,stroke-width:2px
```
