vinhhien112/Three.js-Object-Sculptor-Codex-Plugin

# Three.js Object 雕塑器 将附件图片中的物体转化为一个通过质量门控的、准备好动画的纯代码 Three.js 程序化模型。 Three.js Object Sculptor 是一个 Codex 插件，用于将用户提供的附件图片中的可见物体重建为纯代码的 Three.js 模型。它不会尝试进行摄影测量、下载美术资源包，或从单张图片中提取完美的网格。相反，它会引导 Codex 完成一项雕刻工作流：验证图片，精确描述物体，将其分解为几何体和材质系统，从搭建基础形状到细化细节，连接对动画友好的层级结构，然后将浏览器渲染结果与原始参考图进行比较。 ## 演示 ### 塔楼船 [打开塔楼船在线演示](https://3dship.harrysoftware.com)  这项塔楼船研究展示了预期的输出形态：一个在浏览器中渲染、由代码雕刻而成的 Three.js 物体，它基于附件参考图重建，具备程序化几何体、铰接部件、材质处理和交互控制。 ### 古秋树 [打开古秋树在线演示](https://tree.harrysoftware.com/)  这项植物学研究重建了一棵复杂的古树，包含程序化曲线、确定性分支、分层树皮材质、密集的秋叶以及准备好动画的层级结构。 ## 概览 - **名称：** Three.js Object Sculptor - **类别：** 用于图像到程序化 3D 工作流的 Codex 插件 - **输入：** 附件物体图片、参考截图或本地图片路径 - **输出：** 纯代码的程序化 Three.js 物体工厂，由 `ObjectSculptSpec` 提供支持 - **主要目标：** 在适合浏览器的 Three.js 代码中重建目标物体的轮廓、组件结构、材质、光照响应以及准备好执行操作的层级结构 - **最适用于：** 准备好动画的实时道具、游戏物体、场景装饰、可破坏物体、产品级物体、植物物体、机械部件和风格化参考重建 - **不适用于：** 摄影测量、精确网格提取、扫描资源、下载的美术包，或仅凭单张图片生成保证完美的生产级几何体 ## 功能简介 - 验证图像是否适合进行程序化 3D 重建。 - 在生成代码之前创建规范的复杂度预评估。 - 编写包含组件层级、材质、光照、轴心点(pivot)、插槽(socket)、动画锚点、破坏锚点和质量目标的 `ObjectSculptSpec`。 - 实施分阶段构建流程：基础搭建、结构构建、形状优化、材质处理、表面处理、光照处理、交互处理和优化。 - 从当前解锁的雕刻阶段生成纯代码的 Three.js 工厂骨架。 - 将生成的物体设计为准备好执行操作的层级结构，以便后续的动画、变换、物理或破坏请求有真实的轴心点和附加点可供使用。 - 将参考图/渲染截图打包到一张对比表中，供 AI 视觉审查。 - 记录自我纠正审查，包含整体、图层和关键特征得分。 - 支持源自参考图的程序化 PBR 证据：反照率、粗糙度估计、高度、法线和 AO 贴图。 ## 使用场景 - 将附件物体图片转换为完全使用 TypeScript 和几何体代码生成的程序化 Three.js 模型。 - 构建具有明确轴心点、插槽、父子层级和变换锚点的、准备好动画的 Three.js 道具。 - 将参考物体重新创建为适合浏览器的程序化资源，无需依赖下载的网格或外部美术资源包。 - 在实现之前生成结构化的物体规范，让 Codex 了解几何体、材质、光照、局部表面特征和交互准备情况。 - 通过在编写模型代码之前规划可拆卸部件、断裂缝隙、碰撞体和特效发射器，创建可破坏或可变形的物体。 - 使用 AI 视觉将渲染模型与原始附件进行比较，并在关键特征不匹配时阻止进度。 - 为 Three.js 游戏、WebGPU 演示、交互式原型和视觉实验生成可重用的程序化物体工厂。 ## 为什么要开发这个插件 程序化 3D 生成可能会以一种非常具体的方式失败：轮廓“看起来差不多对”，但物体失去了使其具有辨识度的细节。该插件旨在让 Codex 在正确的时机放慢速度： - 首先了解正在处理的物体类别和复杂度级别。 - 定义对于这个特定物体来说什么是“足够好”。 - 从粗糙的结构逐步构建到精细的表面响应。 - 如果定义身份的特征错误，则判定该阶段构建失败，即使整体得分看起来可以接受。 其结果不再是那种“一次性生成的网格”，而更像是“Codex 作为一个带有检查点的程序化雕刻师”：搭建基础形状，正确连接活动部件，叠加材质，然后不断细化，直到模型看起来像附件中的物体。 ## 环境要求 - 支持本地插件的 Codex。 - Python 3.10 或更高版本。 - 当你想要实现生成的工厂时，需要一个使用 Three.js 的浏览器项目。 - 对于视觉验收：一张来自渲染模型的截图以及一个 AI 视觉审查器。 辅助脚本使用 Python 标准库模块，并在可用时调用 Shell 图像工具。它们不需要 Playwright 或下载的 Chromium 包。 ## 在 Codex 中安装 将插件源码克隆到你的本地插件文件夹中。将 `REPOSITORY_URL` 替换为你本地的该仓库副本的 Git URL： ``` mkdir -p ~/plugins git clone REPOSITORY_URL ~/plugins/threejs-object-sculptor ``` 确保你的本地 Codex 市场包含该插件的条目。如果你已经有 `~/.agents/plugins/marketplace.json`，请将此对象添加到其 `plugins` 数组中： ``` { "name": "threejs-object-sculptor", "source": { "source": "local", "path": "./plugins/threejs-object-sculptor" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Productivity" } ``` 如果你还没有本地市场文件，请使用以下内容创建 `~/.agents/plugins/marketplace.json`： ``` { "name": "local", "interface": { "displayName": "Local Plugins" }, "plugins": [ { "name": "threejs-object-sculptor", "source": { "source": "local", "path": "./plugins/threejs-object-sculptor" }, "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" }, "category": "Productivity" } ] } ``` 在 Codex 中安装它： ``` codex plugin add threejs-object-sculptor@local ``` 安装后启动一个新的 Codex 线程，以便加载插件技能。 ## 快速开始 在 Codex 中，附加一张物体图片并询问： ``` Use Three.js Object Sculptor to turn the object in this attachment into a procedural Three.js model built entirely with code. ```  为获得最佳效果，请包含预期用途： ``` Make it a real-time browser prop, action-ready for animation, transformation, physics, and destruction. ``` 该插件将引导 Codex 完成： 1. 图像适用性检查。 2. 预规范复杂度和质量契约。 3. 详细的物体雕刻规范。 4. 严格验证。 5. 逐阶段的 Three.js 工厂生成。 6. 浏览器截图审查。 7. AI 视觉对比和自我纠正。 ## 推荐工作流 从插件根目录使用这些脚本。 探查参考图像： ``` python3 scripts/probe_reference_image.py ./reference/oak-tree.png ``` 创建预规范评估： ``` python3 scripts/new_pre_spec_assessment.py "Ancient Autumn Oak" \ --image ./reference/oak-tree.png \ --complexity complex \ --out assessment.json ``` 创建初始雕刻规范： ``` python3 scripts/new_sculpt_spec.py "Ancient Autumn Oak" \ --image ./reference/oak-tree.png \ --assessment assessment.json \ --out object-sculpt-spec.json ``` 验证规范： ``` python3 scripts/validate_sculpt_spec.py object-sculpt-spec.json --strict-quality ``` 检查解锁了哪个雕刻阶段： ``` python3 scripts/sculpt_pass_orchestrator.py status object-sculpt-spec.json ``` 生成当前阶段： ``` python3 scripts/generate_threejs_factory.py object-sculpt-spec.json \ --out src/createObjectModel.ts ``` 渲染模型后创建对比表： ``` python3 scripts/make_visual_comparison_sheet.py \ --reference ./reference/oak-tree.png \ --render ./screenshots/oak-render.png \ --out ./screenshots/oak-comparison.png \ --json ``` 记录 AI 视觉审查： ``` python3 scripts/append_sculpt_review.py object-sculpt-spec.json \ --pass-id blockout \ --fidelity 0.82 \ --action continue \ --summary "Blockout silhouette and primary trunk fork are acceptable." \ --render-screenshot ./screenshots/oak-render.png \ --comparison-image ./screenshots/oak-comparison.png \ --ai-vision-score 0.82 \ --feature-reviews-json ./reviews/blockout-features.json \ --ai-vision-notes "Main proportions pass; canopy microstructure remains deferred." \ --in-place ``` 同步阶段状态： ``` python3 scripts/sculpt_pass_orchestrator.py sync object-sculpt-spec.json --in-place ``` ## PBR 提取 该插件可以从图像像素中提取源自参考图的程序化 PBR 证据： ``` python3 scripts/extract_reference_pbr.py ./reference/oak-bark.png \ --out-dir ./generated/pbr/oak-bark \ --material-id bark \ --target-threshold 0.7 \ --report ./generated/pbr/oak-bark/report.json ``` 这会产生有用的材质证据，例如调色板、反照率、粗糙度估计、高度、法线和 AO 贴图。这并不是从单张图像进行的精确逆向渲染。当置信度低于阈值时，除非明确使用 `--allow-low-confidence`，否则脚本将拒绝修补规范。 ## 质量门控 该插件使用两个级别的视觉验收： - 整体匹配：轮廓、比例、相机/视图、材质读取和光照。 - 语义特征匹配：从同一张完整的参考图/渲染对比图像中对选定的关键物体特征进行评分。 关键特征目标的示例： - 船体形状、舱室结构、帆索具和栏杆（对于船只）。 - 树干分叉、主要树枝插槽、树冠质量、树皮材质和根部flare（对于树木）。 - 车身外壳、车轮、挡风玻璃、格栅和前大灯组（对于车辆）。 如果关键特征未达到其阈值，即使全局得分很高，该阶段也会失败。 ## 常见问题 ### 这是摄影测量吗？ 不。Three.js Object Sculptor 不会从像素中重建扫描的网格。它帮助 Codex 推断程序化模型方案，并生成近似可见物体的 Three.js 代码。 ### 它会生成 GLB 文件吗？ 默认情况下不会。主要输出是纯代码的 Three.js 工厂和 `ObjectSculptSpec`。如果以后需要 GLB 输出，可以在目标 Three.js 项目中添加导出工具。 ### 生成的模型可以制作动画吗？ 可以。动画准备是其核心目标。规范要求在相关位置提供轴心点、插槽、父子层级、变换通道、碰撞代理以及可拆卸或可破坏的组件角色。 ### 它会使用下载的资产或美术包吗？ 不。该工作流围绕生成的几何体、程序化材质、本地图像证据和原生代码的 Three.js 构建而设计。 ### 一张图片能创建出精确的生产级模型吗？ 不能。一张图片可能足以进行有用的程序化重建，但隐藏面、精确尺寸和精细的材质表现可能需要假设、额外的参考视图或较低的保真度目标。 ### 插件如何决定模型是否足够好？ 它使用质量契约、分阶段构建、浏览器截图、一张参考图/渲染对比表以及 AI 视觉审查。即使全局视觉得分看起来可以接受，关键特征的不达标仍可能导致该阶段失败。 ## 项目布局 ``` .codex-plugin/plugin.json skills/object-to-threejs-procedural/SKILL.md skills/object-to-threejs-procedural/references/ scripts/ ``` 重要脚本： - `probe_reference_image.py`：技术图像元数据探查。 - `new_pre_spec_assessment.py`：复杂度和质量契约骨架。 - `new_sculpt_spec.py`：初始 `ObjectSculptSpec`。 - `validate_sculpt_spec.py`：结构化和严格的质量验证。 - `sculpt_pass_orchestrator.py`：阶段锁定和流水线同步。 - `generate_threejs_factory.py`：当前阶段的 Three.js 工厂生成器。 - `make_visual_comparison_sheet.py`：完整的参考图/渲染对比图像。 - `append_sculpt_review.py`：自我纠正审查记录器。 - `extract_reference_pbr.py`：源自参考图的 PBR 证据提取。 ## 局限性 - 单张图像无法显示隐藏面或保证精确的几何体。 - 透明玻璃、烟雾、液体、皮毛、细密布料和精确的相似性任务可能需要额外的参考或较低的保真度目标。 - 生成的工厂是程序化构建的起点，不能直接替代最终的生产资产流水线。 - 验收时需要进行 AI 视觉审查；脚本会打包证据，但不会自行神奇地判断视觉质量。 ## 开发说明 更改插件后，请更新缓存清除器并重新安装。如果你安装了 Codex 的 `plugin-creator` 技能，请使用它的 `update_plugin_cachebuster.py` 辅助工具： ``` python3 /path/to/plugin-creator/scripts/update_plugin_cachebuster.py ~/plugins/threejs-object-sculptor codex plugin add threejs-object-sculptor@local ``` 然后打开一个新的 Codex 线程以加载更新后的技能和脚本。 ## 许可证 MIT

标签：Codex插件, Three.js, Web3D, 图像转3D, 程序化建模, 逆向工具