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,93 +1,53 @@
|
||||
# Job Runtime 与 Server
|
||||
|
||||
AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧准备输入、提交普通字典参数并导入结果。
|
||||
|
||||
## 目录职责
|
||||
|
||||
```text
|
||||
src/anyimage/
|
||||
├── runtime.py # Environment 与 JobRuntime 配置
|
||||
└── server/
|
||||
├── app.py # 公开 Job 注册
|
||||
├── model_catalog.py # 模型声明
|
||||
├── model_download.py # 下载与校验
|
||||
├── model_manager.py # 模型目录与 Session 生命周期
|
||||
├── jobs/ # 公开协议与流程编排
|
||||
├── media/ # 图片、视频、序列帧和尺寸处理
|
||||
├── geometry/ # Depth / Normal 文件产物与相机元数据
|
||||
├── models/ # 模型适配与 ONNX 推理
|
||||
└── outputs/ # Debug Prediction 序列化
|
||||
```
|
||||
|
||||
`jobs/` 编排任务，领域目录提供媒体、Geometry、模型和输出能力。
|
||||
|
||||
## 生命周期
|
||||
`runtime.py` 配置 BlendJob `JobRuntime` 和独立 Python 3.12 Environment。`server/app.py` 注册 Job，`model_manager.py` 作为 `model_manager` Resource 管理下载文件与缓存 Session。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Request["Operator request()"] --> Runtime["JobRuntime"]
|
||||
Runtime --> Queue["单 Worker 队列"]
|
||||
Queue --> Job["app.py 注册的 Job"]
|
||||
Job --> Resource["ModelManager / Media"]
|
||||
Resource --> Directory["jobs/<job-id>/"]
|
||||
Directory --> Response["Operator response()"]
|
||||
A[Operator request] --> B[JobRuntime]
|
||||
B --> C[Server 单 Worker 队列]
|
||||
C --> D[Job 调用媒体与模型模块]
|
||||
D --> E[写入 jobs/job-id 目录]
|
||||
E --> F[主线程 response]
|
||||
```
|
||||
|
||||
Job 在阶段边界调用 `context.check_cancelled()`，并把稳定产物写入当前 Job 目录。Blender 响应完成后，再由输入所有者清理临时 Packed Image 文件。
|
||||
Job 在阶段和帧边界检查取消，进度通过 `context.progress()` 返回。视频临时帧由 `media/input.py` 的上下文管理器清理，Blender 导出的临时输入由对应 Operator 清理。
|
||||
|
||||
## 公开 Job
|
||||
## Job 与数据模块
|
||||
|
||||
| Job | 主要用途 |
|
||||
| Job | 实现与用途 |
|
||||
| --- | --- |
|
||||
| `download-model`、`download-required-models` | 准备模型文件 |
|
||||
| `remove-background` | 生成 BEN2 透明前景 |
|
||||
| `upscale-image` | 4× 图片或帧序列 |
|
||||
| `generate-depth-plane-geometry` | 为 Depth Plane 复制颜色并生成 Z Depth 与相机元数据 |
|
||||
| `generate-cutout-artifacts` | 为 Cutout 生成 Depth 或 Normal 文件产物 |
|
||||
| `debug-*` | 保存模型适配层的直接输出 |
|
||||
| `download-model`、`download-required-models` | `app.py` 调用 ModelManager 下载单个或缺失模型 |
|
||||
| `remove-background` | `jobs/remove_background.py`，生成 BEN2 前景 |
|
||||
| `upscale-image` | `jobs/upscale.py`，生成 2× 图像或序列 |
|
||||
| `generate-depth-plane-geometry` | `jobs/depth_plane.py`，复制整图颜色并生成深度、元数据与切线法线 |
|
||||
| `generate-cutout-artifacts` | `jobs/cutout.py`，按请求生成 Cutout 深度和法线 |
|
||||
|
||||
`generate-depth-plane-geometry` 对应 `jobs/depth_plane.py`；`generate-cutout-artifacts` 对应 `jobs/cutout.py`。共享的 MoGe-2 推理编排位于 `geometry/prediction_artifacts.py`，它把 Selection RGBA 合成到黑底后执行推理，并把单帧 `GeometryFrame` 交给 Depth、Normal 与 Metadata Writer。Depth EXR 与元数据写入位于 `geometry/depth_texture.py`，Normal 编码位于 `geometry/normal_texture.py`。Selection Mask 由 Blender 在最终图片或网格阶段组合。
|
||||
`media/` 处理单图、序列、视频与输入尺寸。Depth Plane 和 Cutout 按单张静态图片工作；Remove Background 与 Upscale 逐帧处理动画输入。
|
||||
|
||||
## 尺寸约束
|
||||
`geometry/prediction_artifacts.py` 将限尺寸后的 RGBA 合成到黑底，运行一次 MoGe-2，再调用深度、法线和元数据写入器。Cutout 的深度分支通过 `edge_depth.py` 延展轮廓附近的深度；法线使用原预测。文件字段见 [Job 产物](outputs.md)。
|
||||
|
||||
`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map 的模型分析图长边；材质颜色图使用原始分辨率。
|
||||
## 模型与缓存
|
||||
|
||||
Blender 侧的 **Maximum Cutout Mesh Resolution** 统一限制所有 Cutout Shape 实际几何范围的最长网格采样边，不限制 Selection bounds 的原始像素尺寸。
|
||||
| 用途 | 模型 | Session 分类 |
|
||||
| --- | --- | --- |
|
||||
| Depth 与 Normal | MoGe-2 ViT-S / ViT-B / ViT-L Normal | geometry |
|
||||
| Remove Background | BEN2 | ben2 |
|
||||
| Upscale | Real-ESRGAN WDN、SAFMN、Real-ESRGAN x4plus、PiSA-SR | upscale |
|
||||
|
||||
`generate-depth-plane-geometry` 与 `generate-cutout-artifacts` 只接受一帧，因此 Depth Plane 与 Cutout 是静态图工作流。Remove Background 与 Upscale 继续通过媒体入口处理单图、视频和序列帧。
|
||||
|
||||
## 模型
|
||||
|
||||
Depth Plane、Cutout Depth 与 Normal Map 使用 MoGe-2，Remove Background 使用 BEN2，Upscale 使用所选高清模型。MoGe-2 生产推理直接返回 `GeometryFrame`；DA3 调试推理保留模型原始 Prediction，并可按帧适配到相同结构。
|
||||
|
||||
`ModelManager` 按模型族管理下载目录与 ONNX Session，同一族只保留最近使用的模型和 Device，避免同类模型重复占用资源。
|
||||
|
||||
BEN2、DA3、MoGe-2 与 Upscale 共用 ONNX Runtime 推理入口。CUDA Session 使用可收缩的 memory arena；单次图片、完整帧集合或完整 Upscale tile 集合只在最后一次模型运行结束时收缩空闲 arena。Session 持有的模型权重与执行计划继续由 `ModelManager` 缓存，后续相同模型与 Device 直接复用。CPU、DirectML 与 CoreML 按各自 Provider 的普通运行方式执行。macOS arm64 默认使用 CPU；用户可选择 `coreml`，由 ONNX Runtime CoreML Execution Provider 在 Apple CPU、GPU 与 Neural Engine 之间调度，不使用 PyTorch MPS backend。MoGe-2 的动态 ONNX 图只把静态输入 shape 分区交给 CoreML，其余节点由 CPU Provider 执行；其他模型不使用该限制。
|
||||
`model_catalog.py` 声明文件来源、许可、大小和 SHA-256。`model_download.py` 下载文件并校验；ModelManager 按模型路径和设备缓存各类最近使用的 Session，切换模型或设备时释放对应类别。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Request["模型请求"] --> Cache["ModelManager 获取缓存 Session"]
|
||||
Cache --> Runs["执行单次或批量模型运行"]
|
||||
Runs --> Final["最后一次模型运行"]
|
||||
Final --> Shrink["CUDA 收缩空闲 memory arena"]
|
||||
Shrink --> Reuse["Session 留在 ModelManager 中复用"]
|
||||
A[取得缓存 Session] --> B[运行单图、多帧或 tile]
|
||||
B --> C[最后一次推理]
|
||||
C --> D[CUDA 收缩空闲 arena]
|
||||
D --> E[保留 Session 供后续复用]
|
||||
E --> F[Clear Models 或关闭 Server 时释放]
|
||||
```
|
||||
|
||||
## Environment 与 Storage Root
|
||||
Windows 默认 DirectML，macOS arm64 默认 CPU 并支持选择 CoreML。MoGe-2 为 CoreML 配置静态 shape 分区，其余计算由 CPU 执行。PiSA-SR 在 CoreML 上返回明确的支持限制；其分阶段 Session 在切换阶段、取消和清理时关闭。
|
||||
|
||||
`runtime.py` 声明独立 Python 3.12 环境和固定依赖。首次安装会准备默认 MoGe-2、BEN2 与 Real-ESRGAN WDN 模型。Storage Root 默认是 `~/.anyimage`：
|
||||
## Environment 与存储
|
||||
|
||||
```text
|
||||
~/.anyimage/
|
||||
├── .venv/
|
||||
├── models/
|
||||
├── jobs/
|
||||
├── environment.json
|
||||
├── manifest.json
|
||||
├── install.log
|
||||
└── server.log
|
||||
```
|
||||
|
||||
切换 Storage Root 等同于切换整套 Environment、模型与任务数据，不自动迁移旧目录。
|
||||
|
||||
各 Job 的稳定产物见 [Job 产物](outputs.md)。
|
||||
首次安装通过 `post_install()` 下载默认 MoGe-2、BEN2 与 Real-ESRGAN WDN。Storage Root 默认 `~/.anyimage`，其中保存 `.venv/`、`models/`、`jobs/` 及环境状态和日志。设置入口与安装流程见 [AI 环境管理](operators/ai-setup.md)。
|
||||
|
||||
Reference in New Issue
Block a user