README.md

---
title: ThreeGen
emoji: 🧊
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "5.29.0"
app_file: app.py
pinned: false
tags:
  - build-small
  - off-brand
  - tiny-titan
  - best-demo
  - track:wood
  - sponsor:openai
  - achievement:offbrand
  - achievement:fieldnotes
---

# 🧊 ThreeGen

**Describe a 3D scene, get clean Three.js code.**

Type a prompt. A 3B model emits a JSON scene graph. A deterministic compiler turns it into a live Three.js preview with copy-paste-ready code.

## What it does

ThreeGen converts natural-language prompts into interactive 3D scenes. You describe an object — a star badge, a stack of neon cubes, a glass torus knot — and get a self-contained `.html` file you can open in any browser. The preview in the app is the exact same code that ends up in the Code tab: no divergence between "preview" and "output."

## The problem and the approach

Small models can't write Three.js directly — they hallucinate method names, invent APIs, and produce broken code at high rates. ThreeGen sidesteps this by splitting the job in two:

1. **The model writes structured JSON** — a narrow, validated scene graph (objects, materials, layout, animations). This is a small, learnable format even a 3B model handles well.
2. **A deterministic compiler writes Three.js** — `compiler.py` translates the scene graph into guaranteed-valid code, applies version-pinned Three.js r160, handles lighting, bloom, OrbitControls, and async font loading.

The model never touches the Three.js API. The preview never breaks on a bad token.

```
prompt → Qwen2.5-Coder-3B → JSON scene graph → validate/repair → compiler → Three.js HTML
```

## Features

- **Primitives** — box, sphere, cylinder, cone, torus, torus knot, icosahedron, plane, ring, capsule, and more
- **Extruded shapes** — star, heart, arrow, hexagon, shield, custom SVG paths
- **3D text** — FontLoader + TextGeometry, composited into extruded badge templates
- **Deterministic templates** — star badge, shield badge: the model picks shape + colors, Python handles layout
- **Scene-graph groups** — hierarchical `THREE.Group()` with row / column / stack / grid layout, nested groups supported
- **Materials** — glass, metal, neon glow, chrome, matte, wireframe, with roughness/metalness control
- **Live preview** — iframe with OrbitControls (drag to orbit, scroll to zoom)
- **Copy-paste code** — the Code tab is the complete HTML file; save it, double-click, done
- **Lighting + glow controls** — ambient, directional, environment map, UnrealBloomPass strength slider

## Built small

Runs on **Qwen2.5-Coder-3B-Instruct** — a 3-billion-parameter model — on a single ZeroGPU T4. The model's job is intentionally narrow: emit a small JSON schema, not write a graphics library. Reliability comes from the compiler, not from model size.

## Demo

Demo video: [https://youtu.be/1NUB0DOGgcA](https://youtu.be/1NUB0DOGgcA)

Social post: [https://x.com/i/status/2066608249064030439](https://x.com/i/status/2066608249064030439)

## How it works (technical)

**Pipeline:**
1. `llm.py` — loads the model (or returns a mock for local dev), assembles a system prompt with the scene schema and ~30 few-shot examples, runs greedy generation, extracts the first valid JSON block from the output
2. `scene.py` — Pydantic v2 models for every node type (`Obj`, `ExtrudeNode`, `Text3DNode`, `GroupNode`, `Animation`); validators clamp out-of-range values and repair missing fields; `_parse_scene_item` dispatches on `"type"`
3. `compiler.py` — walks the scene graph with a `_Ctx` context object, emits Three.js JS for each node type, collects async font jobs for `Text3DNode`; wraps everything in an `async IIFE` inside a single self-contained HTML file with an importmap pinned to Three.js r160
4. `app.py` — Gradio 6 UI with ZeroGPU `@spaces.GPU` decorator; `generate()` builds the scene and compiles HTML; `rerender()` recompiles from cached scene JSON with new style/glow values without re-running the model

**Three.js output** uses a version-pinned importmap (`r160`) so the generated code remains valid regardless of CDN updates. All add-ons (OrbitControls, EffectComposer, UnrealBloomPass, RoundedBoxGeometry, FontLoader) are loaded from the same pinned release.

## Future work

- **Bloc3D mesh extension** — extend the pipeline to emit geometry for actual mesh generation (the project's longer-term goal)
- **Fine-tuning** — synthetic prompt→JSON pairs on a 0.5B model to push reliability further down in parameter count
- **More templates** — coin, ribbon, seal; parameterized layout macros

## Files

| file | role |
|---|---|
| `scene.py` | scene DSL schema, Pydantic validation, node types |
| `llm.py` | model load, few-shot prompt, JSON extraction, mock fallback |
| `compiler.py` | scene graph → standalone Three.js HTML |
| `app.py` | Gradio UI, ZeroGPU wiring, style/glow controls |

## GitHub

[https://github.com/bolajiev/ThreeGen](https://github.com/bolajiev/ThreeGen)

## Local dev

```bash
pip install -r requirements.txt

# No model download, no GPU — instant iteration:
MOCK=1 python app.py

# Real model:
python app.py
```