nan
4c902ed7db
- 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.
76 lines
5.4 KiB
Markdown
76 lines
5.4 KiB
Markdown
## Context
|
||
|
||
`build_depth_plane.py` 当前读取纹理 R 通道并生成固定底面浮雕；`build_depth_surface.py` 使用 XYZ 投影并沿平滑法线生成壳。Cutout 的 Depth Solid 请求 VECTOR，Depth Balloon 请求 Z，但 Balloon 节点和 `common/depth.py` 已读取 B/Z。Server 将两类产物写成相同规格的 RGBA float32 EXR。
|
||
|
||
本设计以当前工作区已实现的 `add-projected-depth-plane` 为基线，覆盖其中关于独立 Surface 入口与 Z/VECTOR 双产物的决定。
|
||
|
||
## Goals / Non-Goals
|
||
|
||
统一整图深度几何的交互入口和深度产物契约，保留两种形态及 Cutout 的现有几何效果。删除范围限定于独立 Z 文件输出及失去用途的分支；内部标量深度、标定元数据、Cutout 的形状参数继续承担原有职责。
|
||
|
||
## Decisions
|
||
|
||
### 一个入口与模式接口
|
||
|
||
保留 `ConvertToDepthPlane`、`anyimage.convert_to_depth_plane`、Convert to Depth Plane 和 `O Image Depth Plane`。删除独立 Surface 注册、菜单、类、结果类型映射和公开资产组。模式在修改器中选择，默认 Relief；模式切换只触发节点求值。
|
||
|
||
| 接口顺序 | 默认值与语义 |
|
||
| --- | --- |
|
||
| Geometry | 结构输入 |
|
||
| Mode | Relief / Camera，默认 Relief |
|
||
| Subdivide | 6，范围 0–10 |
|
||
| Thickness（Relief） | 0，最小 0，DISTANCE |
|
||
| Thickness（Camera） | 0，最小 0，DISTANCE |
|
||
| Depth Scale | 1，最小 0 |
|
||
| Options / Reference Depth | 元数据 reference_depth × Uniform Scale，DISTANCE |
|
||
| Options / Normal Smooth | 50，范围 0–50，仅影响 Camera 厚度方向 |
|
||
| Data / Uniform Scale | 隐藏，默认 1 |
|
||
| Data / Depth Image | 隐藏 |
|
||
|
||
输入统一 SINGLE。两个独立输入均显示 Thickness，依次控制 Relief 的基础厚度和 Camera 的向内壳厚度，默认均为 0 m；按不同 socket identifier 保存，切换模式保留各自数值。Normal Smooth 保留在 Options，并通过说明明确适用模式。
|
||
|
||
### 两条几何分支共用数据
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Input[图片矩形 Mesh 与 depth.exr] --> Mode{Mode}
|
||
Mode --> Relief[Relief：固定 XY，读取 B 深度，固定底面]
|
||
Mode --> Camera[Camera：相机 XYZ 投影，沿平滑法线生成壳]
|
||
Relief --> Output[保留 UV 材质与用户属性，清理临时属性]
|
||
Camera --> Output
|
||
```
|
||
|
||
Relief 沿用现有厚度、底面权重、侧面插值和负位移限制，只将标量采样改为 B/Z。Camera 沿用现有完整矩形细分与投影公式：令采样相机 XYZ 乘以 Uniform Scale 得到 C，局部 XY 从基础 XY 按 Depth Scale 插值到 `(C.x, -C.y)`，局部 Z 为 `(Reference Depth - C.z) × Depth Scale`。正 Thickness 保留正面，背面沿正面 POINT 法线按 Normal Smooth 迭代平滑并归一化后向内偏移。
|
||
|
||
共用投影和壳构建函数，两个分支由一个公开节点组组织。构建模块以职责命名；删除仅服务旧公开 Surface 组的构建和布局入口。节点资产始终按名称加载。
|
||
|
||
### 统一深度产物与请求
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Request[整图转换或 Cutout 深度请求] --> Infer[一次 MoGe 推理，保留 points]
|
||
Infer --> Correct[按现有调用条件修正边缘深度]
|
||
Correct --> Artifact[depth.exr：RGB 相机 XYZ，A 有效性]
|
||
Correct --> Metadata[depth.json：尺寸 内参 基准深度]
|
||
Artifact --> Load[结果键 depth，主线程加载并 Pack]
|
||
Load --> XYZ[Camera 与 Depth Cutout：读取 XYZ]
|
||
Load --> Z[Relief 与 Depth Balloon：读取 B/Z]
|
||
```
|
||
|
||
将深度产物选择收敛为布尔 `generate_depth`，默认 false；整图 Job 固定请求 true，Cutout 根据 Depth Solid / Depth Balloon 判断。替换 `depth_mode` 参数与 `depth_mode_for_shape`，生成法线的参数保持独立。只生成法线时仍可不保留 points。
|
||
|
||
写出函数统一为 `write_depth_texture`，沿用当前 vector 写出的 RGBA float32 数值、有效性和非有限值处理；文件名 `depth.exr`，返回键 `depth`。删除 Z 写出函数与旧结果键，直接更新全部调用和测试。所有需要深度的推理保留 XYZ，内部 `GeometryFrame.depth` 继续用于标量运算；元数据仍通过 `depth_metadata` 返回 `depth.json`。深度与法线继续来自同一次预测，保持各自现有边缘修正语义。
|
||
|
||
### 交付与验证
|
||
|
||
客户端、Server、节点构建及测试作为一次契约变更交付，不增加旧键、旧名称转发。已有 blend 内嵌旧组不主动迁移；需要新模式接口时重新转换源图片。归档时协调前序未归档规格，确保最终规格只保留统一入口和产物契约。
|
||
|
||
实现阶段更新脚本、验证、测试与节点资产文档并运行测试。资产更新阶段构建并验证 `O_AnyImage.blend`，对定义与保存资产使用同组几何用例，最后在 Blender 检查总览和局部实际绘制布局；视觉验收单独记录，不能由坐标检查代替。
|
||
|
||
## Risks / Trade-offs
|
||
|
||
- R 与 Z 在旧标量 EXR 中相同，普通灰度测试会掩盖读错通道 → 使用 X、Y、Z 明显不同的合成纹理覆盖全部消费者。
|
||
- Balloon 从仅保留 depth 改为保留 points，增加中间内存 → 验证单次推理、释放路径和正常生成；文件格式与通道数保持一致。
|
||
- 两种模式中 Thickness 的几何含义不同 → 明确接口说明，并测试切换保留值及两种模式各自的厚度行为。
|
||
- 新代码与旧节点资产混用可能造成接口错误 → 资产更新时同时检查菜单、注册、公开组清单及实际资产求值。
|