Add tools and tests for AnyImage model management and documentation

- Implement sync_models.py for preparing and uploading ONNX artifacts.
- Create build_node.py for building and validating Blender scripts.
- Add docs.py for building and previewing documentation with Mike or MkDocs.
- Introduce model_exports.py for exporting PyTorch models to ONNX format.
- Develop pack.py for packaging the project with dependencies for different platforms.
- Add test_sync_models.py to validate sync_models functionality.
- Add test_tool_commands.py to ensure repository tools have correct command scripts.
- Initialize tools package with __init__.py.
This commit is contained in:
2026-08-31 15:15:33 +08:00
parent 377eee43f5
commit e7aeeb21d4
99 changed files with 1953 additions and 1676 deletions

View File

@@ -1,60 +1,52 @@
# 节点资产
AnyImage 将生产功能使用的可复用 Geometry Nodes 和 Shader 节点组统一构建到 `O_AnyImage.blend`,运行时只按名称加载,不动态创建节点组。
生产节点组由脚本构建到 `src/anyimage/assets/O_AnyImage.blend`;运行时只加载,不创建节点组。
## 对应文件
## 构建
```text
src/anyimage/
├── assets/O_AnyImage.blend
├── operators/common/mesh_result.py # 运行时资产加载与 Modifier 输入
└── operators/convert_to_plane/nodes.py # Plane 节点资产名称与加载入口
tools/node_assets/
├── build.py # 统一构建入口
├── node_graph.py # Cutout 资产构建专用节点图函数
├── build_mesh_plane.py
├── build_depth_plane.py
├── build_material_layers.py
├── build_shadeless.py
├── build_cutout.py
├── validate.py # 资产清单与基础接口
├── validate_mesh_plane.py
└── validate_cutout.py
```
## 构建与加载
```mermaid
flowchart TD
Scripts["tools/node_assets/build_*.py"] --> Build["Blender 后台构建"]
Build --> Blend["assets/O_AnyImage.blend"]
Blend --> Loader["operators/common/mesh_result.py"]
Loader --> Modifier["运行时 Node Group / Modifier"]
```
使用 Blender 而不是普通 Python 执行:
在项目根目录执行:
```bash
BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
"$BLENDER_BIN" --background --python tools/node_assets/build.py
"$BLENDER_BIN" --background --python tools/node_assets/validate.py
"$BLENDER_BIN" --background --python tools/node_assets/validate_mesh_plane.py
"$BLENDER_BIN" --background --python tools/node_assets/validate_cutout.py
uv run build_node
```
`build.py` 从空 Factory 文件开始,依次构建 `O Mesh Plane`、`O Image Depth Plane`、`O Image Layer`、`O Image Depth Layer`、`O Shadeless`、四个 Cutout 内部节点组与公开修改器节点组 `O Image Cutout`,再保存唯一资产文件。`O Image Cutout` 用 Menu Switch 包装四个内部组;运行时 Loader 只加载这个稳定入口,Blender 4.5 根据 Shape 菜单依赖只显示当前分支实际使用的输入。
脚本依次构建资产、运行三项 Blender 验证和完整测试,任一步失败即退出。
## 验证范围
脚本按 `--blender`、环境变量 `BLENDER_BIN`、项目 `.env`、`PATH` 的顺序查找 Blender。无法自动找到时,在项目根目录的 `.env` 中配置:
基础验证检查完整发布资产清单、节点树类型、Modifier 标记、接口顺序和 Fake User。专项验证继续检查:
```dotenv
BLENDER_BIN="/absolute/path/to/blender"
```
- Mesh Plane 的接口、细分、Thickness 和几何求值;
- `O Image Cutout` 的公开接口、Shape 菜单和四个内部组的依赖关系;
- 节点不重叠、主要连线保持从左向右;
- 局部 Group Input 未使用输出隐藏;
- Cleanup 只在四条分支之前执行,Smooth 只在菜单选择之后执行;
- Repeat Zone 数量和四种 Shape 的关键几何求值稳定。
`.env` 已被 Git 忽略。临时指定路径或跳过 Python 测试:
节点资产接口变化时,应运行全部四个 Blender 入口和完整 Python 测试。只修改 Python、Markdown 或打包逻辑时无需重建 `.blend`。Blender 自动生成的 `.blend1` 等备份不属于发布资产。
```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` 备份,并覆盖唯一发布资产。
## 修改节点组
1. 修改 `tools/node_assets/build_*.py`;
2. 更新对应验证;
3. 运行一键构建脚本;
4. 搜索并清理旧名称、接口和路径;
5. 检查 `.blend`、代码、测试和文档差异。
接口、节点、连线、默认值或布局变化时必须重建。只修改运行时 Python、Markdown 或打包逻辑时无需重建。
`O_AnyImage.blend1` 等备份不应提交或打包。