feat: Add surface generation and media handling

- Implemented surface generation functionality in `surface.py`, including geometry estimation and texture writing. - Introduced media input handling in `input.py`, supporting image and video frame extraction. - Added model management for geometry adapters in `models/__init__.py`. - Created BEN2 and DA3 model inference logic in `ben2.py` and `da3.py`, respectively. - Developed ONNX model inference utilities for BEN2 and DA3 in `onnx_ben2.py` and `onnx_da3.py`. - Added support for MoGe-2 model inference in `moge2.py` with necessary ONNX utilities. - Implemented output handling for depth and surface data in `depth.py` and `surface.py`. - Created debug output utilities for DA3 and MoGe-2 predictions in `debug_da3.py` and `debug_moge2.py`. - Enhanced ONNX runtime session management in `onnx_runtime.py`. - Updated `__init__.py` files to include new modules and functions for better organization.
2026-08-18 23:27:10 +08:00
parent 9dfa49602c
commit 835225d264
62 changed files with 2126 additions and 2318 deletions
--- a/docs/depth-plane.md
+++ b/docs/depth-plane.md
@@ -11,7 +11,7 @@
     `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 始终保留原始 `results.npz`，并按 Output Format 单独生成 Maps、纹理 GLB 或彩色 PLY。
+   - 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
@@ -23,7 +23,9 @@
    Image Empty 引用视频或序列帧时，DA3 与 MoGe-2 会按 Empty 的 Image Frames 数值逐帧估计
    深度（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset，与背景蒙版范围一致；
    DA3 会复用同一个 ONNX Session 对每帧独立推理，再合并为原有序列输出，避免多帧 Attention 的平方级显存占用。
-    该行为只用于 Depth Plane 转换；Surface 仅支持单张图片，Debug 多帧输出仍联合推理。
+    DA3 与 MoGe-2 均先用未经抠图的原始 RGB 生成深度，再运行可选 BEN2；BEN2 Alpha 只参与最终输出过滤和材质 Mask。
+    该行为只用于 Depth Plane 转换；Surface 仅支持单张图片。Debug 中 DA3 多帧输入联合推理，
+    MoGe-2 与 BEN2 按单图 API 逐帧运行。
    Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty
    一致；Original 模式的视频或序列帧使用 `frame.0001.jpg` 等原图序列作为颜色与深度，
    `foreground.0001.png` 只提供前景 Alpha。
--- a/docs/development.md
+++ b/docs/development.md
@@ -24,9 +24,14 @@ flowchart LR
 - `blender/depth_plane.py` 与 `blender/surface.py` 实现 Image Empty 输入检查、几何构建和资产挂载
 - `job_runtime.py` 以入口字符串声明独立 Server，并配置 Environment、Storage Root 与首次安装后的推荐模型下载
 - `server/__init__.py` 创建 `JobServer`、注册公开 Job，并把 `ModelManager` 注册为 Resource
- `server/media.py`、`background.py`、`da3.py`、`moge2.py` 负责业务流程；`onnx_*.py` 只处理模型输入、推理和输出恢复
+- `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/geometry.py` 生成 NPZ、预览、点云和纹理网格；所有任务产物写入 Runtime 分配的 opaque-ID Job 目录
+- `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)。

@@ -56,18 +61,37 @@ flowchart LR
 │       ├── model_catalog.py
 │       ├── server/
 │       │   ├── __init__.py
-│       │   ├── background.py
-│       │   ├── da3.py
-│       │   ├── geometry.py
-│       │   ├── media.py
+│       │   ├── jobs/
+│       │   │   ├── background.py
+│       │   │   ├── debug_ben2.py
+│       │   │   ├── debug_da3.py
+│       │   │   ├── debug_moge2.py
+│       │   │   ├── depth.py
+│       │   │   ├── foreground.py
+│       │   │   ├── frames.py
+│       │   │   └── surface.py
+│       │   ├── geometry/
+│       │   │   ├── projection.py
+│       │   │   ├── grid_mesh.py
+│       │   │   └── surface.py
+│       │   ├── media/
+│       │   │   └── input.py
 │       │   ├── model_download.py
 │       │   ├── model_catalog.py
 │       │   ├── model_manager.py
