# 功能参考

本页概览 AnyImage 的能力。安装步骤见[安装与首次配置](installation.md)，实际操作见[工作流选择](workflows.md)与各使用指南。

## 工作流

| 工作流 | 适合 | 输入 | 结果 |
| --- | --- | --- | --- |
| Clipboard Image | 无需先另存即可使用系统剪贴板图片 | 剪贴板中的静态图片 | Reference Image、Plane、图片节点或笔刷 Texture |
| Mesh Plane | 不需要深度的图片卡片与背景板 | 单图、视频、序列帧 | 带图片材质和 Geometry Nodes 的普通平面 |
| Depth Plane | 快速制作可调节的立体图片 | 单图、视频、序列帧 | 带颜色、深度与 Geometry Nodes 的面片 |
| Surface | 从单张图片恢复透视空间 | 单图 | 相机空间网格、材质与可选匹配相机 |
| Remove Background | 提取透明前景 | 单图、视频、序列帧 | 透明图片或透明序列 |
| Upscale | 在安全输出上限内增加图片像素 | 单图、视频、序列帧 | 三档模型生成的高清图片或序列 |
| Image Mask | 用 Box、Lasso、Line 或 Polyline 直接清理图片 | 静态 Image Empty | 原位更新并 Pack 的透明裁切图 |
| Image Perspective | 四点透视矫正裁切 | 静态 Image Empty | Pack 的矩形裁切图 |
| Cutout | 套索选择区域并生成四种网格形状 | 静态 Image Empty | 带孔洞与原图 UV 的规则三角基础面 |
| Balloon | 沿轮廓绘制鼓起造型 | 静态 Image Empty | 带原图 UV 的封闭网格 |
| Debug | 检查模型原始输出 | 模型支持的图片或帧序列 | 保存在 Job 目录中的原始 Prediction |

Depth Plane 与 Surface 可使用 DA3 或 MoGe-2。DA3 提供相对深度和相机信息；MoGe-2 还提供 metric depth、法线与有效区域。BEN2 为去背景和可选前景处理提供 Alpha。

## Blender 交互

复制图片后，在支持的编辑器中按 `Ctrl+V`（macOS 为 `Cmd+V`）即可粘贴；图片会 Pack 到当前 `.blend`。3D View 的 Object Mode 默认创建 Reference Image，也可在 Redo 面板切换为 Plane；Shader Editor、Compositor 与 Geometry Nodes 创建对应图片节点，Sculpt、Vertex Paint 与 Texture Paint 则设置笔刷 Texture。详见[粘贴剪贴板图片](clipboard-image.md)。

主要功能位于 Image Empty 的 `AnyImage` 右键菜单；AnyImage 使用 prepend 注册，显示在右键菜单最上方。

`Convert to Mesh Plane` 位于 `Convert to Depth Plane` 上方，不需要 AI Environment。它生成基础四边形，并由 `O Mesh Plane` 修改器实时处理 `Thickness` 与 `Subdivide`；`Thickness` 为 `0` 时保持单面。操作会立即执行；创建后可在 Last Operation 中调整 `Shadeless` 与 `Keep Original`。

Cutout 复用 Image Lasso 的反选与 Refine 流程，但自交选区使用非零环绕填充：同方向重叠保留，反方向内环形成孔洞。基础面以均匀六角格点填充平滑约束轮廓，`Point Spacing` 以完整源图像素为单位控制内部密度，不随局部裁切范围重新归一化；短轮廓会自适应边界采样以免有效小区域消失。未启用 Refine 的 Surface 与 Balloon 只按套索建面，不把原图 Alpha 计入几何；同时关闭 `Normal` 时在 Blender 内完成遮罩、轮廓和建面，不启动 BlendJob。套索或 Refine Alpha 以 `0.5` 为几何剔除阈值，并确定紧凑矩形裁剪范围。材质 Color 使用当前 Empty Image 在该范围内的原始像素，不乘选择 Alpha，只保留图片原有 Alpha；MoGe 深度与法线则使用同一裁剪范围的局部分析图，选区内保留当前图片 RGB，范围外 RGBA 置零。Upscale 图片直接使用高清图的所选区域进行材质与 AI 分析。裁剪贴图可以是非正方形，局部平面范围和 UV 会映射回源图对应区域。`Normal` 默认关闭，启用后才用 MoGe-2 写入 normal；Depth Surface 保留 MoGe 原生 object-space 像素，Surface、Balloon 与 Depth Balloon 根据成品网格 TBN 烘成 tangent-space 像素。Depth 类型始终使用 Job 生成深度，但同样由该选项决定是否写入 normal。Refine 启用后由 BEN2 返回裁剪后的最终 Alpha，Blender 再从该 Alpha 建面。详细操作与计算边界见 [Cutout](cutout.md)。

