Initial public release

openspec/changes/archive/2026-09-17-add-projected-depth-plane/.openspec.yaml

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

openspec/changes/archive/2026-09-17-add-projected-depth-plane/design.md

@@ -0,0 +1,78 @@
+## Context
+
+普通 Plane 的 `create_mesh_plane_mesh()` 创建中心四边形和完整 UV，`O Mesh Plane` 负责矩形细分。现有 Depth Plane 使用固定底面的浮雕置换；Depth Cutout 的曲面分支使用相机 XYZ 投影。整图 Job 已通过通用 Artifact 层执行一次 MoGe-2 推理，该层支持 VECTOR Depth。
+
+Cutout 的双击入口集中在 `SelectCutoutSelection.invoke()`、`full_image` Property 和 WorkspaceTool keymap。工作区中的 Cutout Shape 重组仍在进行，本提案以当前文件中的实际实现为基线。
+
+## Goals / Non-Goals
+
+本次目标是建立独立的整图 Depth Surface 转换，并让 Cutout 通过套索提交区域。Depth Surface 的用户控制固定为 Subdivide、Thickness、Depth Scale、Reference Depth、Normal Smooth。
+
+## Decisions
+
+### 入口与命名
+
+采用 `ConvertToDepthSurface`、`anyimage.convert_to_depth_surface`、界面文字 **Convert to Depth Surface** 和资产名 `O Image Depth Surface`，表达输出是相机投影曲面。菜单中的顺序为 Plane、Depth Plane、Depth Surface，现有 Depth Plane 继续承担固定底面浮雕。
+
+Cutout 直接使用共享拖动 keymap，删除双击整图绑定、`full_image` 声明和完整矩形 Selection 构造代码；`invoke()` 仅记录 Pie Event 后启动共享手势。清理因此失去用途的 import 和测试夹具。
+
+### 整图生成主链
+
+```mermaid
+flowchart TD
+    Image[Image Empty] --> Convert[Convert to Depth Surface]
+    Convert --> Check[静态图片与 AI 环境检查]
+    Check --> Job[整图 Depth Job：VECTOR 模式]
+    Job --> Prediction[一次 MoGe-2 推理]
+    Prediction --> Files[完整 Color、vector-depth.exr、depth.json、tangent-normal.png]
+    Files --> Load[主线程加载并 Pack 深度与法线]
+    Load --> Mesh[共用矩形 Mesh、中心矩阵与材质]
+    Mesh --> Modifier[加载 O Image Depth Surface]
+    Modifier --> Result[替换源 Empty 并创建一个 Undo 步骤]
+```
+
+在现有整图 Job 上增加明确的深度产物选择，Depth Plane 使用 Z，Depth Surface 使用 VECTOR；两者均从一次预测生成 Tangent Normal。Blender 侧将转换类型随请求保存至响应阶段，据此选择节点组和结果标识。复用 `common` 的图片加载、深度尺度、材质与对象替换函数；Server 只引用自身目录内的共享 Artifact 层。
+
+### 基础网格与节点接口
+
+Depth Surface 使用 `create_mesh_plane_mesh()` 和 `build_mesh_plane_matrix()`，保持整张图片的矩形边界、中心原点、UV 和材质槽。节点内部调用 `O Mesh Plane`，以 Thickness 0 生成基础曲面；同一 Subdivide 下，它与普通 Plane 的零厚度网格具有相同顶点、面连接与 UV。Alpha 参与材质显示，模型 Validity 用于数据有效性处理，几何始终覆盖完整矩形。
+
+| 输入 | 默认值 | 语义 |
+| --- | --- | --- |
+| Subdivide | 6，范围 0–10 | 沿用 O Mesh Plane 的细分 |
+| Thickness | 0，最小 0 | 均匀曲面壳厚度，DISTANCE |
+| Depth Scale | 1，最小 0 | 平面到相机曲面的缩放，可大于 1 |
+| Normal Smooth | 50，范围 0–50 | 厚度方向的法线平滑次数，放在 Options |
+| Reference Depth | Metadata reference_depth × Uniform Scale | 局部深度基准，DISTANCE，放在 Options |
+
+Geometry 为结构输入；Depth Image 与 Uniform Scale 为隐藏数据输入。所有修改器输入使用 SINGLE。
+
+### 投影与厚度
+
+沿用 Depth Cutout 的 VECTOR Depth 坐标约定：将采样相机 XYZ 乘以 Uniform Scale，翻转 Y 得到局部 XY，局部 Z 为 `(Reference Depth − scaled_camera_z) × Depth Scale`。局部 XY 从基础矩形位置按 Depth Scale 插值到缩放后的相机 XY；0 为原平面，1 为完整投影，大于 1 为外推。Reference Depth 使用与采样相同的局部单位。
+
+```mermaid
+flowchart TD
+    Base[O Mesh Plane 零厚度矩形细分] --> Projection[相机 XY 插值与相对 Z 深度]
+    Texture[VECTOR Depth × Uniform Scale] --> Projection
+    Projection --> Thickness{Thickness}
+    Thickness -- 0 --> Surface[单层曲面]
+    Thickness -- 大于 0 --> Shell[沿平滑法线向内生成均匀壳并连接外边界]
+    Surface --> Output[保留 UV 与材质，清理临时属性]
+    Shell --> Output
+```
+
+提取现有曲面分支中可复用的投影、均匀厚度节点构建函数，按业务职责集中在共用构建模块；新组只组合自身需要的步骤。零厚度保持单层矩形拓扑，正厚度保留投影正面、沿内侧扩展背面并连接四周。厚度采用正面 POINT 法线，按 Normal Smooth 迭代次数进行邻域平滑后归一化，使对应正背面顶点之间的距离等于 Thickness。
+
+### 验证边界
+
+以合成相机 XYZ 纹理验证投影和坐标方向，用相同 Subdivide 的普通 Plane 对照基础拓扑与 UV；使用非方图、偏移 Image Empty、旋转缩放矩阵验证定位。检查五项可见参数、隐藏数据输入、SINGLE、材质槽和临时属性清理。
+
+节点布局按实际 Blender 绘制尺寸检查总览和局部，几何主链连续、计算支线就近接入。实现阶段按项目总则只运行测试；资产构建、资产视觉验收和节点资产文档同步作为后续发布准备，当前提案不执行构建。
+
+## Risks / Trade-offs
+
+- 相机纹理的 Y 方向或中心对齐错误会使结果镜像、偏移 → 使用带非中心主点的合成相机数据验证，并保持与现有 Depth Cutout 相同的投影公式。
+- 深度不连续处的矩形面会被拉伸 → 将连续矩形拓扑作为明确输出约定，用阶跃深度验证连接关系稳定。
+- 新增类型和共享 Job 分支可能影响现有转换 → 检查注册与逆序注销、Z/VECTOR 产物选择、单次推理及 Undo 回归。
+- 工作区同时调整 Cutout 节点 → 实施前核对当前构建函数和 Shape 设置，在现有修改基础上提取共用步骤。

openspec/changes/archive/2026-09-17-add-projected-depth-plane/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+整图相机投影曲面需要与普通 Plane 一样稳定的矩形基础网格，以及少量直接的深度控制。将它作为独立转换入口，也让 Cutout 的交互集中在用户圈选区域。
+
+## What Changes
+
+- **BREAKING**：完全删除 Cutout 双击整图生成入口，包括快捷键、`full_image` 属性和整图 Selection 构造分支。
+- 新增 **Convert to Depth Surface**，与 Convert to Plane、Convert to Depth Plane 并列，用完整图片生成相机投影深度曲面。
+- 新增 `O Image Depth Surface`：基础网格复用普通 Plane 的矩形、UV、中心原点和 `O Mesh Plane` 细分，只公开 `Subdivide`、`Thickness`、`Depth Scale`、`Reference Depth` 四项用户参数。
+- 相机投影沿用 Depth Cutout 的坐标与深度缩放语义；厚度采用均匀曲面壳，默认零厚度。
+- 整图转换复用现有 MoGe-2 单次推理、材质与对象替换流程。
+
+## Capabilities
+
+### New Capabilities
+
+- `projected-depth-surface`: 整图 Depth Surface 转换、矩形基础网格、相机投影和精简节点接口。
+- `cutout-lasso-entry`: Cutout 通过有效套索进入 Shape 选择，彻底移除双击整图入口。
+
+### Modified Capabilities
+
+无。当前 `openspec/specs/` 尚无已归档规范；本次独立规定新增及调整后的行为。
+
+## Impact
+
+- `operators/cutout_tool/main.py` 及其交互测试。
+- `operators/convert_to_plane/`、`menu.py`、`__init__.py` 的转换入口、结果创建与类型注册。
+- `common/depth.py` 等共用深度数据处理；按需扩展整图 Job 的产物选择，保持后端模块边界。
+- `tools/node_assets/` 的构建和验证、新节点组及节点测试；实施阶段按项目约束执行测试，节点资产构建和产物更新单独安排。
+- 无新增第三方依赖；实现以当前工作区为基线，衔接正在进行的 Cutout Shape 调整。

