107 lines
10 KiB
Markdown
107 lines
10 KiB
Markdown
# 功能与使用
|
||
|
||
本文档面向开发者和需要了解内部实现细节的用户，从原 README 迁移而来。普通用户请阅读项目根目录的
|
||
`README.md`。
|
||
|
||
`SnapForm` 是一套从图片快速构建空间结构的 Blender Extension。目前以
|
||
[Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
|
||
作为首个 AI 能力，在独立 Environment 中运行 DA3，可将模型 API Prediction 保存在独立 job 目录，
|
||
也可把 Image Empty 转换成带几何与材质置换的立体面片。MoGe-2 作为独立深度来源，保留其 metric depth、normal、mask 与 intrinsics 输出，不复用 DA3 Prediction 后处理。Debug 面板还可运行
|
||
[BEN2](https://github.com/PramaLLC/BEN2) 背景剔除功能测试。
|
||
|
||
## 当前功能
|
||
|
||
- 使用 Blender Extension manifest，可通过 `Install from Disk` 安装
|
||
- 在独立 Environment 中通过常驻 Server 运行 ONNX Runtime；MoGe-2、DA3 与 BEN2 的模型执行及后处理完全不使用 PyTorch，避免污染 Blender Python 进程
|
||
- Server 的深度模型缓存只保留 DA3 或 MoGe-2 其中一个，切换时主动释放前一个；BEN2 使用独立缓存，
|
||
可与当前深度模型共存
|
||
- Blender 使用内置 `urllib.request` 访问仅监听 `127.0.0.1` 的 Server；连接由随机端口与 Instance ID 归属当前 Runtime
|
||
- 常驻 Server 复用 ONNX Runtime session、BEN2 与最近使用的深度模型，连续执行时不再重复加载
|
||
- 每个 Blender 实例持有自己的 Job Server；`Job Server` 面板显示状态与模型缓存，并提供安装、启动、清理、重启和停止控制
|
||
- Environment、模型和任务结果默认保存在 `~/.snapform`，可由多个 Blender 版本共享
|
||
- 当前仅启用 FP32 DA3 Small 和 Base；它们不随首次安装下载，Giant 1.1 与 Nested Giant Large 1.1 暂停使用
|
||
- 支持 BEN2 Base 单图背景剔除测试，输出透明 PNG 与推理耗时
|
||
- 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
|
||
- 视频按顺序截取前若干帧，可设置参与重建的最大帧数
|
||
- `Models` panel 默认折叠，展开后可逐项查看和下载所有可用模型
|
||
- Environment 已安装时不额外占用面板空间；模型列表每个模型只占一行
|
||
- `Debug` 默认折叠，内部的 `DA3`、`MoGe-2` 与 `BEN2` 也分别默认折叠
|
||
- DA3、MoGe-2 与 BEN2 分别使用独立 Debug Job，直接保存各自 API 返回，不共享按模型分支的总控函数
|
||
- DA3 Debug 保存 Prediction NPZ；MoGe-2 Debug 保存逐帧原始预测 NPZ；BEN2 Debug 保存直接返回的透明前景
|
||
- Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
|
||
`(Missing)`，已下载模型保持原名
|
||
- Debug 不运行点云、Surface、深度预览、置信度 percentile 或坐标变换等 SnapForm 后处理
|
||
- Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
|
||
- Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
|
||
- 缺少必需的 `MoGe-2 ViT-S Normal` 或 `BEN2 Base` 时，Image Empty 的 `SnapForm`
|
||
右键子菜单显示 `Download Required Models`；单次任务只下载缺失项，并在补齐前禁用
|
||
`Convert to Depth Plane`、`Convert to Surface` 和 `Remove Background`。Environment 未安装时，
|
||
同一位置改为显示 `Install Environment` 与 `Install Environment (Mirror)`，三个禁用的功能入口仍然可见
|
||
- 菜单、模型面板和转换对话框直接检查 Storage Root 的 `models/` 必需文件，显示模型状态时不会启动 Job Server
|
||
- Image Empty 支持视频与序列帧输入：`Convert to Depth Plane` 逐帧估计深度，
|
||
`Remove Background` 逐帧抠图，入口保持不变。DA3 转换时每帧独立执行 ONNX 推理并复用模型 Session；
|
||
DA3 Debug 多帧任务继续联合推理；MoGe-2 与 BEN2 Debug 按单图 API 逐帧运行
|
||
- 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）；
|
||
Geometry Nodes 与材质 Image Texture 均可按场景帧播放序列帧
|
||
- 使用浮点深度贴图、`O DA3 Depth Plane` Geometry Nodes 和原图 Bump 构建立体面片
|
||
- 转换对话框选择推理模式、处理分辨率与背景移除；细分和置换方式在 Geometry Nodes 修改器中调整
|
||
- Debug 的 DA3 输出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不修改当前场景
|
||
- Debug 完整保留模型 API 返回的数组字段，不混入 SnapForm 派生几何
|
||
- 安装和模型下载使用后台子进程；推理提交给常驻 Server，状态栏实时显示阶段、百分比进度条与取消按钮
|
||
- 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复
|
||
|
||
## 使用
|
||
|
||
1. 运行 `uv run python pack.py`，分别构建 `windows-x64`、`macos-arm64`、
|
||
`linux-x64` 三个平台的 Extension ZIP（如 `SnapForm.v0.12.13.macos-arm64.zip`）。
|
||
安装包不携带 uv 或 AI 项目源码；首次安装 Environment 时下载固定版本 uv，并校验固定 SHA-256。官方安装按钮使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像按钮使用 CNB uv Release、CNB Python 解释器镜像和清华 PyPI。
|
||
2. 在 Blender 的 `Preferences > Extensions` 中选择 `Install from Disk`。
|
||
3. 在 Extension Preferences 中确认 Storage Root 与 Device。Device 是正式功能
|
||
（Image Empty 右键菜单）使用的推理设备，默认取本机最快的 DirectML/CoreML provider，否则 CPU，且只列出
|
||
本机支持的设备。
|
||
4. 在 `Job Server` 选择 `Install Environment` 或 `Install Environment (Mirror)`。首次安装会下载 Python、ONNX Runtime、FastAPI、Uvicorn；
|
||
uv 由 Job Runtime 的 Environment 安装器下载并校验，DA3、BEN2 与 MoGe 不安装源码包，
|
||
并在 Environment 安装后自动下载 `MoGe-2 ViT-S Normal` 和 FP16 `BEN2 Base` 推荐模型。首次安装
|
||
Environment Bootstrap 的 0–100% 只包含 uv、Python 与 packages：三阶段显示 `1/3`、`2/3`、`3/3`，范围分别为 1–20%、20–50%、50–98%，最终验证使用 98–100%。下载占各阶段的 84–87%；开始与验证不显示编号，单阶段状态不显示 `1/1`。
|
||
两个默认模型由普通的 `post_install(runtime)` 发起正式 Server Job。
|
||
安装完成后直接写入 Environment Manifest，不再额外导入全部组件进行验证；`DA3 Base` 等其他模型可稍后在 `Models` 面板按需下载。
|
||
Environment packages 使用固定的 Resolving、Downloading 与 Installing 状态，原始 uv 输出写入 `install.log`。模型下载显示速度，例如
|
||
`Downloading DA3 Small 14.2 MB/s`；镜像来源显示为
|
||
`Downloading DA3 Small (mirror) 14.2 MB/s`。下载按字节连续推进，重试或切换镜像时进度不会倒退。
|
||
Environment 安装阶段与 `Models` 面板单独下载使用相同的模型名称格式，不会改写为通用的 `Downloading packages`。
|
||
Environment 安装后即使模型下载中断也仍会保留，但 `Install Environment` 会以失败结束并显示模型下载错误。
|
||
可稍后在 Image Empty 的 `SnapForm` 右键菜单用 `Download Required Models` 一次补齐缺失的
|
||
MoGe-2 ViT-S 与 BEN2，也可在 `Models` 面板单独补下。
|
||
安装不做启动网络预检；每个模型都先尝试 Hugging Face，失败后尝试 OmooLab R2，两者都失败时当前 Job 失败。
|
||
官方安装固定使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像安装固定使用 CNB uv Release、`python-build-standalone` 镜像和清华 PyPI。两种方式都不测速、不竞速、不自动切换，镜像配置只注入当前安装子进程。模型仍按自身的 Hugging Face 与 OmooLab R2 逻辑下载。
|
||
5. 在 3D View 按 `N`，打开 `SnapForm` 页签。
|
||
6. 如需其他模型，展开 `Models` panel，找到模型并点击该行的 `Download`。
|
||
7. 展开默认收起的 `Debug`，在 DA3、MoGe-2 或 BEN2 区域选择模型与输入，然后直接运行对应 API。
|
||
8. 选择一张图片或一个视频文件。视频可设置从头截取的帧数，然后点击 `Generate Output`。
|
||
9. 测试背景剔除时，确认 `Models` panel 中的 `BEN2 Base` 已就绪，然后在 `Debug` 的
|
||
`BEN2` 区域选择单张图片并点击 `Remove Background`。
|
||
完成后会打开 job 文件夹，其中的 `foreground.png` 带透明 Alpha；状态栏显示
|
||
BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。
|
||
|
||
## Image Empty 去背景
|
||
|
||
1. 确认 `Models` panel 中的 `BEN2 Base` 已就绪；首次安装 Environment 时会默认下载。
|
||
2. 在 3D View 选中 Image Empty，右键打开 `SnapForm` 子菜单并选择 `Remove Background`。
|
||
3. 完成后以 Fake User 保留原 Image datablock，新建并 Pack 一张透明 PNG 到当前 `.blend`，然后只把
|
||
当前 Empty 的 `data` 换成新图；Empty 的 Transform、显示尺寸、Offset 及其他设置保持不变。
|
||
4. 新 Image 使用原图去掉格式后再追加 `.color` 的名称。例如 `img.png` 生成
|
||
`img.color`，`img.png.001` 生成 `img.001.color`。已有同名 datablock 时由
|
||
Blender 自动追加编号。
|
||
|
||
原图已 Pack 时会先写出临时 PNG 交给 BEN2，任务结束后删除临时输入；原 Image 仍保持 Pack
|
||
状态和原始内容。正式任务的 `color.0001.png` 也会保留在对应 job 目录中。
|
||
|
||
Image Empty 引用视频或序列帧时，Remove Background 直接执行，默认取 Empty 的 Image Frames
|
||
数值（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset；若 Offset 加 Frames 超出视频长度，
|
||
会把窗口整体收进视频内（保证实际处理 Frames 帧数），Offset 过小时从第 1 帧开始。输出
|
||
`color.0001.png` 等透明序列帧（帧号从 0001 开始，与 Blender 场景帧一一对应），并把
|
||
关闭去背景时，原始颜色帧同样以 `color.0001.*` 起始的统一名称写入 job 目录。替换 Empty 的 Image 为
|
||
加载这些帧的 SEQUENCE Image，从原 Empty 的 Start 位置开始播放（Start 原样保留）。图片类型只取决于源 Empty：普通单图的单个 `color.0001.*` 仍作为 `IMAGE`，Movie/Sequence 即使只导出一帧也作为 `SEQUENCE`；`.depth` 同样遵循该规则。
|
||
Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因此保持外部引用 job 目录；
|
||
请保留对应 job 目录，否则序列会失效。
|