img2threejs: When Image-to-3D Becomes Code-to-3D

A zero-dependency pipeline turns a single image into procedural Three.js factories, so AI agents can rebuild, inspect, and refine 3D objects as source code instead of opaque meshes.

9 min read • View on GitHub • More from hoainho

A wide desk split into two systems. On the left, a sealed opaque cube sits beside unreadable binary fragments, while on the right, stacked TypeScript sheets and Three.js primitives assemble into a small mechanical object with visible pivots and hierarchy lines. The scene explains that this project translates an image into a program, not a mesh file.
The central inversion is simple: the output is legible code, not a black-box asset.

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

hoainho, Project Creator / Maintainer · hoainho/img2threejs README
Key Takeaways

The model is not a mesh. It is code.

Most image-to-3D tools try to end with a file format: GLB, OBJ, maybe a tidy export for another pipeline. img2threejs takes the opposite route. It turns a reference image into TypeScript that builds the object at runtime with Three.js primitives, grouped hierarchies, and procedural hooks.

That shift matters because code is inspectable. An LLM can read it, patch it, and try again. A mesh is just an opaque blob with triangle count anxiety.

A WSJ hedcut-style portrait of hoainho, rendered from a verified GitHub avatar. The portrait gives the article a human anchor while keeping the visual language consistent with the editorial treatment.

Why agents need 3D as source code

The project’s core argument is practical. Coding agents reason in text, not in hidden geometry. If the output is procedural code, the same model that wrote it can also inspect it, compress it, refactor it, and generate variations without ever crossing a file-type boundary.

FormatWhat the agent seesHow easy it is to editBest use
Binary meshTriangles, buffers, opaque exportLowShipping assets after the fact
Procedural TypeScriptReadable functions, groups, pivots, materialsHighIterating with coding assistants
Visual editor outputScene graph hidden behind a UIMediumDesigner-led composition

This is why the comparison is not really about image-to-3D quality. It is about media. Mesh generators produce objects. img2threejs produces instructions.

The pipeline is staged on purpose

The system is not magic. It is a sequence of checks that tries to preserve enough evidence for the model to write the right code.

The engine room lives in forge/. The first pass probes the image at a low level, then scaffolds landmarks, estimates camera pose, extracts evidence for lighting and materials, and only then moves toward code generation. The point is not speed. The point is discipline.

A close-up of an open grimoire page on a drafting table. The page contains structured notes about geometry patterns, likeness rules, and validation steps, while a compass, ruler, and small Three.js object are linked to the page by thin lines. The image explains that the repository uses prompt context as an operational instruction set.
The grimoire acts like a field manual for reconstruction, not a passive README.

The grimoire is the real secret

The grimoire/ folder is where the project teaches itself a vocabulary. It is not just a documentation layer. It is the language the agent uses to describe bevels, rivets, hierarchy, likeness, and validation in a way that can be repeated across objects.

That matters because reconstruction fails when the model improvises. A shared prompt language narrows the search space. It gives the system a way to say, "this part is a hinge," instead of vaguely hoping the shape looks hinged.

# Standard-library-only image probing is the kind of constraint that changes the whole toolchain.
# The point is portability in locked-down agent environments.
import struct
import zlib

def read_png_dimensions(path):
    with open(path, 'rb') as f:
        sig = f.read(8)
        if sig != b'\x89PNG\r\n\x1a\n':
            raise ValueError('Not a PNG')
        length = struct.unpack('>I', f.read(4))[0]
        chunk_type = f.read(4)
        if chunk_type != b'IHDR':
            raise ValueError('Missing IHDR')
        width, height = struct.unpack('>II', f.read(8))
        return width, height

The no-dependency constraint is not a gimmick

The repository leans hard on the Python standard library. No Pillow, no NumPy, no OpenCV. That is a real tradeoff, because the parsing code gets more manual, but it also means the pipeline can run in minimal containers and agent environments where installing extra packages is a liability.

For this kind of tool, portability is not a nice-to-have. It is part of the product. If the goal is to let coding assistants reconstruct objects inside a constrained workflow, then the workflow itself has to be as frictionless as possible.

What this beats, and what it does not

Tool classStrengthWeaknessWhere img2threejs fits
Neural mesh generatorsFast, photoreal outputsOpaque, harder to editGood for assets, not code-native iteration
Visual 3D toolsFriendly scene buildingStill centered on UI workflowsUseful for designers, less native for agents
img2threejsEditable, token-efficient, animation-readyNot chasing photorealismBest when the workflow starts in a coding assistant

This is not a claim that procedural code beats every mesh generator. It does not. It is a narrower claim: if the user is an LLM-driven coding agent, the most useful output may be the one it can immediately read back and revise.

The bigger bet: procedural 3D for AI workflows

img2threejs points at a larger format shift. If language models are becoming the interface for creation, then 3D should be generated in a form they can reason about. Not just render. Not just export. Reason.

That is the project’s best idea. It recasts 3D reconstruction as a translation layer between vision and code, and once you see that, the rest of the design choices start to make sense.