feat(cutout_tool): Implement cutout region to shape functionality

- Added interaction helpers for cutout region validation and shape menu interaction.
- Created main operator for converting image regions into cutout shapes, including AI artifact generation.
- Introduced object creation logic for cutout shapes, handling depth and normal textures.
- Defined cutout shape identifiers and node groups for various shape types.
- Implemented depth texture writing and prediction artifact generation for MoGe-2.
- Developed server jobs for generating cutout artifacts, depth planes, and refining image regions.
- Added region refinement logic to enhance gesture masks using BEN2.

docs/guides/cutout.md

@@ -21,36 +21,38 @@ Cutout 用套索从一张 Image Empty 中选择区域，再生成 Surface、Ball
 
 四种结果都保留源 Image Empty，并在同一位置创建新网格。它们共享选区轮廓、UV、材质和基础三角网格，因此可以从同一张图多次生成不同 Shape 进行比较。
 
-无论是否启用 Refine Selection，套索超出图片的部分都不会生成网格，源图中 `Alpha <= 0.1` 的像素也始终从 Region 中排除。双击使用完整画面时同样只为 `Alpha > 0.1` 的 Region 生成网格。
+无论是否启用 Fit to Foreground，套索超出图片的部分都不会生成网格，源图中 `Alpha <= 0.1` 的像素也始终从 Region 中排除。双击使用完整画面时同样只为 `Alpha > 0.1` 的 Region 生成网格。
 
 ## 工具设置
 
-- **Point Spacing**：相邻网格点大约对应多少源图像素。数值越小，网格越密，轮廓和变形细节越多。
-- **Normal**：使用 MoGe-2 生成法线贴图。默认关闭。
-- **Refine Selection**：用 BEN2 把几何套索收紧到其中的前景内容。默认关闭。
+选项按执行意图排列：
 
-Surface 与 Balloon 在 Normal、Refine 都关闭时完全在 Blender 中生成，不需要 AI Environment。开启任一 AI 选项，或选择 Depth Shape 时，会提交后台任务。
+- **Fit to Foreground**：用 BEN2 把几何套索贴合到其中的前景主体，默认关闭。
+- **Mesh Sampling Spacing**：相邻网格采样点大约对应多少源图像素；数值越小，三角网格越密。
+- **Generate Normal Map**：是否使用 MoGe-2 生成法线贴图，默认关闭；空间由 Shape 自动决定。
 
-Point Spacing 先按完整源图换算基础密度；选区裁切后的长边若超过全局 **Maximum AI Input Size**，网格密度会按分析图的等比缩放比例降低。颜色贴图始终保留原裁切分辨率，不会使用限制后的临时分析图。建议先用默认 `32` 观察形状；轮廓需要更细时再逐步减小。
+Surface 与 Balloon 在 **Generate Normal Map**、**Fit to Foreground** 都关闭时完全在 Blender 中生成，不需要 AI Environment。开启任一 AI 选项，或选择 Depth Shape 时，会提交后台任务。
+
+Mesh Sampling Spacing 先按完整源图换算期望密度，再由 Cutout 区的 **Maximum Cutout Mesh Resolution** 限制裁切区域的最长采样边。这个网格上限对 Surface、Balloon 与 Depth Shape 完全相同。**Maximum AI Input Size** 只限制 Fit to Foreground、Depth 和 Normal Map 的模型分析图；颜色贴图始终保留原裁切分辨率。建议先用默认 `32` 观察形状，轮廓需要更细时再逐步减小。
 
 ## 调整修改器
 
 四个 Shape 都使用同一个 `O Image Cutout` Geometry Nodes 修改器。创建时 Shape 菜单已经设为饼菜单所选类型；切换 Shape 后，Blender 只显示该类型实际使用的输入。常用参数包括：
 
 - **Thickness**：Surface / Depth Surface 使用场景距离；Balloon / Depth Balloon 使用鼓起高度倍率。
-- **Cleanup**：碎岛面积阈值；创建时根据 Point Spacing 和图片平面尺寸自动写入。为便于在修改器中调节，显示值放大了 `100` 倍，节点内部会还原为实际面积，因此这次显示缩放不会改变默认清理效果。
+- **Cleanup**：碎岛面积阈值；创建时根据 Mesh Sampling Spacing 和图片平面尺寸自动写入。为便于在修改器中调节，显示值放大了 `100` 倍，节点内部会还原为实际面积，因此这次显示缩放不会改变默认清理效果。
 - **Smooth Iterations**：位于外层，控制平滑次数，默认 `0`；**Smooth** 位于 Options 中，控制每次平滑的混合强度。四种 Shape 都可使用。
 - **Depth Scale**：Depth Shape 的深度强度；`0` 回到基础平面或 Balloon。
 
