Add new node asset scripts for geometry and shader operations

- Implemented `build_mesh_plane.py` to create a geometry node group for mesh planes with customizable parameters. - Created `build_shadeless.py` for a shader node group that displays color without scene lighting while preserving shadows and reflections. - Added `validate.py` to validate the integrity of the newly created node groups and their inputs. - Introduced `validate_cutout.py` to ensure the functionality of cutout node groups and their dependencies. - Developed `validate_mesh_plane.py` to test the mesh plane creation and its modifier settings.
2026-08-30 00:17:29 +08:00
parent 7d39fe8c5e
commit 32bcd45d7b
168 changed files with 7213 additions and 13121 deletions
--- a/docs/internals/runtime.md
+++ b/docs/internals/runtime.md
@@ -0,0 +1,86 @@
+# Job Runtime 与 Server
+
+AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程和任务队列。Blender 侧只配置 Runtime 与提交参数；`server/` 是不依赖 `bpy` 的计算包，可以在独立解释器中导入。
+
+## 对应文件
+
+```text
+src/anyimage/
+├── runtime.py                 # Environment 与 JobRuntime 配置
+└── server/
+    ├── app.py                 # Job 注册和共享资源
+    ├── model_catalog.py       # 模型声明
+    ├── model_download.py      # 下载、校验与镜像回退
+    ├── model_manager.py       # 模型目录与 Session 缓存
+    ├── media/input.py         # 图片、视频和序列输入
+    ├── jobs/                  # app.py 可提交的公开任务
+    ├── selection/             # 选区栅格化与 Cutout 图片准备
+    ├── models/                # 模型适配与 ONNX 推理
+    ├── geometry/              # 深度反投影与法线纹理编码
+    └── outputs/               # Debug Prediction 序列化
+```
+
+## 任务生命周期
+
+```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()"]
+```
+
+Runtime 在首次任务或显式启动时拉起 Server。任务在队列中串行执行，进度、取消和日志由 BlendJob 提供；AnyImage Job 在阶段边界调用 `context.check_cancelled()`，并把业务产物写入当前 Job 目录。Operator 完成响应后再清理 Blender 侧为 Packed Image 准备的临时输入。
+
+`server/app.py` 是任务清单的唯一入口：
+
+| Job | 主要用途 |
+| --- | --- |
+| `download-model`、`download-required-models` | 准备模型文件 |
+| `remove-background` | BEN2 透明前景 |
+| `upscale-image` | 4× 图片或帧序列 |
+| `refine-image-mask` | 为 Image Box / Lasso 细化选区 |
+| `prepare-geometry-data` | 为 Depth Plane 或 Cutout 准备颜色、选区、深度和法线数据 |
+| `debug-*` | 保存模型适配层的直接输出 |
+
+## 媒体输入
+
+`server/media/input.py` 把单图、视频和图片目录统一为有序帧路径，并用上下文管理器负责临时帧目录的生命周期。它还支持将颜色输入与分析输入分开：例如 Upscale 结果可以作为颜色来源，同时使用它保存的原图引用进行 Depth Plane 分析。帧展开是媒体输入的内部能力，不再暴露没有业务消费者的独立 Job。 `server/media/resolution.py` 提供默认 `2048` 的共用输入长边限制；Upscale 直接限制每帧，`prepare-geometry-data` 则在 Cutout 裁切和分析输入选择完成后限制 Depth / Normal 模型输入。该临时缩放图不参与颜色产物写入。
+
+当前 `prepare-geometry-data` 只接受一帧，因此 Depth Plane 与 Cutout 都是静态图工作流。Remove Background 与 Upscale 通过同一媒体入口处理单图、视频和序列帧。
+
+公开 Job 不与 Operator 一一对应：Depth Plane 和 Cutout 共享 `prepare-geometry-data`，四个 Debug Job 共享 `jobs/debug_predictions.py`。Job 只负责协议和编排；可复用的输入、选区、模型与几何数据能力分别位于 `media/`、`selection/`、`models/` 和 `geometry/`，Job 之间不互相导入实现。
+
+## 模型层
+
+Job 只编排流程，模型适配层把不同推理 API 统一为内存对象：
+
+- DA3 适配为深度、置信度、相机内外参与相机点。
+- MoGe-2 适配为深度、法线、有效区域、相机内参与可选相机点。
+- BEN2 返回带 Alpha 的前景图。
+- Upscale 返回保留源 Alpha 的 4× RGBA 图。
+
+`ModelManager` 管理下载目录和 ONNX Session。缓存按 BEN2、几何模型和 Upscale 三个族分开；每个族只保留最近一次使用的模型与 Device，切换同族模型时释放旧 Session。这样连续任务可以复用模型，同时避免同一类模型重复占用资源。
+
+## Environment 与 Storage Root
+
+`runtime.py` 声明 Python 3.12 环境和固定版本的 NumPy、Pillow、PyAV、trimesh、Hugging Face Hub 与 ONNX Runtime。Windows 安装 DirectML 版本，其他平台安装标准 ONNX Runtime。首次安装后依次下载默认 MoGe-2、BEN2 和 Real-ESRGAN WDN 模型。
+
+Storage Root 默认是 `~/.anyimage`：
+
+```text
+~/.anyimage/
+├── .venv/           # 独立 Environment
+├── models/          # 模型目录
+├── jobs/            # Job 产物与 job.log
+├── environment.json
+├── manifest.json
+├── install.log
+└── server.log
+```
+
+Storage Root 由扩展偏好设置提供给 Runtime。切换路径等同于切换整套 Environment、模型和任务数据，不会自动迁移旧目录。
+
+各 Job 的稳定产物见 [Job 产物](outputs.md)。