AnyImage/docs/internals/operators/cutout-tool.md

Cutout Tool

Cutout 从图片上的一个 Selection 开始，可按需生成 Depth 或 Normal Map，最后在 Blender 中创建带材质与 Modifier 的 Mesh Object。

执行过程

flowchart TD
    Select["圈定 SelectionPath"]
    Menu["打开 Shape Pie Menu"]
    Shape["选择 Shape"]
    Raster["SelectionPath → 几何 SelectionMask"]
    Route{"需要后台生成数据？"}
    Local["读取局部 RGBA<br/>源 Alpha × Selection 值"]
    Bounds["写出几何 bounds 矩形 RGBA"]
    Job["生成 Depth / Normal 产物"]
    Encoded["加载并 Pack 输入 RGBA"]
    Ready["贴图 Alpha × Selection Mask"]
    Build["构建 BaseShape"]
    Create["创建 Blender 对象"]

    Select --> Menu --> Shape --> Raster --> Route
    Route -- "否" --> Local --> Ready
    Route -- "是" --> Bounds --> Job --> Encoded --> Ready
    Ready --> Build --> Create

Surface 与 Balloon 在本地组合源 Alpha 与几何 Selection 后构建 BaseShape；Depth Shape 和 Normal Map 先通过同一个矩形图片协议生成所需产物。

节点说明

圈定 Selection，选择 Shape

Cutout 工具由 __init__.py 注册，交互从 main.py 中的 SelectCutoutSelection 开始。它接收 Lasso 或双击整图手势，只构建内存中的 SelectionPath，然后调用 interaction.py 打开 Shape 饼菜单。此时不读取源图像素、不栅格化 Mask，也不扫描可见 Alpha。

对象命中由 Blender 原生点选决定。普通点击另一对象时只切换 active；空白单击保留当前 active Image Empty。Lasso 可从透明区域或 Viewport 空白开始拖动，双击也可从空命中位置打开整图 Shape 菜单。起始点不判断图片范围或 Alpha，完整 Selection 的几何与内容有效性在后续栅格化和 Shape 构建阶段判断。

interaction.py 读取工具选项，并在构建菜单按钮时把只含 Points 的完整 SelectionPath 编码一次，同时把当前 Inward Axis 固定到各 CutoutSelectionToShape。这次编码只用于跨 Blender Operator 传值，不属于 Selection Mask 构建。Mesh Detail 的 Low、Medium、High、Ultra 分别携带 32、16、8、4 px 的源图采样间距；档位越高，采样越密。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 shape.py。

栅格化 Selection

用户选定 Shape 后，main.py 中的 CutoutSelectionToShape 接过主线。它从自身 Property 恢复 SelectionPath，再使用 common/selection.py 以 non-zero winding 在 Path Bounds 与 2 px 抗锯齿边缘内栅格化为一次纯几何 SelectionMask。values 保存局部几何权重，bounds 保存它在源图中的位置；栅格阶段不读取、接收或合并源 Alpha。

实际 Cutout 业务随后读取一次源 RGBA。无需 AI 时，它在几何 bounds 内显式计算 source_alpha × selection_values，由该内容 Mask 判断空内容并约束轮廓；原始 SelectionMask 不被修改。此时按 Selection bounds 长边 ÷ Mesh Detail 像素间距 计算实际采样长边；只有它超过 Maximum Cutout Mesh Resolution 时才等比增大有效间距。bounds 的原始像素长边本身不会触发降密。

需要后台生成数据？

选择 Depth Balloon、Depth Surface 或开启 Normal Map 时需要提交 Job。

Surface 和 Balloon 的本地路径直接使用本地内容 Mask。

生成 Depth / Normal 产物

main.py 先通过 common/image.py 把 Selection 几何 bounds 内的原始 RGBA 写成矩形输入。该文件保留源 Alpha，不预乘 Lasso 值；文件、Packed 或内存图片都使用同一个入口。随后把请求提交给 server/jobs/cutout.py，生成本次 Shape 需要的产物：

• 需要 Vector Depth 时写出相机空间 XYZ 组成的 vector-depth.exr，需要 Z Depth 时写出 z-depth.exr，两者都配套 depth.json；
• Normal Map 根据既定空间写出 tangent-normal.png 或 object-normal.png。

Depth 与 Normal Map 共享同一个 MoGe-2 GeometryFrame。模型输入先按 Alpha 合成到黑底；Vector/Z Depth 的 RGB 保留完整连续 Field，Alpha 保存模型 Validity。Depth Surface 的 Normal Map 编码为 Cutout 原生 XY / Z 对象空间，正面中性法线为局部 +Z；其余 Shape 使用 Tangent Space。main.normal_mode_for_shape() 根据 Shape 确定 Normal Space。

