feat(node_assets): add image plane geometry nodes and validation scripts
- Implemented `image_plane.py` to build the Image Plane Geometry Nodes group with customizable parameters for geometry, subdivide, and thickness. - Created `image_plane_validation.py` to validate the functionality of the image plane, ensuring correct geometry generation and material assignment. - Developed `material_layers.py` to construct shader node groups for image materials, including depth and normal handling. - Authored `plane_layouts.py` to define node arrangements for image geometry assets. - Introduced `shadeless.py` to create a shadeless shader node group that displays color without scene lighting while preserving shadows and reflections.
This commit is contained in:
@@ -1,56 +1,23 @@
|
||||
# Plane 转换
|
||||
|
||||
Plane 转换从当前 Image Empty 创建普通 Plane 或 Depth Plane：普通 Plane 同步完成，Depth Plane 先取得 MoGe-2 Z Depth 与 Tangent Normal 文件，再回到 Blender 创建对象。
|
||||
|
||||
## 执行过程
|
||||
`operators/convert_to_plane/conversion.py` 提供 `ConvertToPlane`、`ConvertToDepthPlane` 与 `GenerateDepthPlane`。对象和材质导入位于 `object.py`，基础矩形网格位于 `image_plane.py`。
|
||||
|
||||
```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"]
|
||||
A[Image Empty] --> B{转换类型}
|
||||
B -- Plane --> C[复制 Color 与动画设置]
|
||||
C --> D[中心原点四边形与 O Image Plane]
|
||||
B -- Depth Plane --> E[检查静态图与 AI 就绪状态]
|
||||
E --> F[generate-depth-plane-geometry]
|
||||
F --> G[Color、depth.exr、depth.json、Tangent Normal]
|
||||
G --> H[加载并 Pack 数据]
|
||||
H --> I[O Image Depth Plane 与材质]
|
||||
D --> J[替换源 Empty 并保留世界位置]
|
||||
I --> J
|
||||
```
|
||||
|
||||
两条路径共用 Image Empty 的显示范围、颜色材质和中心原点 Plane。Depth Plane 通过一次 MoGe-2 Server Job 同时生成 Z Depth 与 Tangent Normal；节点根据相机元数据生成单面地形体块，Normal Map 则进入材质着色。
|
||||
普通 Plane 支持图片、视频和序列，材质保留 Image User 帧设置。基础四边形以局部中心为原点，对象矩阵补偿原 Image Empty 显示范围；节点组生成细分与厚度，材质位于 Mesh 第 0 个槽。
|
||||
|
||||
## 节点说明
|
||||
Depth Plane 从 Preferences 取得 MoGe-2 模型、分辨率级别与 AI 输入上限，一次推理生成相机 XYZ 深度和切线法线。`create_depth_plane_from_result()` 创建颜色材质与深度修改器，并在失败时清理未使用的数据块。
|
||||
|
||||
### 选择 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。
|
||||
`O Image Depth Plane` 提供默认 Relief 和 Camera：Relief 读取深度 Z 形成固定底面的地形；Camera 使用相机 XYZ 投影并沿平滑法线形成壳。两个模式各自保存 Thickness。完整接口见[节点资产](../node-assets.md)，文件协议见[Job 产物](../outputs.md)。
|
||||
|
||||
Reference in New Issue
Block a user