img2threejs/img2threejs

Reference images reconstructed in code as animation-ready Three.js models, running live in the browser.

→ Open the Live Demo Gallery

Every model in the gallery is generated code, running in your browser. No mesh files, no downloads.

---

Live demos

Reconstructions built entirely from primitives, procedural shaders, and generated geometry. Open any model to orbit it, inspect its reference, and read the generated source.

| Demo | Subject | Built with | View | Source | | --- | --- | --- | --- | --- | | Dual-Sword Warrior — TypeScript procedural surfaces ⚠︎ | character | v1.5.1 | Live | code | | Low-Poly Humanoid — Rigged Character ⚠︎ | character | v1.5.0 | Live | code | | ★ Talon Knife \| Doppler Ruby (Factory New) | object | v1.4.4 | Live | code | | AWP \| Medusa (Minimal Wear) · V2 rebuild | object | V2 | Live | code | | Pikachu 10K Star Celebration ⚠︎ | character | v1.5-beta | Live | code | | Glock-18 \| Ghost Protocol (Well-Worn) | object | v1.4.1 | Live | code | | Classic Knife \| Fade (Minimal Wear) | object | v1.3 | Live | code | | BMX Endurance Bike | object | v1.3 | Live | code | | M9 Bayonet \| Doppler Phase 2 | object | v1.3 | Live | code | | Sony WF-1000XM3 Earbuds + Case | object | v1.2 | Live | code | | ISSACA 12 Gauge Shotgun | object | v1.2 | Live | code | | Gerber Paracord Knife | object | v1.2 | Live | code | | Doraemon House (isometric diorama) | object | v1.2 | Live | code | | War-Hauler "SECTOR 07" | object | v1.2 | Live | code | | Crowned Loot Chest ⚠︎ | object | v1.2 | Live | code |

⚠︎ marks a demo whose registry status is still placeholder rather than final — it renders, but it is not finished work. The Built with column is the version each demo's own registry entry records in generatedWith, not an inference from dates; awp-medusa-v2 records V2, which is that demo's rebuild pass rather than a release number. Rows are ordered newest first by the commit that added the demo.

The gallery source lives in img2threejs/img2threejs-showcase. If this project is useful, a star on this repo helps others find it.

---

What it does

You give it one reference image of an object. It produces a THREE.Group factory written in TypeScript that recreates that object from primitives, procedural shaders, and generated geometry — with a runtime hierarchy (pivots, sockets, colliders) so the result is ready to animate, not an inert lump.

It runs under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever the docs say "agent vision" or "agent browser tool", it uses whatever the host provides — native image reading, a browser MCP, the project preview, or a user-supplied screenshot.

Subjects and detail accuracy

• Objects and characters. Each subject is classified object, character, or hybrid. Objects follow the hard-surface pipeline; characters route through an anatomy-aware track (head-unit proportions, facial landmarks, pose) documented in grimoire/character/reconstruction.md.
• Detail-first analysis. Before code generation the pipeline enumerates a detailInventory of identity-defining small details (gloss, bevel/rounding, screws/rivets, engraved or painted linework, contours, stains and wear). Every detail must map to a real component or material entry, and a strict-quality gate blocks generation until the inventory is complete. Taxonomy: grimoire/intake/detail_inventory.md.
• Maximum likeness for a specific person or character. An opt-in projection-first path fits a parametric template to image landmarks, de-lights the photo, camera-matches the render, and projects the reference onto the mesh. A single image cannot guarantee 100 percent likeness, so the pipeline reports per-region confidence and asks for more views when it matters. Details: grimoire/character/likeness_maximization.md.
• Multi-view silhouette carving. An opt-in geometryDescriptor.visualHull intersects at least two deterministic orthographic binary silhouettes into a bounded, welded voxel mesh. It records unseen areas as low-confidence rather than inventing hidden detail. Schema and runtime check: grimoire/scripts.md.
• CS2 weapon review gates. Knife and Glock-18 routes use family-specific component contracts. The review records exactness tier, family identity, painted-region and projection coverage, per-region confidence, approximation notes, and versioned review-scene metadata; component-coverage and map-stripped blockout gates prevent a convincing texture from standing in for real structure. Ships with the CS2 domain plugin; see its docs/cs2/review-gates.md.
• Resumable local workflow. forge/state.py records an ordered, evidence-backed intake/pass checklist for the generic profile and every registered domain (in-repo character, plus installed domain plugins such as CS2 and animated-character from plugin-character). forge/next.py --state resumes from that checklist while the existing spec, render, and review gates remain authoritative.
• Material reference pipeline. Every visible material region can be cropped, analyzed, resolved against the versioned Three.js material registry, fitted into ObjectSculptSpec, rendered from controlled camera views, and accepted only after a per-region comparison gate. See docs/materials/README.md.
• Python-assisted browser rendering. Python may orchestrate camera batches, hashes, manifests, and deterministic diagnostics, but the target browser Three.js route remains the rendering authority. See grimoire/build/python_threejs_render_bridge.md.

---

How it works

A staged sculpting pipeline turns the reference image into a spec, then generates and vision-reviews one build pass at a time — blockout → structural → form → material → surface → lighting → interaction → optimization — self-correcting until every identity-defining feature clears its threshold.

→ Full pipeline diagram, gates, self-correction logic, and the token-efficiency design: docs/ARCHITECTURE.md A staged sculpting pipeline turns the reference image into a spec, then generates and vision-reviews one build pass at a time — blockout → structural → form → material → surface → lighting → interaction → optimization — self-correcting until every identity-defining feature clears its threshold. Deterministic Python scripts handle validation and gating; model tokens are spent only on visual judgment and code.

