[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93018":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":14,"starSnapshotCount":14,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},93018,"Three.js-Object-Sculptor-Codex-Plugin","vinhhien112\u002FThree.js-Object-Sculptor-Codex-Plugin","vinhhien112","Codex plugin that turns attached object images into code-only, animation-ready procedural Three.js models.",null,"Python",982,114,1,0,28,883,74.18,"MIT License",false,"main",true,[],"2026-07-22 04:02:07","# Three.js Object Sculptor\n\nTurn the object in an attached image into a quality-gated, animation-ready procedural Three.js model built entirely with code.\n\nThree.js Object Sculptor is a Codex plugin for rebuilding the visible object in a user-provided attachment image as a code-only Three.js model. It does not try to do photogrammetry, download an art pack, or extract a perfect mesh from one image. Instead, it guides Codex through a sculpting workflow: validate the image, describe the object precisely, decompose it into geometry and material systems, build from blockout to detail, wire an animation-friendly hierarchy, then compare the browser render against the original reference.\n\n## Demo\n\n### Tower Ship\n\n[Open the live tower ship demo](https:\u002F\u002F3dship.harrysoftware.com)\n\n![Procedural Three.js tower ship demo generated from an attached reference image](assets\u002Ftower-ship-demo.png)\n\nThis tower ship study shows the intended output shape: a browser-rendered, code-sculpted Three.js object rebuilt from an attached reference image, with procedural geometry, articulated parts, material work, and interactive controls.\n\n### Ancient Autumn Tree\n\n[Open the live ancient autumn tree demo](https:\u002F\u002Ftree.harrysoftware.com\u002F)\n\n![Procedural Three.js ancient autumn tree reconstructed from an attached reference image](assets\u002Fancient-autumn-tree-demo.png)\n\nThis botanical study reconstructs a complex ancient tree with procedural curves, deterministic branching, layered bark materials, dense autumn foliage, and an animation-ready hierarchy.\n\n## At A Glance\n\n- **Name:** Three.js Object Sculptor\n- **Category:** Codex plugin for image-to-procedural-3D workflows\n- **Input:** an attached object image, reference screenshot, or local image path\n- **Output:** a code-only procedural Three.js object factory, backed by an `ObjectSculptSpec`\n- **Primary goal:** recreate the target object's silhouette, component structure, materials, lighting response, and action-ready hierarchy in browser-friendly Three.js code\n- **Best for:** animation-ready real-time props, game objects, scene dressing, destructible objects, product-style objects, botanical objects, mechanical parts, and stylized reference reconstructions\n- **Not for:** photogrammetry, exact mesh extraction, scanned assets, downloaded art packs, or guaranteed production-perfect geometry from one image\n\n## What It Does\n\n- Validates whether an image is suitable for procedural 3D reconstruction.\n- Creates a pre-spec complexity assessment before code generation.\n- Writes an `ObjectSculptSpec` with component hierarchy, materials, lighting, pivots, sockets, animation anchors, destruction anchors, and quality targets.\n- Enforces a staged build pipeline: blockout, structural pass, form refinement, material pass, surface pass, lighting pass, interaction pass, and optimization.\n- Generates a code-only Three.js factory skeleton from the current unlocked sculpt pass.\n- Designs the generated object as an action-ready hierarchy, so later animation, transformation, physics, or destruction requests have real pivots and attachment points to use.\n- Packages reference\u002Frender screenshots into one comparison sheet for AI vision review.\n- Records self-correction reviews with overall, layer, and critical feature scores.\n- Supports reference-derived procedural PBR evidence: albedo, roughness estimate, height, normal, and AO maps.\n\n## Use Cases\n\n- Convert an attached object image into a procedural Three.js model generated entirely with TypeScript and geometry code.\n- Build animation-ready Three.js props with meaningful pivots, sockets, parent-child hierarchy, and transform anchors.\n- Recreate reference objects as browser-friendly procedural assets without relying on downloaded meshes or external art packs.\n- Generate a structured object spec before implementation, so Codex understands geometry, materials, lighting, local surface features, and interaction readiness.\n- Create destructible or transformable objects by planning detachable parts, fracture seams, colliders, and effect emitters before the model is coded.\n- Compare the rendered model against the original attachment with AI vision and block progress when critical features do not match.\n- Produce reusable procedural object factories for Three.js games, WebGPU demos, interactive prototypes, and visual experiments.\n\n## Why This Exists\n\nProcedural 3D generation can fail in a very specific way: the silhouette is \"kind of right\", but the object loses the details that make it recognizable. This plugin is designed to slow Codex down at the right moments:\n\n- First understand what object class and complexity tier it is dealing with.\n- Define what \"good enough\" means for this specific object.\n- Build from coarse structure to fine surface response.\n- Fail a pass if an identity-defining feature is wrong, even when the overall score looks acceptable.\n\nThe result is less \"one-shot generated mesh\" and more \"Codex as a procedural sculptor with checkpoints\": block out the form, attach the moving parts correctly, layer the materials, then keep refining until the model reads like the object in the attachment.\n\n## Requirements\n\n- Codex with local plugin support.\n- Python 3.10 or newer.\n- A browser project using Three.js when you want to implement the generated factory.\n- For visual acceptance: a screenshot from the rendered model and an AI vision reviewer.\n\nThe helper scripts use Python standard-library modules and shell image tooling when available. They do not require Playwright or a downloaded Chromium bundle.\n\n## Install For Codex\n\nClone the plugin source into your local plugin folder. Replace `REPOSITORY_URL` with the Git URL for your copy of this repository:\n\n```bash\nmkdir -p ~\u002Fplugins\ngit clone REPOSITORY_URL ~\u002Fplugins\u002Fthreejs-object-sculptor\n```\n\nMake sure your local Codex marketplace has an entry for the plugin. If you already have `~\u002F.agents\u002Fplugins\u002Fmarketplace.json`, add this object to its `plugins` array:\n\n```json\n{\n  \"name\": \"threejs-object-sculptor\",\n  \"source\": {\n    \"source\": \"local\",\n    \"path\": \".\u002Fplugins\u002Fthreejs-object-sculptor\"\n  },\n  \"policy\": {\n    \"installation\": \"AVAILABLE\",\n    \"authentication\": \"ON_INSTALL\"\n  },\n  \"category\": \"Productivity\"\n}\n```\n\nIf you do not have a local marketplace file yet, create `~\u002F.agents\u002Fplugins\u002Fmarketplace.json` with:\n\n```json\n{\n  \"name\": \"local\",\n  \"interface\": {\n    \"displayName\": \"Local Plugins\"\n  },\n  \"plugins\": [\n    {\n      \"name\": \"threejs-object-sculptor\",\n      \"source\": {\n        \"source\": \"local\",\n        \"path\": \".\u002Fplugins\u002Fthreejs-object-sculptor\"\n      },\n      \"policy\": {\n        \"installation\": \"AVAILABLE\",\n        \"authentication\": \"ON_INSTALL\"\n      },\n      \"category\": \"Productivity\"\n    }\n  ]\n}\n```\n\nInstall it in Codex:\n\n```bash\ncodex plugin add threejs-object-sculptor@local\n```\n\nStart a new Codex thread after installation so the plugin skill is loaded.\n\n## Quick Start\n\nIn Codex, attach an object image and ask:\n\n```text\nUse Three.js Object Sculptor to turn the object in this attachment into a procedural Three.js model built entirely with code.\n```\n\n![Codex prompt example using an attached object image with Three.js Object Sculptor and Browser](assets\u002Fcodex-prompt-example.png)\n\nFor best results, include the intended use:\n\n```text\nMake it a real-time browser prop, action-ready for animation, transformation, physics, and destruction.\n```\n\nThe plugin will guide Codex through:\n\n1. Image suitability check.\n2. Pre-spec complexity and quality contract.\n3. Detailed object sculpt spec.\n4. Strict validation.\n5. Pass-by-pass Three.js factory generation.\n6. Browser screenshot review.\n7. AI vision comparison and self-correction.\n\n## Recommended Workflow\n\nUse the scripts from the plugin root.\n\nProbe a reference image:\n\n```bash\npython3 scripts\u002Fprobe_reference_image.py .\u002Freference\u002Foak-tree.png\n```\n\nCreate a pre-spec assessment:\n\n```bash\npython3 scripts\u002Fnew_pre_spec_assessment.py \"Ancient Autumn Oak\" \\\n  --image .\u002Freference\u002Foak-tree.png \\\n  --complexity complex \\\n  --out assessment.json\n```\n\nCreate a starter sculpt spec:\n\n```bash\npython3 scripts\u002Fnew_sculpt_spec.py \"Ancient Autumn Oak\" \\\n  --image .\u002Freference\u002Foak-tree.png \\\n  --assessment assessment.json \\\n  --out object-sculpt-spec.json\n```\n\nValidate the spec:\n\n```bash\npython3 scripts\u002Fvalidate_sculpt_spec.py object-sculpt-spec.json --strict-quality\n```\n\nCheck which sculpt pass is unlocked:\n\n```bash\npython3 scripts\u002Fsculpt_pass_orchestrator.py status object-sculpt-spec.json\n```\n\nGenerate the current pass:\n\n```bash\npython3 scripts\u002Fgenerate_threejs_factory.py object-sculpt-spec.json \\\n  --out src\u002FcreateObjectModel.ts\n```\n\nCreate a comparison sheet after rendering the model:\n\n```bash\npython3 scripts\u002Fmake_visual_comparison_sheet.py \\\n  --reference .\u002Freference\u002Foak-tree.png \\\n  --render .\u002Fscreenshots\u002Foak-render.png \\\n  --out .\u002Fscreenshots\u002Foak-comparison.png \\\n  --json\n```\n\nRecord an AI vision review:\n\n```bash\npython3 scripts\u002Fappend_sculpt_review.py object-sculpt-spec.json \\\n  --pass-id blockout \\\n  --fidelity 0.82 \\\n  --action continue \\\n  --summary \"Blockout silhouette and primary trunk fork are acceptable.\" \\\n  --render-screenshot .\u002Fscreenshots\u002Foak-render.png \\\n  --comparison-image .\u002Fscreenshots\u002Foak-comparison.png \\\n  --ai-vision-score 0.82 \\\n  --feature-reviews-json .\u002Freviews\u002Fblockout-features.json \\\n  --ai-vision-notes \"Main proportions pass; canopy microstructure remains deferred.\" \\\n  --in-place\n```\n\nSync the pass state:\n\n```bash\npython3 scripts\u002Fsculpt_pass_orchestrator.py sync object-sculpt-spec.json --in-place\n```\n\n## PBR Extraction\n\nThe plugin can extract reference-derived procedural PBR evidence from image pixels:\n\n```bash\npython3 scripts\u002Fextract_reference_pbr.py .\u002Freference\u002Foak-bark.png \\\n  --out-dir .\u002Fgenerated\u002Fpbr\u002Foak-bark \\\n  --material-id bark \\\n  --target-threshold 0.7 \\\n  --report .\u002Fgenerated\u002Fpbr\u002Foak-bark\u002Freport.json\n```\n\nThis produces useful material evidence such as palette, albedo, roughness estimate, height, normal, and AO maps. It is not exact inverse rendering from a single image. When confidence is below the threshold, the script refuses to patch the spec unless `--allow-low-confidence` is explicitly used.\n\n## Quality Gates\n\nThe plugin uses two levels of visual acceptance:\n\n- Overall match: silhouette, proportions, camera\u002Fview, material read, and lighting.\n- Semantic feature match: selected critical object features scored from the same full reference\u002Frender comparison image.\n\nExamples of critical feature targets:\n\n- Hull shape, cabin blocks, sail rigging, and rails for a boat.\n- Trunk fork, major branch sockets, canopy mass, bark material, and root flare for a tree.\n- Body shell, wheels, windshield, grille, and headlight clusters for a vehicle.\n\nIf a critical feature fails its threshold, the pass fails even if the global score is high.\n\n## FAQ\n\n### Is this photogrammetry?\n\nNo. Three.js Object Sculptor does not reconstruct a scanned mesh from pixels. It helps Codex infer a procedural model plan and generate Three.js code that approximates the visible object.\n\n### Does it generate a GLB file?\n\nNot by default. The main output is a code-only Three.js factory and an `ObjectSculptSpec`. You can add export tooling in the target Three.js project if you later need GLB output.\n\n### Can the generated model be animated?\n\nYes. Animation readiness is a core goal. The spec asks for pivots, sockets, parent-child hierarchy, transform channels, collider proxies, and detachable or breakable component roles where relevant.\n\n### Does it use downloaded assets or art packs?\n\nNo. The workflow is designed around generated geometry, procedural materials, local image evidence, and code-native Three.js construction.\n\n### Can one image create an exact production model?\n\nNo. One image can be enough for a useful procedural reconstruction, but hidden sides, exact dimensions, and fine material behavior may need assumptions, extra reference views, or a lower-fidelity target.\n\n### How does the plugin decide whether the model is good enough?\n\nIt uses a quality contract, staged build passes, browser screenshots, one reference\u002Frender comparison sheet, and AI vision review. Critical features can fail a pass even when the global visual score looks acceptable.\n\n## Project Layout\n\n```text\n.codex-plugin\u002Fplugin.json\nskills\u002Fobject-to-threejs-procedural\u002FSKILL.md\nskills\u002Fobject-to-threejs-procedural\u002Freferences\u002F\nscripts\u002F\n```\n\nImportant scripts:\n\n- `probe_reference_image.py`: technical image metadata probe.\n- `new_pre_spec_assessment.py`: complexity and quality-contract skeleton.\n- `new_sculpt_spec.py`: starter `ObjectSculptSpec`.\n- `validate_sculpt_spec.py`: structural and strict quality validation.\n- `sculpt_pass_orchestrator.py`: pass locking and pipeline sync.\n- `generate_threejs_factory.py`: current-pass Three.js factory generator.\n- `make_visual_comparison_sheet.py`: full reference\u002Frender comparison image.\n- `append_sculpt_review.py`: self-correction review recorder.\n- `extract_reference_pbr.py`: reference-derived PBR evidence extraction.\n\n## Limitations\n\n- A single image cannot reveal hidden sides or guarantee exact geometry.\n- Transparent glass, smoke, liquid, fur, fine cloth, and exact likeness tasks may require extra references or a lower-fidelity target.\n- The generated factory is a starting point for procedural construction, not a finished asset pipeline replacement.\n- AI vision review is expected for acceptance; the scripts package evidence but do not magically judge visual quality by themselves.\n\n## Development Notes\n\nAfter changing the plugin, update the cachebuster and reinstall. If you have Codex's `plugin-creator` skill installed, use its `update_plugin_cachebuster.py` helper:\n\n```bash\npython3 \u002Fpath\u002Fto\u002Fplugin-creator\u002Fscripts\u002Fupdate_plugin_cachebuster.py ~\u002Fplugins\u002Fthreejs-object-sculptor\ncodex plugin add threejs-object-sculptor@local\n```\n\nThen open a new Codex thread to pick up the updated skill and scripts.\n\n## Support This Project\n\nIf Three.js Object Sculptor helps you, you can support its continued development:\n\n\u003Ca href=\"https:\u002F\u002Fko-fi.com\u002Fharrynguyen112\">\n  \u003Cimg height=\"36\" src=\"https:\u002F\u002Fstorage.ko-fi.com\u002Fcdn\u002Fkofi6.png?v=6\" alt=\"Buy Me a Coffee on Ko-fi\">\n\u003C\u002Fa>\n\n## License\n\nMIT\n","这是一个Codex插件，将用户提供的物体图像自动转化为纯代码实现、支持动画的程序化Three.js 3D模型。它不依赖摄影测量或网格提取，而是通过结构化提示工程引导AI分阶段完成图像理解、几何分解、材质建模、层级构建与质量验证，输出可直接在浏览器中渲染和交互的Three.js工厂函数。核心特点包括基于ObjectSculptSpec规范的可复现流程、动画就绪的层级设计、多阶段质量门控及面向实时渲染的优化。适用于游戏道具、场景装饰、产品展示、植物建模、机械部件等需快速生成可编程、可动画3D资产的开发场景。",2,"2026-07-11 02:30:40","CREATED_QUERY"]