By peter_lzh img2threejs: Turn a Single Photo Into an Editable, Animatable Three.js 3D Model — 4.8k Stars in 11 Days
A couple of days ago I wanted to embed a real-world object as a 3D model in a webpage, and all I had on my hard drive was one photo.
The old playbook offers two routes: run NeRF and get a mesh weighing tens of megabytes (GPU required), or hand-model it in Blender — and my modeling skills are hopeless, so that was out.
Then I stumbled onto a new project: img2threejs. Launched just 11 days ago, it already has 4.8k stars. Its clever trick: you give it one image, and it has an AI write code that “builds” the object. No geometry inversion, no asset packs to download.
What the Project Does
You provide a reference image of an object. The tool generates a TypeScript factory function returning a THREE.Group, reconstructing the object from primitives, procedural shaders, and generated geometry — complete with a runtime hierarchy (pivots, sockets, colliders) so the result is genuinely animatable rather than a dead, rigid lump.
It runs under Claude Code, Codex, or OpenCode, and is agent-agnostic: wherever the docs mention “agent vision” or an “agent browser tool,” it will use whatever capability the host provides — native image reading, a browser MCP, project previews, or screenshots supplied by the user.
Subject Types and Detail Fidelity
- Objects and characters. Every subject is classified as object, character, or hybrid. Objects go through a hard-surface pipeline; characters follow an anatomy-aware track (head-unit proportions, facial landmarks, pose), detailed in
grimoire/character/reconstruction.md. - Detail-first analysis. Before any code generation, the pipeline enumerates a
detailInventorylisting the small identity-defining details — gloss, bevels/fillets, screws/rivets, engraved or painted lines, silhouettes, stains, and wear. Every detail must map to a real component or material entry, and a strict quality gate blocks incomplete inventories from reaching generation. The taxonomy lives ingrimoire/intake/detail_inventory.md. - Maximum likeness for specific people or characters. An optional projection-first path fits a parametric template to image keypoints, de-lights the image, camera-matches the render, and projects the reference onto the mesh. A single image can’t guarantee 100% likeness, so the pipeline reports per-region confidence and requests more viewpoints when needed. See
grimoire/character/likeness_maximization.md. - CS2 weapon review gates. The knife and Glock-18 routes use family-specific component contracts. Reviews record precision tier, family identity, painted-area and projection coverage, per-region confidence, approximation notes, and versioned review-scene metadata; component coverage and de-textured blockout gates prevent “looks-alike” textures from impersonating real structure. See
docs/cs2/review-gates.md.
In short: it doesn’t reconstruct geometry — it has the agent assemble the object from Three.js primitives, procedural shaders, and generated geometry. The output is a THREE.Group factory function: diffable, versionable, and born animation-ready with pivots, sockets, and colliders built in.
Why It’s Token-Efficient
Most image-to-3D agent loops burn tokens on mechanical busywork — re-reading the whole model every stage, scoring pixels, hand-verifying JSON, repeating finished steps. img2threejs pushes all of that into deterministic scripts, spending model tokens only where judgment is truly needed.
- Scripts execute, the model judges. Python scripts handle validation, gating, spec authoring, PBR extraction, comparison-image packing, and pipeline state. They never score visuals. The model’s tokens do exactly one thing: look at a side-by-side comparison image and decide pass or fail.
- Zero dependencies, zero install burden. Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG reading and writing is hand-rolled with
structandzlib. Nothing to install means nothing in the agent’s context to debug. - Stage-gated generation. The code generator only emits the currently unlocked build stage. The model never regenerates or rereads the entire model each iteration — every step stays small and focused.
- Fail early, before code generation. Strict quality gates block shallow specs before a single line of Three.js is generated, so no tokens are wasted on an under-specified model.
- One image per review. Each stage is judged on a single packed comparison image (reference beside render), not a pile of scattered screenshots.
- Text output, not binaries. The result is a diffable TypeScript + JSON spec — small, reviewable, version-controllable — instead of multi-megabyte mesh files.
The pipeline is a staged “sculpting” flow with eight build passes unlocked in order (blockout → structural → form → material → surface → lighting → interaction → optimization), each behind its own gate. The net effect: you still get a faithful 3D model from one image, but expensive model context is reserved for visual judgment and code — not bookkeeping. A full stage-by-stage token breakdown is in docs/TOKEN_COST.md.
How to Try It
Clone it as a skill:
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs
Paste an object photo into Claude Code and run:
/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.
No agent? The scripts run standalone:
python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts
