gokayfem/image-to-sculpt

项目介绍

Image 2 Sculpt 是给编程智能体（Claude Code、Codex、Cursor、Copilot、Gemini 等）使用的技能。用户提供一张图片，智能体据此生成一个封闭的水密 3D 雕塑，并用这张图自身的遮罩、深度、法线和相机来拟合，而不是调用黑盒图像转 3D 模型。照片看不到的面由生成的视图补全，但这些视图必须先完成配准和筛选；另有一个视图在拟合前被冻结，不参与塑形，单独报告结果。

构建过程按编号记录在 build/steps/ 中。Blender 会从照片的相机回放每一步，生成 360° 转台和逐视图渲染，并导出 .blend、GLB、OBJ 和 STL；同时产出延时视频和逐视图对照图，匹配质量按视图分别展示，不压成一个总分。

适用输入包括 AI 渲染图、角色或产品图、真实手办和雕像照片、带透明通道的抠图 PNG，以及同一物体的多张照片。场景、发丝级结构、透明或镜面材质明确不在支持范围内。

安装与运行

需要 Python 3.10+（numpy、scipy、scikit-image、Pillow）、Blender 5.2+、ffmpeg，以及用于遮罩、深度、法线和生成视图的 FAL_KEY。执行 pip install -r requirements.txt 可安装完整依赖。先用以下命令检查环境：

python3 skills/image-to-sculpt/scripts/i2s.py doctor

在 Claude Code 中安装：

claude plugin marketplace add gokayfem/image-to-sculpt
claude plugin install image-to-sculpt@image-to-sculpt

其他智能体可通过 skills 安装（npx skills add gokayfem/image-to-sculpt），或手动复制技能目录。不支持技能机制的助手请看 adapters。

在仓库根目录新建并运行一个案例，以 owl.jpg 为例：

python3 skills/image-to-sculpt/scripts/i2s.py new cases/owl --input owl.jpg --subject "carved wooden owl figurine"
python3 skills/image-to-sculpt/scripts/i2s.py run cases/owl

run 会执行创建后的全部阶段。也可以单独调用 prep、views、hull、fit、check、blender 等阶段。产物位于 cases/owl，该目录已被 git 忽略。

限制与成本

生成视图、遮罩、深度和法线等付费调用按案例预算控制，用 --budget 设置；每次请求的 ID 会在等待结果前写入 case.json。README 估计一个典型案例约 2 美元，包括 10 个生成视图及照片自身的各类映射。没有 API key 时，可以用抠图 PNG 加自己导入的视图跑通；只提供正面图也可以，但背面形状只能推断。

输入会被填充（绝不裁剪）到视图生成器支持的宽高比，单位按主体归一化。注册、表面拟合和精确有符号距离场由测试覆盖：

python3 tests/run_tests.py
python3 tests/run_tests.py --slow

快速测试约 1 分钟，慢速测试增加端到端合成管线。CI 在 Linux 上运行这两组测试，不依赖 fal、Blender 或 ffmpeg。

HotRepo 点评

在 HotRepo 2026 年 11 月 9 日的新项目记录中，该项目在从 11 月 8 日开始的统计窗口内新增 105 个 Star 和 4 个 Fork，没有记录到 GitHub 全语言日榜名次。目前只有单次快照，不足以判断趋势。更值得关注的是它以测量为核心的设计：逐视图对照参考图、保留一个不参与拟合的视图、记录可被 Blender 回放的每一步，这些都与一次性图像转 3D 调用不同；合成测试也覆盖了视图配准和表面精度，而不只是检查是否产出模型。