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/upscale.md

@@ -1,37 +1,44 @@
 # Upscale
 
-本页对应 `src/anyimage/operators/upscale.py`。该模块读取扩展首选项中的模型与全局 AI 输入长边上限，检查当前 Image 是否可处理，再提交 4× 高清任务。
+Upscale 从当前 Image Empty 读取单图或多帧媒体，在输入长边允许时生成 4× RGBA 结果并替换原图。
 
-## 对应文件
-
-```text
-src/anyimage/
-├── operators/
-│   ├── upscale.py                 # Blender 入口、任务参数与结果替换
-│   └── common/image_data.py            # 媒体输入准备与结果 Image 创建
-└── server/
-    ├── jobs/upscale.py            # 单图与多帧任务编排
-    ├── media/resolution.py        # 共用长边限制与等比缩放
-    ├── models/upscale.py          # 输入约束与 Alpha 合并
-    └── models/onnx_upscale.py     # 分块 4× ONNX 推理
-```
-
-## 主流程
+## 执行过程
 
 ```mermaid
 flowchart TD
-    Empty["Image Empty"] --> Source["读取当前 Image"]
-    Source --> Gate{"当前长边小于全局上限？"}
-    Gate -- "否" --> Disabled["Upscale 置灰"]
+    Empty["Image Empty"] --> Gate{"长边小于输入上限？"}
+    Gate -- "否" --> Disabled["禁用或报告错误"]
     Gate -- "是" --> Prepare["准备媒体输入"]
     Prepare --> Job["upscale-image Job"]
     Job --> RGB["分块执行 4× RGB 推理"]
     Job --> Alpha["独立缩放 Alpha"]
-    RGB --> Merge["合并 RGBA 结果"]
+    RGB --> Merge["合并 RGBA"]
     Alpha --> Merge
     Merge --> Replace["导入并替换当前 Image"]
 ```
 
-模型以 256×256 分块处理 RGB，并带入相邻上下文以减弱块边界；Alpha 不进入模型，使用 Lanczos 独立放大后合并为 RGBA。`max_input_size` 来自全局 **Maximum AI Input Size**，默认 `2048`。Operator 只允许当前 Image 长边小于该值时执行，因此正式流程不会预缩放输入，4× 输出长边小于上限的四倍。Server 仍保留相同上限作为任务边界。
+模型只处理 RGB，Alpha 单独放大后再合并。Blender 侧在提交前检查 **Maximum AI Input Size**，Server 模型层也应用同一个输入上限。
 
-菜单根据当前尺寸只显示预计的 4× 结果尺寸。结果通过与 Remove Background、Image Mask 和 Perspective 相同的 Image Empty 替换入口处理：原 Image 没有其他用户且未启用 Fake User 时，移除旧数据并让结果沿用原名；存在其他用户时保留原 Image，并只让当前 Empty 使用独立结果。结果不增加 Upscale 专属后缀，也不保存来源引用。后续 Upscale 与 Depth Plane 都读取当前 Image。模型与全局输入上限在每次执行时从 Preferences 读取，再写入可序列化的隐藏属性交给 Job。Provider 资源错误会释放当前 Upscale Session，并提示降低全局输入上限或改用 CPU。
+## 节点说明
+
+### 检查尺寸并准备输入
+
+入口位于 `operators/upscale.py`。`UpscaleImage.poll()` 读取 `preferences.py` 中的 **Maximum AI Input Size**；当前 Image 长边必须严格小于该值。菜单显示的预计尺寸来自同一文件的 `upscale_output_size()`。
+
+执行时，`upscale.py` 冻结当前模型和输入上限，并通过 `operators/common/image_data.py` 准备单图、视频或序列输入。Packed Image 与内存修改结果会导出临时文件，多帧输入保留帧起点和抽帧设置。
+
+### 分块放大 RGB
+
+`UpscaleImage` 提交 `upscale-image` Job。`server/jobs/upscale.py` 展开媒体帧并逐帧调用模型；`server/models/upscale.py` 负责输入约束、RGB/Alpha 分离和结果合并，`server/models/onnx_upscale.py` 以 256 × 256 分块执行 4× ONNX 推理并带入相邻上下文。
+
+`server/media/resolution.py` 统一解释输入长边上限。正式 Upscale 在 Blender 侧直接禁用超限图片，因此不会进入预缩放路径，输出长边小于上限的四倍；模型层仍保留同一限制作为任务边界。
+
+### 合并 Alpha
+
+Alpha 不进入模型，由 `server/models/upscale.py` 使用 Lanczos 放大到目标尺寸，再与 4× RGB 合并为 RGBA。Provider 资源不足时，Server 释放当前 Upscale Session，并返回降低输入上限或改用 CPU 的提示。
+
+### 导入并替换结果
+
+响应阶段回到 `operators/upscale.py`，通过 `operators/common/image_data.py` 读取 `upscale.*` 结果序列并替换当前 Empty。源 Image 没有其他用户且未启用 Fake User 时会被清理并由结果继承名称；存在其他用户时只替换当前 Empty 的引用。
+
+结果不添加 Upscale 专属数据块后缀，也不保留来源引用。后续再次 Upscale 或转换 Depth Plane 时，读取的都是当前结果 Image。