img2threejs: a procedural Three.js model generator that reconstructs objects from reference images using code-only geometry

What it solves

img2threejs converts a single reference image of an object, character, or creature into a procedural Three.js model. Unlike photogrammetry or mesh extraction, it generates code-only models using primitives and shaders, ensuring the results are lightweight, animation-ready, and run directly in the browser without requiring external mesh files or art packs.

How it works

The project uses a staged sculpting pipeline that transforms an image into a technical specification, then iteratively builds the model through several passes: blockout, structural, form, material, surface, lighting, interaction, and optimization.

It is designed to be agent-agnostic, running within AI coding agents like Claude Code, Codex, or OpenCode. The pipeline uses deterministic Python scripts for validation and quality gating, while the AI agent handles visual judgment and code generation. For characters, it employs an anatomy-aware track with parametric templates and landmark fitting to maximize likeness.

Who it’s for

Developers and 3D artists who need to quickly generate browser-based 3D assets from images, specifically those looking for procedural, code-driven geometry rather than static meshes.

Highlights

  • Code-Only Reconstruction: Generates TypeScript factories that create models from primitives and procedural shaders.
  • Animation-Ready: Produces a runtime hierarchy with pivots, sockets, and colliders for immediate animation.
  • Detail-First Analysis: Uses a strict quality gate that requires a complete inventory of identity-defining details (like bevels, rivets, and wear) before generation begins.
  • Subject-Specific Pipelines: Includes dedicated tracks for hard-surface objects, humanoid characters, and creatures (quadruped, avian, etc.).
  • Detailed Review Gates: Implements rigorous checks, including CS2-specific weapon contracts and CIEDE2000 color math for accuracy.

Sources