-两个 Depth Shape 共用 **Base Plane Depth**；Depth Balloon 还提供 **Depth Direction**。生成前会检查最终 Region 输入的 Alpha：`Alpha < 0.1` 的像素达到 `5%` 时，根据有效 Region 自适应 Base Plane Depth，并为 Depth Balloon 拟合 Direction；不足 `5%` 时使用稳定的固定基准。这个判断不依赖双击全图或 Refine Selection。插件自动写入的 Depth Image 与 Uniform Scale 位于折叠的 Data 面板，一般无需手动修改。
+两个 Depth Shape 共用 **Base Plane Depth**；Depth Balloon 还提供 **Depth Direction**。生成前会检查最终 Region 输入的 Alpha：`Alpha < 0.1` 的像素达到 `5%` 时，根据有效 Region 自适应 Base Plane Depth，并为 Depth Balloon 拟合 Direction；不足 `5%` 时使用稳定的固定基准。这个判断不依赖双击全图或 Fit to Foreground。插件自动写入的 Depth Image 与 Uniform Scale 位于折叠的 Data 面板，一般无需手动修改。
 
 Balloon 的轮廓高度算法由扩展 Preferences 中的 **Balloon Profile** 控制：Poisson 更平滑，Teddy 更强调轮廓骨架。修改默认值只影响之后创建的 Shape。
 
-## Refine 与 Normal
+## Fit to Foreground 与 Normal Map
 
-Refine Selection 只在“套索与源图可见 Alpha 的交集”内收紧最终 Region，不把 AI 生成的颜色写回原图。材质继续使用当前 Image Empty 的源颜色和原 Alpha。
+Fit to Foreground 只在“套索与源图可见 Alpha 的交集”内收紧最终 Region，不把 AI 生成的颜色写回原图。材质使用按最终 Region 包围矩形裁切的当前 Image Empty 源图，保留源颜色和原 Alpha，不把 RegionMask 写入 Alpha。
 
-Normal 设为 **None** 时使用几何法线；**Tangent** 把 MoGe-2 结果作为基于完整图片平面的浮雕细节，**Object** 则直接编码到 Cutout 对象局部轴。两种模式都不根据 Geometry Nodes 的成品网格再次烘焙。Normal 保持模型分析分辨率，Color Image 仍保留原始裁切分辨率；Depth 与 Normal 同时需要时共享同一次 Prediction，不会重复运行模型。
+Normal Map 关闭时使用几何法线。开启后，Depth Surface 自动使用 Object Space，把模型法线编码到 Cutout 对象局部轴；Surface、Balloon 与 Depth Balloon 自动使用 Tangent Space，作为相对图片平面的浮雕细节。用户不直接选择 Normal Space，两种路径都不根据 Geometry Nodes 的成品网格再次烘焙。Normal Map 保持模型分析分辨率，Color Image 仍保留原始裁切分辨率；Depth 与 Normal Map 同时需要时共享同一次 Prediction，不会重复运行模型。
 
 ## 当前范围
 

docs/guides/depth-plane.md

@@ -16,12 +16,6 @@ Depth Plane 将一张静态图片转换为带深度位移的网格，适合快
 
 默认推荐。MoGe-2 估算尺度一致的深度与相机信息，使用 **MoGe Resolution Level** 控制处理精度。第一次使用建议保持 `5`。
 
-### DA3
-
-DA3 提供另一种深度结果，使用 **DA3 Resolution Scale** 按原图长边计算处理尺寸。比例越高，通常会保留更多细节，也会增加耗时和内存占用。
-
-切换模型后，如果对应文件尚未下载，先在同一设置区点击 **Download**。
-
 ## 调整结果
 
 生成对象使用运行时创建的 `O Image Depth Plane` Geometry Nodes 修改器：

docs/guides/faq.md

@@ -39,7 +39,7 @@ Environment 或默认模型缺失不会让四个 AI 功能变灰；点击功能
 
 ## Cutout Depth Surface 边缘破碎或细节太多
 
