feat: Introduce Balloon Lasso Tool for mesh extraction

- Added BalloonTool workspace tool to facilitate the extraction of balloon meshes in the 3D viewport.
- Implemented ActivateBalloonTool operator to activate the Balloon Lasso Tool.
- Refactored BalloonLasso operator into ExtractBalloon for better clarity and functionality.
- Enhanced properties for balloon extraction, including mode, thickness, resolution, and material reuse options.
- Updated SnapFormSettings to include new balloon-related properties.
- Improved material and image handling for balloon extraction, ensuring compatibility and reusability.
- Added tests to validate the registration and functionality of the new balloon tools and properties.

docs/depth-plane.md

@@ -1,73 +1,66 @@
 # Depth Plane
 
-本页记录 Depth Plane 的数据、节点和材质实现。日常操作与参数说明请阅读
-[Depth Plane 使用指南](guide-depth-plane.md)。
+Depth Plane 把图片映射为带深度位移的面片，适合快速获得可调节的立体效果。操作方法见[Depth Plane 使用指南](guide-depth-plane.md)。
 
-## Image Empty 转深度面片
+## 数据流
 
-1. 在 3D View 选中 `Object Type = Empty`、`Display As = Image` 的对象。
-2. 右键打开 `SnapForm` 子菜单并选择 `Convert to Depth Plane`，通过 `Depth from` 选择深度来源：
-   - `DA3`：显示 Model 和 Resolution Scale。ONNX 模型使用 camera decoder 恢复相机。Process Res 先以原图长边乘以
-     Resolution Scale，再钳制到 `252–1008`，最后对齐到最接近的 `14` 倍数。Resolution Scale 以百分比
-     显示，范围为 `1–100%`，默认 `100%`；界面只在标签中实时显示最终 Process Res。
-     转换导出 `mini_npz`，使用前需要在
-     `Models` panel 下载所选模型，并固定使用 `process_res_method="upper_bound_resize"`；设备和参考视图策略
-     继续使用场景设置。Model 下拉菜单只列出已经下载的 DA3 模型；若没有可用模型，对话框会引导到
-     `Models` panel 下载。
-   - MoGe-2：使用所选模型输出 metric depth、normal、validity mask 与 normalized intrinsics。Depth Plane 不保存体积较大的 points；Surface 会在 AI 进程内用内置 NumPy 网格构建生成 mesh.npz。Debug 则逐帧保存 API 直接返回的 points、depth、normal、mask 与 intrinsics，不生成网格或预览。
-   - `Original`：直接把原图作为深度贴图，不显示估算参数。仅在开启 `Remove Background` 时运行 BEN2
-      取得前景 Alpha；视频或序列帧按需同时抽取原始帧与前景序列，把原始帧作为 `.depth` 序列。
-   `MoGe-2 ViT-S` 是默认深度来源。选择 `DA3` 时，其 Model 与 Resolution Scale
-   参数会集中显示在独立边框中。`Remove Background` 与 `Shadeless` 直接显示，不再使用 Options 折叠；
-   `Keep Original` 默认关闭，并在分割线下方保持为最后一项。仅当开启 `Remove Background` 时才需要
-   `BEN2 Base`，并把 `.color` 的 Alpha 作为独立 Mask，不在 Server 中改写深度值。无论颜色层是直接
-   复制原图，还是由 BEN2 为单图或序列修改 Alpha，Server 都统一写为 `color.0001.*`；Blender 只导入
-   这一份 `.color`，不复用源 Empty 的 Image。颜色贴图会按当前场景的 View Transform 选择对应输入色彩空间：AgX、ACES 1.3、ACES 2.0、Filmic、Khronos PBR Neutral 分别使用 `AgX Base sRGB`、`ACES 1.3 sRGB`、`ACES 2.0 sRGB`、`Filmic sRGB`、`Khronos PBR Neutral sRGB`；无法匹配当前 View Transform 时回退 `sRGB`。
-    Image Empty 引用视频或序列帧时，DA3 与 MoGe-2 会按 Empty 的 Image Frames 数值逐帧估计
-    深度（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset，与背景蒙版范围一致；
-    DA3 会复用同一个 ONNX Session 对每帧独立推理，再合并为原有序列输出，避免多帧 Attention 的平方级显存占用。
-    DA3 与 MoGe-2 均先用未经抠图的原始 RGB 生成深度，再运行可选 BEN2；BEN2 Alpha 只参与最终输出过滤和材质 Mask。
-    该行为只用于 Depth Plane 转换；Surface 仅支持单张图片。Debug 中 DA3 多帧输入联合推理，
-    MoGe-2 与 BEN2 按单图 API 逐帧运行。
-    Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty
-    一致；Original 模式的视频或序列帧使用 `color.0001.*` 颜色层同时作为颜色与深度输入；开启
-    Remove Background 时同名颜色层包含 BEN2 修改后的 Alpha。
-    DA3 动画深度以 EXR 序列帧（`depth.0001.exr` 起）保存在 Job 目录根下；MoGe-2 动画只为置换数据创建 `moge_depth.0001.exr` 起的 EXR 序列。MoGe-2 的 `results.npz` 保留完整 depth、normal 与 mask 数组，Server 另外输出对应 PNG 预览。
-   DA3 与 MoGe-2 的单帧推理进度只显示模型与阶段名称，不追加 `1/1`；多帧时继续显示当前帧与总数。`Shadeless`、`Remove Background` 与 `Keep Original` 均默认关闭，因此默认删除原对象。`Shadeless` 会以 `O Shadeless` 节点组替代普通 Principled BSDF 路径，并继续通过 Alpha 与 Transparent BSDF 混合。
-3. DA3 或 MoGe-2 完成后会自动创建面片。DA3 面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
-   Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
-   的可见尺寸、Offset 与 Transform。DA3 会把用于匹配画面尺寸的缩放预乘到 `.depth` 数值，
-   XY 缩放烘焙到 Mesh，Z 不参与平面匹配；最终对象 Scale 为 `(1, 1, 1)`，视觉深度与旧逻辑一致。
-   关闭 `Keep Original` 时，成功生成后删除源 Empty。生成面片 Object 使用源 Empty 的原名；开启
-   `Keep Original` 时不处理
-   同名冲突，由 Blender 自动为生成面片追加编号。
-4. Blender 只创建保留图像纵横比的最低密度基础网格，再把 `O DA3 Depth Plane` 作为 Geometry Nodes
-   修改器添加到对象。节点组与 `O DA3 Surface` 一同保存在 `O_SnapForm.blend`，关闭
-   `show_group_selector`，不为每个对象复制节点组。MoGe-2 使用单独的 `O MoGe2 Depth Plane`，处理
-   网格细分、metric depth 位移和材质设置；材质使用 `O MoGe2 Depth Plane Layer`，直接接入模型 normal。
-   `O MoGe2 Depth Plane` 与 DA3 一样通过隐藏的 Color Image 读取 `.color` Alpha，以 `Alpha > 0.5`
-   划分前景范围，并在范围外改用 `Background Depth`。两个修改器公开以下参数：
-   - `Displacement`：位于 Geometry 之后的第一项，菜单包含 `Geometry`（默认）与 `Material`。`Geometry`
-     在节点组内沿法线修改网格，`Material` 保持网格平面并启用材质置换；
-   - `Subdivision`：位于第二项，默认 `5`。节点读取基础平面的 Bounding Box，短边分段数为 `2^Subdivision`，
-     长边按宽高比计算并四舍五入；例如 16:9 图片在等级 `5` 时生成 `57×32` 个面；
-   - `Background Depth`：默认 `-1`，允许正负值，Structure Type 为 `Single`，直接显示且不再放在 Panel 中。前景 Mask 外的结构或
-     材质置换使用该值；是否存在背景只取决于转换所得色彩贴图的 `Alpha > 0.5` 二值结果；
-   - `Depth Scale`：默认 `1`，允许正负值，Structure Type 为 `Single`，同时控制 Geometry 与 Material
-     两条置换路径。
-   Grid 重建后通过隐藏的 Material 输入重新赋予转换材质，并对所有面执行 Shade Smooth。
-   材质使用显式指向 `UVMap` 的 UV Map 节点连接颜色、前景 Mask 与深度 Image Texture，不依赖活动 UV。
-   前景深度先与 `Background Depth` 取 Maximum，再按色彩贴图 Alpha 与背景深度混合，
-   深度分支在混合前使用 `Alpha > 0.5` 转为二值 Mask，避免半透明前景被背景深度拉扯；
-   材质表面 Alpha 同样使用二值 Mask。材质置换使用相同的二值和钳制顺序。
-   节点组还会把 `o_material_displacement` 与 `o_background_depth` 写入点域，材质通过
-   `Geometry` 类型的 Attribute 节点读取。点域会为顶点保存重复值，但能在应用修改器后继续保留参数；
-   相比自适应网格本身，其占用很小。Depth Image 与 Color Image 是修改器隐藏数据输入，
-   由导入流程自动设置。
-   `.color` 与 `.depth` 的 Blender Image 类型只依据源 Empty Image：普通单图使用 `IMAGE`，Movie 或 Sequence 使用 `SEQUENCE`；即使动画源这次只处理一帧也仍为 `SEQUENCE`，不按输出文件数量推断。视频与序列帧还会为 Depth 与 Color 共同写入隐藏的 `Frame`、`Frame Start`、`Frames` 与 `Cyclic`。
-   节点组内部不再使用 Scene Time。只有原 Image Empty 是视频或序列时，导入流程才直接给修改器的 `Frame`
-   socket 添加 Scripted Expression Driver `frame`；静态图保持默认值 `1`，不创建 Driver。导入内容已经
-   是截取后的帧，因此 Offset 在节点组内恒定为 `0`。
-   节点组根据 `Frame` 计算从 `1` 开始的 Image Texture Frame：场景帧与 Start 都为 `1` 时读取图片第 `1` 帧；非循环输入
-   钳制到有效范围；循环输入使用 Floored Modulo，让 `Frame Start` 前后的负、正相对帧都映射到
-   `1…Frames`，因此开始帧之前也会循环播放。Geometry 置换会像材质 Image Texture 一样随场景帧刷新。
+```mermaid
+flowchart LR
+    Input["Image Empty"] --> Depth{"深度来源"}
+    Depth --> DA3["DA3"]
+    Depth --> MoGe["MoGe-2"]
+    Depth --> Original["Original"]
+    DA3 --> Layers["颜色层 + 深度层"]
+    MoGe --> Layers
+    Original --> Layers
+    Layers --> Import["Blender 导入"]
+    Import --> Mesh["基础面片"]
+    Import --> Nodes["Geometry Nodes"]
+    Import --> Material["材质"]
+```
+
+Server 为每帧准备颜色、深度和可选前景 Alpha。Blender 导入这些数据，创建基础面片，并用 Geometry Nodes 与材质分别完成几何位移和表面细节。
+
+## 深度来源
+
+| 来源 | 深度含义 | 额外数据 | 适合 |
+| --- | --- | --- | --- |
+| DA3 | 相对深度 | 相机内参与置信度 | 通用单图与动画 |
+| MoGe-2 | Metric depth | 法线、Mask、相机内参 | 更稳定的尺度与表面法线 |
+| Original | 原图亮度 | 可选 BEN2 Alpha | 已准备好高度图的素材 |
+
+DA3 和 MoGe-2 都以未经抠图的 RGB 估计深度。启用 Remove Background 后，BEN2 Alpha 用于颜色透明度和前景 Mask，深度本身保持模型输出。
+
+视频与序列帧逐帧推理并复用同一个模型 Session，因此显存主要由单帧分辨率决定。DA3 Debug 的多帧联合推理属于另一条工作流。
+
+## Blender 结果
+
+转换会创建以下数据：
+
+- 与源 Image Empty 对齐的面片
+- `.depth` 与 `.color` Image datablock
+- 使用 `O DA3 Depth Plane` 或 `O MoGe2 Depth Plane` 的 Geometry Nodes 修改器
+- 连接颜色、Alpha、Bump 与材质位移的材质
+
+Geometry Nodes 提供深度范围、细分、重拓扑、平滑、背景深度和位移强度等控制。深度 Mask 在几何和材质路径中使用相同阈值，以保持轮廓一致。
+
+材质与图片名称以源 Image datablock 为基名。对象 Transform、显示尺寸和 Offset 会转换为面片的空间位置与比例。
+
+## 单图与动画文件
+
+单图深度使用 OpenEXR Pack 到 `.blend`，以保留浮点范围。Packed Image 会先导出临时输入，任务结束后清理，源 Image 保持不变。
+
+动画使用 Job 目录中的外部序列：
+
+```text
+<job-id>/
+├── color.0001.jpg/png
+├── depth.0001.exr
+└── results.npz
+```
+
+MoGe-2 动画的深度序列使用 `moge_depth.0001.exr`。这些文件是 `.blend` 的运行时依赖，详见[动画与序列帧](animation.md)。
+
+## 适用范围
+
+Depth Plane 是固定平面上的深度位移，不是完整的逐像素 camera-space 重建。它强调可编辑性和动画支持；需要透视网格时使用 [Surface](surface.md)。

