AnyImage/docs/depth-plane.md

Depth Plane

Image Empty 转深度面片

1. 在 3D View 选中 Object Type = Empty、Display As = Image 的对象。
2. 右键打开 SnapForm 子菜单并选择 Convert to Depth Plane，通过 Depth from 选择深度来源：
   • DA3：显示 Model、Use Ray Pose 和 Resolution Scale。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 进程内用 points 和官方 utils3d.build_mesh_from_map 直接生成 mesh.npz。Debug 始终保留原始 results.npz，并按 Output Format 单独生成 Maps、纹理 GLB 或彩色 PLY。
   • Original：直接把原图作为深度贴图，不显示估算参数。仅在开启 Remove Background 时运行 BEN2 取得前景 Alpha；视频或序列帧按需同时抽取原始帧与前景序列，把原始帧作为 .depth 序列。 Original 是默认深度来源。选择 DA3 时，其 Model、Use Ray Pose 与 Resolution Scale 参数会集中显示在独立边框中。Remove Background 与 Unshaded 直接显示，不再使用 Options 折叠； Keep Original 默认关闭，并在分割线下方保持为最后一项。仅当开启 Remove Background 时才需要 BEN2 Base，并把 .foreground 的 Alpha 作为独立 Mask，不在 Service 中改写深度值。保存 .foreground 时保留 BEN2 Alpha，但 RGB 使用未经修改的原始输入； 因此材质直接用 .foreground 同时提供颜色和 Mask，不再额外加载原图 Image Texture。 Image Empty 引用视频或序列帧时，DA3 与 MoGe-2 会按 Empty 的 Image Frames 数值逐帧估计 深度（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset，与背景蒙版范围一致； Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty 一致；Original 模式的视频或序列帧使用 frame.0001.jpg 等原图序列作为颜色与深度， foreground.0001.png 只提供前景 Alpha。 DA3 的深度仍以 EXR 序列帧（depth.0001.exr 起）保存在 job 目录根下；MoGe-2 分别使用 moge_depth、moge_mask 与 moge_normal EXR 序列。 Unshaded、Remove Background 与 Keep Original 均默认关闭，因此默认删除原对象。
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 位移、mask 删点和材质设置；材质使用 O MoGe2 Depth Plane Layer，直接接入 模型 normal，不携带 DA3 的材质置换与背景深度分支。DA3 修改器公开以下参数：
   • 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 与 Foreground Image 是修改器隐藏数据输入， 由导入流程自动设置。 视频与序列帧还会为 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 一样随场景帧刷新。