# ianhuang0630/blenderalchemyofficial architecture

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

- Interactive diagram: https://gitdiagram.com/ianhuang0630/blenderalchemyofficial
- Repository: https://github.com/ianhuang0630/blenderalchemyofficial

## Overview

##### Project Type and Purpose
- This is a specialized “pipeline” tool that automates Blender scene editing via Vision-Language Models (VLMs).
- It orchestrates an iterative edit generator & state evaluator (both LLM-powered) to progressively refine Blender scripts.

##### Main Components
A. Runner & Orchestration
- main.py: CLI entry point
- refinement_process.py: core loop coordinating edit generation, rendering, evaluation, and selection
B. Configuration & Inputs
- configs/*.yaml: run parameters, prompts, model selections, API key paths
- starter_blends/*.blend: initial Blender scene files
- blender_scripts/*: editable Blender-Python starter scripts by task (materials, lighting, shapekeys, geonodes)
- blender_base/*.py: “rendering scripts” that exec the editable script then invoke Blender render
C. Agents & Prompting
- agents.py: wrapper for edit generator and state evaluator agents
- prompting/*: modules constructing LLM prompts for geonodes, lighting, material, placement, shapekey
D. Execution Environment
- Infinigen-enabled Blender binary (external tool)
- LLM APIs (OpenAI GPT-4V, Claude, Gemini, or local Ollama models)
E. Data & Utilities
- utils/*: code for reading/writing records, images, experiment logs
- metrics.py: evaluation metrics
- output/ (generated at runtime): per-instance directories storing renders, scripts, thought_process JSON
F. External Services
- LLM API endpoints
- (Optional) image-generation model for “imagined” reference images

##### Relationships & Data Flow
1. User invokes main.py with arguments → loads configs, maps blender_base & blender_script paths
2. refinement_process instantiates agents (edit generator & state evaluator)
3. For each iteration:
a. Edit generator sends current state + prompt → LLM API → candidate Python edits
b. Each candidate edit is saved and fed to blender_base script → Blender binary → rendered image
c. State evaluator sends rendered images + prompt → LLM API → evaluation scores
d. refinement_process selects best candidate → updates “current state” script
4. Iterate until stopping criterion → final output folder with best_of.png and full logs

##### Architectural Patterns & Principles
- Pipeline pattern with clearly separated stages (generate → render → evaluate)
- Modular “agent” abstraction encapsulating LLM interactions
- Pluggable scripts: users can swap in different blender_scripts or blender_base for new tasks
- Configuration-driven: no hard-coded hyperparameters or model choices

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runner & Orchestration
    subgraph "Runner & Orchestration"
        direction TB
        CLI["main.py"]:::code
        ConfigLoader["Config Loader"]:::code
        Pipeline["Refinement Pipeline"]:::code
        CLI -->|"invokes with args"| ConfigLoader
        ConfigLoader -->|"loads configs & maps scripts"| Pipeline
    end

    %% Refinement Pipeline Stages
    subgraph "Refinement Pipeline"
        direction TB
        Generate["Edit Generator Agent"]:::code
        Agents["agents.py"]:::code
        PromptModules["Prompt Modules"]:::scripts
        subgraph "Prompting"
            direction TB
            GM_init["__init__.py"]:::code
            GM_geo["geonodes.py"]:::code
            GM_light["lighting.py"]:::code
            GM_mat["material.py"]:::code
            GM_place["placement.py"]:::code
            GM_shape["shapekey.py"]:::code
        end
        Generate -->|uses| Agents
        Generate -->|constructs prompts via| Prompting

        Render["Blender Execution"]:::scripts
        subgraph "Blender Execution"
            direction TB
            BS["bodyshape_shapekeys.py"]:::scripts
            GN["geonodes.py"]:::scripts
            IM["infinigen_render_materials.py"]:::scripts
            LA["lighting_adjustments.py"]:::scripts
            BlenderBin["Blender Binary"]:::external
            BS --> GN
            GN --> IM
            IM --> LA
            LA -->|"exec editable script then render"| BlenderBin
        end

        Evaluate["State Evaluator Agent"]:::code

        Generate -->|"candidate edits (Python scripts)"| Render
        Render -->|"rendered images (.png)"| Evaluate
        Evaluate -->|"evaluation scores (JSON)"| Pipeline
    end

    %% Configuration & Inputs
    subgraph "Data & Storage"
        direction TB
        Configs["configs/"]:::scripts
        Blends["starter_blends/"]:::scripts
        ScriptsDir["blender_scripts/"]:::scripts
        Utils["Utilities"]:::storage
        Metrics["metrics.py"]:::code
        Output["output/"]:::storage

        Configs --- ConfigLoader
        Blends --- ConfigLoader
        ScriptsDir --- ConfigLoader
        Utils --- Pipeline
        Metrics --- Pipeline
        Output --- Pipeline
    end

    %% Utils files
    subgraph "Experiment Utilities"
        direction TB
        U1["code.py"]:::code
        U2["image.py"]:::code
        U3["records.py"]:::code
    end
    U1 --> Utils
    U2 --> Utils
    U3 --> Utils

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM APIs (GPT-4V, Claude, Gemini)"]:::external
        ImgGen["Optional Image-Generation Model"]:::external
    end
    Generate -->|"calls LLM API"| LLM
    Evaluate -->|"calls LLM API"| LLM
    Generate -.-> ImgGen

    %% Click Events
    click CLI "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/main.py"
    click ConfigLoader "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/refinement_process.py"
    click Configs "https://github.com/ianhuang0630/blenderalchemyofficial/tree/main/configs/"
    click Blends "https://github.com/ianhuang0630/blenderalchemyofficial/tree/main/starter_blends/"
    click ScriptsDir "https://github.com/ianhuang0630/blenderalchemyofficial/tree/main/blender_scripts/"
    click BS "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/blender_base/bodyshape_shapekeys.py"
    click GN "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/blender_base/geonodes.py"
    click IM "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/blender_base/infinigen_render_materials.py"
    click LA "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/blender_base/lighting_adjustments.py"
    click Agents "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/agents.py"
    click GM_init "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/prompting/__init__.py"
    click GM_geo "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/prompting/geonodes.py"
    click GM_light "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/prompting/lighting.py"
    click GM_mat "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/prompting/material.py"
    click GM_place "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/prompting/placement.py"
    click GM_shape "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/prompting/shapekey.py"
    click U1 "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/utils/code.py"
    click U2 "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/utils/image.py"
    click U3 "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/utils/records.py"
    click Metrics "https://github.com/ianhuang0630/blenderalchemyofficial/blob/main/metrics.py"

    %% Styles
    classDef code fill:#D6EAF8,stroke:#2980B9
    classDef scripts fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#FDEBD0,stroke:#D35400
    classDef storage fill:#E5E7E9,stroke:#BDC3C7
```
