nan
835225d264
- Implemented surface generation functionality in `surface.py`, including geometry estimation and texture writing. - Introduced media input handling in `input.py`, supporting image and video frame extraction. - Added model management for geometry adapters in `models/__init__.py`. - Created BEN2 and DA3 model inference logic in `ben2.py` and `da3.py`, respectively. - Developed ONNX model inference utilities for BEN2 and DA3 in `onnx_ben2.py` and `onnx_da3.py`. - Added support for MoGe-2 model inference in `moge2.py` with necessary ONNX utilities. - Implemented output handling for depth and surface data in `depth.py` and `surface.py`. - Created debug output utilities for DA3 and MoGe-2 predictions in `debug_da3.py` and `debug_moge2.py`. - Enhanced ONNX runtime session management in `onnx_runtime.py`. - Updated `__init__.py` files to include new modules and functions for better organization.
144 lines
6.5 KiB
Markdown
144 lines
6.5 KiB
Markdown
# 程序设计、开发与许可证
|
||
|
||
## 程序设计
|
||
|
||
SnapForm 分成 Blender 主进程与独立 Job Server 两侧。Blender 侧只负责界面、任务参数和 `.blend` 数据修改；模型下载、媒体准备、ONNX 推理和文件输出都在 Python 3.12 Environment 中运行。两侧由随扩展分发的 BlendJob wheel 连接，避免把 FastAPI、ONNX Runtime 等计算依赖载入 Blender Python。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
User["Image Empty / Debug Panel"] --> Operator["Blender Operator"]
|
||
Operator --> Runtime["JobRuntime"]
|
||
Runtime --> Server["JobServer FIFO Queue"]
|
||
Server --> Handler["SnapForm Job Handler"]
|
||
Handler --> Model["ModelManager / ONNX"]
|
||
Handler --> JobFiles["Job Directory"]
|
||
JobFiles --> Response["Operator response"]
|
||
Response --> Scene["Blender Scene"]
|
||
```
|
||
|
||
核心边界如下：
|
||
|
||
- `src/snapform/__init__.py` 是注册入口，集中注册 Blender 类型、`Scene.snapform_settings`、右键菜单与 Runtime
|
||
- `panel.py`、`preferences.py`、`properties.py` 只描述 UI 和 Blender 属性，不直接导入 Server 模型实现
|
||
- `operators.py` 将 Blender 状态转换为普通字典参数；Job 完成后在主线程导入图片、网格、材质和相机
|
||
- `blender/depth_plane.py` 与 `blender/surface.py` 实现 Image Empty 输入检查、几何构建和资产挂载
|
||
- `job_runtime.py` 以入口字符串声明独立 Server，并配置 Environment、Storage Root 与首次安装后的推荐模型下载
|
||
- `server/__init__.py` 创建 `JobServer`、注册公开 Job，并把 `ModelManager` 注册为 Resource
|
||
- `server/jobs/` 按任务组织完整流程；DA3、MoGe-2、BEN2 Debug 各自拥有独立模块和 Job，不用模型分支总控函数
|
||
- `server/models/` 包含三个模型适配器及其 ONNX 实现，只负责模型载入、推理和 Prediction；不接收 Job Context、不写文件
|
||
- `server/geometry/` 包含投影、像素网格和唯一 Surface Builder，均为纯数据转换；不负责 Debug 或文件输出
|
||
- `server/outputs/` 只负责 Depth、Surface 与各模型 Debug 的序列化；Debug writer 原样保存 API 字段，不构建派生几何
|
||
- `server/media/input.py` 只处理图片、序列和视频输入；共享的可选前景流程保留在 `jobs/foreground.py`
|
||
- 根目录 `model_catalog.py` 供 Blender UI 与本地就绪检查使用；`server/model_catalog.py` 独立声明下载与推理所需模型，二者的模型键、目录名和 `ready_patterns` 由测试约束一致
|
||
- `server/__init__.py` 只注册 Job 与 Resource；`jobs/background.py`、`jobs/frames.py` 分别实现去背景和帧提取
|
||
- 所有任务产物写入 Runtime 分配的 opaque-ID Job 目录
|
||
|
||
功能细节继续按主题维护：[Depth Plane](depth-plane.md)、[Surface](surface.md)、[输出格式](outputs.md) 和 [Job Server](server.md)。
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
.
|
||
├── AGENTS.md
|
||
├── README.md
|
||
├── pack.py
|
||
├── sync_models.py
|
||
├── docs/
|
||
├── src/
|
||
│ └── snapform/
|
||
│ ├── __init__.py
|
||
│ ├── blender_manifest.toml
|
||
│ ├── job_runtime.py
|
||
│ ├── operators.py
|
||
│ ├── panel.py
|
||
│ ├── preferences.py
|
||
│ ├── properties.py
|
||
│ ├── assets/
|
||
│ │ └── O_SnapForm.blend
|
||
│ ├── blender/
|
||
│ │ ├── depth_plane.py
|
||
│ │ └── surface.py
|
||
│ ├── model_catalog.py
|
||
│ ├── server/
|
||
│ │ ├── __init__.py
|
||
│ │ ├── jobs/
|
||
│ │ │ ├── background.py
|
||
│ │ │ ├── debug_ben2.py
|
||
│ │ │ ├── debug_da3.py
|
||
│ │ │ ├── debug_moge2.py
|
||
│ │ │ ├── depth.py
|
||
│ │ │ ├── foreground.py
|
||
│ │ │ ├── frames.py
|
||
│ │ │ └── surface.py
|
||
│ │ ├── geometry/
|
||
│ │ │ ├── projection.py
|
||
│ │ │ ├── grid_mesh.py
|
||
│ │ │ └── surface.py
|
||
│ │ ├── media/
|
||
│ │ │ └── input.py
|
||
│ │ ├── model_download.py
|
||
│ │ ├── model_catalog.py
|
||
│ │ ├── model_manager.py
|
||
│ │ ├── models/
|
||
│ │ │ ├── ben2.py
|
||
│ │ │ ├── da3.py
|
||
│ │ │ ├── moge2.py
|
||
│ │ │ ├── onnx_ben2.py
|
||
│ │ │ ├── onnx_da3.py
|
||
│ │ │ ├── onnx_moge2.py
|
||
│ │ │ └── onnx_runtime.py
|
||
│ │ └── outputs/
|
||
│ │ ├── debug_da3.py
|
||
│ │ ├── debug_moge2.py
|
||
│ │ ├── depth.py
|
||
│ │ └── surface.py
|
||
│ └── wheels/
|
||
│ └── blendjob-0.1.13-py3-none-any.whl
|
||
├── tests/
|
||
└── tools/
|
||
```
|
||
|
||
## 常见命令
|
||
|
||
在项目根目录使用 Git Bash：
|
||
|
||
```bash
|
||
uv sync
|
||
uv run pytest
|
||
uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
|
||
uv run python pack.py
|
||
```
|
||
|
||
`pack.py` 根据 `blender_manifest.toml` 分别生成 Windows、macOS 和 Linux 扩展包，例如 `dist/SnapForm.v0.12.11.windows-x64.zip`。更换 `src/snapform/wheels/` 中随扩展分发的 wheel 后，先刷新锁文件再测试：
|
||
|
||
```bash
|
||
uv lock --refresh
|
||
uv run pytest
|
||
```
|
||
|
||
## 资产构建与验证
|
||
|
||
`tools/` 脚本依赖 `bpy`，必须由 Blender 执行。设置本机 Blender 可执行文件后，可以重建或验证 `O_SnapForm.blend`：
|
||
|
||
```bash
|
||
BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
|
||
|
||
"$BLENDER_BIN" --background --python tools/build_geometry_nodes_asset.py
|
||
"$BLENDER_BIN" --background --python tools/validate_depth_plane_asset.py
|
||
"$BLENDER_BIN" --background --python tools/validate_geometry_nodes_asset.py
|
||
"$BLENDER_BIN" --background --python tools/validate_moge_depth_plane.py
|
||
"$BLENDER_BIN" --background --python tools/validate_moge_surface.py
|
||
```
|
||
|
||
验证脚本会自动把 `src/snapform/wheels/` 中的 BlendJob wheel 加入 Blender Python 路径，因此可在
|
||
`--factory-startup` 的干净环境中直接运行。
|
||
|
||
只改 Python、文档或打包逻辑时不需要重建 `.blend` 资产；修改节点组、材质组或其接口时，应运行相应资产验证脚本，并再次运行完整测试。
|
||
|
||
## 上游与许可证
|
||
|
||
- Depth Anything 3 代码采用 Apache 2.0
|
||
- BEN2 ONNX 模型采用其仓库声明的 Apache 2.0 License
|
||
- SnapForm Extension 代码采用 GPL-3.0-or-later
|
||
- 模型权重许可证由所选 Hugging Face 模型仓库决定，Extension 下载前会在界面显示
|