-│       │   ├── moge2.py
-│       │   ├── onnx_ben2.py
-│       │   ├── onnx_da3.py
-│       │   ├── onnx_moge2.py
-│       │   └── onnx_runtime.py
+│       │   ├── models/
+│       │   │   ├── ben2.py
+│       │   │   ├── da3.py
+│       │   │   ├── moge2.py
+│       │   │   ├── onnx_ben2.py
+│       │   │   ├── onnx_da3.py
+│       │   │   ├── onnx_moge2.py
+│       │   │   └── onnx_runtime.py
+│       │   └── outputs/
+│       │       ├── debug_da3.py
+│       │       ├── debug_moge2.py
+│       │       ├── depth.py
+│       │       └── surface.py
 │       └── wheels/
 │           └── blendjob-0.1.13-py3-none-any.whl
 ├── tests/
@@ -106,6 +130,9 @@ 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` 资产；修改节点组、材质组或其接口时，应运行相应资产验证脚本，并再次运行完整测试。

 ## 上游与许可证
--- a/docs/features.md
+++ b/docs/features.md
@@ -5,7 +5,7 @@

 `SnapForm` 是一套从图片快速构建空间结构的 Blender Extension。目前以
 [Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
-作为首个 AI 能力，在独立 Environment 中运行 DA3，可将官方导出结果保存在独立 job 目录，
+作为首个 AI 能力，在独立 Environment 中运行 DA3，可将模型 API Prediction 保存在独立 job 目录，
 也可把 Image Empty 转换成带几何与材质置换的立体面片。MoGe-2 作为独立深度来源，保留其 metric depth、normal、mask 与 intrinsics 输出，不复用 DA3 Prediction 后处理。Debug 面板还可运行
 [BEN2](https://github.com/PramaLLC/BEN2) 背景剔除功能测试。

@@ -26,14 +26,11 @@
 - `Models` panel 默认折叠，展开后可逐项查看和下载所有可用模型
 - Environment 已安装时不额外占用面板空间；模型列表每个模型只占一行
 - `Debug` 默认折叠，内部的 `DA3`、`MoGe-2` 与 `BEN2` 也分别默认折叠
- 使用一个输出类型下拉菜单和一个 `Generate Output` 按钮
- DA3 与 MoGe-2 Debug 都先选择单一 Output Format，只显示当前格式的专属参数；GLB 与 PLY 不会在一次测试中同时生成
- Debug 的模型选项按格式过滤；PLY 只提供两个带 Gaussian head 的 Giant 模型
+- DA3、MoGe-2 与 BEN2 分别使用独立 Debug Job，直接保存各自 API 返回，不共享按模型分支的总控函数
+- DA3 Debug 保存 Prediction NPZ；MoGe-2 Debug 保存逐帧原始预测 NPZ；BEN2 Debug 保存直接返回的透明前景
 - Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
  `(Missing)`，已下载模型保持原名
- 分别调用 DA3 的 `glb`、`gs_ply`、`depth_vis` 和 `mini_npz` exporter
- `Textured Surface (GLB)` 直接使用 DA3 Prediction 中的深度、置信度和相机参数，把相邻像素
-  组成三角面并写入 `mesh.glb`；每个输入帧生成一张独立纹理网格，不做多视图融合
+- Debug 不运行点云、Surface、深度预览、置信度 percentile 或坐标变换等 SnapForm 后处理
 - Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
 - Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
 - 缺少必需的 `MoGe-2 ViT-S Normal` 或 `BEN2 Base` 时，Image Empty 的 `SnapForm`
@@ -43,13 +40,13 @@
 - 菜单、模型面板和转换对话框直接检查 Storage Root 的 `models/` 必需文件，显示模型状态时不会启动 Job Server
 - Image Empty 支持视频与序列帧输入：`Convert to Depth Plane` 逐帧估计深度，
  `Remove Background` 逐帧抠图，入口保持不变。DA3 转换时每帧独立执行 ONNX 推理并复用模型 Session；
-  Debug 多帧任务继续联合推理，以保留跨视图相机与深度关系
+  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 按钮保持原位置并变灰，任务完成后恢复

@@ -79,7 +76,7 @@
   官方安装固定使用 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`，选择 `Output Type` 和本次执行使用的模型。
