img2threejs

// Overview

img2threejs takes a single reference image of an object and produces a TypeScript factory that returns a `THREE.Group` recreating that object from primitives, procedural shaders and generated geometry. The output is code rather than a mesh file — no photogrammetry, no mesh extraction, no downloaded art packs — and it carries a runtime hierarchy of pivots, sockets and colliders so the result can be animated instead of sitting inert.

It runs as a skill inside a coding agent — Claude Code, Codex or OpenCode — and is deliberately agent-agnostic: wherever its documentation calls for agent vision or an agent browser tool, it uses whatever the host provides, whether native image reading, a browser MCP, the project preview or a screenshot you supply. Work proceeds through a staged sculpting pipeline (blockout → structural → form → material → surface → lighting → interaction → optimization) in which each pass is generated, vision-reviewed against the reference and self-corrected until every identity-defining feature clears its threshold. Deterministic Python scripts do the validation and gating, so model tokens are spent on visual judgement and code rather than bookkeeping.

Subjects are classified as object, character or hybrid, with characters routed through an anatomy-aware track and objects through a hard-surface pipeline. Before any code is generated the pipeline enumerates a `detailInventory` of identity-defining small details — gloss, bevels, screws and rivets, engraved linework, contours, stains and wear — and a strict-quality gate blocks generation until every entry maps to a real component or material. Domain knowledge lives in installable plugins rather than the core checkout, and the project is candid about its ceiling: a single image cannot reveal hidden sides, unseen faces are inferred by mirroring visible ones, and "this cannot reach the requested fidelity from this image" is treated as a valid result.

// What it does

• Turns one reference image into a TypeScript `createObjectNameModel(spec, options)` factory returning an animation-ready `THREE.Group`
• Staged sculpt pipeline — blockout, structural, form, material, surface, lighting, interaction, optimization — with a vision review and self-correction at each pass
• Required `detailInventory` pass plus a strict-quality gate that blocks code generation until every identity-defining detail maps to a real component or material
• Object, character and hybrid subject tracks, with characters routed through an anatomy-aware pipeline and skinned-mesh rigging data on `root.userData.rig`
• Domain plugins installed through the `img2` harness (`img2 install / add / doctor`), including CS2 weapon skins, animated characters and a GLB emission target
• Resumable multi-session workflow: `forge/state.py` records an evidence-backed checklist and `forge/next.py` picks the reconstruction back up
• Optional multi-view silhouette carving that records unseen areas as low-confidence instead of inventing hidden detail

// Getting started

img2threejs installs as a skill in your agent's skills directory and is invoked from the agent with a reference image. If you use more than one host, keep one checkout and symlink each host's entrypoint at it so they cannot drift apart.

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

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

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

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

object-sculpt-spec.json      # component tree, materials, sockets, review history
createObjectNameModel.ts     # THREE.Group factory
# plus render and comparison sheets per pass

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Recreate a product, prop or weapon from a single reference photo as editable, diffable code instead of an opaque mesh file
• Produce animation-ready 3D assets whose pivots, sockets and colliders are already wired up
• Keep a web 3D scene token-efficient and download-free by shipping generated geometry code rather than model files
• Add a domain of your own — its checklist steps, quality floors and blocking review gate — by writing an img2 plugin

// How img2threejs compares

img2threejs alongside other open-source 3d & cad generation tools AI/TLDR tracks, ranked by GitHub stars.