openspec/changes/archive/2026-09-17-add-projected-depth-plane/specs/cutout-lasso-entry/spec.md

@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: Cutout starts shape generation from a lasso
+Cutout SHALL 在用户提交有效套索后打开 Shape Pie Menu，并将圈选路径传给 Shape 生成入口。
+
+#### Scenario: Submit a lasso
+- **WHEN** 用户在 active Image Empty 上完成有效 Cutout 套索
+- **THEN** 系统打开当前可用 Shape 菜单并传递该套索路径
+
+### Requirement: Full-image double-click entry is removed
+系统 MUST 删除 Cutout 的双击整图 keymap、`full_image` Property、整图 Selection 构造分支及专属调用代码。双击 MUST NOT 打开整图 Shape 菜单或提交整图生成任务。
+
+#### Scenario: Double-click an image
+- **WHEN** Cutout 已激活，用户在 Image Empty 上双击且未形成有效套索
+- **THEN** 不打开 Shape 菜单、不创建对象、不提交生成 Job
+
+#### Scenario: Double-click viewport space
+- **WHEN** active Image Empty 存在，用户在图片外空白区域双击
+- **THEN** 不启动整图 Cutout，选择处理沿用共享图片手势规则
+
+#### Scenario: Inspect registration
+- **WHEN** 检查 Cutout 的 Operator Property 和 WorkspaceTool keymap
+- **THEN** 不存在 `full_image` 或用于整图生成的 `DOUBLE_CLICK` 绑定

openspec/changes/archive/2026-09-17-add-projected-depth-plane/specs/projected-depth-surface/spec.md

