AnyImage/openspec/specs/cutout-axis-convention/spec.md

cutout-axis-convention Specification

Purpose

TBD - created by archiving change standardize-cutout-z-axis. Update Purpose after archive.

Requirements

Requirement: Cutout base mesh matches the source image plane

系统 SHALL 直接在源 Image Empty 的局部 XY 平面创建 Cutout BaseShape，基础顶点 MUST 使用 z = 0，逆时针正面 MUST 朝局部 +Z，且对象放置 MUST 保持裁切区域的世界空间位置。

Scenario: Inspect a Cutout before Geometry Nodes evaluation

• WHEN 系统已从源图片裁切区域创建 Cutout Mesh，但尚未求值或复用 O Image Cutout Modifier
• THEN Mesh 位于对象局部 XY 平面，正面朝向与源 Image Empty 一致，且 X/Y 范围对应原裁切区域

Scenario: Evaluate an undeformed Surface

• WHEN Surface Cutout 以零厚度和零平滑求值
• THEN 求值前后的平面内坐标、正面朝向和世界空间位置保持一致，不执行轴交换或补偿旋转

Requirement: Cutout Shape nodes use the local Z axis

O Image Surface、O Image Balloon、O Image Depth Balloon 与 O Image Depth Surface SHALL 接收局部 XY 平面几何，并统一使用局部 -Z 表示从图片平面向内的方向。外层 O Image Cutout 的默认 -Z 分支 MUST 直通该原生结果。平面内 X/Y 坐标 MUST 不因 Shape 求值而互换。

Scenario: Reuse a Shape group with XY geometry

• WHEN 任一 Cutout Shape 节点组直接接收位于 XY 平面的输入 Mesh
• THEN 节点组沿 Z 轴生成 Shape，并保持输入几何的 X/Y 方向

Scenario: Build Surface or Balloon thickness

• WHEN Surface 或 Balloon 使用正 Thickness 求值
• THEN 厚度和 Balloon 高度沿局部 Z 轴展开，图片内部一侧位于负 Z 方向

Scenario: Apply depth deformation

• WHEN Depth Balloon 或 Depth Surface 使用非零 Depth Scale 求值
• THEN 深度位置在统一的 XY / Z 对象空间中计算，不依赖 X 轴中间坐标系或最终轴变换

Requirement: Cutout exposes selectable output axes

系统 SHALL 保留 Inward Axis Scene Property、Operator 参数和 O Image Cutout 节点接口。-Z MUST 为默认值并直接使用原生 XY / Z Shape 结果；选择 +X 时，外层节点组 MUST 将 Z 轴结果转换为 +X 内向对象空间，对象矩阵 MUST 执行配对补偿以保持相同世界空间形状。

Scenario: Create a Cutout from the tool

• WHEN 用户打开 Cutout 工具设置并选择任一 Shape
• THEN 工具显示并传递 Inward Axis，默认 -Z 创建结果直接沿用源 Image Empty 的局部轴

Scenario: Select the positive X output

• WHEN 用户把 Inward Axis 设为 +X
• THEN O Image Cutout 将原生 Z 轴 Shape 转换为 +X 内向的局部几何，对象矩阵同步补偿，世界空间位置和外观与默认结果一致

Scenario: Reuse a Shape subgroup directly

• WHEN 调用方绕过外层 O Image Cutout 并直接复用任一 Shape 子节点组
• THEN 子节点组始终使用原生 XY / Z 坐标，不公开或模拟旧 X 轴内部约定

Requirement: Depth Surface normals match the Z-axis object space

Depth Surface 的 Object Space Normal Artifact SHALL 编码原生 Z 轴 Cutout 对象空间；不可见区域 MUST 使用局部 +Z 中性法线。默认 -Z 输出 MUST 原样使用该图片；选择 +X 输出时，Blender MUST 将其转换到配对的 +X 对象空间。

Scenario: Encode a known object-space normal

• WHEN Server 为 Depth Surface 编码已知的相机空间法线
• THEN 输出通道直接对应最终 XY / Z Cutout 对象空间，且无需 Blender 后处理即可作为 Object Space Normal 使用

Scenario: Load a Depth Surface normal image

• WHEN Blender 收到 object-normal.png 并以默认 -Z 创建 Depth Surface 材质
• THEN 图片像素保持 Artifact 原值并以 Object Space 连接到材质

Scenario: Load a positive X Depth Surface normal image

• WHEN Blender 收到 object-normal.png 并以 +X 创建 Depth Surface 材质
• THEN 图片通道按 Z 到 X 的配对轴变换转换一次，再以 Object Space 连接到材质

Scenario: Fill an invisible normal region

• WHEN Object Space Normal 的像素不在可见内容区域
• THEN 该像素编码局部 +Z，不会在正面产生虚假的侧向法线