nan
6c8358f92f
- Updated the naming convention for upscaled images to include underscores and file extensions. - Renamed properties related to cutout pixel size to point spacing for clarity. - Adjusted alpha region calculations to use a half-alpha threshold for better accuracy. - Enhanced the handling of foreground mesh masks to consider half-alpha values. - Introduced new functions for unbounded selections and cutout images, ensuring proper handling of source and selection images. - Improved test coverage for cutout functionalities, including bounds mapping and alpha preservation. - Updated tests to reflect changes in naming conventions and functionality adjustments.
99 lines
6.7 KiB
Markdown
99 lines
6.7 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/ 任务产物与 job.log
|
||
├── environment.json 环境声明
|
||
├── manifest.json 已安装环境指纹
|
||
├── install.log 安装日志
|
||
└── server.log 带 Job ID 的任务主线与 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 与序列文件 |
|
||
| `server/model_catalog.py` | Blender UI 与 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 铺回原图尺寸，并以中性法线填充无效区域。Blender 主线程负责采样深度属性、创建 Base Plane Empty、组装 `O Balloon Shape` 修改器，再根据最终评估网格的 TBN 把相机轴 normal 烘成 tangent-space Image 并接入统一的 `O Image Layer` 材质。
|
||
|
||
Cutout 的 `generate-mesh` 不复用上述裁切图作为 AI 输入。套索或 BEN2 结果仅写成几何 mask；MoGe 深度与法线始终分析完整图片。输入为 Upscale 结果时，请求会额外携带放大前的 `analysis_input`，推理读取该输入，颜色与几何 mask 仍读取当前高清图；Depth Balloon 会先把套索坐标缩放到分析分辨率，再限制有效深度。Blender 材质使用当前 Empty Image 的未裁切副本。
|
||
|
||
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
|
||
- Real-ESRGAN General WDN x4v3、SAFMN Real x4、Real-ESRGAN x4plus
|
||
|
||
Upscale 使用上述三档 4× RGB 模型。正式 `upscale-image` Job 把结果写成 `upscale.0001.png` 起的序列并回写为 `_upscale.png` Image 数据块；对应 Debug Job 保留模型直通输出，便于横向比较。
|
||
|
||
首次安装会下载 MoGe-2 ViT-S Normal、BEN2 Base 与默认的 Real-ESRGAN General WDN x4v3。SAFMN Real x4 和 Real-ESRGAN x4plus 可在扩展偏好设置按需下载。模型保存在 `models/`，可由多个 Blender 版本共享。Server 会复用连续任务所需的同一 Session；切换模型族时释放旧 Session，推理资源异常时立即卸载当前高清 Session。
|
||
|
||
模型按目录声明的 Hugging Face 仓库下载，并以 OmooLab 镜像作为回退；未声明 Hugging Face 仓库的模型直接使用镜像。AnyImage 用同一个准备 Operator 封装 BlendJob 安装任务，并按状态显示 `Set Up AI Environment…` 或 `Download Required Models…`。
|
||
|
||
`upscale-image` 与 `debug-upscale` 共用模型推理。三个模型在模型层分块处理任意宽高输入；正式 Job 还应用输出上限、保留 Alpha 并导入 Blender。
|
||
|
||
## 任务生命周期
|
||
|
||
Server 在第一次提交 Job 或手动 Start 时启动。任务进入单 Worker FIFO Queue，同一时间执行一个推理、下载或媒体任务。
|
||
|
||
Job 被接受时，Runtime 创建 opaque ID 和对应目录。进度保存在 Server 内存中，Blender 定期轮询状态。取消会在下载分块或一次 ONNX 调用结束后的检查点生效。
|
||
|
||
`server.log` 记录带时间、Job ID 与 Job Type 的排队、开始、成功、取消和失败主线，以及 Server 自身异常。Handler 细节与完整 traceback 写入对应 `jobs/<job-id>/job.log`，因此可先从主线定位 Job ID，再查看单个任务。
|
||
|
||
Blender 正常退出或禁用扩展时会停止所属 Server；Server 也监视父进程，在异常退出后自行结束。
|
||
|
||
Environment 安装发生在 Server 启动前，使用 `install.log` 记录过程。安装完成后的模型下载是普通 Job，与推理共享队列、进度和取消机制。
|
||
|
||
## DA3 多帧限制
|
||
|
||
DA3 ONNX 的联合注意力显存随帧数和分辨率快速增长。Depth Plane 动画采用逐帧推理并复用 Session，使峰值显存接近单帧任务；代价是各帧不共享相机位姿与深度尺度。
|
||
|
||
DA3 Debug 保留联合推理，用于检查模型原始多帧行为。Server 会在预计注意力张量过大时提前报错，此时应减少帧数或 Resolution Scale。
|