img2threejs

Rebuild the object in a reference image as a code-only, procedural Three.js model.

Quality-gated, animation-ready, and deliberately token-efficient — reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.

A single reference image reconstructed in code — correct proportions, colours, bevels, gold trim, and an emissive emblem — 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. The clips below are the live models running in-browser — open each one to orbit it and read the generated source.

Demo Preview Subject View Source

Sony WF-1000XM3 Earbuds + Case

hard-surface object Live code

ISSACA 12 Gauge Shotgun

hard-surface object Live code

Gerber Paracord Knife

hard-surface object Live code

Doraemon House (isometric diorama)

hard-surface object Live code

War-Hauler "SECTOR 07"

hard-surface object Live code

Crowned Loot Chest

hard-surface object Live code

The gallery source lives in hoainho/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.

How it works

The skill runs a staged sculpting pipeline. Scripts gate each stage; the agent's vision is the only thing that can approve a pass.

flowchart TD
    A[Reference image] --> B[Probe and suitability gate]
    B --> C[Pre-Spec Assessment: class, complexity, quality contract]
    C --> D[Author ObjectSculptSpec: components, materials, sockets]
    D --> E{Validate and strict-quality}
    E -- too shallow --> D
    E -- ok --> F[Locked build passes]
    F --> G[Generate Three.js factory: current pass only]
    G --> H[Render in browser and screenshot]
    H --> I[Package one side-by-side sheet]
    I --> J{Agent vision review}
    J -- score below threshold --> K[Self-correct: refine-spec or refine-code]
    K --> F
    J -- pass --> L{More passes?}
    L -- yes --> F
    L -- no --> M[Animation-ready Three.js model]

Build passes

The model is sculpted in a fixed order; a pass unlocks only after the previous one is reviewed and accepted:

blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass

Each pass has its own acceptance criteria. A pass is marked continue only with a real render, a comparison sheet, an agent-vision score at or above threshold, and every identity-defining feature at or above its own threshold.

The gates

• Suitability — is the image a viable 3D target at all.

• Pre-spec and strict-quality — blocks code generation until the spec is deep enough for the object's complexity (no single-root spec for a compound object).

• Screenshot feedback — continue requires a render plus a comparison sheet plus a passing vision score.

• Action-ready — the model exposes a runtime hierarchy (pivots, sockets, colliders, destruction groups) via root.userData.sculptRuntime.

• Attachment correctness — child parts (handles, limbs, tubes) declare how they join their parent, so nothing floats in mid-air.

• Material and lighting realism — independent PBR channels and real lights, never albedo aliased into roughness.

Self-correction

After every pass the agent chooses exactly one action: continue, refine-spec, refine-code, request-input, or stop. refine-spec fixes a wrong or shallow spec and re-validates; refine-code fixes geometry, material, or lighting that does not match a sound spec.

Quick start

Install — place this folder in your skills directory:

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

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.

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.

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

python3 forge/stage1_intake/probe_image.py <image>
python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <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

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, spec authoring, PBR extraction, comparison-sheet packaging, and pipeline state. They never score visuals. The model's tokens go to one thing: looking at a single side-by-side sheet and decidin