Initial public release

openspec/changes/archive/2026-09-17-split-depth-and-relief-planes/.openspec.yaml

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

openspec/changes/archive/2026-09-17-split-depth-and-relief-planes/design.md

@@ -0,0 +1,68 @@
+## Context
+
+两个转换入口分别使用相机投影和浮雕节点组。Server 生成相机 XYZ 深度与对应空间的法线，客户端创建矩形基础网格并加载节点组。depth.exr 的 Alpha 存储模型有效性，作为 Valid Only 的判定依据。
+
+工作区已有材质和转换代码修改，实施须以当前代码为基础保留这些行为。
+
+## Goals
+
+提供独立的 Depth Plane 与 Relief Plane 转换；Depth Plane 在节点内按深度有效性 Alpha 剔除几何，保留动态细分，并使用 Object Space 法线。
+
+## Decisions
+
+### 入口与节点资产
+
+| 入口 | Operator | 节点组 | 形状 | 法线空间 |
+| --- | --- | --- | --- | --- |
+| Convert to Depth Plane | `anyimage.convert_to_depth_plane` | `O Image Depth Plane` | 相机投影曲面 | OBJECT |
+| Convert to Relief Plane | `anyimage.convert_to_relief_plane` | `O Image Relief Plane` | 固定底面浮雕 | TANGENT |
+
+两个节点组各自保留 Subdivide、Thickness、Depth Scale、Reference Depth 及所需数据输入。Depth Plane 额外保留 Normal Smooth，增加默认开启的 Valid Only。Relief Plane 延续原 Relief 的厚度与位移语义。移除 Mode 与 Camera Thickness 命名，各组使用自己的 Thickness。
+
+两个 Operator 共用图片准备、Job 调度和产物加载函数，通过可序列化业务参数区分转换类型。后端沿用整图深度 Job，并根据转换类型生成对应的单份法线产物。新类型纳入注册和逆序注销。
+
+### 节点内 Alpha 剔除
+
+```mermaid
+flowchart TD
+    A[矩形基础网格与 UV] --> B[Subdivide 生成网格]
+    B --> C{Valid Only}
+    D[depth.exr 有效性 Alpha] --> E[Alpha 小于 1 后在 Point 域求值]
+    E --> F[剔除透明区域几何]
+    C -- 开启 --> F
+    C -- 关闭 --> G[相机 XYZ 投影]
+    F --> G
+    G --> H[曲面厚度]
+    H --> I[清理临时属性与输出]
+```
+
+剔除读取depth.exr 的有效性 Alpha，并使用原图 UV。直接使用 Data 中已有的 Depth Image 输入。用户只控制 Valid Only 和已有 Subdivide；内部使用 Linear / Extend 深度采样，Separate Color 的 Alpha 接 Float / Less Than（B = 1），再经 Boolean / Point 的 Evaluate on Domain 接 Face / All 的 Delete Geometry。仅全部顶点有效性均小于 1 的面删除，混合边界面保留。
+
+剔除在几何节点中每次求值，避免将轮廓烘焙为固定网格。Valid Only 关闭时，投影与厚度接收完整细分网格。节点处理保持 UV、原图构图和世界位置。
+
+### 最终几何平滑
+
+Depth Plane 在投影、厚度及临时属性清理后直接调用 `node_graph.expand_smooth()`，复用 Depth Cutout 的 Smooth 模块。主接口 Smooth 默认 0、范围 0–20；Options 中 Smooth Weight 默认 1、范围 0–1，subtype 为 FACTOR。其后执行平滑着色与输出。
+
+### 法线产物与材质
+
+Depth Plane 请求并读取 `object_normal`，通过 `create_image_material(..., normal_space="OBJECT")` 创建材质；Relief Plane 请求并读取 `tangent_normal`，使用 TANGENT。复用现有法线编码和材质入口，确认相机轴到对象局部轴的转换与曲面投影一致。
+
+深度继续使用 `depth`、`depth_metadata` 协议，RGB 保存相机 XYZ，Alpha 保存有效性。
+
+## Risks / Trade-offs
+
+- Alpha 边界受网格密度影响 → 用有效性为 0、介于 0 和 1、混合边界和细窄结构验证参考图的宽松规则，并检查调整 Subdivide 后的实际结果。
+- Object Normal 与局部投影坐标不一致会造成明暗反向 → 验证法线轴向、材质空间设置及对象旋转后的表现。
+- 裁剪后的开口边界影响曲面厚度 → 在零厚度和正厚度下验证边界、UV 与几何求值。
+- 节点资产接口发生破坏性变化 → 构建脚本、验证及测试按两个独立资产同步更新，删除合并模式的旧连接与引用。
+
+## Migration Plan
+
+实现顺序为入口与请求分流、法线产物绑定、节点组拆分、Alpha 剔除、验证与测试。沿用现有 Depth Plane 标识作为 Camera 入口，新增 Relief 标识，不增加旧模式兼容层。节点接口变化同步节点资产文档。
+
+代码阶段运行测试；资产构建与 Blender 节点编辑器视觉验收作为后续资产更新阶段单独执行，交付时分别说明完成状态。
+
+## Reference Graph
+
+用户参考图已确认：Separate Color / Alpha → Less Than 1 → Evaluate on Domain（Boolean、Point）→ Delete Geometry（Face、All）。Valid Only 通过几何 Switch 控制此段，关闭时使用完整细分网格。节点资产构建和 Blender 检查已获用户授权。

