# Plane 转换

Plane 转换从当前 Image Empty 创建普通 Plane 或 Depth Plane：普通 Plane 同步完成，Depth Plane 先取得 MoGe-2 Z Depth 文件再回到 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"]
    Result --> Import["直接加载并 Pack Depth Image"]
    Import --> Depth["创建 Depth Plane Object"]
```

两条路径共用 Image Empty 的显示范围、颜色材质和基础 Plane。Depth Plane 多出一次 Server Job，并由节点根据相机元数据把 Z Depth 转换为局部位移。正式流程只使用 MoGe-2；DA3 只保留 Debug 入口。

## 节点说明

### 选择 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()` 创建对象。`object.py` 使用 `mesh_plane.py` 生成与 Image Empty 显示范围一致的基础四边形，并通过 `nodes.py` 加载 `O Mesh Plane` 修改器。

Movie 或 Sequence 的 Image User 设置会保留。转换完成后，新 Plane 替换源 Empty，并沿用原对象名称。

### 生成 Z Depth

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，写出 `z-depth.exr` 与 `depth.json`。EXR 的 RGB 重复保存相机 Z，Alpha 保存有效区；JSON 保存图片尺寸、相机内参与参考深度。AI 输入上限只影响模型分析图，颜色副本仍保留原始分辨率。

### 创建 Depth Plane

Job 返回后，`object.create_depth_plane_from_result()` 直接加载并 Pack `z-depth.exr`，数据块仍由 `depth_data_name()` 命名。`depth.json` 用于计算统一尺度，`O Image Depth Plane` 根据参考深度、统一尺度和用户的 Depth Amount 把相机 Z 转换为局部位移。

随后 `object.py` 创建颜色材质和基础四边形，`nodes.py` 加载 `O Image Depth Plane` 修改器。`conversion.py` 最后用一个 Undo 步骤替换源 Empty。