Add depth surface processing and layout tools

- Implemented `cutout_depth_surface.py` for face separation and connected thickness calculations for depth surface assets. - Created `cutout_depth_surface_layout.py` to arrange nodes for staggered calculation branches in depth surface processing. - Authored `geometry_layouts.py` to define layouts for various geometry assets, including image cutouts and depth planes. - Introduced `node_layout.py` for shared presentation rules, facilitating node arrangement and validation in geometry-node layouts.
2026-09-07 19:21:03 +08:00
parent a0adf79db0
commit 7dec3b7ca4
21 changed files with 2075 additions and 373 deletions
--- a/openspec/changes/replace-depth-surface-stretch-with-split/.openspec.yaml
+++ b/openspec/changes/replace-depth-surface-stretch-with-split/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-07
--- a/openspec/changes/replace-depth-surface-stretch-with-split/design.md
+++ b/openspec/changes/replace-depth-surface-stretch-with-split/design.md
@@ -0,0 +1,100 @@
+## Context
+
+动机见 proposal.md。当前 `_build_depth_surface` 投影后执行 Stretch Limit 删几何，再进入分层厚度。外层 Cutout 在 Shape 前执行 Cleanup，在 Shape 后执行 Smooth。四种 Shape 共用基础网格，节点资产通过构建脚本生成并在运行时加载。
+
+最新实验采用场景 Z 差除以实际面中心距离，六个物体共用节点组。用户确认内部阈值约 `5` 时效果较好，同时观察到有厚度时侧壁与正面脱开。已有“坐标有限、面数增加、平面厚度正确”的检查不足以证明封边成功。
+
+## Goals
+
+分离在 Depth Surface 分支内完成；厚度生成使用拆边后的同一份边界数据。零值关闭时沿用完整原始表面的采样和投影行为。验收覆盖节点组本体和真实 Cutout 外层处理链。
+
+## Decisions
+
+### 1. 用实际采样跨度计算深度坡度
+
+令 `Cₐ、Cᵦ` 为变形前相邻面的中心，`Zₐ、Zᵦ` 为面中心 UV 采样得到的相机 Z，`U` 为正式 Uniform Scale，`D` 为 Depth Scale：
+
+```text
+g = abs(Zₐ - Zᵦ) × U × abs(D) / distance(Cₐ, Cᵦ)
+```
+
+基准中心与 `U × Z` 使用一致的对象局部距离单位。复用 `common.depth.depth_uniform_scale` 和现有参考深度计算，不增加新的 Mesh Detail 数据输入。对中心距离为零的退化邻接不选边，避免除零；数值保护采用与模型尺度一致的容差。
+
+选择共享边上恰有两个邻面的情况。Corners of Edge → Face of Corner → Evaluate at Index 取得邻面字段。采用 Z 而非 XYZ 距离，避免把正常横向间距计入断层；采用实际中心跨度而非期望网格长度，避免轮廓附近的小三角形在 Low 下被过大的分母抑制。
+
+### 2. 使用正向的 Split 控制
+
+`Split` 位于内外两层接口的 Options，替代 Stretch Limit 的位置，`FACTOR`、`SINGLE`、范围 `0–1`、默认 `0`。
+
+使用简单倒数换算：对于 `s > 0`，内部阈值 `T(s) = 2.5 / s`。节点直接比较 `g × s > 2.5`，零值自然关闭，避免零点除法。
+
+| Split | 内部阈值 | 含义 |
+|---|---:|---|
+| 0 | 显式关闭 | 原表面保持连接 |
+| 0.25 | 10 | 较少分离 |
+| 0.5 | 5 | 用户认可的实验强度 |
+| 0.75 | 3.333… | 更多分离 |
+| 1 | 2.5 | 最大强度 |
+
+常数 `2.5` 仅用于把内部阈值 `5` 放到滑块中点。关闭分支旁路新增面采样与拆边，但仍执行 Cleanup 和原始采样投影。
+
+### 3. 固定切口两侧的数据，再生成厚度
+
+```mermaid
+flowchart TD
+    A[原基础网格与深度图片] --> B{Split 大于 0}
+    B -->|是| C[面中心采样并计算深度坡度]
+    C --> D[存入面角命名属性并拆共享边]
+    D --> J[Cleanup 清理拆后平面区域]
+    J --> E[在剩余顶点域固定投影位置和边界身份]
+    B -->|否| K[Cleanup 清理原平面区域]
+    K --> F[原顶点采样与投影]
+    E --> G[生成正背面和共享边界侧壁]
+    F --> G
+    G --> L[移除暂存命名属性]
+    L --> H[外层 Smooth 与输出]
+```
+
+带局部斜坡的三角阶跃样例已复现：原厚度流程直接使用面角字段时产生 64 条开口边，改为厚度前固定顶点字段后降为零。新增面角、侧面分离和重复挤出改变了面角到顶点的平均权重，使侧壁与盖面的坐标不同。
+
+实现上在拆边后、厚度前固定最终顶点投影数据及边界身份，正面、背面、各段侧壁共同引用该数据。侧壁起点必须与正面边界一致，终点必须与背面边界一致，段间共享同一边界环；不得在新增侧面域重新平均原面深度。连接按同一分离区域的边界身份完成，防止全局 Merge by Distance 把原本独立的切口重新焊接。合并容差不能用来掩盖边界坐标不一致。
+
+选边字段先在 EDGE 域求值，再转换到 POINT 域标记关联顶点。仅这些顶点采用拆后所属侧的平均 Z，并以 `原 XYZ × 所属侧 Z / 原 Z` 沿原相机射线重建；其他顶点保留原 XYZ。面中心 XYZ 不直接用于替换顶点位置，以免轮廓向面中心收缩。
+
+保留现有分层厚度的用户语义和分段能力，修正其中的属性传播或连接环节。先复现开裂并检查面朝向、各段挤出方向、顶点域数据和边界配对，再确定最小修改。对定向正确的流形输入，每个加厚区域必须闭合；片段之间可以分离，片段内部不能露缝。
+
+连接使用拆后原顶点编号与厚度层编号作为身份。生成侧壁后，暂时将这两个整数编码成合并坐标，使 Merge by Distance 只合并相同身份的副本，随后恢复捕获的真实表面位置与厚度偏移。编号按整数商、余数拆分以保持浮点表示精确；真实场景中的近距离与重合区域不影响连接身份。
+
+跨区域暂存数据使用保留前缀 `o_depth_` 的 Store Named Attribute，在消费区域用 Named Attribute 就近读取。FACE 保存原面中心与相机采样，CORNER 保存所属侧采样与切口标记，POINT 保存最终相机坐标、表面位置、源顶点编号与厚度分段数。输出前用一个 Wildcard 模式的 Remove Named Attribute 匹配 `o_depth_*`，保持 UVMap 和用户属性。
+
+### 4. 接入正式资产与外层流程
+
+删除 Stretch Limit 接口及其专用边长捕获、删除和松散拓扑清理节点。Depth Surface 将 Cleanup 移到 Split Edges 后、投影和厚度前，按拆后 Mesh Island 的平面面积执行既有清理阈值；避免厚度与侧壁面积影响碎片判定。外层将 Cleanup 值传入此分支，不再对 Depth Surface 提前或重复清理。Split 为零时仍对原平面区域清理。其他三种 Shape 保持原清理位置，外层 Split 仅连接 Depth Surface。
+
+多个物体复用同一组资产，图片与标定由各自修改器传入。验证 Smooth 作用于已正确连接的实体，既不重新缝合不同分离区域，也不暴露侧壁接缝。运行时仍按名称加载资产。
+
+### 5. 按语义组织节点布局
+
+按 AGENTS.md 整理资产中全部七个几何节点组。Depth Surface 的几何主链从左到右连续排列：面采样与判别、拆边、Cleanup、投影、厚度、输出。辅助字段放在使用位置附近，通过局部 Group Input 接入；隐藏未使用输出，保留节点默认 name 与标题，不用 label 替代节点类型。
+
+主轴长度由处理阶段决定，字段计算按各自算式长度横向展开，同一目的的计算聚在主轴同一侧，独立用途可在两侧错落分布。支线可以跨越多个主链步骤的横向范围，同侧支线使用不同的距离和起点，并利用附近空位收紧末端连线；必要的向左引用直接连接，允许交叉，不使用 Reroute 绕行。参照 OmooNodes 的 `O Solidfy`、`O Project`、`O Smooth` 和 `O Tube`，使用局部输入与紧凑分支；完整参数已接线的简单运算可折叠。
+
+大步骤之间保留明显空白，通过节点默认标题与分支形状辨认处理阶段，不放置 String 注解。计算分支可以向主轴起点左侧展开，暂存值通过命名属性传递。
+
+主轴可适当宽松，支线内部间距明显小于不同部分之间的距离，用留白表达用途分组。Depth Plane 的深度偏移与厚度权重在同一侧汇合，Depth Surface 的选边判别构成紧凑的局部计算组。Join Geometry、Menu Switch、Combine XYZ 的独立同级分支末端排成一列、输出端对齐；菜单分支按输入顺序上下排列。供多个部分使用的共享上游留在公共位置。
+
+Repeat 输入与输出围住厚度循环内部节点，内部流程保持从左到右，不让区域跨越无关主链或遮挡节点。Frame 仅包裹具有完整语义的区域。接口保持 Options/Data 的业务边界及 SINGLE 结构，长度参数使用 DISTANCE，Split 使用 FACTOR。
+
+布局由构建脚本确定。结构验证覆盖节点实际尺寸的非重叠、接口顺序、未使用输出隐藏和区域配对；另在 Blender 节点编辑器检查可读缩放下的主链、长线、交叉和回折。自动拓扑分层或统一网格排布不能替代视觉验收。消除可避免的交叉，共享字段通过就近输入和必要的转接组织，避免为减少节点数而拉出横跨整个图的线。
+
+## Risks / Trade-offs
+
+- 深度坡度也响应连续陡坡 → 使用有界控制范围，以平面、斜坡、深度阶跃共同校验阈值含义。
+- High 比 Low 捕获更多局部变化 → 用规则重采样的合成曲面检查尺度趋势，真实图片用边界位置和碎片形态比较，不以切边总数相等作为验收。
+- 小三角形放大深度噪声 → 检查退化采样跨度、低噪声样本和最大档，不擅自增加改变几何的平滑预处理。
+- 厚度侧壁开裂可能存在多个原因 → 将闭合拓扑、共享边界坐标、法线和真实渲染列为独立验证项。
+- 全局焊接或外层平滑改变切口 → 用间隔小于原焊接容差的双片段覆盖回归。
+
+## Migration Plan
+
+新资产移除旧输入，无旧名转发或兼容控制。替换构建脚本、验证及测试后同步节点资产和必要的节点资产说明；不重写历史 OpenSpec 变更，不构建扩展发行包。已有文件中的旧节点数据由既有资产更新流程处理，不在本变更新增文件迁移机制。
--- a/openspec/changes/replace-depth-surface-stretch-with-split/proposal.md
+++ b/openspec/changes/replace-depth-surface-stretch-with-split/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+Depth Surface 的 Stretch Limit 通过删几何处理深度断层，在粗网格上产生斑驳缺面。面深度拆边实验已能保留表面并分离遮挡关系，但增加厚度后侧壁与正面脱开，且目前阈值的操作方向不符合使用习惯。
+
+## What Changes
+
+- **BREAKING**：移除 Depth Surface 及外层 Cutout 的 Stretch Limit 接口、拉伸删几何及其松散拓扑清理分支，以 Options 中的 `Split` 替代。
+- 使用“场景 Z 差 / 置换前相邻面中心实际距离”识别需要拆开的共享边。Uniform Scale 使用现有图片标定结果，Depth Scale 参与判断。
+- `Split` 范围为 `0–1`，默认 `0` 完全关闭；越大越容易分离。中点 `0.5` 对应实验内部 Split Ratio `5`。
+- 拆边后保留面所属侧的采样数据，贯穿原 Depth Surface 投影和厚度流程；修复侧壁与正、背面连接，使有厚度的分离区域具有完整边界。
+- Depth Surface 的 Cleanup 放在 Split Edges 之后、投影和厚度之前，按拆分后的平面区域清理小碎片。
+- 多个物体共同引用资产中的节点组，通过各自修改器传入图片和标定数据；四种 Shape 继续共享基础网格。
+- 整理资产中全部七个几何节点组：主轴横排、支线双侧错落并就近汇入，必要的回接直接连接，验证 Repeat 区域的排列；将布局经验写入 AGENTS.md。
+
+## Capabilities
+
+### New Capabilities
+
+- `depth-surface-face-separation`：规定分离控制、面深度判据、厚度连接完整性和共享节点集成行为。
+
+### Modified Capabilities
+
+无。当前 `openspec/specs` 尚无对应主规格；本变更替代已实现的 `restore-depth-surface-stretch-culling` 的产品行为，不改写其历史记录。
+
+## Impact
+
+- `tools/node_assets/build_cutout.py`、节点验证及 `src/anyimage/assets/O_AnyImage.blend`。
+- Cutout 真实 Blender 求值测试、接口结构测试及节点资产说明。
+- 原 Depth Surface 的厚度生成与采样属性传递需要联合验证，并回归外层 Cleanup、Smooth 和其他 Shape。
+- 复用现有 Depth Image、Uniform Scale 和 Reference Depth 输入；不新增模型推理或依赖。
--- a/openspec/changes/replace-depth-surface-stretch-with-split/specs/depth-surface-face-separation/spec.md
+++ b/openspec/changes/replace-depth-surface-stretch-with-split/specs/depth-surface-face-separation/spec.md
@@ -0,0 +1,131 @@
+## Purpose
+
+规定 Cutout Depth Surface 在深度断层处保留原表面并分离相邻区域的行为，提供默认关闭、随数值增大而增强的控制，并确保厚度生成后每个分离区域的正面、背面和侧壁保持完整连接。
+
+## ADDED Requirements
+
+### Requirement: 分离控制替换拉伸剔除
+
+系统 SHALL 在 Depth Surface 及外层 Cutout 的 Options 中以 `Split` 替代 `Stretch Limit`。Split SHALL 为范围 `0–1` 的比例输入，默认 `0`，增大时不得降低同一输入几何的切边选择强度。
+
+#### Scenario: 默认关闭
+- **WHEN** 用户使用默认 Split `0`
+- **THEN** 系统不增加切边，并在 Cleanup 保留的区域上使用原 Depth Surface 采样与投影行为
+
+#### Scenario: 中点与最大强度
+- **WHEN** Split 分别设为 `0.5` 和 `1`
+- **THEN** 内部深度坡度阈值分别为 `5` 和 `2.5`，且控制值不能超过 `1`；正值对应阈值为 `2.5 / Split`
+
+#### Scenario: 接口替换
+- **WHEN** 用户检查新 Cutout 的 Options
+- **THEN** 可见 Split，且不存在 Stretch Limit 控制及其拉伸删几何行为
+
+### Requirement: 使用相邻面深度与实际跨度选择共享边
+
+系统 SHALL 以场景尺度的相邻面中心 Z 差除以变形前两面中心的实际距离作为坡度得分；场景深度 SHALL 包含图片标定的 Uniform Scale 和当前 Depth Scale 的幅度。系统 SHALL 只对恰有两个邻面的共享边执行此判断，并安全处理零跨度输入。
+
+#### Scenario: 同一阈值两侧
+- **WHEN** Split 为 `0.5`，两个有效邻接的坡度得分分别为 `4` 和 `6`
+- **THEN** 得分 `4` 的边不被选中，得分 `6` 的边被选中进行分离
+
+#### Scenario: 等比尺度变化
+- **WHEN** 图片几何和经标定的深度同时等比缩放且 Split 不变
+- **THEN** 相应共享边的坡度得分和选择结果保持一致
+
+#### Scenario: 深度归零与退化邻接
+- **WHEN** Depth Scale 为 `0` 或邻面中心距离为零
+- **THEN** 该条件不产生新增切边，且求值不产生非有限坐标
+
+### Requirement: 分离保留表面及两侧独立位置
+
+系统 SHALL 通过拓扑分离保留原始表面的覆盖，使用各自所属侧的数据确定拆后位置。仅设置选边而继续使用共享 UV 的同一个深度值 SHALL NOT 被视为实现两侧分离。
+
+#### Scenario: 零厚度深度阶跃
+- **WHEN** Cleanup 为零，规则网格跨越深度阶跃且 Split 选中贯通边界
+- **THEN** 原始面全部保留，两侧具有独立顶点与不同场景深度，且没有拉伸剔除造成的缺面
+
+#### Scenario: 开启控制但没有切边
+- **WHEN** Split 大于零且所有共享边均未达到分离阈值
+- **THEN** 顶点投影与 Split 为零时完全一致，轮廓不因面中心平均而收缩
+
+#### Scenario: 切口保持原相机射线
+- **WHEN** 某些共享边被分离
+- **THEN** 仅关联顶点使用所属侧的深度，并保持原 XYZ 的相机射线方向；其他顶点保留原采样位置
+
+### Requirement: Cleanup 在拆边后生成厚度前执行
+
+Depth Surface SHALL 在 Split Edges 后、投影及厚度生成前执行一次 Cleanup，按拆分后平面区域的面积使用既有清理阈值。其他 Shape SHALL 保持原 Cleanup 顺序。
+
+#### Scenario: 清理拆出的碎片
+- **WHEN** 拆边生成低于 Cleanup 面积阈值的独立区域
+- **THEN** 该区域在生成厚度前被清理，其余区域随后投影并加厚
+
+#### Scenario: 厚度不改变清理结果
+- **WHEN** Split、基础网格和 Cleanup 保持不变，仅调整 Thickness
+- **THEN** 被 Cleanup 保留的平面区域不变
+
+#### Scenario: 关闭分离仍可清理
+- **WHEN** Split 为零且 Cleanup 为正
+- **THEN** Cleanup 对原平面区域执行一次，不因分离关闭而失效
+
+### Requirement: 厚度侧壁与正背面完整连接
+
+系统 SHALL 在加厚时使每个分离区域的侧壁与正面、背面及相邻厚度段共享连续边界。对定向正确的流形片状输入，各加厚区域 SHALL 形成闭合表面，不得跨区域重新焊接切口。
+
+#### Scenario: 阶跃区域加厚
+- **WHEN** 对已拆开的深度阶跃区域设置正厚度
+- **THEN** 每个区域的侧壁准确连接其正背面，边界无开口、重叠但未连接的接缝或错位边界
+
+#### Scenario: 分段厚度
+- **WHEN** 厚度足以生成多个侧壁段
+- **THEN** 各段相接且总厚度符合输入值，侧壁端点与对应表面边界一致
+
+#### Scenario: 近距离独立区域
+- **WHEN** 两个独立分离区域的间隔小于既有几何焊接容差
+- **THEN** 厚度连接仍保持区域独立，不因全局合并恢复原连接
+
+### Requirement: 正式 Cutout 流程共享分离能力
+
+系统 SHALL 让多个物体共享同一套节点资产，并通过各自修改器传入数据。Split SHALL 仅影响 Depth Surface 分支；外层 Cleanup、Smooth 及其他三种 Shape SHALL 保持各自职责。
+
+#### Scenario: 六物体共享节点
+- **WHEN** 三张图片分别创建 High 和 Low 的 Depth Surface
+- **THEN** 六个物体引用共享节点组，同一图片的标定值一致，各物体控制值可以独立调整
+
+#### Scenario: 完整修改器链
+- **WHEN** Depth Surface 同时启用分离、正厚度及外层 Smooth
+- **THEN** 同一区域的正背面和侧壁保持连接，分离区域之间保持独立
+
+#### Scenario: 切换其他 Shape
+- **WHEN** 用户改变 Split 后选择其他三种基础 Shape
+- **THEN** Split 不改变这些 Shape 的基础拓扑与形状结果
+
+### Requirement: 节点布局清晰可读
+
+资产中全部七个几何节点组 SHALL 遵循 AGENTS.md 的节点组规范：主链从左到右连续排列、辅助分支就近汇入、节点无重叠、保留默认节点标题并隐藏未使用输出。必要的向左引用 SHALL 直接连接，不使用 Reroute 绕行，允许回接连线交叉。
+
+跨区域暂存值 SHALL 使用 `o_depth_*` 命名属性并就近读取，在输出前通过一个 Wildcard 模式的 Remove Named Attribute 统一清理。大步骤之间 SHALL 留白，不放置 String 注解。同一目的的计算 SHALL 聚在主轴同一侧，支线内部间距 SHALL 明显小于与其他部分的距离。独立用途可在两侧错落展开，长算式可超出所服务主链步骤的范围；必要的几何引用可回接。
+
+#### Scenario: 暂存属性生命周期
+- **WHEN** Split 和 Thickness 分别开启或关闭
+- **THEN** 面、面角和顶点暂存值在正确域传递，输出不残留暂存属性，UVMap 与用户属性保持可用，关闭分支不出现移除缺失属性的警告
+
+#### Scenario: 查看所有几何资产
+- **WHEN** 用户打开任一几何节点组
+- **THEN** 计算分支按用途聚拢并利用附近空位，长算式横排，局部输入靠近消费节点，布局调整保持原计算结果
+
+#### Scenario: 查看同级分支汇合
+- **WHEN** 多个独立同级分支输入 Join Geometry、Menu Switch 或 Combine XYZ 等汇合节点
+- **THEN** 分支末端排成一列并对齐输出端，XYZ 三轴按同级输入组织，菜单分支按输入顺序上下排列，共享上游留在公共位置
+
+#### Scenario: 查看同一用途的计算
+- **WHEN** 用户查看 Depth Plane 的置换计算或 Depth Surface 的 Split 选边判别
+- **THEN** 同一用途的计算聚在主轴同一侧，内部节点间距紧凑，与其他部分之间保留更大的空白，主轴可适当宽松
+
+#### Scenario: 查看分离与厚度流程
+- **WHEN** 用户在节点编辑器查看新 Depth Surface
+- **THEN** 能沿主链依次辨认采样判别、拆边、投影、厚度和输出，辅助连线不横跨无关区域，节点文字不被遮挡
+
+#### Scenario: 查看成对区域
+- **WHEN** 用户检查厚度 Repeat 区域
+- **THEN** 成对节点位置正确，循环内部节点清晰排列，区域不遮挡其他节点，Frame 仅用于确有包裹语义的部分
--- a/openspec/changes/replace-depth-surface-stretch-with-split/tasks.md
+++ b/openspec/changes/replace-depth-surface-stretch-with-split/tasks.md
@@ -0,0 +1,67 @@
+## 1. 固定失败样例与控制语义
+
+- [x] 1.1 将正厚度侧壁脱开缩减为定向正确的流形网格和深度阶跃样例，以边界配对、非流形边和未焊接接缝检查复现失败，记录根因。
+- [x] 1.2 增加 Split 简单倒数换算测试，覆盖默认关闭、0.5 对应阈值 5、最大值 1 对应阈值 2.5，以及切边选择随控制值单调增强。
+- [x] 1.3 增加原始表面、平面、斜坡、阶跃、等比缩放和零跨度用例，验证面中心 Z 差与实际中心跨度的判据及关闭时的原始投影行为。
+
+## 2. 接入分离与厚度连接
+
+- [x] 2.1 移除内外节点组的 Stretch Limit 接口与专用删几何分支，在 Options 原位置加入 Split；通过接口测试确认范围、默认值、FACTOR、SINGLE 及只连接 Depth Surface。
+- [x] 2.2 实现面采样、邻面判别、面角捕获和拆边，复用 Uniform Scale 与 Depth Scale；通过零厚度阶跃测试确认保留全部原始面且两侧独立。
+- [x] 2.3 在拆边后固定顶点投影及边界身份，修复厚度侧壁数据传播与连接；通过单段、多段、粗细网格测试确认正背面和侧壁闭合、厚度正确。
+- [x] 2.4 限制连接在对应区域内完成；通过间隔小于原合并容差的双区域用例确认不会重新焊接切口。
+- [x] 2.5 将 Depth Surface 的 Cleanup 移至 Split Edges 后、投影和厚度前，移除该分支提前和重复清理；通过碎片样例验证按拆后平面面积清理、关闭 Split 仍清理且 Thickness 不改变保留区域。
+- [x] 2.6 接入外层 Smooth 和 Shape 分支，通过完整修改器求值测试确认加厚区域保持连接，其他 Shape 的 Cleanup 位置与行为不变。
+
+## 3. 整理节点布局与共享资产
+
+- [x] 3.1 按 AGENTS.md 重排主链和辅助分支，局部放置 Group Input，保留默认标题并隐藏未使用 sockets；在节点编辑器检查可读性，消除可避免的长线、交错和回折。
+- [x] 3.2 整理厚度 Repeat 配对区域及必要 Frame，通过实际节点尺寸检查确保无重叠、无遮挡，并保存节点编辑器预览供审阅。
+- [x] 3.3 更新节点验证脚本，覆盖接口顺序、SINGLE、subtype、未使用输出隐藏、布局与几何求值；运行验证确认通过。
+- [x] 3.4 构建并验证节点资产，检查六个物体共同引用资产节点组、标定与控制各自传入，运行时不新建节点组。
+
+## 4. 综合验收
+
+- [x] 4.1 用蜘蛛与蛛丝、甲虫右侧腿与躯干、噬菌体左下交叉腿检查 High/Low，在 Split 0、0.5、1 及正厚度下保存对比；重点确认中点效果、碎片程度和侧壁无缝连接。
+- [x] 4.2 运行 Cutout 定向测试、节点资产验证和相关回归测试，重新打开保存的 Blender 文件复核厚度与共享节点；不能仅以面数或厚度范围通过代替闭合验证。
+- [x] 4.3 同步必要的节点资产说明以符合 AGENTS.md，验证构建脚本、资产接口和说明一致，不构建扩展发行包。
+- [x] 4.4 运行 OpenSpec 严格校验，确认所有规格场景都有测试或明确的视觉验收记录后再标记实施完成。
+
+## 5. 轮廓与连线修正
+
+- [x] 5.1 只在选中切边的关联顶点应用所属侧深度，沿原相机射线重建位置；验证无切边时投影完全不变、切口外顶点不变、切口顶点保持原射线。
+- [x] 5.2 明确排列侧壁、背面、连接及位置恢复分支，复制局部 Position 字段并用 Reroute 通道组织长线；保存实际节点编辑器预览并验证长连线不斜穿计算区域。
+
+## 6. 按处理阶段组织布局
+
+- [x] 6.1 阅读用户的 OmooNodes 参考资产，按几何主轴收拢阶段，属性计算在局部竖排和并行展开，局部重复 Group Input。
+- [x] 6.2 验证重排前后运算、默认值和实际连接一致，运行 Cutout 求值检查，并在 Blender 中按实际节点尺寸复核布局、保存预览。
+
+## 7. 命名属性与阶段留白
+
+- [x] 7.1 将跨区域暂存数据改为 o_depth_* 命名属性并就近读取，输出前统一移除，验证字段域、几何结果和属性清理。
+- [x] 7.2 拉开大步骤间距，以 String 节点标注阶段，按主轴与局部计算树重排并在 Blender 检查实际布局。
+- [x] 7.3 重建资产，复核六物体共享节点与厚度闭合，运行回归和 OpenSpec 校验。
+
+## 8. 双侧计算分支与 Wildcard 清理
+
+- [x] 8.1 用单个 Wildcard Remove Named Attribute 清理 o_depth_*，验证新增匹配属性同样被清理、用户属性保留。
+- [x] 8.2 移除 String 注解，将分支在主轴上下错落横向展开，允许必要的几何引用回接，检查实际节点布局。
+- [x] 8.3 重建共享资产，比较真实样例几何，运行节点验证、回归与 OpenSpec 校验。
+
+## 9. 全部几何资产布局与规则
+
+- [x] 9.1 回接直接连接，收紧支线与主轴的间距，将同样的布局方式用于资产中的全部七个几何节点组。
+- [x] 9.2 将主轴、双侧支线、局部输入、命名属性、Wildcard 清理与视觉检查规则整理进 AGENTS.md，更新节点资产说明。
+- [x] 9.3 重建资产，对比运算和连接、执行几何回归，并在 Blender 中逐组检查实际布局，保存预览。
+
+## 10. 紧凑布局与同级输入对齐
+
+- [x] 10.1 收紧全部几何节点组的间距，将同一目的的节点聚拢，并将汇合节点的独立同级来源排齐，菜单分支按输入顺序排列。
+- [x] 10.2 同步 AGENTS.md 与布局规范，验证汇合分支对齐、实际尺寸和计算结果，保存预览。
+
+## 11. 按用途聚拢支线与 XYZ 对齐
+
+- [x] 11.1 将 Combine XYZ 纳入同级输入对齐，Depth Plane 同用途计算收在一侧，收紧 Split 选边支线内部间距，同步 AGENTS.md 与布局规范。
+- [x] 11.2 重建资产并检查七组实际节点布局，确认计算与连接不变，运行节点验证及相关回归，保存局部预览。
+
--- a/openspec/changes/replace-depth-surface-stretch-with-split/validation.md
+++ b/openspec/changes/replace-depth-surface-stretch-with-split/validation.md
@@ -0,0 +1,57 @@
+## 验收记录
+
+- Blender 4.5.10 LTS：三套节点资产验证脚本通过，进程正常退出。
+- 最终 Cutout 定向测试：62 项通过，进程正常退出。
+- 全量回归：649 项通过、2 项预期失败、59 项子测试通过；开发环境 bpy 在解释器退出阶段仍使进程返回 1。正式 Blender 的构建、求值及重新打开检查均正常退出。
+- 三张图片各 High/Low，Split 为 0、0.5、1，Thickness 为 0、0.02，共 36 组求值：零厚度保留全部原始面；正厚度所有面边均成对连接，无开口边或非流形边。
+- 六个物体共用正式 `O Image Cutout` 及其 Depth Surface 子组。重新打开保存文件后，图像数据有效，零厚度顶点坐标与保存前一致；Split 0.5、Thickness 0.02、Smooth Iterations 2 时仍全部闭合。
+- Blender 节点编辑器实际尺寸检查无节点重叠，Repeat 区域内无无关节点；已保存总览、面判别和 Repeat 局部预览。
+- 阶段布局复核：参照 OmooNodes 的四个节点组后，图宽从 27550 缩至 8580 个节点编辑器单位。主轴横排，字段按局部阶段展开；实际节点尺寸检查通过。重排前后全部节点运算、默认输入和穿过 Reroute 后的实际连接完全一致，58 项定向测试与 36 组样例求值通过。
+
+## 视觉结果
+
+蜘蛛与蛛丝、甲虫右侧腿和噬菌体左下交叉腿的 High/Low 对比均已保存，包含关闭、中点、最大强度和中点加厚。
+
+中点能分离主要深度连接，最大强度进一步增加局部分离。High/Low 的三角形布局与深度采样不同，切口位置和碎片形状仍有差异；例如甲虫右侧末端在 High 中点已断开，Low 到最大值才断开。厚度沿各自区域形成连续侧壁，闭合结论同时由完整网格拓扑检查支持。
+
+合成用例覆盖默认投影、控制阈值、规则斜坡重采样、等比缩放、零跨度、拆后清理、单段与多段厚度、重合独立区域及外层平滑。接口和依赖检查覆盖其他 Shape 不受 Split 影响。
+
+审阅文件位于本机：`C:/Users/icrdr/.codex/visualizations/2026/09/06/01a076f5-7f13-7083-84cd-f624eeeb4c30/corrected-depth-surface/`，其中 `cutout-depth-surface.blend` 为共享正式节点的六物体场景，`*-comparison.png` 为三张对比图，`node-layout-*.png` 为节点预览，`validation.json` 为 36 组完整网格检查记录。
+
+最新阶段布局及六物体审阅文件位于同级 `compact-depth-surface/`，节点预览为 `layout-overview.png`、`layout-split.png`、`layout-projection.png`、`layout-thickness.png`。参考资产截图及连接一致性检查位于同级 `layout-study/`。
+
+## 命名属性与阶段留白复核
+
+- FACE、CORNER、POINT 暂存值已改为 `o_depth_*` 命名属性，8 项属性在输出前按启用分支逐项移除。4 组 Split/Thickness 组合验证无残留且保留 UVMap 和 `o_user_weight`；Blender 修改器界面不再出现关闭厚度时的缺失属性清理警告。
+- 与上一版 `compact-depth-surface/` 的 24 份样例数据对比，面索引完全相同，顶点坐标绝对误差不超过 `1e-6`；36 组完整求值及六个平滑后闭合实体复核通过。
+- 大步骤之间保留至少 500 个节点编辑器单位的空白，6 个 String 节点显示阶段说明。计算树从局部 Named Attribute 和 Group Input 展开，几何起点位于部分计算节点右侧。实际节点尺寸检查无重叠，Repeat 区域未遮挡其他节点。
+- 最新六物体场景位于同级 `named-depth-surface/cutout-depth-surface.blend`；`layout-*.png` 为总览、Split、投影、厚度、位置恢复和属性清理预览。重新打开后图片数据、共享节点与厚度闭合均通过。
+
+## 双侧支线与 Wildcard 复核
+
+- Remove Named Attribute 使用 `pattern_mode = WILDCARD`，一个节点匹配 `o_depth_*`。删除逐项清理与条件分支，移除全部 String 注解。测试额外注入 `o_depth_probe`，确认前缀匹配生效且保留 `o_user_weight`、UVMap。
+- 计算分支在主轴上下交错展开；面判别与厚度分段算式横向延伸，厚度统计从主链向左引用几何。验证仅要求几何主轴向右，辅助引用允许回接；实际节点尺寸无重叠，Repeat 区域未遮挡其他节点。
+- 62 项 Cutout 定向测试、三套 Blender 资产验证通过。36 组真实样例求值和六个平滑实体保持闭合；与命名属性版的 24 份数据比较，面索引相同，坐标绝对误差不超过 `1e-6`。
+- 最新审阅场景为同级 `tree-depth-surface/cutout-depth-surface.blend`，六个物体共用正式节点。`layout-*.png` 保存总览和局部节点编辑器预览；重新打开检查及 OpenSpec 严格校验通过。
+
+## 全部几何资产布局复核
+
+- 七个几何节点组均按主轴与双侧计算分支整理，局部重复 Group Input；基础平面在 UV 和网格尺寸区域分别计算相同的源包围盒尺寸。深度表面的厚度统计直接向左引用几何，支线末端移近使用位置，前向旁路仅保留少量转接。
+- 将重复的输入与尺寸计算归一化后，全部资产的运算、默认值和实际连接与重排前一致。24 份真实样例的面索引完全相同，顶点坐标绝对误差不超过 `1e-6`；36 组求值、六个平滑闭合实体和重新打开检查通过。
+- Blender 4.5.10 LTS 中逐组检查总览和实际绘制边界，七组均无节点重叠；Depth Surface 的投影、厚度等阶段另保存局部预览，Repeat 区域检查通过。所有组保留默认标题、隐藏未使用输出且无 String 注解。
+- 三套 Blender 资产验证正常退出。完整回归为 650 项通过、2 项预期失败、59 项子测试通过；开发环境 bpy 在测试完成后的退出阶段仍返回 1。
+- 布局规则已写入 AGENTS.md。最新预览与六物体审阅场景位于同级 `all-geometry-layout/`，七组总览分别按节点组名称保存为 PNG，`drawn-layouts.json` 记录实际尺寸，`semantics.json` 与 `geometry-comparison.json` 记录比较结果。
+
+## 紧凑布局与同级输入复核
+
+- 全部七组按实际绘制边界比较，布局宽度减少约 13–26%，高度减少约 30–37%。同一目的的计算、正背面汇合与局部输入进一步聚拢，四个 Shape 在菜单前按输入顺序排成一列。
+- 验证独立同级来源的输出端对齐，并保留共享上游与后续处理的主轴关系。实际节点边界与厚度 Repeat 区域检查通过，运算、默认值和实际连接与本轮重排前一致。
+- 65 项相关测试及三套 Blender 4.5.10 LTS 资产验证全部通过，进程正常退出。预览位于同级 `compact-peers-layout/`，`*-peers.png` 为汇合局部，`layout-*.png` 为 Depth Surface 阶段预览。
+
+## 用途分组与 XYZ 同级输入复核
+
+- Depth Plane 的深度偏移与厚度权重计算收在主轴同一侧；Depth Surface 的 Split 判别和投影支线内部收紧，主轴与不同用途之间保留更大间距。
+- Combine XYZ 的独立输入分支末端对齐，供多个部分使用的共享上游保留在公共位置。几何主轴、同级来源、未使用输出、实际节点边界与 Repeat 区域检查通过，七个几何节点组均在 Blender 中检查总览和相关局部。
+- 与本轮修改前资产比较，全部十个节点组的运算、默认值和实际连接相同。65 项相关测试、三套 Blender 4.5.10 LTS 资产验证通过，进程正常退出。
+- 本轮预览位于同级 `branch-clusters-layout/`，`O Image Depth Surface-selection.png` 为选边判别，两个 `*-projection.png` 为置换计算，`*-xyz.png` 为 XYZ 汇合；`drawn-layouts.json` 和 `semantics.json` 保存实际边界与一致性记录。
+