Add image perspective editing and related tools

- Implemented the Image Perspective tool for editing image corners in Blender.
- Created a new operator `EditImagePerspective` to handle the perspective transformation.
- Added a preview feature for the perspective adjustment.
- Introduced the `ImagePolylineTool` for editing image masks with polylines.
- Developed backend support for Real-ESRGAN model inference, including ONNX integration.
- Added functionality for image masking and background removal.
- Created unit tests for the Real-ESRGAN ONNX model to ensure correct preprocessing and inference.

docs/development.md

@@ -37,7 +37,7 @@ Mesh Plane、Depth Plane、Surface、Background 和 Balloon 按功能组织。
 
 Server 的模型模块返回 Prediction，几何模块处理数组与网格，输出模块写文件。Blender 数据只在 Operator Response 的主线程阶段创建。
 
-Image Box、Lasso 与 Perspective 位于 `operators/image_extract/` 功能包。模块职责、交互状态、像素管线、背景清理和 Empty 定位见 [Image 工具技术实现](image-tools-technical.md)。
+Image Box、Lasso、Line、Polyline 与 Perspective 位于 `operators/image_edit/` 功能包。模块职责、交互状态、像素管线、Refine 和 Empty 定位见 [Image 工具技术实现](image-tools-technical.md)。
 
 ## 项目结构
 
@@ -122,5 +122,6 @@ BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
 
 - Depth Anything 3 代码采用 Apache 2.0
 - BEN2 ONNX 模型采用其仓库声明的 Apache 2.0 License
+- Real-ESRGAN General x4v3 ONNX 权重采用其模型仓库声明的 BSD 3-Clause License
 - AnyImage Extension 代码采用 GPL-3.0-or-later
 - 模型权重许可证由所选 Hugging Face 模型仓库决定

docs/features.md

@@ -11,7 +11,7 @@
 | Depth Plane | 快速制作可调节的立体图片 | 单图、视频、序列帧 | 带颜色、深度与 Geometry Nodes 的面片 |
 | Surface | 从单张图片恢复透视空间 | 单图 | 相机空间网格、材质与可选匹配相机 |
 | Remove Background | 提取透明前景 | 单图、视频、序列帧 | 透明图片或透明序列 |
-| Image Lasso | 手绘提取并原位更新图片 | 静态 Image Empty | Pack 的透明裁切图 |
+| Image Mask | 用 Box、Lasso、Line 或 Polyline 直接清理图片 | 静态 Image Empty | 原位更新并 Pack 的透明裁切图 |
 | Image Perspective | 四点透视矫正裁切 | 静态 Image Empty | Pack 的矩形裁切图 |
 | Balloon | 沿轮廓绘制鼓起造型 | 静态 Image Empty | 带原图 UV 的封闭网格 |
 | Debug | 检查模型原始输出 | 模型支持的图片或帧序列 | 保存在 Job 目录中的原始 Prediction |
@@ -30,9 +30,9 @@ Balloon 作为不依赖 AI 的基础工具单独排列；三个 AI 功能在缺
 
 转换任务完成后，AnyImage 在一个 Undo 步骤中创建网格、图片、材质和修改器。源 Image Empty 是否保留由转换选项决定。
 
-Image Box、Image Lasso 与 Image Perspective 组成一个工具组，共用源图选择、`Remove Background`、`Continuous` 和 `Padding`。Box 提取矩形，Lasso 提取自由轮廓，Perspective 将任意顺序输入的四个角矫正为指定比例的矩形。结果都是 Pack 的 Image Empty，并沿用源图朝向与深度。
+Image Box、Lasso、Line 与 Polyline 组成 Mask 工具组，并共用 `EditImageMask`。四者用 `F` 切换反选；`Refine Selection` 只用于 Box / Lasso。Perspective 是位于 Mask 组与 Balloon Lasso 之间的独立工具，将任意顺序输入的四个角矫正为指定比例的矩形。结果直接更新当前 Image Empty，并 Pack 到 `.blend`。
 
