# wgsxm/partcrafter architecture

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

- Interactive diagram: https://gitdiagram.com/wgsxm/partcrafter
- Repository: https://github.com/wgsxm/partcrafter

## Overview

##### Project Type and Purpose
- From the README and paper title, PartCrafter is a research‐oriented, deep-learning codebase that takes a single RGB image as input and generates a structured 3D mesh with multiple parts via compositional latent diffusion transformers.
- It’s not a classic web or mobile full-stack app but a machine-learning research project with distinct data-processing, model-training, and inference pipelines.

##### File Structure
- Current top-level:
- LICENSE (MIT)
- README.md (project overview + teaser)
- assets/ (figures, teaser image)
- data/ or datasets/ – raw meshes and paired images
- src/ – model definitions, training loops, inference scripts
- configs/ – hyperparameter files (e.g., Hydra or YAML)
- checkpoints/ – saved model weights
- tools/ or scripts/ – mesh pre/postprocessing, visualization

##### README for Architectural Insights
- Core functionality: joint generation of multiple mesh parts in one shot
- Key model components implied by the paper:
- Image encoder (to extract features)
- Latent diffusion module (to model generative process in latent space)
- Transformer-based compositional decoder (to assemble parts)
- Mesh reconstruction pipeline (to convert latent outputs back to 3D geometry)

a. Main Components
- Data Ingestion & Preprocessing
- RGB image loader
- Mesh/part annotation loader
- Augmentation & batching
- Model Core
- Vision Encoder (e.g., ResNet/ViT) → image tokens
- Latent Diffusion Transformer
– Latent space encoder
– Diffusion U-Net or custom block
– Compositional Transformer decoder (per-part latent vectors)
- Mesh Generation & Post-Processing
- Latent→mesh decoder (e.g., MLPs + mesh template deformation)
- Part assembly module (stitches sub‐meshes)
- Mesh refinement (smoothing, normals)
- Training & Checkpointing
- Optimizer & scheduler (e.g., AdamW)
- Loss computation (reconstruction, part consistency)
- Logging (TensorBoard, Weights & Biases)
- Checkpoint saver / Loader
- Inference & Evaluation
- Single shot inference script
- Export formats (OBJ/PLY)
- Visualization (built-in viewer or external)
- External Services / Hardware
- GPU cluster or cloud instance
- Dataset storage (local disk or S3)

b. Relationships & Data Flows
Image file → Preprocessor → Batch → Vision Encoder → Latent Diffusion → Transformer → Mesh Decoder → Export
- Training loop to Model Core, Loss, Optimizer, Checkpoint modules in a circular flow.
- External Storage → Data Loader and Checkpoint Loader.

c. Architectural Patterns & Principles
- Modular ML Pipeline: clearly separate data, model, training, and inference modules
- Config-driven experiments: use a config folder to swap hyperparameters without code changes
- Reusability: factor out common utilities (logging, checkpointing, mesh I/O)
- Scalability: able to plug in different encoders or diffusion backbones

d. Key Technologies & Frameworks
- PyTorch (model definition, training)
- HuggingFace diffusers / transformers (if leveraged)
- Trimesh or Open3D (mesh I/O, visualization)
- Hydra / YAML (configuration management)
- CUDA / cuDNN (GPU acceleration)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Pipeline
    subgraph "Data Pipeline"
        A["RGB Image Loader"]:::data
        B["Mesh Annotation Loader"]:::data
        C["Augmentation & Batching"]:::data
    end

    %% Model Core
    subgraph "Model Core"
        D["Vision Encoder"]:::model
        subgraph "Latent Diffusion Transformer"
            E1["Latent Encoder"]:::model
            E2["Diffusion U-Net"]:::model
            E3["Compositional Transformer Decoder"]:::model
        end
        F["Mesh Decoder & Part Assembly"]:::post
    end

    %% Training Infrastructure
    subgraph "Training Infrastructure"
        G["Loss Computation"]:::infra
        H["Optimizer & Scheduler"]:::infra
        I["Checkpoint Manager"]:::infra
        J["Logging (TensorBoard/W&B)"]:::infra
    end

    %% Inference & Export
    subgraph "Inference & Export"
        K["Inference Script"]:::post
        L["Export (OBJ/PLY)"]:::post
        M["Visualization"]:::post
    end

    %% External Services
    subgraph "External Services"
        S["GPU Cluster"]:::external
        T["Dataset Storage (Local/S3)"]:::external
        U["Configs (Hydra/YAML)"]:::external
    end

    %% Data Flow
    T --> A
    T --> B
    A --> C
    B --> C
    C --> D
    D --> E1
    E1 --> E2
    E2 --> E3
    E3 --> F
    F --> K
    K --> L
    K --> M

    %% Training Loop
    C --> D
    E3 --> G
    G --> H
    H --> I
    I --> D
    G --> J
    H --> J

    %% External Dependencies
    S --> D
    S --> E2
    S --> H
    S --> K
    U --> A
    U --> B
    U --> D
    U --> E2
    U --> E3
    U --> F
    U --> G
    U --> H
    U --> K

    %% Click Events
    click README.md "https://github.com/wgsxm/partcrafter/blob/main/README.md"
    click assets "https://github.com/wgsxm/partcrafter/tree/main/assets/"
    click LICENSE "https://github.com/wgsxm/partcrafter/tree/main/LICENSE"

    %% Styles
    classDef data fill:#D0E8FF,stroke:#74A9D8,stroke-width:1px
    classDef model fill:#D6F5D6,stroke:#4CAF50,stroke-width:1px
    classDef infra fill:#FFE4C4,stroke:#FF9800,stroke-width:1px
    classDef post fill:#E6DAF8,stroke:#9C27B0,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#9E9E9E,stroke-width:1px,stroke-dasharray: 5 5
```
