nan
b5a2f9690c
- Added depth.py for MoGe-2 depth sampling and balloon deformation functionality. - Introduced validate_balloon_asset.py to validate balloon shape modifiers and material properties in Blender. - Enhanced test_server.py with new unit tests for balloon depth analysis and job progress tracking. - Updated existing tests to improve code clarity and maintainability.
87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# Job Server
|
||
|
||
SnapForm 把 AI 与媒体处理放在独立 Job Server 中运行，使 Blender Python 保持轻量。安装和使用问题见[安装与首次配置](installation.md)与[常见问题](faq.md)。
|
||
|
||
## 架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
Blender["Blender Operator"] --> Runtime["JobRuntime"]
|
||
Runtime --> Queue["FIFO Queue"]
|
||
Queue --> Job["SnapForm 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、队列、状态和取消协议。SnapForm 的 Operator 负责业务参数，Server Job 负责工作流编排，结果由 Operator 在 Blender 主线程中导入。
|
||
|
||
## Storage Root
|
||
|
||
默认位置为 `~/.snapform`：
|
||
|
||
```text
|
||
~/.snapform/
|
||
├── .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` 材质。
|
||
|
||
正式功能支持：
|
||
|
||
- MoGe-2 ViT-S、ViT-B、ViT-L Normal
|
||
- DA3 Small、DA3 Base
|
||
- BEN2 Base
|
||
|
||
首次安装会下载 MoGe-2 ViT-S Normal 与 BEN2 Base。模型保存在 `models/`，可由多个 Blender 版本共享。Server 缓存 BEN2 和最近使用的一个深度模型，以控制内存占用。
|
||
|
||
模型下载优先使用 Hugging Face，并以 OmooLab 镜像作为回退。Environment 安装则提供官方源和镜像源两个明确入口；它们只影响 Environment Bootstrap，不改变模型下载策略。
|
||
|
||
## 任务生命周期
|
||
|
||
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。
|