AnyImage/openspec/changes/unify-boundary-depth-smoothing/design.md

Context

当前三个深度表面均在投影后执行 Boundary Smooth。Depth Cutout 保护原 Alpha 轮廓的三维位置，Depth Plane 平滑有效性剔除形成的新边界，Depth Panorama 平滑球面的实际开口。

独立实验复用了猫、幼虫和人物的已有深度数据。Cutout 的六个网格在 4、12 次深度 Blur 后明显减少尖刺；Depth Plane 在 Subdivide 4、6 和 Boundary Smooth 5、12 下也有改善。两轮实验均验证关闭还原、拓扑保持和厚度／Split 组合。全景尚需专项验证。

实验文件位于本机临时目录 anyimage-boundary-depth-trial：boundary-smooth-comparison.blend、convert-boundary-comparison.blend 及对应指标 JSON。正式回归测试使用可重建的合成数据；实图用于人工验收。

Goals

• 三个已有 Boundary Smooth 的深度表面使用同一标量平滑规则和参数语义。
• 在边界窄带降低采样深度突变，保留内部数据及对应投影方向。
• 通过现有公共节点构建模块复用实现，并更新可直接加载的节点资产。

Decisions

求值顺序

flowchart TD
    A[基础网格与深度采样] --> B[有效性剔除]
    B --> C[Split 与切口深度处理]
    C --> D[在当前连通网格上 Blur 深度标量]
    D --> E[按边界两圈影响权重混合]
    E --> F[沿原投影方向置换]
    F --> G[现有 Boundary Smooth 网格平滑]
    G --> H[厚度与后续形状处理]

共享实现位于 tools/nodes/common/boundary_smoothing.py，输入深度标量和边界保护字段，输出平滑后的标量。字段在剔除和 Split 后、置换前的 Point 域求值，使已删区域及已分离表面按当前拓扑隔离。各组负责把标量接入自身的投影表达式。

参数与影响范围

Boundary Smooth 同时给深度 Blur 和现有网格平滑提供迭代数，默认 5、范围 0–20，保持已有 socket 标识。实验中的独立 Boundary Depth Blur 输入收敛为现有控制项。

深度 Blur 使用 FLOAT、固定 Weight 0.5。令 B 为可处理的边界点字段，P 为保护字段：

• 在当前网格上对 B 执行 2 次、Weight 1 的 Blur。
• 应用权重为 max(B, blurred_B) * (1 - P)，外边界完全应用，邻近两圈逐渐减弱。
• 原深度与平滑深度按该权重混合。
• 迭代数为 0 或权重为 0 时直接返回原采样值，保证关闭及影响范围外的精确保持。

深度计算和影响权重使用共享字段连接。Smooth Weight 延续现有网格平滑职责，深度 Blur 的固定 Weight 与独立实验一致。

三个节点组的边界与投影

节点组	深度 Blur 影响边界	标量与重建方式
O Image Depth Cutout	原 Alpha 轮廓及 Split 后的新边界	平滑相机 Z；按新旧 Z 比例缩放原相机点，再进入现有投影
O Image Depth Plane	有效性剔除及 Split 后的新边界；保护 UV 原矩形外框	平滑相机 Z；按原相机射线重建点，再进入现有投影
O Image Depth Panorama	球面有效性剔除及 Split 后产生的实际开口	平滑有效径向距离；保持球面方向，再进入 Depth Scale 的半径表达式

Cutout 原轮廓的深度可以变化，后续网格平滑继续使用现有原轮廓保护字段。这样保留图像投影轮廓，同时允许轮廓深度变平顺。Depth Plane 的矩形外框保护同时约束影响起点和最终权重。

Panorama 的经度接缝和极点依照真实球面拓扑求值；UV 接缝本身不形成平滑边界。有效距离平滑在 Invalid Distance 替代分支之前接入，保留区域的无效距离继续由该参数决定。无效区域与有效区域之间沿现有剔除逻辑断开混合面，验证其不会参与有效边界的平均。

相机 Z 重建必须处理零值及不可用于比例计算的采样，直接保留对应原点值，保证结果有限。投影方向保持的断言放在深度平滑／置换阶段；后续网格平滑仍按既有规则移动顶点。

节点与资产组织

公共函数以标量字段为复用边界，三个消费组分别完成相机与球面重建。使用显式域转换及明确源几何采样，所有几何组与嵌套组保持 Capture Attribute 为零。直接连接可复用字段；必要的现有临时命名协议在最后消费者后清理，保留用户属性。

实施时读取当前工作区基线，保留其他修改。完成源码与测试后运行 uv run node-group build，更新 O_AnyImage.blend 并独立加载验证接口、求值和节点布局。

三个消费组的资产版本统一设为 12，运行时通过 load_node_group(..., asset_revision=12) 请求。加载器保留当前文件中旧组及其现有使用者，为新建对象读取新版本；对应 Operator 回归覆盖旧组存在时的行为。

Risks / Trade-offs

• 稀疏网格的两圈覆盖范围较宽，较高迭代数可能软化真实轮廓深度 → 保留默认值 5，并用 Subdivide 4、6 对比 5、12 的效果。
• 深度 Blur 与后置网格平滑叠加 → 分别检查置换阶段的射线保持、最终尖刺改善和整体形状，不把梯度下降单独视为几何更准确。
• 模型 validity 开口可能位于物体内部 → 使用内部孔洞、真实深度断层与孤立尖刺的合成用例，检查影响范围及不同连通表面的隔离。
• 球面方向和无效距离与相机 Z 语义不同 → Panorama 使用径向适配，覆盖经度接缝、极点、Invalid Distance 和 Valid Only 两个分支后再交付。