docs/development.md

@@ -2,94 +2,64 @@
 
 ## 程序设计
 
-SnapForm 分成 Blender 主进程与独立 Job Server 两侧。Blender 侧只负责界面、任务参数和 `.blend` 数据修改；模型下载、媒体准备、ONNX 推理和文件输出都在 Python 3.12 Environment 中运行。两侧由随扩展分发的 BlendJob wheel 连接，避免把 FastAPI、ONNX Runtime 等计算依赖载入 Blender Python。
+SnapForm 分为 Blender 交互层、BlendJob Runtime 和 Job Server 计算层。
 
 ```mermaid
 flowchart LR
-    User["Image Empty / Debug Panel"] --> Operator["Blender Operator"]
+    UI["菜单 / Panel"] --> Operator["Feature Operator"]
     Operator --> Runtime["JobRuntime"]
-    Runtime --> Server["JobServer FIFO Queue"]
-    Server --> Handler["SnapForm Job Handler"]
-    Handler --> Model["ModelManager / ONNX"]
-    Handler --> JobFiles["Job Directory"]
-    JobFiles --> Response["Operator response"]
+    Runtime --> Job["Server Job"]
+    Job --> Files["Job Directory"]
+    Files --> Response["Operator Response"]
     Response --> Scene["Blender Scene"]
 ```
 
-核心边界如下：
+Blender 交互层管理 UI、RNA 状态、任务参数和结果导入。Runtime 管理 Environment、Server、队列、进度与取消。Server Job 组合媒体、模型、几何和输出模块。完整运行设计见 [Job Server](server.md)。
 
-- `src/snapform/__init__.py` 是注册入口，集中注册 Blender 类型、`Scene.snapform_settings`、右键菜单与 Runtime
-- `menu.py` 与 `panel.py` 是同级 Blender UI 入口；`preferences.py`、`properties.py` 分别保存插件配置和 RNA 状态，它们都不直接导入 Server 模型实现
-- `runtime.py` 创建唯一 `JobRuntime`，配置 Environment、Storage Root、Server 入口与首次安装后的推荐模型下载
-- `operators/` 按功能组织 Blender 操作。Depth Plane、Surface、Background 与 Balloon 各自包含入口 Operator、Job 请求和结果回写，不设置跨功能的 `results.py`
-- `operators/common.py` 只保留跨 Job Operator 共用的参数校验、模型就绪检查、临时输入清理和请求参数构造；`operators/image.py` 与 `operators/material.py` 提供各功能 Operator 共用的 Image Empty、序列和材质操作，三者同层但不互相混合职责
-- `operators/models.py` 与 `operators/debug.py` 分别承载模型管理和 Debug 操作
-- `operators/balloon/` 以持续 `BalloonLasso` 控制器分发单次、可独立 Redo/Undo 的 `ExtractBalloon`；`geometry.py` 负责共用拓扑，`poisson.py` 与 `teddy.py` 分别计算两种厚度场
-- `operators/depth_plane/` 将转换入口、Job 请求、响应回写、深度数据和网格构建收拢在同一功能包；`operators/surface.py` 与 `operators/background.py` 采用相同的功能内聚原则
-- `server/__init__.py` 创建 `JobServer`、注册公开 Job，并把 `ModelManager` 注册为 Resource
-- `server/jobs/` 按任务组织完整流程；DA3、MoGe-2、BEN2 Debug 各自拥有独立模块和 Job，不用模型分支总控函数
-- `server/models/` 包含三个模型适配器及其 ONNX 实现，只负责模型载入、推理和 Prediction；不接收 Job Context、不写文件
-- `server/geometry/` 包含投影、像素网格和唯一 Surface Builder，均为纯数据转换；不负责 Debug 或文件输出
-- `server/outputs/` 只负责 Depth、Surface 与各模型 Debug 的序列化；Debug writer 原样保存 API 字段，不构建派生几何
-- `server/media/input.py` 只处理图片、序列和视频输入；共享的可选前景流程保留在 `jobs/foreground.py`
-- 根目录 `model_catalog.py` 供 Blender UI 与本地就绪检查使用；`server/model_catalog.py` 独立声明下载与推理所需模型，二者的模型键、目录名和 `ready_patterns` 由测试约束一致
-- `server/__init__.py` 只注册 Job 与 Resource；`jobs/background.py`、`jobs/frames.py` 分别实现去背景和帧提取
-- 所有任务产物写入 Runtime 分配的 opaque-ID Job 目录
+### 代码组织
 
-功能细节继续按主题维护：[Depth Plane](depth-plane.md)、[Surface](surface.md)、[输出格式](outputs.md) 和 [Job Server](server.md)。
+| 位置 | 内容 |
+| --- | --- |
+| `__init__.py` | Blender 类型、菜单与 Runtime 注册 |
+| `menu.py`、`panel.py` | 用户入口 |
+| `preferences.py`、`properties.py` | 扩展配置与 Scene 状态 |
+| `runtime.py` | JobRuntime 配置 |
+| `operators/` | Blender 功能与结果导入 |
+| `server/jobs/` | Server 工作流 |
+| `server/models/` | ONNX 模型适配 |
+| `server/geometry/` | 纯数据几何处理 |
+| `server/outputs/` | 文件序列化 |
+| `server/media/` | 媒体输入 |
+| `assets/O_SnapForm.blend` | Geometry Nodes 与材质资产 |
+
+Depth Plane、Surface、Background 和 Balloon 按功能组织。一个功能的入口、请求和 Blender 回写放在一起；跨功能的图片、材质和参数处理放在 `operators/common.py`、`operators/image.py` 与 `operators/material.py`。
+
+Server 的模型模块返回 Prediction，几何模块处理数组与网格，输出模块写文件。Blender 数据只在 Operator Response 的主线程阶段创建。
 
 ## 项目结构
 
 ```text
 .
-├── AGENTS.md
 ├── README.md
+├── docs/
 ├── pack.py
 ├── sync_models.py
-├── docs/
-├── src/
-│   └── snapform/
-│       ├── __init__.py
-│       ├── blender_manifest.toml
-│       ├── runtime.py
-│       ├── menu.py
-│       ├── panel.py
-│       ├── preferences.py
-│       ├── properties.py
-│       ├── model_catalog.py
-│       ├── assets/
-│       │   └── O_SnapForm.blend
-│       ├── operators/
-│       │   ├── common.py
-│       │   ├── image.py
-│       │   ├── material.py
-│       │   ├── models.py
-│       │   ├── debug.py
-│       │   ├── background.py
-│       │   ├── surface.py
-│       │   ├── depth_plane/
-│       │   │   ├── operator.py
-│       │   │   ├── data.py
-│       │   │   └── build.py
-│       │   └── balloon/
-│       │       ├── operator.py
-│       │       ├── geometry.py
-│       │       ├── poisson.py
-│       │       └── teddy.py
-│       ├── server/
-│       │   ├── __init__.py
-│       │   ├── jobs/
-│       │   ├── geometry/
-│       │   ├── media/
-│       │   ├── models/
-│       │   └── outputs/
-│       └── wheels/
-│           └── blendjob-*.whl
+├── src/snapform/
+│   ├── blender_manifest.toml
+│   ├── runtime.py
+│   ├── menu.py
+│   ├── panel.py
+│   ├── preferences.py
+│   ├── properties.py
+│   ├── operators/
+│   ├── server/
+│   ├── assets/
+│   └── wheels/
 ├── tests/
 └── tools/
 ```
 
-## 常见命令
+## 开发命令
 
 在项目根目录使用 Git Bash：
 
@@ -100,51 +70,35 @@ uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
 uv run python pack.py
 ```
 
-`.github/workflows/test.yml` 在 `main` push、Pull Request 与手动触发时使用 Python 3.11 和锁定依赖运行完整测试。`.github/workflows/build.yml` 只响应 `v*` tag，在再次通过完整测试后运行 `pack.py`，并把生成的 ZIP 上传到该 tag 对应的 Gitea Release。`pack.py` 从 `pyproject.toml` 的默认 `dependencies` 读取 Extension wheel 需求，按 Manifest 平台从 PyPI 下载 wheel，并把各平台对应的 wheel 列入包内 Manifest；`src/snapform/wheels/` 只保留本地资产，不作为 uv source。`.github/workflows/docs.yml` 在 `main` 的文档内容、MkDocs 配置或自身 Workflow 变化时部署，也可手动触发；它只使用 `docs` 依赖组，因此不安装默认依赖。Server Environment 与测试依赖声明在 `dev` 组，文档工具声明在 `docs` 组；新增依赖后应更新锁文件，不要在 Workflow 中另行维护下载清单。
+`pack.py` 为 Windows x64、macOS Apple Silicon 与 Linux x64 构建扩展 ZIP 到 `dist/`。依赖、wheel 或 Manifest 改变后，应同步检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 与打包测试。
 
-本地预览用户文档：
+CI 分为三条流程：
+
+- `test.yml`：在 push、Pull Request 与手动触发时运行测试
+- `build.yml`：响应 `v*` tag，测试后构建并上传 Release
+- `docs.yml`：文档变化后构建并部署站点
+
+## 文档
+
+本地预览和严格构建：
 
 ```bash
-uv run mkdocs serve
+uv run --only-group docs mkdocs serve
+uv run --only-group docs mkdocs build
 ```
 
-构建静态文档或使用 Mike 发布版本化文档：
+版本化发布可使用 Mike：
 
 ```bash
