Refactor geometry node groups for image depth processing

- Introduced new utility functions in common nodes for evaluating fields and capturing attributes.
- Simplified volume field calculations in image depth cutout and panorama groups by utilizing new utility functions.
- Enhanced readability and maintainability of the image depth cutout and panorama node groups by removing redundant code and improving function usage.
- Adjusted default values for thickness and depth scale in image relief plane group for better user experience.
- Improved handling of geometry attributes and connections in image depth plane group to streamline processing.
This commit is contained in:
2026-09-10 16:46:19 +08:00
parent 489003c2cc
commit 8ae3c1d5b7
20 changed files with 553 additions and 473 deletions

View File

@@ -2,21 +2,33 @@
## 构建节点资产
生产节点组由 `uv run build-nodes` 构建到 `src/anyimage/assets/O_AnyImage.blend`
生产节点组由 `uv run node-group build` 构建到 `src/anyimage/assets/O_AnyImage.blend`
节点组文件在 `tools/nodes/groups`
节点组规则:
- Group Input 按区域重复放置,Named Attribute 等字段入口就近读取;隐藏所有未使用输出,避免从远处拉线
- 跨区域暂存值用 Store Named Attribute 写入 `o_*` 命名空间,按用途分配前缀并明确 FACE、CORNER、POINT 域和存取时机;末尾用一个 Wildcard 模式的 Remove Named Attribute 清理该前缀,例如 `o_depth_*`,保留用户属性和 UV
- Capture Attribute 适合局部字段固定;若属性连线跨越多个步骤,改为命名属性,让计算分支独立展开
- 字段默认直接连接,多个消费者可复用同一输出;按消费位置的几何、域、类型和输入属性版本验证求值等价性
- 域转换使用 Evaluate on Domain 或明确域的采样节点表达;跨变形、拓扑或分支变化需要固定源值时,使用 Capture Attribute,明确捕获时机并验证几何传播路径
- 命名属性用于需要按名称访问的数据协议,明确名称、类型、域、写入选择和消费者;内部临时属性使用专用 `o_*` 前缀,在最后消费者之后按前缀清理,保留 UV、用户属性和外部协议属性
- Group Input 按区域重复放置,通过字段排列和必要的 Reroute 保持连线可读,隐藏未使用输出;存储须有数据生命周期依据
- 构建阶段通过明确的节点或 socket 引用接线
- 保留节点默认 `name` 和标题,不用 `label` 覆盖,不用 String 节点注解。Frame 仅用于确有包裹语义的区域
- 全接线的简单数学运算可折叠;需要阅读的常数、运算域和模式保持可见
- 修改器 Geometry Nodes 的输入 socket 默认使用 `SINGLE`
- socket `subtype` 按业务语义设置:长度用 `DISTANCE`,`0–1` 比例用 `FACTOR`,`0–100` 用 `PERCENTAGE`;无对应范围语义时保留默认
- 接口或布局变更须验证 socket 顺序与结构、未使用输出隐藏及几何求值;纯布局变更比较运算、默认值和实际连接,确认功能不变
```mermaid
flowchart TD
A[字段生产与消费] --> B{需要按名称访问}
B -->|是| C[命名属性]
B -->|否| D{目标上下文重新求值是否等价}
D -->|是| E[字段直连并显式转换域]
D -->|否| F[在源几何与源域捕获]
F --> G[随几何传递匿名属性]
```
## 资产清单
@@ -31,6 +43,7 @@
| `O Image Cutout` | `image_cutout.py` |
| `O Image Depth Cutout` | `image_depth_cutout.py` |
| `O Image Depth Balloon` | `image_depth_balloon.py` |
| `O Image Depth Panorama` | `image_depth_panorama.py` |
## 构建资产脚本
@@ -40,8 +53,8 @@
保存后,`check.py` 在独立 Blender 进程中重新加载资产并做基本几何求值。接口、默认值和详细几何行为由 `tests/` 检查。
```bash
uv run build-nodes --blender "/path/to/blender"
uv run build-nodes --skip-tests
uv run node-group build --blender "/path/to/blender"
uv run node-group build --skip-tests
```
脚本按 `--blender`、环境变量 `BLENDER_BIN`、项目 `.env`、`PATH` 的顺序查找 Blender。无法自动找到时,在项目根目录的 `.env` 中配置: