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.

openspec/changes/separate-depth-alpha-and-model-input/.openspec.yaml

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

openspec/changes/separate-depth-alpha-and-model-input/design.md

@@ -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 获得新产物。仅回退本变更引入的修改即可恢复旧行为。

openspec/changes/separate-depth-alpha-and-model-input/proposal.md

@@ -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 语义。实现只运行测试，不同步内部文档或构建节点资产、扩展包；无新增依赖。

openspec/changes/separate-depth-alpha-and-model-input/specs/depth-alpha-semantics/spec.md

@@ -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

openspec/changes/separate-depth-alpha-and-model-input/tasks.md

@@ -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。最终差异及写入调用检查通过；本变更未修改几何节点脚本、资产或节点测试。