img2threejs: rebuild one reference photo as an animation-ready Three.js model in code

The usual image-to-3D route runs photogrammetry, extracts a mesh, or downloads an existing asset. img2threejs takes another path: hand an agent one reference image and it writes TypeScript that recreates the object from Three.js primitives, procedural shaders and generated geometry. The output is diffable code plus a JSON spec, not a multi-megabyte mesh file. The repository had 18,337 stars on October 18, 2026, uses Apache-2.0 and is primarily Python.

Core features

• A factory function, not a mesh: the result is a THREE.Group factory with a runtime hierarchy — pivots, sockets and colliders — so it is ready to animate. Every model in the public gallery can be orbited in the browser beside its reference image, with the generated source a click away.
• Staged reconstruction with self-correction: the pipeline runs blockout → structural → form → material → surface → lighting → interaction → optimization. Each stage generates, renders and visually compares against the reference, looping back until the identity-defining features clear their thresholds. The generator emits only the currently unlocked pass, so the model never re-reads the whole project each round.
• A fail-closed quality gate: before code generation the pipeline enumerates a detailInventory — gloss, bevels, screws and rivets, engraved or painted linework, contours, wear — and maps each item to a real component or material. If the mapping is incomplete the gate returns BLOCKED with the spec, failure metrics, causes and next action instead of writing an approximate model.
• Scripts enforce, the model judges: validation, gating, spec authoring, PBR extraction, comparison-sheet packaging and pipeline state live in Python scripts. The scripts never score visuals; model tokens go to one decision — pass or fail from a single side-by-side sheet. That split is where the project’s token efficiency comes from.
• Routing by subject: each subject is classified as object, character or hybrid. Objects follow a hard-surface pipeline; characters go through an anatomy-aware track with head-unit proportions, facial landmarks and pose. An opt-in projection-first path exists for a specific person, and the README is explicit that one image cannot guarantee 100% likeness — the pipeline reports per-region confidence and asks for more views when it matters.

Typical use cases

• Lightweight 3D on a web page: a product page that wants an orbitable, animatable model avoids loading a large mesh; code models are smaller, versionable and easy to restyle.
• Fast placeholders for game or interaction prototypes: generate an animatable structure from a reference, confirm proportions and silhouette, then decide whether to invest in production art.
• Teams that need reviewable assets: TypeScript and a JSON spec go through code review, diff and rollback like any other source file.
• Stylised subjects with explicit rules: the repo ships domain plugins such as CS2 weapon skins that encode family identification, painted-region coverage and structural gates as checkable rules.

The boundaries matter too. Installing the skill generates nothing on its own; an agent must run the gated pipeline. Subjective likeness and animation quality are not provable by the doctor commands — only the render comparisons and domain gates speak to those. The private environment plugin needs authorised Git access. Camera, lighting and material inference can still be wrong, and occluded regions get a confidence estimate, not a guarantee. It is also not photogrammetry: “scan this real object” is not the job. Where DrawAI rebuilds a bitmap into editable vector objects, img2threejs rebuilds it into running 3D code.

Quick start

npx --yes img2threejs@latest install --dry-run
npx --yes img2threejs@latest install

The CLI needs Node.js 18+ and Git; the reconstruction scripts need Python 3.10+. The installer detects Hermes, Claude Code, Codex and other hosts; use --host claude to install into just one. Then start a fresh session, attach an image and invoke the skill:

/img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
Keep its proportions, silhouette and colours. Follow the quality gates.
Report the output files, render-review evidence and any inferred regions.

To see the output first, every model in the official gallery is generated code running live in a browser.

Summary

img2threejs suits front-end and game developers who need editable, reviewable 3D output, and teams that want image-to-model inside an engineering workflow rather than as a one-off render. Pushing mechanical work into deterministic scripts and spending model tokens only on visual judgement makes cost and reproducibility more controllable; the trade-off is a longer pipeline that depends on the agent actually honouring the gates. The project was created in July 2026, ships changes frequently (still pushing on October 17), and its README marks some gallery demos as placeholder rather than finished. Apache-2.0, primarily Python, stats checked October 18, 2026.