# Depth Plane

## 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，Color Space 固定为 `AgX Base 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`、`moge_mask` 与 `moge_normal` EXR 序列。
   `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 一样随场景帧刷新。