/img2threejs

name: img2threejs
description: Turn an object or character reference image into a quality-gated, animation-ready procedural Three.js model built in code. Use for image-to-3D reconstruction, detail-accurate object rebuilds, stylized/likeness-maximized human characters, sculpt specs, and staged code generation.
license: Apache-2.0
version: 2.0.1

img2threejs — Image to procedural Three.js

Rebuild the object visible in a reference image as a **code-only** procedural Three.js model, gated by a staged sculpting pipeline and an AI-vision self-correction loop. This is reconstruction-by-code, **not** photogrammetry, mesh extraction, or downloaded art packs. That promise governs how the model is *built* — it says nothing about which file formats it can subsequently be *exported* to; an explicitly-selected emission target (`--target <kind>`) is a terminal, whole-artifact transform of the already-built model, verified to its own stated limit, never a second way to build one.

Agent-agnostic: works under Hermes, Claude Code, Codex, or OpenCode. Wherever this doc says "agent vision" or "agent browser tool", use whatever the host provides — native image reading, a browser MCP (playwright/chrome-devtools), the project preview, or a user-supplied screenshot.

This file is the always-loaded router: it holds the order of operations and every hard rule as one line. The full contract behind each rule lives in the `grimoire/` or `docs/` file that rule names — read the named file at the moment you reach that stage, not before.

Canonical shared checkout

Keep one checkout of this repository and let every host enter it through a symlink, so the hosts execute the same code instead of drifting apart. `npx --yes img2threejs@latest install` does this for the hosts it detects (`hermes`, `claude`, `codex`, `opencode`); it refuses (exit 2) to replace a link it does not manage, so a hand-made link is never silently swapped for a release copy. **Hermes** reads skills per profile: also link `~/.hermes/profiles/<profile>/skills/img2threejs` (the installer writes only `~/.hermes/skills/`). Install, manual symlinks, and troubleshooting: [`docs/INSTALL.md`](docs/INSTALL.md).

When To Use

The user attaches/points to an object image and wants a procedural Three.js model, a reconstruction/animation/destruction plan, a sculpt spec, or code. Also for material studies, action-ready props, game objects, botanical/mechanical parts, and stylized reconstructions.

Profile preflight (once per run, before `forge/next.py`)

Domain knowledge (CS2 skins, animated characters, emission targets) lives in plugins, not in this checkout. Pick the profile from the subject, then confirm this environment can start it:

python3 forge/state.py init --help | grep -- --profile   # profiles available here

• `generic` / `character` are built in: no harness, no plugin, nothing else to check.
• A missing domain profile (e.g. `cs2`) is a setup gap: never downgrade to

`generic` silently. Installing it edits the user's machine, so give them the commands in [`docs/INSTALL.md` §3](docs/INSTALL.md#3-add-a-plugin-only-if-you-need-one), get their go-ahead, re-check, and continue.

• Installed but not listed (wrong `$IMG2_HOME`), or a Hermes plugin link: [`docs/PLUGINS.md`](docs/PLUGINS.md).
• Then read what the profile's own steps name, at the moment you reach them: the plugin's

`SKILL.md` and contracts govern that domain.

Core Promise

Sculpt from a photo, in order — never one-shot a mesh: 1. **Run `python3 forge/next.py --state .img2threejs/state.json [<spec>]` first**, at every start, resume, and before every correction iteration. It reports the ordered checklist, exact next command, evidence status, and bounded correction-loop status; it never replaces the spec/pass gates. Obey a hard stop; never continue from memory. 2. **Validate** the image is a suitable 3D target (`grimoire/intake/validation_rubric.md`). 3. **Assess** object class + complexity, then write a `qualityContract` before any code. 4. **Spec** it: component hierarchy, materials, lighting, pivots, sockets, action anchors. 5. **Build pass-by-pass** from blockout → structure → form → material → lighting → interaction → optimization. 6. **Verify** each pass with a screenshot compared against the reference; fail a pass if an identity-defining feature is wrong even when the global score looks fine.

State explicitly when output is approximate/stylized/low-poly. A single image cannot reveal hidden sides or guarantee exact geometry — say so instead of faking confidence.

Mandatory Local State Gate

Conversation context is disposable; `.img2threejs/state.json` is the local checklist authority. Initialize once per reconstruction, then gate every step through it:

python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|character|installed-domain> --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>

• `next.py` prints the current step, pass, incomplete mandatory steps, exact next command, and

`loop/max`. Exit code 3 or `status=stopped` is a hard stop: report the reason and request input. Never bypass it by reconstructing progress from chat history.

• Every completed step needs evidence; mark a non-applicable step `skipped` only with `--reason` —

silent omission is forbidden. Loop counts derive from `reviewHistory` actions (`refine-spec`/`refine-code`), not agent memory. Defaults: 3 corrections per pass, 6 total.

• A domain profile's steps, gates and reference material come from the **registry**: in-repo

modules (`character`) and installed plugins (e.g. `cs2`) register identically, and `forge/state.py init` names what is available. A profile adds mandatory gates without changing the core order -- a domain plugin typically requires an autho