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,51 +1,43 @@
|
||||
# Job 产物
|
||||
|
||||
Server 在 Job 目录写入图片、JSON 或 Debug NPZ；Blender 根据 Job 返回值读取文件并创建 Image、Mesh、Material 与 Object。
|
||||
Server 把结果写入 Job 目录，返回以相对文件名为值的字典。Blender 主线程通过 JobResult 读取文件，再创建或更新 Image、Mesh、Material 和 Object。
|
||||
|
||||
## 正式 Job
|
||||
| Job | 文件 | 消费方 |
|
||||
| --- | --- | --- |
|
||||
| `remove-background` | `image.0001.png` 起 | Image Empty 替换 |
|
||||
| `upscale-image` | `upscale.0001.png` 起 | 2× Image Empty 替换 |
|
||||
| `generate-depth-plane-geometry` | `image.0001.*`、`depth.exr`、`depth.json`、`tangent-normal.png` | Plane 对象与材质 |
|
||||
| `generate-cutout-artifacts` | 按请求提供深度、元数据和法线 | Cutout 对象与材质 |
|
||||
|
||||
| Job | 主要文件 | Blender 消费方式 |
|
||||
| | | |
|
||||
| `remove-background` | `image.0001.png` 起 | 替换 Image Empty 的颜色数据 |
|
||||
| `upscale-image` | `upscale.0001.png` 起 | 替换或新建高清颜色数据 |
|
||||
| `generate-depth-plane-geometry` | `image.0001.*`、`z-depth.exr`、`depth.json` | 创建 Depth Plane |
|
||||
| `generate-cutout-artifacts` | 可选 Depth 与 Normal 文件 | 创建 Cutout Shape 与材质 |
|
||||
## 深度与法线协议
|
||||
|
||||
Depth Job 保存可由 Blender 直接加载的模型空间 EXR；Blender 主线程负责轮廓提取、三角化、Depth 标定和数据创建。
|
||||
| 返回字段 | 文件 | 内容 |
|
||||
| --- | --- | --- |
|
||||
| `depth` | `depth.exr` | float32 RGB 保存相机空间 XYZ，Alpha 保存 Validity |
|
||||
| `depth_metadata` | `depth.json` | `image_size`、3×3 `intrinsics`、`reference_depth` |
|
||||
| `tangent_normal` | `tangent-normal.png` | 切线空间法线 |
|
||||
| `object_normal` | `object-normal.png` | Cutout 原生 XY / Z 坐标的对象空间法线 |
|
||||
|
||||
## Depth 与 Normal 文件
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[矩形源 RGBA] --> B[限尺寸并合成黑底模型输入]
|
||||
B --> C[MoGe-2 GeometryFrame]
|
||||
C --> D[原预测生成 Normal]
|
||||
C --> E{Cutout 深度？}
|
||||
E -- 是 --> F[按源 Alpha 延展轮廓深度]
|
||||
E -- 否 --> G[完整相机 Points]
|
||||
F --> G
|
||||
G --> H[depth.exr 与 depth.json]
|
||||
D --> I[Blender 加载并 Pack]
|
||||
H --> I
|
||||
```
|
||||
|
||||
MoGe-2 的原始结果由模型适配器转换为单帧 `GeometryFrame`。它包含 Depth、Validity、Intrinsics，以及可选的 Normal 和 Points；`geometry/prediction_artifacts.py` 把同一 Frame 交给各 Writer，并按请求写出以下文件：
|
||||
`depth_texture.py` 保存完整有限 Points；模型 Mask 转为 `0/1` Validity。参考深度取有效、有限、正深度且满足源 Alpha 条件的样本中位数：整图使用 Alpha ≥ 0.1，Cutout 使用所选 Alpha Threshold 并要求 Alpha > 0。非法字段和空参考区域抛出错误。
|
||||
|
||||
| 文件 | 内容 |
|
||||
| --- | --- |
|
||||
| `vector-depth.exr` | RGB 保存完整相机空间 XYZ，Alpha 保存 Validity |
|
||||
| `z-depth.exr` | RGB 重复保存完整相机 Z，Alpha 保存 Validity |
|
||||
| `depth.json` | 保存 `image_size`、3×3 `intrinsics` 与有效区域的 `reference_depth` |
|
||||
| `tangent-normal.png` | Tangent Space Normal Map |
|
||||
| `object-normal.png` | Cutout 原生 XY / Z 空间的 Object Space Normal Map |
|
||||
`common/depth.py` 加载深度并配置 Non-Color、CHANNEL_PACKED 与 Pack。Relief 和 Depth Balloon 读取 B/Z，Camera 与 Depth Solid 读取 XYZ，共用同一 EXR。
|
||||
|
||||
MoGe-2 的布尔 Mask 以 `0/1` 写入 Validity。Mask 外的有限 Depth/XYZ 仍保留在 RGB，使 Geometry Nodes 的线性采样维持连续；输入 Alpha、正深度和有限性只参与 `depth.json` 的参考样本筛选。任一待写 Field 包含 NaN/Inf 时不生成 EXR。
|
||||
## Selection 与颜色
|
||||
|
||||
Blender 通过 `common/depth.py` 加载 EXR，设为 Non-Color 并 Pack。Depth 与 Normal 数据块分别由 `depth_data_name()` 和 `normal_data_name()` 命名。Geometry Nodes 采样已加载的 EXR。
|
||||
Cutout 提交几何 bounds 内的原始 RGBA。Blender 在创建网格时组合源 Alpha 和 `SelectionMask`；颜色图保留矩形源 RGBA，法线可见区域取源 Alpha。AI 分析尺寸与颜色分辨率分别处理。
|
||||
|
||||
## Cutout Selection 产物
|
||||
|
||||
Blender 先把 `SelectionPath` 栅格化为 `SelectionMask`，再把局部 RGBA 作为 Server 输入。MoGe-2 输入统一按 `RGB × Alpha` 合成到黑底；完全透明像素下的隐藏 RGB 不影响预测。Server 不接收 Path 或 Mask 对象协议：
|
||||
|
||||
- 需要 Vector Depth 时请求 `vector-depth.exr` 与 `depth.json`；
|
||||
- 需要 Z Depth 时请求 `z-depth.exr` 与 `depth.json`；
|
||||
- Normal Map 按空间请求 `tangent-normal.png` 或 `object-normal.png`。
|
||||
|
||||
Cutout 的 Color、Normal 与 Depth 使用同一图片 Alpha 内容范围；Blender 再将该 Alpha 与 `SelectionMask` 相乘构建 Shape。Surface 与 Balloon 的本地路径直接组合源 Alpha 和 `SelectionMask`。
|
||||
|
||||
## Debug 产物
|
||||
|
||||
| Job | 文件 |
|
||||
| | |
|
||||
| `debug-da3` | `prediction.npz` |
|
||||
| `debug-moge2` | `prediction*.npz` |
|
||||
| `debug-ben2` | `foreground*.png` |
|
||||
| `debug-upscale` | `prediction*.png` |
|
||||
|
||||
Debug Job 保存模型适配层的直接输出。
|
||||
Remove Background、Upscale、Frame、Mask、Rectify 通过 `common/image.py` 的编辑结果入口保留源 Image 名称和共享引用语义。Plane 与 Cutout 的材质贴图使用 Color、Depth、Normal 命名函数。
|
||||
|
||||
Reference in New Issue
Block a user