img2threejs/img2threejs

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

What it solves

img2threejs converts a single reference image of an object or character into a procedural Three.js model. Unlike photogrammetry or mesh extraction, it rebuilds the object using code-only geometry, primitives, and procedural shaders, ensuring the result is animation-ready and token-efficient for AI agents.

How it works

The project uses a staged sculpting pipeline that integrates AI agents (like Claude Code) with deterministic Python scripts. The process follows a strict sequence of build passes:

  1. Analysis: The system classifies the subject (object, character, or hybrid) and creates a detailInventory of identity-defining features (bevels, screws, gloss, etc.).
  2. Specification: It authors an ObjectSculptSpec JSON that defines the component tree and materials.
  3. Iterative Sculpting: The model is built in passes (blockout $\rightarrow$ structural $\rightarrow$ form refinement $\rightarrow$ material $\rightarrow$ surface $\rightarrow$ lighting $\rightarrow$ interaction $\rightarrow$ optimization).
  4. Review Loop: After each pass, a Python script generates a side-by-side comparison sheet (reference vs. render). An AI agent reviews the render and decides whether to continue, refine-spec, or refine-code based on a vision score.
  5. Output: The final result is a TypeScript factory function that returns a THREE.Group with a runtime hierarchy (pivots, sockets, and colliders) for animation.

Who it’s for

Developers and technical artists who want to generate 3D assets from images without relying on heavy mesh files or manual modeling, specifically those using AI agents to automate the 3D creation workflow.

Highlights

  • Code-only Reconstruction: Generates TypeScript code instead of binary mesh files, making assets diffable and version-controllable.
  • Agent-Agnostic: Works with any agent that has vision and browser tools (e.g., Claude Code, Codex).
  • Token-Efficient: Offloads mechanical tasks (validation, PBR extraction, comparison packaging) to Python scripts to save model tokens.
  • Animation-Ready: Includes a runtime hierarchy with pivots and sockets rather than producing a static mesh.
  • Strict Quality Gates: Prevents code generation until the specification is sufficiently detailed to match the object's complexity.