openspec/changes/archive/2026-09-17-split-depth-and-relief-planes/proposal.md

@@ -0,0 +1,28 @@
+## Why
+
+整图相机投影与固定底面浮雕需要独立的转换入口和几何节点。相机投影生成背景模型时，透明区域需要参与几何剔除，同时保留修改器中调整网格密度的能力。
+
+## What Changes
+
+- **BREAKING**：拆分现有 Relief / Camera 模式，`Convert to Depth Plane` 专门生成相机投影曲面，新增 `Convert to Relief Plane` 生成固定底面浮雕。
+- 两个入口分别加载 `O Image Depth Plane` 和 `O Image Relief Plane`，各自提供所需参数，移除 Mode 选择与跨模式参数。
+- Depth Plane 在基础网格细分后、深度投影与厚度处理前，根据depth.exr 有效性 Alpha 宽松剔除几何。修改器提供默认开启的 `Valid Only` 开关，保留 `Subdivide` 动态调节。
+- 宽松剔除使用深度有效性 Alpha < 1，经 Boolean / Point 的 Evaluate on Domain 后连接 Face / All 的 Delete Geometry。
+- Depth Plane 生成并使用 Object Space Normal Map；Relief Plane 延续 Tangent Space Normal Map。
+
+- Depth Plane 复用 Depth Cutout 的 Smooth 模块，在最终曲面或厚度几何上执行平滑，提供 Smooth 和 Smooth Weight。
+
+## Capabilities
+
+### New Capabilities
+
+- `separate-depth-relief-planes`：独立转换入口、节点资产、参数及对应法线空间。
+- `depth-plane-alpha-culling`：可开关、随细分重新求值的 Alpha 几何剔除。
+
+### Modified Capabilities
+
+无；当前 `openspec/specs/` 无已归档规范。本提案接续 `unify-depth-plane-and-artifact` 的现有实现。
+
+## Impact
+
+涉及转换 Operator、菜单与注册、Server Job 参数与法线产物、对象和材质创建、节点资产构建脚本、布局、验证及测试。节点资产文档随接口更新。复用现有深度协议与 Object Normal 生成能力，无需新增依赖。实施时保留工作区已有修改；执行测试，节点资产构建与 Blender 视觉验收单独安排。

openspec/changes/archive/2026-09-17-split-depth-and-relief-planes/specs/depth-plane-alpha-culling/spec.md