-先增大 **Point Spacing** 降低基础网格密度，再调整 **Cleanup** 清理小块，并用 **Smooth** 稳定表面。必要时降低模型分辨率。
+先增大 **Mesh Sampling Spacing** 降低基础网格密度，再调整 **Cleanup** 清理小块，并用 **Smooth** 稳定表面。必要时降低模型分辨率。
 
 ## 动画面片不播放
 

docs/guides/image-tools.md

@@ -12,12 +12,12 @@ Image Box、Lasso、Line、Polyline 与 Perspective 直接编辑静态 Image Emp
 | **Image Polyline** | 逐点构建精确多边形 |
 | **Image Perspective** | 将任意顺序输入的四个角矫正为矩形 |
 
-在 3D Viewport 左侧工具栏长按 Image Mask 图标，可以在 Box、Lasso、Line 与 Polyline 之间切换。**Refine Selection** 只显示在 Box / Lasso；Line / Polyline 保持几何直线边界。Perspective 使用独立图标。
+在 3D Viewport 左侧工具栏长按 Image Mask 图标，可以在 Box、Lasso、Line 与 Polyline 之间切换。**Fit to Foreground** 只显示在 Box / Lasso；Line / Polyline 保持几何直线边界。Perspective 使用独立图标。
 
 <div class="screenshot-placeholder" markdown>
 **截图占位：Image 工具组与 Tool Settings**
 
-显示包含四个工具的 Image Mask 组、独立 Perspective，以及 Box / Lasso 的 Refine Selection。
+显示包含四个工具的 Image Mask 组、独立 Perspective，以及 Box / Lasso 的 Fit to Foreground。
 
 目标文件：`images/image-tools/tool-group.png`
 </div>
@@ -48,7 +48,7 @@ Image Box、Lasso、Line、Polyline 与 Perspective 直接编辑静态 Image Emp
 - 关闭：保留选区内；
 - 开启：保留选区外。
 
-Cutout、Box 与 Lasso 分别保存各自的 **Refine Selection** 设置；在一个工具中切换不会改变另外两个工具。启用后，BEN2 会先把几何选区收紧到其中的前景，再应用反选。例如框住一个苹果并开启反选，最终会清理苹果本身、保留其余内容。Line / Polyline 不提供 Refine，以保持直线边界和明确的裁切方向。
+Cutout、Box 与 Lasso 分别保存各自的 **Fit to Foreground** 设置；在一个工具中切换不会改变另外两个工具。启用后，BEN2 会先把几何 Region 收紧到其中的前景，再应用反选。例如框住一个苹果并开启反选，最终会清理苹果本身、保留其余内容。Line / Polyline 不提供 Fit to Foreground，以保持直线边界和明确的裁切方向。
 
 结果会直接更新当前 Empty 的图片，并把画布紧裁切到最终可见 Alpha。只有一个 Image Empty 使用该图片时，工具更新原 Image；两个或更多 Image Empty 共用它时，工具为当前 Empty 创建独立结果，其他 Empty 保持不变。对象 Transform 不变，显示尺寸与 Image Offset 会更新，使剩余像素保持在原图片平面上的位置。透明区只修改 Alpha，保留源 RGB 供纹理过滤使用。未形成有效区域的单击会静默结束；有效选区没有可见像素时只显示警告，不修改图片。
 
@@ -69,7 +69,7 @@ Cutout、Box 与 Lasso 分别保存各自的 **Refine Selection** 设置；在
 
 `Backspace` 返回上一步，右键或 `Esc` 取消。四点会自动排序，点击顺序不会改变输出旋转。
 
-Perspective 只执行图片 Homography 与紧裁切，不做 Refine，也不尝试从当前 View 推导真实相机。结果保持源 Empty 的 Transform，并按原四边形覆盖范围近似更新显示位置与尺寸。选区完全位于图片外或没有可见像素时不会执行。
+Perspective 只执行图片 Homography 与紧裁切，不提供 Fit to Foreground，也不尝试从当前 View 推导真实相机。结果保持源 Empty 的 Transform，并按原四边形覆盖范围近似更新显示位置与尺寸。选区完全位于图片外或没有可见像素时不会执行。
 
 <div class="screenshot-placeholder" markdown>
 **截图占位：Perspective 比例确认**

docs/guides/models-and-storage.md

@@ -9,18 +9,18 @@ AnyImage 把运行环境、模型和任务结果放在 Blender 之外，多个 B
 - **Ready** 表示模型文件已经就绪。
 - **Download** 用于按需下载模型。
 - Depth & Normal 与 Upscale 的下载按钮位于当前模型选择项下方；切换选择后，可直接下载对应模型。
