nan
7dec3b7ca4
- Implemented `cutout_depth_surface.py` for face separation and connected thickness calculations for depth surface assets. - Created `cutout_depth_surface_layout.py` to arrange nodes for staggered calculation branches in depth surface processing. - Authored `geometry_layouts.py` to define layouts for various geometry assets, including image cutouts and depth planes. - Introduced `node_layout.py` for shared presentation rules, facilitating node arrangement and validation in geometry-node layouts.
89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
# 节点资产
|
||
|
||
生产节点组由脚本构建到 `src/anyimage/assets/O_AnyImage.blend`；运行时只加载，不创建节点组。
|
||
|
||
## 构建
|
||
|
||
在项目根目录执行：
|
||
|
||
```bash
|
||
uv run build_node
|
||
```
|
||
|
||
脚本依次构建资产、运行三项 Blender 验证和完整测试，任一步失败即退出。
|
||
|
||
脚本按 `--blender`、环境变量 `BLENDER_BIN`、项目 `.env`、`PATH` 的顺序查找 Blender。无法自动找到时，在项目根目录的 `.env` 中配置：
|
||
|
||
```dotenv
|
||
BLENDER_BIN="/absolute/path/to/blender"
|
||
```
|
||
|
||
`.env` 已被 Git 忽略。临时指定路径或跳过 Python 测试：
|
||
|
||
```bash
|
||
uv run build_node --blender "/path/to/blender"
|
||
uv run build_node --skip-tests
|
||
```
|
||
|
||
## 资产清单
|
||
|
||
| 节点组 | 构建模块 |
|
||
| --- | --- |
|
||
| `O Mesh Plane` | `build_mesh_plane.py` |
|
||
| `O Image Depth Plane` | `build_depth_plane.py` |
|
||
| `O Image Layer`、`O Image Depth Layer` | `build_material_layers.py` |
|
||
| `O Shadeless` | `build_shadeless.py` |
|
||
| `O Image Cutout` | `build_cutout.py` |
|
||
| `O Image Surface`、`O Image Balloon` | `build_cutout.py` |
|
||
| `O Image Depth Balloon`、`O Image Depth Surface` | `build_cutout.py` |
|
||
|
||
构建从空 Factory 文件生成全部节点组，关闭 `.blend1` 备份，并覆盖唯一发布资产。
|
||
|
||
四个 Cutout Shape 子节点统一接收局部 XY 平面，并以 `-Z` 表示向图片内部的方向。`O Image Cutout` 在 Shape 分支与平滑之后处理 **Inward Axis**：默认 `-Z` 直接输出原生几何，`+X` 分支执行一次 Z 到 X 的轴转换；运行时对象矩阵使用逆变换补偿，保证两种模式落在相同世界空间位置。
|
||
|
||
`O Image Depth Plane`、`O Image Cutout`、`O Image Depth Balloon` 与 `O Image Depth Surface` 统一使用 **Reference Depth** 作为采样深度的运算基准。
|
||
|
||
### Depth Surface 分离与厚度
|
||
|
||
Options 中的 **Split** 范围为 `0–1`，默认 `0` 关闭分离，数值越大越容易分离。节点比较 `场景 Z 差 × Split > 原始面中心距离 × 2.5`；`0.5` 对应深度坡度阈值 `5`。场景 Z 差包含图片标定的 **Uniform Scale** 和 **Depth Scale**。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[基础网格与深度图片] --> B[面中心采样与共享边判别]
|
||
B --> C[存入面角命名属性并 Split Edges]
|
||
C --> D[Cleanup 清理拆后平面区域]
|
||
D --> E[切口顶点沿原相机射线采用所属侧深度]
|
||
E --> J[固定顶点数据并投影]
|
||
J --> F[生成正背面与分段侧壁]
|
||
F --> G[按原顶点及厚度层身份连接]
|
||
G --> H[恢复场景坐标]
|
||
H --> K[移除 o_depth_* 暂存属性]
|
||
K --> I[外层 Smooth 与方向变换]
|
||
```
|
||
|
||
Split 关闭时使用原顶点采样，Cleanup 仍处理原平面区域。Depth Surface 的 Cleanup 在分离后、投影和厚度前执行；其他 Shape 保持原清理流程。
|
||
|
||
未关联选中切边的顶点使用原始 XYZ。切口顶点以 `原 XYZ × 所属侧 Z / 原 Z` 保持原相机射线，随后执行既有 Uniform Scale、Reference Depth 和 Depth Scale 投影。
|
||
|
||
厚度前固定顶点数据，使正背面和侧壁使用相同位置。连接时以原顶点编号和厚度层构造临时整数坐标，合并同一身份的副本后恢复场景坐标，保持近距离分离区域各自独立。实现位于 `cutout_depth_surface.py`，由 `build_cutout.py` 构建进共享节点资产。
|
||
|
||
暂存值通过 Store Named Attribute 写入保留前缀 `o_depth_`：面中心与相机采样使用 FACE，所属侧相机采样与切口标记使用 CORNER，最终相机坐标、表面位置、源顶点编号与厚度分段数使用 POINT。计算区域就近使用 Named Attribute，末尾用一个 Wildcard 模式的 Remove Named Attribute 匹配 `o_depth_*`，输出保留 UVMap 与用户属性。
|
||
|
||
### 几何节点布局
|
||
|
||
全部七个几何节点组使用连续横排的几何主轴。主轴可适当宽松，支线内部紧凑，同一目的的计算聚在同一侧，内部间距明显小于与其他部分的距离；独立用途可在两侧错落展开。长算式横排，末端就近汇入主轴。Join Geometry、Menu Switch、Combine XYZ 的同级独立分支末端排成一列并对齐输出端，菜单分支按输入顺序上下排列，共享上游留在公共位置。必要的向左引用直接连接。Group Input 与 Named Attribute 就近放置，全接线的简单运算可折叠，常数和域设置保持可见。
|
||
|
||
`geometry_layouts.py` 组织平面、外层 Cutout 和三个 Shape 的布局，`cutout_depth_surface_layout.py` 组织 Depth Surface；`node_layout.py` 统一放置局部输入、隐藏未使用输出并检查节点边界。具体规则见 [AGENTS.md](../../AGENTS.md)。布局验收包含实际节点编辑器预览，以及重排前后的运算、默认值、实际连接和几何结果比较。
|
||
|
||
## 修改节点组
|
||
|
||
1. 修改 `tools/node_assets/build_*.py`；
|
||
2. 更新对应验证；
|
||
3. 运行一键构建脚本；
|
||
4. 搜索并清理旧名称、接口和路径；
|
||
5. 检查 `.blend`、代码、测试和文档差异。
|
||
|
||
接口、节点、连线、默认值或布局变化时必须重建。只修改运行时 Python、Markdown 或打包逻辑时无需重建。
|
||
|
||
`O_AnyImage.blend1` 等备份不应提交或打包。
|