# img2threejs

> Rebuild an object from one reference image as procedural Three.js code, not a mesh

- Category: Multimodal Generation / 3D & CAD Generation
- Language: TypeScript
- Licence: Apache-2.0
- Repository: https://github.com/img2threejs/img2threejs
- Website: https://img2threejs.io/
- Canonical page: https://ai-tldr.dev/tools/img2threejs/

## In short

img2threejs takes a single reference image of an object and produces a TypeScript factory that returns a `THREE.Group` recreating that object from primitives, procedural shaders and generated geometry. It sits in the 3D & CAD Generation category of the Multimodal Generation tools and is open-source, written in TypeScript and licensed Apache-2.0.

## Overview

img2threejs takes a single reference image of an object and produces a TypeScript factory that returns a `THREE.Group` recreating that object from primitives, procedural shaders and generated geometry. The output is code rather than a mesh file — no photogrammetry, no mesh extraction, no downloaded art packs — and it carries a runtime hierarchy of pivots, sockets and colliders so the result can be animated instead of sitting inert.

It runs as a skill inside a coding agent — Claude Code, Codex or OpenCode — and is deliberately agent-agnostic: wherever its documentation calls for agent vision or an agent browser tool, it uses whatever the host provides, whether native image reading, a browser MCP, the project preview or a screenshot you supply. Work proceeds through a staged sculpting pipeline (blockout → structural → form → material → surface → lighting → interaction → optimization) in which each pass is generated, vision-reviewed against the reference and self-corrected until every identity-defining feature clears its threshold. Deterministic Python scripts do the validation and gating, so model tokens are spent on visual judgement and code rather than bookkeeping.

Subjects are classified as object, character or hybrid, with characters routed through an anatomy-aware track and objects through a hard-surface pipeline. Before any code is generated the pipeline enumerates a `detailInventory` of identity-defining small details — gloss, bevels, screws and rivets, engraved linework, contours, stains and wear — and a strict-quality gate blocks generation until every entry maps to a real component or material. Domain knowledge lives in installable plugins rather than the core checkout, and the project is candid about its ceiling: a single image cannot reveal hidden sides, unseen faces are inferred by mirroring visible ones, and "this cannot reach the requested fidelity from this image" is treated as a valid result.

## What it does

- Turns one reference image into a TypeScript `createObjectNameModel(spec, options)` factory returning an animation-ready `THREE.Group`
- Staged sculpt pipeline — blockout, structural, form, material, surface, lighting, interaction, optimization — with a vision review and self-correction at each pass
- Required `detailInventory` pass plus a strict-quality gate that blocks code generation until every identity-defining detail maps to a real component or material
- Object, character and hybrid subject tracks, with characters routed through an anatomy-aware pipeline and skinned-mesh rigging data on `root.userData.rig`
- Domain plugins installed through the `img2` harness (`img2 install / add / doctor`), including CS2 weapon skins, animated characters and a GLB emission target
- Resumable multi-session workflow: `forge/state.py` records an evidence-backed checklist and `forge/next.py` picks the reconstruction back up
- Optional multi-view silhouette carving that records unseen areas as low-confidence instead of inventing hidden detail

## Getting started

img2threejs installs as a skill in your agent's skills directory and is invoked from the agent with a reference image. If you use more than one host, keep one checkout and symlink each host's entrypoint at it so they cannot drift apart.

1. Install it as a skill

   Clone the repository straight into your skills directory.

```bash
git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs
```

2. Add domain plugins (optional)

   Domain knowledge lives in installed plugins, not in the checkout. Install the img2 harness once, then add plugins to it. With no plugins installed, the `generic` and `character` profiles are available; asking for a profile whose plugin is missing fails loudly rather than silently downgrading.

```bash
npx github:img2threejs/img2 install   # ~/.img2, the plugin registry, and an `img2` launcher
img2 add img2threejs/plugin-cs2       # clone @ newest tag, pin SHA, link host skills
img2 doctor                           # fail-loud static audit of every installed plugin
```

3. Invoke it on an image

   Attach or point to an object image in your agent and run the skill. It classifies the subject, runs the detail inventory and gates every pass on its own.

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

4. Resume a multi-session reconstruction

   Create a local state index first, then let `next.py` resume from the recorded checklist while the spec, render and review gates stay authoritative.

```bash
python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json
```

5. Collect the output

   You get an `ObjectSculptSpec` JSON with the component tree, materials, repetition systems, sockets and per-pass review history; the TypeScript factory, whose `root.userData.sculptRuntime` exposes nodes, sockets, colliders and destruction groups; and render plus comparison sheets documenting fidelity at each pass.

```text
object-sculpt-spec.json      # component tree, materials, sockets, review history
createObjectNameModel.ts     # THREE.Group factory
# plus render and comparison sheets per pass
```

## When to use it

- Recreate a product, prop or weapon from a single reference photo as editable, diffable code instead of an opaque mesh file
- Produce animation-ready 3D assets whose pivots, sockets and colliders are already wired up
- Keep a web 3D scene token-efficient and download-free by shipping generated geometry code rather than model files
- Add a domain of your own — its checklist steps, quality floors and blocking review gate — by writing an img2 plugin
