Refactor image mesh processing and background removal functionality

- Updated NODE_GROUP_NAME from "O Refine DA3 Surface" to "O DA3 Surface".
- Introduced `remove_surface_background` function to filter out background faces and compact geometry.
- Enhanced `build_image_mesh` to conditionally remove background faces based on a new property.
- Added `snapform_remove_background` and `snapform_keep_original` properties to operators for better control over background handling.
- Updated UI to reflect new properties and improved resolution scaling logic.
- Refactored tests to cover new background removal functionality and ensure proper geometry handling.
- Adjusted geometry nodes and validation scripts to remove references to background handling.

docs/technical.md

@@ -39,7 +39,7 @@
 - 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）；
   Geometry Nodes 与材质 Image Texture 均可按场景帧播放序列帧
 - 使用浮点深度贴图、`O DA3 Depth Plane` Geometry Nodes 和原图 Bump 构建立体面片
-- 转换对话框选择推理模式和处理分辨率；细分、背景与置换方式在 Geometry Nodes 修改器中调整
+- 转换对话框选择推理模式、处理分辨率与背景移除；细分和置换方式在 Geometry Nodes 修改器中调整
 - Debug 的 DA3 输出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不修改当前场景
 - 完整保留每次任务生成的所有官方文件
 - 安装和模型下载使用后台子进程；推理提交给常驻 AI Host，状态栏实时显示阶段、百分比进度条与取消按钮
@@ -103,18 +103,19 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
 
 1. 在 3D View 选中 `Object Type = Empty`、`Display As = Image` 的对象。
 2. 右键打开 `SnapForm` 子菜单并选择 `Convert to Depth Plane`，通过 `Depth from` 选择深度来源：
-   - `AI Generated`：显示 Model、Use Ray Pose 和 Resolution Scale。实际 Process Res 为图片长边像素数
-     乘以 Resolution Scale；范围为 `0.1–1.0`，默认 `1.0`。计算后的 Process Res 会直接显示在
-     `Resolution Scale (… px)` 标签中。
+   - `AI Generated`：显示 Model、Use Ray Pose 和 Resolution Scale。Process Res 先以原图长边乘以
+     Resolution Scale，再钳制到 `252–1008`，最后对齐到最接近的 `14` 倍数。Resolution Scale 以百分比
+     显示，范围为 `1–100%`，默认 `100%`；界面只在标签中实时显示最终 Process Res。
      转换导出 `mini_npz`，使用前需要在
      `Host > Models` 下载所选模型，并固定使用 `process_res_method="upper_bound_resize"`；设备和参考视图策略
      继续使用场景设置。Model 下拉菜单只列出已经下载的 DA3 模型；若没有可用模型，对话框会引导到
      `Host > Models` 下载。
-    - `Original`：直接把原图作为深度贴图，不显示估算参数。单张图片运行 BEN2 取得前景 Alpha；视频或
-      序列帧同时抽取原始帧与前景序列，把原始帧作为 `.depth` 序列。
+    - `Original`：直接把原图作为深度贴图，不显示估算参数。仅在开启 `Remove Background` 时运行 BEN2
+      取得前景 Alpha；视频或序列帧按需同时抽取原始帧与前景序列，把原始帧作为 `.depth` 序列。
    `Original` 是默认深度来源。选择 `AI Generated` 时，其 Model、Use Ray Pose 与 Resolution Scale
-   参数会集中显示在独立边框中。两种模式都有默认折叠的 Options，内部只保留 `Unshaded`；
-   `Delete Original` 保持在折叠项外。转换固定需要 `BEN2 Base`，只把 `.foreground` 的 Alpha 作为独立
+   参数会集中显示在独立边框中。`Remove Background` 与 `Unshaded` 直接显示，不再使用 Options 折叠；
+   `Keep Original` 默认关闭，并在分割线下方保持为最后一项。仅当开启 `Remove Background` 时才需要
+   `BEN2 Base`，并把 `.foreground` 的 Alpha 作为独立
    Mask，不在 Host 中改写深度值。保存 `.foreground` 时保留 BEN2 Alpha，但 RGB 使用未经修改的原始输入；
    因此材质直接用 `.foreground` 同时提供颜色和 Mask，不再额外加载原图 Image Texture。
     Image Empty 引用视频或序列帧时，AI Generated 会按 Empty 的 Image Frames 数值逐帧估计
@@ -123,40 +124,39 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
     一致；Original 模式的视频或序列帧使用 `frame.0001.jpg` 等原图序列作为颜色与深度，
     `foreground.0001.png` 只提供前景 Alpha。
     AI Generated 的深度仍以 EXR 序列帧（`depth.0001.exr` 起）保存在 job 目录根下。
-   `Unshaded` 默认关闭，并默认删除原对象。
+   `Unshaded`、`Remove Background` 与 `Keep Original` 均默认关闭，因此默认删除原对象。
 3. AI Generated 完成后会自动创建面片。面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
    Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
    的可见尺寸、Offset 与 Transform。AI Generated 会把用于匹配画面尺寸的缩放预乘到 `.depth` 数值，
    XY 缩放烘焙到 Mesh，Z 不参与平面匹配；最终对象 Scale 为 `(1, 1, 1)`，视觉深度与旧逻辑一致。
