Initial public release

openspec/changes/archive/2026-09-17-improve-relief-depth-controls/.openspec.yaml

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

openspec/changes/archive/2026-09-17-improve-relief-depth-controls/design.md

@@ -0,0 +1,52 @@
+## Context
+
+`O Image Relief Plane` 先由 `O Image Plane` 生成固定底面位于 `Z=0`、可变面位于 `Z=Thickness` 的几何，再按 `Reference Depth - sampled depth` 计算位移。当前有厚度时，负位移最多接近 `-Thickness`，因此可变面会进入基础厚度区域；`Reference Depth` 又是校准值，不适合作为艺术调整用的整体平移控件。
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- 将 `Z=Thickness` 明确定义为 depth 0 和浮雕深度的最低高度。
+- 让 `Depth Scale` 以 depth 0 为位移基准改变起伏幅度。
+- 提供默认值为 `1` 的 `Depth Offset`，在方向换算和缩放之前进一步矫正 `Reference Depth`。
+- 保持固定底面不动，并保持侧壁各层按原有权重插值位移。
+- 创建 Relief Plane 时给出基于完整有效深度场的近似 `Depth Direction`。
+
+**Non-Goals:**
+
+- 不改变 `Reference Depth`、`Uniform Scale` 或 `Depth Direction` 的含义。
+- 不改变 Depth Plane、Cutout、AI 产物及对象创建流程。
+- 不为旧节点图保留兼容接口或迁移节点。
+
+## Decisions
+
+### 使用单一最终位移公式
+
+可变面的完整标量位移定义为：
+
+`corrected_reference_depth = reference_depth + depth_offset`
+
+`relief_offset = max((direction_adjusted(corrected_reference_depth) - sampled_metric_depth) * depth_scale, 0)`
+
+最终可变面高度为 `Thickness + relief_offset`。`Depth Offset` 与 `Reference Depth` 先相加，矫正后的参考深度再参与 `Depth Direction` 的参考平面换算、采样深度求差和 `Depth Scale` 缩放。缩放只产生从 `Thickness` 高度出发的位移，所以 depth 0 始终对应 `Thickness` 高度。
+
+备选方案是把 `Depth Offset` 作为缩放后的几何平移，但这会脱离参考深度标定，并使 `Depth Scale=0` 时仍产生位移。将它作为 Reference Depth 矫正值，可让两者遵循同一套方向和缩放语义。
+
+### Depth Offset 使用主界面距离输入
+
+新增 `Depth Offset`，类型为 Float、subtype 为 `DISTANCE`、默认值为 `1`，允许正负值。`Depth Direction` 与 `Depth Offset` 均不放入 Options，主界面在 `Thickness` 后依次排列 `Depth Direction`、`Depth Offset`、`Depth Scale`。节点图先将 Depth Offset 与 `Reference Depth` 相加，再把结果传入现有 `reference_plane_depth()`。
+
+### 沿现有层权重应用最终位移
+
+最终 `relief_offset` 继续乘以从固定底面到可变面的 `layer_weight`。这样固定底面保持 `Z=0`，可变面应用完整位移，侧壁中间层保持线性插值。`Thickness=0` 时沿用现有权重为 `1` 的单面行为。
+
+### Relief 与 Cutout Symmetry 共用稳健平面拟合
+
+将稳健深度平面拟合下沉到 `common.depth`。Relief 创建时把完整深度图的有效像素中心映射到图片平面的局部 XY，以 `Uniform Scale` 转为本地深度后拟合平面，并用归一化 `(slope_x, slope_y, 1)` 初始化 `Depth Direction`。Cutout Symmetry 改用同一公共函数，继续在其裁切网格采样域上拟合，避免维护两套算法。`Depth Offset` 使用节点组默认值 `1`。
+
+## Risks / Trade-offs
+
+- [已有场景依赖浮雕压入基础厚度] → 这是本次明确要求的行为变化；通过几何求值测试锁定新边界，不增加兼容分支。
+- [负 Depth Offset 使更多采样在 depth 0 处被截断，局部细节可能变平] → 接口说明明确 Depth Offset 是参考深度矫正，并用正、负 Depth Offset 场景覆盖预期。
+- [节点接口和发布资产不一致] → 修改构建脚本后运行 `uv run node-group build`，同时检查保存资产接口和求值结果。
+- [整图内容不是单一平面] → 沿用 Cutout Symmetry 的迭代稳健权重降低离群深度影响，只把结果作为可继续手调的初始值。