@@ -0,0 +1,85 @@
+## ADDED Requirements
+
+### Requirement: Full-image depth surface has a conversion entry
+系统 SHALL 提供 `anyimage.convert_to_depth_surface`，界面显示 Convert to Depth Surface，与 Plane、Depth Plane 并列；该入口 SHALL 从当前静态 Image Empty 创建完整图片的相机投影曲面。
+
+#### Scenario: Convert a still image
+- **WHEN** 当前 Image Empty 是静态图片且 AI 环境可用
+- **THEN** 执行一次完整图片转换，成功后结果沿用源对象名称并替换源 Empty
+- **AND** 一次 Undo 恢复转换前状态
+
+#### Scenario: Reject unsupported media
+- **WHEN** 输入为多帧 Movie 或 Sequence
+- **THEN** 提示仅支持静态图片，不提交推理任务
+
+#### Scenario: AI setup is required
+- **WHEN** AI 环境未就绪
+- **THEN** 沿用现有 AI 设置流程，源 Empty 保持可用
+
+### Requirement: Base geometry matches Plane conversion
+Depth Surface SHALL 使用普通 Convert to Plane 的基础 Mesh 创建、中心矩阵、UV 和 O Mesh Plane 细分。相同 Subdivide 下投影前零厚度几何 MUST 与普通 Plane 的零厚度几何一致。整图矩形拓扑 SHALL 覆盖透明区域及深度跳变区域。
+
+#### Scenario: Compare planar meshes
+- **WHEN** 对同一图片以相同 Subdivide 创建普通 Plane 和 Thickness 0、Depth Scale 0 的 Depth Surface
+- **THEN** 两者顶点位置、面连接、UV 和材质索引一致
+
+#### Scenario: Preserve placement
+- **WHEN** 源 Image Empty 具有非中心显示偏移以及平移、旋转、缩放
+- **THEN** Depth Scale 0、Thickness 0 的结果四角与源显示矩形的世界空间四角一致
+- **AND** 对象原点位于显示矩形中心
+
+#### Scenario: Preserve rectangular coverage
+- **WHEN** 图片包含透明孔洞或纹理深度跳变
+- **THEN** 基础网格仍为完整矩形细分，Alpha 由材质表达
+
+### Requirement: Surface controls include normal smoothing
+`O Image Depth Surface` SHALL 只公开 Subdivide、Thickness、Depth Scale、Reference Depth 以及 Normal Smooth 五项用户控制。默认值 SHALL 分别为 6、0、1 和 Metadata reference_depth 乘以 Uniform Scale。Geometry SHALL 为结构输入，Depth Image 与 Uniform Scale SHALL 为隐藏数据输入。输入 MUST 使用 SINGLE；Thickness、Reference Depth MUST 使用 DISTANCE。
+
+#### Scenario: Inspect a new modifier
+- **WHEN** 创建 Depth Surface 修改器
+- **THEN** 用户看到规定的五项控制，Reference Depth 与 Normal Smooth 位于 Options；Normal Smooth 默认 50，范围 0–50
+- **AND** 不出现 Cutout 的 Mode、Split、Balloon、Inflation、轮廓或轴向控制
+
+### Requirement: Geometry follows camera projection
+Depth Surface SHALL 按现有 Depth Cutout 的相机 XYZ 坐标约定投影。采样 XYZ 乘以 Uniform Scale 后，XY SHALL 以 Depth Scale 从基础平面插值至相机 X、负相机 Y；Z SHALL 为 `(Reference Depth − scaled_camera_z) × Depth Scale`。
+
+#### Scenario: Full projection
+- **WHEN** Thickness 为 0、Depth Scale 为 1，输入合成相机 XYZ 纹理
+- **THEN** 每个顶点的位置符合相机投影公式，包括 Y 方向与深度基准
+
+#### Scenario: Adjust depth strength
+- **WHEN** Depth Scale 分别为 0、0.5、1 和大于 1 的值
+- **THEN** XY 与 Z 按同一缩放语义连续变化，0 恢复基础平面，大于 1 正常外推
+
+#### Scenario: Adjust reference depth
+- **WHEN** Reference Depth 增加局部距离 d，Depth Scale 为 s
+- **THEN** 曲面 Z 增加 d × s，投影 XY 保持不变
+
+### Requirement: Thickness forms a uniform surface shell
+Thickness 为 0 时系统 SHALL 输出单层曲面；Thickness 大于 0 时 SHALL 保留投影正面，按正面 POINT 法线按 Normal Smooth 进行邻域平滑并归一化后的方向向内生成背面并连接矩形边界。
+
+#### Scenario: Zero thickness
+- **WHEN** Thickness 为 0
+- **THEN** 仅存在一层曲面，无重复背面或退化侧壁
+
+#### Scenario: Positive thickness
+- **WHEN** 对平坦深度输入设置正 Thickness
+- **THEN** 对应正背面顶点之间的距离等于 Thickness，边界闭合且法线朝向一致
+
+### Requirement: One prediction produces complete image artifacts
+整图 Depth Surface SHALL 通过共用 Artifact 层执行一次 MoGe-2 推理，生成 VECTOR Depth、Metadata 与 Tangent Normal，并保留完整 Color。Blender SHALL 在主线程加载、Pack 并设置图片色彩空间，将 Normal 用于材质，将 VECTOR Depth 用于几何。
+
+#### Scenario: Complete a generation job
+- **WHEN** 整图 Depth Surface Job 成功
+- **THEN** 只执行一次推理，并返回 `vector_depth`、`depth_metadata`、`tangent_normal` 及完整颜色产物
+
+#### Scenario: Preserve existing depth plane generation
+- **WHEN** 用户执行现有 Convert to Depth Plane
+- **THEN** 继续生成 Z Depth 与 Tangent Normal，并创建固定底面浮雕
+
+### Requirement: Node assets preserve geometry data
+新节点组 SHALL 从 `assets/O_AnyImage.blend` 按名称加载。节点求值 SHALL 保留 UV 与第 0 个材质槽，并清理自身临时属性；构建验证 SHALL 检查接口、实际几何与 Blender 中的节点布局。
+
+#### Scenario: Evaluate the asset
+- **WHEN** 加载并求值 `O Image Depth Surface`
+- **THEN** 结果保留 UV、用户属性和材质，不残留自身 `o_depth_*` 临时属性