-操作步骤见 [Image Box、Lasso 与 Perspective](image-tools.md)；处理管线与模块职责见 [Image 工具技术实现](image-tools-technical.md)。
+操作步骤见 [Image 编辑工具](image-tools.md)；处理管线与模块职责见 [Image 工具技术实现](image-tools-technical.md)。
 
 Balloon 默认在 Blender 内部生成，无需 Environment 或模型。Tool Settings 提供模式、厚度、采样距离、材质复用、`Contour`、`Depth` 与 MoGe-2 `Depth Model`；AI 未就绪时只禁用这三个控件，并在 Tool Settings 中显示安装按钮。Depth 会把物理距离相对化并稳健拟合初始基面，保留未截断的正负起伏。Base Plane 子 Empty 的旋转定义基面朝向，沿自身局部 Z 移动定义 middle level。
 
@@ -50,7 +50,7 @@ Blender 无法整体 Pack 图片序列，因此动画结果会继续引用 Job
 
 AI 任务在独立 Python Environment 中通过 ONNX Runtime 执行。Blender 负责界面、任务提交和结果导入，Job Server 负责模型与文件处理。
 
-默认 Storage Root 为 `~/.anyimage`，其中保存 Environment、模型、日志和 Job 结果。连续任务会复用已加载的模型 Session；DA3 与 MoGe-2 共享一个深度模型缓存位置，BEN2 可同时保留。
+默认 Storage Root 为 `~/.anyimage`，其中保存 Environment、模型、日志和 Job 结果。连续任务会复用已加载的模型 Session；DA3 与 MoGe-2 共享一个深度模型缓存位置，BEN2 与 Real-ESRGAN 可同时保留。
 
 安装、下载和推理都在后台运行，并通过状态栏提供进度与取消操作。详细设计见[Job Server](server.md)。
 
@@ -62,6 +62,8 @@ AI 任务在独立 Python Environment 中通过 ONNX Runtime 执行。Blender
 - DA3 Small、DA3 Base
 - BEN2 Base
 
+Debug 另外提供 Real-ESRGAN General x4v3，用于直接检查 4× RGB 放大能力；它当前不属于正式图片工具。
+
 首次安装会准备 MoGe-2 ViT-S Normal 与 BEN2 Base，其他模型可从 AnyImage 扩展偏好设置按需下载。
 
-Debug 工作流保存模型 API 的直接返回，适合验证模型、设备与输入。Depth Plane 和 Surface 则在模型结果之上继续生成 Blender 可用的贴图与几何。文件字段见[输出格式](outputs.md)。
+Debug 工作流保存模型 API 的直接返回，适合验证模型、设备与输入。General x4v3 对每张输入整图推理并保存 `prediction*.png`，不加入切片、降噪强度、Alpha 合成或 Blender 图片写回。Depth Plane 和 Surface 则在模型结果之上继续生成 Blender 可用的贴图与几何。文件字段见[输出格式](outputs.md)。

docs/image-tools-technical.md

@@ -1,77 +1,84 @@
 # Image 工具技术实现
 
-Image Box、Lasso 与 Perspective 位于 `operators/image_extract/`。三者共享源图选择、设置、图片写回、空间定位、Continuous 分层和可选背景清理。
+Image 工具位于 `operators/image_edit/`。Box、Lasso、Line 与 Polyline 共享直接编辑管线；Perspective 在工具栏中独立显示并处理 Homography，但复用源图选择、绘制和 Empty 写回。
 
 ## 模块职责
 
 ```mermaid
 flowchart LR
-    Box["box.py\nWorkspaceTool"] --> Region["region.py\nBox / Lasso Operator"]
-    Lasso["lasso.py\nWorkspaceTool"] --> Region
-    Perspective["perspective.py\n四点与透视矫正"]
-    Region --> Common["common.py\n共享选择、设置与结果写回"]
+    Tools["box / lasso / line / polyline\nWorkspaceTool"] --> Mask["mask.py\n手势、Refine、Invert"]
+    Perspective["perspective.py\n四点、比例、Homography"]
+    Mask --> Common["common.py\n选择、绘制、裁切、Empty 写回"]
     Perspective --> Common
-    Common --> Job["extract-image-background\n可选 BEN2 Job"]
+    Mask --> Job["refine-image-mask\nBEN2 内容 mask"]
 ```
 
-`box.py` 与 `lasso.py` 只声明 WorkspaceTool。两者通过 `selection_shape` 复用 `ExtractImageRegion`；Perspective 保留独立 Operator，因为它还有四点输入、比例预览和 Homography。
+- `box.py`、`lasso.py`、`line.py`、`polyline.py` 只声明 WorkspaceTool。
+- `mask.py` 用 `EditImageMask` 统一四种手势；`RefineImageMask` 负责异步 BEN2 响应。
+- `perspective.py` 维护四点输入、比例预览和全分辨率重采样。
+- `common.py` 只放跨两条管线实际共用的逻辑。
 
 ## 首次点击
 
