# hukenovs/hagrid architecture

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

- Interactive diagram: https://gitdiagram.com/hukenovs/hagrid
- Repository: https://github.com/hukenovs/hagrid

## Overview

##### Project type and purpose
- This is a Python-based machine-learning pipeline for hand-gesture recognition. It bundles:
- A massive image dataset (HaGRIDv2) with downloader and converter scripts
- Model definitions for classification and object detection (PyTorch)
- Training, testing and inference/​demo entrypoints
- Configuration-driven experiments with multi-GPU support

##### File structure
- Top-level scripts:
- download.py – fetches and unpacks the raw dataset
- run.py – unified CLI for train/test based on YAML configs
- demo.py / demo_ff.py – real-time inference demos (detector vs full-frame classifier)
- ddp_run.sh – wrapper for PyTorch DDP multi-GPU runs
- configs/ – YAML config files per backbone (ResNet, ViT, MobileNet, SSD-Lite, etc.)
- dataset/ – Dataset class (dataset.py) exposing PyTorch DataLoader API
- models/
- classifiers/ – full-frame classification architectures
- detectors/ – SSD-based gesture detectors
- model.py – unifying interface
- converters/ – scripts to transform COCO→YOLO formats and back
- custom_utils/ – reusable utilities: distributed training (ddp_utils.py), common training loops (train_utils.py), generic helpers (utils.py)
- constants.py – global constants (e.g., class lists)
- requirements.txt / pyproject.toml – dependency declarations

##### README highlights
- Dataset hosting (1.5 TB HaGRIDv2), JSON annotations (COCO), metadata
- Pretrained model zoo for detectors (YOLOv10x/n, SSDLiteMobileNetV3) and classifiers (ResNet, ViT, ConvNeXt)
- Training/testing commands (single vs multi-GPU) with TensorBoard logging
- Conversion tools to export annotations to YOLO or COCO formats

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Acquisition
    subgraph "Data Acquisition"
        S3["Remote Storage (S3/HTTP)"]:::data
        DL["download.py"]:::compute
        S3 -->|"downloads images"| DL
        DL -->|"saves to local"| LocalData["Local Dataset Folder"]:::data
    end

    %% Data Preparation
    subgraph "Data Preparation"
        LocalData --> Converters["Annotation Conversion"]:::util
        subgraph "Converters"
            CU["convert_utils.py"]:::util
            H2C["hagrid_to_coco.py"]:::util
            H2Y["hagrid_to_yolo.py"]:::util
            CCFG["converter_config.yaml"]:::config
        end
        Converters --> CU
        Converters --> H2C
        Converters --> H2Y
        Converters --> CCFG
        Converters -->|"outputs prepared data"| PrepData["Prepared Dataset"]:::data
    end

    %% Dataset API
    subgraph "Dataset API"
        DDINIT["__init__.py"]:::util
        DS["dataset.py"]:::util
        PrepData --> DS
    end

    %% Model Zoo
    subgraph "Model Zoo"
        MI["model.py"]:::model
        subgraph "Classifiers"
            BC["base_model.py"]:::model
            VIT["vit.py"]:::model
        end
        subgraph "Detectors"
            SSD["ssd_mobilenetv3.py"]:::model
        end
        MI --> BC
        MI --> VIT
        MI --> SSD
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        CONFIG["configs/*.yaml"]:::config
        RUN["run.py"]:::compute
        TU["train_utils.py"]:::util
        DDPW["ddp_run.sh"]:::compute
        DDU["ddp_utils.py"]:::util
        DS -->|"batches data"| RUN
        MI -->|"loads model defs"| RUN
        CONFIG --> RUN
        RUN --> TU
        RUN --> DDU
        DDPW --> DDU
        RUN -->|"outputs checkpoints & logs"| Outputs["Checkpoints & Logs"]:::data
        Outputs -->|"view metrics"| TB["TensorBoard UI"]:::external
    end

    %% Evaluation / Testing
    subgraph "Evaluation"
        RUN_TEST["run.py (test mode)"]:::compute
        Outputs --> RUN_TEST
        RUN_TEST --> Metrics["Evaluation Metrics"]:::data
    end

    %% Inference / Demo
    subgraph "Inference / Demo"
        DEMO_D["demo.py (detector)"]:::compute
        DEMO_FF["demo_ff.py (full-frame)"]:::compute
        Outputs --> DEMO_D
        Outputs --> DEMO_FF
    end

    %% Constants & Dependencies
    subgraph "Globals & Environment"
        CONST["constants.py"]:::util
        REQ["requirements.txt"]:::config
        PYPROJ["pyproject.toml"]:::config
    end

    %% Click events
    click DL "https://github.com/hukenovs/hagrid/blob/master/download.py"
    click Converters "https://github.com/hukenovs/hagrid/tree/master/converters/"
    click CU "https://github.com/hukenovs/hagrid/blob/master/converters/convert_utils.py"
    click H2C "https://github.com/hukenovs/hagrid/blob/master/converters/hagrid_to_coco.py"
    click H2Y "https://github.com/hukenovs/hagrid/blob/master/converters/hagrid_to_yolo.py"
    click CCFG "https://github.com/hukenovs/hagrid/blob/master/converters/converter_config.yaml"
    click DDINIT "https://github.com/hukenovs/hagrid/blob/master/dataset/__init__.py"
    click DS "https://github.com/hukenovs/hagrid/blob/master/dataset/dataset.py"
    click MI "https://github.com/hukenovs/hagrid/blob/master/models/model.py"
    click BC "https://github.com/hukenovs/hagrid/blob/master/models/classifiers/base_model.py"
    click VIT "https://github.com/hukenovs/hagrid/blob/master/models/classifiers/vit.py"
    click SSD "https://github.com/hukenovs/hagrid/blob/master/models/detectors/ssd_mobilenetv3.py"
    click RUN "https://github.com/hukenovs/hagrid/blob/master/run.py"
    click TU "https://github.com/hukenovs/hagrid/blob/master/custom_utils/train_utils.py"
    click DDPW "https://github.com/hukenovs/hagrid/blob/master/ddp_run.sh"
    click DDU "https://github.com/hukenovs/hagrid/blob/master/custom_utils/ddp_utils.py"
    click CONFIG "https://github.com/hukenovs/hagrid/tree/master/configs/"
    click CONST "https://github.com/hukenovs/hagrid/blob/master/constants.py"
    click REQ "https://github.com/hukenovs/hagrid/blob/master/requirements.txt"
    click PYPROJ "https://github.com/hukenovs/hagrid/blob/master/pyproject.toml"

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000;
    classDef compute fill:#CCFFCC,stroke:#000;
    classDef model fill:#FFCC99,stroke:#000;
    classDef util fill:#D8BFD8,stroke:#000;
    classDef config fill:#FFB6C1,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
