# samnguyen2k5/nusc-isc-footballanalysis architecture

> Architecture diagram of the GitHub repository samnguyen2k5/nusc-isc-footballanalysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samnguyen2k5/nusc-isc-footballanalysis
- Repository: https://github.com/samnguyen2k5/nusc-isc-footballanalysis

## Overview

##### Project Type & Purpose
- This repository is a research-oriented computer-vision pipeline for football pitch analysis (segmentation, line/conic detection, homography estimation, keypoint detection, mask clustering).
- The “notebooks/” folder drives interactive development, while “scripts/” contains the core reusable library modules. Pretrained model weights sit in “weights/”.

##### File Structure
- Top-level folders:
- notebooks/ – Jupyter notebooks for each development stage (e.g., “Segmentation Model.ipynb”, “HomographyNet.ipynb”, “Full Pipeline.ipynb”)
- scripts/ – Python packages separated into:
– classes/frame (frame.py)
– classes/pitch (homography_solver.py, keypoint_mapping.py, pitch.py, helper.py)
– datasets (calibration.py, field_masking.py, field_pitch.py)
- weights/ – pretrained models (e.g. yolo-sn-ball-opt.pt)
- Config files: requirements.txt, setup.sh

##### Read README for Context
- Project name: “NUSC-ISC-FootballAnalysis”
- No explicit architecture section, but notebook and script division implies a data-pipeline library plus experiment layer.

