/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.4.4

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.

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 <spec>` first, or `python3 forge/next.py --state .img2threejs/state.json`.** The state form reports the ordered local checklist, exact next command, evidence status, and bounded correction-loop status; it never replaces the spec/pass gates. 1. **Use local state first.** Initialize it once, then run `python3 forge/next.py --state .img2threejs/state.json [<spec>]` at every start/resume and before every correction iteration. 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. 3. **Spec** it: component hierarchy, materials, lighting, pivots, sockets, action anchors. 4. **Build pass-by-pass** from blockout → structure → form → material → lighting → interaction → optimization. 5. **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.

Resumable local workflow

For a cross-agent or multi-session reconstruction, initialize the local state before intake:

python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json
python3 forge/next.py --state .img2threejs/state.json
python3 forge/state.py mark image-analysis --evidence analysis.md

`generic`, `character`, and `cs2` profiles insert their required intake gates in order. Every completed step needs evidence; every skipped step needs a reason. The state file is a resumability index, not visual evidence: renders, specs, review history, and deterministic gates remain the authoritative artifacts.

Transparency and Process Debugging (Critical — from Bowie Knife reconstruction)

**The problem:** When the user cannot tell what was done or where something went wrong, they cannot debug the process. Over-claiming (reporting success when features still don't match) destroys trust and makes iterative improvement impossible.

**Rule:** Be transparent + don't over-claim. State exactly what changed each pass, with evidence, and name what still doesn't match:

• After each pass, explicitly list what changed: "Updated guard shape to extend left edge from -0.56 to -0.48 for handle overlap"
• Provide evidence: reference the specific values, coordinates, or parameters that changed
• Name what still doesn't match: "Handle silhouette traced but still flat plane (no Z palm-swell), procedural crosshatch not reference's exact dot-grid knurl"
• Explain why a change was made: "Extended guard left edge because handle ends at X=-0.42 and guard ended at X=-0.20, causing visual gap"
• Never claim a feature is "done" when it's only "improved" — use precise language
• When a gate passes but visual inspection shows issues, explain the limitation: "2D gate passed (fidelity 0.83) but three-quarter render shows blade reads as toy (no grind wedge) — 2D gates are blind to 3D realism"

**The user needs to be able to debug the process, not just the output.** If something is wrong, they should be able to trace which decision led to the error and correct it. Opaque processes force restarts; transparent processes enable refinement.

Transparency and Process Debugging

Report what changed each pass with evidence (exact values/coordinates), name what still doesn't match, and never claim "done" when only "improved". A passing gate is not proof of 3D realism. Full rule + examples: `grimoire/review/self_correction.md`.

GLB-mediated v2 render-fidelity track (1.5 alpha)

When the user supplies a GLB as an intermediate reference, use the browser-rendered GLB as the structural and visual baseline, then author an independent procedural factory. The raw GLB is never pixel evidence and its topology/materials are never copied into the factory.

Before any factory edit:

1. Run `forge/stage1_intake/probe_glb.py` and inspect `semanticDecomposition`. A merged one-node/one-mesh/one-primitive/one-material asset is `insufficient` for reliable semantic labels; connected-component/curvature/normal/UV segmentation is hypothesis evidence only. Request a multipart GLB or capture a browser seman