→ Full pipeline diagram, gates, self-correction logic, script reference, and the token-efficiency design: docs/ARCHITECTURE.md

---

Quick start

1. Install — place this folder in your skills directory:

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

If you use more than one host, keep a single checkout and point each entrypoint at it as a symlink, so they cannot drift apart:

   ~/.claude/skills/img2threejs -> 
   ~/.codex/skills/img2threejs  -> 
   

2. Add domain plugins (optional) — domain knowledge (CS2 skins today) lives in installed plugins, not in this checkout. Install the img2 harness once, then add plugins to it:

   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
   

An installed domain plugin contributes its own checklist steps, evidence collection, spec augmentation (quality floors merge raise-only), and a blocking review gate — and registers its profile with forge/state.py init --profile . With no plugins installed, generic, and character are available; a profile whose plugin is missing (cs2, animated-character) fails loud naming what is installed, never silently downgrades. img2 remove reverses cleanly.

Official plugins:

| Plugin | Adds | Install | |---|---|---| | plugin-cs2 | cs2 profile — CS2 weapon-skin reconstruction: family adapters, finish rules, domain review gate | img2 add img2threejs/plugin-cs2 | | plugin-character | animated-character profile — everything character has plus the Stage R rigging/animation gates | img2 add img2threejs/plugin-character | | plugin-img2glb | image → glb emission target via the hosted TRELLIS space | img2 add img2threejs/plugin-img2glb | | plugin-hello-cube | minimal reference plugin — copy it to write your own | img2 add img2threejs/plugin-hello-cube |

Writing your own: the harness repo's docs/WRITING_A_PLUGIN.md.

3. Invoke — in Claude Code, attach or point to an object image and run:

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

That is enough: the skill classifies the subject, runs the detail inventory, and gates every pass on its own.

4. Follow the pipeline — the skill validates the image, writes an assessment and spec, generates the factory pass by pass, and shows you a side-by-side comparison at each step until the render matches.

For a multi-session reconstruction, create a local state index first:

   python3 forge/state.py init --reference  --profile character --spec object-sculpt-spec.json
   python3 forge/next.py --state .img2threejs/state.json
   

Driving it harder

The one-liner leaves the judgement calls to the skill. When you already know what "correct" means for your subject, say so — each line below maps onto a real gate or artifact in the pipeline, so it changes what gets enforced rather than just adding adjectives:

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
Fidelity   Hold proportions and silhouette to the reference. Enumerate the identity-defining
           details first — bevels and rounding, panel seams, fasteners, engraved or painted
           linework, gloss vs matte zones, wear — and drop any detail you cannot place on a
           real component instead of faking it.
Materials  Derive the finish class and gradient stops from the reference pixels, not from
           memory. Flag any colour that will not survive tone-mapping.
Runtime    Expose pivots and sockets for whatever should move, plus a userData.tick for a
           looping idle animation.
Gates      Run --strict-quality, and do not advance a pass until the side-by-side review
           passes. Report per-region confidence for anything the image cannot show.

Useful additions depending on the subject:

• A specific person or character — Maximize likeness: fit the parametric template to the landmarks, de-light and camera-match the reference, then project it. Tell me which regions are inferred.
• An animal or creature — This is a creature, not a humanoid — use the quadruped body plan and the body-unit proportion system.
• A saturated anodized or candy finish — The coat is candy-coat, not gem-metal. Keep the hue; do not let the environment steal it.
• A cost ceiling — Stay at low effort and skip the presentation composer; I only need the evaluation render.

The scripts run from the skill root and need only Python 3.10+ — nothing to install.

python3 forge/stage1_intake/probe_image.py 
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image  --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image  --assessment assessment.json --out spec.json
python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts

The factory generator repeats the strict-quality gate and is fail-closed: on failure it returns BLOCKED with the spec artifact, failure metrics, causes, and next action, and does not write a factory. --allow-nonstrict is only for explicit legacy test fixtures, never production output.

Copy-paste prompts for the GLB-reference route

Rebuilding a character from a GLB reference rather than a photo is a different route with its own gates — the GLB is a measurement instrument and never ships. Three prompts cover it, each in its own copy block:

| Prompt | Use it when | Do not use it when | |---|---|---| | Build | you have a GLB and no built surfaces yet | there is no GLB, or the build already completed and merely looks wrong | | Polish | the build completed and the result does not look like the GLB | the surfaces were never built — that is a build re-run, not a polish | | Animation | the figure looks right standing still and has passed the build gates | the surface is ungated, or joint_loops.py fails — that is a surface finding no weight tuning reaches |

They force every parameter the GLB genuinely carries — size, proportions, per-band widths and centroids, base colour, roughness and metalness — to the measured value, with the check that proves it landed. Three things are not 1:1 and each prompt says so: rigging and animation are usually absent from the asset (skinCount: 0, animationCount: 0), texture images and normal maps are deliberately not copied per this skill's code-only contract, and nothing finer than the node's cell size can be carried at all.

These are reference material, not a guarantee. They are written to be general, so the measured figures in them came from one character and are there to show what to measure — not values to copy. Run the one that matches your situation rather than all three in sequence; each notes the cost of being used out of turn.

For the script-by-script reference, the full scripts table, and expected artifacts, see docs/ARCHITECTURE.md.

---

Why it is token-efficient

Most image-to-3D agent loops burn tokens by asking the model to do mechanical work — re-reading the whole model every pass, scoring pixels, validating JSON by hand, re-running steps it already did. img2threejs pushes all of that into deterministic scripts and spends model tokens only where judgment is actually required.

• Scripts enforce, the model judges. The Python scripts handle validation, gating,