# Plane 转换

Plane 转换从当前 Image Empty 创建普通 Plane 或 Depth Plane：普通 Plane 同步完成，Depth Plane 先取得 MoGe-2 Z Depth 与 Tangent Normal 文件，再回到 Blender 创建对象。

## 执行过程

```mermaid
flowchart TD
    Empty["Image Empty"] --> Kind{"转换类型"}
    Kind -- "Plane" --> Color["复制 Color Image"]
    Color --> Plane["创建 Plane Object"]
    Kind -- "Depth Plane" --> Job["generate-depth-plane-geometry"]
    Job --> Result["Color Image + z-depth.exr + depth.json + tangent-normal.png"]
    Result --> Import["加载并 Pack Depth / Normal Image"]
    Import --> Depth["创建 Depth Plane Object"]
```

两条路径共用 Image Empty 的显示范围、颜色材质和中心原点 Plane。Depth Plane 通过一次 MoGe-2 Server Job 同时生成 Z Depth 与 Tangent Normal；节点根据相机元数据生成单面地形体块，Normal Map 则进入材质着色。

## 节点说明

### 选择 Plane 或 Depth Plane

`operators/convert_to_plane/__init__.py` 导出注册类型，实际入口在 `conversion.py`。`ConvertToPlane` 进入本地路径，`ConvertToDepthPlane` 检查静态图片和 AI 环境后启动 `GenerateDepthPlane`。

### 创建普通 Plane

`conversion.py` 先调用 `object.create_color_image()` 复制当前 Image，再由 `object.create_plane_object()` 创建对象。`mesh_plane.py` 把基础四边形顶点放在局部原点两侧，并把 Image Empty 显示范围中心补入对象矩阵，因此世界空间位置不变而对象原点位于面中心。随后从节点资产加载 `O Mesh Plane` 修改器。

材质存入 Mesh 第 `0` 个材质槽。`O Mesh Plane` 将带匿名标记的输入几何与生成几何临时合并，统一设置材质索引 `0` 后再删除输入几何，从而让纯生成面保留原 Mesh 的材质集合。Movie 或 Sequence 的 Image User 设置会保留。转换完成后，新 Plane 替换源 Empty，并沿用原对象名称。

### 生成 Depth 与 Normal

Depth 路径中的 `GenerateDepthPlane` 位于 `conversion.py`。它从 Preferences 读取 **Depth & Normal Model**、**MoGe Resolution Level** 和 **Maximum AI Input Size**，提交 `generate-depth-plane-geometry` Job。

`server/jobs/depth_plane.py` 编排完整图片任务，`server/geometry/prediction_artifacts.py` 把图片合成到黑底后调用一次 MoGe-2，并从同一个 `GeometryFrame` 写出 `z-depth.exr`、`depth.json` 与 `tangent-normal.png`。该 Artifact 生成层也由 Cutout Job 复用；两种顶层 Job 继续各自负责完整图片与 Selection 的输入、结果协议。

EXR 的 RGB 重复保存完整相机 Z，Alpha 保存模型 Validity；JSON 保存图片尺寸、相机内参与有效区域的参考深度。Tangent Normal 使用 PNG 保存，只参与材质着色。AI 输入上限只影响模型分析图，颜色副本仍保留原始分辨率。

### 创建 Depth Plane

Job 返回后，`object.create_depth_plane_from_result()` 加载并 Pack `z-depth.exr` 与 `tangent-normal.png`。Depth 数据块仍由 `depth_data_name()` 命名；Normal 图片设为 Non-Color，并以 Tangent Space 接入 `O Image Layer`。结果材质与 Cutout 一样使用 Principled IOR `1.2`，并由 `O Image Layer` Color 直接驱动 IOR Level。`depth.json` 的参考深度乘以统一尺度后初始化 **Reference Depth**，使它和采样深度处于同一局部距离单位。

`O Image Depth Plane` 把 `O Mesh Plane` 的固定底面放在原图片平面，`Thickness` 只沿正法线移动可变面与中间环，再按各层位置应用深度位移：

```mermaid
flowchart TD
    Depth["Z Depth × Uniform Scale"] --> Offset["(Reference Depth - Depth) × Depth Scale"]
    Offset --> Clamp["负向位移限制在固定底面之前"]
    Block["O Mesh Plane 厚度体块"] --> Weight["固定底面 0 → 中间环 → 可变面 1"]
    Clamp --> Apply["位移 × 层权重"]
    Weight --> Apply
    Apply --> Terrain["单面地形体块"]
```

固定底面位于原图片平面，未置换可变面位于正法线方向的 **Thickness** 距离处。**Depth Scale** 为 `0` 时成品厚度等于 **Thickness**；正向位移可以超出基础厚度，负向位移不会穿过固定底面。`conversion.py` 最后用一个 Undo 步骤替换源 Empty。