img2threejs/img2threejs

img2threejs – Turn a single reference image into procedural Three‑js code

What it is

• A Python‑driven skill that lets large‑language‑model agents (Claude Code, Codex, OpenCode, Hermes, etc.) reconstruct an object or character from a single photo as a THREE.Group factory written in TypeScript. The generated code uses only primitives, procedural shaders and generated geometry – no mesh files or downloaded assets.

Why it matters

• Produces animation‑ready, token‑efficient 3‑D models that can be dropped straight into a Three.js scene. Because the output is code, it stays lightweight, version‑controllable and easy to tweak.
• Built with a quality‑gated pipeline that enumerates every visual detail, validates it against a material registry, and only spends LLM tokens on parts that need visual judgment.

Key features

• Agent‑agnostic skill – works with any LLM that can run a skill (Claude Code, Codex, OpenCode, Hermes). The skill is installed into the agent’s skill store and invoked with a simple prompt.
• Domain plugins – optional extensions for specific use‑cases (character rigging, Counter‑Strike 2 weapon skins, private environment plugin, etc.). Plugins add extra intake contracts, rig checks and review gates.
• Deterministic pipeline – multi‑stage sculpting flow (blockout → structural → form → material → surface → lighting → interaction → optimization) with Python scripts that enforce gates and resume work from a saved state.
• Live demo gallery – a public site (https://img2threejs.io) showcases dozens of reconstructions, each with a link to the generated TypeScript source.
• Open‑source tooling – the core skill lives in this repo, the showcase in a companion repo, and plugins are separate packages that can be added via the img2 harness.

Installation

# Install the skill into every detected agent
npx --yes img2threejs@latest install
# Verify installation per‑agent
npx --yes img2threejs@latest doctor

• Requires Node ≥ 18, Git, and Python ≥ 3.10.
• For Hermes users, link the skill into the active profile as described in the README.

Optional plugin harness

# Install the harness that manages plugins
npx --yes @img2threejs/img2@latest install --yes
# List available plugins
img2 plugins
# Add a plugin, e.g. character rigging
img2 add character --yes

Plugins are not installed by default; pick only those you need.

Running a reconstruction

1. Restart the agent after installation.
2. In the agent chat, attach an image (or give its path) and issue a prompt such as:

   /img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
   Keep its proportions, silhouette and colours. Follow the quality gates.
   

3. The agent will:
   • Validate the image.
   • Build a detail inventory and a spec document.
   • Generate the TypeScript factory pass‑by‑pass.
   • Render the result in a hidden Three.js view and compare it to the reference.
   • Return the generated source files, render‑review evidence and any confidence scores.

Outputs

• A src/model.ts (or similarly named) file exporting a THREE.Group factory.
• A JSON spec describing the hierarchy, materials and any confidence metrics.
• Rendered screenshots used for the visual‑review step.

Documentation & resources

• Architecture & gate design: docs/ARCHITECTURE.md
• Installation guide: docs/INSTALL.md
• Plugin system: docs/PLUGINS.md
• Writing your own plugin: WRITING_A_PLUGIN.md
• Live demo gallery: https://img2threejs.io

License

• Apache 2.0 (see LICENSE).

Who might use this

• Game developers who need lightweight, animatable assets without shipping heavy mesh files.
• Creators of interactive web experiences who prefer code‑first 3‑D models.
• Researchers exploring LLM‑driven 3‑D generation pipelines.
• Anyone who wants a deterministic, quality‑controlled way to turn a photo into Three.js code.