@@ -0,0 +1,36 @@
+## ADDED Requirements
+
+### Requirement: Optional alpha culling defaults to enabled
+Depth Plane 修改器 SHALL 提供默认开启的 Valid Only 开关，按 depth.exr 有效性 Alpha 剔除几何。该处理 MUST 在基础网格细分之后、深度投影和厚度之前执行。
+
+#### Scenario: Default conversion
+- **WHEN** 用户转换包含无效深度区域的图片为 Depth Plane
+- **THEN** Valid Only 默认开启，深度有效性 Alpha 参与基础网格的几何剔除
+
+#### Scenario: Disable alpha culling
+- **WHEN** 用户关闭 Valid Only
+- **THEN** 完整细分网格进入相机投影与厚度流程
+
+#### Scenario: Fully valid depth
+- **WHEN** depth.exr 有效性 Alpha 全部为 1
+- **THEN** Alpha 剔除保留完整基础网格
+
+### Requirement: Culling remains responsive to subdivision
+系统 SHALL 在节点内重新求值 Alpha 剔除，允许用户继续通过 Subdivide 调节网格。剔除后的几何 MUST 保留正确 UV，并进入现有相机投影和曲面厚度计算。
+
+#### Scenario: Change subdivision
+- **WHEN** 用户修改 Subdivide
+- **THEN** 节点重新生成网格并依据该网格重新检测 Alpha，无需重新运行 AI
+
+#### Scenario: Apply thickness after culling
+- **WHEN** 用户对已剔除的曲面设置正 Thickness
+- **THEN** 厚度从保留的曲面生成，无效区域已删除的基础面不会重新出现
+
+### Requirement: Permissive culling follows the reference graph
+Alpha 剔除 MUST 使用用户参考图中的宽松判定连接，且只公开 Valid Only 开关，网格精度使用已有 Subdivide。
+
+深度图片 SHALL 使用 Linear / Extend 采样；Separate Color 的 Alpha SHALL 接 Float / Less Than（B = 1），结果通过 Boolean / Point 的 Evaluate on Domain 后接 Delete Geometry（Face、All）。一个面仅在所有顶点都满足 Alpha < 1 时删除；至少一个顶点 Alpha 为 1 的边界面保留。
+
+#### Scenario: Verify the reference rule
+- **WHEN** 实现 Alpha 判定
+- **THEN** 节点连接、运算、默认值和域设置与参考图一致，有效与无效区域交界网格的保留结果符合该图规则

openspec/changes/archive/2026-09-17-split-depth-and-relief-planes/specs/separate-depth-relief-planes/spec.md

@@ -0,0 +1,50 @@
+## ADDED Requirements
+
+### Requirement: Independent conversion entries and assets
+系统 SHALL 提供 Convert to Depth Plane 和 Convert to Relief Plane 两个入口，分别加载 `O Image Depth Plane` 与 `O Image Relief Plane`。Depth Plane MUST 使用相机投影，Relief Plane MUST 使用固定底面浮雕。两组 SHALL 提供各自参数并移除 Mode 选择。
+
+#### Scenario: Convert an image to a depth plane
+- **WHEN** 用户对静态 Image Empty 执行 Convert to Depth Plane
+- **THEN** 系统创建相机投影曲面，绑定独立 Depth Plane 节点组，并保留原图构图、UV 与世界位置
+
+#### Scenario: Convert an image to a relief plane
+- **WHEN** 用户对静态 Image Empty 执行 Convert to Relief Plane
+- **THEN** 系统创建固定底面浮雕，绑定独立 Relief Plane 节点组，Thickness 与 Depth Scale 延续原 Relief 语义
+
+#### Scenario: Inspect modifier controls
+- **WHEN** 用户查看两种结果的修改器
+- **THEN** 两者各自提供 Subdivide、Thickness、Depth Scale、Reference Depth，Depth Plane 提供 Normal Smooth，两者均无 Mode 选择
+
+### Requirement: Normal space follows conversion type
+系统 SHALL 为 Depth Plane 生成并消费 `object_normal`，材质使用 OBJECT 空间；为 Relief Plane 生成并消费 `tangent_normal`，材质使用 TANGENT 空间。法线编码 MUST 与对应对象局部坐标一致。
+
+#### Scenario: Depth material uses object normals
+- **WHEN** Depth Plane Job 完成并创建材质
+- **THEN** 材质加载 Object Normal 产物并启用 Object Space，法线轴向与相机投影后的局部几何一致
+
+#### Scenario: Relief material uses tangent normals
+- **WHEN** Relief Plane Job 完成并创建材质
+- **THEN** 材质加载 Tangent Normal 产物并使用 Tangent Space
+
+### Requirement: Shared conversion lifecycle
+两个转换 SHALL 使用静态图与 AI 就绪检查、统一深度产物协议、对象替换及失败清理流程。新增 Operator MUST 纳入注册与逆序注销。
+
+#### Scenario: Failed result creation
+- **WHEN** 任一转换在加载产物或创建对象时失败
+- **THEN** 系统保留可用源对象，并清理本次创建且未被使用的数据块
+
+#### Scenario: Extension lifecycle
+- **WHEN** 扩展注册后逆序注销
+- **THEN** 两个转换入口均正确注册与移除
+
+
+### Requirement: Depth plane shares Cutout smoothing
+Depth Plane SHALL 在投影与厚度之后复用 Depth Cutout 的 Smooth 模块。Smooth MUST 默认 0、范围 0–20；Options 中的 Smooth Weight MUST 默认 1、范围 0–1，使用 FACTOR 子类型。
+
+#### Scenario: Smooth final geometry
+- **WHEN** 用户增加 Smooth 并使用正 Smooth Weight
+- **THEN** 最终顶点位置按 Cutout 的共用规则平滑，面连接与 UV 保持一致
+
+#### Scenario: Disable smoothing
+- **WHEN** Smooth 为 0 或 Smooth Weight 为 0
+- **THEN** 几何位置与未平滑结果相同

