AnyImage/openspec/changes/normalize-moge-alpha-depth/design.md

Context

Cutout Job 会把最终 Region 图像交给 MoGe-2。Remove Background 路径会清除全透明像素下的 RGB，Fit to Foreground 路径则可能保留隐藏 RGB；MoGe-2 只读取 RGB，因此两条业务路径当前并不等价。

几何预测的另一处边界也不统一：MoGe-2 先返回专用 Prediction，Normal Writer 直接读取它，Depth Writer 才临时转换为 GeometryFrame；DA3 则有另一套转换入口。这样 GeometryFrame 没有真正成为模型预测与几何产物之间的稳定协议。

MoGe-2 返回连续的 Depth/Points Field 和原始 Mask。当前 Depth Writer 会按有效性 Mask 清零 RGB，而 Depth Surface 线性采样 RGB、不读取 Alpha，因此 Mask 边界的零坐标会把网格拉向相机原点。

Goals / Non-Goals

Goals:

• 以 MoGe-2 单帧预测的数据类型重建 GeometryFrame，并让 MoGe-2 与 DA3 都通过模型适配器产出该类型。
• 让 Depth EXR、Normal Texture 和 depth.json 只消费 GeometryFrame，不直接依赖模型专用预测结构。
• 让所有 MoGe-2 调用在同一个 Server 边界获得确定的黑底 RGB 输入。
• 让 Depth EXR 分别表达连续数值场与原始模型 Mask，两者互不改写。
• 保留严格的 Metadata 校准筛选，并阻止非有限数值进入 Blender。

Non-Goals:

• 不修改 BEN2、MoGe-2 或 DA3 模型实现及其推理分辨率。
• 不改变 Depth EXR 文件名、尺寸、RGBA 通道布局或节点组接口。
• 不用输入 Alpha 覆盖模型 Mask，也不在本次变更中让 Geometry Nodes 按 Alpha 丢弃点。
• 不把 DA3 恢复为当前生产路径；仅保持其适配器与统一协议可用、可测试。

Decisions

1. GeometryFrame 是单帧几何预测协议

GeometryFrame 按 MoGe-2 单帧结果定义：

• depth: ndarray[H, W]，必需的 float32 深度场；
• normal: ndarray[H, W, 3] | None，MoGe-2 提供，DA3 可为空；
• validity: ndarray[H, W]，必需的 float32 模型有效性信号；MoGe-2 的原始 Mask 转换为 0/1，DA3 保存原始连续 Confidence；
• intrinsics: ndarray[3, 3]，必需的 float32 像素坐标内参；
• points: ndarray[H, W, 3] | None，可选的 float32 相机空间点场；

构造时校验 dtype、维度和同帧空间尺寸，但不在容器内改写预测值。validity 是唯一存储的模型有效性信号；不再同时保存 mask、confidence 和派生的 valid_mask，避免相同职责出现多个可漂移来源。

MoGe-2 的生产推理入口直接返回一组 GeometryFrame，在适配器内完成 batch 拆分、Mask 到 Validity 的转换和内参像素化。用于调试 NPZ 的原始单次推理入口继续返回模型原始字典，因为它不是 Artifact 生产边界。DA3 保留原始调试推理，并提供同样的逐帧适配器：normal=None，从深度和内参生成 Points，并把 Confidence 作为连续 Validity。

不选择在通用层保留 MoGe-2 Prediction 再二次转换，因为这会继续允许 Writer 绕过统一协议。也不把 GeometryFrame 限定为 MoGe-2 类型，避免 DA3 和后续模型各自复制 Artifact 逻辑。

2. 所有几何 Artifact Writer 只消费 GeometryFrame

Vector Depth Writer 从 frame.points 和 frame.validity 写 EXR；Z Depth Writer 从 frame.depth 和 frame.validity 写 EXR；Normal Writer 从 frame.normal 生成贴图；Metadata Writer 从 frame.depth、frame.intrinsics 和调用方提供的业务 Region Mask 计算 depth.json。

Writer 只依赖通用 GeometryFrame，不导入 moge2 或 da3。缺少所需可选字段时明确失败，例如没有 points 不能写 Vector Depth，没有 normal 不能写 Normal Texture。Artifact 编排层从 MoGe-2 取得一帧 GeometryFrame 后，把同一对象传给各 Writer，不再读取模型专用属性。

