Reconstruction by Code: Why img2threejs Treats the LLM as a Technical Artist, Not a Mesh Factory

Open the live demo gallery for img2threejs and the first thing you notice is what is missing. There are no download buttons for GLB files, no wireframe statistics counting triangles, and no texture atlases. Instead, you get a browser-rendered Sony WF-1000XM3 earbud case, a 12-gauge shotgun, and a crowned loot chest, each orbiting smoothly under your cursor. Click through, and the source is right there: not a mesh, but a TypeScript factory function that assembles the object from Three.js primitives, procedural shaders, and generated geometry. The model is the code, and the code is the model.

This is the central conceit of hoainho’s img2threejs, a project that has quietly accumulated nearly fourteen hundred stars and a spot in AI agent skill marketplaces. At a time when image-to-3D usually means uploading a photo to a cloud service and receiving an OBJ or a textured GLB minutes later, img2threejs asks a different question. What if the most useful artifact an AI can produce is not a mesh file, but a build script?

The Hype Moment: Agent Skills and the Return of Proceduralism

The attention spike around img2threejs is inseparable from the current moment in AI tooling. The repository is packaged as an agent-agnostic skill for Claude Code, Codex, and OpenCode, designed to slot into the emerging ecosystem where large language models operate inside development environments with vision and browser tools. It arrived when developers were looking for serious, repeatable workflows that could consume an agent’s visual reasoning without burning through context windows on mechanical bookkeeping.

The project’s demos are deliberately hard-surface objects—earbuds, shotguns, knives, a Doraemon house diorama—reconstructed with correct proportions, bevels, gold trim, and emissive emblems. These are not photogrammetry scans, nor are they extracted meshes run through a decimation algorithm. They are code-only reconstructions, rebuilt from primitives in a staged pipeline that the README calls, with refreshing precision, reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs. That distinction matters because it defines what the user actually receives: a diffable, version-controllable TypeScript module that returns a Three.js Group with a full runtime hierarchy of pivots, sockets, colliders, and destruction groups.

The Sculpting Pipeline: Gated Passes and Agent Vision

Where img2threejs diverges most sharply from the one-click mesh generators offered by Meshy, Sloyd, or Spline is in its process. The project treats 3D reconstruction not as an inference problem but as a sculpting discipline with eight locked passes: blockout, structural, form-refinement, material, surface, lighting, interaction, and optimization. A pass unlocks only after the previous one has been rendered in a browser, packaged into a side-by-side comparison sheet against the reference image, and approved by agent vision.

This is project management disguised as software architecture. Before any Three.js code is emitted, the pipeline runs a suitability gate, a pre-spec assessment that classifies the object and writes a quality contract, and a strict-quality validation that blocks shallow specifications. The model must enumerate a detail inventory of identity-defining features—gloss, bevels, screws, engraved linework, wear stains—and map each one to a real component or material entry. If the inventory is incomplete, the gate refuses to proceed. The result is a fail-fast system that prevents the expensive mistake of generating geometry from an underspecified brief.

The self-correction loop is equally disciplined. After each pass, the agent chooses exactly one action: continue, refine-spec, refine-code, request-input, or stop. There is no casual regeneration of the entire model. The code generator emits only the currently unlocked pass, so the model never wastes tokens re-reading or re-writing geometry it has already approved. The README is explicit about the division of labor: Python scripts enforce pipeline state and validation; the model’s tokens are reserved solely for looking at a single comparison sheet and rendering a pass-or-fail judgment.

Token Economics: The Boring Part That Matters

The img2threejs README contains an unusually frank section on token efficiency, and it is here that the project’s engineering personality comes through. Every orchestration script is pure Python 3.10+ standard library. There are no pip installs, no Pillow, no NumPy, no Playwright. PNG read and write operations are handled with struct and zlib. The authors have stripped the tooling down to the bone so that nothing to install means nothing to debug in-context.

This austerity serves a strategic purpose. Most image-to-3D agent loops burn context windows on mechanical work: re-reading entire model files, hand-validating JSON, re-running steps already completed. img2threejs pushes all of that into deterministic scripts and spends model tokens only where judgment is actually required. The output is text—an ObjectSculptSpec JSON and a TypeScript factory—rather than multi-megabyte binary meshes. For teams running agent loops against metered API access, this is not a minor optimization. It is a structural reallocation of compute cost from the model to the runtime environment.

Hard Surfaces and Honest Limits

The project is strongest on hard-surface objects, and its authors are upfront about where the pipeline falters. A single reference image cannot reveal hidden sides, so unseen geometry is inferred by mirroring visible faces rather than hallucinating detail. The README states plainly that output may be approximate, stylized, or low-poly, and that a failure to reach requested fidelity from a single image is a valid, expected result. Characters are currently stylized reconstructions routed through an anatomy-aware track with head-unit proportions and facial landmarks; photorealistic likeness is explicitly deferred to a future projection-first path with per-region confidence reporting.

This honesty is rarer than it should be in the current landscape. Competitors like Meshy promise fully textured models in about a minute with up to 600K faces and PBR-ready texture maps. Sloyd offers clean OBJ exports for game engines and 3D printing. Spline generates variants from text and images inside a visual editor. These tools optimize for immediacy and asset volume. img2threejs optimizes for inspectability, animation readiness, and runtime hierarchy. It is less a replacement for a modeler than a replacement for the technical artist who once translated a concept art sheet into a rigged, componentized scene graph.

The Broader Landscape: Code vs. Mesh

Positioned against the field, img2threejs occupies a narrow but significant gap. The academic framework 3Dify, described in a recent arXiv paper, uses LLMs to drive Digital Content Creation tools like Blender and Unreal Engine via the Model Context Protocol or GUI automation. It is procedural in the Houdini sense—node graphs and DCC toolchains—but tied to heavy external software. img2threejs skips the DCC entirely. Its output is a web-native factory that runs in any browser carrying Three.js.

That makes it closer in spirit to procedural generation tools like Houdini or Blender’s Geometry Nodes, yet stripped down for a web runtime and an AI collaborator. Where Houdini’s operators demand years of expertise to master, img2threejs attempts to encode that expertise into rubrics stored in a grimoire folder, letting an agent with vision capabilities execute the sculpting logic pass by pass. The bet is that for web-based games, interactive product configurators, and browser-native AR, a procedural code factory is more durable than a static mesh download.

Where It Goes Next

The roadmap points toward two frontiers that will test this code-first philosophy. Version 1.3 plans to introduce likeness maximization for characters using a projection-first path: camera pose solving, de-lighting, and texture projection onto fitted parametric templates with per-region confidence scores. Version 1.4 targets animation-ready rigs with SkinnedMesh, morph targets, and glTF export. Both milestones introduce tensions. Projection and rigging push the pipeline toward the very mesh-and-texture workflows it currently avoids; glTF export, in particular, would mean emitting binary geometry after all.

Whether img2threejs can retain its identity as a code-only procedural system while absorbing these more traditional 3D pipelines remains an open question. For now, it stands as a compelling argument that the best artifact an image-to-3D system can produce is not a file, but a factory. In a landscape crowded with mesh generators, that is a genuinely different kind of output.