+7. 展开默认收起的 `Debug`，在 DA3、MoGe-2 或 BEN2 区域选择模型与输入，然后直接运行对应 API。
 8. 选择一张图片或一个视频文件。视频可设置从头截取的帧数，然后点击 `Generate Output`。
 9. 测试背景剔除时，确认 `Models` panel 中的 `BEN2 Base` 已就绪，然后在 `Debug` 的
   `BEN2` 区域选择单张图片并点击 `Remove Background`。
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,6 +5,6 @@
 - [功能与使用](features.md)：能力概览、安装使用和 Image Empty 去背景
 - [Depth Plane](depth-plane.md)：深度面片的数据、节点与材质流程
 - [Surface](surface.md)：透视网格、Geometry Nodes 后处理与材质法线
- [输出格式](outputs.md)：Debug 输出类型、参数和任务产物
+- [输出格式](outputs.md)：Debug 原始 API 返回与 Depth、Surface 任务产物
 - [Job Server](server.md)：Environment、模型缓存、任务目录与运行机制
 - [程序设计、开发与许可证](development.md)：模块边界、调用流程、项目结构、常用命令与许可证
--- a/docs/outputs.md
+++ b/docs/outputs.md
@@ -1,29 +1,32 @@
 # 输出格式

-## DA3 ONNX
+## Debug

-`Output Type` 提供以下结果：
+Debug 用于直接比较 DA3、MoGe-2 与 BEN2 模型 API 的返回效果，不复用 Depth、Surface 或 Geometry
+后处理。三个入口对应三个独立 Job：

- Point Cloud (GLB)：由 depth、confidence、相机参数和原图生成彩色点云
- Depth Preview (Images)：保存深度着色预览
- Depth Data (NPZ)：保存 depth、confidence、extrinsics、intrinsics 与处理后的图像
- Textured Surface (GLB)：SnapForm 根据 Prediction 构建纹理网格
+- 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

-DA3 Small 与 Base 的 ONNX 图不包含 Gaussian head，因此不提供 Gaussian Splats。默认推理参数为：
+Debug 不生成点云、三角网格、深度预览、置信度 percentile 或坐标变换后的派生产物。输入为多帧时，
+DA3 保留联合推理；MoGe-2 与 BEN2 按其单图 API 逐帧保存结果。

- `process_res=504`
- `process_res_method="upper_bound_resize"`
- `ref_view_strategy="saddle_balanced"`
- `conf_thresh_percentile=40.0`
- `num_max_points=1_000_000`
- `show_cameras=True`
+## Depth

-相机外参与内参由模型的 camera decoder 输出恢复，不运行 ray-pose 求解器。
+generate-depth 输出 Blender Depth Plane 所需的 results.npz。DA3 保存 depth、conf、
+extrinsics 与 intrinsics；MoGe-2 保存 depth、normal、mask 与 intrinsics，并额外写出
+Depth Plane 导入所需的贴图。这里的文件转换属于正式 Depth 工作流，不属于 Debug。

-## MoGe-2 ONNX
+## Surface

