程序设计、开发与许可证

程序设计

SnapForm 分成 Blender 主进程与独立 Job Server 两侧。Blender 侧只负责界面、任务参数和 .blend 数据修改；模型下载、媒体准备、ONNX 推理和文件输出都在 Python 3.12 Environment 中运行。两侧由随扩展分发的 BlendJob wheel 连接，避免把 FastAPI、ONNX Runtime 等计算依赖载入 Blender Python。

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 共用的纯数据声明；server/model_download.py、server/model_manager.py 分别负责下载和 Session 生命周期
server/geometry.py 生成 NPZ、预览、点云和纹理网格；所有任务产物写入 Runtime 分配的 opaque-ID Job 目录

功能细节继续按主题维护：Depth Plane、Surface、输出格式和 Job Server。

项目结构

.
├── 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_manager.py
│       │   ├── moge2.py
│       │   ├── onnx_ben2.py
│       │   ├── onnx_da3.py
│       │   ├── onnx_moge2.py
│       │   └── onnx_runtime.py
│       └── wheels/
│           └── blendjob-0.1.6-py3-none-any.whl
├── tests/
└── tools/

常见命令

在项目根目录使用 Git 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.3.windows-x64.zip。从 PyPI 下载并更换 src/snapform/wheels/ 中随扩展分发的 wheel 后，先刷新锁文件再测试：

uv lock --refresh
uv run pytest

资产构建与验证

tools/ 脚本依赖 bpy，必须由 Blender 执行。设置本机 Blender 可执行文件后，可以重建或验证 O_SnapForm.blend：

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 下载前会在界面显示

4.9 KiB Raw Blame History Unescape Escape