Skip to content
Back to search

img2threejs

SkillWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/img2threejs/img2threejs with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/img2threejs/img2threejs'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/img2threejs-img2threejs/badge.svg)](/listings/img2threejs-img2threejs)

HTML

<a href="/listings/img2threejs-img2threejs"><img src="/api/listings/img2threejs-img2threejs/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Needs **Node.js ≥ 18, Git and Python ≥ 3.10**, and one of Claude Code, Codex, OpenCode or Hermes.

1. Install the base skill

npx --yes img2threejs@latest install   # links the skill into every agent it finds
npx --yes img2threejs@latest doctor    # one line per agent: "managed" means installed

**Hermes users**, also link the skill into your profile (the installer only writes `~/.hermes/skills/`):

ln -sfn ~/.hermes/skills/img2threejs ~/.hermes/profiles/${HERMES_ACTIVE_PROFILE:-img2threejs}/skills/img2threejs

Then **restart your agent** and go to [step 4](#4-run-a-reconstruction-in-your-agent). Prefer to let your agent install it, want a manual or single-agent install, or something failed: [`docs/INSTALL.md`](docs/INSTALL.md) (paste-to-agent prompt, expected output, troubleshooting, update and uninstall, other agents such as Cursor).

**Already installed?** Update with the row that matches your install in [`docs/INSTALL.md` §4](docs/INSTALL.md#4-update-an-existing-install).

2. Install the plugin harness, if needed

Skip this unless you need a plugin from the table below. Plugins come from a separate CLI, the `img2` harness (`~/.img2`); install it once:

npx --yes @img2threejs/img2@latest install --yes
npx --yes @img2threejs/img2@latest plugins       # the live catalog

It links an `img2` command if `~/.local/bin`, `/opt/homebrew/bin` or `/usr/local/bin` is on your `PATH`; otherwise use the `npx --yes @img2threejs/img2@latest` form, or `alias img2='npx --yes @img2threejs/img2@latest'`. What it changes on your machine: [`docs/INSTALL.md` §3](docs/INSTALL.md#3-add-a-plugin-only-if-you-need-one).

3. Choose plugins — do not install everything by default

| Plugin / source README | Adds | Access | Install after harness setup | |---|---|---|---| | [character](https://github.com/img2threejs/plugin-character) | Character rigging and animation: skeleton from a GLB, skin conditioning, clip measurement, action design, and a twelve-check rig gate. | Public | `img2 add character --yes` | | [cs2](https://github.com/img2threejs/plugin-cs2) | Counter-Strike 2 weapon and glove skin reconstruction: intake contract, authoritative classification, finish/material recipes, and a blocking review gate. | Public | `img2 add cs2 --yes` | | [environment](https://github.com/img2threejs/plugin-environment) | Install and manage the private img2 environment plugin through the img2 harness. Authorized GitHub access is required. | **Private — authorized Git access required** | `img2 add environment --yes` | | [hello-cube](https://github.com/img2threejs/plugin-hello-cube) | Turn an image into a deterministic Three.js cube (contract exerciser) | Public | `img2 add hello-cube --yes` | | [img2glb](https://github.com/img2threejs/plugin-img2glb) | Turn an image into a GLB 3D mesh via the hosted TRELLIS space | Public | `img2 add img2glb --yes` |

The table above is generated from the live catalog (`scripts/ci/plugin_table.py`); list all plugins with `img2 plugins`. Open each plugin's linked README for its input requirements, dependencies and tool setup. Example (the `cs2` plugin; substitute any catalog id):

img2 add cs2 --yes
img2 list
img2 doctor
img2 sync --check

An installed domain plugin contributes its checklist steps, evidence collection, spec augmentation (quality floors merge raise-only), and blocking review gates. With no plugins installed, the base has `generic` and `character` profiles. A profile whose plugin is missing (`cs2`, `animated-character`) fails loud naming what is installed; it never silently downgrades. The base skill is not a plugin: **do not use `img2 add` to install this repository.**

**Private `environment` plugin:** needs a GitHub account with access to its repository and working Git credentials. The public [`img2-environment`](https://www.npmjs.com/package/img2-environment) installer can bootstrap the harness but does not grant that access. Hermes users link each plugin

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 466 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: img2threejs
  3. description: 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.
  4. license: Apache-2.0
  5. version: 2.0.1
  6. ---
  7. # img2threejs — Image to procedural Three.js
  8. Rebuild the object visible in a reference image as a **code-only** procedural Three.js model,
  9. gated by a staged sculpting pipeline and an AI-vision self-correction loop. This is
  10. reconstruction-by-code, **not** photogrammetry, mesh extraction, or downloaded art packs. That
  11. promise governs how the model is *built* — it says nothing about which file formats it can
  12. subsequently be *exported* to; an explicitly-selected emission target (`--target <kind>`) is a
  13. terminal, whole-artifact transform of the already-built model, verified to its own stated limit,
  14. never a second way to build one.
  15. Agent-agnostic: works under Hermes, Claude Code, Codex, or OpenCode. Wherever this doc says "agent vision" or "agent browser tool", use
  16. whatever the host provides — native image reading, a browser MCP (playwright/chrome-devtools), the
  17. project preview, or a user-supplied screenshot.
  18. This file is the always-loaded router: it holds the order of operations and every hard rule as one
  19. line. The full contract behind each rule lives in the `grimoire/` or `docs/` file that rule names —
  20. read the named file at the moment you reach that stage, not before.
  21. ## Canonical shared checkout
  22. Keep one checkout of this repository and let every host enter it through a symlink, so the hosts
  23. execute the same code instead of drifting apart. `npx --yes img2threejs@latest install` does this
  24. for the hosts it detects (`hermes`, `claude`, `codex`, `opencode`); it refuses (exit 2) to replace a
  25. link it does not manage, so a hand-made link is never silently swapped for a release copy.
  26. **Hermes** reads skills per profile: also link `~/.hermes/profiles/<profile>/skills/img2threejs`
  27. (the installer writes only `~/.hermes/skills/`). Install, manual symlinks, and troubleshooting:
  28. [`docs/INSTALL.md`](docs/INSTALL.md).
  29. ## When To Use
  30. The user attaches/points to an object image and wants a procedural Three.js model, a
  31. reconstruction/animation/destruction plan, a sculpt spec, or code. Also for material studies,
  32. action-ready props, game objects, botanical/mechanical parts, and stylized reconstructions.
  33. ## Profile preflight (once per run, before `forge/next.py`)
  34. Domain knowledge (CS2 skins, animated characters, emission targets) lives in plugins, not in this
  35. checkout. Pick the profile from the subject, then confirm this environment can start it:
  36. ```bash
  37. python3 forge/state.py init --help | grep -- --profile # profiles available here
  38. ```
  39. - `generic` / `character` are built in: no harness, no plugin, nothing else to check.
  40. - A missing domain profile (e.g. `cs2`) is a setup gap: never downgrade to
  41. `generic` silently. Installing it edits the user's machine, so give them the commands in
  42. [`docs/INSTALL.md` §3](docs/INSTALL.md#3-add-a-plugin-only-if-you-need-one), get their go-ahead,
  43. re-check, and continue.
  44. - Installed but not listed (wrong `$IMG2_HOME`), or a Hermes plugin link: [`docs/PLUGINS.md`](docs/PLUGINS.md).
  45. - Then read what the profile's own steps name, at the moment you reach them: the plugin's
  46. `SKILL.md` and contracts govern that domain.
  47. ## Core Promise
  48. Sculpt from a photo, in order — never one-shot a mesh:
  49. 1. **Run `python3 forge/next.py --state .img2threejs/state.json [<spec>]` first**, at every start,
  50. resume, and before every correction iteration. It reports the ordered checklist, exact next
  51. command, evidence status, and bounded correction-loop status; it never replaces the spec/pass
  52. gates. Obey a hard stop; never continue from memory.
  53. 2. **Validate** the image is a suitable 3D target (`grimoire/intake/validation_rubric.md`).
  54. 3. **Assess** object class + complexity, then write a `qualityContract` before any code.
  55. 4. **Spec** it: component hierarchy, materials, lighting, pivots, sockets, action anchors.
  56. 5. **Build pass-by-pass** from blockout → structure → form → material → lighting → interaction → optimization.
  57. 6. **Verify** each pass with a screenshot compared against the reference; fail a pass if an
  58. identity-defining feature is wrong even when the global score looks fine.
  59. State explicitly when output is approximate/stylized/low-poly. A single image cannot reveal
  60. hidden sides or guarantee exact geometry — say so instead of faking confidence.
  61. ## Mandatory Local State Gate
  62. Conversation context is disposable; `.img2threejs/state.json` is the local checklist authority.
  63. Initialize once per reconstruction, then gate every step through it:
  64. ```bash
  65. python3 forge/state.py init --state .img2threejs/state.json --reference <img> --profile <generic|character|installed-domain> --spec object-sculpt-spec.json
  66. python3 forge/next.py --state .img2threejs/state.json [object-sculpt-spec.json]
  67. python3 forge/state.py mark <step-id> --state .img2threejs/state.json --evidence <path>
  68. ```
  69. - `next.py` prints the current step, pass, incomplete mandatory steps, exact next command, and
  70. `loop/max`. Exit code 3 or `status=stopped` is a hard stop: report the reason and request input.
  71. Never bypass it by reconstructing progress from chat history.
  72. - Every completed step needs evidence; mark a non-applicable step `skipped` only with `--reason` —
  73. silent omission is forbidden. Loop counts derive from `reviewHistory` actions
  74. (`refine-spec`/`refine-code`), not agent memory. Defaults: 3 corrections per pass, 6 total.
  75. - A domain profile's steps, gates and reference material come from the **registry**: in-repo
  76. modules (`character`) and installed plugins (e.g. `cs2`) register identically, and
  77. `forge/state.py init` names what is available. A profile adds mandatory gates without changing
  78. the core order -- a domain plugin typically requires an authoritative classification, an intake
  79. manifest, and a machine-readable domain review before AI review; `character` requires the
  80. character contracts and landmark evidence; `animated-character` (requires the installed plugin-character) adds all of `character` plus the
  81. nine Stage R steps (`grimoire/readiness/animation_contract.md`). Pick it whenever the rig must
  82. MOVE — on `character` the Stage R gates are absent and the build completes without ever running
  83. them, which is how animation used to ship broken. Its order is load-bearing: repair the mesh,
  84. freeze it, bind additively, then verify parity. Every profile records suitability, projection
  85. applicability, and
  86. material-evidence applicability. The state file is a resumability index, not visual evidence:
  87. renders, specs, review history, and deterministic gates remain the authoritative artifacts.
  88. ## Required Inputs
  89. - one image path / screenshot / URL / attached image (if missing or unreadable, ask)
  90. - intended use: prop, game object, hero render, playable/destructible object, animation rig
  91. (default: real-time browser prop with interactive performance)
  92. - when a domain plugin serves the item, whatever authoritative record its intake step requires, or
  93. an explicit request for the user/vision provider to supply one; heuristic detection alone is not
  94. enough to select a geometry adapter
  95. ## The Loop (scripts do enforcement; agent vision does judgment)
  96. Run scripts from the skill root (`forge/...`). Pure Python 3.10+ stdlib, no pip installs.
  97. Full flags: `grimoire/scripts.md`. Never let a script *score* visuals — that is the agent's job.
  98. 1. **Analyze the image first** (agent vision, before any script): work the layered observation
  99. protocol in `grimoire/intake/image_analysis.md` — identify/classify, decompose macro→meso→micro,
  100. map part relationships, name materials in PBR terms, list identity-defining features, and flag
  101. what the single view hides. Observation before inference; controlled 3D vocabulary; 3D
  102. object-space not 2D image-space. Then probe local images:
  103. `forge/stage1_intake/probe_image.py <image>` (metadata only, not a visual check).
  104. 1a. **Local Spec Search** — after image analysis, before writing or refining a spec, pull local
  105. domain evidence (anatomy/PBR/wear/geometry/runtime/physics) rather than inventing it:
  106. `python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --out assessment.json`
  107. (auto-runs BM25 over the `core_3d` collection, or the collection a declared domain contributes
  108. -- the collection is NEVER guessed from the target name; writes a `localSpecSearch` bundle that
  109. `new_sculpt_spec.py --assessment` carries into the spec). Full query-expansion recipe
  110. (bilingual terms, focused `search_specs.py` retrieval, cache rules):
  111. `grimoire/intake/local_spec_search.md`. MUST read it before retrying an incomplete or
  112. domain-specific query.
  113. 1b. **Domain intake** — when a domain plugin serves the item, complete its intake steps before
  114. pre-spec authoring (admission, heuristic signal, classification, family/route resolution).
  115. MUST read the contract its step names, completely, before creating the manifest or
  116. running pre-spec assessment.
  117. 1c. **Optional fidelity evidence adapters** — only when they improve an observed weak point; the
  118. stdlib core remains authoritative. Thin/complex masks → local SAM2; character face/pose →
  119. MediaPipe; weak front/back cues → Depth Anything V2
  120. (`forge/stage1_intake/run_vision_adapter.py <segment|landmarks|depth> ...`; every adapter emits
  121. provenance; monocular depth is relative only). **MCP-only scene mutations never count as
  122. implementation** — write the proven change back to the spec or TypeScript, rebuild, recapture.
  123. Full adapter + MCP routing and authority boundaries:
  124. `docs/integrations/reference_fidelity_tooling.md`.
  125. 2. **Pre-Spec Assessment Gate** — classify + score complexity + write the quality contract:
  126. `forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <img> --complexity <simple|moderate|complex|ultra-complex> --out assessment.json`. Rules: `grimoire/intake/quality_contract.md`.
  127. Set `objectClass.primaryDomain` (`object` | `character` | `hybrid`) and fill the seeded
  128. `detailInventory` (its `targetMinDetails` scales with complexity). A domain plugin may **raise**
  129. these floors through its augmentation -- the merge clamps, so a plugin can never lower one
  130. (a skin's finish/wear/hardware IS the item, so such a domain is held to the
  131. top fidelity bar. Author procedural GEOMETRY but route the FINISH through the projection path in
  132. step 2c — a procedural finish for a patterned skin (Doppler/Gamma/Marble/Fade) reads visibly
  133. wrong against the reference. A domain plugin ships its own finish rulebook and texture-acquisition
  134. guide; read what its checklist steps name.
  135. 2b. **Detail inventory** (do not skip for detailed subjects) — scan zones and enumerate every
  136. identity-defining small detail (gloss, bevel, fasteners, linework, contours, stains):
  137. `forge/stage1_intake/build_detail_inventory.py <image> --mode grid-3x3 --out-dir <dir> --out di.json`.
  138. Each detail MUST map to a `component.localFeatures` or `material.localOverrides` entry — never
  139. prose only. Taxonomy + 3D-term recipes: `grimoire/intake/detail_inventory.md`.
  140. 2c. **Projection-first fidelity** (characters AND reference-matched surfaces — painted skins,
  141. decals, painted patterns) — when the goal is matching a specific reference's surface, put the
  142. photo's own pixels on the mesh instead of approximating them procedurally. This is the single
  143. biggest fidelity lever; a procedural material for a patterned surface is the #1 reconstruction
  144. failure. Recipe (`grimoire/character/likeness_maximization.md` — its two levers generalize past
  145. characters): solve the camera (`stage1_intake/solve_camera_pose.py` → `referenceCamera`),
  146. **de-light** the reference (`stage1_intake/delight_albedo.py`, hard requirement — de-lighting is
  147. what makes projection safe), then project the de-lit crop and bake it into UVs
  148. (`stage3_build/bake_projected_texture.py --mesh-id <id>`). For a painted skin the projected de-lit
  149. crop IS the finish — no procedural Doppler material. For characters, first capture landmarks
  150. (`stage1_intake/extract_landmarks.py --out anatomy.json`), fill `preSpecAssessment.anatomy`,
  151. route `grimoire/character/reconstruction.md`. A single view cannot show hidden sides — report
  152. per-region confidence and request more views when it matters.
  153. Character sub-routes, in order — decide what parts exist before shaping any, and shape the head
  154. before the hair that sits on it:
  155. - **Parts** — `grimoire/character/structure_decomposition.md`
  156. - **Head** — `grimoire/character/head_construction.md` (what the likeness gate reads against)
  157. - **Hair** — `grimoire/character/stylized_hair_threejs.md` + parameter contract in
  158. `grimoire/character/threejs_hair_parameter_contract.json`. Lock topology only after the
  159. silhouette review passes: material tuning cannot repair wrong lock topology.
  160. 2d. **Reference-free humanoid** — a generic figure with no reference image has nothing to measure,
  161. so fill anatomy from public canon:
  162. `forge/stage2_spec/humanoid_proportions.py <spec> --style-heads 8 --in-place`. It writes
  163. `anatomy.source: "canon-table"` so canon is never mistaken for measurement, refuses to run when
  164. the spec names a reference image, and names anything the corpus does not supply rather than
  165. interpolating it.
  166. 3. Author the spec from the assessment:
  167. `forge/stage2_spec/new_sculpt_spec.py "Name" --image <img> --assessment assessment.json --augmentation spec-augmentation.json --domain <profile> --out object-sculpt-spec.json` (the checklist step carries the resolved flags).
  168. Replace generic starter `featureReviewTargets` with the object's real identity-defining
  169. systems (≤5 critical, ≤3 important per pass); for characters add `anatomy-proportion`,
  170. `face-landmark-placement`, `pose-silhouette`, `outfit-and-palette`. Use 3D-graphics terms only
  171. (`grimoire/glossary/3d_vocabulary.md`), never "nice/smooth/shiny". Classify every component's
  172. `topologyClass`/`topologyRationale` per `grimoire/intake/surface_topology.md` before picking a
  173. `primitive` — this is what prevents a continuous organic form from being picked as a box.
  174. 4. When material fidelity matters and a source image exists, analyze each material's **finish** then
  175. extract reference PBR evidence, both per crop (verify the crop is on the part you think it is):
  176. - `forge/stage1_intake/analyze_texture.py <crop> --spec spec.json --material-id <id> --in-place`
  177. classifies the finish, extracts the gradient palette, and writes doc-grounded
  178. MeshPhysicalMaterial scalars onto the material. Recipes + Three.js texture/PBR rules:
  179. `grimoire/build/threejs_texture_reference.md`. Rule of thumb: **solid albedo for flat paint,
  180. real reference crop for patterned finishes**.
  181. - `forge/stage1_intake/extract_pbr_evidence.py <crop> --out-dir <dir> --material-id <id> --target-threshold 0.7`.
  182. Confidence < 0.7 is a stop/refine-input signal, not a pass. It is inference, not inverse rendering.
  183. - For multiple named regions: `forge/stage1_intake/material_region_analysis.py --manifest regions.json --out-dir material-evidence --out material-analysis.json`,
  184. resolve each assignment from `docs/materials/material-reference.json`, wire it in with
  185. `forge/stage2_spec/apply_material_analysis.py`.
  186. - Emit the controlled material camera/crop contract (`forge/stage4_review/material_views.py`),
  187. compare visible-footprint crops (`material_comparator.py`), apply only bounded material-scoped
  188. corrections (`material_feedback.py`), and record the blocking result (`material_gate.py`).
  189. 5. Validate, then strict-validate before generating code:
  190. `forge/stage2_spec/validate_sculpt_spec.py object-sculpt-spec.json` then `--strict-quality`.
  191. Strict blocks shallow specs (a complex object with one root, no repetition systems, no
  192. local overrides, no micro groups is NOT implementation-ready even if JSON validates).
  193. 6. **Locked build passes** — only touch the currently unlocked pass:
  194. `forge/stage3_build/orchestrate_passes.py status object-sculpt-spec.json`
  195. `forge/stage3_build/generate_threejs_factory.py object-sculpt-spec.json --out src/createObjectModel.ts`
  196. The generator is fail-closed: `strict-quality` must pass before it writes any factory, and a
  197. future `--pass-id` fails until prior passes are reviewed `continue`. If blocked, preserve the
  198. `BLOCKED` artifact and refine the subject-specific spec; do not substitute a generic template.
  199. The local state adds `--force` only for a new pass or `refine-spec`; `refine-code` edits the
  200. current artifact without regenerating it. Before overwriting, carry valid hand refinement back
  201. into the spec; generated code must not be the only copy of reconstruction decisions.
  202. 6a. **Hitting a triangle budget.** `performanceBudget.targetTriangles` selects a tessellation tier
  203. for every primitive with segment counts (low ≤6k, standard ≤60k, else hero) and caps
  204. implicit-surface sampling grids. Where a tier is not precise enough, add
  205. `geometryDescriptor.decimate: {"targetRatio": 0.4}` to that component — a quadric collapse in
  206. the generated factory, run **before** skin binding so weights are computed on surviving
  207. vertices. It keeps `position` only (normals recomputed), so it is refused on an
  208. authored/unwrapped `uvStrategy`. Offline LOD tiers:
  209. `forge/stage3_build/decimate.py <mesh.json> --ratio <r> --json`.
  210. 7. Render the current pass in a browser/preview, capture a screenshot at a review viewpoint.
  211. 7a. **Off-axis and placement gates — a single review viewpoint is not evidence about the model.**
  212. Capture a turntable, not one frame, and run all three; each catches a defect class the older
  213. gates pass by construction (a hole through a skull, a hat at hip height and a floating charm all
  214. survived eight front-only review rounds):
  215. `forge/stage4_review/turntable_gate.py --capture 0=front.png --capture 90=right.png --capture 180=rear.png --capture 270=left.png --json`
  216. `node runtime/scripts/export_mesh_geometry.mjs --url <preview> --out meshes.json` then
  217. `forge/stage4_review/self_intersection.py meshes.json --json`
  218. `forge/stage4_review/attachment_anchor.py object-sculpt-spec.json --measured measured.json --json`
  219. All three exit `0` clean / `1` gate failure / `2` error. A failure blocks `continue` even when
  220. the global fidelity score passes. Read `sampledVertexCount` / `unmeasuredAttachments` /
  221. `missingAzimuths` before believing a clean verdict: each names what the gate did not look at.
  222. 8. **Run deterministic gates before AI vision.** MUST read
  223. `grimoire/review/gates_reference.md` and `grimoire/review/self_correction.md` completely. Run
  224. `forge/stage4_review/diagnose_render.py` and record the passing Tier 1 result with
  225. `--spec object-sculpt-spec.json --pass-id <pass> --in-place`; for non-planar forms also run
  226. `forge/stage4_review/diagnose_render_multi_angle.py` with the fixed view and at least two
  227. meaningful orbit views. Then run
  228. `forge/stage3_build/orchestrate_passes.py check object-sculpt-spec.json --pass-id <pass>`.
  229. 9. Package one side-by-side sheet, then inspect it with agent vision:
  230. `forge/stage4_review/make_comparison_sheet.py --reference <img> --render <shot> --out cmp.png --json`.
  231. 10. Record the review (overall + per-layer + per-feature scores + decision):
  232. `forge/stage4_review/append_review.py object-sculpt-spec.json --pass-id <pass> --fidelity <0-1> --action <continue|refine-spec|refine-code|request-input|stop> --summary "..." --render-screenshot <shot> --comparison-image cmp.png --ai-vision-score <0-1> --layer-scores-json '{...}' --feature-reviews-json <f.json> --in-place`.
  233. When a domain plugin contributes a review gate, produce its versioned report first with
  234. the command that plugin's review step names, then attach it with
  235. `--domain-review-json <report>.json --review-scene-json <the plugin's scene fixture>`. The
  236. checklist step carries the resolved paths.
  237. A failed family, painted-region, projection-coverage, critical-detail, or orbit gate blocks
  238. `continue` even when the global score passes. See the plugin's own review-gate documentation.
  239. 11. Sync pipeline state after manual review edits, record checklist evidence, then re-run the local
  240. state gate before another correction or pass:
  241. `forge/stage3_build/orchestrate_passes.py sync object-sculpt-spec.json --in-place`
  242. `python3 forge/next.py --state .img2threejs/state.json object-sculpt-spec.json`.
  243. 12. Before declaring completion, run
  244. `forge/stage4_review/check_part_coverage.py --spec object-sculpt-spec.json --manifest parts.json`
  245. and verify the action-ready hierarchy. Mark `part-coverage` and `action-ready` only with evidence.
  246. ## GLB-mediated v2 render-fidelity track (1.5 alpha)
  247. When the user supplies a GLB as an intermediate reference, the browser-rendered GLB is the
  248. structural and visual baseline for an independently authored procedural factory. The raw GLB is
  249. never pixel evidence and its topology/materials are never copied into the factory. Before any
  250. factory edit — full contract in `grimoire/build/python_threejs_render_bridge.md`, machine-readable
  251. schema in `docs/specs/render-profile.v2.schema.json` (+ example; fail-closed validation):
  252. 1. `forge/stage1_intake/probe_glb.py` first. A merged one-node/one-mesh asset is `insufficient`
  253. for semantic labels; request a multipart GLB or a browser semantic-ID pass before claiming
  254. exact regions.
  255. 2. Author ONE shared `render-profile.v2` (`forge/stage4_review/validate_render_profile.py`) used by
  256. both the GLB and procedural routes. Region IDs are subject-specific, never inherited from the
  257. example profile; declare the required set in `extensions.requiredSemanticRegions` so omission is
  258. a hard validation error.
  259. 3. Capture six passes per admitted view (`beauty`, `alpha-silhouette`, `semantic-id`, `depth`,
  260. `normal`, `roughness-material-id`); score with `forge/stage4_review/compare_region_passes.py`.
  261. Missing semantic-ID data blocks per-region confidence rather than falling back to whole-image
  262. scores.
  263. 4. Use region-specific continuous geometry — never replace a face/head volume, cloth shell, or tail
  264. with floating primitives when the region's silhouette requires a continuous surface.
  265. 5. Run ONE correction group per loop, in order: `camera → silhouette → face → clothing → accessory
  266. → materials → lighting`; recapture the full pass set after each group and record the changed
  267. group, hashes and score. Never combine groups when diagnosing improvement.
  268. ## Gates (do not skip)
  269. Before any visual review or `continue` decision, MUST read the full gate-by-gate contract in
  270. `grimoire/review/gates_reference.md` (Divine Eye, VLM rescue, multi-angle, interior difference,
  271. chirality, hair, domain review, bounded correction, Divine Eye fitting, screenshot feedback, assembly,
  272. attachment, material, detail inventory, rig payload, character track). In short:
  273. - Validate references first (`grimoire/intake/validation_rubric.md`, `check_reference_admission.py`).
  274. - `divine_eye.py` is deterministic-first; the VLM (`vlm_gate.py`) is a gated last layer, never
  275. consulted on a hard-gate failure.
  276. - A non-planar form must hold from ≥2 angles (`diagnose_render_multi_angle.py`).
  277. - Measure INSIDE the silhouette every visual pass (`interior_difference.py`). Silhouette IoU reads
  278. ~11% of figure cells: a model with its face deleted scored the same 0.8803 as the finished face.
  279. - Every `-l`/`-r` pair is a MIRROR, not a rotation — hard at spec time (`validate_chirality`). A pair
  280. wrong the same way on both sides still passes, and needs `medial_lateral_bias` vs a reference.
  281. - Hair subjects: `scalp_exposure.py` is HARD and runs on geometry before any render; `hair_gate.py`
  282. is soft and subordinate to it. A coverage shortfall never authorises widening the masses.
  283. - Flat colour regions with hard boundaries (blaze/bib/socks, livery stripe, painted marking) are an
  284. identity feature, so their boundaries are gated on geometry: `vertex_region_gate.py`. Never a
  285. texture — this pipeline emits code; the shape predicates live in `_shared/vertex_paint.py`.
  286. - A curve claim ("curled into a hook, not a straight cone") needs `swept_arc_gate.py`: silhouette IoU
  287. passes a straight cone occupying roughly the right cells.
  288. - Character builds validate the rig payload (`stage5_rig/validate_rig_payload.py`) before binding a
  289. `THREE.Skeleton`; it proves payload integrity only, never pose stress or likeness.
  290. - A rig that must MOVE runs the animation gates too (`grimoire/readiness/animation_contract.md`;
  291. the checklist steps and gate come from the installed plugin-character -- `stage5_rig/` remains in
  292. this repo as the emitter's library, not the checklist authority). A clip that exists is not a
  293. clip that plays: only G1
  294. (`maxSampledBindingDelta <= 2^-23`) separates the two, and a gate whose input is missing reports
  295. `unevaluated`, never a pass. Bind at IDENTITY in attached mode and take the display offset from
  296. the mesh bounds alone; loop is decided by `poseReturn`, never by travel.
  297. - A domain plugin's review gate also runs against its versioned scene fixture.
  298. - Local state enforces 3 corrections per pass and 6 total by default; reaching either limit is a
  299. hard stop. `correction_loop.py` may stop earlier on repeated defects, oscillation, or plateau.
  300. - `continue` requires a render + comparison sheet + AI-vision score ≥ threshold, every critical
  301. feature ≥ its own threshold (`grimoire/feedback/render_capture.md`).
  302. - Every model ships explodable AND clickable — a structure gate, not pixels
  303. (`check_part_coverage.py`, `grimoire/build/geometry_patterns.md`).
  304. - Action-ready, attachment, material/lighting, detail inventory, and character-track requirements:
  305. `grimoire/readiness/action_rigging.md`, `grimoire/readiness/joint_attachment.md`,
  306. `grimoire/feedback/shading_realism.md`, `grimoire/intake/quality_contract.md`,
  307. `grimoire/intake/validation_rubric.md`.
  308. ## Self-Correction
  309. After every pass, decide exactly one: `continue | refine-spec | refine-code | request-input | stop`.
  310. `refine-spec` fixes a wrong/missing/shallow spec (re-validate, don't patch code around it);
  311. `refine-code` fixes geometry/material/lighting that doesn't match a sound spec. Before making the
  312. decision, MUST read the root-cause guide + fidelity scale in `grimoire/review/self_correction.md`,
  313. record the decision, and re-run the local state gate.
  314. **Small features need a different instrument.** Divine Eye's SSIM/tonal/edge signals run on a 64×64
  315. luma grid, so a detail a few pixels wide is absent before any comparison happens. When fidelity
  316. depends on individual tears, spars, fangs or eyes, use the four-tier microscope:
  317. `grimoire/review/divine_eye_microscope.md`. Two empirically established rules from it: measure
  318. fidelity on a component's **visible footprint** (full frame minus a component-hidden frame), never
  319. on an isolation render; and never colour-gate a **concave** feature, where a dark ratio captures
  320. cavity shading rather than material.
  321. ## Transparency and Process Debugging
  322. Report what changed each pass with evidence (exact values/coordinates), name what still doesn't
  323. match, and never claim "done" when only "improved". A passing gate is not proof of 3D realism.
  324. Full rule + examples: `grimoire/review/self_correction.md`.
  325. ## Left and right
  326. A left/right pair is a **reflection**, never a rotation: negate the lateral axis and nothing else,
  327. `(x, y, z) → (-x, y, z)`. With `forward: +Z`, Y up and a right-handed frame, the character's own
  328. left is **+X**. The convention lives as code in `forge/_shared/chirality.py`
  329. (`CHARACTER_LEFT_SIGN`), with two different gates for the two defects that shipped from getting it
  330. wrong: `validate_chirality` catches a rotation-mistaken-for-reflection at spec time, and
  331. `medial_lateral_bias` vs a reference catches a pair that is wrong the same way on both sides.
  332. Reflecting also inverts triangle winding — flip it back on the mirrored side or `flatShading`
  333. lights the limb as though lit from behind. Full write-up with the measured defects:
  334. `grimoire/scripts.md` ("Left and right").
  335. ## Hair
  336. Hair has its own subsystem because it has failure modes no other gate can see. Full contract,
  337. measurements and non-goals: `docs/HAIR_PIPELINE.md`. The hard rules:
  338. - Roots bind to the scalp as `(u, v)`, never absolute positions (hard validation error).
  339. - `standProud` is enforced by the generator, not advisory.
  340. - `scalp_exposure.py` is a HARD gate on geometry before any render; a coverage shortfall never on
  341. its own authorises widening the masses.
  342. - Default representation tier is `shell`, not locks; strand impression comes from faceting and
  343. material (`hair.human.code-only`), since this skill emits no textures.
  344. - `plane-card` is rejected for hair (needs an alpha texture this skill cannot emit).
  345. - Hair is rigidly parented, never smooth-skinned (the geodesic field runs through the skull).
  346. ## Domain plugins
  347. A domain plugin makes a run exact where this pipeline would otherwise infer. It contributes its own
  348. checklist steps and gates, and publishes a `spec-augmentation.json` that this pipeline pulls at
  349. `spec-authoring`. With no plugin serving the item, nothing here changes: author the skeleton and
  350. infer the shape from the reference, as for any other object.
  351. - The steps a plugin contributes appear in the checklist with their own ids and resolved paths. Read
  352. what each step names -- a plugin ships its own contract, and it governs its own domain.
  353. - A plugin may **raise** this pipeline's quality floors and can never lower one; the merge clamps.
  354. - A plugin that does not serve an item publishes no augmentation. That is not an error and not a
  355. blocked run: it is the generic path, and the reconstruction proceeds by inference.
  356. - This pipeline names no domain. If a rule is domain-specific, it lives in that domain's plugin.
  357. ### The img2 harness
  358. Plugins are installed and managed by the `img2` harness
  359. ([img2threejs/img2](https://github.com/img2threejs/img2)), a separate dependency-free CLI (Node
  360. launcher, Python core). This skill vendors no domain logic and never writes a substitute for it;
  361. a missing profile is handled by the preflight above, and only a plugin that does not exist
  362. upstream is a blocker to report.
  363. ```bash
  364. img2 plugins # list plugins
  365. img2 add img2threejs/plugin-<id> --ref <tag> # install a plugin at a tag (e.g. plugin-cs2)
  366. img2 doctor # what each host resolves: base-skill path + version, plugin gates
  367. img2 capabilities --from-kind image --to-kind glb # which installed plugin serves an edge
  368. ```
  369. Setup and the full CLI reference live in the README quick-start and the harness repo's docs.
  370. ## Forge Runtime Contracts
  371. Subdivision runtime tests compile generated TypeScript against the showcase checkout. Set
  372. `IMG2THREEJS_SHOWCASE_ROOT` to that checkout; without it, local runtime-only tests skip with an
  373. actionable message while static contracts still run. CI should set `IMG2THREEJS_REQUIRE_SHOWCASE=1`
  374. to turn a missing showcase checkout into a test failure.
  375. ```bash
  376. IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_subdivision.py
  377. IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 -m unittest discover -s forge/tests
  378. IMG2THREEJS_SHOWCASE_ROOT=/path/to/img2threejs-showcase python3 forge/tests/test_showcase_tsc_smoke.py
  379. ```
  380. ## Implementation Rules (brief)
  381. TypeScript + plain Three.js unless the project uses a wrapper. `Group` factory
  382. `createObjectNameModel(spec, options)`, reconstruction data kept separate from renderer objects,
  383. deterministic seeds for all procedural noise. Prefer primitives / `Shape` extrude / curve+tube /
  384. instancing / displacement / generated canvas textures before any external art. Full geometry &
  385. material recipes + hard-won failure patterns: `grimoire/build/geometry_patterns.md`.
  386. ### Optional Python ↔ Three.js render bridge
  387. When Python is requested for character rendering, use it as a deterministic job/evidence layer
  388. around the browser Three.js runtime: camera-batch manifests, source/output hashes, readiness and
  389. settle checks, screenshot persistence, masks, diagnostics, and comparison packaging. The target
  390. Three.js browser route remains the rendering authority. Do not silently replace the procedural
  391. TypeScript factory with Blender/VRM/GLB output. Full routing, manifest fields, and failure rules:
  392. `grimoire/build/python_threejs_render_bridge.md`.
  393. ### Standard character pipeline (merged 1.5 beta + alpha)
  394. Use `grimoire/readiness/standard_character_pipeline.md` for character work. Beta owns the
  395. strict sculpt/build/review gates; alpha owns deterministic camera manifests, browser screenshot
  396. evidence and UniRig-shaped rig validation. CharacterGen, Tripo, VRM and other neural/asset
  397. systems are opt-in adapters with source, checkpoint, license, coordinate conversion and output
  398. hashes. They never silently replace the procedural TypeScript factory. Image-to-mesh systems emit a
  399. static mesh with no skeleton, so their output is never animation-ready however good it looks.
  400. Executable entry points: `forge/stage4_review/render_bridge.py` and
  401. `scripts/capture_threejs_playwright.py` (`init → browser capture → validate → diagnose`; capture
  402. must operate on the real showcase/browser route and leave readable PNGs in the workspace).
  403. ## Output
  404. - **Analysis-only**: suitability verdict + scores, object extraction, macro→micro hierarchy,
  405. geometry strategy, material/lighting recipe, animation/destruction feasibility, plan + risks.
  406. - **Implementation**: the above briefly, then edit code; verify with typecheck/build + a screenshot.
  407. - **Not feasible**: name the blocker, ask for more views / cleaner image / accepted stylization /
  408. a narrower target. "This cannot reach the requested fidelity from this image" is a valid result.
README.md · README · 584 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/logo.svg" width="112" height="104" alt="img2threejs logo" />
  3. # img2threejs
  4. **Rebuild the object in a reference image as a code-only, procedural Three.js model.**
  5. Quality-gated, animation-ready, and deliberately token-efficient — reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.
  6. [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
  7. [![Version](https://img.shields.io/badge/version-2.0.1-green.svg)](CHANGELOG.md)
  8. [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
  9. [![Runtime](https://img.shields.io/badge/runtime-Three.js-000000.svg)](https://threejs.org)
  10. [![Tooling](https://img.shields.io/badge/tooling-Python%203.10%2B%20stdlib-3776ab.svg)](forge)
  11. [![Sponsor](https://img.shields.io/badge/Sponsor-Ko--fi-FF5E5B.svg?logo=kofi&logoColor=white)](https://ko-fi.com/iamnick)
  12. [![Scripts](https://img.shields.io/badge/scripts-forge%20%2F%20scripts-3776ab.svg)](scripts)
  13. [![Sponsored by MiniMax](https://img.shields.io/badge/Sponsored%20by-MiniMax-000000.svg?labelColor=1a1a1a&logo=MiniMax&logoColor=white)](https://platform.minimax.io/subscribe/token-plan)
  14. [![Sponsored by Atlas Cloud](https://img.shields.io/badge/Sponsored%20by-Atlas%20Cloud-000000.svg?labelColor=1a1a1a&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA4NDUuOTUgNzkyIj48cGF0aCBmaWxsPSIjZmZmIiBkPSJNNzEyLjA1LDU5NC4zTDQyMi45OCwxNS40NiwxMzMuOSw1OTQuM2wtOTEuMDEsMTgyLjI1YzU3LjE4LTM0LjU1LDExOS40OS02MS40LDE4NS40NC03OS40NSw2Mi4wMi0xNi45NywxMjcuMjQtMjYuMjEsMTk0LjY1LTI2LjIxLDM0LjY5LDAsNjguNzksMi40OSwxMDIuMTksNy4xOGwtNjUuNzItMTQxLjc2Yy0xOC42MS0zLjIzLTEwMS4yOC0zLjIzLTE2MS44Myw5Ljg0bDEyNS4zNi0yNzMuMTYsMTk0LjY1LDQyNC4xMmMuMzUuMS42OS4yMSwxLjAzLjMsNjUuNTcsMTguMDQsMTI3LjUzLDQ0Ljc4LDE4NC40MSw3OS4xNGwtOTEuMDEtMTgyLjI1WiIvPjwvc3ZnPg%3D%3D)](https://www.atlascloud.ai/console/coding-plan)
  15. [![Sponsored by Tripo](https://img.shields.io/badge/Sponsored%20by-Tripo-000000.svg?labelColor=1a1a1a&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbC1ydWxlPSJldmVub2RkIj48cGF0aCBmaWxsPSIjZmFjZTAwIiBkPSJNMTIuNjYxIDQuNzUyYS4wNC4wNCAwIDAwLS4wMTMtLjA1NS4wMzguMDM4IDAgMDAtLjAyLS4wMDVINi40OTZhLjE5LjE5IDAgMDEtLjE2NS0uMDkyTDQuMjQ1IDEuMDUyYS4wMzQuMDM0IDAgMDEuMDE0LS4wNDdBLjAzOC4wMzggMCAwMTQuMjc1IDFjNS40OTIgMCAxMC43MzMgMCAxNS43MjEuMDAyIDIuMDg5IDAgMy42OTkgMS41NCA0LjAwMyAzLjU5OC4wMDguMDYyLS4wMTkuMDkyLS4wOC4wOTJoLTYuNjdhLjIwNC4yMDQgMCAwMC0uMTc0LjFjLTEuNDE0IDIuNDEtMi44MiA0LjgwMy00LjIxOCA3LjE3OC0uMjguNDcyLS45Mi42Mi0xLjM3My4zNDItLjE5LS4xMTYtLjM1Ny0uMzA0LS41MDItLjU2MWEzNy45MTcgMzcuOTE3IDAgMDAtLjg4Mi0xLjQ4OWMtLjIyMi0uMzU2LS4yMzQtLjcwNy0uMDM1LTEuMDUyYTY2MS43NyA2NjEuNzcgMCAwMTIuNTk3LTQuNDZ2LjAwMnoiLz48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMTAuNzcyIDE2Ljk4NmMuNTcuOTcyIDEuOTM1LjkxNiAyLjQ4OS0uMDI4TDE5IDcuMTY0YS4xMjcuMTI3IDAgMDEuMTE2LS4wNjdoNC4yM2MuMDE3IDAgLjAzLjAxNC4wMjguMDMgMCAuMDA1LS4wMDEuMDEtLjAwMy4wMTMtMi42MDUgNC40MzItNS4yMzIgOC45MDYtNy44OCAxMy40Mi0xLjI4MyAyLjE5MS00LjI3OCAyLjUxNy02LjE3OS45NDctLjMwOC0uMjU0LS42NjUtLjcyNy0xLjA2OS0xLjQxNy0yLjUyNS00LjMyNC01LjA5OC04LjcxLTcuNzItMTMuMTYyLTEuMDYzLTEuODAzLS40MjQtMy45NDcgMS4xOS01LjIuMDUzLS4wNDEuMDk1LS4wMzMuMTI5LjAyMyAyLjkwNSA0Ljk1IDUuODgyIDEwLjAyOSA4LjkzIDE1LjIzNnoiLz48L3N2Zz4%3D)](https://www.tripo3d.ai/)
  16. [![Sponsored by Hyper3D](https://img.shields.io/badge/Sponsored%20by-Hyper3D-000000.svg?labelColor=1a1a1a&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAYAAABzenr0AAAAAXNSR0IArs4c6QAAAERlWElmTU0AKgAAAAgAAYdpAAQAAAABAAAAGgAAAAAAA6ABAAMAAAABAAEAAKACAAQAAAABAAAAIKADAAQAAAABAAAAIAAAAACshmLzAAADlElEQVRYCeWWbWiOURjH9wzDZoYs5i3aF%2FEBiTYZRQ35qGxS%2B2AoFNoHRcl7vlETGcWX1aLkLbKsJTNiXmpKpExt5v2lGWNte%2Fz%2Bd%2Ff9dO6z57mfe08p5arfc851netc57rP23PS0v53iYSZgGg0Ogy%2F5VACU%2BAnnIlEIjWUf1cYvAgaIZ7sxxjqI1LKkuCb4Ue8kV1bB%2BXElIIn60TgLdDnDhRULEsWa8DtjKZp7woa1W37TTljwAMEdSBgFjS5AyQrzuOQ7jKCcnBQ7FBtBCmHZPIdh0oYpaCUObATnoCS3wPzwwzo28F0GkKnezDX7fyJ8gF8hT54Bc3wmCP4mtIn9C%2FCcBbyoQv2QSW%2BqicXAhRAL7yFU3AI6uEoTE8ewZmNqfg%2BB8kL0FFdEqavpnI9qPNe0HRKdkOGHQBbBIbbdunYi6EbfsER%2BAC6yBILDgqoo3cavBOwPXEPZyDNWNxjiP0iSA6CTks7zAyKp8xLwBv8ZKCz24j%2FMVhj%2B2JbCRItoy4syW0YavvGdBovywvRHpgcawio4LcBWmG06YaeB7pFlUAneFJm%2BqWbCvWXrn6FndtqtSVSJ9GgPTLecviG3gDZYH71VjLRn5sjdgKNrv2CWwYWBNItOBZqYZ7l3IN%2BHyaAeUHNQS8AR8wGGe6AvlznP64w6FIaRrosoNTAs6AOTNGXt8Em00hdH10It8CXWRrT%2FpEBTmA3p0x%2BppSj2JtOF403e56vlmA25HoGo1TijtgzIONxiK2R4%2BX%2F6fWrjnaO3xbLnoduJ%2Bq55HgVew%2FIHoUMZiLTc7JKe3Y09TuYPV3VpixE8Z0Ms9Grx2aAAZWMprcCpsEzbFUErqJuyk0Ubbz3oMFr8NETzZagS6fddtYltBbiyeF%2BziEMBCqNF8y1lfpCYNQ1fDegw0batPNDCb6ZkAstYMsjDP6lwaA1b7Y9DV033S5YB1mJsqAtGyrAeSVRFkIj6CbUdVwH%2BWb%2F2HuAhus0rDAbrXotus61LhKt%2FTX4DBLNjv7tVkE9bGNfaDNrabW3dBx74Klnp%2B4XHBeD%2FrWCpJpGvRNMP%2FPh%2BoC20EvlzwCNzmVg%2FnGg9pOHWA7AJdDSeHKVyoCf6LEl8LIhiN5yekoVQ7x7Qq468w2gP68meAc3mN5uygFJvwS83iSyiPpqUELjYAwooU7QgG%2BgGjTwF8qUJGECZjSS0bWqy2cQdEBbKl9Lv39P%2FgAQ2ul5m76dAQAAAABJRU5ErkJggg%3D%3D)](https://hyper3d.ai/)
  17. <table align="center">
  18. <tr>
  19. <td align="center"></td>
  20. <td align="center"><sub><b>DAILY</b></sub></td>
  21. <td align="center"><sub><b>WEEKLY</b></sub></td>
  22. </tr>
  23. <tr>
  24. <td align="right"><sub><b>Python</b></sub></td>
  25. <td><a href="https://trendshift.io/repositories/83608?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-83608" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/83608/daily?language=Python" alt="hoainho%2Fimg2threejs | Trendshift" width="250" height="55"/></a></td>
  26. <td><a href="https://trendshift.io/repositories/83608?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-83608" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/83608/weekly?language=Python" alt="img2threejs%2Fimg2threejs | Trendshift" width="250" height="55"/></a></td>
  27. </tr>
  28. <tr>
  29. <td align="right"><sub><b>All languages</b></sub></td>
  30. <td><a href="https://trendshift.io/repositories/83608?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-83608" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/83608/daily" alt="img2threejs%2Fimg2threejs | Trendshift" width="250" height="55"/></a></td>
  31. <td><a href="https://trendshift.io/repositories/83608?utm_source=trendshift-badge&amp;utm_medium=badge&amp;utm_campaign=badge-trendshift-83608" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/trendshift/repositories/83608/weekly" alt="img2threejs%2Fimg2threejs | Trendshift" width="250" height="55"/></a></td>
  32. </tr>
  33. </table>
  34. </div>
  35. *Reference images reconstructed in code as animation-ready Three.js models, running live in the browser.*
  36. ### [→ Open the Live Demo Gallery](https://img2threejs.io/)
  37. Every model in the gallery is generated code, running in your browser. No mesh files, no downloads.
  38. ---
  39. ## Live demos
  40. Reconstructions built entirely from primitives, procedural shaders, and generated geometry. Open any model to orbit it, inspect its reference, and read the generated source.
  41. <!-- showcase:start -->
  42. | Demo | Subject | Built with | View | Source |
  43. | --- | --- | --- | --- | --- |
  44. | Tropical Island — Code-only Diorama | object | — | [Live](https://img2threejs.io/#/demo/tropical-island) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/tropical-island/createTropicalIslandModel.ts) |
  45. | Man Robot · Segment Color Studio | character | — | [Live](https://img2threejs.io/#/demo/man-robot-studio) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/man-robot-studio/robotModel.ts) |
  46. | Snowbound Crossing — Mini Game | object | — | [Live](https://img2threejs.io/#/demo/snowy-village) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/snowy-village/createSnowyVillageModel.ts) |
  47. | Ocean Blue PRS Guitar — Measured Surface Flow | object | `v1.5.2` | [Live](https://img2threejs.io/#/demo/prs-ocean) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/prs-ocean/createPrsOceanModel.ts) |
  48. | Groot — Heart of the Forest | character | `v1.5.2` | [Live](https://img2threejs.io/#/demo/monster-tree) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/monster-tree/createMonsterTreeModel.ts) |
  49. | Raz — Detonating Strike VFX | character | `v1.5.2` | [Live](https://img2threejs.io/#/demo/raz) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/raz/razVfx.ts) |
  50. | Starship + Super Heavy | object | `v1.2.0` | [Live](https://img2threejs.io/#/demo/starship-super-heavy) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/starship-super-heavy/createStarshipSuperHeavyModel.ts) |
  51. | Mars Cat — Measured Procedural Surfaces | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/mars-cat) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/mars-cat/createMarsCatModel.ts) |
  52. | Lee Sin — Game Character | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/leesin) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/leesin/createLeesinModel.ts) |
  53. | Dual-Sword Warrior — Procedural Character | character | `v1.5.1` | [Live](https://img2threejs.io/#/demo/girl-character-3) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/girl-character-3/createGirlCharacter3Model.ts) |
  54. | AWP \| Medusa (Minimal Wear) · V2 rebuild | object | `v1.4.4` | [Live](https://img2threejs.io/#/demo/awp-medusa-v2) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/awp-medusa-v2/createAwpMedusaModelV2.ts) |
  55. | ★ Talon Knife \| Doppler Ruby (Factory New) | object | `v1.4.4` | [Live](https://img2threejs.io/#/demo/talon-doppler-ruby) | [code](https://github.com/img2threejs/img2threejs-showcase/blob/main/src/demos/talon-doppler-ruby/createTalonDopplerRubyModel.ts) |
  56. <!-- showcase:end -->
  57. The newest finished demos, generated from the gallery's
  58. [`demos.json`](https://img2threejs.io/demos.json) by `scripts/ci/showcase_table.py`. The gallery
  59. also has work in progress. **Built with** is the version tag in each demo's own `generatedWith`
  60. record (— when it names none).
  61. 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.
  62. ---
  63. ## What it does
  64. 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.
  65. It runs under Hermes, 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.
  66. ### Subjects and detail accuracy
  67. - **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`.
  68. - **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`.
  69. - **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`.
  70. - **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`.
  71. - **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. Ships with the CS2 domain plugin; see its `docs/cs2/review-gates.md`.
  72. - **Resumable local workflow.** `forge/state.py` records an ordered, evidence-backed intake/pass checklist for the generic profile and every registered domain (in-repo `character`, plus installed domain plugins such as CS2 and `animated-character` from plugin-character). `forge/next.py --state` resumes from that checklist while the existing spec, render, and review gates remain authoritative.
  73. - **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`](docs/materials/README.md).
  74. - **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`](grimoire/build/python_threejs_render_bridge.md).
  75. ---
  76. ## How it works
  77. 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.
  78. **→ Full pipeline diagram, gates, self-correction logic, script reference, and the token-efficiency design: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**
  79. ---
  80. ## Quick start
  81. Needs **Node.js ≥ 18, Git and Python ≥ 3.10**, and one of Claude Code, Codex, OpenCode or Hermes.
  82. ### 1. Install the base skill
  83. ```bash
  84. npx --yes img2threejs@latest install # links the skill into every agent it finds
  85. npx --yes img2threejs@latest doctor # one line per agent: "managed" means installed
  86. ```
  87. **Hermes users**, also link the skill into your profile (the installer only writes `~/.hermes/skills/`):
  88. ```bash
  89. ln -sfn ~/.hermes/skills/img2threejs ~/.hermes/profiles/${HERMES_ACTIVE_PROFILE:-img2threejs}/skills/img2threejs
  90. ```
  91. Then **restart your agent** and go to [step 4](#4-run-a-reconstruction-in-your-agent). Prefer to let
  92. your agent install it, want a manual or single-agent install, or something failed:
  93. [`docs/INSTALL.md`](docs/INSTALL.md) (paste-to-agent prompt, expected output, troubleshooting,
  94. update and uninstall, other agents such as Cursor).
  95. **Already installed?** Update with the row that matches your install in
  96. [`docs/INSTALL.md` §4](docs/INSTALL.md#4-update-an-existing-install).
  97. ### 2. Install the plugin harness, if needed
  98. Skip this unless you need a plugin from the table below. Plugins come from a separate CLI, the
  99. `img2` harness (`~/.img2`); install it once:
  100. ```bash
  101. npx --yes @img2threejs/img2@latest install --yes
  102. npx --yes @img2threejs/img2@latest plugins # the live catalog
  103. ```
  104. It links an `img2` command if `~/.local/bin`, `/opt/homebrew/bin` or `/usr/local/bin` is on your
  105. `PATH`; otherwise use the `npx --yes @img2threejs/img2@latest` form, or
  106. `alias img2='npx --yes @img2threejs/img2@latest'`. What it changes on your machine:
  107. [`docs/INSTALL.md` §3](docs/INSTALL.md#3-add-a-plugin-only-if-you-need-one).
  108. ### 3. Choose plugins — do not install everything by default
  109. <!-- plugins:start -->
  110. | Plugin / source README | Adds | Access | Install after harness setup |
  111. |---|---|---|---|
  112. | [character](https://github.com/img2threejs/plugin-character) | Character rigging and animation: skeleton from a GLB, skin conditioning, clip measurement, action design, and a twelve-check rig gate. | Public | `img2 add character --yes` |
  113. | [cs2](https://github.com/img2threejs/plugin-cs2) | Counter-Strike 2 weapon and glove skin reconstruction: intake contract, authoritative classification, finish/material recipes, and a blocking review gate. | Public | `img2 add cs2 --yes` |
  114. | [environment](https://github.com/img2threejs/plugin-environment) | Install and manage the private img2 environment plugin through the img2 harness. Authorized GitHub access is required. | **Private — authorized Git access required** | `img2 add environment --yes` |
  115. | [hello-cube](https://github.com/img2threejs/plugin-hello-cube) | Turn an image into a deterministic Three.js cube (contract exerciser) | Public | `img2 add hello-cube --yes` |
  116. | [img2glb](https://github.com/img2threejs/plugin-img2glb) | Turn an image into a GLB 3D mesh via the hosted TRELLIS space | Public | `img2 add img2glb --yes` |
  117. <!-- plugins:end -->
  118. The table above is generated from the live catalog (`scripts/ci/plugin_table.py`); list all
  119. plugins with `img2 plugins`. Open each plugin's linked README for its input requirements,
  120. dependencies and tool setup. Example (the `cs2` plugin; substitute any catalog id):
  121. ```bash
  122. img2 add cs2 --yes
  123. img2 list
  124. img2 doctor
  125. img2 sync --check
  126. ```
  127. An installed domain plugin contributes its checklist steps, evidence collection, spec
  128. augmentation (quality floors merge raise-only), and blocking review gates. With no plugins
  129. installed, the base has `generic` and `character` profiles. A profile whose plugin is
  130. missing (`cs2`, `animated-character`) fails loud naming what is installed; it never silently
  131. downgrades. The base skill is not a plugin: **do not use `img2 add` to install this repository.**
  132. **Private `environment` plugin:** needs a GitHub account with access to its repository and working
  133. Git credentials. The public [`img2-environment`](https://www.npmjs.com/package/img2-environment)
  134. installer can bootstrap the harness but does not grant that access. Hermes users link each plugin
  135. by hand ([`docs/INSTALL.md` §3](docs/INSTALL.md#3-add-a-plugin-only-if-you-need-one)). Why a run
  136. cannot see an installed plugin, and how plugins reach the pipeline: [`docs/PLUGINS.md`](docs/PLUGINS.md).
  137. To write a plugin, follow [WRITING_A_PLUGIN.md](https://github.com/img2threejs/img2/blob/main/docs/WRITING_A_PLUGIN.md).
  138. ### 4. Run a reconstruction in your agent
  139. Restart the agent (or start a new session) after installing skills.
  140. In Claude Code, attach an image or give its path and invoke:
  141. ```text
  142. /img2threejs Rebuild the object in ./reference.png as a procedural Three.js model.
  143. Keep its proportions, silhouette and colours. Follow the quality gates.
  144. Report the output files, render-review evidence and any inferred regions.
  145. ```
  146. In another host, ask the agent to use the installed `img2threejs` skill with that image.
  147. For a plugin workflow, name the profile explicitly, for example:
  148. ```text
  149. Use img2threejs with the installed cs2 domain and ./reference.png.
  150. Follow the cs2 profile and its family-specific reconstruction and review gates.
  151. ```
  152. ```text
  153. Use img2threejs with the installed character plugin and ./reference.png.
  154. Follow the animated-character profile. Do not claim animation readiness until its rig gates pass.
  155. ```
  156. The agent validates the image, writes an assessment and spec, generates the factory pass
  157. by pass, and reviews rendered comparisons. Installation alone does none of that.
  158. For a multi-session reconstruction, run these from the skill root:
  159. ```bash
  160. python3 forge/state.py init --reference <image> --profile character --spec object-sculpt-spec.json
  161. python3 forge/next.py --state .img2threejs/state.json
  162. ```
  163. ### 5. Audit and maintain the installation
  164. ```bash
  165. npx --yes img2threejs@latest doctor # base-skill host/link report
  166. img2 doctor # static audit of registered plugins
  167. img2 update cs2 --check # read-only check for a newer plugin version
  168. img2 update cs2 # install a newer available plugin version
  169. img2 remove cs2 # unlink owned links and back up the managed checkout
  170. ```
  171. Neither doctor command proves visual likeness or animation quality; those require the
  172. reconstruction's render and domain gates. `img2 update --check` exits 1 when an update is
  173. pending, not only on errors. Local `--link` checkouts are live and are not fetched by update.
  174. Symptoms and fixes: [`docs/INSTALL.md` §6](docs/INSTALL.md#6-when-something-is-off); plugin
  175. audit exit codes and replacement behaviour: the
  176. [img2 README](https://github.com/img2threejs/img2#refs-replacement-and-common-refusals).
  177. ### Driving it harder
  178. 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:
  179. ```
  180. /img2threejs Rebuild the subject in this image as a procedural Three.js model.
  181. Fidelity Hold proportions and silhouette to the reference. Enumerate the identity-defining
  182. details first — bevels and rounding, panel seams, fasteners, engraved or painted
  183. linework, gloss vs matte zones, wear — and drop any detail you cannot place on a
  184. real component instead of faking it.
  185. Materials Derive the finish class and gradient stops from the reference pixels, not from
  186. memory. Flag any colour that will not survive tone-mapping.
  187. Runtime Expose pivots and sockets for whatever should move, plus a userData.tick for a
  188. looping idle animation.
  189. Gates Run --strict-quality, and do not advance a pass until the side-by-side review
  190. passes. Report per-region confidence for anything the image cannot show.
  191. ```
  192. Useful additions depending on the subject:
  193. - **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.`
  194. - **An animal or creature** — `This is a creature, not a humanoid — use the quadruped body plan and the body-unit proportion system.`
  195. - **A saturated anodized or candy finish** — `The coat is candy-coat, not gem-metal. Keep the hue; do not let the environment steal it.`
  196. - **A cost ceiling** — `Stay at low effort and skip the presentation composer; I only need the evaluation render.`
  197. The scripts run from the skill root and need only Python 3.10+ — nothing to install.
  198. ```bash
  199. python3 forge/stage1_intake/probe_image.py <image>
  200. python3 forge/stage2_spec/new_pre_spec_assessment.py "Name" --image <image> --out assessment.json
  201. python3 forge/stage2_spec/new_sculpt_spec.py "Name" --image <image> --assessment assessment.json --out spec.json
  202. python3 forge/stage2_spec/validate_sculpt_spec.py spec.json --strict-quality
  203. python3 forge/stage3_build/generate_threejs_factory.py spec.json --out src/createObjectModel.ts
  204. ```
  205. The factory generator repeats the strict-quality gate and is fail-closed: on failure it returns
  206. `BLOCKED` with the spec artifact, failure metrics, causes, and next action, and does not write a
  207. factory. `--allow-nonstrict` is only for explicit legacy test fixtures, never production output.
  208. ### Copy-paste prompts for the GLB-reference route
  209. Rebuilding a character from a **GLB reference** rather than a photo is a different route with its own
  210. gates — the GLB is a measurement instrument and never ships. Three prompts cover it, each in its own
  211. copy block:
  212. | Prompt | Use it when | Do not use it when |
  213. |---|---|---|
  214. | [Build](docs/GLB_CHARACTER_PROMPT.md) | you have a GLB and no built surfaces yet | there is no GLB, or the build already completed and merely looks wrong |
  215. | [Polish](docs/GLB_CHARACTER_POLISH_PROMPT.md) | the build completed and the result does not look like the GLB | the surfaces were never built — that is a build re-run, not a polish |
  216. | [Animation](docs/GLB_CHARACTER_ANIMATION_PROMPT.md) | the figure looks right standing still and has passed the build gates | the surface is ungated, or `joint_loops.py` fails — that is a surface finding no weight tuning reaches |
  217. They force every parameter the GLB genuinely carries — size, proportions, per-band widths and
  218. centroids, base colour, roughness and metalness — to the measured value, with the check that proves
  219. it landed. Three things are **not** 1:1 and each prompt says so: rigging and animation are usually
  220. absent from the asset (`skinCount: 0`, `animationCount: 0`), texture images and normal maps are
  221. deliberately not copied per this skill's code-only contract, and nothing finer than the node's cell
  222. size can be carried at all.
  223. **These are reference material, not a guarantee.** They are written to be general, so the measured
  224. figures in them came from one character and are there to show what to measure — not values to copy.
  225. Run the one that matches your situation rather than all three in sequence; each notes the cost of
  226. being used out of turn.
  227. For the script-by-script reference, the full scripts table, and expected artifacts, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  228. ---
  229. ## Why it is token-efficient
  230. 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.
  231. - **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.
  232. - **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.
  233. - **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.
  234. - **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.
  235. - **One image per review.** Each pass is judged from exactly one packaged comparison sheet (reference beside render), not a scattering of screenshots.
  236. - **Text output, not binaries.** The result is diffable TypeScript plus a JSON spec — small, reviewable, and version-controllable, instead of multi-megabyte mesh files.
  237. 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](docs/TOKEN_COST.md).
  238. ---
  239. ## Scripts
  240. | Script | Role |
  241. | --- | --- |
  242. | `stage1_intake/probe_image.py` | Image metadata and obvious technical issues (not a visual check). |
  243. | `stage2_spec/new_pre_spec_assessment.py` | Classify the object, score complexity, emit a quality contract. |
  244. | `stage2_spec/new_sculpt_spec.py` | Author the ObjectSculptSpec from the assessment. |
  245. | `stage2_spec/validate_sculpt_spec.py` | Validate the spec; `--strict-quality` blocks shallow specs before codegen. |
  246. | `stage1_intake/extract_pbr_evidence.py` | Reference-derived PBR evidence per crop (inference, not inverse rendering). |
  247. | `stage1_intake/material_region_analysis.py` | Crop material regions, run texture/PBR evidence, and resolve registry profiles. |
  248. | `stage2_spec/apply_material_analysis.py` | Wire region assignments, priors, maps, and provenance into ObjectSculptSpec. |
  249. | `stage3_build/orchestrate_passes.py` | Locked pass state: status, check, sync. |
  250. | `stage3_build/generate_threejs_factory.py` | Emit the Three.js `Group` factory for the current unlocked pass. |
  251. | `stage4_review/material_views.py` | Emit multi-angle, zoomed, microscope, environment, and capture-readback contracts. |
  252. | `stage4_review/material_comparator.py` | Compare the visible material crop and classify per-channel mismatches. |
  253. | `stage4_review/material_feedback.py` | Apply bounded, material-scoped corrections through the existing stop policy. |
  254. | `stage4_review/material_gate.py` | Block material-pass until registry, crop, render, compatibility, and comparison evidence passes. |
  255. | `stage4_review/make_comparison_sheet.py` | Package one reference-vs-render sheet for review. |
  256. | `stage4_review/append_review.py` | Record a per-pass review: scores, decision, evidence. |
  257. | `_shared/feature_acceptance_policy.py` | Internal helper enforcing per-feature score thresholds. |
  258. | `stage1_intake/build_detail_inventory.py` | Slice the reference into zones and scaffold a detail inventory. |
  259. | `stage1_intake/extract_landmarks.py` | Overlay a landmark grid and scaffold an anatomy block for characters. |
  260. | `stage1_intake/solve_camera_pose.py` | Emit a reference-camera block so the render can be camera-matched. |
  261. | `stage1_intake/delight_albedo.py` | Approximate a neutral albedo from the photo before texture projection. |
  262. | `stage3_build/bake_projected_texture.py` | Emit a projection/UV-bake descriptor for photo-texture projection. |
  263. | `stage5_rig/rig_spec.py` | Derive and validate a skeleton from the component tree, so bones cannot drift from the geometry. |
  264. | `stage5_rig/geodesic_skinning.py` | Vertex weights from distance measured through the solid; keeps rigid roles out of smooth skinning. |
  265. | `stage5_rig/validate_rig_payload.py` | Blocking payload-integrity gate before a `THREE.Skeleton` is bound. |
  266. | `stage1_intake/extract_hair_evidence.py` | Hair/skin split, banded coverage, hairline, highlight band, root-to-tip delta. |
  267. | `stage4_review/scalp_exposure.py` | HARD gate: finds bald patches on geometry, before any render. |
  268. | `stage4_review/hair_gate.py` | Soft gate: hair coverage, hairline and highlight offsets against the reference. |
  269. | `stage4_review/interior_difference.py` | Appearance difference inside the silhouette, banded by height. Required per visual pass. |
  270. | `_shared/chirality.py` | Left/right as an importable convention, with the two gates the two chirality defects need. |
  271. | `_shared/pipeline_routing.py` | Fail-closed weapon/character routing; low confidence resolves to `request-input`. |
  272. This is a curated selection — `forge/` holds around ninety modules. The executable reference with every flag is [`grimoire/scripts.md`](grimoire/scripts.md), and the gate-by-gate contract is [`grimoire/review/gates_reference.md`](grimoire/review/gates_reference.md). The rest of `grimoire/` holds the rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).
  273. ### Optional reference-fidelity tooling
  274. The stdlib-only core can use an isolated evidence layer without taking on runtime dependencies:
  275. SAM2 component masks, Depth Anything V2 relative-depth priors, MediaPipe face/pose landmarks,
  276. Chrome DevTools diagnostics, Three.js scene inspection, Playwright cross-browser fallback, and
  277. version-aware Context7 retrieval. These tools never approve a pass or silently provide geometry.
  278. Install, routing, provenance rules and exact commands:
  279. [`docs/integrations/reference_fidelity_tooling.md`](docs/integrations/reference_fidelity_tooling.md).
  280. ### Optional GLB-baseline character pipeline
  281. [`integrations/glb_character_pipeline`](integrations/glb_character_pipeline) reconstructs a character
  282. from a **multipart GLB used as a measurement instrument plus its diffuse image**, and emits the
  283. procedural TypeScript the demo actually ships — no `.glb` or `.bin` is fetched at runtime. It carries
  284. its own `pyproject.toml`/`uv.lock` so the stdlib-only `forge` core stays dependency-free, and operates
  285. on a companion showcase checkout via `IMG2THREEJS_SHOWCASE_ROOT`.
  286. It applies **only** when a build has a GLB to measure — skip it entirely otherwise, and use the core
  287. image-driven pipeline instead. Reproduces `girl-character`'s shipped `crossSections.ts` exactly (748
  288. rings, 86,240 ring points). Method and per-stage rationale:
  289. [`PIPELINE.md`](integrations/glb_character_pipeline/PIPELINE.md).
  290. ---
  291. ## What you get
  292. - An `ObjectSculptSpec` JSON: the full component tree, materials, repetition systems, sockets, and a recorded review history for every pass.
  293. - A TypeScript `createObjectNameModel(spec, options)` factory returning a `THREE.Group`, with `root.userData.sculptRuntime` exposing nodes, sockets, colliders, and destruction groups.
  294. - For character builds, `root.userData.rig`: bones, one shared `Skeleton`, bone order and index map, and a `bound` flag computed from whether every skinned mesh actually bound.
  295. - A render plus comparison sheets documenting the fidelity at each pass.
  296. For the script-by-script reference and the full list of output artifacts, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
  297. ---
  298. ## Roadmap
  299. **Shipped:**
  300. - **v1.0** — object pipeline: staged sculpt, render-vs-reference review loop, action-ready hierarchy.
  301. - **v1.1** — detail-first analysis: required detail inventory, strict-quality gate.
  302. - **v1.2** — humanoid character generator: anatomy track, proportion-lock and feature-placement passes.
  303. - **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.
  304. - **v1.4 — The Weapon Update** — CS2 image-matched reconstruction: provenance-aware intake, projection-first finishes, family-specific weapon adapters, and structural review gates.
  305. - **v1.4.1** — CS2 hardening: explicit component coverage, a dedicated Glock-18 assembly contract, map-stripped blockout evidence, and stricter geometry-integrity checks.
  306. - **creature generator** — 4 body plans (quadruped / avian / winged-dragon / serpentine), `animalAnatomy` spec, spine-loft geometry, ΔE00 colour gates.
  307. - **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.
  308. - **v2.0 — The Plugin Update** — the domain registry, pull-based spec augmentation
  309. with raise-only quality floors, the emission-target socket with provenance, per-plugin blocking
  310. gates, and the img2 harness (`img2 install/add/doctor`). CS2 extracted into `plugin-cs2`,
  311. `animated-character` served by `plugin-character`; the base names no domain. The "plugin
  312. ecosystem and API" originally slotted for the Procedural World bundle, shipped first as its own major.
  313. **Next — one theme per release:**
  314. - **v2.1 — The Character Split**: the in-repo `character` domain joins `plugin-character`, so the base names no domain and the v2.0 plugin split closes.
  315. - **v2.2 — The Environment Update**: buildings, rooms, streets, vegetation, terrain-aware and multi-object reconstruction.
  316. - **v2.3 — The Game Pipeline Update**: Unity and Unreal exporters, a Blender bridge, LOD and collision-mesh generation.
  317. - **v2.4 — The Animation Update**: auto rigging, auto skin weights, Mixamo compatibility, facial rig.
  318. - **v2.5 — The AI Studio Update**: web UI, batch processing, visual prompt builder, cloud rendering.
  319. - **v3.0 — The Procedural World Update**: multi-view reconstruction, procedural city generation, semantic world understanding.
  320. The arc: assets (v1.4–v1.5) → the plugin ecosystem (v2.0–v2.1) → worlds (v2.2–v2.3) → production (v2.4–v2.5) → an AI game-asset platform that generates playable worlds from reference images (v3.0).
  321. **→ 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).
  322. ---
  323. ## Honesty about limits
  324. 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.
  325. ---
  326. ## Star history
  327. If img2threejs is useful to you, a star helps others find it.
  328. <a href="https://www.star-history.com/#hoainho/img2threejs&Timeline">
  329. <picture>
  330. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=hoainho/img2threejs&type=timeline&theme=dark&legend=top-left&sealed_token=HhzHOwb32twyQntl75HMLNf5E7hkH9aNTaSpn20ZThsyQC2Rt7fA_Wthz0osSgItW_WUiwA3MUa5-7GXquQCVL1uHLePUOUN9uVoiArBCm-l21DXJ51yVQ" />
  331. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=hoainho/img2threejs&type=timeline&legend=top-left&sealed_token=HhzHOwb32twyQntl75HMLNf5E7hkH9aNTaSpn20ZThsyQC2Rt7fA_Wthz0osSgItW_WUiwA3MUa5-7GXquQCVL1uHLePUOUN9uVoiArBCm-l21DXJ51yVQ" />
  332. <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=hoainho/img2threejs&type=timeline&legend=top-left&sealed_token=HhzHOwb32twyQntl75HMLNf5E7hkH9aNTaSpn20ZThsyQC2Rt7fA_Wthz0osSgItW_WUiwA3MUa5-7GXquQCVL1uHLePUOUN9uVoiArBCm-l21DXJ51yVQ" width="600" />
  333. </picture>
  334. </a>
  335. ---
  336. ## Support the project
  337. img2threejs is free and open source. If it saved you time or found its way into your project, consider supporting continued development:
  338. [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/O8A625YLSR)
  339. VietQR / MoMo / PayPal also work — see the [donate page](https://img2threejs.io/donate.html).
  340. ---
  341. ## Sponsors
  342. Reconstruction-by-code is an inference workload before it is a graphics one: every gate rerun, every
  343. render-vs-reference pass and every material fit spends tokens. These four pay for that loop.
  344. <table>
  345. <tr>
  346. <td align="center" width="200">
  347. <a href="https://platform.minimax.io/subscribe/token-plan" target="_blank" rel="noopener noreferrer">
  348. <picture>
  349. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/minimax-logomark.svg" />
  350. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/minimax-logomark.svg" />
  351. <img alt="MiniMax" src="assets/sponsors/minimax-logomark.svg" width="72" height="60" />
  352. </picture>
  353. </a>
  354. <br /><sub><b>MiniMax</b></sub>
  355. <br /><sub>Token-plan model API</sub>
  356. </td>
  357. <td align="center" width="200">
  358. <a href="https://www.atlascloud.ai/console/coding-plan" target="_blank" rel="noopener noreferrer">
  359. <picture>
  360. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/atlas-cloud-logomark-white.svg" />
  361. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/atlas-cloud-logomark-black.svg" />
  362. <img alt="Atlas Cloud" src="assets/sponsors/atlas-cloud-logomark-black.svg" width="72" height="67" />
  363. </picture>
  364. </a>
  365. <br /><sub><b>Atlas Cloud</b></sub>
  366. <br /><sub>Full-modal AI inference</sub>
  367. </td>
  368. <td align="center" width="200">
  369. <a href="https://www.tripo3d.ai/" target="_blank" rel="noopener noreferrer">
  370. <picture>
  371. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/tripo-logomark-white.svg" />
  372. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/tripo-logomark-black.svg" />
  373. <img alt="Tripo" src="assets/sponsors/tripo-logomark-black.svg" width="68" height="68" />
  374. </picture>
  375. </a>
  376. <br /><sub><b>Tripo</b></sub>
  377. <br /><sub>Image &amp; text to 3D</sub>
  378. </td>
  379. <td align="center" width="200">
  380. <a href="https://hyper3d.ai/" target="_blank" rel="noopener noreferrer">
  381. <picture>
  382. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/hyper3d-logomark-white.png" />
  383. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/hyper3d-logomark-black.png" />
  384. <img alt="Hyper3D" src="assets/sponsors/hyper3d-logomark-black.png" width="68" height="68" />
  385. </picture>
  386. </a>
  387. <br /><sub><b>Hyper3D</b></sub>
  388. <br /><sub>Rodin generative 3D</sub>
  389. </td>
  390. </tr>
  391. </table>
  392. ### MiniMax
  393. <img alt="" src="assets/sponsors/minimax-logomark.svg" width="38" height="32" align="right" />
  394. **[MiniMax](https://platform.minimax.io/subscribe/token-plan)** is a global AI foundation model company founded in early 2022, committed to advancing the frontiers of AI towards AGI under the mission "Intelligence with Everyone." MiniMax has independently developed a family of multimodal foundation models with strong code and agent capabilities plus ultra-long context processing — spanning text, audio, image, video, and music. The same company publishes [MiniMax Code](https://code.minimax.io), [MiniMax Design](https://design.minimax.io/), [MiniMax Audio](https://www.minimax.io/audio) and [Talkie](https://www.talkie-ai.com/), and serves a token-plan API platform for developers and enterprises at <https://platform.minimax.io/subscribe/token-plan>. Check the token plan for budget-friendly access to the M3, M2.7, M2.5, H3, Speech 2.8 and Music 3.0 model families.
  395. ### Atlas Cloud
  396. <picture>
  397. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/atlas-cloud-logomark-white.svg" />
  398. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/atlas-cloud-logomark-black.svg" />
  399. <img alt="" src="assets/sponsors/atlas-cloud-logomark-black.svg" width="38" height="36" align="right" />
  400. </picture>
  401. **[Atlas Cloud](https://www.atlascloud.ai/console/coding-plan)** is a full-modal AI inference
  402. platform: one AI API for video generation, image generation and LLM access, with unified access to
  403. 300+ curated models across every modality instead of a separate integration per vendor.
  404. That single endpoint is what keeps this project's loop affordable — the pipeline is token-hungry by
  405. design, because gating a spec before codegen means running the analysis more than once. Atlas Cloud's
  406. coding plan is the budget-friendly route to that API.
  407. **→ [Open the Atlas Cloud coding plan](https://www.atlascloud.ai/console/coding-plan)**
  408. ### Tripo
  409. <picture>
  410. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/tripo-logomark-white.svg" />
  411. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/tripo-logomark-black.svg" />
  412. <img alt="" src="assets/sponsors/tripo-logomark-black.svg" width="38" height="38" align="right" />
  413. </picture>
  414. **[Tripo](https://www.tripo3d.ai/)** turns a prompt or a reference image into a production 3D asset:
  415. High Detail meshes up to 2M polygons for render and print, artist-grade quad **Smart Mesh** from 500
  416. to 50K triangles for real-time engines, AI auto-rigging, PBR texturing up to 8K, and part-level
  417. segmentation. Exports GLB, FBX, OBJ, USD, STL and 3MF, with first-party plugins for Blender, Unity,
  418. Unreal, Godot, Cocos and ComfyUI.
  419. It pairs with img2threejs as the measuring stick. A procedural rebuild lives or dies on silhouette,
  420. proportion and joint placement, and a quad mesh plus an auto-rig of the same subject gives those
  421. gates a second read that one reference photograph cannot settle on its own.
  422. **→ [Open Tripo Studio](https://www.tripo3d.ai/)**
  423. ### Hyper3D
  424. <picture>
  425. <source media="(prefers-color-scheme: dark)" srcset="assets/sponsors/hyper3d-logomark-white.png" />
  426. <source media="(prefers-color-scheme: light)" srcset="assets/sponsors/hyper3d-logomark-black.png" />
  427. <img alt="" src="assets/sponsors/hyper3d-logomark-black.png" width="38" height="38" align="right" />
  428. </picture>
  429. **[Hyper3D](https://hyper3d.ai/)** builds **Rodin**, which generates a 3D asset from a prompt or an
  430. image in seconds with high reference fidelity and coherent detail across views. Generation is
  431. steerable rather than a dice roll: bounding-box, voxel and point-cloud ControlNet guidance, partial
  432. editing to refine one region without disturbing the rest, smart low-poly optimisation, and
  433. ChatAvatar for rigged production faces. Exports STL, FBX, OBJ, GLB, glTF and USDZ.
  434. It answers the one question a single photograph never can — what the back looks like. Generate the
  435. subject, orbit it, and the hidden sides become references the material and surface gates can actually
  436. be run against, instead of assumptions the pipeline has to make silently.
  437. **→ [Open Hyper3D Rodin](https://hyper3d.ai/)**
  438. ---
  439. Sponsorship pays for compute, not for coverage: a sponsor's product is described here in its own
  440. terms, and no gate, default or benchmark in this repository is weighted toward one. Want your logo in
  441. this row? Open an issue or write to <hoainho.work@gmail.com>.
  442. ---
  443. ## Contributing
  444. Contributions are welcome — procedural material recipes, new gates, host coverage, and demos especially. See [CONTRIBUTING.md](CONTRIBUTING.md) and the [roadmap](ROADMAP.md) for where the project is headed.
  445. ## License
  446. Apache License 2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.