AnyImage/openspec/changes/unify-depth-plane-and-artifact/design.md

Context

build_depth_plane.py 当前读取纹理 R 通道并生成固定底面浮雕；build_depth_surface.py 使用 XYZ 投影并沿平滑法线生成壳。Cutout 的 Depth Solid 请求 VECTOR，Depth Balloon 请求 Z，但 Balloon 节点和 common/depth.py 已读取 B/Z。Server 将两类产物写成相同规格的 RGBA float32 EXR。

本设计以当前工作区已实现的 add-projected-depth-plane 为基线，覆盖其中关于独立 Surface 入口与 Z/VECTOR 双产物的决定。

Goals / Non-Goals

统一整图深度几何的交互入口和深度产物契约，保留两种形态及 Cutout 的现有几何效果。删除范围限定于独立 Z 文件输出及失去用途的分支；内部标量深度、标定元数据、Cutout 的形状参数继续承担原有职责。

Decisions

一个入口与模式接口

保留 ConvertToDepthPlane、anyimage.convert_to_depth_plane、Convert to Depth Plane 和 O Image Depth Plane。删除独立 Surface 注册、菜单、类、结果类型映射和公开资产组。模式在修改器中选择，默认 Relief；模式切换只触发节点求值。

接口顺序	默认值与语义
Geometry	结构输入
Mode	Relief / Camera，默认 Relief
Subdivide	6，范围 0–10
Thickness（Relief）	0，最小 0，DISTANCE
Thickness（Camera）	0，最小 0，DISTANCE
Depth Scale	1，最小 0
Options / Reference Depth	元数据 reference_depth × Uniform Scale，DISTANCE
Options / Normal Smooth	50，范围 0–50，仅影响 Camera 厚度方向
Data / Uniform Scale	隐藏，默认 1
Data / Depth Image	隐藏

输入统一 SINGLE。两个独立输入均显示 Thickness，依次控制 Relief 的基础厚度和 Camera 的向内壳厚度，默认均为 0 m；按不同 socket identifier 保存，切换模式保留各自数值。Normal Smooth 保留在 Options，并通过说明明确适用模式。

两条几何分支共用数据

flowchart TD
    Input[图片矩形 Mesh 与 depth.exr] --> Mode{Mode}
    Mode --> Relief[Relief：固定 XY，读取 B 深度，固定底面]
    Mode --> Camera[Camera：相机 XYZ 投影，沿平滑法线生成壳]
    Relief --> Output[保留 UV 材质与用户属性，清理临时属性]
    Camera --> Output

Relief 沿用现有厚度、底面权重、侧面插值和负位移限制，只将标量采样改为 B/Z。Camera 沿用现有完整矩形细分与投影公式：令采样相机 XYZ 乘以 Uniform Scale 得到 C，局部 XY 从基础 XY 按 Depth Scale 插值到 (C.x, -C.y)，局部 Z 为 (Reference Depth - C.z) × Depth Scale。正 Thickness 保留正面，背面沿正面 POINT 法线按 Normal Smooth 迭代平滑并归一化后向内偏移。

共用投影和壳构建函数，两个分支由一个公开节点组组织。构建模块以职责命名；删除仅服务旧公开 Surface 组的构建和布局入口。节点资产始终按名称加载。

统一深度产物与请求

flowchart TD
    Request[整图转换或 Cutout 深度请求] --> Infer[一次 MoGe 推理，保留 points]
    Infer --> Correct[按现有调用条件修正边缘深度]
    Correct --> Artifact[depth.exr：RGB 相机 XYZ，A 有效性]
    Correct --> Metadata[depth.json：尺寸 内参 基准深度]
    Artifact --> Load[结果键 depth，主线程加载并 Pack]
    Load --> XYZ[Camera 与 Depth Cutout：读取 XYZ]
    Load --> Z[Relief 与 Depth Balloon：读取 B/Z]

将深度产物选择收敛为布尔 generate_depth，默认 false；整图 Job 固定请求 true，Cutout 根据 Depth Solid / Depth Balloon 判断。替换 depth_mode 参数与 depth_mode_for_shape，生成法线的参数保持独立。只生成法线时仍可不保留 points。

写出函数统一为 write_depth_texture，沿用当前 vector 写出的 RGBA float32 数值、有效性和非有限值处理；文件名 depth.exr，返回键 depth。删除 Z 写出函数与旧结果键，直接更新全部调用和测试。所有需要深度的推理保留 XYZ，内部 GeometryFrame.depth 继续用于标量运算；元数据仍通过 depth_metadata 返回 depth.json。深度与法线继续来自同一次预测，保持各自现有边缘修正语义。

交付与验证

客户端、Server、节点构建及测试作为一次契约变更交付，不增加旧键、旧名称转发。已有 blend 内嵌旧组不主动迁移；需要新模式接口时重新转换源图片。归档时协调前序未归档规格，确保最终规格只保留统一入口和产物契约。

实现阶段更新脚本、验证、测试与节点资产文档并运行测试。资产更新阶段构建并验证 O_AnyImage.blend，对定义与保存资产使用同组几何用例，最后在 Blender 检查总览和局部实际绘制布局；视觉验收单独记录，不能由坐标检查代替。

Risks / Trade-offs

• R 与 Z 在旧标量 EXR 中相同，普通灰度测试会掩盖读错通道 → 使用 X、Y、Z 明显不同的合成纹理覆盖全部消费者。
• Balloon 从仅保留 depth 改为保留 points，增加中间内存 → 验证单次推理、释放路径和正常生成；文件格式与通道数保持一致。
• 两种模式中 Thickness 的几何含义不同 → 明确接口说明，并测试切换保留值及两种模式各自的厚度行为。
• 新代码与旧节点资产混用可能造成接口错误 → 资产更新时同时检查菜单、注册、公开组清单及实际资产求值。