nan
92d2cea1d1
- Implement tests for ben2 and da3 model caching to ensure models are reused for matching runtime keys. - Verify service state management, including client registration, job cancellation, and client expiration. - Test discovery file creation and removal based on service ownership. - Ensure frame extraction functionality works without models and produces expected results.
SnapForm
SnapForm 是一个 Blender 扩展，可以把一张照片、一段视频或一组序列帧快速变成有真实深度的立体面片。
它能做什么
- 一键把 Image Empty 转换为立体面片：让 AI 估算深度，或直接用原图作为深度
- 把单张 Image Empty 转换为透视纹理网格，并自动匹配原对象的 Transform 与 Offset
- 一键去除图片背景，生成透明前景图
- 支持视频与序列帧输入，逐帧处理，动画也能得到逐帧对应的立体面片
- 全部操作都在右键菜单里完成，不需要写任何代码
安装
- 下载对应系统的扩展压缩包
- 打开 Blender，进入
Preferences > Extensions - 点击
Install from Disk，选择下载的压缩包 - 在扩展偏好设置中确认 Storage Root 与 Device（保持默认即可）；Device 默认取本机 最快的 CUDA/MPS，否则 CPU。下载超时会自动重试国内镜像，无需手动配置
- 打开 3D 视图右侧的
SnapForm面板，点击Install Environment
DA3、BEN2 源码包和 uv 已内置在扩展里，安装时直接从本地解包，不需要访问 GitHub。首次使用仍会自动
下载运行环境依赖（PyTorch 等），随后自动下载 DA3 Small 和 BEN2 Base。其他 AI 模型可在
Models panel 中按需下载，请保持网络畅通，首次安装需要一些时间。
快速上手
转换为立体面片
- 在 3D 视图中选中一个 Image Empty（空物体，显示方式为 Image）
- 右键打开
SnapForm子菜单，选择Convert to Depth Plane - 在对话框中选择：
Depth from：Original直接用原图，AI Generated让 AI 估算深度Resolution Scale使用1–100%，按原图长边计算 Process Res；结果会限制在252–1008并自动对齐到 14 的倍数Remove Background默认关闭；开启后在转换期间使用 BEN2 删除背景Unshaded保留为直接显示贴图颜色的选项Keep Original默认关闭，位于分割线下方；开启后保留源 Image Empty
- 点击确认，稍等片刻就得到带位移的立体面片
去除背景
选中 Image Empty 后，右键打开 SnapForm 子菜单并选择 Remove Background，完成后 Empty 会自动
换成透明前景图。该操作在子菜单中使用独立分割区域。
转换为透视网格
选中单张图片的 Image Empty，右键打开 SnapForm 子菜单并选择 Convert to Surface。SnapForm 会按 DA3
相机内参与深度逐像素反投影，并把生成网格匹配到原 Empty 的可见尺寸、Offset 与 Transform。DA3
confidence 与边拉伸结果会保存为 Surface attributes，再由一个可复用的 Geometry Nodes
修改器完成剔面、快速重拓扑、Relax 与 UV 重投。开启 Remove Background 时，背景三角面会在转换期间
直接删除，不再交给 Geometry Nodes。匹配相机默认不创建；开启后会作为 Surface 的子级。
当前此功能仅支持单张图片。
转换对话框提供模型与 Resolution Scale、Create Matching Camera、Remove Background、Unshaded，
以及分割线下方的 Keep Original。
界面会显示计算所得的实际 Process Res。剔除和重拓扑参数直接在
Geometry Nodes 修改器中调整；Unshaded 可使用与 Depth Plane 相同的 Emission 材质。普通材质的
Bump Scale 会在材质组内乘以 0.001，并按透视表面的深度空间缩放。Surface attributes 统一使用 o_ 前缀；Service 准备过程显示
Preparing surface data n/6，可看到当前阶段与总步骤。
视频与序列帧
SnapForm 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并生成逐帧对应的立体面片。处理范围默认
跟随 Empty 上设置的 Image Frames 与 Offset，不需要额外配置。
任务结果保存在哪里
任务结果保存在 ~/.snapform/jobs/ 下，每个任务一个文件夹，名称统一为
动作-对象_日期-时间-微秒。Packed Image 和序列帧的输入副本会直接归档到对应任务根目录，
不再使用公共 inputs/ 文件夹；导出产物也尽量平铺。视频或序列帧生成的面片会引用任务文件夹里的
序列帧，请保留对应文件夹，不要随意删除。
常见问题
- 首次使用需要下载模型，如果下载慢或失败，稍后在
Modelspanel 里重试即可 - 安装 Environment 时提示下载超时：新版会自动探测并切换到镜像、失败时自动重试一次；如果仍然
超时，在扩展偏好设置的
PyPI Index中填入镜像地址（如清华）后重新安装即可 - 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image
- 动画面片不动：检查 Empty 的
Image Frames是否大于 1，并确认播放场景帧
技术文档
面向开发者的技术内容见 docs/technical.md。