117 lines
4.9 KiB
Markdown
117 lines
4.9 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/media.py`、`background.py`、`da3.py`、`moge2.py` 负责业务流程；`onnx_*.py` 只处理模型输入、推理和输出恢复
|
||
- 根目录 `model_catalog.py` 供 Blender UI 与本地就绪检查使用；`server/model_catalog.py` 独立声明下载与推理所需模型，二者的模型键、目录名和 `ready_patterns` 由测试约束一致
|
||
- `server/geometry.py` 生成 NPZ、预览、点云和纹理网格；所有任务产物写入 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
|
||
│ │ ├── background.py
|
||
│ │ ├── da3.py
|
||
│ │ ├── geometry.py
|
||
│ │ ├── media.py
|
||
│ │ ├── model_download.py
|
||
│ │ ├── model_catalog.py
|
||
│ │ ├── model_manager.py
|
||
│ │ ├── moge2.py
|
||
│ │ ├── onnx_ben2.py
|
||
│ │ ├── onnx_da3.py
|
||
│ │ ├── onnx_moge2.py
|
||
│ │ └── onnx_runtime.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
|
||
```
|
||
|
||
只改 Python、文档或打包逻辑时不需要重建 `.blend` 资产；修改节点组、材质组或其接口时，应运行相应资产验证脚本，并再次运行完整测试。
|
||
|
||
## 上游与许可证
|
||
|
||
- Depth Anything 3 代码采用 Apache 2.0
|
||
- BEN2 ONNX 模型采用其仓库声明的 Apache 2.0 License
|
||
- SnapForm Extension 代码采用 GPL-3.0-or-later
|
||
- 模型权重许可证由所选 Hugging Face 模型仓库决定，Extension 下载前会在界面显示
|