[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93488":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":36,"readmeContent":37,"aiSummary":10,"trendingCount":16,"starSnapshotCount":16,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},93488,"img2threejs","hoainho\u002Fimg2threejs","hoainho","Rebuild the object in a reference image as a code-only, procedural, quality-gated, animation-ready Three.js model. Token-efficient image-to-3D.","https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F",null,"Python",1230,97,1,7,0,431,903,1765,103.97,"MIT License",false,"main",true,[26,27,28,29,30,31,32,33,34,35],"3d","ai-agents","claude-code","computer-graphics","generative","image-to-3d","procedural-generation","threejs","typescript","webgl","2026-07-22 04:02:09","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"assets\u002Flogo.svg\" width=\"112\" height=\"112\" alt=\"img2threejs logo\" \u002F>\n\n# img2threejs\n\n**Rebuild the object in a reference image as a code-only, procedural Three.js model.**\n\nQuality-gated, animation-ready, and deliberately token-efficient — reconstruction-by-code, not photogrammetry, mesh extraction, or downloaded art packs.\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n[![Version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fversion-1.2.0-green.svg)](SKILL.md)\n[![PRs welcome](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![Runtime](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fruntime-Three.js-000000.svg)](https:\u002F\u002Fthreejs.org)\n[![Tooling](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Ftooling-Python%203.10%2B%20stdlib-3776ab.svg)](scripts)\n\n![img2threejs demo — a reference loot-chest image reconstructed as a procedural Three.js model](assets\u002Fdemo.gif)\n\n\u003C\u002Fdiv>\n\n*A single reference image reconstructed in code — correct proportions, colours, bevels, gold trim, and an emissive emblem — running live in the browser.*\n\n### [→ Open the Live Demo Gallery](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F)\n\nEvery model in the gallery is generated code, running in your browser. No mesh files, no downloads.\n\n---\n\n## Live demos\n\nReconstructions built entirely from primitives, procedural shaders, and generated geometry. The clips below are the live models running in-browser — open each one to orbit it and read the generated source.\n\n| Demo | Preview | Subject | View | Source |\n| --- | --- | --- | --- | --- |\n| Sony WF-1000XM3 Earbuds + Case | \u003Cimg src=\"assets\u002Fsony-wf1000xm3.gif\" width=\"260\" alt=\"Sony WF-1000XM3 live demo\" \u002F> | hard-surface object | [Live](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F#\u002Fdemo\u002Fsony-wf1000xm3) | [code](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase\u002Fblob\u002Fmain\u002Fsrc\u002Fdemos\u002Fsony-wf1000xm3\u002FcreateSonyWf1000xm3Model.ts) |\n| ISSACA 12 Gauge Shotgun | \u003Cimg src=\"assets\u002Fissaca-shotgun.gif\" width=\"260\" alt=\"ISSACA 12 Gauge Shotgun live demo\" \u002F> | hard-surface object | [Live](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F#\u002Fdemo\u002Fissaca-shotgun) | [code](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase\u002Fblob\u002Fmain\u002Fsrc\u002Fdemos\u002Fissaca-shotgun\u002FcreateIssacaShotgunModel.ts) |\n| Gerber Paracord Knife | \u003Cimg src=\"assets\u002Fgerber-knife.gif\" width=\"260\" alt=\"Gerber Paracord Knife live demo\" \u002F> | hard-surface object | [Live](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F#\u002Fdemo\u002Fgerber-knife) | [code](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase\u002Fblob\u002Fmain\u002Fsrc\u002Fdemos\u002Fgerber-knife\u002FcreateGerberKnifeModel.ts) |\n| Doraemon House (isometric diorama) | \u003Cimg src=\"assets\u002Fdoraemon-house.gif\" width=\"260\" alt=\"Doraemon House live demo\" \u002F> | hard-surface object | [Live](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F#\u002Fdemo\u002Fdoraemon-house) | [code](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase\u002Fblob\u002Fmain\u002Fsrc\u002Fdemos\u002Fdoraemon-house\u002FcreateDoraemonHouseModel.ts) |\n| War-Hauler \"SECTOR 07\" | \u003Cimg src=\"assets\u002Fwarhauler.gif\" width=\"260\" alt=\"War-Hauler SECTOR 07 live demo\" \u002F> | hard-surface object | [Live](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F#\u002Fdemo\u002Fwarhauler) | [code](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase\u002Fblob\u002Fmain\u002Fsrc\u002Fdemos\u002Fwarhauler\u002FcreateWarHaulerModel.ts) |\n| Crowned Loot Chest | \u003Cimg src=\"assets\u002Fcrown-chest.gif\" width=\"260\" alt=\"Crowned Loot Chest live demo\" \u002F> | hard-surface object | [Live](https:\u002F\u002Fhoainho.github.io\u002Fimg2threejs-showcase\u002F#\u002Fdemo\u002Fcrown-chest) | [code](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase\u002Fblob\u002Fmain\u002Fsrc\u002Fdemos\u002Fcrown-chest\u002FcreateCrownChestModel.ts) |\n\nThe gallery source lives in [hoainho\u002Fimg2threejs-showcase](https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs-showcase). If this project is useful, a star on this repo helps others find it.\n\n---\n\n## What it does\n\nYou 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.\n\nIt runs under Claude Code, Codex, or OpenCode. It is agent-agnostic: wherever the docs say \"agent vision\" or \"agent browser tool\", it uses whatever the host provides — native image reading, a browser MCP, the project preview, or a user-supplied screenshot.\n\n### Subjects and detail accuracy\n\n- **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\u002Fcharacter\u002Freconstruction.md`.\n- **Detail-first analysis.** Before code generation the pipeline enumerates a `detailInventory` of identity-defining small details (gloss, bevel\u002Frounding, screws\u002Frivets, 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\u002Fintake\u002Fdetail_inventory.md`.\n- **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\u002Fcharacter\u002Flikeness_maximization.md`.\n\n---\n\n## How it works\n\nThe skill runs a staged sculpting pipeline. Scripts gate each stage; the agent's vision is the only thing that can approve a pass.\n\n```mermaid\nflowchart TD\n    A[Reference image] --> B[Probe and suitability gate]\n    B --> C[Pre-Spec Assessment: class, complexity, quality contract]\n    C --> D[Author ObjectSculptSpec: components, materials, sockets]\n    D --> E{Validate and strict-quality}\n    E -- too shallow --> D\n    E -- ok --> F[Locked build passes]\n    F --> G[Generate Three.js factory: current pass only]\n    G --> H[Render in browser and screenshot]\n    H --> I[Package one side-by-side sheet]\n    I --> J{Agent vision review}\n    J -- score below threshold --> K[Self-correct: refine-spec or refine-code]\n    K --> F\n    J -- pass --> L{More passes?}\n    L -- yes --> F\n    L -- no --> M[Animation-ready Three.js model]\n```\n\n### Build passes\n\nThe model is sculpted in a fixed order; a pass unlocks only after the previous one is reviewed and accepted:\n\n`blockout → structural-pass → form-refinement → material-pass → surface-pass → lighting-pass → interaction-pass → optimization-pass`\n\nEach pass has its own acceptance criteria. A pass is marked `continue` only with a real render, a comparison sheet, an agent-vision score at or above threshold, and every identity-defining feature at or above its own threshold.\n\n### The gates\n\n- **Suitability** — is the image a viable 3D target at all.\n- **Pre-spec and strict-quality** — blocks code generation until the spec is deep enough for the object's complexity (no single-root spec for a compound object).\n- **Screenshot feedback** — `continue` requires a render plus a comparison sheet plus a passing vision score.\n- **Action-ready** — the model exposes a runtime hierarchy (pivots, sockets, colliders, destruction groups) via `root.userData.sculptRuntime`.\n- **Attachment correctness** — child parts (handles, limbs, tubes) declare how they join their parent, so nothing floats in mid-air.\n- **Material and lighting realism** — independent PBR channels and real lights, never albedo aliased into roughness.\n\n### Self-correction\n\nAfter every pass the agent chooses exactly one action: `continue`, `refine-spec`, `refine-code`, `request-input`, or `stop`. `refine-spec` fixes a wrong or shallow spec and re-validates; `refine-code` fixes geometry, material, or lighting that does not match a sound spec.\n\n---\n\n## Quick start\n\n1. **Install** — place this folder in your skills directory:\n\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Fhoainho\u002Fimg2threejs.git ~\u002F.claude\u002Fskills\u002Fimg2threejs\n   ```\n\n2. **Invoke** — in Claude Code, attach or point to an object image and run:\n\n   ```\n   \u002Fimg2threejs Rebuild this object as a Three.js model, keep the proportions, angles, and colours.\n   ```\n\n3. **Follow the pipeline** — the skill validates the image, writes an assessment and spec, generates the factory pass by pass, and shows you a side-by-side comparison at each step until the render matches.\n\nThe scripts run from the skill root and need only Python 3.10+ — nothing to install.\n\n```bash\npython3 forge\u002Fstage1_intake\u002Fprobe_image.py \u003Cimage>\npython3 forge\u002Fstage2_spec\u002Fnew_pre_spec_assessment.py \"Name\" --image \u003Cimage> --out assessment.json\npython3 forge\u002Fstage2_spec\u002Fnew_sculpt_spec.py \"Name\" --image \u003Cimage> --assessment assessment.json --out spec.json\npython3 forge\u002Fstage2_spec\u002Fvalidate_sculpt_spec.py spec.json --strict-quality\npython3 forge\u002Fstage3_build\u002Fgenerate_threejs_factory.py spec.json --out src\u002FcreateObjectModel.ts\n```\n\n---\n\n## Why it is token-efficient\n\nMost 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.\n\n- **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.\n- **Zero dependencies, zero install churn.** Every script is pure Python 3.10+ standard library. No pip, no PIL, no numpy, no Playwright. PNG read\u002Fwrite is done with `struct` and `zlib`. Nothing to install means nothing to debug in-context.\n- **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.\n- **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.\n- **One image per review.** Each pass is judged from exactly one packaged comparison sheet (reference beside render), not a scattering of screenshots.\n- **Text output, not binaries.** The result is diffable TypeScript plus a JSON spec — small, reviewable, and version-controllable, instead of multi-megabyte mesh files.\n\nThe 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\u002FTOKEN_COST.md](docs\u002FTOKEN_COST.md).\n\n---\n\n## Scripts\n\n| Script | Role |\n| --- | --- |\n| `stage1_intake\u002Fprobe_image.py` | Image metadata and obvious technical issues (not a visual check). |\n| `stage2_spec\u002Fnew_pre_spec_assessment.py` | Classify the object, score complexity, emit a quality contract. |\n| `stage2_spec\u002Fnew_sculpt_spec.py` | Author the ObjectSculptSpec from the assessment. |\n| `stage2_spec\u002Fvalidate_sculpt_spec.py` | Validate the spec; `--strict-quality` blocks shallow specs before codegen. |\n| `stage1_intake\u002Fextract_pbr_evidence.py` | Reference-derived PBR evidence per crop (inference, not inverse rendering). |\n| `stage3_build\u002Forchestrate_passes.py` | Locked pass state: status, check, sync. |\n| `stage3_build\u002Fgenerate_threejs_factory.py` | Emit the Three.js `Group` factory for the current unlocked pass. |\n| `stage4_review\u002Fmake_comparison_sheet.py` | Package one reference-vs-render sheet for review. |\n| `stage4_review\u002Fappend_review.py` | Record a per-pass review: scores, decision, evidence. |\n| `_shared\u002Ffeature_acceptance_policy.py` | Internal helper enforcing per-feature score thresholds. |\n| `stage1_intake\u002Fbuild_detail_inventory.py` | Slice the reference into zones and scaffold a detail inventory. |\n| `stage1_intake\u002Fextract_landmarks.py` | Overlay a landmark grid and scaffold an anatomy block for characters. |\n| `stage1_intake\u002Fsolve_camera_pose.py` | Emit a reference-camera block so the render can be camera-matched. |\n| `stage1_intake\u002Fdelight_albedo.py` | Approximate a neutral albedo from the photo before texture projection. |\n| `stage3_build\u002Fbake_projected_texture.py` | Emit a projection\u002FUV-bake descriptor for photo-texture projection. |\n\nThe `grimoire\u002F` folder holds the detailed rubrics each gate applies (validation, pre-spec assessment, procedural patterns, material and lighting realism, attachment correctness, action-ready models, self-correction).\n\n---\n\n## What you get\n\n- An `ObjectSculptSpec` JSON: the full component tree, materials, repetition systems, sockets, and a recorded review history for every pass.\n- A TypeScript `createObjectNameModel(spec, options)` factory returning a `THREE.Group`, with `root.userData.sculptRuntime` exposing nodes, sockets, colliders, and destruction groups.\n- A render plus comparison sheets documenting the fidelity at each pass.\n\n---\n\n## Roadmap\n\n- **v1.0** — object pipeline: staged sculpt, render-vs-reference review loop, action-ready hierarchy. *Shipped.*\n- **v1.1** — detail-first analysis: required detail inventory, strict-quality gate. *Shipped.*\n- **v1.2** — humanoid character generator: anatomy track, proportion-lock and feature-placement passes. *Shipped.*\n- **v1.3** — likeness maximization: projection-first character rendering, per-region confidence. *Planned.*\n- **v1.4** — animation-ready rigs: SkinnedMesh, morph targets, glTF export. *Planned.*\n\nFull detail and later milestones: [ROADMAP.md](ROADMAP.md). Technical specification: [docs\u002FUPGRADE_PLAN.md](docs\u002FUPGRADE_PLAN.md).\n\n---\n\n## Honesty about limits\n\nA 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.\n\n---\n\n## Contributing\n\nContributions 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.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",2,"2026-07-20 02:30:02","CREATED_QUERY"]