# yakhyo/gaze-estimation architecture

> Architecture diagram of the GitHub repository yakhyo/gaze-estimation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yakhyo/gaze-estimation
- Repository: https://github.com/yakhyo/gaze-estimation

## Overview

##### Main Components
- Data Management and Pre-processing:
- The “data” directory (which will hold datasets like Gaze360 and MPIIFaceGaze as shown in the README’s folder structure) and the “utils/datasets.py” file indicate that data ingestion and pre-processing are core components.
- Model Definitions:
- The “models” directory contains dedicated files (resnet.py, mobilenet.py, mobileone.py) implementing different neural network backbones.
- Training Module:
- “main.py” (and additionally “mpii_train.py”) serve as the entry point for training the gaze estimation models. They make use of configuration (config.py) and utility functions (“utils/helpers.py”) to manage training workflows.
- Evaluation Module:
- “evaluate.py” handles the testing/assessment of the trained models via command-line arguments.
- Inference Module:
- “inference.py” is used for live or video-based inference. It supports viewing the results and saving output video.
- ONNX Integration:
- “onnx_export.py” provides functionality to convert PyTorch models into the ONNX format.
- “onnx_inference.py” shows how to run inference using an ONNX model.
- Configuration and Utilities:
- “config.py” provides centralized configuration details.
- “utils” folder (with helpers and datasets) includes reusable code shared across other modules.
- Assets and Weights:
- The “assets” directory holds demonstration videos and images, while the “weights” directory is used to store pre-trained model weights.

##### Components’ Relationships and Interactions
- Data Flow:
- Data is loaded from the “data” directory using routines in “utils/datasets.py”. Pre-processing transforms are applied and then fed into the training routines (main.py, mpii_train.py).
- Model Pipeline:
- The training module uses model definitions from the “models” folder. Configurations (potentially from “config.py”) govern parameters such as network type, learning rate, and epoch count.
- Once trained, models are saved as weight files in the “weights” folder.
- Evaluation and Inference:
- The evaluation script (“evaluate.py”) takes the saved model weights to measure performance.
- The inference script (“inference.py”) loads a model (or even uses ONNX exported models via “onnx_inference.py”) to process incoming video or camera inputs and display/store the output.
- ONNX Component:
- “onnx_export.py” converts models to a format that is optimized for runtime (lightweight, mobile-friendly inference).
- This creates an alternative pipeline for deployment where users call “onnx_inference.py” for high-performance inference.

##### Architectural Patterns & Design Principles
- Modularity:
- The separation between modules (data, models, training, evaluation, inference) means that each component has a clear responsibility.
- Pipeline Processing:
- The flow from data pre-processing to training, evaluating, and finally deploying on inference or ONNX-based inference pipelines is linear and well-defined.
- Extensibility:
- With clearly separated model implementations and training/inference workflows, adding new network architectures or supporting new datasets is straightforward.

##### Specific Elements
- “Data & Pre-processing (data/ & utils/datasets.py)”
- “Model Architectures (models/ - ResNet, MobileNet, MobileOne)”
- “Training Engine (main.py, mpii_train.py)”
- “Evaluation (evaluate.py)”
- “Inference (inference.py)”
- “ONNX Export/Infernce (onnx_export.py, onnx_inference.py)”
- “Configuration (config.py) & Utilities (utils/helpers.py)”
- Training flow and backpropagation loops
- Data input to training and data output to evaluation/inference
- Conversion from standard model weights to ONNX models, then to inference

