AnyImage/openspec/specs/pinned-geometry-smoothing/spec.md

pinned-geometry-smoothing Specification

Purpose

TBD - created by archiving change pin-geometry-node-smoothing. Update Purpose after archive.

Requirements

Requirement: 边界平滑固定开启 Pin Sharp 与 Pin Boundary

O Image Cutout Symmetry 的 Seam Smooth，以及 O Image Depth Plane、O Image Depth Cutout、O Image Depth Panorama 的 Boundary Smooth SHALL 固定使用 Pin Sharp = 1 与 Pin Boundary = 1，且 MUST NOT 为这两个 pin 新增或修改 modifier 输入。

Scenario: 边界点按边界条带松弛

• WHEN 平滑命中边界点，包括 Split 形成的切边与对称平面的切缝
• THEN 该点的目标位置取自边界条带自身权重 0.5 的一步 Blur
• AND 该点不被内部 Blur 结果拖拽，轮廓不因平滑收缩

Scenario: 边界顶点仍沿边界移动

• WHEN 边界上存在阶梯状顶点
• THEN 顶点沿边界移动以消除阶梯
• AND 顶点不会被固定在原位

Scenario: 尖锐处少动

• WHEN 平滑范围内存在法线不连续的尖锐处
• THEN 该点的平滑权重乘以 |Blur(Normal, 10)|
• AND 尖锐处的位移小于同等权重下平坦区域的位移

Requirement: Fill Smooth 平滑衔接带

O Image Cutout Symmetry 的 Fill Smooth SHALL 平滑 front 表面与它挤出的侧壁之间的衔接带。锚点 SHALL 是 front 的完整边界带，即外侧轮廓与对称面上的切缝，SHALL 按四圈渐变衰减并覆盖对称轴上的点。该衔接处不是网格边界，因此 MUST NOT 套用 Pin Boundary，但 SHALL 保留 Pin Sharp。

Scenario: 衔接带使用邻域平均

• WHEN Fill Smooth 大于 0
• THEN 受力点按邻域平均松弛，不切换到边界条带目标

Scenario: 衔接带保留锐度权重

• WHEN 衔接带范围内存在法线不连续的尖锐处
• THEN 该点的平滑权重乘以 |Blur(Normal, 10)|

Scenario: 衔接带覆盖对称轴上的点

• WHEN Fill Smooth 大于 0
• THEN 对称轴上的点与外侧轮廓同样产生面内位移

Scenario: 衔接带比两圈更宽

• WHEN Fill Smooth 大于 0
• THEN 从轮廓向内第三圈的点仍然受力
• AND 超出配置圈数的点保持原位

Requirement: 作用范围保持渐变语义

Boundary Smooth、Fill Smooth、Seam Smooth SHALL 继续表示平滑生效的渐变区域与迭代次数，落在范围外的顶点 MUST 保持原位。

Scenario: 范围外不动

• WHEN 任一平滑的迭代次数大于 0
• THEN 落在渐变范围外的顶点位置与输入完全一致
• AND 拓扑与 UV 保持不变

Scenario: Cutout 轮廓与切边权重差异

• WHEN Depth Cutout 同时存在原始轮廓与 Split 切边
• THEN Split 切边使用完整权重
• AND 原始轮廓使用 0.1 倍权重
• AND Depth Plane 与 Panorama 的轮廓权重保持 1.0

Scenario: 关闭平滑

• WHEN 迭代次数为 0
• THEN 输出几何与未平滑的基线完全一致

Requirement: 共享平滑实现

common/smoothing.py SHALL 提供单一的平滑构建函数：pin 形态使用边界条带目标与锐度系数，普通形态只使用邻域平均目标。各节点组只提供几何、迭代次数、作用范围、权重、可移动分量与是否 pin；系统 MUST NOT 为单个节点组保留独立的平滑实现或旧偏移路径。

Scenario: 站点调用一致

• WHEN 任一节点组构建顶点位置平滑
• THEN 该组只传入几何、迭代次数、作用范围、权重、允许移动的分量与是否 pin
• AND 边界条带分支、锐度权重与普通邻域平均目标由共享实现生成

Scenario: 对称平面约束

• WHEN O Image Cutout Symmetry 应用 Fill 或 Seam 平滑
• THEN 位移限制在对称平面内的分量
• AND 镜像焊接与闭合性保持不变

Requirement: 属性平滑保持现状

法线平滑、深度模糊、掩码与统计模糊 MUST NOT 纳入 pin，保持既有节点与权重。

Scenario: 属性平滑不受影响

• WHEN 构建 Depth Cutout、Depth Plane 或 Panorama
• THEN 法线平滑与深度模糊的节点结构、迭代次数与权重与变更前一致

Requirement: 资产与测试同步

源码、保存资产与测试 SHALL 保持一致；几何节点及嵌套组 MUST 保持 Capture Attribute 为零。

Scenario: 重建资产

• WHEN 执行节点资产构建并在独立 Blender 进程重新加载
• THEN 资产与源码构建结果通过相同的行为验证
• AND Capture Attribute 检查通过