# xpixelgroup/hat architecture

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

- Interactive diagram: https://gitdiagram.com/xpixelgroup/hat
- Repository: https://github.com/xpixelgroup/hat

## Overview

##### Project Type and Purpose
- This is an open-source research codebase for image super-resolution using Transformers.
- It exposes CLI entry points for training, testing, and inference, driven by YAML config files.
- Core functionality: data loading, model architecture definition, training/evaluation loops, experiment management.

##### High‐Level Components (to represent as major blocks)
a. CLI & Configuration Layer
- Scripts: `hat/train.py`, `hat/test.py`, top‐level `predict.py`
- Config files under `options/train` and `options/test` (YAML)
b. Data Layer
- Dataset classes in `hat/data` (e.g., `imagenet_paired_dataset.py`, `realesrgan_dataset.py`)
- Raw data under `datasets/…`
c. Model Layer
- Architectures in `hat/archs` (e.g., `hat_arch.py`, `discriminator_arch.py`, `srvgg_arch.py`)
- Model wrappers in `hat/models` (e.g., `hat_model.py`, `realhatgan_model.py`, `realhatmse_model.py`)
d. Training & Evaluation Engine
- Training loop in `hat/train.py` invoking PyTorch distributed launch
- Testing/inference loop in `hat/test.py`
- Experiment directory structure in `experiments/pretrained_models` and `results/`
e. External & Auxiliary Services
- PyTorch >=1.7 & BasicSR dependency
- Remote storage for pretrained weights (Google Drive, Baidu)
- Visualization artifacts in `figures/`
- Reproducibility badge via Replicate, PapersWithCode

##### Relationships & Data Flow
- User invokes CLI script → Configuration Loader reads YAML → Data Loader instantiates PyTorch Dataset → Data Batches flow into Model Builder → Forward pass through Transformer‐based architecture → Loss & optimizer updates (Training Engine)
- For testing: Model Loader loads pretrained weights → Data Loader provides LR/HQ image pairs or LR only → Model inference → Metrics & output images saved to `results/`
- Experiment Manager handles logging (console, TensorBoard), checkpointing to `experiments/`, and final model export.

##### Architectural Patterns & Design Principles
- Modularity: clear separation of concerns among data, model, and engine modules.
- Configuration-driven: no hard-coded hyperparameters; all in YAML.
- Plugin-style extensibility: new architectures or datasets can be dropped into `hat/archs` or `hat/data` and selected in config.
- Distributed training leveraging PyTorch’s `torch.distributed.launch`.

