img2threejs does not output a mesh file. Point it at a reference image and it rebuilds the object shown there as a THREE.Group factory written in TypeScript, built from primitives, procedural shaders, and generated geometry. What you get back is source: readable, diffable, and editable by hand when the render is nearly right.
The project calls this reconstruction-by-code, and it is explicit that it is not photogrammetry, mesh extraction, or a downloaded art pack. Every model in the public showcase gallery is generated code running in the browser, with the source linked next to it. You can orbit the model, inspect its reference image, and read the function that produced it.
The pipeline is a ladder of gates
The interesting engineering is not the code generation. It is the refusal to let a pass advance.
A run moves through a fixed order: blockout, structural-pass, form-refinement, material-pass, surface-pass, lighting-pass, interaction-pass, optimization-pass. A pass unlocks only after the previous one has been reviewed and accepted, and acceptance means something specific: a real render, a side-by-side comparison sheet against the reference, an agent-vision score at or above threshold, and every identity-defining feature clearing its own threshold.
Before any code is generated the pipeline enumerates a detailInventory of the small things that make an object recognizable: gloss, bevels and rounding, screws and rivets, engraved or painted linework, contours, stains and wear. Each detail has to map onto a real component or material entry. A strict-quality gate blocks generation until the inventory is complete, and blocks a single-root spec for a compound object.
The CS2 knife and Glock-18 routes go further, with family-specific component contracts plus component-coverage and map-stripped blockout gates, which exist to stop a convincing texture from standing in for structure that was never built. Those reviews record exactness tier, family identity, painted-region and projection coverage, and per-region confidence.
After each pass the agent picks exactly one action: continue, refine-spec, refine-code, request-input, or stop. The split between refine-spec and refine-code is a small design decision that pays off in debugging, because it separates "the plan was wrong" from "the plan was fine and the geometry missed it".
Animation-ready is a claim with a definition
Plenty of tools produce a static shape. img2threejs treats a runtime hierarchy as part of the acceptance criteria: the model exposes pivots, sockets, colliders, and destruction groups through root.userData.sculptRuntime, and an attachment-correctness gate makes child parts declare how they join their parent so handles, limbs, and tubes do not float in mid-air. That is what the project means when it says the output is ready to animate rather than an inert lump.
Subjects are classified as object, character, or hybrid, and characters route through an anatomy-aware track with head-unit proportions and facial landmarks. For likeness work there is an opt-in path that fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. The README does not oversell it: a single image cannot guarantee full likeness, so the pipeline reports per-region confidence and asks for more views when the image cannot show what matters.
Where it fits
It runs as a skill under Claude Code, Codex, or OpenCode, and it is deliberately agent-agnostic. Wherever the docs mention agent vision or an agent browser tool, it uses whatever the host provides: native image reading, a browser MCP, the project preview, or a screenshot you supply. The tooling itself is Python 3.10 or newer using only the standard library, so there is nothing to install beyond cloning the folder into a skills directory. License is Apache-2.0.
The project describes itself as deliberately token-efficient, though it publishes no measurement of that, so treat it as the authors' framing rather than a result. The part you can check by reading the repository is the review loop: the agent's own vision, scored against a side-by-side sheet, is the only thing allowed to approve a pass. For anyone who has watched an agent spend a long context window nudging a 3D asset it cannot see, that is the idea worth stealing.
GitHub: https://github.com/img2threejs/img2threejs
Curated by Agent Palisade — practical AI for small and mid-sized businesses.
Top comments (0)