-   开启 `Delete Original` 时，成功生成后
-   删除源 Empty。生成面片 Object 使用源 Empty 的原名；关闭 `Delete Original` 时不处理
+   关闭 `Keep Original` 时，成功生成后删除源 Empty。生成面片 Object 使用源 Empty 的原名；开启
+   `Keep Original` 时不处理
    同名冲突，由 Blender 自动为生成面片追加编号。
 4. Blender 只创建保留图像纵横比的最低密度基础网格，再把 `O DA3 Depth Plane` 作为 Geometry Nodes
-   修改器添加到对象。节点组与 `O Refine DA3 Surface` 一同保存在 `O_SnapForm.blend`，关闭
+   修改器添加到对象。节点组与 `O DA3 Surface` 一同保存在 `O_SnapForm.blend`，关闭
    `show_group_selector`，不为每个对象复制节点组。修改器公开以下参数：
-   - `Subdivision`：默认 `5`。节点读取基础平面的 Bounding Box，短边分段数为 `2^Subdivision`，
+   - `Displacement`：位于 Geometry 之后的第一项，菜单包含 `Geometry`（默认）与 `Material`。`Geometry`
+     在节点组内沿法线修改网格，`Material` 保持网格平面并启用材质置换；
+   - `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` 保持网格平面并启用材质置换。
+   - `Background Depth`：默认 `0`，允许正负值，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 与背景深度混合，
+   前景深度先与 `Background Depth` 取 Maximum，再按色彩贴图 Alpha 与背景深度混合，
    深度分支在混合前使用 `Alpha > 0.5` 转为二值 Mask，避免半透明前景被背景深度拉扯；
-   材质表面 Alpha 仍保留柔和边缘。材质置换使用相同的二值和钳制顺序。
+   材质表面 Alpha 同样使用二值 Mask。材质置换使用相同的二值和钳制顺序。
    节点组还会把 `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` 帧；非循环输入
+   视频与序列帧还会为 Depth 与 Foreground 共同写入隐藏的 `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 一样随场景帧刷新。
 
@@ -165,13 +165,17 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
 1. 在 3D View 选中仅包含一帧的 Image Empty，右键打开 `SnapForm` 子菜单并选择
    `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 Surface` 节点组直接作为 Geometry Nodes 修改器
+   对话框中的 Resolution Scale 与 Depth Plane 使用相同设计：原图长边乘以 `1–100%` 的比例后，
+   将实际 Process Res 钳制在 `252–1008` 并按 `14` 对齐。
+2. Host 请求 DA3 的 `depth`、`conf` 与 `intrinsics`。仅在开启 `Remove Background` 时运行 BEN2 取得
+   前景 Alpha，并在输出前删除包含背景顶点的三角面；关闭时不加载 BEN2。Depth 不做 smoothing，Host
+   反投影深度网格，建立源三角面，计算 confidence percentile 与 camera-space edge stretch，并写入
+   基于原图像素坐标的源 `UVMap`。这些步骤只准备修改器的输入网格，不执行 Relax、拓扑修复、平滑、
+   小岛清理或最终 UV 重投影。运行时显示的六个 `Preparing surface data` 步骤均指这段 Host 端源数据准备。
+3. Blender 把勾选 `Usage > Modifier` 的 `O DA3 Surface` 节点组直接作为 Geometry Nodes 修改器
    添加到 Surface，不另设修改器名称。节点组内没有子节点组，依次完成：
    - 修改器顶层依次显示 `Resolution`、`Relax Iterations`、`Smooth`；默认展开的 `Culling` Panel
-     包含 `Confidence`、`Stretch`、`Background`。两个百分比输入都使用 `0–100` 的节点值，并在组内
+     只包含 `Confidence` 与 `Stretch`。两个百分比输入都使用 `0–100` 的节点值，并在组内
      转换为 `0–1` 阈值；`Stretch = 100%` 明确选择全部面，剔面后同时删除
      Face Count 为零的孤立顶点；
    - 每轮 Remesh Iteration 依次执行 Connected Merge、循环拓扑修复与一次 Smooth，使新拓扑在进入下一轮
@@ -188,8 +192,8 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
    修改器关闭 `show_group_selector`。`Fix Topology` 位于默认折叠的 `Options` Panel。
    节点图按 Culling、Remesh、Topology Fix、Island Cleanup 与 UV 分区摆放；各区就近使用独立的
    Group Input，并隐藏没有连线的接口，避免跨越整个节点图的输入连线。
-5. Host 准备过程固定显示 6 个编号阶段：验证 DA3 数据、反投影、准备 DA3/BEN2 attributes、构建原始
-   拓扑、投影 UV/attributes、写出网格。状态栏显示 `Post-processing n/6: ...`。
+5. Host 准备过程固定显示 6 个编号阶段：验证 DA3 数据、反投影、准备 DA3 与可选 BEN2 数据、构建原始
+   源三角面、源 UV/attributes、写出网格。状态栏显示 `Preparing surface data n/6: ...`。
 6. Host 在 job 根目录写出 `mesh.npz` 与 `texture.png`。NPZ 保存 camera-space `vertices`、
    `faces`、`uv`、`intrinsics`、`image_size` 与有效深度中位数 `reference_depth`。Blender 读取这些
    数据后直接创建 Surface 与原图材质，不需要 Open3D 或 OpenCV 进入 Blender Python 环境。
@@ -200,14 +204,26 @@ Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因
    边界重合，主点同时匹配 Empty Offset。网格对象直接沿用源 Empty 的 `matrix_world`，因此位置、旋转、
    缩放及父级关系产生的世界变换保持一致。更近的顶点沿 Empty 局部 `+Z` 方向凸出，三角面正面朝向
    观察相机，启用 Backface Culling 时可从正面看到。
-8. 转换对话框不再提供后处理参数，只保留模型设置、`Create Matching Camera`、`Unshaded` 与
-   `Delete Original`。`Unshaded` 使用与 Depth Plane 相同的 Emission/Transparent 材质路径；普通材质的
+8. 转换对话框不再提供后处理参数，只保留模型与 Resolution Scale 设置、`Create Matching Camera`、
+   `Remove Background`、`Unshaded`，以及分割线下方的 `Keep Original`。背景移除默认关闭；开启后 Host
+   使用 BEN2，并在写出 Surface 前直接删除背景三角面，不再由 Geometry Nodes 的 Background 开关处理。
+   `Unshaded` 使用与 Depth Plane 相同的 Emission/Transparent 材质路径；普通材质的
    Bump Scale 按 `abs(object.scale.z) × camera scale_z` 设置，并在材质组内乘以固定基准 `0.001`，
    与透视表面实际深度尺度一致；它允许负数以反转凹凸方向。
    相机默认关闭；开启后会在 Empty 局部 `+Z` 侧创建一台朝向局部 `-Z` 的透视相机，并成为生成 Surface
-   的子级，使二者移动时保持投影关系。开启 `Delete Original` 时，网格成功创建后删除源 Empty。
+   的子级，使二者移动时保持投影关系。关闭 `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)。
+
 Debug 的 Textured Surface GLB 会把 depth、confidence 与 confidence percentile 写入自定义顶点
 attributes。其他 DA3 Debug 三维输出会同时写出未压缩的 `prediction.attributes.npz`，保存完整
 depth、confidence、intrinsics、extrinsics 与 confidence percentile。当前 trimesh 的 glTF 点图元