-`resolve_image_extract_click()` 将首次点击归为两种结果：
+`resolve_image_edit_click()` 临时调用 Viewport Select 判断点击目标：
 
-| 点击目标 | 结果 |
+| 点击目标 | 行为 |
 | --- | --- |
-| 另一张 Image Empty | 只选择并设为 Active |
-| 当前 Active 图片、空白或非图片对象 | 使用当前 Active 图片开始取区 |
+| 另一张 Image Empty | 选择并设为 Active，本次不编辑 |
+| 当前 Active 图片、空白或非图片对象 | 恢复原选择并开始编辑当前图片 |
 
-这段逻辑由三个工具共用。点击非图片对象后会恢复原选择，避免触发对象移动或更换源图。
+这避免工具在无有效源图时退化为对象移动，也让用户无需切回 Select Tool。
 
-## 处理管线
+## Mask 管线
 
 ```mermaid
 flowchart TD
-    Input["屏幕选区"] --> Pixels["转换到源图片像素坐标"]
-    Pixels --> Background{"Remove Background?"}
-    Background -- 否 --> Local["Blender 内处理 RGBA"]
-    Background -- 是 --> Server["选区画布 → BEN2 → 局部图片"]
-    Local --> Tool{"工具类型"}
-    Server --> Tool
-    Tool -- Box / Lasso --> Crop["Alpha bounds + Padding"]
-    Tool -- Perspective --> Warp["预乘 Alpha Homography"]
-    Warp --> Crop
-    Crop --> Result["创建并 Pack Image\n定位 Empty"]
+    Gesture["屏幕手势"] --> Polygon["源图片像素 polygon / mask"]
+    Polygon --> Refine{"Refine Selection?"}
+    Refine -- 否 --> Content["几何 mask"]
+    Refine -- 是 --> Server["选区外 RGBA 清零 → BEN2"]
+    Server --> Content2["BEN2 Alpha × 几何 mask"]
+    Content --> Invert{"Invert?"}
+    Content2 --> Invert
+    Invert -- 否 --> Final["final mask"]
+    Invert -- 是 --> Reverse["1 - final mask"]
+    Final --> Apply["源 Alpha × mask"]
+    Reverse --> Apply
+    Apply --> Crop["按非零 Alpha 紧裁切\n保留源 RGB"]
+    Crop --> Write["替换 Image 并更新 Empty 显示"]
 ```
 
-Box 与 Lasso 将选区外 RGBA 清为透明黑，再按非零 Alpha 的最小范围裁切。Perspective 先将四点规范为沿源图 X/Y 方向的凸四边形，再按确认的宽高比重采样；点击顺序不参与输出旋转。
+Box / Lasso 的顺序固定为 **Refine → Invert**。BEN2 只提供内容 Alpha；最终 RGB 始终来自源图。Blender 侧只修改 Alpha，不清理透明区 RGB，以避免 Viewport 纹理过滤产生黑边。Line / Polyline 强制关闭 Refine，只执行几何 mask 与 Invert。
 
-透视预览固定生成一次 512 × 512 临时 Image。鼠标移动只改变屏幕上的预览比例；确认后才执行全分辨率重采样。
+Line 的屏幕坐标 Y 轴与图片坐标 Y 轴方向相反，因此像素阶段会反转线段端点，使半透明预览侧与实际保留侧一致；`Ctrl` 只影响屏幕端点的 5° 吸附。零长度点击在投影前直接取消，投影结果不足两个点时也会安全终止。Polyline 接近起点时绘制闭合圆环，并支持单击起点或 `Enter` 完成；完成时显式闭合，不把当前游标位置作为额外顶点。
 
-## 背景清理
+## Perspective 管线
 
-`extract-image-background` 与标准 `remove-background` Job 共用 `remove_image_background()`。图片工具的 Job 只增加三项选区语义：
+四点先按源图片 X/Y 方向规范为凸四边形，输入顺序不参与输出方向。第四点后只生成一次 512 × 512 临时纹理；移动鼠标改变 UI 比例，确认时才进行全分辨率 Homography。
 