##### Putting It All Together
- Data flows (e.g., LR image → SR output, checkpoint → resume training).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI & Configuration Layer"
        TrainScript["train.py"]:::config
        TestScript["test.py"]:::config
        PredictScript["predict.py"]:::config
        TrainConfigs["options/train/ (YAML)"]:::config
        TestConfigs["options/test/ (YAML)"]:::config
    end

    subgraph "Data Layer"
        ImgDataset["imagenet_paired_dataset.py"]:::data
        RealESRGANDataset["realesrgan_dataset.py"]:::data
        MetaInfo["meta_info_DF2Ksub_GT.txt"]:::data
        RawData["datasets/"]:::data
    end

    subgraph "Model Layer"
        HATArch["hat_arch.py"]:::model
        SRVGGArch["srvgg_arch.py"]:::model
        DiscArch["discriminator_arch.py"]:::model
        HATModel["hat_model.py"]:::model
        GANModel["realhatgan_model.py"]:::model
        MSEModel["realhatmse_model.py"]:::model
    end

    subgraph "Compute Engine"
        Trainer["Training Engine"]:::compute
        Tester["Testing/Inference Engine"]:::compute
    end

    subgraph "Experiments & Results"
        Pretrained["experiments/pretrained_models/"]:::storage
        Checkpoints["experiments/ (checkpoints & logs)"]:::storage
        ResultsDir["results/"]:::storage
        Figures["figures/"]:::storage
    end

    subgraph "External & Auxiliary Services"
        PyTorch["PyTorch ≥1.7"]:::external
        BasicSR["BasicSR"]:::external
        RemoteStorage["Google Drive / Baidu"]:::external
        ReproBadge["Replicate / PapersWithCode"]:::external
        RequirementsTXT["requirements.txt"]:::external
        SetupPy["setup.py"]:::external
        SetupCFG["setup.cfg"]:::external
        Version["VERSION"]:::external
    end

    %% Relationships
    TrainScript -->|uses| TrainConfigs
    TestScript -->|uses| TestConfigs
    TrainScript -->|loads| ImgDataset
    TrainScript -->|loads| RealESRGANDataset
    TestScript -->|loads| ImgDataset
    TestScript -->|loads| RealESRGANDataset
    PredictScript -->|invokes| Tester

    TrainConfigs -->|configures| Trainer
    TestConfigs -->|configures| Tester

    ImgDataset -->|data| Trainer
    RealESRGANDataset -->|data| Trainer
    ImgDataset -->|data| Tester
    RealESRGANDataset -->|data| Tester

    HATArch -->|defines| Trainer
    SRVGGArch -->|defines| Trainer
    DiscArch -->|defines| Trainer
    HATModel -->|wraps| Trainer
    GANModel -->|wraps| Trainer
    MSEModel -->|wraps| Trainer

    Trainer -->|saves| Checkpoints
    Trainer -->|exports| Pretrained

    Tester -->|outputs| ResultsDir
    Tester -->|generates| Figures

    %% External dependencies
    PyTorch -.-> Trainer
    PyTorch -.-> Tester
    BasicSR -.-> Trainer
    BasicSR -.-> Tester
    RemoteStorage -.-> Pretrained
    ReproBadge -.-> TrainScript
    ReproBadge -.-> TestScript

    RequirementsTXT -.->|defines| TrainScript
    SetupPy -.->|project setup| TrainScript
    SetupCFG -.->|project setup| TrainScript
    Version -.->|project version| TrainScript

    %% Click Events
    click TrainScript "https://github.com/xpixelgroup/hat/blob/main/hat/train.py"
    click TestScript "https://github.com/xpixelgroup/hat/blob/main/hat/test.py"
    click PredictScript "https://github.com/xpixelgroup/hat/blob/main/predict.py"
    click TrainConfigs "https://github.com/xpixelgroup/hat/tree/main/options/train/"
    click TestConfigs "https://github.com/xpixelgroup/hat/tree/main/options/test/"
    click ImgDataset "https://github.com/xpixelgroup/hat/blob/main/hat/data/imagenet_paired_dataset.py"
    click RealESRGANDataset "https://github.com/xpixelgroup/hat/blob/main/hat/data/realesrgan_dataset.py"
    click MetaInfo "https://github.com/xpixelgroup/hat/blob/main/hat/data/meta_info/meta_info_DF2Ksub_GT.txt"
    click RawData "https://github.com/xpixelgroup/hat/tree/main/datasets/"
    click HATArch "https://github.com/xpixelgroup/hat/blob/main/hat/archs/hat_arch.py"
    click SRVGGArch "https://github.com/xpixelgroup/hat/blob/main/hat/archs/srvgg_arch.py"
    click DiscArch "https://github.com/xpixelgroup/hat/blob/main/hat/archs/discriminator_arch.py"
    click HATModel "https://github.com/xpixelgroup/hat/blob/main/hat/models/hat_model.py"
    click GANModel "https://github.com/xpixelgroup/hat/blob/main/hat/models/realhatgan_model.py"
    click MSEModel "https://github.com/xpixelgroup/hat/blob/main/hat/models/realhatmse_model.py"
    click Pretrained "https://github.com/xpixelgroup/hat/tree/main/experiments/pretrained_models/"
    click Checkpoints "https://github.com/xpixelgroup/hat/tree/main/experiments/"
    click ResultsDir "https://github.com/xpixelgroup/hat/tree/main/results/"
    click Figures "https://github.com/xpixelgroup/hat/tree/main/figures/"
    click RequirementsTXT "https://github.com/xpixelgroup/hat/blob/main/requirements.txt"
    click SetupPy "https://github.com/xpixelgroup/hat/blob/main/setup.py"
    click SetupCFG "https://github.com/xpixelgroup/hat/blob/main/setup.cfg"
    click Version "https://github.com/xpixelgroup/hat/tree/main/VERSION"

    %% Styles
    classDef config fill:#D3C4E3,stroke:#333,stroke-width:1px
    classDef data fill:#C4DBE0,stroke:#333,stroke-width:1px
    classDef model fill:#C4E0C4,stroke:#333,stroke-width:1px
    classDef compute fill:#F3D8B4,stroke:#333,stroke-width:1px
    classDef storage fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px
```
