Add tests for foreground preservation and refactor geometry node asset

- Implement test to ensure foreground preserves source RGB and Ben2 alpha in WorkerTest.
- Remove outdated tests related to background distance and original background depth.
- Update geometry node asset to reflect new naming conventions and structure.
- Introduce validation for depth plane asset, ensuring correct input/output configurations and attribute handling.
- Adjust confidence and edge parameters in geometry node asset to support a wider range of values.

docs/technical.md

@@ -30,17 +30,16 @@
 - Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
   `(Missing)`，已下载模型保持原名
 - 分别调用 DA3 的 `glb`、`gs_ply`、`depth_vis` 和 `mini_npz` exporter
-- `Textured Mesh (GLB)` 直接使用 DA3 Prediction 中的深度、置信度和相机参数，把相邻像素
+- `Textured Surface (GLB)` 直接使用 DA3 Prediction 中的深度、置信度和相机参数，把相邻像素
   组成三角面并写入 `mesh.glb`；每个输入帧生成一张独立纹理网格，不做多视图融合
 - Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
 - Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
 - Image Empty 支持视频与序列帧输入：`Convert to Depth Plane` 逐帧估计深度，
   `Remove Background` 逐帧抠图，入口保持不变
 - 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）；
-  Displace 修改器与材质 Image Texture 均可按场景帧播放序列帧
-- 使用浮点深度贴图、Simple Subdivision、Displace Modifier 和原图 Bump
-  构建立体面片
-- 转换对话框可选择推理模式、处理分辨率和面片网格细分
+  Geometry Nodes 与材质 Image Texture 均可按场景帧播放序列帧
+- 使用浮点深度贴图、`O DA3 Depth Plane` Geometry Nodes 和原图 Bump 构建立体面片
+- 转换对话框选择推理模式和处理分辨率；细分、背景与置换方式在 Geometry Nodes 修改器中调整
 - Debug 的 DA3 输出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不修改当前场景
 - 完整保留每次任务生成的所有官方文件
 - 安装和模型下载使用后台子进程；推理提交给常驻 AI Host，状态栏实时显示阶段、百分比进度条与取消按钮
@@ -111,27 +110,20 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
      `Host > Models` 下载所选模型，并固定使用 `process_res_method="upper_bound_resize"`；设备和参考视图策略
      继续使用场景设置。Model 下拉菜单只列出已经下载的 DA3 模型；若没有可用模型，对话框会引导到
      `Host > Models` 下载。
-    - `Original`：直接把原图作为深度贴图，不显示估算参数。单张图片不启动 Runtime；视频或
-      序列帧会启动轻量抽帧任务，把帧抽出来作为 `.depth` 序列（比直接引用视频稳定）。
+    - `Original`：直接把原图作为深度贴图，不显示估算参数。单张图片运行 BEN2 取得前景 Alpha；视频或
+      序列帧同时抽取原始帧与前景序列，把原始帧作为 `.depth` 序列。
    `Original` 是默认深度来源。选择 `AI Generated` 时，其 Model、Use Ray Pose 与 Resolution Scale
-   参数会集中显示在独立边框中。两种模式都有默认折叠的 Options，内部依次为 Displace via、
-   Subdivision、Background Depth Distance 和 Unshaded；Delete Original 保持在折叠项外。
-   Background Depth Distance 默认 `0`，表示不剔除背景。大于 `0` 时需要 `BEN2 Base`，并使用固定值
-    处理 alpha 背景。AI Generated 的 DA3 仍完全使用原图估算深度，推理后先把全部 depth 转换为
-    `1 - DA3 depth`，再只把全透明区域设为 `-Background Depth Distance`；平面尺寸仍使用转换前的深度参考值，
-    同时把比背景更远的前景值钳制到背景平面，并强制最外侧 1 像素为背景距离，以减少边缘墙面和毛刺；
-    因此背景赋值不会缩放前景。Original 则把原图前景转为灰度深度，并把全透明区域设为该距离的负值，
-    生成浮点 `.depth` 图片或 EXR 序列。两种模式都会使用 `.foreground` 作为材质颜色，不修改源
-    Image Empty 的 Image datablock，也不根据每帧前景深度动态调整背景值。
+   参数会集中显示在独立边框中。两种模式都有默认折叠的 Options，内部只保留 `Unshaded`；
+   `Delete Original` 保持在折叠项外。转换固定需要 `BEN2 Base`，只把 `.foreground` 的 Alpha 作为独立
+   Mask，不在 Host 中改写深度值。保存 `.foreground` 时保留 BEN2 Alpha，但 RGB 使用未经修改的原始输入；
+   因此材质直接用 `.foreground` 同时提供颜色和 Mask，不再额外加载原图 Image Texture。
     Image Empty 引用视频或序列帧时，AI Generated 会按 Empty 的 Image Frames 数值逐帧估计
     深度（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset，与背景蒙版范围一致；
     Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty
