img2threejs: How to Turn an Image into Procedural Three.js

img2threejs rebuilds the object in a reference image as a code-only, procedural, animation-ready Three.js model. You get a TypeScript factory and a sculpt spec—not an opaque mesh download. This guide walks through install, photo prep, prompts, review passes, and common pitfalls.

Official sources:

• Skill: github.com/img2threejs/img2threejs
• Live gallery: img2threejs.github.io/img2threejs-showcase
• Hosted product (optional): img2threejs.org

What you get when it works

A successful run typically produces:

1. A create…Model() Three.js Group factory in TypeScript
2. An ObjectSculptSpec JSON describing components, materials, and hierarchy
3. Runtime hooks—pivots, sockets, colliders, and often a userData.tick idle animation

That output is meant to be diffed, reviewed, and wired into your scene like normal code.

Step 1 — Install the skill

Clone into your agent skills directory (Claude Code example):

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

If you use more than one host (Claude Code, Codex, OpenCode), keep one checkout and symlink each entrypoint to it so copies cannot drift:

~/.claude/skills/img2threejs -> <your checkout>
~/.codex/skills/img2threejs  -> <your checkout>

Scripts need Python 3.10+ standard library only—no pip install for the core forge tools.

Step 2 — Prepare a good reference image

The pipeline is gated on what the photo actually shows. Better input means fewer blocked passes.

Start with hard-surface objects (earbuds case, knife, vehicle, chest). Character likeness and multi-view carving are advanced paths—learn the object workflow first.

Browse the live showcase before your first run: open a few demos, orbit them, and note which reference photos produce convincing structure and animation.

Step 3 — Invoke the skill

In Claude Code (or your host), attach the image and run something like:

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

That one-liner is enough for a default run: classify subject, build a detail inventory, then generate pass by pass under quality gates.

Stronger prompts when you know the bar

Spell constraints that map to real gates—not vague adjectives:

/img2threejs Rebuild the subject in this image as a procedural Three.js model.
 
Fidelity   Hold proportions and silhouette to the reference. Enumerate identity-defining
           details first — bevels, 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 finish class and gradient stops from the reference pixels, not memory.
Runtime    Expose pivots and sockets for whatever should move, plus a userData.tick for
           a looping idle animation.
Gates      Run --strict-quality. Do not advance a pass until side-by-side review passes.
           Report per-region confidence for anything the image cannot show.

Useful add-ons:

• Specific person or character — ask for likeness maximization, landmark fit, and which regions are inferred
• Creature / animal — say it is not humanoid; request the correct body plan
• Candy / anodized finishes — name the coat class so environment lighting does not steal the hue
• Budget — ask for low effort and skip presentation composer if you only need evaluation renders

Step 4 — Follow the pipeline (do not skip gates)

img2threejs stages reconstruction roughly as:

blockout → structural → form → material → surface → lighting → interaction → optimization

Deterministic Python scripts validate specs and gate progress. Model tokens are spent on visual judgment and code, not bookkeeping.

Practical habits:

1. Let strict-quality block shallow specs — fixing the inventory early is cheaper than regenerating a whole factory
2. Review one comparison sheet per pass — reference beside render; pass or fail with notes
3. Resume with state for long subjects — init a local state index, then continue with forge/next.py --state
4. Prefer fail-closed — if factory generation is BLOCKED, fix the listed metrics before forcing codegen

Manual script entry points (from the skill root) look like:

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

Use the README and docs/ARCHITECTURE.md in the repo for the full script table and artifact layout.

Step 5 — Drop the factory into your Three.js app

Once you have createObjectNameModel.ts:

1. Import the factory next to your other scene builders
2. Add the returned THREE.Group to the scene
3. Hook lights and an orbit camera similar to the showcase viewer
4. If userData.tick (or documented pivots) exists, call it from your animation loop
5. Commit the TypeScript factory + spec JSON so reviews stay text-diffable

Do not treat the first pass as final art direction—treat it as a gated draft you can refine with another skill invocation or hand edits.

Showcase workflow (optional but useful)

Before or after generating:

1. Open the showcase gallery
2. Pick subjects close to yours (material class, complexity, animation needs)
3. Enter a demo: drag to orbit, scroll to zoom
4. Compare the reference photo to the live model
5. Steal the bar: what details were modeled as geometry vs faked as texture

If you later contribute a demo, follow the showcase repo’s CONTRIBUTING.md and npm run new-demo flow.

When to use something else

FAQ

Do I need to install Python packages?

Core forge scripts are designed for Python 3.10+ stdlib only. Follow the skill README if a profile adds optional tooling.

Can one photo guarantee perfect likeness?

No. Unseen sides are inferred or left low-confidence. Ask the skill to report per-region confidence, and supply more views when likeness matters.

Why did generation stop with BLOCKED?

Strict-quality gates refuse shallow specs before codegen. Read the failure metrics, complete the detail inventory or material evidence, then retry—do not disable strict mode for production subjects.

Where do I learn expected quality?

Orbit finished exhibits in the live gallery, then match that bar with your own reference photo and the prompts above.