README.md

metadata

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

Social post: 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

Local dev

pip install -r requirements.txt

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

# Real model:
python app.py