-- polygon mask；
-- 局部图片在源图中的 bounds；
-- Box / Lasso 使用的透明 Padding。
+透视重采样使用预乘 Alpha 插值，随后恢复 RGB、清理透明像素并紧裁切。输出最长边限制为 8192 px，总像素限制约 16 MP。
 
-Perspective 请求的 Job Padding 固定为 0。局部结果回到 Blender 后先换算为源图坐标，再执行透视矫正和最终 Padding。
+Perspective 不调用 BEN2，也不支持 Invert。它是 deform 工具，不属于 mask 清理语义。
 
-## Empty 定位与 Continuous
+## Empty 写回
 
-Box 与 Lasso 根据裁切前后的像素 bounds 换算 Empty 的中心和显示尺寸。Perspective 使用源四边形的轴对齐 bounds 近似放置结果。三者都沿用源 Empty 的矩阵，因此朝向与深度不变。
+`replace_empty_image_pixels()` 创建并 Pack 新 Image datablock，然后替换当前 Empty 的 `data`。它不复制对象，也不修改 `matrix_world`。
 
-Continuous 关闭时直接更新源 Empty；开启时复制对象，并沿操作开始时捕获的 View 方向偏移：
+`align_empty_display_to_bounds()` 根据源画布、旧 `plane_bounds`、结果尺寸和放置 bounds 更新：
 
-```text
-offset = display_size × world_scale × 0.001 × layer
-```
+- `empty_display_size`；
+- `empty_image_offset`。
 
-`layer` 记录在源对象的 `_anyimage_extract_layer` Custom Property 中，使连续结果依次靠近当前 View。
+Box、Lasso、Line 与 Polyline 的放置 bounds 等于最终裁切范围，因此像素与原图片平面严格对齐。Perspective 的结果比例可能不同于四边形轴对齐范围，因此只保持中心和覆盖尺度近似一致。
 
-## 维护约束
+## Server 边界
 
-- WorkspaceTool 的显示设置放在 `box.py`、`lasso.py`、`perspective.py`。
-- Box / Lasso 的共享交互放在 `region.py`，跨三个工具的行为放在 `common.py`。
-- Blender 数据只在主线程 Operator 中读写；Server 参数保持为可序列化字典。
-- 普通裁切不启动 Job Server；只有 Remove Background 需要 Environment 与 BEN2。
+普通 Mask 和 Perspective 完全在 Blender 侧执行。只有 Box / Lasso 的 **Refine Selection** 提交 `refine-image-mask`：
+
+1. 根据 polygon 创建局部透明画布；
+2. 清空选区外 RGBA；BEN2 公共入口再以输入 Alpha 遮住透明 RGB；
+3. 使用共享的 `remove_image_background()` 运行 BEN2；
+4. 再乘几何 selection mask；
+5. 返回紧裁切的 `image.png` 与源图坐标 `bounds.json`。
+
+Blender 只读取返回图片的 Alpha，并把它应用到原图 RGB。相同的 BEN2 输入清理规则也用于 Remove Background、Depth Plane、Surface 和 Balloon；正式输出使用源 RGB 与 BEN2 Alpha。Blender 数据只在主线程 Operator 中读写，Job 参数保持为可序列化字典。

docs/image-tools.md

@@ -1,85 +1,82 @@
-# Image Box、Lasso 与 Perspective
+# Image 编辑工具
 
-这三个工具用于从 Image Empty 中提取局部图片。结果仍是 Image Empty，并自动 Pack 到 `.blend`。
-
-它们只处理静态图片。视频和序列帧请使用其他转换工具。
+Image Box、Lasso、Line、Polyline 与 Perspective 直接编辑静态 Image Empty，并把结果 Pack 到当前 `.blend`。前四个工具组成 Mask 工具组；Perspective 是紧随其后的独立工具，Balloon Lasso 位于 Perspective 之后。
 
 ## 选择工具
 
-| 工具 | 适合 |
+| 工具 | 用途 |
 | --- | --- |
-| **Image Box** | 提取矩形区域，操作最快 |
-| **Image Lasso** | 沿物体或不规则边界自由绘制 |
-| **Image Perspective** | 将海报、屏幕、门窗等四边形内容矫正为矩形 |
+| **Image Box** | 用矩形保留或清理图片区域 |
+| **Image Lasso** | 手绘自由选区 |
+| **Image Line** | 用一条直线清理一侧 |
+| **Image Polyline** | 逐点构建精确多边形 |
+| **Image Perspective** | 将任意顺序输入的四个角矫正为矩形 |
 
