# switchablenorms/celebamask-hq architecture

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

- Interactive diagram: https://gitdiagram.com/switchablenorms/celebamask-hq
- Repository: https://github.com/switchablenorms/celebamask-hq

## Overview

##### Project type and purpose
- This repository is an open-source, research-oriented ML toolkit built around the CelebAMask-HQ dataset. It contains two sub-projects:
a. MaskGAN_demo – an interactive facial image manipulation demo using a GAN (pix2pixHD-based).
b. face_parsing – a U-Net-based face segmentation pipeline with data preprocessing, training, and testing scripts.
- The root README describes the CelebAMask-HQ dataset (30k high-res face images + 19-class masks), and points to demo capabilities and downstream tasks (face parsing, generation, editing).

##### File structure
- Top-level directories:
- MaskGAN_demo/
– data/ (dataset abstractions, loaders)
– models/ (base_model, network definitions, pix2pixHD_model)
– options/ (CLI config for train/test)
– ui/ & ui_util/ (interactive GUI event handling, config)
– demo.py (entrypoint for interactive demo)
- face_parsing/
– Data_preprocessing/ (mask generation, partitioning scripts)
– model_utils.py, unet.py (model code)
– trainer.py, tester.py, main.py (training & test orchestration)
– data_loader.py (custom loader)
– run.sh, run_test.sh (bash wrappers)
– README.md (dataset and demo overview)
– images/ (sample visuals)
- Patterns:
- Modular separation by concern (data, models, options, UI).
- Inheritance and factory patterns in data loaders (base_data_loader → custom_dataset_data_loader) and models (base_model → pix2pixHD_model).
- CLI option classes (base_options, train_options, test_options).

