Skip to content

Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.

docs: themed roadmap v1.4-v2.0, v1.2/v1.3 changelog detail, advanced prompt example

Hoài Nhớbd5b504f5bce
diff --git a/README.md b/README.md
index 85d4965..56c87da 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ Quality-gated, animation-ready, and deliberately token-efficient — reconstruct
*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](https://hoainho.github.io/img2threejs-showcase/)
+### [→ Open the Live Demo Gallery](https://img2threejs-showcase.pages.dev/)
Every model in the gallery is generated code, running in your browser. No mesh files, no downloads.
@@ -34,14 +34,14 @@ Reconstructions built entirely from primitives, procedural shaders, and generate
| Demo | Preview | Subject | View | Source |
| --- | --- | --- | --- | --- |
-| Sony WF-1000XM3 Earbuds + Case | <img src="assets/sony-wf1000xm3.gif" width="260" alt="Sony WF-1000XM3 live demo" /> | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/sony-wf1000xm3) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/sony-wf1000xm3/createSonyWf1000xm3Model.ts) |
-| ISSACA 12 Gauge Shotgun | <img src="assets/issaca-shotgun.gif" width="260" alt="ISSACA 12 Gauge Shotgun live demo" /> | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/issaca-shotgun) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/issaca-shotgun/createIssacaShotgunModel.ts) |
-| Gerber Paracord Knife | <img src="assets/gerber-knife.gif" width="260" alt="Gerber Paracord Knife live demo" /> | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/gerber-knife) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/gerber-knife/createGerberKnifeModel.ts) |
-| Doraemon House (isometric diorama) | <img src="assets/doraemon-house.gif" width="260" alt="Doraemon House live demo" /> | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/doraemon-house) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/doraemon-house/createDoraemonHouseModel.ts) |
-| War-Hauler "SECTOR 07" | <img src="assets/warhauler.gif" width="260" alt="War-Hauler SECTOR 07 live demo" /> | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/warhauler) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/warhauler/createWarHaulerModel.ts) |
-| Crowned Loot Chest | <img src="assets/crown-chest.gif" width="260" alt="Crowned Loot Chest live demo" /> | hard-surface object | [Live](https://hoainho.github.io/img2threejs-showcase/#/demo/crown-chest) | [code](https://github.com/hoainho/img2threejs-showcase/blob/main/src/demos/crown-chest/createCrownChestModel.ts) |
+| Sony WF-1000XM3 Earbuds + Case | <img src="assets/sony-wf1000xm3.gif" width="260" alt="Sony WF-1000XM3 live demo" /> | hard-surface object | [Live](https://img2threejs-showcase.pages.dev/#/demo/sony-wf1000xm3) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/sony-wf1000xm3/createSonyWf1000xm3Model.ts) |
+| ISSACA 12 Gauge Shotgun | <img src="assets/issaca-shotgun.gif" width="260" alt="ISSACA 12 Gauge Shotgun live demo" /> | hard-surface object | [Live](https://img2threejs-showcase.pages.dev/#/demo/issaca-shotgun) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/issaca-shotgun/createIssacaShotgunModel.ts) |
+| Gerber Paracord Knife | <img src="assets/gerber-knife.gif" width="260" alt="Gerber Paracord Knife live demo" /> | hard-surface object | [Live](https://img2threejs-showcase.pages.dev/#/demo/gerber-knife) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/gerber-knife/createGerberKnifeModel.ts) |
+| Doraemon House (isometric diorama) | <img src="assets/doraemon-house.gif" width="260" alt="Doraemon House live demo" /> | hard-surface object | [Live](https://img2threejs-showcase.pages.dev/#/demo/doraemon-house) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/doraemon-house/createDoraemonHouseModel.ts) |
+| War-Hauler "SECTOR 07" | <img src="assets/warhauler.gif" width="260" alt="War-Hauler SECTOR 07 live demo" /> | hard-surface object | [Live](https://img2threejs-showcase.pages.dev/#/demo/warhauler) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/warhauler/createWarHaulerModel.ts) |
+| Crowned Loot Chest | <img src="assets/crown-chest.gif" width="260" alt="Crowned Loot Chest live demo" /> | hard-surface object | [Live](https://img2threejs-showcase.pages.dev/#/demo/crown-chest) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/crown-chest/createCrownChestModel.ts) |
-The gallery source lives in [hoainho/img2threejs-showcase](https://github.com/hoainho/img2threejs-showcase). If this project is useful, a star on this repo helps others find it.
+The gallery source lives in [img2threejs/img2threejs-showcase](https://github.com/img2threejs/img2threejs-showcase). If this project is useful, a star on this repo helps others find it.
---
@@ -110,7 +110,7 @@ After every pass the agent chooses exactly one action: `continue`, `refine-spec`
1. **Install** — place this folder in your skills directory:
```bash
- git clone https://github.com/hoainho/img2threejs.git ~/.claude/skills/img2threejs
+ git clone https://github.com/img2threejs/img2threejs.git ~/.claude/skills/img2threejs
```
2. **Invoke** — in Claude Code, attach or point to an object image and run:
@@ -119,8 +119,36 @@ After every pass the agent chooses exactly one action: `continue`, `refine-spec`
/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.
+### 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.
```bash
@@ -182,13 +210,27 @@ The `grimoire/` folder holds the detailed rubrics each gate applies (validation,
## 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.*
+**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.
+- **creature generator** — 4 body plans (quadruped / avian / winged-dragon / serpentine), `animalAnatomy` spec, spine-loft geometry, ΔE00 colour gates.
+
+**Next — one theme per release:**
+
+- **v1.4 — The Weapon Update** *(shipping soon)*: a 1:1 photorealistic, non-stylized pipeline for CS2-class hard-surface assets — strict PBR standards and texture projection, mechanical reasoning about the assembly, and true metal / polymer / wood response.
+- **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 detail and later milestones: [ROADMAP.md](ROADMAP.md). Technical specification: [docs/UPGRADE_PLAN.md](docs/UPGRADE_PLAN.md).
+**→ Full roadmap** — per-version detail, the four-phase long view, and the tracked capability gaps: **[ROADMAP.md](ROADMAP.md)**. Technical specification: [docs/UPGRADE_PLAN.md](docs/UPGRADE_PLAN.md).
---
diff --git a/ROADMAP.md b/ROADMAP.md
index 5c60933..23d4631 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -1,38 +1,204 @@
# img2threejs Roadmap
-This roadmap outlines the planned evolution of img2threejs from its initial release through major feature additions. For the full technical specification, requirements, and acceptance criteria, see [docs/UPGRADE_PLAN.md](docs/UPGRADE_PLAN.md).
+Where img2threejs is going: from rebuilding one object at a time to generating whole playable
+worlds from reference images. For the full technical specification and acceptance criteria of
+in-flight work, see [docs/UPGRADE_PLAN.md](docs/UPGRADE_PLAN.md).
-## Version status
+Each release has one theme. That is deliberate — a version people can name is a version people
+can plan around.
-| Version | Theme | Status | Highlights |
+## Shipped
+
+| Version | Theme | Date | Highlights |
+|---|---|---|---|
+| v1.0 | Object pipeline | 2026-07-15 | Staged sculpt pipeline (blockout through optimization), render-vs-reference review loop, action-ready runtime hierarchy |
+| v1.1 | Detail-first analysis | 2026-07-15 | Required `detailInventory` artifact (gloss, bevel, fasteners, linework, stains), strict-quality gate blocking shallow specs before codegen |
+| v1.2 | Humanoid character generator | 2026-07-21 | Character/hybrid domain detection, anatomy-aware track, proportion-lock and feature-placement gated passes, per-part character materials |
+| v1.3 | Quality & efficiency (Divine Eye) | 2026-07-22 | Deterministic multi-signal review harness, input-integrity and geometry-truth gates, reference-grounded texture/material analysis, CIEDE2000 colour math |
+| — | Creature generator | 2026-07-23 | 4 body plans (quadruped / avian / winged-dragon / serpentine), `animalAnatomy` spec, spine-loft (RMF) / membrane-wing / instanced-scale geometry, ΔE00 colour gates, straight-bind rig data |
+
+> **Note on numbering.** The creature-generator tranche is shipped but currently tagged `1.4.0` in
+> `CHANGELOG.md`, and `SKILL.md` reads `1.5.0`. Both are being re-tagged onto a `1.3.x` line so that
+> v1.4 onward can carry the themed roadmap below.
+
+### v1.2 — Humanoid character generator
+
+Characters and hybrid subjects became first-class citizens of the pipeline, alongside a round of
+engine work on the code generator itself.
+
+- **Character / hybrid domain detection** — assessment recognises character-like form language and
+ routes the reconstruction through an anatomy-aware track instead of the hard-surface object path.
+- **Humanoid component template** — measured head-unit proportions, facial landmark placement, and
+ pose alignment emitted from the assessment stage.
+- **Proportion-lock build pass** — a gated pass enforcing anatomical proportion correctness before
+ any form or material work proceeds.
+- **Feature-placement build pass** — a gated pass placing and validating facial and body landmarks
+ against the reference.
+- **Per-part character materials** — skin, hair, cloth, and accessory materials wired into the
+ detail machinery, for stylized figures with recognisable likeness.
+- **Surface-topology classification** — parts classified by surface topology to drive more accurate
+ geometry choices, with per-part colour / RGBA recipes for tighter reference matching.
+- **Real extrude / lathe / tube geometry** — genuine geometry generation replaced the prior
+ approximations; plus tier-1 diagnostics and content-hash caching across passes.
+
+### v1.3 — Quality & efficiency (Divine Eye)
+
+The review harness became deterministic-first: signals are computed by scripts, and the model's
+judgment is spent only where a script cannot decide.
+
+- **Divine Eye** — a deterministic multi-signal ensemble (`divine_eye.py`): IoU and scale hard
+ gates; proportion, symmetry-parity, pHash, SSIM, edge, blowout, flatness, and tonal-parity soft
+ signals; self-uncertainty `probe` routing.
+- **Input integrity** — reference admission and intake-correctness cross-checks, property
+ auto-binding, shared pHash.
+- **Geometry truth** — curve-sweep, a flatness gate, and Blum lathe-profile derivation.
+- **Multi-angle** — degenerate-view detection with reference-free self-consistency, plus
+ auto-framing.
+- **Eye judgment layers** — a gated VLM check, per-feature verification, a bounded stop policy, and
+ a calibration harness (report-only, with a separation check).
+- **Texture-finish analysis** — classifies finish (gem-metal / gemstone / painted-metal /
+ worn-composite / brushed-steel / plastic / `candy-coat`) and writes doc-grounded
+ `MeshPhysicalMaterial` scalars. The `candy-coat` recipe exists so a saturated anodized or doppler
+ coat keeps its hue instead of the environment stealing it.
+- **Reference-grounded gradient stops** — foreground-masked per-band median sampling extracts a
+ material's true gradient from the reference instead of hand-guessing it, and flags blue-leaning
+ stops that would collapse to blue under tone-mapping.
+- **CIEDE2000 colour math** — full ΔE00 (`_shared/color_metrics.py`), verified against the canonical
+ Sharma test pairs, feeding report-only `hue_zone_parity` and `specular_wash` signals that catch
+ "purple rendered blue" where luma and structure signals cannot.
+- **Objectness** — a pure-stdlib HOG-like descriptor and cosine similarity, wired in as a soft
+ signal plus a reconstruction-mode rescue.
+- **Efficiency** — per-module codegen cache with neighbour invalidation.
+- **Presentation** — reference-conditional post-fx (DOF / bloom) kept strictly off the evaluation
+ path, so bloom cannot blow highlights the gate is measuring.
+
+## Roadmap
+
+| Version | Theme | Primary goal | Highlights |
|---|---|---|---|
-| v1.0 | Object pipeline | Shipped | Staged sculpt pipeline (blockout through optimization), render-vs-reference review loop, action-ready runtime hierarchy |
-| v1.1 | Detail-first analysis | Shipped | Required detailInventory artifact (gloss, bevel, fasteners, linework, stains), strict-quality gate blocking shallow specs before codegen |
-| v1.2 | Humanoid character generator | Shipped | Character/hybrid domain detection, anatomy and facial landmarks, proportion-lock and feature-placement build passes, per-part character materials |
-| v1.3 | Likeness maximization | Planned | Projection-first path wired into character rendering (camera solve, de-lighting, texture projection), opt-in generativeAssist mode with confidence reporting, high-likeness character demo |
-| v1.4 | Animation-ready rigs | Planned | True humanoid rig and pivot hierarchy (replacing current world-space flatten), SkinnedMesh with morph targets, glTF export |
-| v1.5 | Ecosystem | Planned | Expanded live demo gallery accepting community demos via pull request, broader host and agent coverage, measured token-cost benchmark replacing current estimates |
+| **v1.4** | Weapon Pipeline | Become the best tool for hard-surface game assets | Weapon reconstruction accuracy · better mechanical reasoning · better materials (metal, polymer, wood) · optimized cost & speed · better prompting & docs |
+| **v1.5** | Character Pipeline | Start supporting characters properly | Character reconstruction · facial features · rigging-ready topology · blendshape preparation · hair & clothing improvements |
+| **v1.6** | Environment Pipeline | Build scenes, not just objects | Buildings · rooms · streets · trees & vegetation · terrain-aware generation · multi-object reconstruction |
+| **v1.7** | Game Pipeline | Game-ready assets | Unity exporter · Unreal exporter · Blender bridge · FBX / OBJ / glTF improvements · LOD generation · collision mesh generation |
+| **v1.8** | Animation Pipeline | Move assets into production | Auto rigging · auto skin weights · Mixamo compatibility · facial rig · lip-sync preparation · animation-ready exports |
+| **v1.9** | AI Studio | Cut the manual work | Web UI · drag & drop workflow · batch processing · visual prompt builder · project management · cloud rendering · public showcase integration |
+| **v2.0** | Procedural World Generation | Whole worlds from reference images | Multi-view reconstruction · large scene generation · semantic world understanding · procedural city generation · interior reconstruction · multi-agent generation pipeline · plugin ecosystem & API |
+
+### Release names
+
+- **v1.4 — The Weapon Update**
+- **v1.5 — The Character Update**
+- **v1.6 — The Environment Update**
+- **v1.7 — The Game Pipeline Update**
+- **v1.8 — The Animation Update**
+- **v1.9 — The AI Studio Update**
+- **v2.0 — The Procedural World Update**
## Version details
-### v1.0 - Object pipeline
-The foundational release introduces the staged reconstruction pipeline for hard-surface objects. Images are analyzed for suitability, authored into an ObjectSculptSpec describing components and materials, then generated pass by pass as Three.js code. Each pass gates on a visual review using side-by-side comparison sheets. The result exposes a runtime hierarchy (pivots, sockets, colliders) ready for animation.
+### v1.4 — The Weapon Update · *shipping soon*
+
+A 1:1 photorealistic, non-stylized rendering pipeline for CS2-class hard-surface assets, built on
+strict PBR standards and texture projection. Where earlier versions accepted a stylized read of a
+weapon, v1.4 targets reference-exactness: correct metal response, correct polymer sheen, correct
+wood grain, and a projected-texture path that puts the reference's own pixels onto the observed
+surfaces instead of approximating them.
+
+Mechanical reasoning improves alongside the materials. A weapon is an assembly with function —
+slide, magazine well, trigger group, rail, muzzle — and the pipeline reasons about those parts as
+mechanism rather than silhouette, which is what makes seams, insets, and part boundaries land where
+a player expects them. Cost and speed are tuned in the same tranche, and the prompting guidance and
+docs are rewritten around the weapon workflow.
+
+### v1.5 — The Character Update
-### v1.1 - Detail-first analysis
-Micro-detail capture becomes a required, evidence-linked artifact with its own validation gate. A detail inventory enumerates identity-defining small features (gloss zones, bevels, screws and rivets, engraved or painted lines, contours, stains and wear). Every detail must map to a real component or material entry, and the strict-quality gate blocks code generation until the inventory is complete and linked. This prevents shallow specs from reaching the renderer.
+Characters become a first-class subject rather than a stylized approximation. Facial features get
+dedicated treatment, and the output topology is built to be rigged: clean, predictable loops that
+deform without artifacts, plus blendshape preparation so expression work has somewhere to attach.
+Hair and clothing — the two things that most often break a code-built character — get their own
+material and geometry improvements.
-### v1.2 - Humanoid character generator
-Characters and hybrid subjects are now first-class. The pipeline detects character-like form language and routes the reconstruction through an anatomy-aware track. A humanoid component template with measured head-unit proportions, facial landmark placement, and pose alignment emerges from the assessment. Build passes for proportion-locking and feature-placement gate on anatomical correctness. Per-part character materials (skin, hair, cloth, accessories) integrate with the Track A detail machinery, producing stylized human figures with correct proportions and recognizable likeness.
+### v1.6 — The Environment Update
-### v1.3 - Likeness maximization
-The projection-first path maximizes likeness for specific people or characters. A parametric humanoid template is fitted to image landmarks, the reference photo is de-lit and camera-matched, then projected onto the fitted mesh as texture. This achieves significantly higher visual fidelity than hand-authored primitives. An optional, clearly flagged generativeAssist mode allows import of a base mesh from external image-to-3D generators, then applies the same projection and material pipeline. Per-region confidence reporting acknowledges unobservable areas (back, sides, occluded geometry) and requests additional views when fidelity matters. A high-likeness character demo showcases the technique.
+The unit of reconstruction grows from one object to a scene. Buildings, rooms, and streets become
+buildable subjects; trees and vegetation get procedural treatment suited to code-only generation;
+and generation becomes terrain-aware, so objects sit in a scene rather than floating in a void.
+Multi-object reconstruction lands here: one reference image, several subjects, correct relative
+placement and scale.
-### v1.4 - Animation-ready rigs
-The character rig moves from a flattened world-space hierarchy to a proper animated skeleton with named joints (neck, shoulders, elbows, hips, knees, ankles). SkinnedMesh deformation and morph targets enable facial expression and body deformation. Clean, predictable mesh topology supports blendshape deformation without artifacts. The rig and morph channels export as glTF and integrate with industry-standard animation tools and game engines.
+### v1.7 — The Game Pipeline Update
+
+Assets stop being Three.js-only. First-class exporters for Unity and Unreal, a Blender bridge, and
+improved FBX / OBJ / glTF output make a generated model something you can drop into an existing
+production pipeline. LOD generation and collision-mesh generation cover the two things every engine
+asks for and no image-to-3D tool ships by default.
+
+### v1.8 — The Animation Update
+
+Rigging becomes automatic: skeleton generation, skin weights, and a facial rig, with Mixamo
+compatibility so existing animation libraries apply without hand work. Lip-sync preparation and
+animation-ready exports close the gap between "a model exists" and "a character performs".
+
+### v1.9 — The AI Studio Update
+
+The pipeline gets a front door for people who don't live in a terminal: a web UI with a
+drag-and-drop workflow, batch processing for more than one asset at a time, a visual prompt builder,
+project management, and cloud rendering. Public showcase integration wires the studio directly to
+the [live gallery](https://img2threejs-showcase.pages.dev/), so publishing a result is a button
+rather than a pull request.
+
+### v2.0 — The Procedural World Update
+
+Multi-view reconstruction removes the single-image blind-side limit that has bounded every prior
+version. Large scene generation, semantic world understanding, procedural city generation, and
+interior reconstruction combine into a pipeline that produces a place rather than a prop, driven by
+a multi-agent generation pipeline. A plugin ecosystem and public API make the whole thing
+extensible by other people.
+
+## The long view
+
+**Phase 1 (v1.4–v1.5) — Assets.** Build high-quality individual assets: weapons, props, characters.
+
+**Phase 2 (v1.6–v1.7) — Worlds.** Build environments and game-ready content: buildings, vegetation,
+streets, export pipelines.
+
+**Phase 3 (v1.8–v1.9) — Production.** Turn generated assets into production-ready content: rigging,
+animation, Blender, Unity, Unreal, and a web platform.
+
+**Phase 4 (v2.0) — AI game-asset platform.** Generate entire playable worlds from reference images:
+multi-view understanding, procedural world generation, AI planning, a full ecosystem, and
+extensible APIs and plugins.
+
+## Known gaps (deep-research audit — 2026-07-22)
+
+A capability audit (NotebookLM research + `file:line` code-map) enumerated Three.js / tech-art
+features the skill does not yet cover. Recorded here so they are tracked, not lost. Most are
+**irrelevant to hard-surface static props** and now map onto a themed version above; one is a real
+latent bug.
+
+| # | Gap | Status / plan | Priority |
+|---|---|---|---|
+| G1 | SkinnedMesh + Bones + Morph targets (organic deform, facial expression) | Roadmap **v1.8 — Animation** (rig-ready topology prepared in v1.5) | deferred |
+| G2 | glTF / GLB export + AnimationMixer (engine portability) | Roadmap **v1.7 — Game Pipeline** | deferred |
+| G3 | **InstancedMesh — real latent bug**: `instanced-cluster` in `VALID_PRIMITIVES` has no `geometry_for()` branch; repetition systems emit a hand-rolled `Mesh` clone loop, not `InstancedMesh` (`generate_threejs_factory.py:1091-1146`) | **Hotfix in progress** | high |
+| G4 | UV unwrapping / atlas, normal+AO baking (high→low), LOD, BVH; procedural-UV seams stretch at primitive joins | Partial today (procedural cyl/triplanar UV + height→normal). Baking and LOD land in **v1.7** | med |
+| G5 | WebGPURenderer + TSL node materials | Deferred — architecture, not render quality | low |
+| G6 | Topology / retopology / CSG boolean-merge (clean welded mesh for skinning) | Feeds **v1.5** rigging-ready topology; `three-bvh-csg` is for export/skinning, not static-prop quality | low |
-### v1.5 - Ecosystem
-The project expands beyond a single skill into a broader ecosystem. A live demo gallery on the project site showcases community reconstructions accepted via pull request, lowering the barrier to sharing results. Coverage extends to more Claude hosts (Codex, OpenCode) and browser automation MCPs. Token costs are measured empirically across real reconstructions rather than estimated, replacing the current engineering-estimate model with a reproducible benchmark. This version solidifies the pipeline as a reference implementation for single-image 3D reconstruction by code.
+**Corrections to the audit (verified against code):**
+- *"IBL/PMREM not integrated"* — **inaccurate.** The generator emits `create<Type>Environment(renderer)`
+ via `PMREMGenerator.fromScene(new RoomEnvironment())` (`generate_threejs_factory.py:1209-1210`);
+ the showcase `Viewer` also builds a PMREM environment. IBL **is** integrated.
+- *"Only a plain WebGLRenderer / no post-processing"* — **half-true by design.** The generator emits a
+ `create<Type>PresentationComposer` (bloom/DOF) for the hero render, but deliberately keeps the
+ evaluation render composer-free (`generate_threejs_factory.py:1251`: "plain renderer with NO
+ composer — bloom blows highlights and DOF blurs edges"). A bright HDRI/bloom on the *eval* path
+ would also **steal hue** from candy/anodized coats — so it must stay off the eval path.
## Contributing
-img2threejs welcomes contributions. For planning or submitting work on v1.3 and later features, see [CONTRIBUTING.md](CONTRIBUTING.md). Feature requests and bug reports help prioritize future releases. The roadmap is responsive to real-world usage and feedback from the open-source community.
+img2threejs welcomes contributions, and the roadmap is responsive to real usage. If you want to work
+on something above, see [CONTRIBUTING.md](CONTRIBUTING.md) — say which version's theme your work
+belongs to so it lands in the right tranche. Feature requests and bug reports genuinely move
+priorities: the [showcase gallery](https://img2threejs-showcase.pages.dev/) tracks likes per
+category precisely so that demand, not guesswork, decides what gets built next.