openspec/changes/archive/2026-09-17-add-projected-depth-plane/tasks.md

@@ -0,0 +1,31 @@
+## 1. 删除 Cutout 双击整图入口
+
+- [x] 1.1 删除 Cutout 的 DOUBLE_CLICK 整图绑定、full_image Property、整图 Selection 分支及失去用途的 import，保留共享套索交互。
+- [x] 1.2 调整交互和注册测试，验证图片内外双击均不打开 Shape 菜单或提交任务，有效套索继续生成 Shape。
+
+## 2. 新增整图 Depth Surface 转换
+
+- [x] 2.1 增加 ConvertToDepthSurface、菜单入口和正逆序注册，验证静态图片、AI 环境及忙碌状态检查。
+- [x] 2.2 扩展共用整图 Job 的 Z/VECTOR 产物选择及 Blender 响应分派，保持普通 Depth Plane 的 Z 路径；验证 VECTOR Depth 和 Tangent Normal 来自一次推理。
+- [x] 2.3 复用 common 的图片、深度、材质及对象收尾函数创建 Depth Surface；共用 Plane 的基础 Mesh 和中心矩阵，初始化四项参数及隐藏深度数据。
+- [x] 2.4 验证完整颜色、材质槽、深度与法线 Pack、源对象替换、失败清理和单步 Undo。
+
+## 3. 构建定义与几何验证
+
+- [x] 3.1 按业务职责提取共用相机投影和均匀厚度构建步骤，新增 O Image Depth Surface 构建定义，并接入节点组构建和验证索引。
+- [x] 3.2 以 O Mesh Plane 的零厚度输出生成完整矩形基础网格，设置 Subdivide、Thickness、Depth Scale、Reference Depth 以及隐藏数据接口，检查 SINGLE 与 socket subtype。
+- [x] 3.3 增加合成纹理几何测试：同级 Plane 拓扑与 UV 对照、Depth Scale 0/0.5/1/>1、Reference Depth、相机 Y 方向和非中心主点。
+- [x] 3.4 增加零厚度单层、正厚度闭合、透明区域完整矩形、深度跳变连接、材质和临时属性清理验证。
+- [x] 3.5 编排新节点组布局与验证入口，覆盖未用输出隐藏、主链及支线间距；记录发布准备时所需的实际绘制尺寸视觉验收项目。
+
+## 4. 回归与交付检查
+
+- [x] 4.1 运行相关转换、交互、注册、Server Job 和节点构建定义测试，修复回归；检查现有 Depth Plane 和圈选 Cutout 的行为。
+- [x] 4.2 运行 uv run pytest，记录测试结果及需要 Blender 或已构建新资产才能完成的验收项。按项目总则，代码实施只运行测试，资产构建、二进制产物和节点资产文档同步留给发布准备。
+
+
+发布准备验收：构建节点资产后，在 Blender 节点编辑器按实际绘制尺寸检查新组总览、投影支线、厚度分支及旁路；检查修改器四项参数的实际显示，并对已发布资产运行几何验证。本次不生成资产或文档产物。
+
+测试记录：全量测试两次均为 723 passed、2 xfailed、62 subtests passed；显式调用 pytest.main 返回 0。两次完整进程均在 pytest 返回后以退出码 1 结束，退出阶段异常尚未定位。新曲面几何、接口、对象定位及失败清理测试全部通过。OpenSpec strict 校验通过。
+
+资产更新记录：已按用户要求运行 build_node --skip-tests，Blender 4.5.10 LTS 构建及三项资产验证均成功。更新后资产与转换回归 53 passed；构建定义和磁盘发布资产使用相同几何用例验证，31 passed，命令退出码均为 0。已同步节点资产说明。Computer Use 应用授权超时，实际节点编辑器视觉验收仍待完成。