feat: Add new Geometry Nodes groups for image relief and shadeless shader
- Implemented the "O Image Relief Plane" Geometry Nodes group to create a fixed-base image relief using depth images and various parameters. - Created the "O Shadeless" shader node group to display color without scene lighting while preserving shadows and reflections. - Introduced a preview feature for node groups, allowing for interactive visualization of node arrangements in an HTML format. - Added a template HTML file for rendering node previews with customizable views and controls.
This commit is contained in:
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-09
|
||||
44
openspec/changes/add-image-layer-alpha-adjustment/design.md
Normal file
44
openspec/changes/add-image-layer-alpha-adjustment/design.md
Normal file
@@ -0,0 +1,44 @@
|
||||
## Context
|
||||
|
||||
`build_material_layer_group()` 共用构建 O Image Layer 和 O Image Depth Layer。普通层直接传出输入 Alpha，深度层使用前景阈值。`create_image_material()` 已集中创建材质，并通过 `configured_material_view_adaptation()` 配置颜色图片。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
目标是将参考图的 Alpha 调整内置到 O Image Layer，支持连续强度调节，并在创建时读取现有偏好。变更范围为普通图像材质层；深度层继续使用其前景阈值协议。
|
||||
|
||||
## Decisions
|
||||
|
||||
### 曲线与接口
|
||||
|
||||
O Image Layer 的默认折叠面板 `Options` 依次包含 `Alpha Fix`、`Normal Scale`、`Object Space`。Alpha Fix 类型为 NodeSocketFloat，subtype 为 FACTOR，范围 0–1，默认 0。直接连接 ShaderNodeFloatCurve 的 Factor，复用节点自身的混合语义：`output = (1 - factor) * alpha + factor * curve(alpha)`。
|
||||
|
||||
曲线使用四个点：起点 `(0, 0)`、低端控制点 `(0.8, 0)`、上方控制点 `(0.925, 0.925)` 和终点 `(1, 1)`。上方控制点为参考图估计值。采用自动钳制手柄、水平延伸及 0–1 的裁剪与采样区间。低端控制点之后快速上升，完整调整时输入 0.85 输出约 0.1593、输入 0.9 输出约 0.774；低端附近存在 Blender 曲线查表插值误差，测试容差为 0.0003。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[组输入 Alpha] --> C[Float Curve Value]
|
||||
B[组输入 Alpha Fix] --> D[Float Curve Factor]
|
||||
C --> E[曲线调整并按 Factor 混合]
|
||||
D --> E
|
||||
E --> F[组输出 Alpha]
|
||||
F --> G[Principled Alpha 或 Shadeless 混合系数]
|
||||
```
|
||||
|
||||
Alpha 曲线放在独立且就近的支线，保持曲线可见、默认节点标题和未使用输出隐藏；Color、Roughness 与 Normal 保持各自连接。
|
||||
|
||||
### 创建时应用偏好
|
||||
|
||||
`create_image_material()` 在普通层节点绑定后读取现有公共偏好函数，将节点实例的 `Alpha Fix` 设为 1 或 0。判断依据就是偏好值，因此开启偏好但颜色空间回退到 sRGB 时仍设为 1。手动拖入节点组时采用资产默认值 0。
|
||||
|
||||
用户随后可独立调整每个材质实例；偏好切换只影响后续创建。普通着色与 Shadeless 共用组输出 Alpha。Color 图片的颜色空间和 Alpha 模式继续由现有配置入口处理。
|
||||
|
||||
### 验证与交付
|
||||
|
||||
修改构建脚本、资产验证及材质测试；通过测试期间构建的节点组检查接口、连接与曲线采样。节点资产文档按节点组专项规范同步描述接口。用户已授权更新节点资产，O_AnyImage.blend 中的 O Image Layer 与运行时代码配套交付；在 Blender 节点编辑器确认实际尺寸、节点间距和连接，并运行全量测试及资产验证。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 截图未展示所有精确坐标与手柄设置 → 用上述初值实现，检查曲线采样，并对照实际节点编辑器及透明边缘效果验收。
|
||||
- 曲线会削弱中低 Alpha → 默认手动实例强度为 0，创建时按用户偏好启用，保留每个实例的强度控制。
|
||||
- 工作区已有材质与节点资产修改 → 在当前实现上追加变更，保留已有修改并检查最终差异。
|
||||
- 旧资产缺少输入 → 验证资产接口与运行时代码一致，正式发布配套资产。
|
||||
@@ -0,0 +1,27 @@
|
||||
## Why
|
||||
|
||||
使用 inverse 类颜色空间时，用户观察到 Alpha 无法正确遮盖图片边缘，手动添加 Float Curve 后可改善。将这项调整放入 O Image Layer，让材质创建时自动应用，并允许用户调节强度。
|
||||
|
||||
## What Changes
|
||||
|
||||
- O Image Layer 内新增 Alpha Float Curve，依据参考图设置曲线。
|
||||
- 默认折叠的 `Options` 面板依次包含 `Alpha Fix`、`Normal Scale`、`Object Space`；Alpha Fix 连接 Float Curve 的 Factor，范围 0–1，默认 0。
|
||||
- 创建使用 O Image Layer 的材质时，读取 `Adapt to Scene View Transform`：开启设为 1，关闭设为 0。
|
||||
- 验证曲线、接口、材质创建和着色输出行为。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `image-layer-alpha-adjustment`: 材质层 Alpha 曲线调整、强度输入与创建时偏好联动。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
无。
|
||||
|
||||
## Impact
|
||||
|
||||
- `tools/node_assets/material_layers.py`：节点组接口、曲线与布局。
|
||||
- `src/anyimage/common/material.py`：创建节点实例时设置调整强度。
|
||||
- `tools/node_assets/asset_validation.py` 及材质相关测试：接口、连接、曲线求值和偏好联动验证。
|
||||
- 发布节点资产 `src/anyimage/assets/O_AnyImage.blend` 需要包含新接口；本轮仅生成提案。
|
||||
@@ -0,0 +1,56 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Image layer exposes alpha adjustment strength
|
||||
|
||||
O Image Layer SHALL 在默认折叠的 `Options` 面板中依次提供 `Alpha Fix`、`Normal Scale`、`Object Space`。Alpha Fix SHALL 为浮点输入，范围 0–1，subtype 为 FACTOR，默认 0，并以该值控制内部 Alpha Float Curve 的 Factor。
|
||||
|
||||
#### Scenario: Options are initially collapsed
|
||||
- **WHEN** 创建 O Image Layer 节点实例
|
||||
- **THEN** Options 面板 SHALL 默认折叠，包含 Alpha Fix、Normal Scale、Object Space
|
||||
- **AND** Color、Alpha、Normal、Bump Scale SHALL 位于面板外
|
||||
|
||||
#### Scenario: Adjustment is disabled
|
||||
- **WHEN** Alpha Fix 为 0
|
||||
- **THEN** 组输出 Alpha SHALL 等于输入 Alpha
|
||||
|
||||
#### Scenario: Adjustment is fully applied
|
||||
- **WHEN** Alpha Fix 为 1
|
||||
- **THEN** 组输出 Alpha SHALL 等于内部 Float Curve 对输入 Alpha 的求值
|
||||
|
||||
#### Scenario: Adjustment is partially applied
|
||||
- **WHEN** Alpha Fix 为 0.5
|
||||
- **THEN** 输出 SHALL 等于原始 Alpha 与完整曲线结果的平均值
|
||||
|
||||
### Requirement: Alpha curve follows the reference profile
|
||||
|
||||
Alpha 曲线 SHALL 使用四个点：起点 `(0, 0)`、低端控制点 `(0.8, 0)`、靠近右上方的平滑控制点和终点 `(1, 1)`，形成参考图中的快速上升轮廓。对输入范围 0–1，完整调整后的输出 SHALL 保持在 0–1，保持单调不减，并保持完全透明与完全不透明端值。
|
||||
|
||||
#### Scenario: Low alpha is suppressed
|
||||
- **WHEN** 输入 Alpha 在 0–0.8 且调整强度为 1
|
||||
- **THEN** 输出 Alpha SHALL 为 0，允许浮点求值误差
|
||||
|
||||
#### Scenario: Opaque alpha is preserved
|
||||
- **WHEN** 输入 Alpha 为 1
|
||||
- **THEN** 任意调整强度下输出 Alpha SHALL 为 1
|
||||
|
||||
### Requirement: Material creation initializes adjustment from preferences
|
||||
|
||||
创建使用 O Image Layer 的材质时，系统 SHALL 通过现有偏好读取入口，将 Alpha Fix 初始化为 `Adapt to Scene View Transform` 开启时的 1、关闭时的 0。
|
||||
|
||||
#### Scenario: Adaptation is enabled
|
||||
- **WHEN** 开启适配后创建普通着色或 Shadeless 材质
|
||||
- **THEN** O Image Layer 实例的 Alpha Fix SHALL 为 1
|
||||
- **AND** 对应着色器 SHALL 使用该组调整后的 Alpha 输出
|
||||
|
||||
#### Scenario: Adaptation is disabled
|
||||
- **WHEN** 关闭适配后创建材质
|
||||
- **THEN** O Image Layer 实例的 Alpha Fix SHALL 为 0
|
||||
|
||||
#### Scenario: Color space falls back
|
||||
- **WHEN** 适配开启且颜色空间解析回退到 sRGB
|
||||
- **THEN** 新建 O Image Layer 实例的 Alpha Fix SHALL 仍为 1
|
||||
|
||||
#### Scenario: Existing material is manually adjusted
|
||||
- **WHEN** 用户修改现有材质的 Alpha Fix 后切换偏好
|
||||
- **THEN** 已有实例的调整值 SHALL 保留
|
||||
- **AND** 后续新建材质 SHALL 使用当前偏好初始化
|
||||
18
openspec/changes/add-image-layer-alpha-adjustment/tasks.md
Normal file
18
openspec/changes/add-image-layer-alpha-adjustment/tasks.md
Normal file
@@ -0,0 +1,18 @@
|
||||
## 1. Alpha 曲线与接口
|
||||
|
||||
- [x] 1.1 在 `material_layers.py` 的 O Image Layer 分支加入 Alpha Fix 输入及 Float Curve，按设计设置坐标、手柄、裁剪和连接。
|
||||
- [x] 1.2 调整节点布局及未使用输出隐藏，在实际 Blender 节点编辑器检查总览与曲线局部。
|
||||
- [x] 1.3 更新资产验证及对应测试，检查 socket 顺序、默认值、连接和曲线采样；覆盖强度 0、0.5、1、低 Alpha、端点、单调性与范围。
|
||||
|
||||
## 2. 材质创建联动
|
||||
|
||||
- [x] 2.1 在 `create_image_material()` 中复用偏好读取入口，为 O Image Layer 实例设置 Alpha Fix。
|
||||
- [x] 2.2 补充材质行为测试，覆盖偏好开关、sRGB 回退、普通着色、Shadeless 及现有材质手动值保留，验证 O Image Depth Layer 的既有 Alpha 行为。
|
||||
|
||||
## 3. 验收
|
||||
|
||||
- [x] 3.1 对照参考图验证曲线形状，使用透明边缘图片比较强度 0、0.5、1 的效果，记录估计控制点的最终取值。
|
||||
- [x] 3.2 按节点组专项规范同步 `docs/internals/node-assets.md` 的新输入与曲线说明。
|
||||
- [x] 3.3 按用户授权更新 O Image Layer 节点资产，运行全量测试并确认正常退出，检查最终差异和接口引用；验证 Blender 节点资产，不构建文档或扩展发布包。
|
||||
|
||||
验证结果：766 passed、2 xfailed、50 subtests passed，退出码 0；Blender 4.5.10 资产验证与 OpenSpec 严格校验通过。
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-09
|
||||
@@ -0,0 +1,57 @@
|
||||
## Context
|
||||
|
||||
动机见 proposal.md。当前共享 Artifact 入口合成黑底；GeometryFrame 保存原始模型 mask；EXR 写入 XYZ 与 mask。补边按 alpha 分量组织，但用包含 mask 的来源集合计算内部距离，会把内部 mask 孔洞也纳入修补。Depth Plane 已支持读取 EXR Alpha，默认 Validity Threshold 为 0.9。
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
本设计将输入颜色、轮廓深度修补和输出有效性分别放在模型输入准备、深度处理、EXR 写入三个边界。实施范围为共享深度产物及消费者测试，节点结构和参数沿用当前实现。
|
||||
|
||||
## Decisions
|
||||
|
||||
### RGB 输入与 alpha 并行处理
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[原始输入图] --> B[读取 RGB 后按输入上限缩放]
|
||||
B --> C[MoGe2 预测]
|
||||
C --> D[GeometryFrame：depth、points、validity 等]
|
||||
A --> E[读取原图 alpha 并对齐预测尺寸]
|
||||
D --> F[按 alpha 轮廓延伸深度]
|
||||
E --> F
|
||||
F --> G[EXR RGB：相机空间 XYZ]
|
||||
D --> H[原图 alpha × validity]
|
||||
E --> H
|
||||
H --> I[EXR Alpha]
|
||||
I --> J[Depth Plane 现有剔除节点]
|
||||
```
|
||||
|
||||
`_limited_model_input` 先 `convert("RGB")` 再 `limit_image`，使缩放直接处理 RGB。原图 alpha 继续从业务输入图单独读取，使用现有 NEAREST 对齐预测尺寸。这里的原图是本次 Job 输入，包含 Remove BG 等已经完成的 alpha 编辑。
|
||||
|
||||
### alpha 决定修补范围，mask 筛选来源
|
||||
|
||||
在 `edge_depth.py` 中分别计算 alpha 轮廓区域与深度来源：可见分量沿用调用方 alpha_threshold；内部距离由 alpha 条件确定。保留现有内部 2 像素保护带、轮廓外 4 像素采样延伸及局部平滑。
|
||||
|
||||
来源同时满足 alpha 条件、原始 validity > 0.5、有限正深度，优先使用同一分量内部来源；细小分量沿用分量内来源回退。低 mask 仅影响来源资格，不扩大修补目标或侵蚀轮廓内部区域。alpha 全 1 时保持现有直接返回行为。
|
||||
|
||||
修改深度后按目标像素射线重建 XYZ，保持未修补区域原值。修补结果的 validity 仍为模型 mask。0.5 是来源筛选条件，Depth Plane 的 0.9 是最终几何筛选阈值，两者各自保持现有用途。
|
||||
|
||||
### 在 EXR 写入边界组合 alpha
|
||||
|
||||
`write_depth_texture` 显式接收已对齐的原图 alpha，检查尺寸并以 float32 写入 `alpha * frame.validity`。统一迁移调用点，参数必需。GeometryFrame 始终保留原始模型信号，供延伸、Normal 和 Metadata 使用。
|
||||
|
||||
XYZ 与有效性通道各自计算：补边只改变 XYZ，alpha 乘积只用于 EXR A。Metadata 继续使用原始模型有效性、可见区域和有限正深度计算参考深度。
|
||||
|
||||
### 消费者沿用职责
|
||||
|
||||
Depth Plane 的 Valid Only 读取组合后的 EXR Alpha，继续使用现有阈值、线性采样和面域规则。Cutout 曲面由自身轮廓生成并采样 XYZ。检查共享 EXR Alpha 的校准读取，保证 Cutout 和 Relief Plane 的有效样本筛选符合组合通道语义。
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- 输入图的隐藏 RGB 可能已被清除 → 使用实际可用 RGB；用保留天空 RGB 的 Remove BG 输出验证输入一致性。
|
||||
- 两个连续值相乘会降低边缘有效性，例如 0.95 × 0.95 = 0.9025 → 测试直接固定乘积与当前阈值的消费行为。
|
||||
- alpha 延伸只能稳定轮廓附近的深度 → 用合成深度场验证边界与来源隔离；有原始风景图时再做模型对照，截图不作为预测正确性的证明。
|
||||
- 工作区有其他进行中修改 → 以当前实现为基础，独立提交本提案文件，实施时保留已有修改。
|
||||
|
||||
## Migration Plan
|
||||
|
||||
依次修改 RGB 准备、alpha 延伸范围、EXR 写入及所有调用，运行针对性与全量测试并确认正常退出。重新执行 Job 获得新产物。仅回退本变更引入的修改即可恢复旧行为。
|
||||
@@ -0,0 +1,25 @@
|
||||
## Why
|
||||
|
||||
透明图合成黑底后交给 MoGe2，会改变天空等背景及轮廓附近的 RGB，影响场景深度预测。Depth Plane 需要同时按原图覆盖范围和模型有效性剔除，Cutout 则需要稳定的 alpha 轮廓深度。
|
||||
|
||||
## What Changes
|
||||
|
||||
- MoGe2 输入先读取 RGB 再缩放，保留透明像素下的颜色。
|
||||
- 深度延伸以原图 alpha 轮廓确定范围，模型 mask 用于筛选可靠来源。
|
||||
- `GeometryFrame.validity` 保持模型 mask；导出 `depth.exr` 时 Alpha 为原图 alpha 与 validity 的乘积，RGB 保存延伸后的相机空间 XYZ。
|
||||
- Depth Plane 通过现有 Valid Only 与 Validity Threshold 消费 EXR Alpha；Cutout 继续按自身轮廓生成几何。
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `depth-alpha-semantics`: 定义 MoGe2 RGB 输入、alpha 轮廓延伸以及深度产物有效性通道。
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
## Impact
|
||||
|
||||
- 涉及 `server/geometry/prediction_artifacts.py`、`edge_depth.py`、`depth_texture.py` 及对应调用与测试。
|
||||
- 检查 Depth Plane、Cutout、Relief Plane 对共享深度产物的消费，包括校准用途。
|
||||
- 接续工作区已有 Depth Plane 与 Relief Plane 拆分实现，采用当前节点阈值和剔除规则。
|
||||
- 深度产物需重新生成以获得新 Alpha 语义。实现只运行测试，不同步内部文档或构建节点资产、扩展包；无新增依赖。
|
||||
@@ -0,0 +1,65 @@
|
||||
## Purpose
|
||||
|
||||
规定透明图进入 MoGe2 时的颜色语义、轮廓深度延伸范围和深度产物的有效性通道，使 Depth Plane 根据图像覆盖与模型判断剔除几何，同时为 Cutout 提供稳定的轮廓深度采样。
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Model input preserves source RGB
|
||||
|
||||
系统 SHALL 使用输入图 RGB 准备 MoGe2 输入，缩放 SHALL 基于 RGB 执行，alpha MUST 保持为独立信号。
|
||||
|
||||
#### Scenario: Same RGB with different alpha
|
||||
- **WHEN** 两张尺寸、RGB 相同的图仅 alpha 不同，并使用相同输入尺寸上限
|
||||
- **THEN** 它们生成的模型 RGB 输入相同，包括触发缩放的情况
|
||||
|
||||
#### Scenario: Transparent sky retains color context
|
||||
- **WHEN** Remove BG 输出保留天空 RGB 并将其 alpha 设为零
|
||||
- **THEN** MoGe2 输入保留天空 RGB，输出深度产物对应像素的 Alpha 为零
|
||||
|
||||
### Requirement: Alpha silhouette determines depth extension
|
||||
|
||||
系统 SHALL 根据原图 alpha 确定可见分量和轮廓修补范围，使用同一分量的可靠深度延伸轮廓。模型有效性 MUST 用于排除不可靠来源，修补范围 SHALL 独立于模型 mask 孔洞。延伸 SHALL 保持原始 alpha、模型有效性与未修补区域的深度。
|
||||
|
||||
#### Scenario: Repair the alpha edge
|
||||
- **WHEN** alpha 轮廓内侧保护带及轮廓外采样带存在不稳定深度，且分量内部存在可靠来源
|
||||
- **THEN** 系统使用该分量可靠深度修补边界，并保持目标像素的相机投影射线
|
||||
|
||||
#### Scenario: Internal mask hole
|
||||
- **WHEN** 一个低 mask 区域完全位于 alpha 轮廓保护带以外的内部
|
||||
- **THEN** 该区域不会仅因 mask 偏低而成为延伸目标，其模型有效性保持原值
|
||||
|
||||
#### Scenario: Fully opaque input
|
||||
- **WHEN** 输入 alpha 全为 1
|
||||
- **THEN** 系统保留原始深度场，包括低 mask 区域
|
||||
|
||||
#### Scenario: Component lacks reliable depth
|
||||
- **WHEN** 某个 alpha 分量没有可靠深度来源
|
||||
- **THEN** 该分量保留原始深度，不从其他分量借用深度
|
||||
|
||||
### Requirement: Depth artifact alpha combines coverage and model validity
|
||||
|
||||
`depth.exr` SHALL 在 RGB 保存相机空间 XYZ，在 Alpha 保存对齐预测尺寸的原图 alpha 与原始模型有效性的逐像素乘积。两个信号 MUST 保留连续值，补边 MUST 保持乘积所用的原始信号。
|
||||
|
||||
#### Scenario: Continuous values
|
||||
- **WHEN** 某像素原图 alpha 为 0.8，模型有效性为 0.75
|
||||
- **THEN** 导出的 Alpha 为 0.6，XYZ 保留该像素的深度处理结果
|
||||
|
||||
#### Scenario: Invisible or model-invalid pixel
|
||||
- **WHEN** 原图 alpha 或模型有效性任一为零
|
||||
- **THEN** EXR Alpha 为零，XYZ 仍保存可供采样的数值场
|
||||
|
||||
### Requirement: Geometry consumers use depth channels by purpose
|
||||
|
||||
Depth Plane SHALL 通过现有 Valid Only 和 Validity Threshold 按 EXR Alpha 剔除。Cutout SHALL 根据自身轮廓生成曲面并读取 XYZ，EXR Alpha 不得引入额外曲面剔除。
|
||||
|
||||
#### Scenario: Depth plane culling
|
||||
- **WHEN** Valid Only 开启且原图 alpha 或模型有效性使乘积低于当前阈值
|
||||
- **THEN** 该采样位置按现有节点的面域规则参与剔除
|
||||
|
||||
#### Scenario: Culling disabled
|
||||
- **WHEN** 用户关闭 Valid Only
|
||||
- **THEN** 完整细分网格继续进入深度投影与厚度处理
|
||||
|
||||
#### Scenario: Cutout keeps its contour
|
||||
- **WHEN** Cutout 轮廓内含低 EXR Alpha 区域
|
||||
- **THEN** 曲面拓扑保持由 Cutout 轮廓决定，深度采样使用导出的 XYZ
|
||||
@@ -0,0 +1,21 @@
|
||||
## 1. 模型输入
|
||||
|
||||
- [x] 1.1 将共享模型输入准备改为读取 RGB 后缩放，更新输入测试，验证相同 RGB、不同 alpha 在缩放和原尺寸情况下得到相同模型输入。
|
||||
|
||||
## 2. alpha 轮廓延伸
|
||||
|
||||
- [x] 2.1 将 alpha 轮廓与 mask 来源筛选分开，固定仅由 alpha 决定的修补范围；通过内部低 mask 孔洞及全不透明输入测试确认深度保持原值。
|
||||
- [x] 2.2 验证轮廓内侧保护带、外侧 4 像素延伸、局部平滑、分量隔离、无可靠来源回退和 XYZ 射线一致性，并确认 alpha 与 validity 未改写。
|
||||
|
||||
## 3. 深度产物与消费者
|
||||
|
||||
- [x] 3.1 为深度 EXR 写入添加必需的原图 alpha 参数并迁移全部调用；验证尺寸检查、零值、连续乘积和 XYZ 原值保存，确认 GeometryFrame.validity 仍为模型 mask。
|
||||
- [x] 3.2 更新 Artifact 集成测试，验证 alpha 对齐预测尺寸、Metadata 使用原始模型有效性与可见参考区域、Normal 使用原始预测。
|
||||
- [x] 3.3 按用户要求保留全部几何节点相关内容；验证 EXR 图像读取保留组合 Alpha 与 XYZ，检查现有校准读取，运行消费者回归测试，节点调整由另一 agent 负责。
|
||||
|
||||
## 4. 整体验证
|
||||
|
||||
- [x] 4.1 运行针对性测试后执行 `uv run pytest`，确认正常退出；检查最终差异与旧调用引用，保留工作区其他修改，仅报告本变更结果，不同步内部文档或构建资产及扩展包。
|
||||
|
||||
|
||||
验证记录：针对性测试 48 passed、2 subtests passed；全量测试 805 passed、2 xfailed，模型同步模块并行迁移导致 6 项初始化错误。迁移后单独重跑 tests/test_sync_models.py，6 passed，退出码 0。最终差异及写入调用检查通过；本变更未修改几何节点脚本、资产或节点测试。
|
||||
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-09-09
|
||||
68
openspec/changes/split-depth-and-relief-planes/design.md
Normal file
68
openspec/changes/split-depth-and-relief-planes/design.md
Normal file
@@ -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 检查已获用户授权。
|
||||
28
openspec/changes/split-depth-and-relief-planes/proposal.md
Normal file
28
openspec/changes/split-depth-and-relief-planes/proposal.md
Normal file
@@ -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 视觉验收单独安排。
|
||||
@@ -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** 节点连接、运算、默认值和域设置与参考图一致，有效与无效区域交界网格的保留结果符合该图规则
|
||||
@@ -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** 几何位置与未平滑结果相同
|
||||
39
openspec/changes/split-depth-and-relief-planes/tasks.md
Normal file
39
openspec/changes/split-depth-and-relief-planes/tasks.md
Normal file
@@ -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 同步节点资产文档中的两个资产接口与处理流程，检查当前源码和资产脚本中的旧模式引用。
|
||||
- [ ] 5.4 完成最终全量测试并确认正常退出。当前全量运行在 tests/test_node_arrangement.py 调用 node_arrangement._route_branch_exits 时发生 Blender access violation，独立复核仍复现。本次节点资产与转换相关 69 项测试通过，退出码 0。
|
||||
|
||||
## 6. 后续节点资产更新阶段
|
||||
|
||||
- [x] 6.1 已按用户授权构建 src/anyimage/assets/O_AnyImage.blend，Blender 4.5.10 的资产清单、接口、布局与几何验证通过。
|
||||
- [ ] 6.2 在 Blender 中按实际节点尺寸检查总览与局部布局，并以风景透明图检查剔除轮廓、厚度、细分调节和对象旋转后的法线表现。当前界面检查受阻：Computer Use 返回“Computer Use was not approved to use Blender”；待获得界面控制授权后完成。
|
||||
|
||||
|
||||
## 7. 复用 Cutout Smooth
|
||||
|
||||
- [x] 7.1 在 Depth Plane 最终几何上复用 expand_smooth，沿用 Smooth 与 Smooth Weight 的默认值、范围及接口归属。
|
||||
- [x] 7.2 覆盖零厚度和正厚度的平滑、关闭平滑、面连接与 UV 保持，并同步节点资产说明。
|
||||
- [ ] 7.3 节点资产已重建，Blender 资产验证和 69 项相关测试通过；全量测试受自动布局工具 access violation 阻塞，待该工具修复后复验。
|
||||
Reference in New Issue
Block a user