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

Three reconstructions built entirely from primitives, procedural shaders, and generated geometry. Open each one, orbit it, and read the generated source.

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

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

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

2. 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.
   

3. 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 scripts/probe_reference_image.py <image>
python3 scripts/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
python3 scripts/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
python3 scripts/validate_sculpt_spec.py spec.json --strict-quality
python3 scripts/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 deciding pass or fail.
• Zero dependencies, zero install churn. Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG read/write is done with struct and zlib. Nothing to install means nothing to debug in-context.
• Pass-gated generation. The code generator emits only the currently unlocked build pass. The model does not regenerate or re-read the entire model on every iteration — each step is small and scoped.
• Fail fast, before codegen. A strict-quality gate blocks shallow specs before a single line of Three.js is generated, so you never spend tokens rendering a model that was underspecified from the start.
• One image per review. Each pass is judged from exactly one packaged comparison sheet (reference beside render), not a scattering of screenshots.
• Text output, not binaries. The result is diffable TypeScript plus a JSON spec — small, reviewable, and version-controllable, instead of multi-megabyte mesh files.

The net effect: you still get a faithful 3D model from an image, but the expensive model context is reserved for visual judgment and code, not bookkeeping. For the full per-stage and per-cycle token breakdown, see docs/TOKEN_COST.md.

Scripts

The references/ folder holds the detailed rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).

What you get

• An ObjectSculptSpec JSON: the full component tree, materials, repetition systems, sockets, and a recorded review history for every pass.
• A TypeScript createObjectNameModel(spec, options) factory returning a THREE.Group, with root.userData.sculptRuntime exposing nodes, sockets, colliders, and destruction groups.
• A render plus comparison sheets documenting the fidelity at each pass.

Roadmap

• v1.0 — object pipeline: staged sculpt, render-vs-reference review loop, action-ready hierarchy. Shipped.
• v1.1 — detail-first analysis: required detail inventory, strict-quality gate. Shipped.
• v1.2 — humanoid character generator: anatomy track, proportion-lock and feature-placement passes. Shipped.
• v1.3 — likeness maximization: projection-first character rendering, per-region confidence. Planned.
• v1.4 — animation-ready rigs: SkinnedMesh, morph targets, glTF export. Planned.

Full detail and later milestones: ROADMAP.md. Technical specification: docs/UPGRADE_PLAN.md.

Honesty about limits

A single image cannot reveal hidden sides or guarantee exact geometry. The skill states plainly when output is approximate, stylized, or low-poly, and infers unseen faces by mirroring visible ones rather than faking confidence. It is strong for hard-surface objects; characters are stylized reconstructions, not photoreal likeness. "This cannot reach the requested fidelity from this image" is a valid, expected result.

Contributing

Contributions are welcome — procedural material recipes, new gates, host coverage, and demos especially. See CONTRIBUTING.md and the roadmap for where the project is headed.

License

MIT. See LICENSE.