-    一致；Original 模式在 Distance 为 `0` 时，单帧复制原图作为 `.depth`，视频或序列帧则使用
-    `frame.0001.jpg` 等原图序列。Distance 大于 `0` 时改为生成包含固定负背景值的浮点 `.depth` 或
-    `depth.0001.exr` 序列。材质颜色在启用固定背景距离时使用 `foreground.0001.png` 序列。
+    一致；Original 模式的视频或序列帧使用 `frame.0001.jpg` 等原图序列作为颜色与深度，
+    `foreground.0001.png` 只提供前景 Alpha。
     AI Generated 的深度仍以 EXR 序列帧（`depth.0001.exr` 起）保存在 job 目录根下。
-   Displace via 可选 `Modifier`（默认）或 `Material`；
-   Unshaded 默认关闭；Subdivision 默认为 `5`，并默认删除原对象。
+   `Unshaded` 默认关闭，并默认删除原对象。
 3. AI Generated 完成后会自动创建面片。面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
    Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
    的可见尺寸、Offset 与 Transform。AI Generated 会把用于匹配画面尺寸的缩放预乘到 `.depth` 数值，
@@ -139,23 +131,48 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
    开启 `Delete Original` 时，成功生成后
    删除源 Empty。生成面片 Object 使用源 Empty 的原名；关闭 `Delete Original` 时不处理
    同名冲突，由 Blender 自动为生成面片追加编号。
