img2threejs: Photo-to-Procedural Three.js Skill — and How bunpav Uses the Code-First Lane
hoainho/img2threejs (~633★, MIT) rebuilds one reference photo as pass-gated procedural Three.js TypeScript — ~80k–180k tokens/object. explainx.ai on bunpav's neural vs code-first 3D lanes, animation sockets, and honest limits.
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.
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:
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 stop outcome — 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)
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.
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, 2026forge//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.
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.
