Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.
Python 3dai-agentsclaude-codecomputer-graphicsgenerativeimage-to-3dprocedural-generationthreejstypescriptwebgl
chore(release): v2.0.0 — The Plugin Update ships as its own major; roadmap renumbered
kokorolx5e795e5daf07
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ef438f1..575a511 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -5,7 +5,10 @@ All notable changes to **img2threejs** are documented here.The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).-## [Unreleased]+## [2.0.0] — 2026-09-05++**The Plugin Update.** The plugin ecosystem — domain registry, img2 harness, plugin-served+domains — ships as its own major, pulled forward from the original Procedural World bundle.### Changed — BREAKINGdiff --git a/README.md b/README.mdindex 1aa1977..0ea2f0c 100644--- a/README.md+++ b/README.md@@ -9,7 +9,7 @@Quality-gated, animation-ready, and deliberately token-efficient — reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.[](LICENSE)-[](CHANGELOG.md)+[](CHANGELOG.md)[](CONTRIBUTING.md)[](https://threejs.org)[](forge)@@ -324,20 +324,21 @@ For the script-by-script reference and the full list of output artifacts, see [d- **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.-- **The Plugin Update (in review, PR #106)** — the domain registry, pull-based spec augmentation+- **v2.0 — The Plugin Update** — the domain registry, pull-based spec augmentationwith raise-only quality floors, the emission-target socket with provenance, per-plugin blocking- gates, and the img2 harness (`img2 install/add/doctor`). CS2 extracted into `plugin-cs2`; the- base names no domain. The "plugin ecosystem and API" originally slotted for v2.0, pulled forward.+ gates, and the img2 harness (`img2 install/add/doctor`). CS2 extracted into `plugin-cs2`,+ `animated-character` served by `plugin-character`; the base names no domain. The "plugin+ ecosystem and API" originally slotted for the Procedural World bundle, shipped first as its own major.- **v1.5 — The Character Update** — a skeleton derived from the component tree and bound to `SkinnedMesh` geometry, geodesic skinning, hair as a five-stage subsystem with a hard scalp-exposure gate, chirality gates, interior-difference review, the `tapered-sweep` primitive, the material pipeline with a blocking acceptance gate, and resumable workflow state. Not included: the `hairProfile` compiler, IK, pose-sweep gating, clothing.**Next — one theme per release:**-- **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.+- **v2.1 — The Environment Update**: buildings, rooms, streets, vegetation, terrain-aware and multi-object reconstruction.+- **v2.2 — The Game Pipeline Update**: Unity and Unreal exporters, a Blender bridge, LOD and collision-mesh generation.+- **v2.3 — The Animation Update**: auto rigging, auto skin weights, Mixamo compatibility, facial rig.+- **v2.4 — The AI Studio Update**: web UI, batch processing, visual prompt builder, cloud rendering.+- **v3.0 — The Procedural World Update**: multi-view reconstruction, procedural city generation, semantic world understanding.-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).+The arc: assets (v1.4–v1.5) → the plugin ecosystem (v2.0) → worlds (v2.1–v2.2) → production (v2.3–v2.4) → an AI game-asset platform that generates playable worlds from reference images (v3.0).**→ 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.mdindex d9afa6c..5540919 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -18,6 +18,7 @@ can plan around.| v1.4 | Weapon Pipeline | 2026-07-25–26 | CS2 image-matched reconstruction, provenance-aware intake and local search, projection-first finishes, family-specific adapters, structural review and component-coverage gates || v1.5 | The Character Update | 2026-08-12 | Skeleton derived from the component tree and bound to `SkinnedMesh` geometry, geodesic skinning, hair as a five-stage subsystem with a hard scalp-exposure gate, chirality gates, interior-difference review, `tapered-sweep`, material pipeline with a blocking acceptance gate, resumable workflow state || v1.5.2 | Character rigging & animation | 2026-08-25 | Clip measurement vocabulary and classifier, corrected loop rule (poseReturn, not travel), proximity weight blending, topology-driven chain resolution, foot-contact gate, and the G1-G10 gate suite where an unmeasured gate reports `unevaluated` rather than a pass |+| v2.0 | The Plugin Update — plugin ecosystem & API | 2026-09-05 | Domain registry (`forge/_shared/domains/`), pull-based spec augmentation with raise-only quality floors, emission-target socket with provenance, per-plugin blocking gates, the img2 harness (`install/add/doctor/sync/capabilities`); CS2 extracted into `plugin-cs2`, `animated-character` served by `plugin-character`, the base names no domain. Pulled forward from the original Procedural World bundle |### v1.2 — Humanoid character generator@@ -81,20 +82,22 @@ judgment is spent only where a script cannot decide.| v1.3 | Quality & efficiency (Divine Eye) | Shipped | Deterministic review harness, input-integrity and geometry-truth gates, projection-first texture/material analysis, CIEDE2000 colour math || v1.4 | Weapon Pipeline | Shipped | CS2 image-matched reconstruction, provenance-aware intake, projection-first finishes, family-specific adapters, structural and component-coverage gates || v1.5 | Character Pipeline | Shipped | Component-derived skeleton bound to `SkinnedMesh` geometry · geodesic skinning · hair subsystem across all five stages · chirality gates · interior-difference review · `tapered-sweep` · material pipeline · resumable workflow state. Not shipped: `hairProfile` compiler, IK, pose-sweep gating, clothing |-| **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 |+| v2.0 | The Plugin Update | Shipped | Domain registry · pull-based spec augmentation with raise-only floors · emission-target socket · per-plugin blocking gates · img2 harness · CS2 and animated-character extracted into installed plugins |+| **v2.1** | Environment Pipeline | Build scenes, not just objects | Buildings · rooms · streets · trees & vegetation · terrain-aware generation · multi-object reconstruction |+| **v2.2** | Game Pipeline | Game-ready assets | Unity exporter · Unreal exporter · Blender bridge · FBX / OBJ / glTF improvements · LOD generation · collision mesh generation |+| **v2.3** | Animation Pipeline | Move assets into production | Auto rigging · auto skin weights · Mixamo compatibility · facial rig · lip-sync preparation · animation-ready exports |+| **v2.4** | AI Studio | Cut the manual work | Web UI · drag & drop workflow · batch processing · visual prompt builder · project management · cloud rendering · public showcase integration |+| **v3.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 |### Release names- **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**+- **v2.0 — The Plugin Update**+- **v2.1 — The Environment Update**+- **v2.2 — The Game Pipeline Update**+- **v2.3 — The Animation Update**+- **v2.4 — The AI Studio Update**+- **v3.0 — The Procedural World Update**## Version details@@ -135,7 +138,21 @@ expression work beyond the morph-target emitter, and clothing. Hair dynamics andare out of scope permanently — a single image carries no motion, and this pipeline emits no texturesor alpha.-### v1.6 — The Environment Update+### v2.0 — The Plugin Update++*Shipped 2026-09-05.*++The plugin ecosystem became the product's spine rather than a line item in a far-future bundle. A+domain registry (`forge/_shared/domains/`) makes profiles pluggable: in-repo modules and installed+plugins register identically, `--profile` choices derive from what is actually present, and an+unregistered profile fails loud naming what is available. CS2 moved out of the base into+`plugin-cs2`; `animated-character` is served by `plugin-character`; the base names no domain and+infers none from a target's name. Specs pull augmentation from plugins with raise-only quality+floors, emission targets are a provenance-tracked socket, and each plugin brings its own blocking+gates. The `img2` harness (`install / add / remove / list / doctor / sync / capabilities`) owns+installation and drift detection across agent hosts.++### v2.1 — The Environment UpdateThe unit of reconstruction grows from one object to a scene. Buildings, rooms, and streets becomebuildable subjects; trees and vegetation get procedural treatment suited to code-only generation;@@ -143,20 +160,20 @@ and generation becomes terrain-aware, so objects sit in a scene rather than floaMulti-object reconstruction lands here: one reference image, several subjects, correct relativeplacement and scale.-### v1.7 — The Game Pipeline Update+### v2.2 — The Game Pipeline UpdateAssets stop being Three.js-only. First-class exporters for Unity and Unreal, a Blender bridge, andimproved FBX / OBJ / glTF output make a generated model something you can drop into an existingproduction pipeline. LOD generation and collision-mesh generation cover the two things every engineasks for and no image-to-3D tool ships by default.-### v1.8 — The Animation Update+### v2.3 — The Animation UpdateRigging becomes automatic: skeleton generation, skin weights, and a facial rig, with Mixamocompatibility so existing animation libraries apply without hand work. Lip-sync preparation andanimation-ready exports close the gap between "a model exists" and "a character performs".-### v1.9 — The AI Studio Update+### v2.4 — The AI Studio UpdateThe pipeline gets a front door for people who don't live in a terminal: a web UI with adrag-and-drop workflow, batch processing for more than one asset at a time, a visual prompt builder,@@ -164,27 +181,29 @@ project management, and cloud rendering. Public showcase integration wires the sthe [live gallery](https://img2threejs-showcase.pages.dev/), so publishing a result is a buttonrather than a pull request.-### v2.0 — The Procedural World Update+### v3.0 — The Procedural World UpdateMulti-view reconstruction removes the single-image blind-side limit that has bounded every priorversion. Large scene generation, semantic world understanding, procedural city generation, andinterior 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.+a multi-agent generation pipeline — all riding the plugin ecosystem and API that shipped in v2.0.## 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,+**Phase 1.5 (v2.0) — Ecosystem.** The plugin architecture shipped ahead of schedule: domains,+emission targets, gates, and augmentation are extension points other people can build on.++**Phase 2 (v2.1–v2.2) — 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,+**Phase 3 (v2.3–v2.4) — 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.+**Phase 4 (v3.0) — AI game-asset platform.** Generate entire playable worlds from reference images:+multi-view understanding, procedural world generation, and AI planning, all riding the v2.0+plugin ecosystem.## Known gaps (deep-research audit — 2026-07-22)@@ -195,10 +214,10 @@ 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 |+| G1 | SkinnedMesh + Bones + Morph targets (organic deform, facial expression) | Roadmap **v2.3 — Animation** (rig-ready topology prepared in v1.5) | deferred |+| G2 | glTF / GLB export + AnimationMixer (engine portability) | Roadmap **v2.2 — Game Pipeline** | deferred || G3 | ~~**InstancedMesh — real latent bug**: `instanced-cluster` has no `geometry_for()` branch; repetition systems emit a hand-rolled `Mesh` clone loop~~ | **Closed.** `geometry_for()` resolves the cluster's base primitive and the repetition emitter builds `new THREE.InstancedMesh(geo, mat, count)`; `test_repetition_system_scale.py` verifies placement by reading matrices back through `InstancedMesh.getMatrixAt` composed with `cluster.matrixWorld`, not by matching source strings | — |-| 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 |+| 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 **v2.2** | 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 |diff --git a/SKILL.md b/SKILL.mdindex 62344f2..4883edf 100644--- a/SKILL.md+++ b/SKILL.md@@ -2,7 +2,7 @@name: img2threejsdescription: Turn an object or character reference image into a quality-gated, animation-ready procedural Three.js model built in code. Use for image-to-3D reconstruction, detail-accurate object rebuilds, stylized/likeness-maximized human characters, sculpt specs, and staged code generation.license: Apache-2.0-version: 1.5.2+version: 2.0.0---# img2threejs — Image to procedural Three.js