Maximum AI Input Size 约束 MoGe-2 的分析图长边；网格密度使用 Maximum Cutout Mesh Resolution，最终颜色图使用 Selection bounds 分辨率。

Color 使用 Selection bounds 内的源 RGBA；Normal 的可见区域、MoGe-2 黑底输入和 Depth Metadata 的参考区域使用源 Alpha。Depth EXR 的 RGB 保存连续 Field，Alpha 保存模型 Validity。Selection Mask 只在 Blender 构建网格时与贴图 Alpha 相乘。

构建 BaseShape

Job 完成后，main.py 在 Blender 主线程加载并 Pack 可选的 Depth 与 Normal 图片，并复用提交前的矩形 RGBA 输入作为颜色图。它从同一 Image 读取 Alpha，与已栅格化的 Selection Mask 相乘后构建网格内容 Mask；颜色及 AI 贴图保持原 Alpha。main.create_cutout_shape() 调用 geometry.py 中的 build_base_shape()：

1. 从内容 Alpha 值提取外轮廓和孔洞；
2. 按 Mesh Detail 对应的采样间距生成轮廓与内部采样点；
3. 进行约束三角化；
4. 计算四种 Shape 共用的 o_balloon；
5. 汇总顶点、三角面、UV 和 Balloon 权重，得到内存中的 BaseShape。

geometry.py 还提供 Depth 标定、采样和网格尺度计算，供后面的对象创建阶段使用。

创建 Blender 对象

main.create_cutout_shape() 把 BaseShape、颜色 Image 和可选产物交给 object.py 的 create_shape_object()。这里创建 Material、Mesh Object，并挂上统一的 O Image Cutout Modifier。材质通过 common/material.py 创建，Cutout 使用 1.2 的 IOR，并由 O Image Layer Color 直接驱动 Principled BSDF 的 IOR Level。本地 Cutout 创建一次几何 bounds 颜色图；AI Cutout 直接复用已编码并 Pack 的矩形输入。

Shape	Modifier 如何形成结果	必需后台产物
Surface	保持基础平面轮廓，可增加真实厚度	无
Balloon	使用 o_balloon 从边缘向内部鼓起	无
Depth Balloon	在 Balloon 上叠加相对基准面的深度	z-depth.exr、depth.json
Depth Surface	使用相机点 XYZ 重建透视表面	vector-depth.exr、depth.json

Depth Shape 的 Reference Depth，以及 Depth Balloon 的 Direction，都由 object.py 调用 geometry.py 的标定函数，根据最终网格内容 Mask 计算。透明像素达到 5% 时使用有效内容区域自适应标定，否则使用稳定的固定基准。

Normal Map 关闭时材质使用几何法线；开启时，object.py 把生成的图片和已经确定的 Normal Space 交给材质节点。最后 main.py 提交 Undo，整条 Cutout 流程结束。

Inward Axis

flowchart TD
    Base["BaseShape 与四种 Shape<br/>原生 XY / Z"] --> Switch{"Inward Axis"}
    Switch -- "-Z（默认）" --> Native["节点几何直接输出<br/>对象沿用源 Empty local transform"]
    Switch -- "+X" --> Orient["O Image Cutout 执行 Z → X<br/>对象矩阵执行 X → Z"]
    Native --> World["相同世界空间结果"]
    Orient --> World
    Normal["Depth Surface<br/>Object Space Normal"] --> Mode{"Inward Axis"}
    Mode -- "-Z" --> Keep["保持原生 Z 轴通道"]
    Mode -- "+X" --> Swizzle["按 Z → X 转换一次"]

BaseShape 与 Shape 子节点始终在局部 XY 平面建模，并沿 -Z 向图片内部生成厚度和深度。统一的 O Image Cutout Modifier 只在选择 +X 时转换最终几何；object.py 同步使用逆矩阵，因此默认 -Z 与源 Image Empty 的 local transform 一致，+X 模式仍保持相同世界空间形状。Depth Surface 的 Object Space Normal 默认直接使用原生 Z 轴 Artifact，仅在 +X 模式转换通道；Tangent Space Normal 不变。

Balloon 与 Depth Balloon 的材质会创建 Geometry Attribute 节点，把 o_balloon 的 Float 输出直接连接到 O Image Layer 已有的 Normal Scale；Surface 与 Depth Surface 不建立这条连接。