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/internals/operators/convert-to-plane.md

@@ -1,61 +1,42 @@
 # Plane 转换
 
-Plane 转换包含两条路径：普通 Plane 在 Blender 内同步完成；Depth Plane 先通过 `generate-depth-plane` Job 取得深度场，再回到 Blender 构建面片。两者共享图片命名、材质与基础四边形能力，但使用不同的 Geometry Nodes。
+Plane 转换从当前 Image Empty 创建普通 Plane 或 Depth Plane：普通 Plane 同步完成，Depth Plane 先取得 MoGe-2 Z Depth 文件再回到 Blender 创建对象。
 
-## 对应文件
-
-```text
-operators/convert_to_plane/
-├── __init__.py    # 对外导出
-├── conversion.py  # 两个入口 Operator 与 Depth Job
-├── build.py       # 颜色、深度场、材质和对象导入
-├── mesh_plane.py  # 基础四边形与 O Mesh Plane 修改器
-└── nodes.py       # 运行时 O Image Depth Plane 节点图
-
-server/
-├── jobs/generate_depth_plane.py
-├── geometry/generate_depth.py
-├── models/da3.py
-├── models/moge2.py
-└── geometry/projection.py
-```
-
-## 总体流程
+## 执行过程
 
 ```mermaid
 flowchart TD
     Empty["Image Empty"] --> Kind{"转换类型"}
-    Kind -- "Plane" --> Copy["复制 Image 与材质"]
-    Copy --> Quad["创建四边形 + O Mesh Plane"]
-    Kind -- "Depth Plane" --> Input["准备颜色与分析输入"]
-    Input --> Job["generate-depth-plane"]
-    Job --> Field["image.0001 + image_geometry.npz"]
-    Field --> Anchor["按 Empty 范围锚定相机点"]
-    Anchor --> Depth["创建深度 Image + 材质 + 节点修改器"]
-    Quad --> Replace["替换源 Empty"]
-    Depth --> Replace
+    Kind -- "Plane" --> Color["复制 Color Image"]
+    Color --> Plane["创建 Plane Object"]
+    Kind -- "Depth Plane" --> Job["generate-depth-plane-geometry"]
+    Job --> Result["Color Image + z-depth.exr + depth.json"]
+    Result --> Import["直接加载并 Pack Depth Image"]
+    Import --> Depth["创建 Depth Plane Object"]
 ```
 
-## 普通 Plane
+两条路径共用 Image Empty 的显示范围、颜色材质和基础 Plane。Depth Plane 多出一次 Server Job，并由节点根据相机元数据把 Z Depth 转换为局部位移。正式流程只使用 MoGe-2；DA3 只保留 Debug 入口。
 
-`ConvertToPlane` 复制当前 Image 数据，保留 Movie / Sequence 的 Image User 设置，创建与 Image Empty 显示范围一致的四边形，再加载内置 `O Mesh Plane` 节点组。原始 Mesh 始终只有一个四边形；`Subdivide`、`Thickness` 和材质赋值由修改器执行。
+## 节点说明
 
-对象继承源 Empty 的 `matrix_world`。转换完成后删除源 Empty，并让新 Plane 沿用对象名称。剪贴板的 Plane 导入复用同一构建函数，因此两种入口得到一致的基础网格与修改器。
+### 选择 Plane 或 Depth Plane
 
-## Depth Plane
+`operators/convert_to_plane/__init__.py` 导出注册类型，实际入口在 `conversion.py`。`ConvertToPlane` 进入本地路径，`ConvertToDepthPlane` 检查静态图片和 AI 环境后启动 `GenerateDepthPlane`。
 
-`ConvertToDepthPlane` 当前只接受静态图片。深度模型和分辨率来自扩展 Preferences：MoGe-2 使用 Resolution Level，DA3 使用按原图尺寸换算并对齐到模型 Patch 的处理分辨率。
+### 创建普通 Plane
 
-`GenerateDepthPlane` 把当前 Image 随模型参数提交给 `generate-depth-plane`。`jobs/generate_depth_plane.py` 负责单图协议，`geometry/generate_depth.py` 负责 AI 深度生成；Server 将模型结果统一为 `GeometryFrame`，写出包含相机点、深度、内参、有效区域和参考深度的 `image_geometry.npz`。Blender 侧通过公共 `load_image_geometry()` 读取为 `ImageGeometry`，与 Cutout 使用同一协议校验。这一步不创建网格。`max_input_size` 同时传入 Job；Server 通过 `media/resolution.py` 在模型推理前限制分析图长边，默认 `2048`。颜色输入仍按当前 Image 的未缩放分辨率复制，受限分析图不会成为材质 Color。
+`conversion.py` 先调用 `object.create_color_image()` 复制当前 Image，再由 `object.create_plane_object()` 创建对象。`object.py` 使用 `mesh_plane.py` 生成与 Image Empty 显示范围一致的基础四边形，并通过 `nodes.py` 加载 `O Mesh Plane` 修改器。
 
-Blender 响应阶段执行三件事：
+Movie 或 Sequence 的 Image User 设置会保留。转换完成后，新 Plane 替换源 Empty，并沿用原对象名称。
 
-1. 根据 Image Empty 的平面范围、相机内参和参考深度，把相机点等比锚定到对象局部空间。
-2. 将锚定点的局部 Z 写入 Packed 浮点 `_depth.exr` Image，并创建颜色材质。
-3. 创建基础四边形和运行时 `O Image Depth Plane` 节点组，以 UV 采样深度并移动正面。
+### 生成 Z Depth
 
-Depth 节点组先复用 `O Mesh Plane` 完成细分与材质，再生成背面厚度、限制正面向内穿透，最后在 Thickness 为零时删除背面和侧面。`Depth Amount` 控制位移强度；`Depth Image` 与 `Material` 是由插件填入的内部输入。
+Depth 路径中的 `GenerateDepthPlane` 位于 `conversion.py`。它从 Preferences 读取 **Depth & Normal Model**、**MoGe Resolution Level** 和 **Maximum AI Input Size**，提交 `generate-depth-plane-geometry` Job。
 
-与 Cutout 的 Depth Surface 不同，Depth Plane 只使用锚定后的 Z 高度，不在 Geometry Nodes 中重建完整相机空间 XYZ。它强调一张图上的可编辑浮雕，而不是局部透视表面。
+`server/jobs/depth_plane.py` 编排任务，`server/geometry/prediction_artifacts.py` 调用 MoGe-2，写出 `z-depth.exr` 与 `depth.json`。EXR 的 RGB 重复保存相机 Z，Alpha 保存有效区；JSON 保存图片尺寸、相机内参与参考深度。AI 输入上限只影响模型分析图，颜色副本仍保留原始分辨率。
 
-颜色材质、Normal 导入和结果对象激活分别复用 `create_image_material()`、`load_normal_result_image()` 与 `finalize_object_result()`；普通 Plane 和 Depth Plane 不再各自维护对象替换步骤。
+### 创建 Depth Plane
+
+Job 返回后，`object.create_depth_plane_from_result()` 直接加载并 Pack `z-depth.exr`，数据块仍由 `depth_data_name()` 命名。`depth.json` 用于计算统一尺度，`O Image Depth Plane` 根据参考深度、统一尺度和用户的 Depth Amount 把相机 Z 转换为局部位移。
+
+随后 `object.py` 创建颜色材质和基础四边形，`nodes.py` 加载 `O Image Depth Plane` 修改器。`conversion.py` 最后用一个 Undo 步骤替换源 Empty。