-在 3D Viewport 左侧工具栏找到 Image 工具组。长按当前图标可以切换三个工具；设置位于 Tool Settings。
+在 3D Viewport 左侧工具栏长按 Image Mask 图标，可以在 Box、Lasso、Line 与 Polyline 之间切换。**Refine Selection** 只显示在 Box / Lasso；Line / Polyline 保持几何直线边界。Perspective 使用独立图标。
 
 <div class="screenshot-placeholder" markdown>
-**截图占位：工具组与 Tool Settings**
+**截图占位：Image 工具组与 Tool Settings**
 
-建议同时显示三个工具入口，以及 Remove Background、Continuous、Padding。
+显示包含四个工具的 Image Mask 组、独立 Perspective、Balloon Lasso，以及 Box / Lasso 的 Refine Selection。
 
 目标文件：`images/image-tools/tool-group.png`
 </div>
 
-## 选择源图片
+## 选择图片
 
-如果当前 Active 已是目标图片，可以直接开始取区。
+直接在当前 Active 图片上开始绘制。如果第一次点击的是另一张 Image Empty，这次点击只会选中它；下一次操作才开始编辑。点击空白处或非图片对象时，继续编辑当前 Active 图片，不会移动对象。
 
-如果要处理另一张图片，先点击它。这一次点击只负责选择；下一次点击或拖动才开始取区。点击空白处或其他类型的对象时，工具继续使用当前 Active 图片。
+没有 Active Image Empty 时，工具会提示先选择图片。切换到其他工具会立即取消正在进行的绘制。
 
-!!! tip
-    最简单的习惯是：先点一下目标图片确认 Active，再开始绘制。
+## 清理选区
 
-## 使用 Box 或 Lasso
+### Box 与 Lasso
 
-=== "Image Box"
+- Box：按住左键拖出矩形，松开后执行。
+- Lasso：按住左键绘制轮廓，松开后执行。
 
-    1. 按住左键，从区域一角拖到另一角。
-    2. 松开左键，立即生成结果。
+### Line
 
-=== "Image Lasso"
+从起点拖到终点，松开后保留直线左侧的内容。按住 `Ctrl` 以 5° 为单位吸附方向；需要另一侧时按 `F` 翻转。
 
-    1. 按住左键，沿需要保留的区域绘制。
-    2. 松开左键，立即生成结果。
+### Polyline
 
-选区可以越过图片边缘。只要范围内仍有可见像素，工具就会按实际内容裁切。
+逐点单击构建多边形。鼠标接近起点时会显示闭合圆环；单击圆环或按 `Enter` 完成，`Backspace` 删除最近一点。
+
+绘制过程中按 `F` 切换反选。反选是一个持续到本次操作完成的状态，不需要按住：
+
+- 关闭：保留选区内；
+- 开启：保留选区外。
+
+Box / Lasso 启用 **Refine Selection** 后，BEN2 会先把几何选区收紧到其中的前景，再应用反选。例如框住一个苹果并开启反选，最终会清理苹果本身、保留其余内容。Line / Polyline 不提供 Refine，以保持直线边界和明确的裁切方向。
+
+结果会直接替换当前 Empty 的图片，并把画布紧裁切到最终可见 Alpha。对象 Transform 不变，显示尺寸与 Image Offset 会更新，使剩余像素保持在原图片平面上的位置。透明区只修改 Alpha，保留源 RGB 供纹理过滤使用；完全透明的结果不会写入。
 
 <div class="screenshot-placeholder" markdown>
-**截图占位：Box 与 Lasso 取区**
+**截图占位：Polyline 与反选**
 
-建议用一张并排图展示矩形拖拽和自由轮廓，不需要额外结果图。
+显示半透明选区面、虚线边界，以及状态栏中的 `F toggles Invert`。
 
-目标文件：`images/image-tools/box-lasso.png`
+目标文件：`images/image-tools/polyline-invert.png`
 </div>
 
-## 使用 Perspective
+## 四点透视
 
