# ankanbhunia/pidm architecture

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

- Interactive diagram: https://gitdiagram.com/ankanbhunia/pidm
- Repository: https://github.com/ankanbhunia/pidm

## Overview

##### Project type and purpose
- This is a research-oriented deep learning pipeline for Person Image Synthesis via a Denoising Diffusion Model (PIDM). It ingests raw person images and pose keypoints, trains a diffusion-based UNet model, and produces new person images conditioned on pose or appearance inputs.

##### File structure
- Top-level scripts:
- train.py – distributed multi-GPU training entry point
- predict.py / PIDM_demo.ipynb – inference APIs and demo notebook
- diffusion.py, model.py – core diffusion scheduler and high-level model interface
- Directories:
- config/ – configuration loaders (YAML, .conf), hyperparameter modules
- data/ – dataset preparation and custom DataLoader wrappers (lmdb conversion)
- models/ – neural network definitions (UNet variants, pose guide network, latent nets, losses)
- utils/ – helper generation routines, inception score, other metrics
- Data assets under data/deepfashion_256x256 and raw dataset paths, organized for LMDB storage via prepare_data.py

##### README for additional insights
- Explains data preparation steps (OpenPose keypoints, train/test splits, LMDB creation)
- Describes training regime (distributed PyTorch DDP over 8 A100s, 300 epochs)
- Shows inference API: Predictor.predict_pose() and .predict_appearance() using DDIM sampler
- Mentions external dependencies: PyTorch, OpenPose, LMDB, Google Drive downloads

##### Key details to capture
- The conversion of raw images+poses to LMDB before training
- The separation of diffusion scheduler from neural net blocks
- Multi-GPU DDP orchestration in train.py
- Predictor abstraction in predict.py, supporting both pose and appearance sampling
- Evaluation hooks during and after training

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        Raw["Raw Images + OpenPose Keypoints"]:::external
        Prepare["Data Preparation"]:::orchestrator
        LMDB[(LMDB Dataset)]:::external
        Raw --> Prepare
        Prepare --> LMDB
        click Prepare "https://github.com/ankanbhunia/pidm/blob/main/data/prepare_data.py"
        click LMDB "https://github.com/ankanbhunia/pidm/tree/main/data/deepfashion_256x256/"
    end

    %% Configuration Manager
    subgraph "Configuration Manager"
        Dataconf["dataconfig.py"]:::data
        Diffconf["diffconfig.py"]:::data
        YAML["data.yaml"]:::data
        CONF["diffusion.conf"]:::data
        click Dataconf "https://github.com/ankanbhunia/pidm/blob/main/config/dataconfig.py"
        click Diffconf "https://github.com/ankanbhunia/pidm/blob/main/config/diffconfig.py"
        click YAML "https://github.com/ankanbhunia/pidm/blob/main/config/data.yaml"
        click CONF "https://github.com/ankanbhunia/pidm/blob/main/config/diffusion.conf"
    end

    %% DataLoader & Dataset Wrappers
    subgraph "DataLoader & Dataset Wrappers"
        DemoDS["demo_dataset.py"]:::data
        DemoAppDS["demo_appearance_dataset.py"]:::data
        FashionData["fashion_data.py"]:::data
        FashionBase["fashion_base_function.py"]:::data
        click DemoDS "https://github.com/ankanbhunia/pidm/blob/main/data/demo_dataset.py"
        click DemoAppDS "https://github.com/ankanbhunia/pidm/blob/main/data/demo_appearance_dataset.py"
        click FashionData "https://github.com/ankanbhunia/pidm/blob/main/data/fashion_data.py"
        click FashionBase "https://github.com/ankanbhunia/pidm/blob/main/data/fashion_base_function.py"
    end

    LMDB -->|"loads"| DemoDS
    LMDB -->|"loads"| DemoAppDS
    LMDB -->|"loads"| FashionData
    DemoDS --> DLoader["PyTorch DataLoader"]:::data
    DemoAppDS --> DLoader
    FashionData --> DLoader

    %% Model & Algorithm Layer
    subgraph "Model & Algorithm Layer"
        Blocks["blocks.py"]:::model
        NN["nn.py"]:::model
        UNet["unet.py"]:::model
        UNetAE["unet_autoenc.py"]:::model
        PoseNet["pose_guide_network.py"]:::model
        Latent["latentnet.py"]:::model
        ModelInterface["model.py"]:::model
        click UNet "https://github.com/ankanbhunia/pidm/blob/main/models/unet.py"
        click UNetAE "https://github.com/ankanbhunia/pidm/blob/main/models/unet_autoenc.py"
        click PoseNet "https://github.com/ankanbhunia/pidm/blob/main/models/pose_guide_network.py"
        click Latent "https://github.com/ankanbhunia/pidm/blob/main/models/latentnet.py"
        click Blocks "https://github.com/ankanbhunia/pidm/blob/main/models/blocks.py"
        click NN "https://github.com/ankanbhunia/pidm/blob/main/models/nn.py"
        click ModelInterface "https://github.com/ankanbhunia/pidm/blob/main/model.py"
    end

    %% Diffusion Scheduler
    subgraph "Diffusion Scheduler"
        Diff["diffusion.py"]:::model
        click Diff "https://github.com/ankanbhunia/pidm/blob/main/diffusion.py"
    end

    %% Training Engine
    subgraph "Training Engine"
        Train["train.py"]:::orchestrator
        Losses["models/losses.py"]:::model
        click Train "https://github.com/ankanbhunia/pidm/blob/main/train.py"
        click Losses "https://github.com/ankanbhunia/pidm/blob/main/models/losses.py"
    end

    %% Inference Engine
    subgraph "Inference Engine"
        Predict["predict.py"]:::orchestrator
        DemoNB["PIDM_demo.ipynb"]:::orchestrator
        click Predict "https://github.com/ankanbhunia/pidm/blob/main/predict.py"
        click DemoNB "https://github.com/ankanbhunia/pidm/blob/main/PIDM_demo.ipynb"
    end

    %% Evaluation & Metrics
    subgraph "Evaluation & Metrics"
        IS["inception.py"]:::orchestrator
        Metrics["metrics.py"]:::orchestrator
        click IS "https://github.com/ankanbhunia/pidm/blob/main/utils/inception.py"
        click Metrics "https://github.com/ankanbhunia/pidm/blob/main/utils/metrics.py"
    end

    %% Utilities
    subgraph "Utilities"
        Gen["gen.py"]:::model
        click Gen "https://github.com/ankanbhunia/pidm/blob/main/utils/gen.py"
    end

    %% Flow Connections
    DLoader --> Train
    Dataconf --> Train
    Diffconf --> Train
    YAML --> Train
    CONF --> Train
    Train --> Blocks
    Train --> NN
    Train --> UNet
    Train --> PoseNet
    Train --> Latent
    Train --> Diff
    Train --> Losses
    Train -->|"writes checkpoints"| Checkpoint[(Checkpoint Store)]:::external

    Checkpoint --> Predict
    Predict --> Blocks
    Predict --> NN
    Predict --> UNet
    Predict --> PoseNet
    Predict --> Latent
    Predict --> Diff
    Predict -->|"outputs images"| Output["Generated Images"]:::external

    Train --> IS
    Train --> Metrics
    Predict --> IS
    Predict --> Metrics

    %% Styles
    classDef data fill:#ADD8E6,stroke:#000,color:#000
    classDef model fill:#90EE90,stroke:#000,color:#000
    classDef orchestrator fill:#FFA500,stroke:#000,color:#000
    classDef external fill:#DDA0DD,stroke:#000,color:#000
```