openspec/changes/archive/2026-09-17-split-depth-and-relief-planes/tasks.md

@@ -0,0 +1,39 @@
+## 1. 补齐 Alpha 规则
+
+- [x] 1.1 获取用户节点连接参考图，记录 Alpha 采样、阈值、字段域、删除模式和宽松边界结果，补齐 design 与 Alpha 规格；本项完成后实施第 4 组任务。
+
+## 2. 转换入口与法线
+
+- [x] 2.1 新增 ConvertToReliefPlane、菜单项与注册清单，ConvertToDepthPlane 改为相机投影语义，复用整图任务调度函数。
+- [x] 2.2 为整图 Job 增加可序列化转换类型参数，Depth 生成 object_normal，Relief 生成 tangent_normal，验证各自产物键与深度协议。
+- [x] 2.3 按转换类型加载节点组和法线，绑定 OBJECT / TANGENT 材质空间，保持对象替换、Undo 与失败清理行为。
+
+## 3. 独立节点资产
+
+- [x] 3.1 将相机投影与浮雕分别整理为 O Image Depth Plane 和 O Image Relief Plane 构建脚本，删除 Mode 与跨模式接口、旧连接及无用引用。
+- [x] 3.2 整理两组布局与验证脚本，确认接口顺序、参数默认值、未使用输出隐藏，以及独立 Thickness 和 Normal Smooth 的归属。
+
+## 4. 节点内 Alpha 剔除
+
+- [x] 4.1 为 Depth Plane 添加默认开启的 Valid Only ，复用现有 Depth Image 输入读取 depth.exr 的有效性 Alpha。
+- [x] 4.2 按已确认参考图在细分后、投影前连接宽松剔除，关闭开关时旁路完整网格，保留 UV 并衔接厚度计算。
+- [x] 4.3 验证全无效、全有效、中间有效性、混合边界与细窄区域，检查 Subdivide 改变后重新求值及零厚度、正厚度结果。
+
+## 5. 测试与接口说明
+
+- [x] 5.1 更新入口、注册注销、Job 产物、对象创建与材质测试，覆盖 Object Normal 轴向和 Relief 行为。
+- [x] 5.2 更新节点结构与几何求值测试，按参考图检查运算、默认值、域及连接，覆盖开关和动态细分。
+- [x] 5.3 同步节点资产文档中的两个资产接口与处理流程，检查当前源码和资产脚本中的旧模式引用。
+- [x] 5.4 完成最终全量测试并确认正常退出。节点资产与转换相关 69 项测试通过，退出码 0。
+
+## 6. 后续节点资产更新阶段
+
+- [x] 6.1 已按用户授权构建 src/anyimage/assets/O_AnyImage.blend，Blender 4.5.10 的资产清单、接口、布局与几何验证通过。
+- [x] 6.2 在 Blender 中按实际节点尺寸检查总览与局部布局，并以风景透明图检查剔除轮廓、厚度、细分调节和对象旋转后的法线表现。
+
+
+## 7. 复用 Cutout Smooth
+
+- [x] 7.1 在 Depth Plane 最终几何上复用 expand_smooth，沿用 Smooth 与 Smooth Weight 的默认值、范围及接口归属。
+- [x] 7.2 覆盖零厚度和正厚度的平滑、关闭平滑、面连接与 UV 保持，并同步节点资产说明。
+- [x] 7.3 节点资产已重建，Blender 资产验证和 69 项相关测试通过。