# meowuu7/geneoh-diffusion architecture

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

- Interactive diagram: https://gitdiagram.com/meowuu7/geneoh-diffusion
- Repository: https://github.com/meowuu7/geneoh-diffusion

## Overview

##### Project type and purpose
- This is a machine-learning research codebase implementing the “Generalizable Hand-Object Interaction (HOI) Denoising” diffusion model in PyTorch.
- It provides end-to-end pipelines: data preparation, training diffusion models (motion & spatial), inference/denoising on test datasets (GRAB, TACO, HOI4D), mesh reconstruction, and visualization.

##### Core logical components
a. Data Sources (External)
- GRAB, HOI4D, TACO raw and pre-processed data under `/data/...`
- Anchor weights & mesh files under `/assets/...`
b. Preprocessing & Data Loaders
- `prepare/` scripts (shell) to download and organise datasets
- Python loader modules in `data_loaders/` and shared utilities in `common/` & `utils/`
c. Core Model & Diffusion Engine
- Network definitions in `model/` (DGCNN, PointNet2, MDM, SMPL models)
- Diffusion algorithm and training losses in `diffusion/`
- MANO hand-model layer provided by the local `manopth/` package
d. Training Pipeline
- Shell scripts `scripts/train/*.sh` call Python trainers in `train/` (e.g., `train_mdm.py`, `training_loop.py`)
- Produces checkpoints in `ckpts/`
e. Inference/Evaluation Pipeline
- Shell scripts `scripts/val/*.sh` orchestrate denoising and reconstruction
- Sample inference entrypoints in `sample/` (e.g., `predict_grab.py`)
- Mesh reconstruction utilities (inside `utils/` and `common/rend_utils.py`)
f. Visualization

##### Interactions & Data Flow
- Start: CLI (shell) → selects dataset paths & parameters →
Data loaders in `data_loaders/` + shared `common/` modules load `.npy`/`.pkl` →
Preprocessed data fed into diffusion networks from `diffusion/` + model definitions from `model/` →
Output latent/object/hand trajectories →
Mesh reconstruction (MANO in `manopth/` + rendering utils) →
Save denoised trajectories under `data/.../result` →
Visualization scripts pick up results and generate figures/videos.

##### Architectural patterns & design principles
- Modular design: clear separation between data I/O, model logic, training loops, inference scripts, and visualization
- Reuse of shared utilities: `common/` vs. project-specific `utils/` for multidomain support
- Shell script orchestration: reproducible pipelines for training & evaluation
- Pluggable dataset backends: each dataset loader conforms to a common interface
- External dependence isolation: local `manopth/` ensures consistent MANO behavior

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        A1[(Raw GRAB Dataset)]:::data
        A2[(Raw HOI4D Dataset)]:::data
        A3[(Raw TACO Dataset)]:::data
        A4[(Anchor Assets)]:::data
    end

    subgraph "Loader Layer"
        B1((data_loaders/)):::loader
        B2((common/)):::loader
        B3((utils/)):::loader
    end

    subgraph "Model Engine"
        C1["Model Definitions"]:::core
        C2["Diffusion Engine"]:::core
        C3["MANO Hand-Model"]:::core
    end

    subgraph "Orchestration"
        D1{{"Training Scripts"}}:::orchestration
        D2{{"Inference Scripts"}}:::orchestration
    end

    subgraph "Output Layer"
        E1[(Checkpoints ckpts/)]:::output
        E2[(Denoised Results)]:::output
    end

    subgraph "Visualization"
        F1["Visualization Scripts"]:::viz
    end

    A1 -->|".npy/.pkl"| B1
    A2 -->|".npy/.pkl"| B1
    A3 -->|".npy/.pkl"| B1
    A4 -->|".pkl/.txt"| B2

    B1 -->|"dataset objects"| C1
    B2 -->|"utilities"| C3
    B3 -->|"helpers"| C1

    C1 --> C2
    C3 --> C2
    C2 -->|"latent trajectories"| D1
    C2 -->|"latent trajectories"| D2

    D1 -->|"model checkpoints"| E1
    D2 -->|"denoised trajectories"| E2

    E2 -->|"result files"| F1

    click A1 "https://github.com/meowuu7/geneoh-diffusion/tree/main/data/grab/"
    click A2 "https://github.com/meowuu7/geneoh-diffusion/tree/main/data/hoi4d/"
    click A3 "https://github.com/meowuu7/geneoh-diffusion/tree/main/data/taco/"
    click A4 "https://github.com/meowuu7/geneoh-diffusion/tree/main/assets/anchor/"
    click B1 "https://github.com/meowuu7/geneoh-diffusion/tree/main/data_loaders/"
    click B2 "https://github.com/meowuu7/geneoh-diffusion/tree/main/common/"
    click B3 "https://github.com/meowuu7/geneoh-diffusion/tree/main/utils/"
    click C1 "https://github.com/meowuu7/geneoh-diffusion/tree/main/model/"
    click C2 "https://github.com/meowuu7/geneoh-diffusion/tree/main/diffusion/"
    click C3 "https://github.com/meowuu7/geneoh-diffusion/tree/main/manopth/"
    click D1 "https://github.com/meowuu7/geneoh-diffusion/tree/main/scripts/train/"
    click D2 "https://github.com/meowuu7/geneoh-diffusion/tree/main/scripts/val/"
    click F1 "https://github.com/meowuu7/geneoh-diffusion/tree/main/visualize/"

    classDef data fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef loader fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#000,stroke-width:1px
    classDef output fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef viz fill:#DDA0DD,stroke:#000,stroke-width:1px
```