openspec/changes/archive/2026-09-17-improve-relief-depth-controls/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+`O Image Relief Plane` 当前允许远于参考深度的采样把浮雕面压到 `Thickness` 高度以下，只在接近固定底面时停止，导致基础厚度同时承担浮雕零点和防穿透边界，深度整体位置也无法独立调节。需要明确浮雕深度零点，使缩放、钳制与整体偏移各自表达单一职责。
+
+## What Changes
+
+- 将 `Thickness` 所在高度定义为浮雕 depth 0，并把采样深度产生的向内位移钳制在该高度，不再让深度结果进入基础厚度区域。
+- 为 `O Image Relief Plane` 新增默认值为 `1` 的公开 `Depth Offset` 距离参数，作为 `Reference Depth` 的附加矫正，在方向换算和 `Depth Scale` 之前参与相对深度计算。
+- 将 `Depth Direction` 和 `Depth Offset` 移到主界面，并在 `Thickness` 后按 `Depth Direction`、`Depth Offset`、`Depth Scale` 排列。
+- 创建 Relief Plane 时从完整深度图拟合近似深度平面，并用其法向初始化 `Depth Direction`。
+- `Depth Scale` 以 `Thickness` 所在的 depth 0 为位移基准，并缩放包含 `Depth Offset` 矫正的相对深度；`Thickness` 高度本身不参与缩放。
+- 更新节点组行为测试、接口清单与发布 `.blend` 节点资产。
+
+## Capabilities
+
+### New Capabilities
+
+- `relief-plane-depth-controls`: 定义 Relief Plane 的 depth 0、钳制、缩放和整体偏移行为。
+
+### Modified Capabilities
+
+无。
+
+## Impact
+
+影响 `tools/nodes/groups/image_relief_plane.py`、`src/anyimage/common/depth.py`、Plane 创建逻辑、相关测试、节点资产接口清单，以及 `src/anyimage/assets/O_AnyImage.blend`。不增加依赖，也不改变 AI 深度产物；已有 Modifier 会获得新的节点组输入，原先依赖负向深度进入基础厚度区域的结果将发生变化。

openspec/changes/archive/2026-09-17-improve-relief-depth-controls/specs/relief-plane-depth-controls/spec.md

