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 和 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。颜色贴图会按当前场景的 View Transform 选择对应输入色彩空间：AgX、ACES 1.3、ACES 2.0、Filmic、Khronos PBR Neutral 分别使用 AgX Base sRGB、ACES 1.3 sRGB、ACES 2.0 sRGB、Filmic sRGB、Khronos PBR Neutral sRGB；无法匹配当前 View Transform 时回退 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 序列。 DA3 与 MoGe-2 的单帧推理进度只显示模型与阶段名称，不追加 1/1；多帧时继续显示当前帧与总数。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 一样随场景帧刷新。