-4. 短边分段数为 `2^Subdivision`，长边分段数根据图像宽高比取最接近的整数。例如高:宽为
-   `2:3`、Subdivision 为 `1` 时，直接生成 `2×3` 个面；Subdivision 为 `3` 时生成
-   `8×12` 个面。随后的 Simple Subdivision 修改器使用原生名称，Viewport Levels 固定为
-   `1`，Render Levels 固定为 `2`，不再随 Resolution Scale 或 Subdivision 动态变化。
+4. Blender 只创建保留图像纵横比的最低密度基础网格，再把 `O DA3 Depth Plane` 作为 Geometry Nodes
+   修改器添加到对象。节点组与 `O Refine DA3 Surface` 一同保存在 `O_SnapForm.blend`，关闭
+   `show_group_selector`，不为每个对象复制节点组。修改器公开以下参数：
+   - `Subdivision`：默认 `5`。节点读取基础平面的 Bounding Box，短边分段数为 `2^Subdivision`，
+     长边按宽高比计算并四舍五入；例如 16:9 图片在等级 `5` 时生成 `57×32` 个面；
+   - `Remove Background`：默认关闭的 Panel Toggle。关闭时折叠隐藏 `Background Depth`，开启后才显示；
+     它不删除几何，而是通过点域的
+     `o_remove_background` Attribute 控制材质 Alpha 是否乘以前景 Mask；
+   - `Background Depth`：默认 `0`，允许正负值。只有开启 `Remove Background` 时，前景 Mask 外的
+     结构或材质置换才使用该值；关闭时所有像素继续使用原始深度；
+   - `Displacement`：菜单包含 `Geometry`（默认）与 `Material`。`Geometry` 在节点组内沿法线修改网格，
+     `Material` 保持网格平面并启用材质置换。
+   - `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 仍保留柔和边缘。材质置换使用相同的二值和钳制顺序。
+   节点组还会把 `o_material_displacement` 与 `o_background_depth` 写入点域，材质通过
+   `Geometry` 类型的 Attribute 节点读取。点域会为顶点保存重复值，但能在应用修改器后继续保留参数；
+   相比自适应网格本身，其占用很小。Depth Image 与 Foreground Image 是修改器隐藏数据输入，
+   由导入流程自动设置。
+   视频与序列帧还会为 Depth 与 Foreground 共同写入隐藏的 `Frame Start`、`Frames` 与 `Cyclic`。
+   导入内容已经是截取后的帧，因此 Offset 在节点组内恒定为 `0`，不再作为输入。节点组使用 Scene Time
+   计算从 `1` 开始的 Image Texture Frame：场景帧与 Start 都为 `1` 时读取图片第 `1` 帧；非循环输入
+   钳制到有效范围；循环输入使用 Floored Modulo，让 `Frame Start` 前后的负、正相对帧都映射到
+   `1…Frames`，因此开始帧之前也会循环播放。Geometry 置换会像材质 Image Texture 一样随场景帧刷新。
 
 ## Image Empty 转透视网格
 
 1. 在 3D View 选中仅包含一帧的 Image Empty，右键打开 `SnapForm` 子菜单并选择
-   `Convert to Mesh`。该入口独立于
+   `Convert to Surface`。该入口独立于
    `Convert to Depth Plane`，当前不处理视频或序列帧。
 2. Host 请求 DA3 的 `depth`、`conf` 与 `intrinsics`，同时固定运行 BEN2 取得前景 alpha。Depth 不做
    smoothing，也不在 Host 中剔面或减面；Host 只反投影完整有效拓扑，并计算 confidence percentile、
    camera-space edge stretch 与 background 标记。
-3. Blender 把勾选 `Usage > Modifier` 的 `O Refine DA3 Mesh` 节点组直接作为 Geometry Nodes 修改器
-   添加到 Mesh，不另设修改器名称。节点组内没有子节点组，依次完成：
+3. Blender 把勾选 `Usage > Modifier` 的 `O Refine DA3 Surface` 节点组直接作为 Geometry Nodes 修改器
+   添加到 Surface，不另设修改器名称。节点组内没有子节点组，依次完成：
    - 修改器顶层依次显示 `Resolution`、`Relax Iterations`、`Smooth`；默认展开的 `Culling` Panel
-     包含 `Confidence`、`Stretch`、`Background`。`Stretch = 100%` 明确选择全部面，剔面后同时删除
+     包含 `Confidence`、`Stretch`、`Background`。两个百分比输入都使用 `0–100` 的节点值，并在组内
+     转换为 `0–1` 阈值；`Stretch = 100%` 明确选择全部面，剔面后同时删除
      Face Count 为零的孤立顶点；
    - 每轮 Remesh Iteration 依次执行 Connected Merge、循环拓扑修复与一次 Smooth，使新拓扑在进入下一轮
      Merge 前先稳定；拓扑修复删除非流形面、单面拓扑和小面积 mesh islands；
@@ -166,7 +183,7 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
      `Smooth` 程度系数；节点组不再额外执行 Flip Faces；
    - 从修改前的原始表面以 nearest-surface 重新采样 `UVMap`，最终明确写为 Corner 域 `2D Vector`。
 4. 节点组随插件放在 `O_SnapForm.blend`。Blender 4.5 首次 Append 后复用同一 datablock；
-   Blender 5.0 以 linked ID 载入后调用 Pack，后续 Mesh 继续复用。插件不会为每个 Mesh 新建节点组，
+   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 分区摆放；各区就近使用独立的
@@ -175,8 +192,8 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
    拓扑、投影 UV/attributes、写出网格。状态栏显示 `Post-processing n/6: ...`。
 6. Host 在 job 根目录写出 `mesh.npz` 与 `texture.png`。NPZ 保存 camera-space `vertices`、
    `faces`、`uv`、`intrinsics`、`image_size` 与有效深度中位数 `reference_depth`。Blender 读取这些
-   数据后直接创建 Mesh 与原图材质，不需要 Open3D 或 OpenCV 进入 Blender Python 环境。
-   Mesh 保留下列结构化 attributes：
+   数据后直接创建 Surface 与原图材质，不需要 Open3D 或 OpenCV 进入 Blender Python 环境。
+   Surface 保留下列结构化 attributes：
    - 点域：`o_depth`、`o_confidence`、`o_confidence_percentile`、`o_background`；
    - 面域：`o_face_confidence`、`o_edge_stretch`、`o_background_face`。
 7. 网格以 `reference_depth` 截面匹配 Image Empty 的显示矩形：该截面的投影四角与 Empty 的可见
@@ -185,12 +202,13 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
    观察相机，启用 Backface Culling 时可从正面看到。
 8. 转换对话框不再提供后处理参数，只保留模型设置、`Create Matching Camera`、`Unshaded` 与
    `Delete Original`。`Unshaded` 使用与 Depth Plane 相同的 Emission/Transparent 材质路径；普通材质的
-   Bump Distance 按 `abs(object.scale.z) × camera scale_z` 缩放，与透视网格实际深度尺度一致。
-   相机默认关闭；开启后会在 Empty 局部 `+Z` 侧创建一台朝向局部 `-Z` 的透视相机，并成为生成 Mesh
+   Bump Scale 按 `abs(object.scale.z) × camera scale_z` 设置，并在材质组内乘以固定基准 `0.001`，
+   与透视表面实际深度尺度一致；它允许负数以反转凹凸方向。
+   相机默认关闭；开启后会在 Empty 局部 `+Z` 侧创建一台朝向局部 `-Z` 的透视相机，并成为生成 Surface
    的子级，使二者移动时保持投影关系。开启 `Delete Original` 时，网格成功创建后删除源 Empty。
-   网格、材质与相机会归入同一个 `Convert to Mesh` Undo 步骤。
+   表面、材质与相机会归入同一个 `Convert to Surface` Undo 步骤。
 
-Debug 的 Textured Mesh GLB 会把 depth、confidence 与 confidence percentile 写入自定义顶点
+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
@@ -224,16 +242,19 @@ Height    = sqrt(Area / Aspect)
 `snapform_camera_plane_height`，便于检查实际采用的
 参考深度和尺寸。
 
-选择 `Modifier` 时，AI Generated 的 Displace Modifier 深度贴图使用 `Extension = Extend`，
-`Strength` 固定为 `1`、`Midlevel` 固定为 `0`。Original 把原图指定给 Displace Texture，并设置
-`Texture Coordinates = UV`、`Midlevel = 0`；其余修改器设置保留 Blender 默认值。
-视频与序列帧生成的深度贴图是 SEQUENCE Image；Displace 修改器的 Texture 与材质的 Image Texture
-节点都支持序列帧，通过 image_user 的 Frames / Offset / Start 设置把第 i 帧映射到场景
-`Start+i` 帧（Start 沿用 Empty 的 Start），并启用 Auto Refresh，播放时随场景帧逐帧更新。
-选择 `Material` 时，不创建 Displace Modifier；深度 Image Texture 的 Color 连接到 Displacement
-节点的 Height，再连接 Material Output 的 Displacement，并把材质 Surface Displacement 设置为
-`Displacement Only`。AI Generated 与 Original 都使用 `Midlevel = 0`、`Scale = 1`，与对应修改器值一致。
-无论选择哪种呈现方式，原始彩色贴图都会连接
+材质始终导入深度 Image Texture，并连接到 Displacement 节点和 Material Output；材质 Surface
+Displacement 设置为 `Displacement Only`，AI Generated 与 Original 都使用 `Midlevel = 0`、`Scale = 1`。
+`o_material_displacement` 为 `False` 时，材质把 Height 乘以零，置换只在几何节点中生效；为 `True` 时，
+几何节点关闭结构置换，材质 Height 恢复。开启 `Remove Background` 时，前景 Alpha 同时用于选择
+原始深度或有符号的 `Background Depth`，使两种置换路径保持一致；关闭时背景深度不参与计算。
+视频与序列帧的颜色、深度与前景 Image Texture
+通过 image_user 的 Frames / Offset / Start 把第 i 帧映射到场景 `Start+i` 帧，并启用 Auto Refresh。
+颜色贴图到 Principled BSDF 之间使用独立的 Shader Node Group。Surface 使用 `O DA3 Surface`；
+Depth Plane 使用显示名为 `O DA3 Depth Plane` 的材质组，并把背景剔除、背景深度与材质置换 Attribute
+读取全部收进组内。两者都依次接收 `Color`、`Alpha`、Float 类型的 `Depth`、`Bump Scale`，输出 `Color`、
+`Roughness`、`Alpha`、`Normal`、`Displacement`。Surface 把原图 Color 同时送入 `Color` 与 `Depth`，
+保持图像 Bump 效果。外层材质只保留贴图、材质组、Principled BSDF 与 Material Output，方便继续调整。
+无论选择哪种置换方式，原始彩色贴图都会连接
 Principled BSDF 的 `Base Color`，并通过
 `Bump.Height → Bump.Normal → Principled.Normal` 提供表面细节。Bump 的基础 Distance 为
 `0.001`，会乘以面片 Transform 的统一缩放倍率。原图 Color 还会经过 `Float Curve` 连接到
@@ -241,21 +262,18 @@ Principled BSDF 的 `Roughness`，曲线两端输出分别为 `0.5` 和 `0.1`；
 Principled BSDF 默认值 `1.5`。
 开启 `Unshaded` 后，原图 Color 连接 Emission，原图 Alpha 作为 Mix Shader 系数，在
 Transparent BSDF 与 Emission 之间混合后连接 Material Output；不创建 Principled BSDF、Bump 或
-Float Curve。若 Displace via 选择 `Material`，深度贴图与 Displacement
-节点仍会保留并连接 Material Output 的 Displacement。
+Float Curve。`Remove Background` 开启时，原图 Alpha 会再乘以前景 Mask Alpha；关闭时仍完整显示原图。
 
 这里的“原始距离”是 DA3 模型输出的尺度。普通 Small、Base、Large 和 Giant 模型的深度不应
 被解释为现实世界的米；需要现实尺度时应选择带 metric depth 的
 `DA3 Nested Giant Large 1.1`。此外，当前结果仍是固定 XY 平面上的深度位移面，不是使用
-相机内参逐像素反投影得到的完整 camera-space 网格；中位深度截面为现有 Displace Modifier
-工作流提供正确的整体高宽尺度。
+相机内参逐像素反投影得到的完整 camera-space 网格；中位深度截面为 Geometry Nodes
+深度面片提供正确的整体高宽尺度。
 
 生成完成后会直接创建面片，不提供缓存重建入口或单独的导入参数。重新选择
 `Convert to Depth Plane` 会按当前 Depth from 再次转换。
-面片、深度 Image、Texture 与 Material 会在同一个 Blender Undo 步骤中创建；转换完成后执行
+面片、深度 Image、前景 Image、Material 与 Geometry Nodes 修改器会在同一个 Blender Undo 步骤中创建；转换完成后执行
 `Ctrl+Z` 会完整撤销本次转换，不会越过转换去回退更早的 Image Empty 操作。
-Background Depth Distance 大于 `0` 时，`.foreground` Image、Original 浮点深度、Pack 和深度面片生成也属于
-同一个 Undo 步骤。
 
 Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PNG 交给 DA3，
 不会 Unpack 或修改源 Image；任务结束后自动删除临时文件。普通图片仍直接读取源文件。DA3 的原始
@@ -290,7 +308,6 @@ Blender 为 Packed Image 或序列帧生成的输入副本也归档到对应 job
 - `remove-background`
 - `remove-image-background`
 - `generate-original-depth-plane`
-- `extract-original-frames`
 
 DA3 官方 exporter 产生的 `gs_ply/`、`depth_vis/`、`exports/mini_npz/` 会在完成后自动平铺，
 不会保留只含一层产物的子目录：
@@ -336,10 +353,10 @@ CC BY-NC 4.0，仅限非商业用途。
 - Gaussian Splats (PLY)：DA3 `gs_ply`，同时传入 `infer_gs=True`
 - Depth Preview (Images)：DA3 `depth_vis`
 - Depth Data (NPZ)：DA3 `mini_npz`
-- Textured Mesh (GLB)：SnapForm 根据 DA3 Prediction 构建并输出 `mesh.glb`
+- Textured Surface (GLB)：SnapForm 根据 DA3 Prediction 构建并输出 `mesh.glb`
 
 Point Cloud 专属设置仅在对应类型下显示，`gs_views_interval` 仅用于 Gaussian Splats。
-Textured Mesh 使用 0–100% 的 Confidence Threshold 删除置信度最低的一定比例：
+Textured Surface 使用 0–100% 的 Confidence Threshold 删除置信度最低的一定比例：
 
 - `process_res=504`
 - `process_res_method="upper_bound_resize"`