##### README for additional insights
- The focus is on non-commercial research use.
- The demo showcases an interactive face editing UI.
- It invites use of the dataset in face parsing, recognition, and GAN-based editing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        RawData["Raw Images + Masks (CelebAMask-HQ)"]:::dataLayer
        Preprocessing["Data Preprocessing"]:::dataLayer
        RawData -->|provides| Preprocessing
    end

    %% Data Preprocessing Details
    subgraph "Preprocessing Modules"
        direction TB
        GColor["g_color.py"]:::dataLayer
        GMask["g_mask.py"]:::dataLayer
        GPartition["g_partition.py"]:::dataLayer
        UtilsPP["utils.py"]:::dataLayer
        Preprocessing --> GColor
        Preprocessing --> GMask
        Preprocessing --> GPartition
        Preprocessing --> UtilsPP
    end

    %% Data Loader Layer
    subgraph "Data Loader Layer"
        direction TB
        MaskGANBaseLoader["base_data_loader.py"]:::dataLayer
        MaskGANBaseDataset["base_dataset.py"]:::dataLayer
        CustomLoader["custom_dataset_data_loader.py"]:::dataLayer
        DataLoaderMG["data_loader.py (MaskGAN)"]:::dataLayer
        AlignedDataset["aligned_dataset.py"]:::dataLayer
        ImageFolder["image_folder.py"]:::dataLayer
        FaceParsingLoader["data_loader.py (face_parsing)"]:::dataLayer

        Preprocessing -->|"outputs"| FaceParsingLoader
        FaceParsingLoader -->|"feeds"| MaskGANBaseLoader
        MaskGANBaseLoader --> MaskGANBaseDataset
        MaskGANBaseLoader --> CustomLoader
        MaskGANBaseLoader --> DataLoaderMG
        MaskGANBaseLoader --> AlignedDataset
        MaskGANBaseLoader --> ImageFolder
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        BaseModel["base_model.py"]:::modelLayer
        Networks["networks.py"]:::modelLayer
        ModelsIndex["models.py"]:::modelLayer
        Pix2PixHD["pix2pixHD_model.py"]:::modelLayer
        UNet["unet.py"]:::modelLayer
        ModelUtils["model_utils.py"]:::modelLayer

        DataLoaderMG --> BaseModel
        CustomLoader --> BaseModel
        BaseModel --> Networks
        BaseModel --> ModelsIndex
        ModelsIndex --> Pix2PixHD
        FaceParsingLoader --> UNet
        FaceParsingLoader --> ModelUtils
    end

    %% Training Orchestration
    subgraph "Training Orchestration"
        direction TB
        BaseOptions["base_options.py"]:::scriptLayer
        TrainOptions["train_options.py"]:::scriptLayer
        DemoEntry["demo.py (MaskGAN)"]:::scriptLayer
        TrainerFP["trainer.py"]:::scriptLayer
        MainFP["main.py"]:::scriptLayer
        ParamsFP["parameter.py"]:::scriptLayer

        BaseModel --> TrainOptions
        Networks --> TrainOptions
        TrainOptions --> DemoEntry
        DemoEntry -->|trains Pix2PixHD| Pix2PixHD
        FaceParsingLoader --> TrainerFP
        TrainerFP --> MainFP
        ParamsFP --> TrainerFP
        MainFP -->|trains UNet| UNet
    end

    %% Inference & Demo UI
    subgraph "Inference & Demo UI"
        direction TB
        TestOptions["test_options.py"]:::scriptLayer
        DemoEntry --> TestOptions
        UI["ui.py"]:::uiLayer
        MouseEvt["mouse_event.py"]:::uiLayer
        UIUtil["config.py"]:::uiLayer

        TestOptions -->|loads weights| Pix2PixHD
        Pix2PixHD -->|inference| UI
        UI --> MouseEvt
        UI --> UIUtil
        FaceParsingLoader --> TesterFP["tester.py"]:::scriptLayer
        TesterFP -->|tests UNet| UNet
    end

    %% Scripts / CLI
    subgraph "Scripts / CLI"
        direction TB
        RunFP["run.sh"]:::scriptLayer
        RunTestFP["run_test.sh"]:::scriptLayer
        RunFP --> MainFP
        RunTestFP --> TesterFP
    end

    %% Documentation / Samples
    subgraph "Documentation / Samples"
        direction TB
        README1["README.md"]:::scriptLayer
        README2["MaskGAN_demo/README.md"]:::scriptLayer
        README3["face_parsing/README.md"]:::scriptLayer
        Images["images/"]:::scriptLayer
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch("PyTorch"):::extDeps
        CUDA("CUDA"):::extDeps
        PIL("Python Imaging Library"):::extDeps
        GUI("GUI toolkit (OpenCV, glfw)"):::extDeps
    end

    %% Styles
    classDef dataLayer fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef modelLayer fill:#90EE90,stroke:#333,stroke-width:1px
    classDef uiLayer fill:#FFA500,stroke:#333,stroke-width:1px
    classDef extDeps fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef scriptLayer fill:#E0E0E0,stroke:#333,stroke-width:1px

    %% Click Events
    click GColor "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/Data_preprocessing/g_color.py"
    click GMask "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/Data_preprocessing/g_mask.py"
    click GPartition "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/Data_preprocessing/g_partition.py"
    click UtilsPP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/Data_preprocessing/utils.py"
    click MaskGANBaseLoader "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/data/base_data_loader.py"
    click MaskGANBaseDataset "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/data/base_dataset.py"
    click CustomLoader "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/data/custom_dataset_data_loader.py"
    click DataLoaderMG "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/data/data_loader.py"
    click AlignedDataset "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/data/aligned_dataset.py"
    click ImageFolder "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/data/image_folder.py"
    click FaceParsingLoader "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/data_loader.py"
    click BaseModel "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/models/base_model.py"
    click Networks "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/models/networks.py"
    click ModelsIndex "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/models/models.py"
    click Pix2PixHD "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/models/pix2pixHD_model.py"
    click UNet "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/unet.py"
    click ModelUtils "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/model_utils.py"
    click BaseOptions "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/options/base_options.py"
    click TrainOptions "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/options/train_options.py"
    click DemoEntry "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/demo.py"
    click TrainerFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/trainer.py"
    click MainFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/main.py"
    click ParamsFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/parameter.py"
    click TestOptions "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/options/test_options.py"
    click UI "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/ui/ui.py"
    click MouseEvt "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/ui/mouse_event.py"
    click UIUtil "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/ui_util/config.py"
    click TesterFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/tester.py"
    click RunFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/run.sh"
    click RunTestFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/run_test.sh"
    click README1 "https://github.com/switchablenorms/celebamask-hq/blob/master/README.md"
    click README2 "https://github.com/switchablenorms/celebamask-hq/blob/master/MaskGAN_demo/README.md"
    click README3 "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/README.md"
    click Images "https://github.com/switchablenorms/celebamask-hq/tree/master/images/"
    click RunTestFP "https://github.com/switchablenorms/celebamask-hq/blob/master/face_parsing/run_test.sh"
```