-- Depth Model 先列出三档 MoGe-2，再列出两档 DA3；DA3 不输出 normal，选择后会在设置下方提示。
+- Depth & Normal 只列出三档 MoGe-2；Depth Plane 与 Cutout 共用这个显式选择。
 - Remove Background 使用的 BEN2 固定模型显示在对应功能区；Cutout 区只包含 Balloon Profile。
 - 默认安装会准备 MoGe-2 ViT-S Normal、BEN2 Base 和 Real-ESRGAN General WDN x4v3。
-- DA3、更大的 MoGe-2，以及可选的 SAFMN Real x4、Real-ESRGAN x4plus 需要时再下载即可。
+- 更大的 MoGe-2，以及可选的 SAFMN Real x4、Real-ESRGAN x4plus 需要时再下载即可。
 - 可公开取得的 ONNX 制品使用经过大小与 SHA-256 校验的原址，并以 OmooLab R2 为镜像；不会把源码仓库名称推测成 Hugging Face 下载地址。
 - Real-ESRGAN General WDN x4v3 与 SAFMN Real x4 的上游只发布 PyTorch 权重，当前 ONNX 均从官方权重导出并仅从 R2 下载。
 
 较大的模型不一定适合所有图片。建议先用默认模型完成构图，再针对细节与性能需求比较其他模型。
 
-## 全局 AI 输入尺寸
+## AI 输入与 Cutout 网格尺寸
 
-Environment 区的 **Maximum AI Input Size** 默认 `2048 px`，可在 `256–8192 px` 之间调整。它既是允许执行 Upscale 的当前图片长边上限，也是 Depth 与 Normal 分析输入的最大长边；Upscale 在达到上限时置灰，Depth 与 Normal 则保持宽高比缩小分析输入。颜色贴图仍使用当前图片的原始分辨率。Cutout 在完成套索裁切后再应用上限，因此整张图片很大但选区较小时不会被无谓缩小。
+Environment 区的 **Maximum AI Input Size** 默认 `2048 px`，可在 `256–8192 px` 之间调整。它是 Upscale 的可执行源图长边上限，也是 Depth、Normal Map 与 Fit to Foreground 模型分析输入的最大长边；颜色贴图仍使用原始分辨率。Cutout 区的 **Maximum Cutout Mesh Resolution** 默认 `1024`，独立限制所有 Shape 的网格采样密度，不会因为某个 Shape 是否使用 AI 而改变含义。
 ## Device
 
 扩展偏好设置中的 **Device** 控制 Depth Plane、Cutout 的 AI 增强、Remove Background 和 Upscale 等正式任务。

docs/guides/workflows.md

@@ -6,11 +6,11 @@
 | --- | --- | --- | --- |
 | Clipboard Image | 剪贴板静态图 | Reference、Plane、节点或笔刷纹理 | 不需要 |
 | Convert to Plane | 单图、Movie、Sequence | 带材质的普通网格 | 不需要 |
-| Convert to Depth Plane | 静态图 | 带深度位移的整图面片 | DA3 或 MoGe-2 |
+| Convert to Depth Plane | 静态图 | 带深度位移的整图面片 | MoGe-2 |
 | Cutout | 静态图局部选区 | 四种局部 Shape | 按 Shape 与选项决定 |
 | Remove Background | 单图、Movie、Sequence | 透明图片或序列 | BEN2 |
 | Upscale | 单图、Movie、Sequence | 4× 图片或序列 | Upscale 模型 |
-| Image Mask / Perspective | 静态图 | 原位更新的裁切或矫正图 | Refine 时使用 BEN2 |
+| Image Mask / Perspective | 静态图 | 原位更新的裁切或矫正图 | Fit to Foreground 时使用 BEN2 |
 
 ## 普通 Plane
 
@@ -26,7 +26,7 @@
 
 ## Cutout
 
-只需要图片局部，或希望按轮廓生成 Balloon / Depth Surface 时，使用工具栏中的 **Cutout**。普通 Surface 与 Balloon 可以完全在 Blender 内完成，Refine、Normal 与 Depth Shape 按需调用 AI。
+只需要图片局部，或希望按轮廓生成 Balloon / Depth Surface 时，使用工具栏中的 **Cutout**。普通 Surface 与 Balloon 可以完全在 Blender 内完成，Fit to Foreground、Generate Normal Map 与 Depth Shape 按需调用 AI。
 
 [阅读 Cutout 指南](cutout.md)