img2threejs/img2threejs

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

What it is

• A skill‑style library that lets a large‑language‑model (Claude, Codex, etc.) take a single picture of an object or character and emit TypeScript code that builds the same thing in Three.js using only primitives, procedural shaders and generated geometry. The output is a THREE.Group factory ready for animation – no mesh files, no downloads.

How it works

1. Intake – the image is fed to the LLM (or any “agent‑vision” tool). The model classifies the subject (object, character, …) and builds a detail inventory of identity‑defining features (bevels, screws, wear, colours, etc.).
2. Spec generation – a deterministic Python script (forge/state.py) records a checklist of evidence and creates a JSON spec describing the geometry, materials and hierarchy.
3. Code synthesis – the LLM generates a TypeScript factory that recreates the spec with Three.js primitives, custom shaders and optionally voxel‑carved silhouettes.
4. Vision‑review loop – after each pass (blockout → structural → material → surface …) the rendered result is compared to the reference; any missing detail blocks progress until the gate is satisfied.
5. Runtime output – the final code runs in the browser, exposing pivots, sockets and userData so the model can be animated immediately.

Key features

• Token‑efficient: only visual judgments and code generation consume LLM tokens; the heavy lifting is done by deterministic Python validation.
• Domain plugins: plug‑in system (plugin‑cs2, plugin‑character, plugin‑img2glb, …) adds specialised checklists and reconstruction rules for particular asset families.
• Quality gates: every detail must map to a real component; the pipeline refuses to “invent” hidden geometry.
• Multi‑view silhouette carving (optional) for voxel‑based hulls when more than one view is supplied.
• Live demo gallery: a public site shows dozens of generated models with source code links.

Typical use‑cases

• Game‑asset pipelines that need lightweight, animation‑ready Three.js models from concept art.
• Rapid prototyping of 3D UI elements or product visualisations without exporting heavy meshes.
• Educational demos of how procedural geometry can approximate real‑world objects.
• Extending AI agents (Claude Code, Codex, OpenCode) with a “rebuild this object” capability.

Getting started

# Clone the skill into your Claude/Codex skills directory
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs

# (Optional) Install the plugin harness and domain plugins
npx github:img2threejs/img2 install          # creates ~/.img2 and the `img2` launcher
img2 add img2threejs/plugin-cs2               # CS2 weapon‑skin rules
img2 add img2threejs/plugin-character         # animated‑character pipeline

Running the skill (inside Claude Code or any LLM that can call a skill):

/img2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.

The skill will:

1. Analyse the attached image,
2. Produce a step‑by‑step spec,
3. Generate the TypeScript factory, and
4. Show a side‑by‑side live preview with the original reference.

Advanced control – you can embed explicit constraints in the prompt to steer the gates, e.g.:

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity   Hold proportions and silhouette, enumerate bevels, seams, fasteners, wear.
Materials  Derive finish and gradient stops from the pixels, flag colours that won’t tone‑map.
Runtime    Expose pivots and sockets for moving parts.

Each line maps to a real validation gate in the pipeline.

Where to see it

• Live demo gallery: https://img2threejs.io/ (each demo links to the generated source).
• Showcase repo: https://github.com/img2threejs/img2threejs-showcase.
• Architecture details: docs/ARCHITECTURE.md in the repository.

License & community

• Apache 2.0.
• Contributions welcome (see CONTRIBUTING.md).
• Sponsored by Atlas Cloud, Tripo, Hyper3D, and a Ko‑fi page.

---

In short, img2threejs is an AI‑augmented pipeline that turns a single picture into clean, animation‑ready Three.js code, with a strong focus on deterministic validation and extensible domain plugins.