Metadata 所需的校准有效性按使用点计算：正的 frame.validity、有限且为正的 Depth，以及业务 Region Mask 的交集。它不是 GeometryFrame 的第二个持久字段，也不反向影响 EXR Alpha 或 RGB。

3. 在最终 MoGe-2 输入边界统一黑底合成

读取最终 region_image_path 为 RGBA，按输入上限缩放，然后使用 output_rgb = source_rgb * alpha 合成到黑底，并始终写为 Job 内的 RGB PNG。即使无需缩放，也经过相同规范化步骤。

这会让半透明像素保留按 Alpha 衰减后的颜色，并彻底消除 Alpha 为零时隐藏 RGB 的差异。Metadata 和 Normal 输出所需的业务 Alpha 仍从原始 Region 图读取，不从已移除 Alpha 的模型输入读取。

不在 Blender 的 prepare_region_input() 提前处理，因为该入口还服务其他 Job，而且 Fit to Foreground 会在 Server 端重新生成 RGBA，无法形成唯一收口点。

4. Depth RGB 保留连续 Field，Alpha 只记录 frame.validity

Vector/Z Depth Writer 无条件把完整 Points/Depth Field 写入 RGB，并仅把 frame.validity 写入 Alpha。零 Validity 不再导致 RGB 清零，使 Depth Surface 在边缘线性采样时仍能得到连续坐标。

Writer 在创建文件前要求所需 Field 全部有限。Mask 为假不豁免该检查，因为 Geometry Nodes 仍会读取 Mask 外 RGB；NaN/Inf 会传播到网格。有限但非正的 Depth 仍忠实写入，正值条件只属于 Metadata 校准。

不把非有限值替换为零或最近有效值：前者会重新引入相机原点尖刺，后者不再忠实于模型结果。

5. 测试固定协议、工作流等价与连续性

测试分为四层：

1. GeometryFrame 校验，以及 MoGe-2/DA3 适配器的字段、形状、dtype、Validity 映射和批次拆分。
2. 模型输入验证 Alpha 为 0、0.5、1 的黑底合成，并验证不同隐藏 RGB 得到相同透明区输入。
3. Writer 验证只接收 GeometryFrame、Validity 为零时 RGB 保留原值、Alpha 等于 frame.validity、缺字段与 NaN/Inf 明确失败；Normal 和 Metadata 不再读取 MoGe-2 专用结果。
4. Depth Surface 使用边缘 Mask 为假但 XYZ 连续的 Vector Depth，验证求值网格不会聚集到相机原点。

Risks / Trade-offs

• [MoGe-2 返回类型变化会影响调用方] → 生产调用集中在 Artifact 编排层；一次性迁移并删除旧 Prediction/转换入口，不保留兼容层。
• [GeometryFrame 严格 dtype 会暴露模型适配错误] → 在适配器边界显式转换并用模型级测试固定协议。
• [黑底输入会改变当前 Fit to Foreground 的预测] → 这是统一语义的预期行为，用像素级测试固定合成规则。
• [零 Validity 区域的有限 Field 可能精度较低] → Alpha 完整保留模型判断供消费者解释；连续 Field 用于避免几何塌缩。
• [完整 Field 中一个非有限值会使 Job 失败] → 失败优于生成被 NaN/Inf 污染的网格，错误信息区分 Depth、Point 和 Normal Field。

Migration Plan

1. 重建 GeometryFrame 与两种模型适配器，迁移 MoGe-2 生产推理返回值并删除旧专用中间结构。
2. 将 Depth、Normal 和 Metadata Writer 改为只消费 GeometryFrame，再迁移 Artifact 编排层。
3. 建立统一的 MoGe-2 黑底输入准备，并补充像素与工作流等价测试。
4. 调整 EXR 通道写入与数值检查，增加 Depth Surface 回归测试。
5. 更新 GeometryFrame、Artifact 和 Cutout 内部文档并运行全量测试。

现有 Job 目录中的旧 EXR 不迁移；重新运行对应功能即可生成新语义 Artifact。回退时必须同时回退协议、适配器、Writer 与测试。