refactor: incorporate Depth Scale into Depth Split criteria for consistent geometry handling

openspec/changes/scale-depth-split-by-depth-scale/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-16

openspec/changes/scale-depth-split-by-depth-scale/design.md

@@ -0,0 +1,42 @@
+## Context
+
+Depth Split 的判据在 `split_depth_surface`（`tools/nodes/common/depth_surface.py`），在边域求值，被 `O Image Depth Plane`、`O Image Depth Cutout`、`O Image Depth Panorama` 共用。当前式子是：
+
+```
+|Δ射线距离| × Reference × Strength  >  面中心距离 × 平均射线距离 × 2.5
+```
+
+四个量各有分工：Δ 是共享边两个面各自的 `|相机 XYZ|` 之差，`Reference` 把无量纲的相对跳变换算回局部长度尺度，`面中心距离` 用采样密度归一化（Subdivide 变化不改变选择），`平均射线距离` 把绝对差归一化成相对跳变（深度图整体缩放不改变选择）。Depth Scale 不在其中。
+
+投影后的深度落差是 `Δ × Depth Scale`：`Y = (Reference − 相机 Z × Uniform Scale) × Depth Scale`。所以判据里缺的正是这个因子。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Depth Scale 为 0 时表面完全平整且不被切开、不删除条带面，输出与关闭 Split 相同。
+- 判据表达投影后的几何落差，切边随 Depth Scale 单调出现。
+- 默认 Depth Scale 为 1 时结果与当前实现完全一致。
+- 三个共用判据的资产行为一致。
+
+**Non-Goals:**
+
+- 不改变相对跳变的归一化方式：平均射线距离、面中心距离、Reference 的作用保持不变。
+- 不新增 Split 参数、不引入自动阈值或滞回。
+- 不改变切边后顶点沿射线重新定位、条带面清理、边界平滑的既有规则。
+- 不改动 `O Image Relief Plane` 与全景的球面半径插值。
+
+## Decisions
+
+**只把 Depth Scale 乘进落差项，不动归一化因子。** 分子就是投影后 Y 方向的真实落差，分母承担的是采样密度与深度数据整体尺度的归一化，跟显示幅度无关；分母也跟着乘会让阈值失去可解释的单位。备选是把 Depth Scale 当开关（只有 0 才禁用 Split），那样阈值不连续，中间幅度没有意义；另一个备选是在投影后的几何上重新求值判据，需要重建面中心距离与射线距离，代价大而收益只是一个常数因子的精度。
+
+**Depth Scale 作为 `split_depth_surface` 的显式参数，由三个调用方各自传入。** 三个资产共用同一判据，参数化后行为一致，不引入全局读取或隐式约定。全景的 Depth Scale 本来就参与「球半径到预测距离」的插值，乘进判据与它的显示语义一致。
+
+**不加平滑或滞回。** Split 是硬阈值，滞回会让同一网格的拓扑依赖求值历史，与现有单次求值模型不符。低 Depth Scale 下拖参数导致的跳变按既定语义接受。
+
+## Risks / Trade-offs
+
+- 拖动 Depth Scale 时会出现「突然全部切开」的跳变 → 接受。Split 本来就是阈值判断，Depth Scale 为 0 的纯净行为优先。
+- Depth Scale 开始影响拓扑：顶点数、边界平滑结果、壳壁都随之变化 → 接受，并在 Depth Split 的参数说明中写清它随 Depth Scale 缩放。
+- 已保存场景若 Depth Scale 小于 1，切边会比以前少 → 这是本次改动的目的；默认值 1 的场景不受影响。
+- 与 `reorganize-cutout-shapes` 中「Split 独立于显示深度幅度」的条目冲突 → 在同一变更里修订该条目。