-uv run mkdocs build
-uv run mike deploy <version> -p
-uv run mike set-default <version> -p
+uv run --only-group docs mike deploy <version> -p
+uv run --only-group docs mike set-default <version> -p
 ```
 
-### 文档部署
-
-`.github/workflows/docs.yml` 在 `main` 分支的文档相关文件变化后运行，也可从 Gitea Actions 手动触发。工作流使用锁定的 Python 依赖严格构建 `site/`，将其放入与站点 URL 对应的 `public/snapform/`，再通过 Wrangler 部署为 Cloudflare Workers Static Assets。
-
-在 Gitea 仓库的 **Settings > Actions** 中配置：
-
-- Secret `CLOUDFLARE_ACCOUNT_ID`：Cloudflare Account ID
-- Secret `CLOUDFLARE_API_TOKEN`：限制到目标账号的 Cloudflare API Token，使用 **Edit Cloudflare Workers** 模板
-- Variable `CLOUDFLARE_WORKER_NAME`：承载文档的 Worker 名称
-
-API Token 不写入仓库。Workflow 只在 `main` 上部署生产文档，不在 Pull Request 中读取 Cloudflare Secret。
-
-目标 Worker 必须专门用于 SnapForm，并把 `docs.omoolab.xyz/snapform/*` 路由到该 Worker。每次 Wrangler 部署都会更新目标 Worker 的整套静态资源；如果一个 Worker 同时承载多个项目，应改由中央文档仓库聚合全部站点后统一部署，不能从各项目仓库分别覆盖它。
-
-
-Mike 不依赖 GitHub API；`mike deploy --branch <branch> --push` 也可以向 Gitea 保存版本化静态站点。当前自动部署先发布 `mkdocs build` 生成的单版本站点，等确定版本 URL 规则后再启用 Mike 分支，避免在 Cloudflare 上提前固化不合适的路径结构。
-
-
-
-`pack.py` 根据 `blender_manifest.toml` 分别生成 Windows、macOS 和 Linux 扩展包，例如 `dist/SnapForm.v0.12.14.windows-x64.zip`。更换 `src/snapform/wheels/` 中随扩展分发的 wheel 后，先刷新锁文件再测试：
-
-```bash
-uv lock --refresh
-uv run pytest
-```
+自动部署将 MkDocs 站点发布到专用 Cloudflare Worker。仓库需要配置 `CLOUDFLARE_ACCOUNT_ID`、`CLOUDFLARE_API_TOKEN` 和 `CLOUDFLARE_WORKER_NAME`。Worker 路由对应 `docs.omoolab.xyz/snapform/*`。
 
 ## 资产构建与验证
 
-`tools/` 脚本依赖 `bpy`，必须由 Blender 执行。设置本机 Blender 可执行文件后，可以重建或验证 `O_SnapForm.blend`：
+`tools/` 中的资产脚本依赖 `bpy`，应由 Blender 执行：
 
 ```bash
 BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
@@ -156,14 +110,11 @@ BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
 "$BLENDER_BIN" --background --python tools/validate_moge_surface.py
 ```
 
-验证脚本会自动把 `src/snapform/wheels/` 中的 BlendJob wheel 加入 Blender Python 路径，因此可在
-`--factory-startup` 的干净环境中直接运行。
-
-只改 Python、文档或打包逻辑时不需要重建 `.blend` 资产；修改节点组、材质组或其接口时，应运行相应资产验证脚本，并再次运行完整测试。
+修改节点组、材质组或资产接口后，运行对应验证脚本和完整测试。Python、文档或打包逻辑变化无需重建 `.blend` 资产。
 
 ## 上游与许可证
 
 - Depth Anything 3 代码采用 Apache 2.0
 - BEN2 ONNX 模型采用其仓库声明的 Apache 2.0 License
 - SnapForm Extension 代码采用 GPL-3.0-or-later
-- 模型权重许可证由所选 Hugging Face 模型仓库决定，Extension 下载前会在界面显示
+- 模型权重许可证由所选 Hugging Face 模型仓库决定

docs/features.md

@@ -1,120 +1,49 @@
 # 功能参考
 
-本页记录完整功能行为和实现边界，主要供开发、测试与故障排查使用。第一次使用 SnapForm 时，请从
-[安装与首次配置](installation.md)或[五分钟上手](quick-start.md)开始。
+本页概览 SnapForm 的能力。安装步骤见[安装与首次配置](installation.md)，实际操作见[工作流选择](workflows.md)与各使用指南。
 
-`SnapForm` 是一套从图片快速构建空间结构的 Blender Extension。目前以
-[Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
-作为首个 AI 能力，在独立 Environment 中运行 DA3，可将模型 API Prediction 保存在独立 job 目录，
-也可把 Image Empty 转换成带几何与材质置换的立体面片。MoGe-2 作为独立深度来源，保留其 metric depth、normal、mask 与 intrinsics 输出，不复用 DA3 Prediction 后处理。Debug 面板还可运行
-[BEN2](https://github.com/PramaLLC/BEN2) 背景剔除功能测试。
+## 工作流
 
-## 当前功能
+| 工作流 | 适合 | 输入 | 结果 |
+| --- | --- | --- | --- |
+| Depth Plane | 快速制作可调节的立体图片 | 单图、视频、序列帧 | 带颜色、深度与 Geometry Nodes 的面片 |
+| Surface | 从单张图片恢复透视空间 | 单图 | 相机空间网格、材质与可选匹配相机 |
+| Remove Background | 提取透明前景 | 单图、视频、序列帧 | 透明图片或透明序列 |
+| Balloon | 沿轮廓绘制鼓起造型 | 静态 Image Empty | 带原图 UV 的封闭网格 |
+| Debug | 检查模型原始输出 | 模型支持的图片或帧序列 | 保存在 Job 目录中的原始 Prediction |
 
-- 使用 Blender Extension manifest，可通过 `Install from Disk` 安装
-- 在独立 Environment 中通过常驻 Server 运行 ONNX Runtime；MoGe-2、DA3 与 BEN2 的模型执行及后处理完全不使用 PyTorch，避免污染 Blender Python 进程
-- Server 的深度模型缓存只保留 DA3 或 MoGe-2 其中一个，切换时主动释放前一个；BEN2 使用独立缓存，
-  可与当前深度模型共存
-- Blender 使用内置 `urllib.request` 访问仅监听 `127.0.0.1` 的 Server；连接由随机端口与 Instance ID 归属当前 Runtime
-- 常驻 Server 复用 ONNX Runtime session、BEN2 与最近使用的深度模型，连续执行时不再重复加载
-- 每个 Blender 实例持有自己的 Job Server；`Job Server` 面板显示状态与模型缓存，并提供安装、启动、清理、重启和停止控制
-- Environment、模型和任务结果默认保存在 `~/.snapform`，可由多个 Blender 版本共享
-- 当前仅启用 FP32 DA3 Small 和 Base；它们不随首次安装下载，Giant 1.1 与 Nested Giant Large 1.1 暂停使用
-- 支持 BEN2 Base 单图背景剔除测试，输出透明 PNG 与推理耗时
-- 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
-- 视频按顺序截取前若干帧，可设置参与重建的最大帧数
-- `Models` panel 默认折叠，展开后可逐项查看和下载所有可用模型
-- Environment 已安装时不额外占用面板空间；模型列表每个模型只占一行
-- `Debug` 默认折叠，内部的 `DA3`、`MoGe-2` 与 `BEN2` 也分别默认折叠
-- DA3、MoGe-2 与 BEN2 分别使用独立 Debug Job，直接保存各自 API 返回，不共享按模型分支的总控函数
-- DA3 Debug 保存 Prediction NPZ；MoGe-2 Debug 保存逐帧原始预测 NPZ；BEN2 Debug 保存直接返回的透明前景
-- Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
-  `(Missing)`，已下载模型保持原名
-- Debug 不运行点云、Surface、深度预览、置信度 percentile 或坐标变换等 SnapForm 后处理
-- Image Empty 右键菜单提供单一 Balloon 套索提取，并可在 Last Operation 中切换 Poisson 与 Teddy / Chordal Axis Mode；无需 Environment 或模型，源 Empty 保留
-- Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
-- Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
-- 缺少必需的 `MoGe-2 ViT-S Normal` 或 `BEN2 Base` 时，Image Empty 的 `SnapForm`
-  右键子菜单显示 `Download Required Models`；单次任务只下载缺失项，并在补齐前禁用
-  `Convert to Depth Plane`、`Convert to Surface` 和 `Remove Background`。Environment 未安装时，
-  同一位置改为显示 `Install Environment` 与 `Install Environment (Mirror)`，三个禁用的功能入口仍然可见
-- 菜单、模型面板和转换对话框直接检查 Storage Root 的 `models/` 必需文件，显示模型状态时不会启动 Job Server
-- Image Empty 支持视频与序列帧输入：`Convert to Depth Plane` 逐帧估计深度，
-  `Remove Background` 逐帧抠图，入口保持不变。DA3 转换时每帧独立执行 ONNX 推理并复用模型 Session；
-  DA3 Debug 多帧任务继续联合推理；MoGe-2 与 BEN2 Debug 按单图 API 逐帧运行
-- 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）；
-  Geometry Nodes 与材质 Image Texture 均可按场景帧播放序列帧
-- 使用浮点深度贴图、`O DA3 Depth Plane` Geometry Nodes 和原图 Bump 构建立体面片
-- 转换对话框选择推理模式、处理分辨率与背景移除；细分和置换方式在 Geometry Nodes 修改器中调整
-- Debug 的 DA3 输出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不修改当前场景
-- Debug 完整保留模型 API 返回的数组字段，不混入 SnapForm 派生几何
-- 安装和模型下载使用后台子进程；推理提交给常驻 Server，状态栏实时显示阶段、百分比进度条与取消按钮
-- 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复
+Depth Plane 与 Surface 可使用 DA3 或 MoGe-2。DA3 提供相对深度和相机信息；MoGe-2 还提供 metric depth、法线与有效区域。BEN2 为去背景和可选前景处理提供 Alpha。
 
-## 使用
+## Blender 交互
 
-1. 运行 `uv run python pack.py`，分别构建 `windows-x64`、`macos-arm64`、
-   `linux-x64` 三个平台的 Extension ZIP（如 `SnapForm.v0.12.17.macos-arm64.zip`）。
-   安装包不携带 uv 或 AI 项目源码；首次安装 Environment 时下载固定版本 uv，并校验固定 SHA-256。官方安装按钮使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像按钮使用 CNB uv Release、CNB Python 解释器镜像和清华 PyPI。
-2. 在 Blender 的 `Preferences > Extensions` 中选择 `Install from Disk`。
-3. 在 Extension Preferences 中确认 Storage Root 与 Device。Device 是正式功能
-   （Image Empty 右键菜单）使用的推理设备。Windows 默认取 DirectML，否则 CPU；Apple M4 或更新芯片列出 MPS/CoreML 与 CPU，Intel、M1–M3 和无法识别的 Mac 只列出 CPU。
-4. 在 `Job Server` 选择 `Install Environment` 或 `Install Environment (Mirror)`。首次安装会下载 Python、ONNX Runtime、FastAPI、Uvicorn；
-   uv 由 Job Runtime 的 Environment 安装器下载并校验，DA3、BEN2 与 MoGe 不安装源码包，
-   并在 Environment 安装后自动下载 `MoGe-2 ViT-S Normal` 和 FP16 `BEN2 Base` 推荐模型。首次安装
-   Environment Bootstrap 的 0–100% 只包含 uv、Python 与 packages：三阶段显示 `1/3`、`2/3`、`3/3`，范围分别为 1–20%、20–50%、50–98%，最终验证使用 98–100%。下载占各阶段的 84–87%；开始与验证不显示编号，单阶段状态不显示 `1/1`。
-   两个默认模型由普通的 `post_install(runtime)` 发起正式 Server Job。
-   安装完成后直接写入 Environment Manifest，不再额外导入全部组件进行验证；`DA3 Base` 等其他模型可稍后在 `Models` 面板按需下载。
-   Environment packages 使用固定的 Resolving、Downloading 与 Installing 状态，原始 uv 输出写入 `install.log`。模型下载显示速度，例如
-   `Downloading DA3 Small 14.2 MB/s`；镜像来源显示为
-   `Downloading DA3 Small (mirror) 14.2 MB/s`。下载按字节连续推进，重试或切换镜像时进度不会倒退。
-   Environment 安装阶段与 `Models` 面板单独下载使用相同的模型名称格式，不会改写为通用的 `Downloading packages`。
-   Environment 安装后即使模型下载中断也仍会保留，但 `Install Environment` 会以失败结束并显示模型下载错误。
-   可稍后在 Image Empty 的 `SnapForm` 右键菜单用 `Download Required Models` 一次补齐缺失的
-   MoGe-2 ViT-S 与 BEN2，也可在 `Models` 面板单独补下。
-   安装不做启动网络预检；每个模型都先尝试 Hugging Face，失败后尝试 OmooLab R2，两者都失败时当前 Job 失败。
-   官方安装固定使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像安装固定使用 CNB uv Release、`python-build-standalone` 镜像和清华 PyPI。两种方式都不测速、不竞速、不自动切换，镜像配置只注入当前安装子进程。模型仍按自身的 Hugging Face 与 OmooLab R2 逻辑下载。
-5. 在 3D View 按 `N`，打开 `SnapForm` 页签。
-6. 如需其他模型，展开 `Models` panel，找到模型并点击该行的 `Download`。
-7. 展开默认收起的 `Debug`，在 DA3、MoGe-2 或 BEN2 区域选择模型与输入，然后直接运行对应 API。
-8. 选择一张图片或一个视频文件。视频可设置从头截取的帧数，然后点击 `Generate Output`。
-9. 测试背景剔除时，确认 `Models` panel 中的 `BEN2 Base` 已就绪，然后在 `Debug` 的
-   `BEN2` 区域选择单张图片并点击 `Remove Background`。
-   完成后会打开 job 文件夹，其中的 `foreground.png` 带透明 Alpha；状态栏显示
-   BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。
+主要功能位于 Image Empty 的 `SnapForm` 右键菜单。菜单会显示 Environment 和必需模型的就绪状态，并在缺少内容时提供安装或下载入口。
 
-## Extract Balloon
+转换任务完成后，SnapForm 在一个 Undo 步骤中创建网格、图片、材质和修改器。源 Image Empty 是否保留由转换选项决定。
 
-`Balloon Mesh (Lasso)` 是纯 Blender 侧入口，不提交 Job，也不调用 BEN2、深度模型或其他 AI，仅支持静态 Image Empty。它启动不进入 Undo/Redo 历史的持续 `BalloonLasso` 控制器；按住左键绘制套索，松开时控制器调用一次独立的 `ExtractBalloon` Operator 并立即完成，随后继续等待下一次圈选。`Esc` 结束控制器，右键只清除当前未完成轨迹。屏幕轨迹通过视图射线与 Empty 图片平面求交，再结合图片宽高比、Display Size、Image Offset 与 Object Transform 映射为原图像素坐标。
+Balloon 是 Blender 内部工具，无需 Environment 或模型。它支持连续绘制，每次 Stroke 都生成一个可单独 Undo/Redo 的结果。Tool Settings 提供模式、厚度、采样距离与材质复用设置。
 
-Operator 的 `Mode` 保留两种厚度算法：
+## 动画
 
-- `Poisson` 在共用二维网格上组装 cotangent Laplacian 与面积载荷，求解零边界 Poisson 场；高度取场值平方根并按 `Thickness` 缩放
-- `Teddy / Chordal Axis` 依据 [Teddy: A Sketching Interface for 3D Freeform Design](https://www.cs.princeton.edu/courses/archive/fall00/cs597b/papers/teddy-siggraph99.pdf) 的思路，仅对平滑轮廓做约束 Delaunay，形成袖段、分叉和端点轴，并用轴半径生成局部圆/椭圆式截面。当前实现将厚度场映射到共用均匀网格，并非逐面复刻论文的专用缝合拓扑
+Depth Plane 和 Remove Background 支持 Movie 与 Image Sequence。它们按 Image Empty 的帧范围处理素材，并生成与场景帧对应的颜色或深度序列。
 
-每次释放都会把该次套索、源对象名称和启动时的完整 Matrix World 传给一个带 `REGISTER`、`UNDO` 的 `ExtractBalloon`。它完成后立即成为 Last Operation，即使持续 Lasso 仍在运行，也可在左下角修改当前结果的 `Mode`、`Thickness` 和 `Resolution`；每次提取分别拥有 Undo 步骤。重建后会重新把源 Image Empty 设为选中和 Active，便于继续圈选，结果也不会跳回原点。Modal 对中键、滚轮、触控板、NDOF、Alt+左键、HUD 和其他未处理事件返回 `PASS_THROUGH`，所以持续状态不阻断 3D View 导航或参数面板交互。`Thickness` 默认 `1.0`、软上限 `5.0` 且无硬上限。`Resolution` 是 subtype 为 `DISTANCE` 的长度属性，直接表示相邻采样点的目标世界空间距离，默认 `0.1 Blender unit`；数值越小网格越密，不再使用密度倍率换算。
+Blender 无法整体 Pack 图片序列，因此动画结果会继续引用 Job 目录。保存或移动 `.blend` 时，应同时保留这些外部文件。详见[动画与序列帧](animation.md)。
 
-两种模式共用轮廓平滑、按弧长等距重采样和二维约束 Delaunay。边界与内部点以 `Resolution` 的世界距离采样，不随图片分辨率、Display Size 或对象 Scale 改变目标间距。前后表面在同一条零厚度边缘共享顶点，不生成直立侧壁，结果为封闭网格。UV 保持原图坐标；材质使用独立的 `O Texture Layer`，并复制源 Image datablock、按 Convert 系列相同规则命名为 `.color`。创建 Object 与 Mesh 时直接使用源 Image Empty 名称，不主动追加 Balloon 后缀；同一 Blender datablock 集合已有重名时仍由 Blender 自动追加数字编号。源 Image Empty 保持不变，Undo 可移除提取结果。
+## 运行环境
 
-当前不提供添加/减去选区、边缘羽化和视频跟踪。
-## Image Empty 去背景
+AI 任务在独立 Python Environment 中通过 ONNX Runtime 执行。Blender 负责界面、任务提交和结果导入，Job Server 负责模型与文件处理。
 
-1. 确认 `Models` panel 中的 `BEN2 Base` 已就绪；首次安装 Environment 时会默认下载。
-2. 在 3D View 选中 Image Empty，右键打开 `SnapForm` 子菜单并选择 `Remove Background`。
-3. 完成后以 Fake User 保留原 Image datablock，新建并 Pack 一张透明 PNG 到当前 `.blend`，然后只把
-   当前 Empty 的 `data` 换成新图；Empty 的 Transform、显示尺寸、Offset 及其他设置保持不变。
-4. 新 Image 使用原图去掉格式后再追加 `.color` 的名称。例如 `img.png` 生成
-   `img.color`，`img.png.001` 生成 `img.001.color`。已有同名 datablock 时由
-   Blender 自动追加编号。
+默认 Storage Root 为 `~/.snapform`，其中保存 Environment、模型、日志和 Job 结果。连续任务会复用已加载的模型 Session；DA3 与 MoGe-2 共享一个深度模型缓存位置，BEN2 可同时保留。
 
-原图已 Pack 时会先写出临时 PNG 交给 BEN2，任务结束后删除临时输入；原 Image 仍保持 Pack
-状态和原始内容。正式任务的 `color.0001.png` 也会保留在对应 job 目录中。
+安装、下载和推理都在后台运行，并通过状态栏提供进度与取消操作。详细设计见[Job Server](server.md)。
 
-Image Empty 引用视频或序列帧时，Remove Background 直接执行，默认取 Empty 的 Image Frames
-数值（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset；若 Offset 加 Frames 超出视频长度，
-会把窗口整体收进视频内（保证实际处理 Frames 帧数），Offset 过小时从第 1 帧开始。输出
-`color.0001.png` 等透明序列帧（帧号从 0001 开始，与 Blender 场景帧一一对应），并把
-关闭去背景时，原始颜色帧同样以 `color.0001.*` 起始的统一名称写入 job 目录。替换 Empty 的 Image 为
-加载这些帧的 SEQUENCE Image，从原 Empty 的 Start 位置开始播放（Start 原样保留）。图片类型只取决于源 Empty：普通单图的单个 `color.0001.*` 仍作为 `IMAGE`，Movie/Sequence 即使只导出一帧也作为 `SEQUENCE`；`.depth` 同样遵循该规则。
-Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因此保持外部引用 job 目录；
-请保留对应 job 目录，否则序列会失效。
+## 模型与调试
+
+正式功能使用以下 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)。

docs/outputs.md

@@ -1,37 +1,28 @@
 # 输出格式
 
-本页说明任务文件的字段与序列化约定，主要用于开发与数据检查。普通使用者只需了解
-[模型、设备与存储](models-and-storage.md)中的 Job 文件夹说明。
+本页记录 Job 产物的稳定用途与主要字段。日常使用只需了解 [Job 文件夹](models-and-storage.md)。
 
-## Debug
+## 文件概览
 
-Debug 用于直接比较 DA3、MoGe-2 与 BEN2 模型 API 的返回效果，不复用 Depth、Surface 或 Geometry
-后处理。三个入口对应三个独立 Job：
+| Job | 主要文件 | 内容 |
+| --- | --- | --- |
+| `generate-depth` | `results.npz`、深度与颜色序列 | Depth Plane 所需深度、相机和贴图 |
+| `generate-surface` | `mesh.npz`、`normal.png`、颜色层 | Surface 网格、相机与材质输入 |
+| `remove-background` | `color.0001.png` 起 | 带 Alpha 的颜色层 |
+| `debug-da3` | `prediction.npz` | DA3 API 返回 |
+| `debug-moge2` | `prediction*.npz` | MoGe-2 API 返回 |
+| `debug-ben2` | `foreground*.png` | BEN2 API 返回 |
 
-- debug-da3：保存 prediction.npz，字段直接来自 DA3 Prediction，包括 depth、conf、
-  extrinsics、intrinsics、processed_images 及模型实际返回的可选标量或数组
-- debug-moge2：每张输入保存一个 prediction.npz 或 prediction.0001.npz，完整保留 MoGe-2 API
-  字典中的 points、depth、normal、mask 与 intrinsics
-- debug-ben2：直接保存 BEN2 API 返回的 foreground.png 或 foreground.0001.png
+## NPZ 字段
 
-Debug 不生成点云、三角网格、深度预览、置信度 percentile 或坐标变换后的派生产物。输入为多帧时，
-DA3 保留联合推理；MoGe-2 与 BEN2 按其单图 API 逐帧保存结果。
+DA3 Depth 结果包含 `depth`、`conf`、`extrinsics` 与 `intrinsics`。MoGe-2 Depth 结果包含 `depth`、`normal`、`mask` 与 `intrinsics`。
 
-## Depth
+Surface 的 `mesh.npz` 包含 `vertices`、`faces`、`uv`、`intrinsics`、`image_size` 与 `reference_depth`，以及 Geometry Nodes 使用的网格属性。
 
-generate-depth 输出 Blender Depth Plane 所需的 results.npz。DA3 保存 depth、conf、
-extrinsics 与 intrinsics；MoGe-2 保存 depth、normal、mask 与 intrinsics，并额外写出
-Depth Plane 导入所需的贴图。这里的文件转换属于正式 Depth 工作流，不属于 Debug。
+Debug 文件保持模型 API 的数据形态，用于比较推理结果；正式 Job 则提供 Blender 导入所需的派生数据。
 
-## Surface
+## 图片序列
 
-generate-surface 统一写出 `mesh.npz`，不再生成 `texture.png`。DA3 与 MoGe-2 都使用
-`geometry/surface.py` 的同一套 Surface 构建算法；序列化位于 `outputs/surface.py`。MoGe-2 normal
-仍由 Server 单独导出为 `normal.png`，Blender 只负责加载并用于材质，不写入几何 NPZ。未去背景时
-无论颜色来自原图复制还是 BEN2，Server 都统一写为 `color.0001.*` 起始的颜色层。Blender 不依据文件数量判断图片类型：源 Empty 为普通单图时载入为 `IMAGE`，源 Empty 为 Movie/Sequence 时即使只有一帧也载入为 `SEQUENCE`；`.depth` 使用相同规则。材质只在 Blender
-端创建。MoGe-2 的 `normal.png` 仍由 Server 生成，Blender 只负责加载使用。
+正式颜色层统一使用 `color.0001.*` 起始的文件名。深度动画使用 EXR 序列以保存浮点值。源 Empty 为 Movie 或 Sequence 时，Blender 按序列载入这些文件，即使任务只输出一帧。
 
-## BEN2
-
-正式 remove-background 工作流输出 `color.0001.png` 起始的透明颜色层。BEN2 ONNX API 返回的 Alpha
-恢复到输入分辨率，RGB 保留输入图像颜色。Debug BEN2 仍保留模型 API 语义，使用 `foreground` 文件名。
+MoGe-2 Surface 的法线单独保存为 `normal.png`。材质在 Blender 端创建，不属于 Job 文件格式。

docs/server.md

@@ -1,129 +1,84 @@
 # Job Server
 
-本页记录 Environment、模型缓存和 Job Runtime 的内部设计。安装或使用遇到问题时，请先查看
-[安装与首次配置](installation.md)和[常见问题](faq.md)。
+SnapForm 把 AI 与媒体处理放在独立 Job Server 中运行，使 Blender Python 保持轻量。安装和使用问题见[安装与首次配置](installation.md)与[常见问题](faq.md)。
 
-## 运行架构
+## 架构
 
-SnapForm 在独立的 Python 3.12 Environment 中运行 HTTP Job Server，Blender 只通过标准库 HTTP Client 提交和轮询任务，不把计算依赖载入 Blender Python。Server 只监听 `127.0.0.1`，由外置 BlendJob wheel 提供的 `ServerController` 保存随机端口与 Instance ID；专属本地进程协议不使用额外 Token 鉴权。
+```mermaid
+flowchart LR
+    Blender["Blender Operator"] --> Runtime["JobRuntime"]
+    Runtime --> Queue["FIFO Queue"]
+    Queue --> Job["SnapForm Job"]
+    Job --> Media["Media"]
+    Job --> Models["ModelManager"]
+    Job --> Geometry["Geometry"]
+    Job --> Outputs["Outputs"]
+    Outputs --> Directory["Job Directory"]
+    Directory --> Blender
+```
 
-每个 Blender 实例启动并持有一个 SnapForm 专属 Server，不发现或复用其它 Blender、其它插件启动的本地 Server。多个 Blender 可以对应多个进程，但模型、Environment 与任务产物仍可共享同一个 Storage Root。
+每个 Blender 实例拥有自己的 Server 进程，连接绑定到本机随机端口和 Instance ID。多个实例可以共享 Storage Root，但各自维护进程、队列和内存中的模型 Session。
 
-Environment、模型和任务结果默认保存在 `~/.snapform`：
+BlendJob 提供 Runtime、HTTP transport、队列、状态和取消协议。SnapForm 的 Operator 负责业务参数，Server Job 负责工作流编排，结果由 Operator 在 Blender 主线程中导入。
+
+## Storage Root
+
+默认位置为 `~/.snapform`：
 
 ```text
 ~/.snapform/
-├── .venv/
-├── environment.json
-├── models/
-├── jobs/
-├── manifest.json
-├── install.log
-├── install-status.json  # 仅在安装期间存在
-└── server.log
+├── .venv/              Python Environment
+├── models/             ONNX 模型
+├── jobs/               任务产物
+├── environment.json    环境声明
+├── manifest.json       已安装环境指纹
+├── install.log         安装日志
+└── server.log          Server 日志
 ```
 
-不同 Blender 版本可共享此目录。也可以在 Extension Preferences 的 `Storage Root` 中修改位置。连接端口与 Instance ID 只保存在启动它们的 Blender 进程内存中。
+更改 Storage Root 相当于切换整套 Environment、模型和任务数据。目录说明见[模型、设备与存储](models-and-storage.md)。
 
-Blender Client 与独立 Server 的通用 HTTP Runtime 都复用 `src/snapform/wheels/` 中随扩展分发的同一份 BlendJob package；Server Environment 不再从 PyPI 安装第二份。`JobServer` 包装 FastAPI 并提供 Job、FIFO Queue 与 Resource API，`JobClient` 是无第三方依赖的 Blender 侧访问器。Blender 侧只把 `server/__init__.py:server` 入口字符串交给 Runtime，不导入 `server` package；独立进程启动后才取得其中的 `server` 实例、注册全部公开 Job，并创建 `model_manager` Resource。
+## 模块关系
 
-SnapForm 根 package 不再有 `client.py`、`environment.py`、`storage.py` 或 `models.py`。这些文件会制造并不存在的业务边界：
+| 模块 | 职责 |
+| --- | --- |
+| `runtime.py` | Environment、Server 生命周期、任务状态与 Storage Root |
+| `server/jobs/` | 按功能编排完整任务 |
+| `server/media/` | 图片、视频和序列输入 |
+| `server/models/` | ONNX Session 与模型 Prediction |
+| `server/geometry/` | 投影、网格和 Surface 数据转换 |
+| `server/outputs/` | NPZ、EXR、PNG 与序列文件 |
+| `model_catalog.py` | Blender UI 的模型声明与本地就绪检查 |
+| `server/model_catalog.py` | Server 的模型下载与推理声明 |
 
-- Storage Root、`.venv`、Manifest、安装状态与日志路径由 `JobRuntime` 唯一管理；
-- `InstallEnvironment` 由 `runtime.operator_classes()` 提供，Python 与 Job 自身的额外 packages 直接声明在传给 Runtime 的 `environment` 字典中；BlendJob 不需要重复声明；
-- Blender Client 使用根目录 `model_catalog.py` 构造 UI 并检查 Storage Root 下的模型必需文件；
-- 独立 Server 使用 `server/model_catalog.py` 下载和验证模型，不依赖 Extension 根 package。两份声明的共享存储字段由测试保持一致，已加载 Session 状态仍读取 Server Snapshot。
+调用方向从 Job 指向媒体、模型、几何和输出模块。模型层返回内存数据，输出层管理文件，Blender 数据始终由 Operator 的 Response 创建。
 
-BlendJob 的 `JobClient` 只是无依赖 HTTP transport，不是 SnapForm 业务抽象，也不向 Operator 暴露 `JobRequest`。
+## Environment 与模型
 
-SnapForm 的业务 Operator 直接提交参数字典，Job Type 一一对应：
+Environment 使用 Python 3.12、ONNX Runtime、NumPy、Pillow、PyAV、trimesh、FastAPI 和 Uvicorn。Windows 使用 DirectML 或 CPU；其他平台根据支持情况使用 CoreML、OpenVINO 或 CPU。
 
-- `download_model` → `download-model`
-- `download_required_models` → `download-required-models`
-- `remove_background` → `remove-background`
-- `extract_frames` → `extract-frames`
-- `generate_depth` → `generate-depth`
-- `generate_surface` → `generate-surface`
-- `debug_da3` → `debug-da3`
-- `debug_moge2` → `debug-moge2`
-- `debug_ben2` → `debug-ben2`
-
-DA3 与 MoGe-2 的生产任务不再合并成带 Backend 参数的通用请求。每个 Operator 的 `request(context)` 直接构造自己的有效参数，Debug 任务也与生产任务完全分开。
-
-Server 端没有 `execute_*`、`*_result` 或 CLI worker 中转。全部 `@server.job(...)` 都集中在
-`server/__init__.py`，这里只负责注册 Job 与 Resource。完整工作流位于 `jobs/`；模型适配器和
-ONNX 实现位于 `models/`；纯投影、网格与唯一 Surface Builder 位于 `geometry/`；文件序列化位于
-`outputs/`；输入准备位于 `media/`。模型下载由 `ModelManager` 单向调用
-`model_download.py`，不存在循环 import。
-
-## ONNX-only Environment
-
-扩展不内置 `uv` 可执行文件或 AI 运行库。`Install Environment` 首先下载固定版本的 uv，校验 SHA-256 后解压到共享 Storage Root，再用它创建环境并安装：
-
-- ONNX Runtime 1.24.4；Windows 使用 `onnxruntime-directml`
-- NumPy 2.4.2、Pillow 12.1.1、PyAV 17.0.0、trimesh 4.11.2
-- FastAPI 0.139.2、Uvicorn 0.51.0、huggingface-hub 1.4.1
-
-运行环境不安装 PyTorch、TorchVision、xFormers，也不安装 DA3、MoGe、BEN2 或 utils3d 的 Python 源码包。模型推理和 SnapForm 所需的相机、点云、网格后处理均由 ONNX Runtime、NumPy 与内部实现完成。
-
-Windows 当前发行环境提供 DirectML 与 CPU；`Auto` 优先使用 `DmlExecutionProvider`。显式指定不可用设备时会安全回退到 CPU。其他平台安装标准 ONNX Runtime，并按可用 provider 选择 CoreML、OpenVINO 或 CPU。Blender 侧通过 `sysctl` 识别 Apple Silicon 代际，只有 M4 或更新芯片才提供 MPS 选项；其他 Mac 只提供 CPU。M4 或更新芯片的 CoreML Session 使用 `MLProgram` 模型格式、全部可用计算单元并允许动态输入 Shape。
-
-`environment.json` 保存规范化后的声明，`manifest.json` 保存该声明与基础 Server packages 的 Hash。Python、packages、平台 packages、基础 Server packages 或 Environment Schema 改变后需要重新执行 `Install Environment`，不再维护手工 Manifest Revision。BlendJob 直接随 Extension 更新，不参与 Environment Hash。
-
-## 模型
-
-所有正式功能都使用 ONNX：
+正式功能支持：
 
 - MoGe-2 ViT-S、ViT-B、ViT-L Normal
 - DA3 Small、DA3 Base
 - BEN2 Base
 
-首次安装在 `post_install(runtime)` 中自动下载 `MoGe-2 ViT-S Normal` 与 FP16 `BEN2 Base`。它们和 `Models` panel 的后续下载一样，都是 `download-model` Job，与推理共用队列、HTTP 进度和取消协议。模型按声明的目录名保存在 `~/.snapform/models/`，并保留仓库内部结构。声明了文件清单与校验值的模型先走 Hugging Face `resolve` 直链流式下载，失败后尝试 `https://models.omoolab.xyz/<repository-name>/<relative-path>`；两者都失败时当前 Job 直接失败，不记录或猜测后续下载源。模型直链的 TCP、代理 CONNECT 与 TLS 建连最长等待 10 秒；连接后连续 60 秒没有收到响应数据则视为当前来源失败并切换下一来源。该空闲超时不限制模型总下载时长。R2 文件会校验大小与 SHA-256。未声明清单的仓库仍使用 `huggingface_hub` 快照下载。可用 `HF_ENDPOINT` 指定 Hugging Face 镜像。
+首次安装会下载 MoGe-2 ViT-S Normal 与 BEN2 Base。模型保存在 `models/`，可由多个 Blender 版本共享。Server 缓存 BEN2 和最近使用的一个深度模型，以控制内存占用。
 
-Image Empty 的右键菜单会读取 `model_manager` 状态；缺少 MoGe-2 ViT-S 或 BEN2 时显示
-`Download Required Models`。对应的 `download-required-models` Job 在 Server 端再次检查就绪状态，
-只下载缺失项，并把多个下载的进度合并为单次 0–100%。必需模型补齐前，右键菜单中的
-`Convert to Depth Plane` 保持禁用。
+模型下载优先使用 Hugging Face，并以 OmooLab 镜像作为回退。Environment 安装则提供官方源和镜像源两个明确入口；它们只影响 Environment Bootstrap，不改变模型下载策略。
 
-`model_manager` Resource 在 Server 内持有磁盘就绪状态和内存 Session。Blender UI 使用 Client catalog 声明的目录名与 `ready_patterns` 直接检查 `<storage-root>/models/`，因此展开模型面板、打开转换对话框或 Image Empty 右键菜单都不会仅为状态检测启动 Server。真正下载或推理时，Server 仍按自身 catalog 通过 `ModelManager.ready()` 重新验证文件。`ModelSessionCache` 保留 BEN2，并在 DA3 与 MoGe-2 之间只保留最近使用的一种 Depth Session。`GET /resources/model_manager` 只返回当前加载状态；`POST /resources/model_manager/clear` 只允许在没有 Active 或 Queued Job 时执行。
+## 任务生命周期
 
-DA3 ONNX 使用模型的 camera decoder 恢复外参与内参，不提供 ray-pose 参数。MoGe-2 的 metric depth、normal、mask、normalized intrinsics，以及 BEN2 的 Alpha，均在 NumPy 后处理中恢复。
+Server 在第一次提交 Job 或手动 Start 时启动。任务进入单 Worker FIFO Queue，同一时间执行一个推理、下载或媒体任务。
 
+Job 被接受时，Runtime 创建 opaque ID 和对应目录。进度保存在 Server 内存中，Blender 定期轮询状态。取消会在下载分块或一次 ONNX 调用结束后的检查点生效。
 
-## 安装网络与镜像
+Blender 正常退出或禁用扩展时会停止所属 Server；Server 也监视父进程，在异常退出后自行结束。
 
-安装器不做带宽测速、来源竞速或失败后的自动切换。`Install Environment` 固定使用 Astral GitHub Release、uv 默认 Python 下载源和 PyPI；`Install Environment (Mirror)` 固定使用 CNB uv Release、CNB `python-build-standalone` 与清华 PyPI。两个 uv 来源使用同一固定版本和 SHA-256；下载压缩包只作临时文件，安装完成后删除。
+Environment 安装发生在 Server 启动前，使用 `install.log` 记录过程。安装完成后的模型下载是普通 Job，与推理共享队列、进度和取消机制。
 
-镜像模式只在当前安装子进程中设置 `UV_PYTHON_INSTALL_MIRROR` 与 `UV_INDEX_URL`，不修改用户环境变量。Windows 系统代理会注入子进程；同时支持 `HTTP_PROXY`、`HTTPS_PROXY` 与 `ALL_PROXY`。post-install 模型下载保持 Hugging Face 与 OmooLab R2 的独立来源逻辑，不读取 Environment 安装模式。
+## DA3 多帧限制
 
-Environment Bootstrap 的单次 0–100% 只包含 uv、Python 与 packages，不包含后续模型下载。开始显示 `Starting installation ...`；uv 使用 1–20%，显示 `1/3 Starting uv download ...`、`1/3 Downloading uv [速度]` 或镜像形式、`1/3 Installing uv ...`；Python 使用 20–50%，显示 Checking、Downloading、Installing，镜像下载带 `(mirror)`；packages 使用 50–98%，显示 Resolving、`Downloading packages [已开始数]/[解析总数]`、Installing，镜像模式带 `(mirror)`；98–100% 显示 `Verifying installation ...`。三个下载区间分别占对应阶段的 84–87%，缓存命中时直接跳过。单阶段状态不显示 `1/1`。
+DA3 ONNX 的联合注意力显存随帧数和分辨率快速增长。Depth Plane 动画采用逐帧推理并复用 Session，使峰值显存接近单帧任务；代价是各帧不共享相机位姿与深度尺度。
 
-首次安装依次显示 Environment、MoGe-2 下载与 BEN2 下载，每项分别使用 0–100%。Environment 由 Job Runtime 依次完成 uv 下载、Python Environment 创建与 packages 安装，uv 不再占用独立一轮进度。两个模型下载由 SnapForm 的 `post_install(runtime)` 通过 `runtime.request()` 顺序发起；切换模型时进度归零，但不显示 `2/2` 等阶段编号。
-任一 post-install 模型失败时，Environment 文件仍然保留，但安装 Operator 返回失败并显示原始模型错误。
-
-## 生命周期
-
-扩展启用后不启动 Server；第一次执行 Job 或点击 `Start` 时才为当前 Blender 启动专属实例。正常关闭或禁用扩展时直接停止自己启动的进程；Server 也监视 Blender 父进程 PID，父进程异常退出后会自行停止。
-
-AI、帧提取和 Models panel 下载的 Job 进度保存在 Server 内存中。Handler 只使用 `context.progress(value, message)` 发布进度，终态由 JobServer 内部管理；SnapForm 不再维护独立的 `server/progress.py` 或 Job 状态 JSON。Blender 每 0.25 秒轮询 `GET /jobs/{job_id}`，任务目录不写 `status.json`。Operator 直接提交参数字典；Job 被接受时由 `JobServer` 自动生成 ID 并创建 `jobs/<opaque-job-id>/`，提交响应同时返回 `job_id` 与 `directory`。路径通过 `JobContext.directory` 传给 Handler，SnapForm Server 强制将输出写入该目录。
-
-`runtime.py` 创建唯一的 `runtime = JobRuntime(...)`，以 `src/snapform/` 为 `entrypoint_root`，传入 `server:server` 相对入口字符串与显式 `snapform` namespace，并导出 `runtime.JobOperatorBase`。Runtime 独占 Storage Root、Environment 路径、安装进程、Server 控制和 Status Bar。Operator 未覆盖 `request(context)` 时会提交全部 Property；覆盖后返回值纯替换默认参数。可选的 `response(context, result)` 在 Blender 主线程直接完成结果导入。SnapForm 不再提供 Client 请求层、Job Mixin、Status Bar 或 Build 中转 Operator。
-
-Environment 安装是 Server 启动前唯一的 Bootstrap 流程：`environment.json` 记录期望安装的环境声明，`install-status.json` 在安装期间回传进度并在任务收尾后删除，`install.log` 持久记录安装输出。Bootstrap 不创建 Job 目录。Environment 成功后执行普通的 `post_install(runtime)`；默认模型下载此时已经是正式 Server Job，会创建自己的 Job 目录，并使用与其它任务相同的进度和取消协议。
-
-Server 使用标准库单 Worker FIFO Queue，全局同时只执行一个 Job，包括模型下载。Server 忙碌时新 Job 进入 `queued`，不再返回 409；排队任务可以在执行前取消。取消运行中任务不会重启 Server；流式模型下载会在分块检查点结束，ONNX Runtime 当前调用则在返回后的最近检查点结束。JobServer 最多保留 100 个已完成 Job 的内存状态，后续提交时清理更早记录。
-
-Server 由 Environment 通过 `python -m blendjob.runner` 启动，避免 BlendJob 内部模块名遮蔽 Python 标准库。启动与崩溃信息写入 `~/.snapform/server.log`。
-
-## 已知限制
-
-DA3 ONNX 的注意力是朴素实现（`MatMul → Softmax → MatMul`），峰值显存与 `(帧数 × 每帧 patch 数)²` 成正比。迁移到 ONNX 前的 PyTorch 版使用 `scaled_dot_product_attention`（`XFORMERS_DISABLED=1`），按块计算注意力分数、不落地完整注意力矩阵，显存近似线性，因此视频能处理几十上百帧；ONNX 导出把 SDPA 回退成朴素注意力，多帧在中高分辨率下会显存爆炸（约 12 帧 @ 1008 即需 ~90 GB）。
-
-Depth Plane 的视频、序列帧转换会复用同一个 ONNX Session 逐帧独立推理，再把结果合并到现有序列输出，因此峰值显存只取决于单帧分辨率。逐帧结果不保留 DA3 的跨视图尺度与相机位姿一致性，适用于当前逐帧动画结构。Surface 只支持单张图片。DA3 Debug 多帧输入仍联合推理；MoGe-2 与 BEN2 Debug 按单图 API 逐帧保存直接返回。
-
-联合推理时，`onnx_da3.infer` 会在执行前按 `views × patches` 预估注意力张量，超过 4 GiB 直接报错并提示减少帧数或 Resolution Scale，避免 onnxruntime 报出难以定位的分配失败或 `UnicodeDecodeError`（DirectML 在中文 Windows 下报错信息为 GBK 编码，被 UTF-8 解码掩盖）。
-
-待解决方向：
-
-- 重新导出 DA3 ONNX，使用 ORT 的 `Attention` / `MultiHeadAttention` 贡献算子，或注入内存高效的注意力算子；
-- 若未来需要统一坐标系的视频重建，可按小窗口分批推理，再对齐相机位姿与深度尺度。
+DA3 Debug 保留联合推理，用于检查模型原始多帧行为。Server 会在预计注意力张量过大时提前报错，此时应减少帧数或 Resolution Scale。

docs/surface.md

@@ -1,194 +1,66 @@
 # Surface
 
-本页记录 Surface 的网格、相机、Geometry Nodes 和材质实现。日常操作与参数说明请阅读
-[Surface 使用指南](guide-surface.md)。
+Surface 从单张图片生成带透视关系的相机空间网格。它比 Depth Plane 更接近真实空间结构，适合需要匹配相机或继续编辑拓扑的场景。操作方法见[Surface 使用指南](guide-surface.md)。
 
-## Image Empty 转透视网格
+## 数据流
 
-1. 在 3D View 选中仅包含一帧的 Image Empty，右键打开 `SnapForm` 子菜单并选择
-   `Convert to Surface`。该入口独立于
-   `Convert to Depth Plane`，当前不处理视频或序列帧。
-   模型列表包含三个 MoGe-2 Normal 模型和两个 DA3 模型，默认使用 MoGe-2 ViT-S Normal。DA3 的
-   Resolution Scale 与 Depth Plane 使用相同设计；MoGe-2 改为显示共享的 Resolution Level。
-2. Server 先用未经抠图的原始 RGB 请求 DA3 的 `depth`、`conf` 与 `intrinsics`，随后仅在开启
-   `Remove Background` 时运行 BEN2 取得前景 Alpha；Alpha 经目标网格分辨率缩放与轻微模糊后，只要
-   大于 `0` 就把对应点视为前景；每个三角形的三个顶点必须全部为前景，任一顶点 Alpha 为 `0` 就在输出前删除该面；
-   关闭时不加载 BEN2。Depth 不做 smoothing，Server 反投影深度网格，建立源三角面，
-   计算 confidence percentile 与 3×3 相对深度不连续度，并写入
-   基于原图像素坐标的源 `UVMap`。这些步骤只准备修改器的输入网格，不执行 Relax、拓扑修复、平滑、
-   小岛清理或最终 UV 重投影。运行时显示的六个 `Preparing surface data` 步骤均指这段 Server 端源数据准备。
-   DA3 与 MoGe-2 最终都由 `server/geometry/surface.py` 构建同一份 Surface 数据；模型模块只提供各自的
-   深度、点、法线、Mask 与相机数据，不再自行拥有 Surface 网格输出实现。
-3. Blender 把勾选 `Usage > Modifier` 的 `O DA3 Surface` 节点组直接作为 Geometry Nodes 修改器
-   添加到 Surface，不另设修改器名称。节点组内没有子节点组，依次完成：
-   - 修改器顶层依次显示 `Iterations`、`Resolution`、`Smooth`；`Iterations` 默认 `2`、最小 `0`，
-     默认展开的 `Culling` Panel 依次包含 `Depth Continuity` 与 `Confidence`。前者直接读取面域 3×3
-     相对深度差，并使用指数映射：
-     默认 `50%` 对应官方 `rtol=0.04`，数值越大，内部阈值越小，剔除的断层面越多；
-   - 每轮 Remesh Iteration 依次执行 Connected Merge、循环拓扑修复与一次 Smooth，使新拓扑在进入下一轮
-     Merge 前先稳定；拓扑修复删除非流形面、单面拓扑和小面积 mesh islands；
-   - 默认 `Resolution` 为原始有效三角边长中位数乘以 `sqrt(10) * 2`。`sqrt(10)` 来自原先 90% 面数缩减
-     的二维边距估计，再乘以 2 为迭代合并留出更平滑、稳定的默认尺度；节点内部 Connected Merge 的
-     Distance 为 `Resolution * 0.5`；
-   - Smooth 采用 `O Smooth` 的边界检测和模糊法线权重，固定开放边界与薄面，只保留一个
-     `Smooth` 程度系数；节点组不再额外执行 Flip Faces；
-   - 从修改前的原始表面以 nearest-surface 重新采样 `UVMap`，最终明确写为 Corner 域 `2D Vector`。
-   MoGe-2 使用独立的 `O MoGe2 Surface`。Server 由内置 NumPy 网格构建函数
-   生成有限深度范围内的紧凑三角网格，并保留模型 mask、逐点 depth 及相邻点相对深度差。Geometry Nodes
-   按官方 `mask & ~depth_map_edge(depth, rtol=0.04)` 的含义，先由 `Mask` 删除 mask 外的面，再由
-   `Depth Continuity` 按同一份 3×3 邻域相对深度差删除断层面。DA3 与 MoGe-2 使用相同的属性、
-   名称、指数滑块和 FACE 删除逻辑，不再额外删除孤立点。之后才执行拓扑修复、Relax、孤岛清理与 UV 重投影。
-   节点组不提供 Confidence 或 Remesh 开关；Remesh 仍是节点处理流程的一部分。
-4. 节点组随插件放在 `O_SnapForm.blend`。Blender 4.5 首次 Append 后复用同一 datablock；
-   Blender 5.0 以 linked ID 载入后调用 Pack，后续 Surface 继续复用。插件不会为每个 Surface 新建节点组，
-   也不会在添加后重命名 Geometry Nodes 修改器。节点组只启用 `Usage > Modifier`，不 Mark as Asset；
-   修改器关闭 `show_group_selector`。`Fix Topology` 位于默认折叠的 `Options` Panel。
-   节点图按 Culling、Remesh、Topology Fix、Island Cleanup 与 UV 分区摆放；各区就近使用独立的
-   Group Input，并隐藏没有连线的接口，避免跨越整个节点图的输入连线。
-   `O DA3 Surface` 与 `O MoGe2 Surface` 的 `Iterations` 默认值均为 `2`、最小值为 `0`，
-   `Resolution` 默认值均为 `0.1`，所有输入 socket 的 Structure Type 均固定为 `Single`。
-5. Surface Job 统一按输入准备、模型推理、可选 BEN2、构建 SurfaceMesh、写出产物五个阶段更新进度；单帧推理只显示模型与阶段名称，不追加 `1/1`，仅多帧时显示当前帧与总数；
-   Surface Builder 是不接收 Job Context 或 progress callback 的纯数据转换。
-6. Server 在 job 根目录写出 `mesh.npz`。NPZ 保存 camera-space `vertices`、`faces`、`uv`、
-   `intrinsics`、`image_size` 与有效深度中位数 `reference_depth`。颜色层无论来自原图复制还是 BEN2，
-   Server 都统一写为 `color.0001.*`。Blender 读取网格数据后额外导入为 `.color`，材质不复用源
-   Empty 的 Image。颜色贴图会按当前场景的 View Transform 选择对应输入色彩空间：AgX、ACES 1.3、ACES 2.0、Filmic、Khronos PBR Neutral 分别使用 `AgX Base sRGB`、`ACES 1.3 sRGB`、`ACES 2.0 sRGB`、`Filmic sRGB`、`Khronos PBR Neutral sRGB`；无法匹配当前 View Transform 时回退 `sRGB`。 Server 不生成 `texture.png`，材质只在
-   Blender 端创建。
-   DA3 Surface 只保留 Geometry Nodes 后处理实际使用的 attributes：点域 `o_depth`、面域
-   `o_confidence` 与面域 `o_depth_discontinuity`。Remove Background 已在 Server
-   建面前直接删除背景三角面，不写入任何 background attribute。MoGe-2 的导入网格保留点域 `o_depth`，
-   以及面域 `o_mask`、`o_depth_discontinuity`，不伪造 confidence、stretch 或 background 属性，
-   也不写入 custom normal。MoGe-2 推理返回的 normal 直接编码为独立的 `normal.png`，Blender 将它
-   作为 Non-Color 贴图导入现有材质；normal 不进入 `mesh.npz`。
-   MoGe-2 Surface 独立导入的 normal Image datablock 以源图片名而非对象名为基名，使用
-   `图片名.normal`，不附加 `.moge2`。
-7. 网格以 `reference_depth` 截面匹配 Image Empty 的显示矩形：该截面的投影四角与 Empty 的可见
-   边界重合，主点同时匹配 Empty Offset。网格对象直接沿用源 Empty 的 `matrix_world`，因此位置、旋转、
-   缩放及父级关系产生的世界变换保持一致。更近的顶点沿 Empty 局部 `+Z` 方向凸出，三角面正面朝向
-   观察相机，启用 Backface Culling 时可从正面看到。
-8. 转换对话框不再提供后处理参数，只保留模型与 Resolution Scale 设置、`Create Matching Camera`、
-   `Remove Background`、`Shadeless`，以及分割线下方的 `Keep Original`。背景移除默认关闭；开启后 Server
-   使用 BEN2，并在写出 Surface 前直接删除背景三角面，不再由 Geometry Nodes 的 Background 开关处理。
-   该预删除同时适用于 DA3 与 MoGe-2；因此 MoGe-2 转换后即使关闭 `Mask`，BEN2 已删除的背景也不会恢复。
-   Surface 材质的 Color Image Texture 始终使用 `.color`；Remove Background 只决定该层是否带 BEN2 Alpha，原 Empty 始终保持原图。颜色贴图会按当前场景的 View Transform 选择对应输入色彩空间：AgX、ACES 1.3、ACES 2.0、Filmic、Khronos PBR Neutral 分别使用 `AgX Base sRGB`、`ACES 1.3 sRGB`、`ACES 2.0 sRGB`、`Filmic sRGB`、`Khronos PBR Neutral sRGB`；无法匹配当前 View Transform 时回退 `sRGB`。
-   `Shadeless` 使用与 Depth Plane 相同的 `O Shadeless` 节点组，并继续通过 Alpha 与 Transparent BSDF 混合；普通材质的
-   Bump Scale 按 `abs(object.scale.z) × camera scale_z` 设置，并在材质组内乘以固定基准 `0.001`，
-   与透视表面实际深度尺度一致；它允许负数以反转凹凸方向。
-   相机默认关闭；开启后会在 Empty 局部 `+Z` 侧创建一台朝向局部 `-Z` 的透视相机，并成为生成 Surface
-   的子级，使二者移动时保持投影关系。关闭 `Keep Original` 时，网格成功创建后删除源 Empty。
-   表面、材质与相机会归入同一个 `Convert to Surface` Undo 步骤。
-
-Process Res 的设计依据 DA3 官方实现：API 与 CLI 默认使用 `process_res=504` 和
-`process_res_method="upper_bound_resize"`；输入预处理的 `PATCH_SIZE=14`，会把宽高分别调整到最接近的
-`14` 倍数。DA3 论文以 `504×504` 为 base resolution，公开的训练尺寸长边为 `504`、`672`、`756` 或
-`896`。官方 CLI 虽给出 `1024` 示例，但没有声明更高分辨率会提升质量，也没有规定 `1000` 为硬上限。
-因此转换入口使用相对原图的 Resolution Scale，同时通过上下限避免 Process Res 过低或过高，并把训练范围
-之外的值明确视为实验设置。参考
-[DA3 API](https://github.com/ByteDance-Seed/Depth-Anything-3/blob/main/docs/API.md)、
-[输入预处理实现](https://github.com/ByteDance-Seed/Depth-Anything-3/blob/main/src/depth_anything_3/utils/io/input_processor.py)
-与[技术报告](https://depth-anything-3.github.io/assets/da3_tech_report_2025.pdf)。
-
-所有任务使用统一的状态栏进度显示。变化中的阶段说明显示在右侧的进度条内部，取消按钮
-位于进度条右侧。状态字段支持阶段、当前操作与预计剩余秒数，界面统一组合为紧凑文案并保证
-进度单调递增。任务进程与 Server 请求在后台启动，按钮点击后立即进入进度状态。Image Depth 的阶段包括 Environment 启动、输入准备、模型加载、深度估算、缓存
-写出和面片构建。进度更新会强制刷新状态栏与窗口，无需移动鼠标即可实时显示。安装中断后残留的
-半成品 Environment 会在下次安装前自动清理，不会因为中断而无法再次安装。
-
-导入过程精确保留 NPZ 内深度值之间的差值。例如深度 `2.0` 和 `5.5` 在
-`Displacement Strength = -1` 时，沿局部 Z 轴相差 `3.5 Blender Unit`。它不会把数值压缩到
-`0..1`，也不再提供视觉归一化模式。
-
-面片尺寸以有效深度的中位数 `Zref` 作为参考截面。先用 `mini_npz` 中的相机内参计算原始
-投影面积，再恢复源图纵横比：
-
-```text
-RawWidth  = depth_width  × Zref × abs(Displacement Strength) / fx
-RawHeight = depth_height × Zref × abs(Displacement Strength) / fy
-Area      = RawWidth × RawHeight
-Aspect    = source_image_width / source_image_height
-Width     = sqrt(Area × Aspect)
-Height    = sqrt(Area / Aspect)
+```mermaid
+flowchart LR
+    Image["单张 Image Empty"] --> Model["DA3 / MoGe-2"]
+    Model --> Builder["Surface Builder"]
+    Builder --> Mesh["mesh.npz"]
+    Mesh --> Blender["Blender 导入"]
+    Blender --> Nodes["Geometry Nodes 后处理"]
+    Nodes --> Result["Surface + Material"]
+    Blender --> Camera["可选匹配相机"]
 ```
 
-这样即使 DA3 估计出的 `fx/fy` 不一致，也不会把正方形原图拉成长方形。主点 `cx/cy` 仍用于
-确定原始相机面片，随后对象 XY Transform 将它匹配到源 Image Empty。生成对象会记录
-`snapform_reference_depth`、`snapform_camera_plane_width` 和
-`snapform_camera_plane_height`，便于检查实际采用的
-参考深度和尺寸。
+模型提供深度、相机和有效区域，Surface Builder 将其转换为统一的相机空间网格。Blender 导入网格后，用 Geometry Nodes 完成清理、重拓扑、平滑和 UV 重投影。
 
-材质始终导入深度 Image Texture，并连接到 Displacement 节点和 Material Output；材质 Surface
-Displacement 设置为 `Displacement Only`，DA3 与 Original 都使用 `Midlevel = 0`、`Scale = 1`。MoGe-2 的位移只在专用 Geometry Nodes 中处理。
-`o_material_displacement` 为 `False` 时，材质把 Height 乘以零，置换只在几何节点中生效；为 `True` 时，
-几何节点关闭结构置换，材质 Height 恢复。色彩贴图的 Alpha 二值结果同时用于选择原始深度或有符号的
-`Background Depth`，使两种置换路径保持一致；未移除背景的普通不透明图片因此全部视为前景。
-视频与序列帧的颜色、深度与前景 Image Texture
-通过 image_user 的 Frames / Offset / Start 把第 i 帧映射到场景 `Start+i` 帧，并启用 Auto Refresh。
-颜色贴图到 Principled BSDF 之间使用独立的 Shader Node Group。DA3 Surface 使用 `O DA3 Surface Layer`，
-MoGe-2 Surface 使用独立的 `O MoGe2 Surface Layer`；它额外接收模型输出的 `Normal` 贴图，使用
-`Normal Map` 节点按 `Object Space` 解码后连接到 Bump 的 `Normal` 输入，使像素级模型法线与原图
-Bump 合并，不依赖重拓扑后的顶点密度；`Normal Strength` 默认值为 `1.0`，只调节模型 normal map，
-颜色贴图 Bump 仍由独立的 `Bump Scale` 控制；
-Depth Plane 使用 `O DA3 Depth Plane Layer` 材质组，并把背景剔除、背景深度与材质置换 Attribute
-读取全部收进组内。两者都接收 `Color`、`Alpha` 与 `Bump Scale`，只有 `O DA3 Depth Plane Layer`
-额外接收 Float 类型的 `Depth`。
-`O DA3 Surface Layer` 只输出 `Color`、`Roughness`、`Alpha` 与 `Normal`，以原图 Color 保留 Bump 效果，
-不创建 Displacement 节点或输出；`O DA3 Depth Plane Layer` 另外输出 `Displacement`。外层材质只保留贴图、
-材质组、Principled BSDF 与 Material Output，方便继续调整。
-Depth Plane 的 Bump Height 直接使用材质组的 `Color` 输入，只受独立的 `Bump Scale` 影响，不使用深度贴图，
-也不经过 `Displacement` 模式开关、`Depth Scale` 或 `Background Depth`；材质 Displacement 仍使用这些参数处理后的深度。
-无论选择哪种置换方式，Layer 的 `Color` 都会连接 Principled BSDF 的 `Base Color`、
-`Subsurface Radius` 与 `Emission Color`；Layer 的 `Normal` 同时连接 `Normal` 与 `Coat Normal`，
-通过 `Bump.Height → Bump.Normal` 提供表面细节。Subsurface、Emission 与 Coat 的强度等其他输入
-保持 Principled BSDF 默认值。Bump 的基础 Distance 为
-`0.001`，会乘以面片 Transform 的统一缩放倍率。原图 Color 还会经过 `Float Curve` 连接到
-Principled BSDF 的 `Roughness`，曲线两端输出分别为 `0.5` 和 `0.1`；材质 IOR 保持
-Principled BSDF 默认值 `1.5`。
-开启 `Shadeless` 后，色彩贴图 Color 接入 `O Shadeless`。该组沿用 Blender Images as Planes 的
-Diffuse、Emission、Light Path 与射线判断连接；二值 Alpha 仍作为 Mix Shader 系数，在 Transparent BSDF
-与 `O Shadeless` 之间混合后连接 Material Output。外层不再创建 Emission、Principled BSDF、Bump 或
-Float Curve。开启 `Remove Background` 时色彩贴图使用 `.color`；关闭时使用 `.color`。
+## 模型数据
 
-这里的“原始距离”是 DA3 模型输出的尺度。普通 Small、Base、Large 和 Giant 模型的深度不应
-被解释为现实世界的米；需要现实尺度时应选择带 metric depth 的
-`DA3 Nested Giant Large 1.1`。此外，当前结果仍是固定 XY 平面上的深度位移面，不是使用
-相机内参逐像素反投影得到的完整 camera-space 网格；中位深度截面为 Geometry Nodes
-深度面片提供正确的整体高宽尺度。
+| 来源 | 用于建网格的数据 | 材质附加数据 |
+| --- | --- | --- |
+| DA3 | Depth、confidence、intrinsics | 原图颜色 |
+| MoGe-2 | Metric depth、mask、intrinsics | 原图颜色与 normal |
 
-生成完成后会直接创建面片，不提供缓存重建入口或单独的导入参数。重新选择
-`Convert to Depth Plane` 会按当前 Depth from 再次转换。
-面片、深度 Image、颜色 Image、Material 与 Geometry Nodes 修改器会在同一个 Blender Undo 步骤中创建；转换完成后执行
-`Ctrl+Z` 会完整撤销本次转换，不会越过转换去回退更早的 Image Empty 操作。
+两种模型共享同一 Surface Builder 和网格文件格式。启用 Remove Background 时，BEN2 Alpha 会在建网格阶段移除背景三角面；这是几何裁剪，转换后关闭材质 Mask 不会恢复已删除的面。
 
-Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PNG 交给 DA3，
-不会 Unpack 或修改源 Image；任务结束后自动删除临时文件。普通图片仍直接读取源文件。DA3 的原始
-`results.npz` 保留在对应 job 文件夹根下，生成的浮点深度 Image 会 Pack 到
-当前 `.blend`。Depth Image 与 Displace Texture 根据源 Image datablock 命名。例如 Empty Object
-名为 `obj_img`、引用的 Image 名为 `img.png` 时，Depth Image 与 Texture 都命名为 `img.depth`；
-生成的 Object、Mesh 与 Material 仍命名为 `obj_img`。Pack 使用 OpenEXR，因而不会把大于 `1.0`
-的原始深度截断。已有同名 datablock 时由 Blender 自动追加 `.001` 等编号。
-视频输入时 Blender 无法整体 Pack 序列帧，因此 `.depth` 与颜色序列改为引用 job 目录根下的
-`depth.0001.exr`、`color.0001.jpg`（`.color`）或 `color.0001.png`，并在每帧保留原始
-浮点深度；保存 `.blend` 后再次打开仍需对应 job 目录存在。
+## 源网格
 
-每个 Server Job 被接受时，Job Runtime 在 Runtime Storage Root 的 `jobs/` 下创建一个独立文件夹。文件夹名是 32 位 opaque Job ID，不包含任务类型或对象名称。执行逻辑从 `JobContext.directory` 获取路径，输出产物直接写入该目录。
+`mesh.npz` 保存：
 
-Blender 为 Packed Image 或序列帧生成的输入副本先保存在系统临时目录，Server 读取完成后由 Blender 清理，不归档到 Job 目录。普通磁盘文件和视频仍直接读取原文件。Server 日志统一写入 `server.log`，进度只保存在 Server 内存中。Environment Bootstrap 使用 Storage Root 下的 `install.log` 与临时的 `install-status.json`，不创建 Job 目录。
+- camera-space `vertices` 与 `faces`
+- 原图坐标对应的 `uv`
+- `intrinsics` 与 `image_size`
+- 用于整体尺度的 `reference_depth`
+- Geometry Nodes 使用的深度、Mask、置信度或连续性属性
 
-正式几何输出由 `generate-depth` 与 `generate-surface` 负责。Debug 使用彼此独立的
-`debug-da3`、`debug-moge2` 与 `debug-ben2`，只保存模型 API 的直接返回，不进入 Geometry 或
-Surface 输出流程。
+源网格保持模型空间信息，视觉清理集中在 Geometry Nodes 中完成。这样可以调整参数、比较结果，也可以 Apply 修改器后继续普通建模。
 
-Job 目录中的典型正式产物如下：
+## Geometry Nodes
 
-```text
-<opaque-job-id>/
-├── results.npz、mesh.npz 或 normal.png
-└── prediction.npz             Debug 原始 API 返回
+DA3 使用 `O DA3 Surface`，MoGe-2 使用 `O MoGe2 Surface`。两者采用相同的处理顺序：
 
-<opaque-job-id>/
-├── color.0001.jpg/png…       正式工作流颜色层（原图复制或 BEN2 Alpha）
-├── depth.0001.exr…           AI 深度序列帧
-└── normal.png                MoGe-2 Surface 法线贴图
-```
+1. 根据有效区域、深度连续性和可用置信度剔除不可靠面
+2. 合并和修复拓扑
+3. 清理小岛并平滑表面
+4. 从源网格重新投影 UV
 
-建议从 `DA3 Base` 开始。它使用 Apache 2.0 模型权重。
+常用控制包括 Iterations、Resolution、Smooth、Depth Continuity、Confidence 和 Mask。节点资产由扩展复用，多个 Surface 不会各自复制一套节点图。
+
+## 空间与相机
+
+网格在 camera space 中生成，再通过源 Image Empty 的 Transform 放入场景。导入过程会匹配图片可见尺寸、宽高比、Offset 与主点位置。
+
+启用 Create Matching Camera 时，SnapForm 根据模型 intrinsics 创建相机并使用相同坐标变换，使网格与相机视图保持一致。模型估计的焦距和主点决定透视关系；`reference_depth` 决定整体尺度。
+
+## 材质与文件
+
+颜色统一写为 `color.0001.*` 并导入为 `.color` Image。MoGe-2 还会输出 `normal.png`，用于材质法线。材质名称以源 Image datablock 为基名。
+
+单图结果可以 Pack 到 `.blend`。模型原始结果与 `mesh.npz` 保留在 Job 目录中，便于调试和重新检查。
+
+## 适用范围
+
+Surface 面向单张图片。它生成可编辑的透视网格，但遮挡区域仍来自单视图估计，无法恢复图片中不可见的真实几何。视频和序列帧应使用 [Depth Plane](depth-plane.md)。