/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: 1.5.2

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.

Agent-agnostic: works under 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 Claude and Codex execute the same code instead of drifting apart:

~/.claude/skills/img2threejs -> <your checkout>
~/.codex/skills/img2threejs  -> <your checkout>

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.

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|cs2|character|animated-character> --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.

• Profiles add mandatory gates without changing the core order: `cs2` requires classification,

manifest, and a machine-readable CS2 review before AI review; `character` requires the character contracts and landmark evidence; `animated-character` adds all of `character` plus the nine Stage R steps (`grimoire/readiness/animation_contract.md`). Pick it whenever the rig must MOVE — on `character` the Stage R gates are absent and the build completes without ever running them, which is how animation used to ship broken. Its order is load-bearing: repair the mesh, freeze it, bind additively, then verify parity. Every profile records suitability, projection applicability, and material-evidence applicability. The state file is a resumability index, not visual evidence: renders, specs, review history, and deterministic gates remain the authoritative artifacts.

Required Inputs

• one image path / screenshot / URL / attached image (if missing or unreadable, ask)
• intended use: prop, game object, hero render, playable/destructible object, animation rig

(default: real-time browser prop with interactive performance)

• for a CS2 request, an authoritative classification record (family/subtype and evidence refs) or

an explicit request for the user/vision provider to supply one; heuristic detection alone is not enough to select a geometry adapter

The Loop (scripts do enforcement; agent vision does judgment)

Run scripts from the skill root (`forge/...`). Pure Python 3.10+ stdlib, no pip installs. Full flags: `grimoire/scripts.md`. Never let a script *score* visuals — that is the agent's job.

1. **Analyze the image first** (agent vision, before any script): work the layered observation protocol in `grimoire/intake/image_analysis.md` — identify/classify, decompose macro→meso→micro, map part relationships, name materials in PBR terms, list identity-defining features, and flag what the single view hides. Observation before inference; con