`O Image Depth Surface` 的平滑阶段直接展开 O Essentials `O Smooth` 的 Repeat Zone 与双域边界判断结构，不嵌套组节点；内部固定按 `Pin Sharp = 1`、`Pin Boundary = 1` 计算，不暴露这两个参数，`Iterations` 默认 `1`、最小可设为 `0`。`Depth Continuity` 默认 `0`；Thickness 固定正面，只向背面挤出。

`Depth Plane` 与普通 `Surface` 的推理仍可沿用 Upscale 保存的原图引用；Cutout 四种形状则以当前高清 Image 的所选区域作为 Color、深度和法线输入。

转换任务完成后，AnyImage 在一个 Undo 步骤中创建网格、图片、材质和修改器。源 Image Empty 是否保留由转换选项决定。

Image Box、Lasso、Line 与 Polyline 组成 Mask 工具组，并共用 `EditImageMask`。四者用 `F` 切换反选；`Refine Selection` 只用于 Box / Lasso。

Perspective 是紧随 Mask 工具组之后的独立工具，将任意顺序输入的四个角矫正为指定比例的矩形。结果直接更新当前 Image Empty，并 Pack 到 `.blend`。

操作步骤见 [Image 编辑工具](image-tools.md)；处理管线与模块职责见 [Image 工具技术实现](image-tools-technical.md)。

Cutout 工具从四个方向生成 Surface、Balloon、Depth Balloon 与 Depth Surface。四种结果使用相同的单面基础薄片、局部 YZ 纸面方向和裁切中心原点，并统一写入 `o_balloon` 点属性；Preferences 可在 Poisson 与 Teddy 两种 Balloon Profile 算法之间选择。

四个 Geometry Nodes 修改器都提供默认折叠的 `Options` 面板，并把 `Cleanup` 收纳其中。Depth Balloon 额外把 `Base Plane` 放入 Options；Depth Surface 把 `Depth Continuity` 与 `Smooth` 放入 Options。Depth Balloon 使用 `Depth Scale` 控制相对基面的深度；`Double Sided` 开启后，先让 Base Plane 决定正面的朝向与基线，再把最终正面关于对象局部 YZ 平面完整镜像；Base Plane 不会改变对称中心。

## 动画

Depth Plane、Remove Background 和 Upscale 支持 Movie 与 Image Sequence。它们按 Image Empty 的帧范围处理素材，并生成与场景帧对应的颜色或深度序列。

Blender 无法整体 Pack 图片序列，因此动画结果会继续引用 Job 目录。保存或移动 `.blend` 时，应同时保留这些外部文件。详见[动画与序列帧](animation.md)。

## 运行环境

AI 任务在独立 Python Environment 中通过 ONNX Runtime 执行。Blender 负责界面、任务提交和结果导入，Job Server 负责模型与文件处理。

默认 Storage Root 为 `~/.anyimage`，其中保存 Environment、模型、日志和 Job 结果。连续使用同一模型会复用已加载的 Session；切换到另一模型族时释放旧 Session，使 Server 最多保留当前使用的一套模型。

安装、下载和推理都在后台运行，并通过状态栏提供进度与取消操作。详细设计见[Job Server](server.md)。

## 模型与调试

正式功能使用以下 ONNX 模型：

- MoGe-2 ViT-S、ViT-B、ViT-L Normal
- DA3 Small、DA3 Base
- BEN2 Base
- Real-ESRGAN General WDN x4v3、SAFMN Real x4、Real-ESRGAN x4plus

Upscale 提供 Real-ESRGAN General WDN x4v3、SAFMN Real x4 和 Real-ESRGAN x4plus 三档 4× RGB 模型。默认 WDN 偏速度和保守细节，SAFMN 居中，x4plus 的细节更明显；三者也保留对应 Debug 入口用于模型直通比较。正式功能会独立放大并合并源 Alpha，默认把输出长边限制在 4096 px，可在 Preferences 提高到 8192 px，并始终受约 32 MP 硬上限约束。

首次安装会准备 MoGe-2 ViT-S Normal、BEN2 Base 与 Real-ESRGAN General WDN x4v3，其他模型可从 AnyImage 扩展偏好设置按需下载。

Debug 工作流保存模型 API 的直接返回，适合验证模型、设备与输入。三档高清模型对每张输入保存 `prediction*.png`，不加入降噪强度、Alpha 合成或 Blender 图片写回。三个模型统一由适配层以 256×256、16 像素上下文执行重叠分块，因而都接受任意图片宽高。Depth Plane 和 Surface 则在模型结果之上继续生成 Blender 可用的贴图与几何。文件字段见[输出格式](outputs.md)。