##### Final Recommendations
- Don’t shy away from breaking down the system into as many distinct components as possible – the clarity is paramount.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Data & Pre-processing
    subgraph "Data & Pre-processing"
        DATA_DIR["data/"]:::dataStyle
        DATASETS["utils/datasets.py"]:::dataStyle
    end

    %% Model Definitions
    subgraph "Model Definitions"
        MODELS_DIR["models/"]:::modelStyle
        RESNET["models/resnet.py"]:::modelStyle
        MOBILENET["models/mobilenet.py"]:::modelStyle
        MOBILEONE["models/mobileone.py"]:::modelStyle
    end

    %% Training Module
    subgraph "Training Module"
        MAIN_TRAIN["main.py"]:::trainStyle
        MPII_TRAIN["mpii_train.py"]:::trainStyle
    end

    %% Evaluation Module
    subgraph "Evaluation Module"
        EVAL["evaluate.py"]:::evalStyle
    end

    %% Inference Module
    subgraph "Inference Module"
        INFER["inference.py"]:::inferStyle
    end

    %% ONNX Integration
    subgraph "ONNX Integration"
        ONNX_EXPORT["onnx_export.py"]:::onnxStyle
        ONNX_INFER["onnx_inference.py"]:::onnxStyle
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        CONFIG["config.py"]:::configStyle
        HELPERS["utils/helpers.py"]:::utilStyle
    end

    %% Assets & Weights
    subgraph "Assets & Weights"
        ASSETS["assets/"]:::assetsStyle
        WEIGHTS["weights/"]:::weightsStyle
    end

    %% External Dependencies
    EXT_LIB["External Libraries (PyTorch,ONNXRuntime,uniface)"]:::extStyle

    %% Connections
    %% Data flows to Training Module
    DATASETS -->|"dataFlow"| MAIN_TRAIN
    DATA_DIR  -->|"dataFlow"| MAIN_TRAIN
    DATASETS -->|"dataFlow"| MPII_TRAIN
    DATA_DIR  -->|"dataFlow"| MPII_TRAIN

    %% Training module depends on Model Definitions and Configuration & Utilities
    MAIN_TRAIN -->|"uses"| MODELS_DIR
    MAIN_TRAIN -->|"uses"| RESNET
    MAIN_TRAIN -->|"uses"| MOBILENET
    MAIN_TRAIN -->|"uses"| MOBILEONE
    MAIN_TRAIN -->|"config"| CONFIG
    MAIN_TRAIN -->|"helpers"| HELPERS
    MPII_TRAIN -->|"config"| CONFIG
    MPII_TRAIN -->|"helpers"| HELPERS

    %% Training outputs saved model weights
    MAIN_TRAIN -->|"saveWeights"| WEIGHTS
    MPII_TRAIN -->|"saveWeights"| WEIGHTS

    %% Evaluation gets weights to evaluate model performance
    WEIGHTS -->|"eval"| EVAL

    %% Inference loads model weights
    WEIGHTS -->|"loadWeights"| INFER

    %% ONNX pipeline from Training
    MAIN_TRAIN -->|"exportONNX"| ONNX_EXPORT
    ONNX_EXPORT -->|"createONNXModel"| ONNX_INFER
    ONNX_INFER -->|"onnxInfer"| INFER

    %% External Dependencies used by multiple modules
    EXT_LIB --- MAIN_TRAIN
    EXT_LIB --- EVAL
    EXT_LIB --- INFER
    EXT_LIB --- ONNX_INFER

    %% Click Events
    click DATA_DIR "https://github.com/yakhyo/gaze-estimation/tree/main/data/"
    click DATASETS "https://github.com/yakhyo/gaze-estimation/blob/main/utils/datasets.py"

    click MODELS_DIR "https://github.com/yakhyo/gaze-estimation/tree/main/models/"
    click RESNET "https://github.com/yakhyo/gaze-estimation/blob/main/models/resnet.py"
    click MOBILENET "https://github.com/yakhyo/gaze-estimation/blob/main/models/mobilenet.py"
    click MOBILEONE "https://github.com/yakhyo/gaze-estimation/blob/main/models/mobileone.py"

    click MAIN_TRAIN "https://github.com/yakhyo/gaze-estimation/blob/main/main.py"
    click MPII_TRAIN "https://github.com/yakhyo/gaze-estimation/blob/main/mpii_train.py"

    click EVAL "https://github.com/yakhyo/gaze-estimation/blob/main/evaluate.py"

    click INFER "https://github.com/yakhyo/gaze-estimation/blob/main/inference.py"

    click ONNX_EXPORT "https://github.com/yakhyo/gaze-estimation/blob/main/onnx_export.py"
    click ONNX_INFER "https://github.com/yakhyo/gaze-estimation/blob/main/onnx_inference.py"

    click CONFIG "https://github.com/yakhyo/gaze-estimation/blob/main/config.py"
    click HELPERS "https://github.com/yakhyo/gaze-estimation/blob/main/utils/helpers.py"

    click ASSETS "https://github.com/yakhyo/gaze-estimation/tree/main/assets/"
    click WEIGHTS "https://github.com/yakhyo/gaze-estimation/tree/main/weights/"

    %% Styles
    classDef dataStyle fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef modelStyle fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef trainStyle fill:#FFCCBC,stroke:#BF360C,stroke-width:2px;
    classDef evalStyle fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef inferStyle fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef onnxStyle fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px;
    classDef configStyle fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
    classDef utilStyle fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
    classDef assetsStyle fill:#CFD8DC,stroke:#263238,stroke-width:2px;
    classDef weightsStyle fill:#CFD8DC,stroke:#263238,stroke-width:2px;
    classDef extStyle fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
```
