# ch-andrei/hdr-iqa-dom-adapt architecture

> Architecture diagram of the GitHub repository ch-andrei/hdr-iqa-dom-adapt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ch-andrei/hdr-iqa-dom-adapt
- Repository: https://github.com/ch-andrei/hdr-iqa-dom-adapt

## Overview

##### Project Type and Purpose
- The project is a deep learning research codebase focused on image quality assessment (IQA) for high dynamic range (HDR) displays.
- Its main purpose is to re-train preexisting neural network models (e.g., PieAPP, VTAMIQ) originally designed for standard dynamic range (SDR) data by incorporating domain adaptation techniques. This involves leveraging pre-trained networks and augmenting training with methods like DeepCORAL, plus exploring different normalization schemes (Pmax vs. 255).
- The repository is intended for experimentation and research, emphasizing training workflows, data preprocessing, and model modules.

##### Analysis of the File Structure
- Top-Level Directories:
- data: Manages datasets, script utilities, and data pre-/post-processing (including patch sampling and dataset splitting).
- modules: Contains various model components (e.g., PieAPP, VisionTransformer, DeepCORAL, RCAN, Attention modules, display simulation, and vtamiq) that implement different IQA methods or components of the overall architectures.
- training: Contains training scripts and configuration files for different training regimes (pre-training, domain adaptation, and multi-task training).
- utils: Provides ancillary functionalities such as image processing, logging, MATLAB interfacing, and miscellaneous helpers.
- Root-level scripts (e.g., run_pretrain_model.py and run_da.py): Serve as entry points for the training pipelines.
- The structure suggests a modular design where each key functionality (data loading, model definition, training procedures, and utility functions) is isolated, allowing clear separation of concerns.

##### Key Components
a. Data Layer:
- Datasets: Represented by the “data/datasets” directory and associated scripts (data/patch_sampling.py, data/utils.py, etc.). This module handles the ingestion and preprocessing (splitting, patch extraction) of both SDR and HDR images.
- Scripts for dataset preparation (e.g., upiq_split_compute.py) could be represented as sub-processes within this layer.
b. Model Modules:
- Core Models: Modules like PieAPP (modules/PieAPP), VTAMIQ (modules/vtamiq and modules/VisionTransformer), RCAN, and Attention (modules/Attention) show the variety of network architectures used.
- Auxiliary Modules: Modules for DeepCORAL (modules/DeepCORAL) and display simulation utilities show additional functionality designed to help with domain adaptation (i.e., aligning the deep feature activations between SDR and HDR domains).
c. Training Pipeline:
- Training scripts in “training” that orchestrate the training loops (train.py, train_da.py, train_multi.py) and configuration (train_config.py).
- Main entry points (run_pretrain_model.py and run_da.py) that kick off different phases of training.
- Loss composition (combining SDR loss, HDR loss, and the CORAL loss) is central to the training logic.
d. Utility/Support Functions:
- These utility components support both the data processing and training runtime environments.

##### Relationships and Interactions
- Data flows from the Data Layer (datasets and pre-processing scripts) into the Training Pipeline.
- The Training Pipeline then uses the Model Modules which encapsulate the neural network architectures.
- Specialized domain adaptation and loss modules (e.g., DeepCORAL from modules/DeepCORAL) are integrated into the training process.
- Utility functions provide cross-cutting support (e.g., for logging and image processing) and interact with both the data handling and training.

##### Important Architectural Patterns and Design Principles
- Modularity: Separation of data, models, training, and utilities to encourage reusability and easier maintenance.
- Pipeline Structure: A well-defined multi-phase training pipeline – starting with pre-training on SDR data and proceeding to domain adaptation training with HDR data.
- Layered Architecture: Distinct separation of core functionalities similar to an application with a “data layer”, “service layer” (Model modules and Loss modules) and “interface layer” (training scripts that serve as launchers).
- Dependency Inversion: Model components and utilities are designed to be plug-and-play, where training scripts call on model modules according to configuration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        A1["Datasets Directory"]:::data
        A2["Patch Sampling Script"]:::data
        A3["Dataset Split Script"]:::data
        A4["Data Utils"]:::data
    end

    subgraph "Training Pipeline"
        C2["Entry Points"]:::training
        C1["Training Scripts"]:::training
    end

    subgraph "Model Modules"
        B1["PieAPP Model"]:::model
        B2a["VTAMIQ Model"]:::model
        B2b["VisionTransformer"]:::model
        B3["DeepCORAL Module"]:::model
        B4["Attention Module"]:::model
        B5["RCAN Module"]:::model
        B6["Display Simulation Module"]:::model
    end

    subgraph "Utility Functions"
        D1["Utility Functions"]:::utility
    end

    %% Data flows
    A1 -->|"preprocesses"| C1
    C2 -->|"launches"| C1

    %% Training Pipeline calls Model Modules
    C1 -->|"trains_using"| B1
    C1 -->|"trains_using"| B2a
    C1 -->|"trains_using"| B2b
    C1 -->|"DeepCORAL_Loss"| B3
    C1 -->|"trains_using"| B4
    C1 -->|"trains_using"| B5
    C1 -->|"trains_using"| B6

    %% Training Pipeline uses Utility Functions
    C1 -->|"support_calls"| D1

    %% Class Definitions for styling
    classDef data fill:#9dc3e6,stroke:#1f78b4,stroke-width:2px;
    classDef model fill:#a7d7a7,stroke:#33a02c,stroke-width:2px;
    classDef training fill:#ffd699,stroke:#ff7f0e,stroke-width:2px;
    classDef utility fill:#d7bde2,stroke:#8e44ad,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/data/datasets"
    click A2 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/blob/main/data/patch_sampling.py"
    click A3 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/blob/main/data/scripts/upiq_split_compute.py"
    click A4 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/blob/main/data/utils.py"
    click B1 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/PieAPP"
    click B2a "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/vtamiq"
    click B2b "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/VisionTransformer"
    click B3 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/DeepCORAL"
    click B4 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/Attention"
    click B5 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/RCAN"
    click B6 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/modules/display_simulation"
    click C1 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/training"
    click C2 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/blob/main/run_pretrain_model.py"
    click D1 "https://github.com/ch-andrei/hdr-iqa-dom-adapt/tree/main/utils"
```
