翻GitHub时挖到一个让人眼前一亮的项目——上传一张普通照片，它能自动识别物体结构、比例和材质，直接生成完整的3D模型。

说几个让我觉得路子很野的设计：

出厂自带“半成品”属性——生成的模型不是死板的照片贴图，而是包含清晰层级与碰撞体组件，拿来就能直接做动画或开发游戏，不用再二次加工。

计算稳不崩塌——内置Python自动化校验机制，把复杂的几何数学计算交给脚本，AI只专心理解结构和生成，产出质量极其稳定。

改模型像改代码一样简单——调整参数、加动画或改逻辑，全在代码里敲几行就能搞定，彻底告别建模软件里来回手动修改的折磨。

不管你是前端开发者、游戏制作人还是3D爱好者，这工具都能把创作效率往上拽一大截。

https://github.com/img2threejs/img2threejs…

img2threejs/img2threejs

Source: https://github.com/img2threejs/img2threejs

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.

	DAILY	WEEKLY
Python
All languages

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.

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. See docs/cs2/review-gates.md.
• Resumable local workflow. forge/state.py records an ordered, evidence-backed intake/pass checklist for generic, character, and CS2 profiles. 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 -> <your checkout>
   ~/.codex/skills/img2threejs  -> <your checkout>
   

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.
   

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

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.

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

   python3 forge/state.py init --reference <image> --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 <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

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.

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, 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 grimoire/ 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).

Optional reference-fidelity tooling

The stdlib-only core can use an isolated evidence layer without taking on runtime dependencies: SAM2 component masks, Depth Anything V2 relative-depth priors, MediaPipe face/pose landmarks, Chrome DevTools diagnostics, Three.js scene inspection, Playwright cross-browser fallback, and version-aware Context7 retrieval. These tools never approve a pass or silently provide geometry. Install, routing, provenance rules and exact commands: docs/integrations/reference_fidelity_tooling.md.

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. For the script-by-script reference and the full list of output artifacts, see docs/ARCHITECTURE.md.

Roadmap

Shipped:

• v1.0 — object pipeline: staged sculpt, render-vs-reference review loop, action-ready hierarchy.
• v1.1 — detail-first analysis: required detail inventory, strict-quality gate.
• v1.2 — humanoid character generator: anatomy track, proportion-lock and feature-placement passes.
• v1.3 — quality & efficiency: the Divine Eye deterministic review harness, input-integrity and geometry-truth gates, reference-grounded texture and gradient analysis, CIEDE2000 colour math.
• v1.4 — The Weapon Update — CS2 image-matched reconstruction: provenance-aware intake, projection-first finishes, family-specific weapon adapters, and structural review gates.
• v1.4.1 — CS2 hardening: explicit component coverage, a dedicated Glock-18 assembly contract, map-stripped blockout evidence, and stricter geometry-integrity checks.
• creature generator — 4 body plans (quadruped / avian / winged-dragon / serpentine), animalAnatomy spec, spine-loft geometry, ΔE00 colour gates.

Next — one theme per release:

• v1.5 — The Character Update (in progress): character reconstruction, facial features, rigging-ready topology, blendshape preparation, hair and clothing.
• v1.6 — The Environment Update: buildings, rooms, streets, vegetation, terrain-aware and multi-object reconstruction.
• v1.7 — The Game Pipeline Update: Unity and Unreal exporters, a Blender bridge, LOD and collision-mesh generation.
• v1.8 — The Animation Update: auto rigging, auto skin weights, Mixamo compatibility, facial rig.
• v1.9 — The AI Studio Update: web UI, batch processing, visual prompt builder, cloud rendering.
• v2.0 — The Procedural World Update: multi-view reconstruction, procedural city generation, semantic world understanding, plugin ecosystem and API.

The arc: assets (v1.4–v1.5) → worlds (v1.6–v1.7) → production (v1.8–v1.9) → an AI game-asset platform that generates playable worlds from reference images (v2.0).

→ Full roadmap — per-version detail, the four-phase long view, and the tracked capability gaps: 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.

Star history

If img2threejs is useful to you, a star helps others find it.

Support the project

img2threejs is free and open source. If it saved you time or found its way into your project, consider supporting continued development:

VietQR / MoMo / PayPal also work — see the donate page. VietQR / MoMo / PayPal also work — see the donate page.

Sponsors

Atlas Cloud is a full-modal AI inference platform that gives developers a single AI API to access video generation, image generation, and LLM APIs. Instead of managing multiple vendor integrations, you connect once and get unified access to 300+ curated models across all modalities. Check out Atlas Cloud’s new coding plan promotion for more budget-friendly API access: https://www.atlascloud.ai/console/coding-plan

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

Apache License 2.0. See LICENSE.