@@ -245,24 +261,27 @@ Height    = sqrt(Area / Aspect)
 材质始终导入深度 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`，使两种置换路径保持一致；关闭时背景深度不参与计算。
+几何节点关闭结构置换，材质 Height 恢复。色彩贴图的 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`，
+颜色贴图到 Principled BSDF 之间使用独立的 Shader Node Group。Surface 使用 `O DA3 Surface Layer`；
+Depth Plane 使用 `O DA3 Depth Plane Layer` 材质组，并把背景剔除、背景深度与材质置换 Attribute
+读取全部收进组内。两者都依次接收 `Color`、`Alpha`、Float 类型的 `Depth`、`Bump Scale`。
+`O DA3 Surface Layer` 只输出 `Color`、`Roughness`、`Alpha` 与 `Normal`，不创建 Displacement 节点或输出；
+`O DA3 Depth Plane Layer` 另外输出 `Displacement`。Surface 把原图 Color 同时送入 `Color` 与 `Depth`，
 保持图像 Bump 效果。外层材质只保留贴图、材质组、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 为
 `0.001`，会乘以面片 Transform 的统一缩放倍率。原图 Color 还会经过 `Float Curve` 连接到
 Principled BSDF 的 `Roughness`，曲线两端输出分别为 `0.5` 和 `0.1`；材质 IOR 保持
 Principled BSDF 默认值 `1.5`。
-开启 `Unshaded` 后，原图 Color 连接 Emission，原图 Alpha 作为 Mix Shader 系数，在
+开启 `Unshaded` 后，色彩贴图 Color 连接 Emission，二值 Alpha 作为 Mix Shader 系数，在
 Transparent BSDF 与 Emission 之间混合后连接 Material Output；不创建 Principled BSDF、Bump 或
-Float Curve。`Remove Background` 开启时，原图 Alpha 会再乘以前景 Mask Alpha；关闭时仍完整显示原图。
+Float Curve。开启 `Remove Background` 时色彩贴图使用 BEN2 输出；关闭时使用原图。
 
 这里的“原始距离”是 DA3 模型输出的尺度。普通 Small、Base、Large 和 Giant 模型的深度不应
 被解释为现实世界的米；需要现实尺度时应选择带 metric depth 的