@@ -0,0 +1,73 @@
+## ADDED Requirements
+
+### Requirement: Relief depth is clamped at the thickness height
+`O Image Relief Plane` SHALL 将未置换可变面所在的 `Thickness` 高度定义为 depth 0。经过参考深度矫正、方向换算和 `Depth Scale` 得到的最终浮雕位移 MUST 不小于零，使可变面不进入固定底面与 `Thickness` 高度之间的基础厚度区域。
+
+#### Scenario: Far depth would move below depth zero
+- **WHEN** 矫正参考深度与采样深度之差经过方向换算和缩放后小于零
+- **THEN** 可变面的最终浮雕位移钳制为零
+- **AND** 可变面位于 `Thickness` 高度
+
+#### Scenario: Positive relief depth
+- **WHEN** 矫正参考深度与采样深度之差经过方向换算和缩放后大于零
+- **THEN** 可变面保留完整的正向浮雕位移
+- **AND** 正向位移不受 `Thickness` 大小限制
+
+#### Scenario: Keep the fixed base
+- **WHEN** `Thickness` 大于零且浮雕深度发生变化
+- **THEN** 固定底面的所有顶点保持在对象空间 `Z=0`
+- **AND** 侧壁各层按其从固定底面到可变面的归一化位置线性应用最终浮雕位移
+
+### Requirement: Relief Plane exposes a reference depth correction
+`O Image Relief Plane` SHALL 在主界面公开 `Depth Offset` 距离输入，默认值为 `1` 并允许正负值。`Depth Direction` 与 `Depth Offset` SHALL 移出 Options，并在 `Thickness` 后按 `Depth Direction`、`Depth Offset`、`Depth Scale` 排列。系统 SHALL 先按 `Reference Depth + Depth Offset` 得到矫正参考深度，再进行 `Depth Direction` 参考平面换算、与缩放采样深度求差及 `Depth Scale` 缩放，最后把负位移钳制为零。
+
+#### Scenario: Use the default offset
+- **WHEN** `Depth Offset` 为默认值 `1`
+- **THEN** 矫正参考深度等于 `Reference Depth + 1`
+- **AND** 系统按现有方向换算和 `Depth Scale` 计算浮雕位移
+- **AND** 最终结果仍钳制在 depth 0
+
+#### Scenario: Increase the reference depth correction
+- **WHEN** 用户增加 `Depth Offset`
+- **THEN** 系统在方向换算和 `Depth Scale` 之前增加矫正参考深度
+- **AND** Depth Offset 对最终位移的影响随 `Depth Scale` 一同缩放
+
+#### Scenario: Decrease the reference depth correction
+- **WHEN** 用户减小 `Depth Offset`
+- **THEN** 系统在方向换算和 `Depth Scale` 之前减小矫正参考深度
+- **AND** 任何结果均不低于 depth 0
+
+#### Scenario: Apply depth direction after correction
+- **WHEN** `Depth Offset` 非零且用户改变 `Depth Direction`
+- **THEN** 系统使用包含 Depth Offset 的矫正参考深度构建方向调整后的参考平面
+- **AND** 随后才计算相对深度和应用 `Depth Scale`
+
+### Requirement: Depth Scale uses depth zero as its invariant origin
+`Depth Scale` SHALL 以 depth 0 为几何位移基准，缩放包含 `Depth Offset` 矫正的相对深度差，MUST 不缩放 `Thickness` 高度本身。
+
+#### Scenario: Set depth scale to zero
+- **WHEN** `Depth Scale` 为 `0`
+- **THEN** 采样深度差、`Reference Depth` 和 `Depth Offset` 均不产生几何位移
+- **AND** 可变面位于 `Thickness` 高度
+
+#### Scenario: Change depth scale
+- **WHEN** 用户改变 `Depth Scale` 且保持 `Thickness`、`Reference Depth` 和 `Depth Offset` 不变
+- **THEN** 系统以 depth 0 为基准缩放包含 Depth Offset 矫正的采样深度差
+- **AND** `Thickness` 所在高度保持不变
+
+### Requirement: Relief Plane initializes an approximate depth direction
+系统 SHALL 在创建 Relief Plane 时，将完整深度图的有效像素映射到图片平面局部坐标，以 `Uniform Scale` 换算深度并进行稳健平面拟合，再用拟合平面的归一化方向初始化 `Depth Direction`。Relief Plane 与 Cutout Symmetry MUST 共用同一平面拟合实现。
+
+#### Scenario: Create a relief from a sloped depth field
+- **WHEN** 有效深度场包含可拟合的整体斜率
+- **THEN** 新建 Relief Plane 的 `Depth Direction` 使用拟合斜率对应的归一化方向
+- **AND** `Depth Offset` 保持默认值 `1`
+
+#### Scenario: Create a relief from a flat depth field
+- **WHEN** 有效深度场整体为平面且没有斜率
+- **THEN** 新建 Relief Plane 的 `Depth Direction` 近似为 `(0, 0, 1)`
+
+#### Scenario: Create a relief without usable depth samples
+- **WHEN** 深度图没有可用于拟合的正有限深度
+- **THEN** Relief Plane 仍然成功创建
+- **AND** `Depth Direction` 回退为 `(0, 0, 1)`

openspec/changes/archive/2026-09-17-improve-relief-depth-controls/tasks.md

@@ -0,0 +1,21 @@
+## 1. Relief depth behavior
+
+- [x] 1.1 Add the public `Depth Offset` distance input to `O Image Relief Plane`, with a default of one and signed range; expose `Depth Direction`, `Depth Offset`, and `Depth Scale` directly below `Thickness` in that order.
+- [x] 1.2 Add `Depth Offset` to `Reference Depth` before `reference_plane_depth()`, then replace the thickness-dependent inward limit with a zero clamp after direction adjustment and `Depth Scale`, preserving fixed-base and side-layer weighting.
+
+## 2. Behavior verification
+
+- [x] 2.1 Update Relief Plane geometry tests to verify far depths stop at `Thickness`, positive depths remain unrestricted, and the fixed base and side interpolation remain valid.
+- [x] 2.2 Add positive, negative, and zero `Depth Offset` tests, including direction adjustment, `Depth Scale = 0`, and checks that Depth Offset is scaled as part of the corrected relative depth while the depth-zero height remains fixed.
+- [x] 2.3 Update the node-group interface inventory test for `Depth Direction` and `Depth Offset` names, order, panel placement, and old base-plane clamp behavior.
+
+## 3. Node asset
+
+- [x] 3.1 Run `uv run node-group build` to rebuild and validate `src/anyimage/assets/O_AnyImage.blend` from the updated source and tests.
+- [x] 3.2 Run the relevant Relief Plane and plane-object tests, then inspect the final diff for stale inward-limit nodes or old behavior references.
+
+## 4. Initial depth direction
+
+- [x] 4.1 Extract the robust plane-direction fit into `common.depth` and reuse it from Cutout Symmetry calibration.
+- [x] 4.2 Fit the complete valid Relief depth image in local plane coordinates and initialize the new Modifier's `Depth Direction`.
+- [x] 4.3 Add sloped-depth initialization and shared calibration regression tests.