##### Main Components & Their Relationships
- Raw video frames & calibration data (<scripts/datasets/calibration.py>)
- Ground-truth masks (<scripts/datasets/field_masking.py>)
- Pretrained weights (weights/…)
B. Core Library (rectangles)
1. Frame Manager (<scripts/classes/frame/frame.py>)
2. Pitch & Homography Solver (<scripts/classes/pitch/homography_solver.py>)
3. Keypoint Mapper & Mask Clustering (<scripts/classes/pitch/keypoint_mapping.py>)
4. Dataset Handlers (<scripts/datasets/*.py>)
- Jupyter notebooks that import the Core Library to run segmentation model training, keypoint network training, homography calibration, and full end-to-end demos
- Visualizations (plots, annotated frames)
- Reports (reports/2510/*.pdf, *.drawio)

Data Flow:
1. Raw frames & calibration → Dataset Handlers → Frame Manager
2. Frames → Segmentation & Keypoint Nets (using weights/)
3. Nets’ outputs → Homography Solver → Aligned pitch coordinate outputs
4. Utilities → compute statistics & produce visualizations
5. Notebooks orchestrate steps 1–4 and export results to reports/

##### Architectural Patterns & Principles
- Modular separation by functionality (classes vs. datasets vs. tools)
- Single Responsibility per module
- Experiment reproducibility via notebooks + versioned requirements.txt + setup.sh

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Store Layer
    subgraph "Data Store" 
        direction TB
        RawFramesCalibration[(Raw Video Frames & Calibration Data)]:::datastore
        GroundTruthMasks[(Ground-Truth Field Masks)]:::datastore
        FieldPitchDataset[(Field & Pitch Dataset)]:::datastore
        PretrainedWeights[(Pretrained Model Weights)]:::datastore
    end

    %% Core Library Layer
    subgraph "Core Library (scripts/)" 
        direction TB
        subgraph "Classes"
            direction TB
            FrameManager["Frame Manager"]:::core
            subgraph "Pitch Modules"
                direction TB
                PitchRepresentation["Pitch Representation & Helper"]:::core
                HomographySolver["Homography Solver"]:::core
                KeypointMapping["Keypoint Mapping & Mask Clustering"]:::core
            end
        end
        subgraph "Dataset Handlers"
            direction TB
            DatasetHandlers["Dataset Handlers"]:::core
        end
        subgraph "Utility Tools"
            direction TB
            DataLoader["Data Loader"]:::core
            Statistics["Statistics"]:::core
            Visualise["Visualise"]:::core
        end
    end

    %% Notebook Layer
    subgraph "Experiment Orchestrator (notebooks/)"
        direction TB
        NB_Segmentation(["250904 - Segmentation Model.ipynb"]):::notebook
        NB_LineConic(["250921 - Line and Conic Detection.ipynb"]):::notebook
        NB_Homography(["251022 - HomographyNet.ipynb"]):::notebook
        NB_Keypoint(["251025 - KeypointNet.ipynb"]):::notebook
        NB_MaskClust1(["251026 - Keypoint Mask Clustering.ipynb"]):::notebook
        NB_MaskClust2(["251028 - Keypoint Mask Clustering.ipynb"]):::notebook
        NB_FullPipeline(["251109 - Full Pipeline.ipynb"]):::notebook
    end

    %% Outputs Layer
    subgraph "Outputs (reports/)"
        direction TB
        Reports["Final Reports & Presentations"]:::output
    end

    %% Data Flows
    RawFramesCalibration -->|"frames, calibration"| DatasetHandlers
    GroundTruthMasks -->|"masks"| DatasetHandlers
    DatasetHandlers -->|"processed frames"| FrameManager
    FrameManager -->|"pitch frames"| PitchRepresentation
    PitchRepresentation -->|"features"| HomographySolver
    HomographySolver -->|"homography data"| KeypointMapping
    KeypointMapping -->|"keypoints, clusters"| NB_FullPipeline
    PretrainedWeights -.->|"model weights"| NB_Segmentation
    PretrainedWeights -.->|"model weights"| NB_Keypoint
    DataLoader -->|"data provision"| NB_Segmentation
    Statistics -->|"metrics"| NB_LineConic
    Visualise -->|"plots, annotations"| NB_FullPipeline
    NB_Segmentation -->|"segmentation outputs"| NB_FullPipeline
    NB_LineConic -->|"line/conic outputs"| NB_FullPipeline
    NB_Homography -->|"homography outputs"| NB_FullPipeline
    NB_Keypoint -->|"keypoint outputs"| NB_FullPipeline
    NB_MaskClust1 -->|"mask clusters"| NB_FullPipeline
    NB_MaskClust2 -->|"mask clusters"| NB_FullPipeline
    NB_FullPipeline -->|"export results"| Reports

    %% Click Events
    click RawFramesCalibration "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/datasets/calibration.py"
    click GroundTruthMasks "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/datasets/field_masking.py"
    click FieldPitchDataset "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/datasets/field_pitch.py"
    click PretrainedWeights "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/tree/main/weights/"
    click FrameManager "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/classes/frame/frame.py"
    click PitchRepresentation "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/classes/pitch/pitch.py"
    click PitchRepresentation "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/classes/pitch/helper.py"
    click HomographySolver "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/classes/pitch/homography_solver.py"
    click KeypointMapping "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/classes/pitch/keypoint_mapping.py"
    click DatasetHandlers "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/tree/main/scripts/datasets/"
    click DataLoader "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/tools/dataloader.py"
    click Statistics "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/tools/statistics.py"
    click Visualise "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/scripts/tools/visualise.py"
    click NB_Segmentation "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/250904 - Segmentation Model.ipynb"
    click NB_LineConic "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/250921 - Line and Conic Detection.ipynb"
    click NB_Homography "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/251022 - HomographyNet.ipynb"
    click NB_Keypoint "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/251025 - KeypointNet.ipynb"
    click NB_MaskClust1 "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/251026 - Keypoint Mask Clustering.ipynb"
    click NB_MaskClust2 "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/251028 - Keypoint Mask Clustering.ipynb"
    click NB_FullPipeline "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/blob/main/notebooks/251109 - Full Pipeline.ipynb"
    click Reports "https://github.com/samnguyen2k5/nusc-isc-footballanalysis/tree/main/reports/2510/"

    %% Styles
    classDef datastore fill:#cce5ff,stroke:#0b5394,stroke-width:1px,shape:cylinder
    classDef core fill:#d4edda,stroke:#155724,stroke-width:1px
    classDef notebook fill:#fff3cd,stroke:#856404,stroke-width:1px,rx:5,ry:5
    classDef output fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
