# Job Runtime 与 Server

AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧只准备输入、提交普通字典参数并导入结果；`server/` 不依赖 `bpy`。

## 目录职责

```text
src/anyimage/
├── runtime.py                 # Environment 与 JobRuntime 配置
└── server/
    ├── app.py                 # 公开 Job 注册
    ├── model_catalog.py       # 模型声明
    ├── model_download.py      # 下载与校验
    ├── model_manager.py       # 模型目录与 Session 生命周期
    ├── jobs/                  # 公开协议与流程编排
    ├── media/                 # 图片、视频、序列帧和尺寸处理
    ├── region/                # 通用 BEN2 Region 细化
    ├── geometry/              # Depth / Normal 文件产物与相机元数据
    ├── models/                # 模型适配与 ONNX 推理
    └── outputs/               # Debug Prediction 序列化
```

公开 Job 不互相导入实现。`jobs/` 只编排，稳定的原子能力放在对应领域目录中。

## 生命周期

```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()"]
```

Job 在阶段边界调用 `context.check_cancelled()`，并把稳定产物写入当前 Job 目录。Blender 响应完成后，再由输入所有者清理临时 Packed Image 文件。

## 公开 Job

| Job | 主要用途 |
| --- | --- |
| `download-model`、`download-required-models` | 准备模型文件 |
| `remove-background` | 生成 BEN2 透明前景 |
| `upscale-image` | 4× 图片或帧序列 |
| `refine-image-region` | 为 Image Box / Lasso 执行 Fit to Foreground |
| `generate-depth-plane-geometry` | 为 Depth Plane 复制颜色并生成 Z Depth 与相机元数据 |
| `generate-cutout-artifacts` | 按需执行 Fit to Foreground，并生成 Depth 或 Normal 文件产物 |
| `debug-*` | 保存模型适配层的直接输出 |

`generate-depth-plane-geometry` 对应 `jobs/depth_plane.py`；`generate-cutout-artifacts` 对应 `jobs/cutout.py`。共享的 MoGe-2 推理编排位于 `geometry/prediction_artifacts.py`，Depth EXR 与元数据写入位于 `geometry/depth_texture.py`，Normal 编码位于 `geometry/normal_texture.py`，Fit to Foreground 的通用实现位于 `region/refine_region.py`。

## 尺寸约束

`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map、Fit to Foreground 的模型分析图长边；不会降低材质颜色图分辨率。

Cutout 另有 Blender 侧的 **Maximum Cutout Mesh Resolution**。它限制所有 Cutout Shape 的网格采样密度，包括完全不使用 AI 的 Surface 与 Balloon。两个设置没有隐式绑定。

`generate-depth-plane-geometry` 与 `generate-cutout-artifacts` 只接受一帧，因此 Depth Plane 与 Cutout 是静态图工作流。Remove Background 与 Upscale 继续通过媒体入口处理单图、视频和序列帧。

## 模型边界

正式 Depth Plane、Cutout Depth 与 Normal Map 都只使用 MoGe-2。BEN2 用于 Remove Background 与 Fit to Foreground，Upscale 使用所选高清模型。DA3 只保留 `debug-da3` 及其 Debug 参数、模型下载与适配代码，不进入任何生产 Operator、Job 或自动回退。

`ModelManager` 按模型族管理下载目录与 ONNX Session，同一族只保留最近使用的模型和 Device，避免同类模型重复占用资源。

## Environment 与 Storage Root

`runtime.py` 声明独立 Python 3.12 环境和固定依赖。首次安装会准备默认 MoGe-2、BEN2 与 Real-ESRGAN WDN 模型。Storage Root 默认是 `~/.anyimage`：

```text
~/.anyimage/
├── .venv/
├── models/
├── jobs/
├── environment.json
├── manifest.json
├── install.log
└── server.log
```

切换 Storage Root 等同于切换整套 Environment、模型与任务数据，不自动迁移旧目录。

各 Job 的稳定产物见 [Job 产物](outputs.md)。