img2threejs
Rebuild the object in a reference image as a code-only, procedural Three.js model.
Quality-gated, animation-ready, and deliberately token-efficient — reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.
A single reference image reconstructed in code — correct proportions, colours, bevels, gold trim, and an emissive emblem — running live in the browser.
→ Open the Live Demo Gallery
Every model in the gallery is generated code, running in your browser. No mesh files, no downloads.
Live demos
Reconstructions built entirely from primitives, procedural shaders, and generated geometry. The clips below are the live models running in-browser — open each one to orbit it and read the generated source.
| Demo | Preview | Subject | View | Source |
|---|---|---|---|---|
| Sony WF-1000XM3 Earbuds + Case | hard-surface object | Live | code | |
| ISSACA 12 Gauge Shotgun | hard-surface object | Live | code | |
| Gerber Paracord Knife | hard-surface object | Live | code | |
| Doraemon House (isometric diorama) | hard-surface object | Live | code | |
| War-Hauler "SECTOR 07" | hard-surface object | Live | code | |
| Crowned Loot Chest | hard-surface object | Live | code |
The gallery source lives in hoainho/img2threejs-showcase. If this project is useful, a star on this repo helps others find it.
What it does
You give it one reference image of an object. It produces a THREE.Group factory written in TypeScript that recreates that object from primitives, procedural shaders, and generated geometry — with a runtime hierarchy (pivots, sockets, colliders) so the result is ready to animate, not an inert lump.
It runs under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever the docs say "agent vision" or "agent browser tool", it uses whatever the host provides — native image reading, a browser MCP, the project preview, or a user-supplied screenshot.
Subjects and detail accuracy
- Objects and characters. Each subject is classified
object,character, orhybrid. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented inreferences/character-reconstruction.md. - Detail-first analysis. Before code generation the pipeline enumerates a
detailInventoryof identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy:references/detail-inventory.md. - Maximum likeness for a specific person or character. An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details:
references/likeness-maximization.md.
How it works
The skill runs a staged sculpting pipeline. Scripts gate each stage; the agent's vision is the only thing that can approve a pass.
flowchart TD
A[Reference image] --> B[Probe and suitability gate]
B --> C[Pre-Spec Assessment: class, complexity, quality contract]
C --> D[Author ObjectSculptSpec: components, materials, sockets]
D --> E{Validate and strict-quality}
E -- too shallow --> D
E -- ok --> F[Locked build passes]
F --> G[Generate Three.js factory: current pass only]
G --> H[Render in browser and screenshot]
H --> I[Package one side-by-side sheet]
I --> J{Agent vision review}
J -- score below threshold --> K[Self-correct: refine-spec or refine-code]
K --> F
J -- pass --> L{More passes?}
L -- yes --> F
L -- no --> M[Animation-ready Three.js model]
Build passes
The model is sculpted in a fixed order; a pass unlocks only after the previous one is reviewed and accepted:
blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass
Each pass has its own acceptance criteria. A pass is marked continue only with a real render, a comparison sheet, an agent-vision score at or above threshold, and every identity-defining feature at or above its own threshold.
The gates
- Suitability — is the image a viable 3D target at all.
- Pre-spec and strict-quality — blocks code generation until the spec is deep enough for the object's complexity (no single-root spec for a compound object).
- Screenshot feedback —
continuerequires a render plus a comparison sheet plus a passing vision score. - Action-ready — the model exposes a runtime hierarchy (pivots, sockets, colliders, destruction groups) via
root.userData.sculptRuntime. - Attachment correctness — child parts (handles, limbs, tubes) declare how they join their parent, so nothing floats in mid-air.
- Material and lighting realism — independent PBR channels and real lights, never albedo aliased into roughness.
Self-correction
After every pass the agent chooses exactly one action: continue, refine-spec, refine-code, request-input, or stop. refine-spec fixes a wrong or shallow spec and re-validates; refine-code fixes geometry, material, or lighting that does not match a sound spec.
Quick start
-
Install — place this folder in your skills directory:
git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs -
Invoke — in Claude Code, attach or point to an object image and run:
/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours. -
Follow the pipeline — the skill validates the image, writes an assessment and spec, generates the factory pass by pass, and shows you a side-by-side comparison at each step until the render matches.
The scripts run from the skill root and need only Python 3.10+ — nothing to install.
python3 scripts/probe_reference_image.py <image>
python3 scripts/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 scripts/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 scripts/validate_sculpt_spec.py spec.json --strict-quality
python3 scripts/generate_threejs_factory.py spec.json --out src/createObjectModel.ts
Why it is token-efficient
Most image-to-3D agent loops burn tokens by asking the model to do mechanical work — re-reading the whole model every pass, scoring pixels, validating JSON by hand, re-running steps it already did. img2threejs pushes all of that into deterministic scripts and spends model tokens only where judgment is actually required.
- Scripts enforce, the model judges. The Python scripts handle validation, gating, spec authoring, PBR extraction, comparison-sheet packaging, and pipeline state. They never score visuals. The model's tokens go to one thing: looking at a single side-by-side sheet and deciding pass or fail.
- Zero dependencies, zero install churn. Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG read/write is done with
structandzlib. Nothing to install means nothing to debug in-context. - Pass-gated generation. The code generator emits only the currently unlocked build pass. The model does not regenerate or re-read the entire model on every