openspec/changes/scale-depth-split-by-depth-scale/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+Depth Split 现在的判据只由深度采样差和局部采样密度决定，Depth Scale 完全不参与。于是 Depth Scale 为 0（表面被压成完全平的一层）时仍然切开并删除条带面，平面上留下没有几何依据的缝隙。用户把 Depth Scale 理解为显示幅度，0 应当不产生任何切割。
+
+## What Changes
+
+- Depth Split 的比较式乘上 Depth Scale，判据从「源深度数据的断层」改为「投影后表面的几何落差」。
+- Depth Scale 为 0 时不切开、不删除条带面，也不改变拓扑；Depth Scale 增大时切边逐步出现。
+- 三个使用该判据的资产行为一致：`O Image Depth Plane`、`O Image Depth Cutout`、`O Image Depth Panorama`。
+- 默认 Depth Scale 为 1，默认行为与现在完全相同。**BREAKING**：Depth Scale 由纯显示参数变为影响拓扑的参数，保存了 Depth Scale 小于 1 的场景会看到切边减少、顶点数与壳壁结果随之改变。
+- 同步修订 `reorganize-cutout-shapes` 中「Split 独立于显示深度幅度」的过时条目。
+
+## Capabilities
+
+### New Capabilities
+
+- `depth-split-selection`: Depth Split 依据什么判定相邻面之间的断层，以及 Depth Scale 在其中的作用。
+
+### Modified Capabilities
+
+无。`openspec/specs` 尚无可修改的已归档规格。
+
+## Impact
+
+- `tools/nodes/common/depth_surface.py`：`split_depth_surface` 增加 Depth Scale 输入，比较式乘该因子。
+- `tools/nodes/groups/image_depth_plane.py`、`image_depth_cutout.py`、`image_depth_panorama.py`：传入各自的 Depth Scale。
+- `tests/tools/nodes/test_depth_surface_split.py`：反转「Depth Scale 不改变切边」的断言，补充 Depth Scale 0 不切开的覆盖。
+- `src/anyimage/assets/O_AnyImage.blend`：重新构建节点资产。
+- 不改动 `O Image Relief Plane`、Cutout 创建入口、材质与依赖。

openspec/changes/scale-depth-split-by-depth-scale/specs/depth-split-selection/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Depth Split 使用投影后的几何落差
+Depth Split 的判定 SHALL 以原始相邻面采样距离差乘 Depth Scale 作为落差量，与变形前的采样跨度比较；平均射线距离 SHALL 继续作为把绝对差归一化为相对跳变的因子，Depth Scale MUST NOT 参与该归一化。参数说明 MUST 说明切边随 Depth Scale 缩放。
+
+#### Scenario: Depth Scale 为零
+- **WHEN** 固定深度图与 Depth Split，把 Depth Scale 设为 0
+- **THEN** 输出拓扑与 Split 为 0 时相同，没有切边，也没有条带面被删除
+
+#### Scenario: Depth Scale 放大落差
+- **WHEN** 同一输入在 Depth Scale 从 0 增大到 1 之间求值
+- **THEN** 选中的切边只增不减，Depth Scale 为 1 时与当前判据结果一致
+
+#### Scenario: 深度数据整体缩放
+- **WHEN** 同一深度图的采样数值整体乘以任意正数
+- **THEN** 选中切边完全相同
+
+### Requirement: 三个深度资产共用同一判据
+`O Image Depth Plane`、`O Image Depth Cutout`、`O Image Depth Panorama` SHALL 使用同一个 Depth Split 判据并各自传入自己的 Depth Scale。
+
+#### Scenario: 资产一致性
+- **WHEN** 三个资产分别求值，Depth Scale 设为零或设为 1
+- **THEN** 三者都表现为零不切开、1 与改动前一致

openspec/changes/scale-depth-split-by-depth-scale/tasks.md

@@ -0,0 +1,16 @@
+## 1. Split 判据
+
+- [x] 1.1 `split_depth_surface` 增加 Depth Scale 参数，落差项乘该因子，并按新含义更新 docstring。
+- [x] 1.2 `O Image Depth Plane`、`O Image Depth Cutout`、`O Image Depth Panorama` 传入各自的 Depth Scale，并把 Depth Split 的参数说明改为随 Depth Scale 缩放。
+
+## 2. 测试
+
+- [x] 2.1 反转 `test_split_topology_uses_depth_before_display_scaling`：Depth Scale 为 0 时不切开且拓扑与关闭 Split 相同，为 1 时与现有结果一致。
+- [x] 2.2 更新 `test_split_mapping_and_uniform_scale` 中 Depth Scale 为 0 仍保持切边的断言。
+- [x] 2.3 为 `O Image Depth Cutout` 与 `O Image Depth Panorama` 补充 Depth Scale 为 0 不切开的覆盖。
+
+## 3. 资产与规范
+
+- [x] 3.1 运行 `uv run node-group build` 重建并验证 `O_AnyImage.blend`。
+- [x] 3.2 修订 `reorganize-cutout-shapes` 中 `depth-cutout-volume` 的 Split 条目，使其与投影后落差判据一致。
+- [x] 3.3 运行相关节点测试并确认通过。