-MoGe-2 Debug 可保存原始 NPZ、depth/normal/mask maps、纹理 GLB 或彩色 PLY。Surface 输出由模型 points、mask 与 depth edge 在内部构建三角网格。
+generate-surface 统一写出 mesh.npz 与 texture.png。DA3 与 MoGe-2 都使用
+geometry/surface.py 的同一套 Surface 构建算法；序列化位于 outputs/surface.py。
+MoGe-2 normal 另存为 normal.png 并由 Blender 材质加载，不写入几何 NPZ。

-## BEN2 ONNX
+## BEN2

-BEN2 输出 `foreground.png`，RGB 保留原始输入，Alpha 来自 ONNX mask 并恢复到输入分辨率。
+正式 remove-background 工作流输出 foreground.png 或透明前景序列。BEN2 ONNX API 返回的 Alpha
+恢复到输入分辨率，RGB 保留输入图像颜色。
--- a/docs/server.md
+++ b/docs/server.md
@@ -39,17 +39,19 @@ SnapForm 的业务 Operator 直接提交参数字典，Job Type 一一对应：
 - `download_required_models` → `download-required-models`
 - `remove_background` → `remove-background`
 - `extract_frames` → `extract-frames`
- `generate_da3_depth` → `generate-da3-depth`
- `generate_moge2_depth` → `generate-moge2-depth`
- `generate_da3_surface` → `generate-da3-surface`
- `generate_moge2_surface` → `generate-moge2-surface`
+- `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`：简单任务直接实现，复杂任务调用按领域拆分的 `media.py`、`background.py`、`moge2.py` 或 `da3.py`；共享的纯几何计算位于 `geometry.py`。模型下载由 `ModelManager` 单向调用 `model_download.py`，不存在循环 import。
+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

@@ -114,7 +116,7 @@ Server 由 Environment 通过 `python -m blendjob.runner` 启动，避免 BlendJ

 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 只支持单张图片；Debug 多帧输出仍使用联合推理，以保留多视图关系。
+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 解码掩盖）。

--- a/docs/surface.md
+++ b/docs/surface.md
@@ -7,15 +7,20 @@
   `Convert to Depth Plane`，当前不处理视频或序列帧。
   模型列表包含三个 MoGe-2 Normal 模型和两个 DA3 模型，默认使用 MoGe-2 ViT-S Normal。DA3 的
   Resolution Scale 与 Depth Plane 使用相同设计；MoGe-2 改为显示共享的 Resolution Level。
