# 功能参考

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

## 工作流

| 工作流 | 适合 | 输入 | 结果 |
| --- | --- | --- | --- |
| Depth Plane | 快速制作可调节的立体图片 | 单图、视频、序列帧 | 带颜色、深度与 Geometry Nodes 的面片 |
| Surface | 从单张图片恢复透视空间 | 单图 | 相机空间网格、材质与可选匹配相机 |
| Remove Background | 提取透明前景 | 单图、视频、序列帧 | 透明图片或透明序列 |
| Balloon | 沿轮廓绘制鼓起造型 | 静态 Image Empty | 带原图 UV 的封闭网格 |
| Debug | 检查模型原始输出 | 模型支持的图片或帧序列 | 保存在 Job 目录中的原始 Prediction |

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

## Blender 交互

主要功能位于 Image Empty 的 `SnapForm` 右键菜单。菜单会显示 Environment 和必需模型的就绪状态，并在缺少内容时提供安装或下载入口。

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

Balloon 默认在 Blender 内部生成，无需 Environment 或模型。Tool Settings 提供模式、厚度、采样距离、材质复用、`Contour`、`Depth` 与 MoGe-2 `Depth Model`。Depth 会把物理距离相对化并稳健拟合初始基面，保留未截断的正负起伏。Base Plane 子 Empty 的旋转定义基面朝向，沿自身局部 Z 移动定义 middle level。

`O Balloon Shape` 计算 `修正厚度 = abs(原 X) × Thickness`，并将修正深度校准为 `(0.5 × 相对基面深度 + 原始 Balloon 最大半厚度) × Depth Strength`。固定的原始半厚度不乘 `Thickness`，因此 Thickness 与 Depth Strength 分别只控制各自分支。节点以归一化原 X 距离经 Smoother Step 得到中心程度，再插值厚度与深度。`Double Sided Depth` 默认关闭，背面保持 Balloon 厚度。MoGe normal 会输出为原图尺寸的 tangent-space 纹理，并通过 `O Balloon Layer` 的 `Normal Strength`（默认 `0.5`）补偿网格无法表达的细节。

新建 Balloon 材质会用 Custom Properties 保存源 Image datablock 和可选 normal Image 的直接引用。`Reuse Material` 优先按这些标记匹配，不依赖材质或节点组名称；普通与 Depth 材质分别复用。Depth Balloon 的共享 normal 会逐次合并新套索的有效区域，避免复用材质时丢失其他套索的法线。

## 动画

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

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

## 运行环境

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

默认 Storage Root 为 `~/.snapform`，其中保存 Environment、模型、日志和 Job 结果。连续任务会复用已加载的模型 Session；DA3 与 MoGe-2 共享一个深度模型缓存位置，BEN2 可同时保留。

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

## 模型与调试

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

- MoGe-2 ViT-S、ViT-B、ViT-L Normal
- DA3 Small、DA3 Base
- BEN2 Base

首次安装会准备 MoGe-2 ViT-S Normal 与 BEN2 Base，其他模型可从 Models 面板按需下载。

Debug 工作流保存模型 API 的直接返回，适合验证模型、设备与输入。Depth Plane 和 Surface 则在模型结果之上继续生成 Blender 可用的贴图与几何。文件字段见[输出格式](outputs.md)。