img2threejs (~633 stars, 53 forks, MIT) is the rare image-to-3D project that refuses to ship a mesh file. You hand it one reference photo; it returns a createObjectNameModel() TypeScript factory, an ObjectSculptSpec JSON, and a THREE.Group with root.userData.sculptRuntime — pivots, sockets, colliders, destruction groups — ready for animation, not an inert GLB lump.
On July 20, 2026, maintainer hoainho merged PR #9 — a layout refactor into forge/, grimoire/, and docs/ with stage-prefixed Python scripts. Version 1.2.0 adds a humanoid character track; hard-surface objects remain the sweet spot.
If you have been following bunpav's procedural labs or agent skills on explainx.ai, img2threejs sits at the intersection: procedural memory for 3D, not another diffusion checkpoint.
Repo: github.com/hoainho/img2threejs · Gallery: hoainho.github.io/img2threejs-showcase · Token model: docs/TOKEN_COST.md
TL;DR — questions people search after the GitHub README
| Question | Answer (July 20, 2026) |
|---|---|
| What do I get? | Diffable TypeScript factory + ObjectSculptSpec JSON — no GLB required |
| License? | MIT — commercial use OK; read scripts before sensitive repos |
| Runtime deps? | Python 3.10+ stdlib only — no pip, no numpy, no Playwright |
| Token cost? | ~80k–180k model tokens/object (hard-surface); ~150k–350k for characters |
| Inputs? | One reference image — agent vision reviews side-by-side sheets each pass |
| Best subjects? | Hard-surface props (chests, earbuds, knives, vehicles) |
| Weak subjects? | Organic heroes, hidden back faces, photoreal human likeness from one photo |
| Animation-ready? | Yes — sculptRuntime exposes sockets/colliders; glTF export planned v1.4 |
| vs neural photo-to-3D? | Code + spec (deterministic, editable) vs GLB (stochastic, opaque) |
| bunpav link? | Architecture fit, not a public product page — see below |
What img2threejs actually does
Most photo-to-3D stacks reconstruct geometry with diffusion or multi-view neural nets and hand you a textured mesh. img2threejs inverts the contract:
"Rebuild the object in a reference image as a code-only, procedural Three.js model." — README
The output is reconstruction-by-code: primitives, procedural shaders, generated geometry — the same patterns you would write by hand if you had a week and strong Three.js taste.
Showcase proof: the live gallery runs Sony WF-1000XM3 earbuds, an ISSACA shotgun, a Gerber knife, a Doraemon diorama, a War-Hauler truck, and a Crowned Loot Chest — each with published TypeScript source you can diff in Git.
Contrast with LingBot-Map: LingBot infers metric geometry from video streams; img2threejs authors forward from one still. Different layer of the 3D stack — and closer to bunpav Primitive Lab sliders than to photogrammetry.
The pass-gated pipeline (scripts enforce, model judges)
img2threejs is an agent skill with a quality-gated sculpt loop. Python scripts under forge/ handle bookkeeping; model tokens go to spec authoring, code edits, and vision review of comparison sheets.
Build passes (fixed order)
Each pass unlocks only after the previous one passes agent-vision threshold:
blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass
Gates that save tokens
| Gate | What it blocks |
|---|---|
| Suitability | Non-viable reference (wrong framing, no clear object) |
| Pre-spec + strict-quality | Shallow ObjectSculptSpec before any Three.js codegen |
| Detail inventory | Missing identity-defining micro-details (bevels, rivets, emissive trim) |
| Screenshot feedback | continue without render + comparison sheet + passing score |
| Attachment correctness | Floating handles, limbs, tubes without join metadata |
After every pass the agent picks exactly one action: continue, refine-spec, refine-code, request-input, or stop.
Quick start commands
git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs
In Claude Code, attach an object image:
/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.
Manual script chain (from skill root):
python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
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
Rubrics live in grimoire/ (validation, materials, lighting realism, action-ready hierarchy). Post-refactor paths replace the older flat scripts/ layout — verify forge/ if you forked before PR #9.
Token economics (~80k–180k per object)
The skill's own TOKEN_COST.md is explicit: figures are engineering estimates, not a measured benchmark (v1.5 benchmark planned).
| Stage | Est. model tokens | Notes |
|---|---|---|
| Deterministic scripts | ~2k–5k total | Near-free subprocess work |
| Assessment + spec JSON | ~15k–25k | Largest text artifact |
| Three.js factory writes/edits | ~20k–45k | Scales with part count |
| Render-review loop (5–8 cycles) | ~30k–70k | Dominant cost |
| Total (one object) | ~80k–180k | Few cycles → many cycles |
Per review cycle: ~5k–12k (~2k–3k vision on one side-by-side sheet + ~1k–2k review write).
Why this beats naive agent loops: validation, gating, PBR evidence extraction, and comparison-sheet packaging run in stdlib Python — the model never re-reads a whole megabyte mesh. Pass-gated codegen emits only the unlocked pass, not the entire factory every iteration.
Pair with explainx.ai's broader token governance mindset: strict-quality upfront is cheaper than three failed renders. For character tracks (v1.2), budget ~150k–350k.
What you get in the repo (not on Sketchfab)
| Artifact | Purpose |
|---|---|
ObjectSculptSpec JSON | Component tree, materials, sockets, review history per pass |
createObjectNameModel(spec, options) | Returns THREE.Group with runtime hierarchy |
root.userData.sculptRuntime | Nodes, pivots, sockets, colliders, destruction groups |
| Comparison sheets | Reference vs render evidence at each pass |
Roadmap snapshot: v1.0–v1.2 shipped (objects + detail inventory + character generator). v1.3 likeness maximization and v1.4 SkinnedMesh / morph targets / glTF export are planned — today you integrate the factory directly in a Three.js scene or wrap export yourself.
Honest limits (read before your jam deadline)
The README states limits plainly — worth quoting because searchers ask:
- Single image cannot reveal hidden sides; unseen faces are mirrored or inferred, not faked as ground truth.
- Hard-surface objects (loot chests, earbuds, knives) are the demo tier; characters are stylized, not photoreal likeness from one photo.
- "This cannot reach the requested fidelity from this image" is a valid
stopoutcome — not a skill failure. - Detail-first analysis helps, but it does not turn a blurry phone snap into CAD.
If you need photo-accurate organic sculpts (faces, cloth, hair), neural photo-to-3D paths still win on silhouette fidelity — at the cost of opaque meshes.
bunpav: two reconstruction lanes (operator view)
Disclosure: I operate bunpav.com (AISOLO Technologies) — the same founder as explainx.ai. No public bunpav page names img2threejs today. This section describes product architecture fit, not a marketed integration badge.
Lane A — Neural photo-to-mesh (credits)
bunpav's credit packs power text-to-3D, photo-to-3D, and auto-rig — diffusion/reconstruction → textured GLB/FBX/OBJ. Stochastic, fast for hero props, VTuber bases, product mockups where you want visual fidelity and will accept multi-MB opaque geometry.
Lane B — Procedural / code-first
Primitive Lab (parametric sliders → live mesh rebuild) plus agent harnesses like img2threejs for photo → procedural factory when you need:
- Editable TypeScript you can patch in a PR
- Animation-ready hierarchy (pivots, sockets, colliders via
sculptRuntime) - Diffable specs for teammates and CI
- Deterministic seeds aligned with Game Lab JSON recipes
bunpav's browser studio is Three.js-native. Procedural factory output can load in-scene before optional GLB export — the code path is not an afterthought bolted onto a mesh viewer.
When to pick which lane
| Need | Prefer |
|---|---|
| Hard-surface crate with hinge socket + collider | img2threejs procedural lane |
| Battle-worn organic gauntlet from one concept sketch | Neural credits lane |
| Twelve palette variants of the same pickup | Primitive Lab sliders |
| Seeded level + props in one afternoon | Game Lab + procedural props + optional neural hero |
This is complementary, not either/or — the same jam team might img2threejs a treasure chest (animation sockets for lid open), neural-gen a boss creature, and parametric-tune twelve barrel variants in Primitive Lab.
Workflow for indie devs and game jams
48-hour jam sketch:
- Greybox in Game Lab with a fixed seed → export JSON for teammates.
- Hero prop from reference photo → run img2threejs locally; drop factory into bunpav or your Three.js build.
- Repeatable pickups → Primitive Lab sliders → GLB export.
- SFX layer → Audio Lab MP3 (credits) per bunpav guide.
Solo dev maintaining a live game: keep ObjectSculptSpec JSON in git next to the factory — when art direction shifts (gold trim → emissive runes), refine-spec beats re-prompting a neural mesh from scratch.
Agent shop setup: install img2threejs beside other skills from the explainx.ai registry; treat grimoire/ rubrics like Kaggle procedural-memory tiers — Read-only spec review before Action-allowed codegen.
img2threejs vs alternatives (July 2026)
| Approach | Output | Editable? | Animation hooks | Single photo |
|---|---|---|---|---|
| img2threejs | TS factory + JSON spec | Git-diffable | sculptRuntime sockets | Yes (hard-surface) |
| bunpav neural photo-to-3D | Textured GLB | Limited | Auto-rig path (credits) | Yes |
| bunpav Primitive Lab | Parametric GLB | Sliders only | Basic | N/A (no photo) |
| Meshy / Tripo | GLB | Low | Varies | Yes |
| Blender manual | Blend/GLB | Full | Full | Reference only |
img2threejs is not a replacement for Blender on film assets. It is a credible agent-native path when code ownership matters as much as pixels.
What people are asking (issues-shaped)
"Can I use this without Claude Code?" — Yes. README targets Codex and OpenCode too; swap "agent vision" for whatever browser/screenshot tool your host provides.
"Is v1.2 character mode production-ready?" — Treat it as stylized reconstruction with anatomy landmarks — not MetaHuman. Likeness-max (v1.3) adds per-region confidence reporting.
"Why not just export GLB from the skill?" — v1.4 plans glTF; until then the value is live factory code in your scene graph. For jam teams that already export GLB from bunpav, run img2threejs when sockets matter more than triangle soup.
"PR #9 broke my fork?" — Scripts moved to forge/stage*; update paths and re-read CONTRIBUTING.md.
Summary
img2threejs (~633★, MIT, v1.2.0) rebuilds one reference photo as pass-gated procedural Three.js — ObjectSculptSpec, TypeScript factory, sculptRuntime animation hierarchy — for roughly ~80k–180k tokens per hard-surface object (TOKEN_COST.md). The July 20, 2026 forge//grimoire/ refactor (PR #9) formalizes stage scripts and rubrics.
bunpav does not publicly brand img2threejs, but the architecture fits: neural credits for organic hero meshes, Primitive Lab for parametric variants, img2threejs for photo → editable code when rigging sockets and diffs beat opaque GLBs. See the bunpav labs guide for pricing and exports. The same render-then-repair instinct shows up outside agent skills — a July 20 Kimi K3 vs Fable 5 stadium case study argues WebGL agents that screenshot and E2E-test before shipping are doing "vibe engineering," not just vibe demos.
Related on explainx.ai
- How to Build a Hop.Earth-Style AI Driving Game (step-by-step, real-world roads + bunpav assets)
- Pascal Editor — open-source 3D buildings (pair with bunpav for AI props)
- Did Opus 5 one-shot Call of Duty? Claude of Duty
- Kimi K3 vs Fable 5 — vibe engineering on a WebGL stadium — self-verifying agents that screenshot Three.js before shipping
- bunpav — procedural 3D, Game Lab, Audio Lab beta
- What are agent skills? Complete guide
- How to build your first agent skill
- Kaggle agent skills whitepaper — procedural memory
- NVIDIA SIGGRAPH 2026 — Blender MCP, Omniverse agent tools, neural rendering keynote
- LingBot-Map — streaming 3D reconstruction
- AI token costs — enterprise governance
- Generate images with Claude Code + OpenAI skill
- Roblox Build — prompt-to-game on mobile
Official: img2threejs GitHub · Showcase gallery · TOKEN_COST.md · bunpav.com
Star counts, pipeline stages, token estimates, and bunpav product surfaces reflect public sources as of July 20, 2026. img2threejs token figures are maintainer estimates — run a dry-run on your object class before budgeting a production sprint. Confirm bunpav credit pricing and commercial terms on bunpav.com before shipping paid titles.