-2. Server 请求 DA3 的 `depth`、`conf` 与 `intrinsics`。仅在开启 `Remove Background` 时运行 BEN2 取得
-   前景 Alpha，并在输出前删除包含背景顶点的三角面；关闭时不加载 BEN2。Depth 不做 smoothing，Server
-   反投影深度网格，建立源三角面，计算 confidence percentile 与 3×3 相对深度不连续度，并写入
+2. Server 先用未经抠图的原始 RGB 请求 DA3 的 `depth`、`conf` 与 `intrinsics`，随后仅在开启
+   `Remove Background` 时运行 BEN2 取得前景 Alpha；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，不另设修改器名称。节点组内没有子节点组，依次完成：
-   - 修改器顶层依次显示 `Resolution`、`Relax Iterations`、`Smooth`；默认展开的 `Culling` Panel
-     依次包含 `Depth Continuity` 与 `Confidence`。前者直接读取面域 3×3 相对深度差，并使用指数映射：
+   - 修改器顶层依次显示 `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；
@@ -37,18 +42,19 @@
   修改器关闭 `show_group_selector`。`Fix Topology` 位于默认折叠的 `Options` Panel。
   节点图按 Culling、Remesh、Topology Fix、Island Cleanup 与 UV 分区摆放；各区就近使用独立的
   Group Input，并隐藏没有连线的接口，避免跨越整个节点图的输入连线。
-   `O DA3 Surface` 与 `O MoGe2 Surface` 的 `Resolution` 默认值均为 `0.1`，所有输入 socket 的
-   Structure Type 均固定为 `Single`。
-5. Server 准备过程固定显示 6 个编号阶段：验证 DA3 数据、反投影、准备 DA3 与可选 BEN2 数据、构建原始
-   源三角面、源 UV/attributes、写出网格。状态栏显示 `Preparing surface data n/6: ...`。
+   `O DA3 Surface` 与 `O MoGe2 Surface` 的 `Iterations` 默认值均为 `2`、最小值为 `0`，
+   `Resolution` 默认值均为 `0.1`，所有输入 socket 的 Structure Type 均固定为 `Single`。
+5. Surface Job 统一按输入准备、模型推理、可选 BEN2、构建 SurfaceMesh、写出产物五个阶段更新进度；
+   Surface Builder 是不接收 Job Context 或 progress callback 的纯数据转换。
 6. Server 在 job 根目录写出 `mesh.npz` 与 `texture.png`。NPZ 保存 camera-space `vertices`、
   `faces`、`uv`、`intrinsics`、`image_size` 与有效深度中位数 `reference_depth`。Blender 读取这些
-   数据后直接创建 Surface 与原图材质，不需要 Open3D 或 OpenCV 进入 Blender Python 环境。
+   数据后直接创建 Surface；材质默认使用原图，开启 Remove Background 时改用 `.foreground`，不需要 Open3D 或 OpenCV 进入 Blender Python 环境。
   DA3 Surface 只保留 Geometry Nodes 后处理实际使用的 attributes：点域 `o_depth`、面域
-   `o_face_confidence` 与面域 `o_depth_discontinuity`。Remove Background 已在 Server
+   `o_confidence` 与面域 `o_depth_discontinuity`。Remove Background 已在 Server
   建面前直接删除背景三角面，不写入任何 background attribute。MoGe-2 的导入网格保留点域 `o_depth`，
   以及面域 `o_mask`、`o_depth_discontinuity`，不伪造 confidence、stretch 或 background 属性，
-   也不写入 custom normal。完整分辨率的 `normal_map` 保存在 NPZ 中并转换为材质贴图。
+   也不写入 custom normal。MoGe-2 推理返回的 normal 直接编码为独立的 `normal.png`，Blender 将它
+   作为 Non-Color 贴图导入现有材质；normal 不进入 `mesh.npz`。
   所有 MoGe-2 Image datablock 都以源图片名而非对象名为基名：depth、normal 与 mask 分别使用
   `图片名.depth`、`图片名.normal`、`图片名.mask`，不附加 `.moge2`。
 7. 网格以 `reference_depth` 截面匹配 Image Empty 的显示矩形：该截面的投影四角与 Empty 的可见
@@ -59,6 +65,7 @@
   `Remove Background`、`Unshaded`，以及分割线下方的 `Keep Original`。背景移除默认关闭；开启后 Server
   使用 BEN2，并在写出 Surface 前直接删除背景三角面，不再由 Geometry Nodes 的 Background 开关处理。
   该预删除同时适用于 DA3 与 MoGe-2；因此 MoGe-2 转换后即使关闭 `Mask`，BEN2 已删除的背景也不会恢复。
+   开启 Remove Background 时，Surface 材质的 Color Image Texture 使用打包后的 `.foreground`，原 Empty 仍保持原图。
   `Unshaded` 使用与 Depth Plane 相同的 Emission/Transparent 材质路径；普通材质的
   Bump Scale 按 `abs(object.scale.z) × camera scale_z` 设置，并在材质组内乘以固定基准 `0.001`，
   与透视表面实际深度尺度一致；它允许负数以反转凹凸方向。
@@ -76,12 +83,6 @@ Process Res 的设计依据 DA3 官方实现：API 与 CLI 默认使用 `process
 [输入预处理实现](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)。

