nan
1613bd3194
- Implemented the Image Perspective tool for editing image corners in Blender. - Created a new operator `EditImagePerspective` to handle the perspective transformation. - Added a preview feature for the perspective adjustment. - Introduced the `ImagePolylineTool` for editing image masks with polylines. - Developed backend support for Real-ESRGAN model inference, including ONNX integration. - Added functionality for image masking and background removal. - Created unit tests for the Real-ESRGAN ONNX model to ensure correct preprocessing and inference.
95 lines
5.9 KiB
Markdown
95 lines
5.9 KiB
Markdown
# Job Server
|
||
|
||
AnyImage 把 AI 与媒体处理放在独立 Job Server 中运行，使 Blender Python 保持轻量。安装和使用问题见[安装与首次配置](installation.md)与[常见问题](faq.md)。
|
||
|
||
## 架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Blender["Blender Operator"] --> Runtime["JobRuntime"]
|
||
Runtime --> Queue["FIFO Queue"]
|
||
Queue --> Job["AnyImage Job"]
|
||
Job --> Media["Media"]
|
||
Job --> Models["ModelManager"]
|
||
Job --> Geometry["Geometry"]
|
||
Job --> Outputs["Outputs"]
|
||
Outputs --> Directory["Job Directory"]
|
||
Directory --> Blender
|
||
```
|
||
|
||
每个 Blender 实例拥有自己的 Server 进程，连接绑定到本机随机端口和 Instance ID。多个实例可以共享 Storage Root，但各自维护进程、队列和内存中的模型 Session。
|
||
|
||
BlendJob 提供 Runtime、HTTP transport、队列、状态和取消协议。AnyImage 的 Operator 负责业务参数，Server Job 负责工作流编排，结果由 Operator 在 Blender 主线程中导入。
|
||
|
||
## Storage Root
|
||
|
||
默认位置为 `~/.anyimage`：
|
||
|
||
```text
|
||
~/.anyimage/
|
||
├── .venv/ Python Environment
|
||
├── models/ ONNX 模型
|
||
├── jobs/ 任务产物
|
||
├── environment.json 环境声明
|
||
├── manifest.json 已安装环境指纹
|
||
├── install.log 安装日志
|
||
└── server.log Server 日志
|
||
```
|
||
|
||
更改 Storage Root 相当于切换整套 Environment、模型和任务数据。目录说明见[模型、设备与存储](models-and-storage.md)。
|
||
|
||
## 模块关系
|
||
|
||
| 模块 | 职责 |
|
||
| --- | --- |
|
||
| `runtime.py` | Environment、Server 生命周期、任务状态与 Storage Root |
|
||
| `server/jobs/` | 按功能编排完整任务 |
|
||
| `server/media/` | 图片、视频和序列输入 |
|
||
| `server/models/` | ONNX Session 与模型 Prediction |
|
||
| `server/geometry/` | 投影、网格和 Surface 数据转换 |
|
||
| `server/outputs/` | NPZ、EXR、PNG 与序列文件 |
|
||
| `model_catalog.py` | Blender UI 的模型声明与本地就绪检查 |
|
||
| `server/model_catalog.py` | Server 的模型下载与推理声明 |
|
||
|
||
调用方向从 Job 指向媒体、模型、几何和输出模块。模型层返回内存数据，输出层管理文件，Blender 数据始终由 Operator 的 Response 创建。
|
||
|
||
## Environment 与模型
|
||
|
||
Environment 使用 Python 3.12、ONNX Runtime、NumPy、Pillow、PyAV、trimesh、FastAPI 和 Uvicorn。Windows 使用 DirectML 或 CPU；其他平台根据支持情况使用 CoreML、OpenVINO 或 CPU。
|
||
|
||
Balloon 的 `analyze-balloon` Job 会裁切套索输入并清零选区外 RGBA。`Contour` 用 BEN2 回传最大连通轮廓；`Depth` 用 MoGe-2 对有效相机距离稳健拟合二维基面，并把物理距离换算为不受绝对拍摄距离影响、未截断的相对深度信号。Job 同时把 MoGe normal 转换为 tangent-space 纹理，铺回原图尺寸并以中性法线填充无效区域。Blender 主线程负责采样深度属性、创建 Base Plane Empty、组装 `O Balloon Shape` 修改器与 `O Balloon Layer` 材质。
|
||
|
||
Image Box 与 Lasso 的 `Refine Selection` 使用 `refine-image-mask` Job。它与标准 `remove-background` Job 共用单图 BEN2 函数；Server 在推理前清空 polygon 外的 RGBA，推理后再次应用几何 mask，并返回局部 Alpha 与源图 bounds。Line、Polyline 与 Perspective 不提交 Job。
|
||
|
||
所有 BEN2 调用都在公共模型入口用输入 Alpha 遮住透明 RGB。Remove Background、Depth Plane、Surface 与 Image Refine 的正式结果保留源 RGB，只采用 BEN2 Alpha；Balloon 同样只消费 BEN2 Alpha。该边界既防止模型识别透明区隐藏内容，也避免把透明黑写回 Blender 后产生过滤黑边。
|
||
|
||
正式功能支持：
|
||
|
||
- MoGe-2 ViT-S、ViT-B、ViT-L Normal
|
||
- DA3 Small、DA3 Base
|
||
- BEN2 Base
|
||
|
||
Debug 任务另外支持 Real-ESRGAN General x4v3；它只提供模型直通测试，不属于正式功能。
|
||
|
||
首次安装会下载 MoGe-2 ViT-S Normal 与 BEN2 Base。Real-ESRGAN General x4v3 由扩展偏好设置按需下载。模型保存在 `models/`，可由多个 Blender 版本共享。Server 缓存 BEN2、Real-ESRGAN 和最近使用的一个深度模型，以控制内存占用。
|
||
|
||
模型下载优先使用 Hugging Face，并以 OmooLab 镜像作为回退。AnyImage 用同一个准备 Operator 封装 BlendJob 安装任务，并按状态显示 `Set Up AI Environment…` 或 `Download Required Models…`；`Use Mirror` 属性只影响 Environment Bootstrap，不改变模型下载策略。Blender UI 通过同一个状态函数检查 Environment 指纹与默认模型文件：缺 Environment 时执行完整安装，只有默认模型缺失时仅提交补齐模型任务。
|
||
|
||
`debug-realesrgan-general-x4v3` 将每张输入的完整 RGB 动态尺寸张量直接送入 ONNX，并把 4× 返回保存为 `prediction*.png`。该 Job 不实现 tile、强度混合、Alpha 合成或 Blender 结果导入。
|
||
|
||
## 任务生命周期
|
||
|
||
Server 在第一次提交 Job 或手动 Start 时启动。任务进入单 Worker FIFO Queue，同一时间执行一个推理、下载或媒体任务。
|
||
|
||
Job 被接受时，Runtime 创建 opaque ID 和对应目录。进度保存在 Server 内存中，Blender 定期轮询状态。取消会在下载分块或一次 ONNX 调用结束后的检查点生效。
|
||
|
||
Blender 正常退出或禁用扩展时会停止所属 Server；Server 也监视父进程，在异常退出后自行结束。
|
||
|
||
Environment 安装发生在 Server 启动前，使用 `install.log` 记录过程。安装完成后的模型下载是普通 Job，与推理共享队列、进度和取消机制。
|
||
|
||
## DA3 多帧限制
|
||
|
||
DA3 ONNX 的联合注意力显存随帧数和分辨率快速增长。Depth Plane 动画采用逐帧推理并复用 Session，使峰值显存接近单帧任务；代价是各帧不共享相机位姿与深度尺度。
|
||
|
||
DA3 Debug 保留联合推理，用于检查模型原始多帧行为。Server 会在预计注意力张量过大时提前报错，此时应减少帧数或 Resolution Scale。
|