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 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:
- 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.
- Validate the image is a suitable 3D target (
grimoire/intake/validation_rubric.md).
- Assess object class + complexity, then write a
qualityContract before any code.
- Spec it: component hierarchy, materials, lighting, pivots, sockets, action anchors.
- Build pass-by-pass from blockout → structure → form → material → lighting → interaction → optimization.
- 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 (cs2, animated-character from plugin-character) 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 authoritative classification, an intake
manifest, and a machine-readable domain review before AI review; character requires the
character contracts and landmark evidence; animated-character (requires the installed plugin-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)
- when a domain plugin serves the item, whatever authoritative record its intake step requires, 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.
- 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; controlled 3D vocabulary; 3D
object-space not 2D image-space. Then probe local images:
forge/stage1_intake/probe_image.py <image> (metadata only, not a visual check).
1a. Local Spec Search — after image analysis, before writing or refining a spec, pull local
domain evidence (anatomy/PBR/wear/geometry/runtime/physics) rather than inventing it:
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json
(auto-runs BM25 over the core_3d collection, or the collection a declared domain contributes
-- the collection is NEVER guessed from the target name; writes a localSpecSearch bundle that
new_sculpt_spec.py --assessment carries into the spec). Full query-expansion recipe
(bilingual terms, focused search_specs.py retrieval, cache rules):
grimoire/intake/local_spec_search.md. MUST read it before retrying an incomplete or
domain-specific query.
1b. Domain intake — when a domain plugin serves the item, complete its intake steps before
pre-spec authoring (admission, heuristic signal, classification, family/route resolution).
MUST read the contract its step names, completely, before creating the manifest or
running pre-spec assessment.
1c. Optional fidelity evidence adapters — only when they improve an observed weak point; the
stdlib core remains authoritative. Thin/complex masks → local SAM2; character face/pose →
MediaPipe; weak front/back cues → Depth Anything V2
(forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...; every adapter emits
provenance; monocular depth is relative only). MCP-only scene mutations never count as
implementation — write the proven change back to the spec or TypeScript, rebuild, recapture.
Full adapter + MCP routing and authority boundaries:
docs/integrations/reference_fidelity_tooling.md.
- Pre-Spec Assessment Gate — classify + score complexity + write the quality contract:
forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json. Rules: grimoire/intake/quality_contract.md.
Set objectClass.primaryDomain (object | character | hybrid) and fill the seeded
detailInventory (its targetMinDetails scales with complexity). A domain plugin may raise
these floors through its augmentation -- the merge clamps, so a plugin can never lower one
(a skin's finish/wear/hardware IS the item, so such a domain is held to the
top fidelity bar. Author procedural GEOMETRY but route the FINISH through the projection path in
step 2c — a procedural finish for a patterned skin (Doppler/Gamma/Marble/Fade) reads visibly
wrong against the reference. A domain plugin ships its own finish rulebook and texture-acquisition
guide; read what its checklist steps name.
2b. Detail inventory (do not skip for detailed subjects) — scan zones and enumerate every
identity-defining small detail (gloss, bevel, fasteners, linework, contours, stains):
forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json.
Each detail MUST map to a component.localFeatures or material.localOverrides entry — never
prose only. Taxonomy + 3D-term recipes: grimoire/intake/detail_inventory.md.
2c. Projection-first fidelity (characters AND reference-matched surfaces — painted skins,
decals, painted patterns) — when the goal is matching a specific reference's surface, put the
photo's own pixels on the mesh instead of approximating them procedurally. This is the single
biggest fidelity lever; a procedural material for a patterned surface is the #1 reconstruction
failure. Recipe (grimoire/character/likeness_maximization.md — its two levers generalize past
characters): solve the camera (stage1_intake/solve_camera_pose.py → referenceCamera),
de-light the reference (stage1_intake/delight_albedo.py, hard requirement — de-lighting is
what makes projection safe), then project the de-lit crop and bake it into UVs
(stage3_build/bake_projected_texture.py --mesh-id <id>). For a painted skin the projected de-lit
crop IS the finish — no procedural Doppler material. For characters, first capture landmarks
(stage1_intake/extract_landmarks.py --out anatomy.json), fill preSpecAssessment.anatomy,
route grimoire/character/reconstruction.md. A single view cannot show hidden sides — report
per-region confidence and request more views when it matters.
Character sub-routes, in order — decide what parts exist before shaping any, and shape the head
before the hair that sits on it:
- Parts —
grimoire/character/structure_decomposition.md
- Head —
grimoire/character/head_construction.md (what the likeness gate reads against)
- Hair —
grimoire/character/stylized_hair_threejs.md + parameter contract in
grimoire/character/threejs_hair_parameter_contract.json. Lock topology only after the
silhouette review passes: material tuning cannot repair wrong lock topology.
2d. Reference-free humanoid — a generic figure with no reference image has nothing to measure,
so fill anatomy from public canon:
forge/stage2_spec/humanoid_proportions.py <spec> --style-heads 8 --in-place. It writes
anatomy.source: "canon-table" so canon is never mistaken for measurement, refuses to run when
the spec names a reference image, and names anything the corpus does not supply rather than
interpolating it.
- Author the spec from the assessment:
forge/stage2_spec/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --augmentation spec-augmentation.json --domain <profile> --out object-sculpt-spec.json (the checklist step carries the resolved flags).
Replace generic starter featureReviewTargets with the object's real identity-defining
systems (≤5 critical, ≤3 important per pass); for characters add anatomy-proportion,
face-landmark-placement, pose-silhouette, outfit-and-palette. Use 3D-graphics terms only
(grimoire/glossary/3d_vocabulary.md), never "nice/smooth/shiny". Classify every component's
topologyClass/topologyRationale per grimoire/intake/surface_topology.md before picking a
primitive — this is what prevents a continuous organic form from being picked as a box.
- When material fidelity matters and a source image exists, analyze each material's finish then
extract reference PBR evidence, both per crop (verify the crop is on the part you think it is):
forge/stage1_intake/analyze_texture.py <crop> --spec spec.json --material-id <id> --in-place
classifies the finish, extracts the gradient palette, and writes doc-grounded
MeshPhysicalMaterial scalars onto the material. Recipes + Three.js texture/PBR rules:
grimoire/build/threejs_texture_reference.md. Rule of thumb: solid albedo for flat paint,
real reference crop for patterned finishes.
forge/stage1_intake/extract_pbr_evidence.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7.
Confidence < 0.7 is a stop/refine-input signal, not a pass. It is inference, not inverse rendering.
- For multiple named regions:
forge/stage1_intake/material_region_analysis.py --manifest regions.json --out-dir material-evidence --out material-analysis.json,
resolve each assignment from docs/materials/material-reference.json, wire it in with
forge/stage2_spec/apply_material_analysis.py.
- Emit the controlled material camera/crop contract (
forge/stage4_review/material_views.py),
compare visible-footprint crops (material_comparator.py), apply only bounded material-scoped
corrections (material_feedback.py), and record the blocking result (material_gate.py).
- Validate, then strict-validate before generating code:
forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json then --strict-quality.
Strict blocks shallow specs (a complex object with one root, no repetition systems, no
local overrides, no micro groups is NOT implementation-ready even if JSON validates).
- Locked build passes — only touch the currently unlocked pass:
forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json
forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts
The generator is fail-closed: strict-quality must pass before it writes any factory, and a
future --pass-id fails until prior passes are reviewed continue. If blocked, preserve the
BLOCKED artifact and refine the subject-specific spec; do not substitute a generic template.
The local state adds --force only for a new pass or refine-spec; refine-code edits the
current artifact without regenerating it. Before overwriting, carry valid hand refinement back
into the spec; generated code must not be the only copy of reconstruction decisions.
6a. Hitting a triangle budget. performanceBudget.targetTriangles selects a tessellation tier
for every primitive with segment counts (low ≤6k, standard ≤60k, else hero) and caps
implicit-surface sampling grids. Where a tier is not precise enough, add
geometryDescriptor.decimate: {"targetRatio": 0.4} to that component — a quadric collapse in
the generated factory, run before skin binding so weights are computed on surviving
vertices. It keeps position only (normals recomputed), so it is refused on an
authored/unwrapped uvStrategy. Offline LOD tiers:
forge/stage3_build/decimate.py <mesh.json> --ratio <r> --json.
- Render the current pass in a browser/preview, capture a screenshot at a review viewpoint.
7a. Off-axis and placement gates — a single review viewpoint is not evidence about the model.
Capture a turntable, not one frame, and run all three; each catches a defect class the older
gates pass by construction (a hole through a skull, a hat at hip height and a floating charm all
survived eight front-only review rounds):
forge/stage4_review/turntable_gate.py --capture 0=front.png --capture 90=right.png --capture 180=rear.png --capture 270=left.png --json
node runtime/scripts/export_mesh_geometry.mjs --url <preview> --out meshes.json then
forge/stage4_review/self_intersection.py meshes.json --json
forge/stage4_review/attachment_anchor.py object-sculpt-spec.json --measured measured.json --json
All three exit 0 clean / 1 gate failure / 2 error. A failure blocks continue even when
the global fidelity score passes. Read sampledVertexCount / unmeasuredAttachments /
missingAzimuths before believing a clean verdict: each names what the gate did not look at.
- Run deterministic gates before AI vision. MUST read
grimoire/review/gates_reference.md and grimoire/review/self_correction.md completely. Run
forge/stage4_review/diagnose_render.py and record the passing Tier 1 result with
--spec object-sculpt-spec.json --pass-id <pass> --in-place; for non-planar forms also run
forge/stage4_review/diagnose_render_multi_angle.py with the fixed view and at least two
meaningful orbit views. Then run
forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass>.
- Package one side-by-side sheet, then inspect it with agent vision:
forge/stage4_review/make_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json.
- Record the review (overall + per-layer + per-feature scores + decision):
forge/stage4_review/append_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <shot> --comparison-image cmp.png --ai-vision-score <0-1> --layer-scores-json '{...}' --feature-reviews-json <f.json> --in-place.
When a domain plugin contributes a review gate, produce its versioned report first with
the command that plugin's review step names, then attach it with
--domain-review-json <report>.json --review-scene-json <the plugin's scene fixture>. The
checklist step carries the resolved paths.
A failed family, painted-region, projection-coverage, critical-detail, or orbit gate blocks
continue even when the global score passes. See the plugin's own review-gate documentation.
- Sync pipeline state after manual review edits, record checklist evidence, then re-run the local
state gate before another correction or pass:
forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place
python3 forge/next.py --state .img2threejs/state.json object-sculpt-spec.json.
- Before declaring completion, run
forge/stage4_review/check_part_coverage.py --spec object-sculpt-spec.json --manifest parts.json
and verify the action-ready hierarchy. Mark part-coverage and action-ready only with evidence.
GLB-mediated v2 render-fidelity track (1.5 alpha)
When the user supplies a GLB as an intermediate reference, the browser-rendered GLB is the
structural and visual baseline for an independently authored procedural factory. The raw GLB is
never pixel evidence and its topology/materials are never copied into the factory. Before any
factory edit — full contract in grimoire/build/python_threejs_render_bridge.md, machine-readable
schema in docs/specs/render-profile.v2.schema.json (+ example; fail-closed validation):
forge/stage1_intake/probe_glb.py first. A merged one-node/one-mesh asset is insufficient
for semantic labels; request a multipart GLB or a browser semantic-ID pass before claiming
exact regions.
- Author ONE shared
render-profile.v2 (forge/stage4_review/validate_render_profile.py) used by
both the GLB and procedural routes. Region IDs are subject-specific, never inherited from the
example profile; declare the required set in extensions.requiredSemanticRegions so omission is
a hard validation error.
- Capture six passes per admitted view (
beauty, alpha-silhouette, semantic-id, depth,
normal, roughness-material-id); score with forge/stage4_review/compare_region_passes.py.
Missing semantic-ID data blocks per-region confidence rather than falling back to whole-image
scores.
- Use region-specific continuous geometry — never replace a face/head volume, cloth shell, or tail
with floating primitives when the region's silhouette requires a continuous surface.
- Run ONE correction group per loop, in order:
camera → silhouette → face → clothing → accessory → materials → lighting; recapture the full pass set after each group and record the changed
group, hashes and score. Never combine groups when diagnosing improvement.
Gates (do not skip)
Before any visual review or continue decision, MUST read the full gate-by-gate contract in
grimoire/review/gates_reference.md (Divine Eye, VLM rescue, multi-angle, interior difference,
chirality, hair, domain review, bounded correction, Divine Eye fitting, screenshot feedback, assembly,
attachment, material, detail inventory, rig payload, character track). In short:
- Validate references first (
grimoire/intake/validation_rubric.md, check_reference_admission.py).
divine_eye.py is deterministic-first; the VLM (vlm_gate.py) is a gated last layer, never
consulted on a hard-gate failure.
- A non-planar form must hold from ≥2 angles (
diagnose_render_multi_angle.py).
- Measure INSIDE the silhouette every visual pass (
interior_difference.py). Silhouette IoU reads
~11% of figure cells: a model with its face deleted scored the same 0.8803 as the finished face.
- Every
-l/-r pair is a MIRROR, not a rotation — hard at spec time (validate_chirality). A pair
wrong the same way on both sides still passes, and needs medial_lateral_bias vs a reference.
- Hair subjects:
scalp_exposure.py is HARD and runs on geometry before any render; hair_gate.py
is soft and subordinate to it. A coverage shortfall never authorises widening the masses.
- Flat colour regions with hard boundaries (blaze/bib/socks, livery stripe, painted marking) are an
identity feature, so their boundaries are gated on geometry:
vertex_region_gate.py. Never a
texture — this pipeline emits code; the shape predicates live in _shared/vertex_paint.py.
- A curve claim ("curled into a hook, not a straight cone") needs
swept_arc_gate.py: silhouette IoU
passes a straight cone occupying roughly the right cells.
- Character builds validate the rig payload (
stage5_rig/validate_rig_payload.py) before binding a
THREE.Skeleton; it proves payload integrity only, never pose stress or likeness.
- A rig that must MOVE runs the animation gates too (
grimoire/readiness/animation_contract.md;
the checklist steps and gate come from the installed plugin-character -- stage5_rig/ remains in
this repo as the emitter's library, not the checklist authority). A clip that exists is not a
clip that plays: only G1
(maxSampledBindingDelta <= 2^-23) separates the two, and a gate whose input is missing reports
unevaluated, never a pass. Bind at IDENTITY in attached mode and take the display offset from
the mesh bounds alone; loop is decided by poseReturn, never by travel.
- A domain plugin's review gate also runs against its versioned scene fixture.
- Local state enforces 3 corrections per pass and 6 total by default; reaching either limit is a
hard stop.
correction_loop.py may stop earlier on repeated defects, oscillation, or plateau.
continue requires a render + comparison sheet + AI-vision score ≥ threshold, every critical
feature ≥ its own threshold (grimoire/feedback/render_capture.md).
- Every model ships explodable AND clickable — a structure gate, not pixels
(
check_part_coverage.py, grimoire/build/geometry_patterns.md).
- Action-ready, attachment, material/lighting, detail inventory, and character-track requirements:
grimoire/readiness/action_rigging.md, grimoire/readiness/joint_attachment.md,
grimoire/feedback/shading_realism.md, grimoire/intake/quality_contract.md,
grimoire/intake/validation_rubric.md.
Self-Correction
After every pass, decide exactly one: continue | refine-spec | refine-code | request-input | stop.
refine-spec fixes a wrong/missing/shallow spec (re-validate, don't patch code around it);
refine-code fixes geometry/material/lighting that doesn't match a sound spec. Before making the
decision, MUST read the root-cause guide + fidelity scale in grimoire/review/self_correction.md,
record the decision, and re-run the local state gate.
Small features need a different instrument. Divine Eye's SSIM/tonal/edge signals run on a 64×64
luma grid, so a detail a few pixels wide is absent before any comparison happens. When fidelity
depends on individual tears, spars, fangs or eyes, use the four-tier microscope:
grimoire/review/divine_eye_microscope.md. Two empirically established rules from it: measure
fidelity on a component's visible footprint (full frame minus a component-hidden frame), never
on an isolation render; and never colour-gate a concave feature, where a dark ratio captures
cavity shading rather than material.
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.
Left and right
A left/right pair is a reflection, never a rotation: negate the lateral axis and nothing else,
(x, y, z) → (-x, y, z). With forward: +Z, Y up and a right-handed frame, the character's own
left is +X. The convention lives as code in forge/_shared/chirality.py
(CHARACTER_LEFT_SIGN), with two different gates for the two defects that shipped from getting it
wrong: validate_chirality catches a rotation-mistaken-for-reflection at spec time, and
medial_lateral_bias vs a reference catches a pair that is wrong the same way on both sides.
Reflecting also inverts triangle winding — flip it back on the mirrored side or flatShading
lights the limb as though lit from behind. Full write-up with the measured defects:
grimoire/scripts.md ("Left and right").
Hair
Hair has its own subsystem because it has failure modes no other gate can see. Full contract,
measurements and non-goals: docs/HAIR_PIPELINE.md. The hard rules:
- Roots bind to the scalp as
(u, v), never absolute positions (hard validation error).
standProud is enforced by the generator, not advisory.
scalp_exposure.py is a HARD gate on geometry before any render; a coverage shortfall never on
its own authorises widening the masses.
- Default representation tier is
shell, not locks; strand impression comes from faceting and
material (hair.human.code-only), since this skill emits no textures.
plane-card is rejected for hair (needs an alpha texture this skill cannot emit).
- Hair is rigidly parented, never smooth-skinned (the geodesic field runs through the skull).
Domain plugins
A domain plugin makes a run exact where this pipeline would otherwise infer. It contributes its own
checklist steps and gates, and publishes a spec-augmentation.json that this pipeline pulls at
spec-authoring. With no plugin serving the item, nothing here changes: author the skeleton and
infer the shape from the reference, as for any other object.
- The steps a plugin contributes appear in the checklist with their own ids and resolved paths. Read
what each step names -- a plugin ships its own contract, and it governs its own domain.
- A plugin may raise this pipeline's quality floors and can never lower one; the merge clamps.
- A plugin that does not serve an item publishes no augmentation. That is not an error and not a
blocked run: it is the generic path, and the reconstruction proceeds by inference.
- This pipeline names no domain. If a rule is domain-specific, it lives in that domain's plugin.
The img2 harness
Plugins are installed and managed by the img2 harness
(img2threejs/img2), a separate dependency-free CLI (Node
launcher, Python core). This skill
never installs anything itself: when state.py init names a profile as unavailable, name the
img2 add command that installs it and stop — never vendor domain logic instead.
img2 add img2threejs/plugin-<id> --ref <tag> # install a plugin at a tag (e.g. plugin-cs2)
img2 doctor # what each host resolves: base-skill path + version, plugin gates
img2 capabilities --from-kind image --to-kind glb # which installed plugin serves an edge
Setup and the full CLI reference live in the README quick-start and the harness repo's docs.
Forge Runtime Contracts
Subdivision runtime tests compile generated TypeScript against the showcase checkout. Set
IMG2THREEJS_SHOWCASE_ROOT to that checkout; without it, local runtime-only tests skip with an
actionable message while static contracts still run. CI should set IMG2THREEJS_REQUIRE_SHOWCASE=1
to turn a missing showcase checkout into a test failure.
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_subdivision.py
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 -m unittest discover -s forge/tests
IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_showcase_tsc_smoke.py
Implementation Rules (brief)
TypeScript + plain Three.js unless the project uses a wrapper. Group factory
createObjectNameModel(spec, options), reconstruction data kept separate from renderer objects,
deterministic seeds for all procedural noise. Prefer primitives / Shape extrude / curve+tube /
instancing / displacement / generated canvas textures before any external art. Full geometry &
material recipes + hard-won failure patterns: grimoire/build/geometry_patterns.md.
Optional Python ↔ Three.js render bridge
When Python is requested for character rendering, use it as a deterministic job/evidence layer
around the browser Three.js runtime: camera-batch manifests, source/output hashes, readiness and
settle checks, screenshot persistence, masks, diagnostics, and comparison packaging. The target
Three.js browser route remains the rendering authority. Do not silently replace the procedural
TypeScript factory with Blender/VRM/GLB output. Full routing, manifest fields, and failure rules:
grimoire/build/python_threejs_render_bridge.md.
Standard character pipeline (merged 1.5 beta + alpha)
Use grimoire/readiness/standard_character_pipeline.md for character work. Beta owns the
strict sculpt/build/review gates; alpha owns deterministic camera manifests, browser screenshot
evidence and UniRig-shaped rig validation. CharacterGen, Tripo, VRM and other neural/asset
systems are opt-in adapters with source, checkpoint, license, coordinate conversion and output
hashes. They never silently replace the procedural TypeScript factory. Image-to-mesh systems emit a
static mesh with no skeleton, so their output is never animation-ready however good it looks.
Executable entry points: forge/stage4_review/render_bridge.py and
scripts/capture_threejs_playwright.py (init → browser capture → validate → diagnose; capture
must operate on the real showcase/browser route and leave readable PNGs in the workspace).
Output
- Analysis-only: suitability verdict + scores, object extraction, macro→micro hierarchy,
geometry strategy, material/lighting recipe, animation/destruction feasibility, plan + risks.
- Implementation: the above briefly, then edit code; verify with typecheck/build + a screenshot.
- Not feasible: name the blocker, ask for more views / cleaner image / accepted stylization /
a narrower target. "This cannot reach the requested fidelity from this image" is a valid result.
1---
2name: img2threejs
3description: 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.
4license: Apache-2.0
5version: 2.0.0
6metadata:
7 source: https://skillmd.com/skills/hoainho/img2threejs
8---
9
10# img2threejs — Image to procedural Three.js
11
12Rebuild the object visible in a reference image as a **code-only** procedural Three.js model,
13gated by a staged sculpting pipeline and an AI-vision self-correction loop. This is
14reconstruction-by-code, **not** photogrammetry, mesh extraction, or downloaded art packs. That
15promise governs how the model is *built* — it says nothing about which file formats it can
16subsequently be *exported* to; an explicitly-selected emission target (`--target <kind>`) is a
17terminal, whole-artifact transform of the already-built model, verified to its own stated limit,
18never a second way to build one.
19
20Agent-agnostic: works under Claude Code, Codex, or OpenCode. Wherever this doc says "agent
21vision" or "agent browser tool", use whatever the host provides — native image reading, a
22browser MCP (playwright/chrome-devtools), the project preview, or a user-supplied screenshot.
23
24This file is the always-loaded router: it holds the order of operations and every hard rule as one
25line. The full contract behind each rule lives in the `grimoire/` or `docs/` file that rule names —
26read the named file at the moment you reach that stage, not before.
27
28## Canonical shared checkout
29
30Keep one checkout of this repository and let every host enter it through a symlink, so Claude and
31Codex execute the same code instead of drifting apart:
32
33```text
34~/.claude/skills/img2threejs -> <your checkout>
35~/.codex/skills/img2threejs -> <your checkout>
36```
37
38## When To Use
39
40The user attaches/points to an object image and wants a procedural Three.js model, a
41reconstruction/animation/destruction plan, a sculpt spec, or code. Also for material studies,
42action-ready props, game objects, botanical/mechanical parts, and stylized reconstructions.
43
44## Core Promise
45
46Sculpt from a photo, in order — never one-shot a mesh:
471. **Run `python3 forge/next.py --state .img2threejs/state.json [<spec>]` first**, at every start,
48 resume, and before every correction iteration. It reports the ordered checklist, exact next
49 command, evidence status, and bounded correction-loop status; it never replaces the spec/pass
50 gates. Obey a hard stop; never continue from memory.
512. **Validate** the image is a suitable 3D target (`grimoire/intake/validation_rubric.md`).
523. **Assess** object class + complexity, then write a `qualityContract` before any code.
534. **Spec** it: component hierarchy, materials, lighting, pivots, sockets, action anchors.
545. **Build pass-by-pass** from blockout → structure → form → material → lighting → interaction → optimization.
556. **Verify** each pass with a screenshot compared against the reference; fail a pass if an
56 identity-defining feature is wrong even when the global score looks fine.
57
58State explicitly when output is approximate/stylized/low-poly. A single image cannot reveal
59hidden sides or guarantee exact geometry — say so instead of faking confidence.
60
61## Mandatory Local State Gate
62
63Conversation context is disposable; `.img2threejs/state.json` is the local checklist authority.
64Initialize once per reconstruction, then gate every step through it:
65
66```bash
67python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|character|installed-domain> --spec object-sculpt-spec.json
68python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
69python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>
70```
71
72- `next.py` prints the current step, pass, incomplete mandatory steps, exact next command, and
73 `loop/max`. Exit code 3 or `status=stopped` is a hard stop: report the reason and request input.
74 Never bypass it by reconstructing progress from chat history.
75- Every completed step needs evidence; mark a non-applicable step `skipped` only with `--reason` —
76 silent omission is forbidden. Loop counts derive from `reviewHistory` actions
77 (`refine-spec`/`refine-code`), not agent memory. Defaults: 3 corrections per pass, 6 total.
78- A domain profile's steps, gates and reference material come from the **registry**: in-repo
79 modules (`character`) and installed plugins (`cs2`, `animated-character` from plugin-character) register identically, and
80 `forge/state.py init` names what is available. A profile adds mandatory gates without changing
81 the core order -- a domain plugin typically requires an authoritative classification, an intake
82 manifest, and a machine-readable domain review before AI review; `character` requires the
83 character contracts and landmark evidence; `animated-character` (requires the installed plugin-character) adds all of `character` plus the
84 nine Stage R steps (`grimoire/readiness/animation_contract.md`). Pick it whenever the rig must
85 MOVE — on `character` the Stage R gates are absent and the build completes without ever running
86 them, which is how animation used to ship broken. Its order is load-bearing: repair the mesh,
87 freeze it, bind additively, then verify parity. Every profile records suitability, projection
88 applicability, and
89 material-evidence applicability. The state file is a resumability index, not visual evidence:
90 renders, specs, review history, and deterministic gates remain the authoritative artifacts.
91
92## Required Inputs
93
94- one image path / screenshot / URL / attached image (if missing or unreadable, ask)
95- intended use: prop, game object, hero render, playable/destructible object, animation rig
96 (default: real-time browser prop with interactive performance)
97- when a domain plugin serves the item, whatever authoritative record its intake step requires, or
98 an explicit request for the user/vision provider to supply one; heuristic detection alone is not
99 enough to select a geometry adapter
100
101## The Loop (scripts do enforcement; agent vision does judgment)
102
103Run scripts from the skill root (`forge/...`). Pure Python 3.10+ stdlib, no pip installs.
104Full flags: `grimoire/scripts.md`. Never let a script *score* visuals — that is the agent's job.
105
1061. **Analyze the image first** (agent vision, before any script): work the layered observation
107 protocol in `grimoire/intake/image_analysis.md` — identify/classify, decompose macro→meso→micro,
108 map part relationships, name materials in PBR terms, list identity-defining features, and flag
109 what the single view hides. Observation before inference; controlled 3D vocabulary; 3D
110 object-space not 2D image-space. Then probe local images:
111 `forge/stage1_intake/probe_image.py <image>` (metadata only, not a visual check).
1121a. **Local Spec Search** — after image analysis, before writing or refining a spec, pull local
113 domain evidence (anatomy/PBR/wear/geometry/runtime/physics) rather than inventing it:
114 `python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json`
115 (auto-runs BM25 over the `core_3d` collection, or the collection a declared domain contributes
116 -- the collection is NEVER guessed from the target name; writes a `localSpecSearch` bundle that
117 `new_sculpt_spec.py --assessment` carries into the spec). Full query-expansion recipe
118 (bilingual terms, focused `search_specs.py` retrieval, cache rules):
119 `grimoire/intake/local_spec_search.md`. MUST read it before retrying an incomplete or
120 domain-specific query.
1211b. **Domain intake** — when a domain plugin serves the item, complete its intake steps before
122 pre-spec authoring (admission, heuristic signal, classification, family/route resolution).
123 MUST read the contract its step names, completely, before creating the manifest or
124 running pre-spec assessment.
1251c. **Optional fidelity evidence adapters** — only when they improve an observed weak point; the
126 stdlib core remains authoritative. Thin/complex masks → local SAM2; character face/pose →
127 MediaPipe; weak front/back cues → Depth Anything V2
128 (`forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...`; every adapter emits
129 provenance; monocular depth is relative only). **MCP-only scene mutations never count as
130 implementation** — write the proven change back to the spec or TypeScript, rebuild, recapture.
131 Full adapter + MCP routing and authority boundaries:
132 `docs/integrations/reference_fidelity_tooling.md`.
1332. **Pre-Spec Assessment Gate** — classify + score complexity + write the quality contract:
134 `forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json`. Rules: `grimoire/intake/quality_contract.md`.
135 Set `objectClass.primaryDomain` (`object` | `character` | `hybrid`) and fill the seeded
136 `detailInventory` (its `targetMinDetails` scales with complexity). A domain plugin may **raise**
137 these floors through its augmentation -- the merge clamps, so a plugin can never lower one
138 (a skin's finish/wear/hardware IS the item, so such a domain is held to the
139 top fidelity bar. Author procedural GEOMETRY but route the FINISH through the projection path in
140 step 2c — a procedural finish for a patterned skin (Doppler/Gamma/Marble/Fade) reads visibly
141 wrong against the reference. A domain plugin ships its own finish rulebook and texture-acquisition
142 guide; read what its checklist steps name.
1432b. **Detail inventory** (do not skip for detailed subjects) — scan zones and enumerate every
144 identity-defining small detail (gloss, bevel, fasteners, linework, contours, stains):
145 `forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json`.
146 Each detail MUST map to a `component.localFeatures` or `material.localOverrides` entry — never
147 prose only. Taxonomy + 3D-term recipes: `grimoire/intake/detail_inventory.md`.
1482c. **Projection-first fidelity** (characters AND reference-matched surfaces — painted skins,
149 decals, painted patterns) — when the goal is matching a specific reference's surface, put the
150 photo's own pixels on the mesh instead of approximating them procedurally. This is the single
151 biggest fidelity lever; a procedural material for a patterned surface is the #1 reconstruction
152 failure. Recipe (`grimoire/character/likeness_maximization.md` — its two levers generalize past
153 characters): solve the camera (`stage1_intake/solve_camera_pose.py` → `referenceCamera`),
154 **de-light** the reference (`stage1_intake/delight_albedo.py`, hard requirement — de-lighting is
155 what makes projection safe), then project the de-lit crop and bake it into UVs
156 (`stage3_build/bake_projected_texture.py --mesh-id <id>`). For a painted skin the projected de-lit
157 crop IS the finish — no procedural Doppler material. For characters, first capture landmarks
158 (`stage1_intake/extract_landmarks.py --out anatomy.json`), fill `preSpecAssessment.anatomy`,
159 route `grimoire/character/reconstruction.md`. A single view cannot show hidden sides — report
160 per-region confidence and request more views when it matters.
161 Character sub-routes, in order — decide what parts exist before shaping any, and shape the head
162 before the hair that sits on it:
163 - **Parts** — `grimoire/character/structure_decomposition.md`
164 - **Head** — `grimoire/character/head_construction.md` (what the likeness gate reads against)
165 - **Hair** — `grimoire/character/stylized_hair_threejs.md` + parameter contract in
166 `grimoire/character/threejs_hair_parameter_contract.json`. Lock topology only after the
167 silhouette review passes: material tuning cannot repair wrong lock topology.
1682d. **Reference-free humanoid** — a generic figure with no reference image has nothing to measure,
169 so fill anatomy from public canon:
170 `forge/stage2_spec/humanoid_proportions.py <spec> --style-heads 8 --in-place`. It writes
171 `anatomy.source: "canon-table"` so canon is never mistaken for measurement, refuses to run when
172 the spec names a reference image, and names anything the corpus does not supply rather than
173 interpolating it.
1743. Author the spec from the assessment:
175 `forge/stage2_spec/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --augmentation spec-augmentation.json --domain <profile> --out object-sculpt-spec.json` (the checklist step carries the resolved flags).
176 Replace generic starter `featureReviewTargets` with the object's real identity-defining
177 systems (≤5 critical, ≤3 important per pass); for characters add `anatomy-proportion`,
178 `face-landmark-placement`, `pose-silhouette`, `outfit-and-palette`. Use 3D-graphics terms only
179 (`grimoire/glossary/3d_vocabulary.md`), never "nice/smooth/shiny". Classify every component's
180 `topologyClass`/`topologyRationale` per `grimoire/intake/surface_topology.md` before picking a
181 `primitive` — this is what prevents a continuous organic form from being picked as a box.
1824. When material fidelity matters and a source image exists, analyze each material's **finish** then
183 extract reference PBR evidence, both per crop (verify the crop is on the part you think it is):
184 - `forge/stage1_intake/analyze_texture.py <crop> --spec spec.json --material-id <id> --in-place`
185 classifies the finish, extracts the gradient palette, and writes doc-grounded
186 MeshPhysicalMaterial scalars onto the material. Recipes + Three.js texture/PBR rules:
187 `grimoire/build/threejs_texture_reference.md`. Rule of thumb: **solid albedo for flat paint,
188 real reference crop for patterned finishes**.
189 - `forge/stage1_intake/extract_pbr_evidence.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7`.
190 Confidence < 0.7 is a stop/refine-input signal, not a pass. It is inference, not inverse rendering.
191 - For multiple named regions: `forge/stage1_intake/material_region_analysis.py --manifest regions.json --out-dir material-evidence --out material-analysis.json`,
192 resolve each assignment from `docs/materials/material-reference.json`, wire it in with
193 `forge/stage2_spec/apply_material_analysis.py`.
194 - Emit the controlled material camera/crop contract (`forge/stage4_review/material_views.py`),
195 compare visible-footprint crops (`material_comparator.py`), apply only bounded material-scoped
196 corrections (`material_feedback.py`), and record the blocking result (`material_gate.py`).
1975. Validate, then strict-validate before generating code:
198 `forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json` then `--strict-quality`.
199 Strict blocks shallow specs (a complex object with one root, no repetition systems, no
200 local overrides, no micro groups is NOT implementation-ready even if JSON validates).
2016. **Locked build passes** — only touch the currently unlocked pass:
202 `forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json`
203 `forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts`
204 The generator is fail-closed: `strict-quality` must pass before it writes any factory, and a
205 future `--pass-id` fails until prior passes are reviewed `continue`. If blocked, preserve the
206 `BLOCKED` artifact and refine the subject-specific spec; do not substitute a generic template.
207 The local state adds `--force` only for a new pass or `refine-spec`; `refine-code` edits the
208 current artifact without regenerating it. Before overwriting, carry valid hand refinement back
209 into the spec; generated code must not be the only copy of reconstruction decisions.
2106a. **Hitting a triangle budget.** `performanceBudget.targetTriangles` selects a tessellation tier
211 for every primitive with segment counts (low ≤6k, standard ≤60k, else hero) and caps
212 implicit-surface sampling grids. Where a tier is not precise enough, add
213 `geometryDescriptor.decimate: {"targetRatio": 0.4}` to that component — a quadric collapse in
214 the generated factory, run **before** skin binding so weights are computed on surviving
215 vertices. It keeps `position` only (normals recomputed), so it is refused on an
216 authored/unwrapped `uvStrategy`. Offline LOD tiers:
217 `forge/stage3_build/decimate.py <mesh.json> --ratio <r> --json`.
2187. Render the current pass in a browser/preview, capture a screenshot at a review viewpoint.
2197a. **Off-axis and placement gates — a single review viewpoint is not evidence about the model.**
220 Capture a turntable, not one frame, and run all three; each catches a defect class the older
221 gates pass by construction (a hole through a skull, a hat at hip height and a floating charm all
222 survived eight front-only review rounds):
223 `forge/stage4_review/turntable_gate.py --capture 0=front.png --capture 90=right.png --capture 180=rear.png --capture 270=left.png --json`
224 `node runtime/scripts/export_mesh_geometry.mjs --url <preview> --out meshes.json` then
225 `forge/stage4_review/self_intersection.py meshes.json --json`
226 `forge/stage4_review/attachment_anchor.py object-sculpt-spec.json --measured measured.json --json`
227 All three exit `0` clean / `1` gate failure / `2` error. A failure blocks `continue` even when
228 the global fidelity score passes. Read `sampledVertexCount` / `unmeasuredAttachments` /
229 `missingAzimuths` before believing a clean verdict: each names what the gate did not look at.
2308. **Run deterministic gates before AI vision.** MUST read
231 `grimoire/review/gates_reference.md` and `grimoire/review/self_correction.md` completely. Run
232 `forge/stage4_review/diagnose_render.py` and record the passing Tier 1 result with
233 `--spec object-sculpt-spec.json --pass-id <pass> --in-place`; for non-planar forms also run
234 `forge/stage4_review/diagnose_render_multi_angle.py` with the fixed view and at least two
235 meaningful orbit views. Then run
236 `forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass>`.
2379. Package one side-by-side sheet, then inspect it with agent vision:
238 `forge/stage4_review/make_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json`.
23910. Record the review (overall + per-layer + per-feature scores + decision):
240 `forge/stage4_review/append_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <shot> --comparison-image cmp.png --ai-vision-score <0-1> --layer-scores-json '{...}' --feature-reviews-json <f.json> --in-place`.
241 When a domain plugin contributes a review gate, produce its versioned report first with
242 the command that plugin's review step names, then attach it with
243 `--domain-review-json <report>.json --review-scene-json <the plugin's scene fixture>`. The
244 checklist step carries the resolved paths.
245 A failed family, painted-region, projection-coverage, critical-detail, or orbit gate blocks
246 `continue` even when the global score passes. See the plugin's own review-gate documentation.
24711. Sync pipeline state after manual review edits, record checklist evidence, then re-run the local
248 state gate before another correction or pass:
249 `forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place`
250 `python3 forge/next.py --state .img2threejs/state.json object-sculpt-spec.json`.
25112. Before declaring completion, run
252 `forge/stage4_review/check_part_coverage.py --spec object-sculpt-spec.json --manifest parts.json`
253 and verify the action-ready hierarchy. Mark `part-coverage` and `action-ready` only with evidence.
254
255## GLB-mediated v2 render-fidelity track (1.5 alpha)
256
257When the user supplies a GLB as an intermediate reference, the browser-rendered GLB is the
258structural and visual baseline for an independently authored procedural factory. The raw GLB is
259never pixel evidence and its topology/materials are never copied into the factory. Before any
260factory edit — full contract in `grimoire/build/python_threejs_render_bridge.md`, machine-readable
261schema in `docs/specs/render-profile.v2.schema.json` (+ example; fail-closed validation):
262
2631. `forge/stage1_intake/probe_glb.py` first. A merged one-node/one-mesh asset is `insufficient`
264 for semantic labels; request a multipart GLB or a browser semantic-ID pass before claiming
265 exact regions.
2662. Author ONE shared `render-profile.v2` (`forge/stage4_review/validate_render_profile.py`) used by
267 both the GLB and procedural routes. Region IDs are subject-specific, never inherited from the
268 example profile; declare the required set in `extensions.requiredSemanticRegions` so omission is
269 a hard validation error.
2703. Capture six passes per admitted view (`beauty`, `alpha-silhouette`, `semantic-id`, `depth`,
271 `normal`, `roughness-material-id`); score with `forge/stage4_review/compare_region_passes.py`.
272 Missing semantic-ID data blocks per-region confidence rather than falling back to whole-image
273 scores.
2744. Use region-specific continuous geometry — never replace a face/head volume, cloth shell, or tail
275 with floating primitives when the region's silhouette requires a continuous surface.
2765. Run ONE correction group per loop, in order: `camera → silhouette → face → clothing → accessory
277 → materials → lighting`; recapture the full pass set after each group and record the changed
278 group, hashes and score. Never combine groups when diagnosing improvement.
279
280## Gates (do not skip)
281
282Before any visual review or `continue` decision, MUST read the full gate-by-gate contract in
283`grimoire/review/gates_reference.md` (Divine Eye, VLM rescue, multi-angle, interior difference,
284chirality, hair, domain review, bounded correction, Divine Eye fitting, screenshot feedback, assembly,
285attachment, material, detail inventory, rig payload, character track). In short:
286
287- Validate references first (`grimoire/intake/validation_rubric.md`, `check_reference_admission.py`).
288- `divine_eye.py` is deterministic-first; the VLM (`vlm_gate.py`) is a gated last layer, never
289 consulted on a hard-gate failure.
290- A non-planar form must hold from ≥2 angles (`diagnose_render_multi_angle.py`).
291- Measure INSIDE the silhouette every visual pass (`interior_difference.py`). Silhouette IoU reads
292 ~11% of figure cells: a model with its face deleted scored the same 0.8803 as the finished face.
293- Every `-l`/`-r` pair is a MIRROR, not a rotation — hard at spec time (`validate_chirality`). A pair
294 wrong the same way on both sides still passes, and needs `medial_lateral_bias` vs a reference.
295- Hair subjects: `scalp_exposure.py` is HARD and runs on geometry before any render; `hair_gate.py`
296 is soft and subordinate to it. A coverage shortfall never authorises widening the masses.
297- Flat colour regions with hard boundaries (blaze/bib/socks, livery stripe, painted marking) are an
298 identity feature, so their boundaries are gated on geometry: `vertex_region_gate.py`. Never a
299 texture — this pipeline emits code; the shape predicates live in `_shared/vertex_paint.py`.
300- A curve claim ("curled into a hook, not a straight cone") needs `swept_arc_gate.py`: silhouette IoU
301 passes a straight cone occupying roughly the right cells.
302- Character builds validate the rig payload (`stage5_rig/validate_rig_payload.py`) before binding a
303 `THREE.Skeleton`; it proves payload integrity only, never pose stress or likeness.
304- A rig that must MOVE runs the animation gates too (`grimoire/readiness/animation_contract.md`;
305 the checklist steps and gate come from the installed plugin-character -- `stage5_rig/` remains in
306 this repo as the emitter's library, not the checklist authority). A clip that exists is not a
307 clip that plays: only G1
308 (`maxSampledBindingDelta <= 2^-23`) separates the two, and a gate whose input is missing reports
309 `unevaluated`, never a pass. Bind at IDENTITY in attached mode and take the display offset from
310 the mesh bounds alone; loop is decided by `poseReturn`, never by travel.
311- A domain plugin's review gate also runs against its versioned scene fixture.
312- Local state enforces 3 corrections per pass and 6 total by default; reaching either limit is a
313 hard stop. `correction_loop.py` may stop earlier on repeated defects, oscillation, or plateau.
314- `continue` requires a render + comparison sheet + AI-vision score ≥ threshold, every critical
315 feature ≥ its own threshold (`grimoire/feedback/render_capture.md`).
316- Every model ships explodable AND clickable — a structure gate, not pixels
317 (`check_part_coverage.py`, `grimoire/build/geometry_patterns.md`).
318- Action-ready, attachment, material/lighting, detail inventory, and character-track requirements:
319 `grimoire/readiness/action_rigging.md`, `grimoire/readiness/joint_attachment.md`,
320 `grimoire/feedback/shading_realism.md`, `grimoire/intake/quality_contract.md`,
321 `grimoire/intake/validation_rubric.md`.
322
323## Self-Correction
324
325After every pass, decide exactly one: `continue | refine-spec | refine-code | request-input | stop`.
326`refine-spec` fixes a wrong/missing/shallow spec (re-validate, don't patch code around it);
327`refine-code` fixes geometry/material/lighting that doesn't match a sound spec. Before making the
328decision, MUST read the root-cause guide + fidelity scale in `grimoire/review/self_correction.md`,
329record the decision, and re-run the local state gate.
330
331**Small features need a different instrument.** Divine Eye's SSIM/tonal/edge signals run on a 64×64
332luma grid, so a detail a few pixels wide is absent before any comparison happens. When fidelity
333depends on individual tears, spars, fangs or eyes, use the four-tier microscope:
334`grimoire/review/divine_eye_microscope.md`. Two empirically established rules from it: measure
335fidelity on a component's **visible footprint** (full frame minus a component-hidden frame), never
336on an isolation render; and never colour-gate a **concave** feature, where a dark ratio captures
337cavity shading rather than material.
338
339## Transparency and Process Debugging
340
341Report what changed each pass with evidence (exact values/coordinates), name what still doesn't
342match, and never claim "done" when only "improved". A passing gate is not proof of 3D realism.
343Full rule + examples: `grimoire/review/self_correction.md`.
344
345## Left and right
346
347A left/right pair is a **reflection**, never a rotation: negate the lateral axis and nothing else,
348`(x, y, z) → (-x, y, z)`. With `forward: +Z`, Y up and a right-handed frame, the character's own
349left is **+X**. The convention lives as code in `forge/_shared/chirality.py`
350(`CHARACTER_LEFT_SIGN`), with two different gates for the two defects that shipped from getting it
351wrong: `validate_chirality` catches a rotation-mistaken-for-reflection at spec time, and
352`medial_lateral_bias` vs a reference catches a pair that is wrong the same way on both sides.
353Reflecting also inverts triangle winding — flip it back on the mirrored side or `flatShading`
354lights the limb as though lit from behind. Full write-up with the measured defects:
355`grimoire/scripts.md` ("Left and right").
356
357## Hair
358
359Hair has its own subsystem because it has failure modes no other gate can see. Full contract,
360measurements and non-goals: `docs/HAIR_PIPELINE.md`. The hard rules:
361
362- Roots bind to the scalp as `(u, v)`, never absolute positions (hard validation error).
363- `standProud` is enforced by the generator, not advisory.
364- `scalp_exposure.py` is a HARD gate on geometry before any render; a coverage shortfall never on
365 its own authorises widening the masses.
366- Default representation tier is `shell`, not locks; strand impression comes from faceting and
367 material (`hair.human.code-only`), since this skill emits no textures.
368- `plane-card` is rejected for hair (needs an alpha texture this skill cannot emit).
369- Hair is rigidly parented, never smooth-skinned (the geodesic field runs through the skull).
370
371## Domain plugins
372
373A domain plugin makes a run exact where this pipeline would otherwise infer. It contributes its own
374checklist steps and gates, and publishes a `spec-augmentation.json` that this pipeline pulls at
375`spec-authoring`. With no plugin serving the item, nothing here changes: author the skeleton and
376infer the shape from the reference, as for any other object.
377
378- The steps a plugin contributes appear in the checklist with their own ids and resolved paths. Read
379 what each step names -- a plugin ships its own contract, and it governs its own domain.
380- A plugin may **raise** this pipeline's quality floors and can never lower one; the merge clamps.
381- A plugin that does not serve an item publishes no augmentation. That is not an error and not a
382 blocked run: it is the generic path, and the reconstruction proceeds by inference.
383- This pipeline names no domain. If a rule is domain-specific, it lives in that domain's plugin.
384
385### The img2 harness
386
387Plugins are installed and managed by the `img2` harness
388([img2threejs/img2](https://github.com/img2threejs/img2)), a separate dependency-free CLI (Node
389launcher, Python core). This skill
390never installs anything itself: when `state.py init` names a profile as unavailable, name the
391`img2 add` command that installs it and stop — never vendor domain logic instead.
392
393```bash
394img2 add img2threejs/plugin-<id> --ref <tag> # install a plugin at a tag (e.g. plugin-cs2)
395img2 doctor # what each host resolves: base-skill path + version, plugin gates
396img2 capabilities --from-kind image --to-kind glb # which installed plugin serves an edge
397```
398
399Setup and the full CLI reference live in the README quick-start and the harness repo's docs.
400
401## Forge Runtime Contracts
402
403Subdivision runtime tests compile generated TypeScript against the showcase checkout. Set
404`IMG2THREEJS_SHOWCASE_ROOT` to that checkout; without it, local runtime-only tests skip with an
405actionable message while static contracts still run. CI should set `IMG2THREEJS_REQUIRE_SHOWCASE=1`
406to turn a missing showcase checkout into a test failure.
407
408```bash
409IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_subdivision.py
410IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 -m unittest discover -s forge/tests
411IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_showcase_tsc_smoke.py
412```
413
414## Implementation Rules (brief)
415
416TypeScript + plain Three.js unless the project uses a wrapper. `Group` factory
417`createObjectNameModel(spec, options)`, reconstruction data kept separate from renderer objects,
418deterministic seeds for all procedural noise. Prefer primitives / `Shape` extrude / curve+tube /
419instancing / displacement / generated canvas textures before any external art. Full geometry &
420material recipes + hard-won failure patterns: `grimoire/build/geometry_patterns.md`.
421
422### Optional Python ↔ Three.js render bridge
423
424When Python is requested for character rendering, use it as a deterministic job/evidence layer
425around the browser Three.js runtime: camera-batch manifests, source/output hashes, readiness and
426settle checks, screenshot persistence, masks, diagnostics, and comparison packaging. The target
427Three.js browser route remains the rendering authority. Do not silently replace the procedural
428TypeScript factory with Blender/VRM/GLB output. Full routing, manifest fields, and failure rules:
429`grimoire/build/python_threejs_render_bridge.md`.
430
431### Standard character pipeline (merged 1.5 beta + alpha)
432
433Use `grimoire/readiness/standard_character_pipeline.md` for character work. Beta owns the
434strict sculpt/build/review gates; alpha owns deterministic camera manifests, browser screenshot
435evidence and UniRig-shaped rig validation. CharacterGen, Tripo, VRM and other neural/asset
436systems are opt-in adapters with source, checkpoint, license, coordinate conversion and output
437hashes. They never silently replace the procedural TypeScript factory. Image-to-mesh systems emit a
438static mesh with no skeleton, so their output is never animation-ready however good it looks.
439Executable entry points: `forge/stage4_review/render_bridge.py` and
440`scripts/capture_threejs_playwright.py` (`init → browser capture → validate → diagnose`; capture
441must operate on the real showcase/browser route and leave readable PNGs in the workspace).
442
443## Output
444
445- **Analysis-only**: suitability verdict + scores, object extraction, macro→micro hierarchy,
446 geometry strategy, material/lighting recipe, animation/destruction feasibility, plan + risks.
447- **Implementation**: the above briefly, then edit code; verify with typecheck/build + a screenshot.
448- **Not feasible**: name the blocker, ask for more views / cleaner image / accepted stylization /
449 a narrower target. "This cannot reach the requested fidelity from this image" is a valid result.