-Debug 的 Textured Surface GLB 会把 depth、confidence 与 confidence percentile 写入自定义顶点
-attributes。其他 DA3 Debug 三维输出会同时写出未压缩的 `prediction.attributes.npz`，保存完整
-depth、confidence、intrinsics、extrinsics 与 confidence percentile。当前 trimesh 的 glTF 点图元
-导出器只写 Position/Color，无法可靠把任意 attribute 嵌入点云 GLB，因此点云先以 companion NPZ
-保留完整结构；后续若改为 SnapForm 自有 glTF writer，可再把这些字段直接嵌入点图元。
-
 所有任务使用统一的状态栏进度显示。变化中的阶段说明显示在右侧的进度条内部，取消按钮
 位于进度条右侧。状态字段支持阶段、当前操作与预计剩余秒数，界面统一组合为紧凑文案并保证
 进度单调递增。任务进程与 Server 请求在后台启动，按钮点击后立即进入进度状态。Image Depth 的阶段包括 Environment 启动、输入准备、模型加载、深度估算、缓存
@@ -130,9 +131,10 @@ Depth Plane 使用 `O DA3 Depth Plane Layer` 材质组，并把背景剔除、
 材质组、Principled BSDF 与 Material Output，方便继续调整。
 Depth Plane 的 Bump Height 直接使用材质组的 `Color` 输入，只受独立的 `Bump Scale` 影响，不使用深度贴图，
 也不经过 `Displacement` 模式开关、`Depth Scale` 或 `Background Depth`；材质 Displacement 仍使用这些参数处理后的深度。
-无论选择哪种置换方式，原始彩色贴图都会连接
-Principled BSDF 的 `Base Color`，并通过
-`Bump.Height → Bump.Normal → Principled.Normal` 提供表面细节。Bump 的基础 Distance 为
+无论选择哪种置换方式，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`。
@@ -162,23 +164,20 @@ Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PN
 `depth.0001.exr`、`frame.0001.jpg`（`.frame`）或 `foreground.0001.png`，并在每帧保留原始
 浮点深度；保存 `.blend` 后再次打开仍需对应 job 目录存在。

-选择 PLY 后，模型菜单只会提供 `DA3 Giant 1.1` 和
-`DA3 Nested Giant Large 1.1`。Small 和 Base 没有 Gaussian head，无法由
-DA3 生成 `gs_ply`。
-
 每个 Server Job 被接受时，Job Runtime 在 Runtime Storage Root 的 `jobs/` 下创建一个独立文件夹。文件夹名是 32 位 opaque Job ID，不包含任务类型或对象名称。执行逻辑从 `JobContext.directory` 获取路径，输出产物直接写入该目录。

 Blender 为 Packed Image 或序列帧生成的输入副本先保存在系统临时目录，Server 读取完成后由 Blender 清理，不归档到 Job 目录。普通磁盘文件和视频仍直接读取原文件。Server 日志统一写入 `server.log`，进度只保存在 Server 内存中。Environment Bootstrap 使用 Storage Root 下的 `install.log` 与临时的 `install-status.json`，不创建 Job 目录。

-与几何输出相关的 Job Type 为 `generate-da3-depth`、`generate-moge2-depth`、`generate-da3-surface`、`generate-moge2-surface`、`debug-da3` 与 `debug-moge2`。每种 Job 只接收对应模型与输出所需的参数。
+正式几何输出由 `generate-depth` 与 `generate-surface` 负责。Debug 使用彼此独立的
+`debug-da3`、`debug-moge2` 与 `debug-ben2`，只保存模型 API 的直接返回，不进入 Geometry 或
+Surface 输出流程。

-DA3 ONNX exporter 产生的 `depth_vis/`、`exports/mini_npz/` 会在完成后自动平铺，
-不会保留只含一层产物的子目录：
+Job 目录中的典型正式产物如下：

 ```text
 <opaque-job-id>/
-├── scene.glb、*.ply、*.jpg 或 results.npz
-└── 其它对应 Debug 格式的产物
+├── results.npz、mesh.npz、texture.png 或 normal.png
+└── prediction.npz             Debug 原始 API 返回

 <opaque-job-id>/
 ├── foreground.png            单图结果