image-to-sculpt

图像转雕塑

输入一张图像，输出一座可验证的雕塑：图像展示的每个表面都按照该图像自身相机视角下的法线、轮廓和深度进行拟合；所有隐藏表面都来自彼此一致的生成视图；构建过程的每一步都会在 Blender 中记录并重放。

输入路由

任何输入都会采用相同的案例目录结构（i2s.py new CASE --input ...）。详情：references/inputs.md。

输入	操作	说明
人物／生物／物体渲染图或 AI 图像	new → run	主要流程
真实物体的照片（小雕像、玩具、产品、雕像）	new --kind photo → run	MoGe 可提供真实焦距和深度
带透明背景的抠图 PNG	new → run	Alpha 通道即为蒙版；无需调用蒙版工具
含有多个物体的复杂图像	prep --select "the red dragon"	SAM-3 会选取主体
绘画、草图或扁平插画	prep --restyle	nano banana 会先将其转换为 3D 渲染图，同时保留姿势
同一物体的多张照片	views --import DIR	用你的照片替换生成的视图；通过配准确定角度
只有一个创意	imagine OUT.png "idea" → new	先生成一张干净的全身渲染图
没有 API 密钥	一张抠图 PNG（以及你自己的视图）	仅正面视图也可用：轮廓会被膨胀，背后的深度则是猜测值

工作流

在每个检查点保存一张带标签的可视化图（checks/sheet_*.png、视图表、转台帧）：先看图，再看数字。修复轮次会增加步骤；已记录的内容绝不修改。

1. 搭建。 i2s.py new CASE --input IMG --subject "short noun phrase"。查看图像并自行撰写主体短语（“矮壮的卡通巨魔”“陶瓷猫头鹰摆件”）：它会用于每条视图提示词。输入图像会连同其 sha256 一并复制，并补边至最接近的生成器宽高比，因此所有视图共用同一镜头。
2. 正面映射。 i2s.py prep CASE（蒙版、MoGe-3 深度 + 焦距、Marigold 法线；单位按主体归一化）。继续之前，检查 ref/front_mask.png 和 ref/front_normals.png。主体选错了 → --select。图像是绘画 → --restyle。
3. 视图。 i2s.py views CASE（9 个视图 + 1 个留出视图，预计约 $2；使用 --set minimal 可生成 5 个）。查看每张生成图像：姿势变化、多出肢体或主体被裁切，都是糟糕的视图。配准会拒绝不一致的视图（与其他视图的包围壳 IoU < 0.80），但仍要说明你看到了什么。没有视图能看到的区域，需要从能观察到这些区域的角度添加视图（--angles "-30:25"），而不是进行更多平滑处理（references/views.md）。
4. 包围壳。 i2s.py hull CASE：配准每个视图（请求的角度只是先验：会识别左右互换，但保留前后方向）、重新居中、筛选、记录雕刻、检测对称性。查看 case.json 中已配准的角度；i2s.py symmetry CASE on|off 可覆盖检测到的镜像平面。
5. 拟合。 i2s.py fit CASE --stage all（形体 → 表面 → 细节，共记录 38 轮），然后运行 cut（按照片所示，切开手指、腿、手臂与身体之间的缝隙）、smooth（去除连接网和斑点）、fit --stage polish。i2s.py run CASE 会按顺序执行第 2–8 步，并使用此默认计划（references/fitting.md）。
6. 检查并迭代。 i2s.py check CASE 会为每个视图生成一张图表：参考图、参考法线、雕塑、法线误差、轮廓差异。查找凸块、连接网、缺失的缝隙、扁平化特征。针对问题处理：parts CASE --prompt "hands"，然后运行 fit --stage focus --region hands、cut --region hands、smooth --region box:...（references/checking.md）。没有前后对比图表，绝不要声称问题已修复。
7. 完成、Blender、影片。 finish（面片平滑、OBJ/STL），blender（从照片相机视角重放每一步、360° 转台、每个视图、sculpt.blend、GLB），film（双面板延时影片，结尾为 360° 旋转、转台、视图表、主图）（references/blender-and-delivery.md）。
8. 报告并停止。 report 会生成 out/REPORT.md、out/index.html 和逐步图表。展示延时影片、视图表和测量表，说明哪些部分效果不佳，然后停止。接下来做什么由用户决定。

硬性规则

• 照片决定它能看到什么。 生成视图只填补照片看不到的部分；绝不使用它们的深度（不同视图之间会相差几厘米）。绝不要将生成视图的法线与照片的法线取平均。
• 为每个视图配准；绝不相信请求的角度。 在巨魔模型上，生成视图的角度偏差达 20–155°，大多是左右互换。搜索会允许这些偏差，但会让正面视图保持在前方、背面视图保持在后方（对称主体的背面轮廓看起来就像正面）。查看 case.json 中已配准的角度。
• 先筛选，再雕刻。 与其他视图不一致的视图，属于不同的主体或姿势：拒绝它（并说明原因），不要用它来切削雕塑。
• 留出一个视图。 它绝不会改变表面；拟合前会冻结其相机。请将它与用于拟合的视图分开报告。它也是生成的，因此衡量的是一致性，而非真实情况。
• 测量，不要只靠目测。 IoU、轮廓距离、法线角度、与参考自身粗糙度相比的粗糙度，以及照片的深度。一个数字不能代表“质量”：请并列报告这些指标。
• 距离场必须保持精确。 每次操作都会重新计算网格的距离（窄带内使用精确三角形距离，带外使用 EDT）。偏移不精确的场、镜像场本身或模糊法线目标，都会导致阶梯状伪影、莫尔环和扁平的鼻子；本项目所依据的案例中就出现了这些问题（references/lessons.md）。
• 记录一切。 每次雕刻、遍历、切割和平滑都是 build/steps/ 和 build/log.jsonl 中的一个步骤，并会在 Blender 中重放且显示在延时视频中。绝不要编辑已记录的步骤；应添加新步骤。
• 付费调用： 每次 fal 调用都必须计入案例预算（settings.budget_usd）；请求 ID 必须在等待前保存到 case.json，且绝不盲目重新提交。绝不打印或写入 FAL_KEY。
• 每个检查点都要提供视觉反馈，且每部影片的第 0 帧都必须是完成的缩略图。
• 说明哪些内容是虚构的。 如果主体只从正面可见，那么它的背面就是生成器的猜测。

参考资料

文件	何时阅读
references/inputs.md	处理特殊输入时；包括蒙版、重新风格化、选择、导入照片、仅有创意构想等
references/views.md	生成、评判、配准、筛选和添加视图时
references/fitting.md	了解遍历的作用、阶段、参数、切割 / 平滑 / 聚焦以及默认方案时
references/checking.md	查看地图表和指标、留出的视图，以及确定下一步修复内容时
references/blender-and-delivery.md	使用 Blender 重放、制作影片、导出、编写报告和查看审核页面时
references/conventions.md	编写新工具时了解世界坐标系、相机、单位和文件格式
references/lessons.md	了解首批案例中出现的问题及上述规则的由来

模板：templates/CONTRACT.md（复制到每个案例中）、templates/acceptance.json（目标）。