-1. 依次点击内容的四个角，顺序不限。
-2. 第四点完成后，Viewport 中央会显示矫正预览。
-3. 左右移动鼠标调整宽高比。
-4. 单击左键确认并生成结果。
+1. 任意顺序单击四个角点。
+2. 第四点后，在 Viewport 中央检查矫正预览。
+3. 左右移动鼠标调整宽高比；按住 `Ctrl` 可吸附到 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`。
+4. 左键确认。
 
-调整比例时按住 `Ctrl`，可以吸附到 `1:1`、`4:3`、`3:4`、`16:9` 和 `9:16`。`Backspace` 返回上一个角点；右键或 `Esc` 取消。
+`Backspace` 返回上一步，右键或 `Esc` 取消。四点会自动排序，点击顺序不会改变输出旋转。
+
+Perspective 只执行图片 Homography 与紧裁切，不做 Refine，也不尝试从当前 View 推导真实相机。结果保持源 Empty 的 Transform，并按原四边形覆盖范围近似更新显示位置与尺寸。选区完全位于图片外或没有可见像素时不会执行。
 
 <div class="screenshot-placeholder" markdown>
 **截图占位：Perspective 比例确认**
 
-建议截取中央图片预览、蓝色边框、比例文字和底部操作提示。
+显示中央图片预览、蓝色边框、当前比例与底部操作提示。
 
 目标文件：`images/image-tools/perspective-aspect.png`
 </div>
 
-## 结果设置
-
-- **Remove Background**：使用 BEN2 删除选区内的背景，再按可见内容裁切。首次使用需要先完成 AI Environment 与 BEN2 配置。
-- **Continuous**：保留源图片，连续创建新结果。新图片会向当前 View 稍微靠近，减少重叠闪烁。
-- **Padding**：在可见内容四周增加透明像素，单位为 px。
-
-Continuous 关闭时，结果会原位替换当前 Image Empty；开启时，源图片保持 Active，便于继续提取其他区域。
-
-## Perspective 的结果位置
-
-Perspective 会矫正图片内容，但不会尝试还原真实相机或空间平面。结果沿用源图片的朝向和深度，并大致放在原四边形覆盖的区域。
-
-需要了解交互状态、像素处理和模块职责时，请阅读 [Image 工具技术实现](image-tools-technical.md)。
+实现结构与像素规则见 [Image 工具技术实现](image-tools-technical.md)。

docs/index.md

@@ -9,7 +9,7 @@ AnyImage 是一款 Blender 扩展，可以把照片、视频或序列帧转换
 - 用 **Depth Plane** 快速得到可调节的浮雕式面片
 - 用 **Surface** 从单张图片生成透视纹理网格
 - 用 **Remove Background** 一键获得透明前景
-- 用 **Image Perspective** 将四点选区矫正为沿用源 Empty 朝向的矩形裁切图
+- 用 **Image Box / Lasso / Line / Polyline** 直接清理图片，或用 **Image Perspective** 做四点透视矫正
 - 处理视频和序列帧，生成可随时间播放的 Depth Plane
 - 使用 Geometry Nodes 继续调整深度、细分、重拓扑与平滑效果
 

docs/models-and-storage.md

@@ -9,7 +9,7 @@ AnyImage 把运行环境、模型和任务结果放在 Blender 之外，多个 B
 - **Ready** 表示模型文件已经就绪。
 - **Download** 用于按需下载模型。
 - 默认安装会准备 MoGe-2 ViT-S Normal 和 BEN2 Base。
-- DA3 与更大的 MoGe-2 模型需要时再下载即可。
+- DA3、更大的 MoGe-2，以及只供 Debug 使用的 Real-ESRGAN General x4v3 需要时再下载即可。
 
 较大的模型不一定适合所有图片。建议先用默认模型完成构图，再针对细节与性能需求比较其他模型。
 

docs/outputs.md

@@ -9,11 +9,12 @@
 | `generate-depth` | `results.npz`、深度与颜色序列 | Depth Plane 所需深度、相机和贴图 |
 | `generate-surface` | `mesh.npz`、`normal.png`、颜色层 | Surface 网格、相机与材质输入 |
 | `remove-background` | `color.0001.png` 起 | 带 Alpha 的颜色层 |
-| `extract-image-background` | `selection-input.png`、`image.png`、`bounds.json` | 图片工具选区内去背景后的局部图片与原图坐标 bounds |
+| `refine-image-mask` | `selection-input.png`、`image.png`、`bounds.json` | BEN2 细化后的局部内容 mask 与原图坐标 bounds |
 | `analyze-balloon` | `lasso-input.png`，按选项输出 `foreground.png`、`contour.json`、`depth.npz`、`normal.png` | 套索约束输入、BEN2 轮廓与 MoGe-2 深度、法线 |
 | `debug-da3` | `prediction.npz` | DA3 API 返回 |
 | `debug-moge2` | `prediction*.npz` | MoGe-2 API 返回 |
 | `debug-ben2` | `foreground*.png` | BEN2 API 返回 |
+| `debug-realesrgan-general-x4v3` | `prediction*.png` | Real-ESRGAN General x4v3 的 4× RGB API 返回 |
 
 ## NPZ 字段
 
@@ -23,7 +24,7 @@ Balloon Depth 的 `depth.npz` 包含相对 `depth_signal`、归一化拟合平
 
 Surface 的 `mesh.npz` 包含 `vertices`、`faces`、`uv`、`intrinsics`、`image_size` 与 `reference_depth`，以及 Geometry Nodes 使用的网格属性。
 
-Debug 文件保持模型 API 的数据形态，用于比较推理结果；正式 Job 则提供 Blender 导入所需的派生数据。
+Debug 文件保持模型 API 的数据形态，用于比较推理结果；正式 Job 则提供 Blender 导入所需的派生数据。General x4v3 的浮点 RGB 返回只做 `[0, 1]` 限制和 8-bit PNG 序列化，不做额外画质处理。
 
 ## 图片序列
 

docs/remove-background.md

@@ -35,4 +35,4 @@ Depth Plane 和 Surface 的转换对话框也提供 **Remove Background**：
 
 当前正式入口不提供 BEN2 refinement 参数。可以在结果材质中继续处理 Alpha，或在外部图像软件中修整生成的颜色图。
 
-输入图片已有 Alpha 时，AnyImage 会先用该 Alpha 遮住 BEN2 推理输入中的透明 RGB，再将结果 Alpha 计算为“输入 Alpha × BEN2 Alpha”。因此 Image Box / Lasso 或外部工具创建的透明范围不会被去背景重新扩张；软边缘也会继续保留。
+所有 BEN2 任务都会先用输入 Alpha 遮住推理输入中的透明 RGB。正式输出只采用 BEN2 的 Alpha，颜色继续使用源 RGB；已有 Alpha 时，结果 Alpha 为“输入 Alpha × BEN2 Alpha”。因此 Image Box / Lasso 或外部工具创建的透明范围不会被去背景重新扩张，软边缘也会继续保留，同时避免透明黑参与 Viewport 纹理过滤。

docs/server.md

@@ -59,7 +59,9 @@ Environment 使用 Python 3.12、ONNX Runtime、NumPy、Pillow、PyAV、trimesh
 
 Balloon 的 `analyze-balloon` Job 会裁切套索输入并清零选区外 RGBA。`Contour` 用 BEN2 回传最大连通轮廓；`Depth` 用 MoGe-2 对有效相机距离稳健拟合二维基面，并把物理距离换算为不受绝对拍摄距离影响、未截断的相对深度信号。Job 同时把 MoGe normal 转换为 tangent-space 纹理，铺回原图尺寸并以中性法线填充无效区域。Blender 主线程负责采样深度属性、创建 Base Plane Empty、组装 `O Balloon Shape` 修改器与 `O Balloon Layer` 材质。
 
-图片 Box、Lasso 与 Perspective 的可选 `Remove Background` 使用 `extract-image-background` Job。它与标准 `remove-background` Job 共用单图 BEN2 去背景函数，再叠加图片工具专属的 polygon mask、局部 bounds 与透明 Padding。
+Image Box 与 Lasso 的 `Refine Selection` 使用 `refine-image-mask` Job。它与标准 `remove-background` Job 共用单图 BEN2 函数；Server 在推理前清空 polygon 外的 RGBA，推理后再次应用几何 mask，并返回局部 Alpha 与源图 bounds。Line、Polyline 与 Perspective 不提交 Job。
+
+所有 BEN2 调用都在公共模型入口用输入 Alpha 遮住透明 RGB。Remove Background、Depth Plane、Surface 与 Image Refine 的正式结果保留源 RGB，只采用 BEN2 Alpha；Balloon 同样只消费 BEN2 Alpha。该边界既防止模型识别透明区隐藏内容，也避免把透明黑写回 Blender 后产生过滤黑边。
 
 正式功能支持：
 
@@ -67,10 +69,14 @@ Balloon 的 `analyze-balloon` Job 会裁切套索输入并清零选区外 RGBA
 - DA3 Small、DA3 Base
 - BEN2 Base
 
-首次安装会下载 MoGe-2 ViT-S Normal 与 BEN2 Base。模型保存在 `models/`，可由多个 Blender 版本共享。Server 缓存 BEN2 和最近使用的一个深度模型，以控制内存占用。
+Debug 任务另外支持 Real-ESRGAN General x4v3；它只提供模型直通测试，不属于正式功能。
+
+首次安装会下载 MoGe-2 ViT-S Normal 与 BEN2 Base。Real-ESRGAN General x4v3 由扩展偏好设置按需下载。模型保存在 `models/`，可由多个 Blender 版本共享。Server 缓存 BEN2、Real-ESRGAN 和最近使用的一个深度模型，以控制内存占用。
 
 模型下载优先使用 Hugging Face，并以 OmooLab 镜像作为回退。AnyImage 用同一个准备 Operator 封装 BlendJob 安装任务，并按状态显示 `Set Up AI Environment…` 或 `Download Required Models…`；`Use Mirror` 属性只影响 Environment Bootstrap，不改变模型下载策略。Blender UI 通过同一个状态函数检查 Environment 指纹与默认模型文件：缺 Environment 时执行完整安装，只有默认模型缺失时仅提交补齐模型任务。
 
+`debug-realesrgan-general-x4v3` 将每张输入的完整 RGB 动态尺寸张量直接送入 ONNX，并把 4× 返回保存为 `prediction*.png`。该 Job 不实现 tile、强度混合、Alpha 合成或 Blender 结果导入。
+
 ## 任务生命周期
 
 Server 在第一次提交 Job 或手动 Start 时启动。任务进入单 Worker FIFO Queue，同一时间执行一个推理、下载或媒体任务。

docs/workflows.md

@@ -8,8 +8,8 @@ AnyImage 提供多种日常工作流。选择结果时，先考虑你需要的
 | Depth Plane | 人物、产品、插画、动态背景、快速场景搭建 | 图片、视频、序列帧 | 带深度位移的平面 | 快速、可动画、Geometry Nodes 参数直观 |
 | Surface | 建筑、室内、街景、需要匹配视角的单图 | 单张图片 | 透视纹理网格 | 空间感更强，可创建匹配相机 |
 | Remove Background | 抠出人物或物体，继续作为 Image Empty 使用 | 图片、视频、序列帧 | 带透明 Alpha 的颜色图 | 不创建网格，保留 Empty 的位置和显示设置 |
-| Image Box / Lasso | 矩形或手绘提取局部内容并按 Alpha 范围裁切 | 静态图片 | Pack 的透明裁切图 | 支持 Padding 与 Continuous，不创建网格 |
-| Image Perspective | 海报、屏幕、门窗等四边形内容的透视矫正裁切 | 静态图片 | Pack 的矩形图片 | 四点任意顺序，共用 Remove Background、Padding 与 Continuous |
+| Image Box / Lasso / Line / Polyline | 用几何选区直接清理图片 | 静态图片 | 原位更新的透明裁切图 | `F` 反选，可用 BEN2 细化选区 |
+| Image Perspective | 海报、屏幕、门窗等四边形内容的透视矫正裁切 | 静态图片 | 原位更新的矩形图片 | 四点任意顺序，交互调整比例 |
 
 ## 什么时候选择 Mesh Plane
 
@@ -37,4 +37,4 @@ Surface 会根据模型估算的相机和深度构建透视网格。相较 Depth
 
 ## 什么时候使用 Image Perspective
 
-当图片中的矩形物体因为透视变成四边形，并且希望得到一张正视矩形裁切图时，使用 3D Viewport 工具栏中的 **Image Perspective**。它只把四点当作图片裁切与 Homography 输入，不假设当前 View 的焦距与原图拍摄相机一致。四点顺序不影响输出方向；结果 Empty 保持源图朝向和深度，并按源图中的选区范围近似放置。需要持续提取多个区域时，可开启与 Image Box / Lasso 共用的 Continuous。
+当图片中的矩形物体因为透视变成四边形，并且希望得到一张正视矩形裁切图时，使用 3D Viewport 工具栏中的 **Image Perspective**。它只把四点当作图片裁切与 Homography 输入，不假设当前 View 的焦距与原图拍摄相机一致。四点顺序不影响输出方向；结果 Empty 保持源图 Transform，并按源图中的选区范围近似更新显示位置与尺寸。