img2threejs

Overview

img2threejs is an open-source image-to-3D project that reconstructs the object in a reference image as a procedural Three.js model written in TypeScript. It generates a THREE.Group factory from primitives, procedural shaders, and generated geometry, adding a runtime hierarchy of pivots, sockets, and colliders so the model is ready to animate. The gallery shows live code-only demos running in the browser, and the project uses deterministic Python scripts for validation and gating while model tokens are reserved for visual judgment and code generation.

Key Features

• Generates TypeScript THREE.Group factories from a single reference image using primitives, procedural shaders, and generated geometry rather than mesh files.
• Runs a staged sculpting pipeline from blockout through optimization, with vision-reviewed passes and self-correction until identity-defining features clear their thresholds.
• Supports object, character, and hybrid subjects, including an anatomy-aware character track and optional likeness and multi-view silhouette workflows.
• Includes deterministic Python scripts for image probing, spec validation, material evidence, pass orchestration, rendering review, and strict-quality gating.
• Uses a detail inventory and strict-quality gate to map identity-defining details to real components or materials before code generation.
• Works with Hermes, Claude Code, Codex, or OpenCode and can be extended through domain plugins such as character, cs2, environment, hello-cube, and img2glb.

Use Cases

• Rebuilding a photographed object or character as an animation-ready Three.js model for browser-based 3D scenes.
• Studying procedural modeling examples and generated source in the live demo gallery.
• Adding domain-specific reconstruction workflows for CS2 weapon skins or rigged characters through plugins.
• Experimenting with an agent-driven, token-efficient image-to-3D pipeline.

Getting Started

• Install Node.js 18 or newer, Git, Python 3.10 or newer, and one supported agent such as Claude Code, Codex, OpenCode, or Hermes.
• Run npx --yes img2threejs@latest install to link the skill into every agent it finds.
• Run npx --yes img2threejs@latest doctor to check managed installations.
• Restart the agent and invoke the img2threejs skill with a reference image and a request to rebuild the object as a procedural Three.js model following the quality gates.
• Optionally install the img2 harness with npx --yes @img2threejs/img2@latest install --yes and add only the plugins you need, such as character or cs2.

Deployment & Requirements

• Node.js 18 or newer, Git, and Python 3.10 or newer.
• One of Claude Code, Codex, OpenCode, or Hermes as the agent host.
• Python scripts use only the Python 3.10+ standard library and require no additional packages.
• Plugin workflows require the separate img2 harness; the private environment plugin additionally requires authorized GitHub access.

Before You Adopt

• License: Apache-2.0. Review its terms before using, modifying, or distributing the project.
• Running the installer or doctor does not prove visual likeness or animation quality; the reconstruction's render and domain gates must pass.
• The private environment plugin is not publicly accessible; it requires authorized GitHub access and working Git credentials.
• Installing the skill alone does not perform a reconstruction; the agent must validate the image, write an assessment and spec, generate the factory in passes, and review rendered comparisons.