# 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。

Cutout 的 `generate-mesh` Job 会把套索或 BEN2 Alpha 收紧为裁切范围，同时分别写出未乘选区 Alpha 的 Color、几何 selection 与局部分析图。Cutout 和 Balloon 只在启用 Normal 时运行 MoGe-2；Depth Balloon 返回浮点深度分析，Depth Surface 返回深度场。Blender 主线程统一创建单面基础网格、计算 `o_balloon`、绑定内部深度图片并组装四个独立 Geometry Nodes；Cutout、Balloon 与 Depth Balloon 的 camera-axis normal 会在最终网格求值后烘成 tangent-space Image。

Depth Balloon 的基面拟合使用四轮稳健加权回归，并对细长选区中方差不足的短轴设置相对主轴的方差下限。该约束只处理病态方向，不会移除长轴上由多数有效深度点支持的趋势。Blender 会把回归平面的符号和半深度倍率转换到 Cutout 的局部 YZ 纸面坐标；Geometry Nodes 计算 `(Base Plane - 深度基值) × Depth Scale`，因此 `Depth Scale = 0` 会同时消除深度图和 Base Plane 对深度分支的影响。

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；Cutout 的 Refine Selection 同样只消费 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。