AnyImage/README.md

SnapForm

SnapForm 是一个 Blender 扩展，可以把一张照片、一段视频或一组序列帧快速变成有真实深度的立体面片。

它能做什么

• 一键把 Image Empty 转换为立体面片：让 AI 估算深度，或直接用原图作为深度
• 把单张 Image Empty 转换为透视纹理网格，并自动匹配原对象的 Transform 与 Offset
• 一键去除图片背景，生成透明前景图
• 支持视频与序列帧输入，逐帧处理，动画也能得到逐帧对应的立体面片
• 全部操作都在右键菜单里完成，不需要写任何代码

安装

1. 下载对应系统的扩展压缩包
2. 打开 Blender，进入 Preferences > Extensions
3. 点击 Install from Disk，选择下载的压缩包
4. 在扩展偏好设置中确认 Storage Root 与 Device（保持默认即可）；Device 默认取本机 最快的 DirectML/CoreML provider，否则 CPU。下载超时会自动重试国内镜像，无需手动配置
5. 打开 3D 视图右侧的 SnapForm 面板，点击 Install Environment

扩展不内置 uv 或 AI 运行库。首次使用会先下载并校验固定版本的 uv，随后自动安装轻量的 ONNX Runtime 环境，再下载 MoGe-2 ViT-S Normal 和 BEN2 Base；不安装 PyTorch，也不下载各模型的 Python 源码包。其他 AI 模型可在 Models panel 中按需下载，请保持网络畅通，首次安装需要一些时间。 安装时 Environment、MoGe-2 和 BEN2 各自使用独立的 0–100% 进度；Environment 这一轮内部依次完成 uv、Python 环境和 packages。进入后续模型时进度归零，但不显示 2/2 等阶段编号。模型源发生瞬时错误时会切换到另一来源继续下载。 任一必需模型在两个来源都下载失败时，Install Environment 会明确报错；Environment 本身仍会保留。 选中 Image Empty 后，右键 SnapForm 子菜单会在缺少 MoGe-2 ViT-S Normal 或 BEN2 Base 时显示 Download Required Models，一次补齐缺失项，不会重复下载已经就绪的模型。 必需模型补齐前，菜单中的 Convert to Depth Plane 会保持禁用。 这些 UI 状态直接检查 Storage Root 的 models/ 文件，不会仅因打开菜单或面板而启动 Job Server。

快速上手

转换为立体面片

1. 在 3D 视图中选中一个 Image Empty（空物体，显示方式为 Image）
2. 右键打开 SnapForm 子菜单，选择 Convert to Depth Plane
3. 在对话框中选择：
   • Depth from：Original 直接用原图，DA3 使用现有 DA3 流程，MoGe-2 生成 metric depth、normal 与有效区域 mask
   • Resolution Scale 使用 1–100%，按原图长边计算 Process Res；结果会限制在 252–1008 并自动对齐到 14 的倍数
   • Remove Background 默认关闭；开启后在转换期间使用 BEN2 删除背景
   • Unshaded 保留为直接显示贴图颜色的选项
   • Keep Original 默认关闭，位于分割线下方；开启后保留源 Image Empty
4. 点击确认，稍等片刻就得到带位移的立体面片

去除背景

选中 Image Empty 后，右键打开 SnapForm 子菜单并选择 Remove Background，完成后 Empty 会自动 换成透明前景图。该操作在子菜单中使用独立分割区域。

转换为透视网格

选中单张图片的 Image Empty，右键打开 SnapForm 子菜单并选择 Convert to Surface。可选择 MoGe-2 ViT-S、ViT-B、ViT-L 或 DA3 Small、Base，其中 MoGe-2 ViT-S 为默认模型。SnapForm 会按模型输出的 相机内参与三维点建立透视网格，并匹配原 Empty 的可见尺寸、Offset 与 Transform。MoGe-2 使用内置 NumPy 网格构建与深度断层 mask 生成干净拓扑；DA3 保留 confidence 与边拉伸剔除。两者再由独立的 Geometry Nodes 修改器完成剔面、快速重拓扑、Relax 与 UV 重投。开启 Remove Background 时，背景三角面会在转换期间 直接删除，不再交给 Geometry Nodes。匹配相机默认不创建；开启后会作为 Surface 的子级。 MoGe-2 的像素级 normal 会作为 Object Space normal 贴图接入 O MoGe2 Surface Layer，并与原图 Bump 合并；网格本身不写入 custom normal，因此重拓扑降低顶点数后仍能保留细腻的法线细节。 当前此功能仅支持单张图片。

MoGe-2 ViT-S、ViT-B、ViT-L、DA3 Small、DA3 Base 与 BEN2 全部使用 ONNX。模型执行、相机与深度恢复、 点云重投影和网格生成均不依赖 PyTorch。Windows 使用 DirectML 加速，provider 不可用时会回退到 ONNX Runtime CPU， 并在任务状态中显示实际 provider。

转换对话框提供模型与 Create Matching Camera、Remove Background、Unshaded；DA3 显示 Resolution Scale，MoGe-2 显示 Resolution Level， 以及分割线下方的 Keep Original。 界面会显示计算所得的实际 Process Res。剔除和重拓扑参数直接在 Geometry Nodes 修改器中调整；Unshaded 可使用与 Depth Plane 相同的 Emission 材质。普通材质的 Bump Scale 会在材质组内乘以 0.001，并按透视表面的深度空间缩放。Surface attributes 统一使用 o_ 前缀；Server 准备过程显示 Preparing surface data n/6，可看到当前阶段与总步骤。

视频与序列帧

SnapForm 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并生成逐帧对应的立体面片。处理范围默认 跟随 Empty 上设置的 Image Frames 与 Offset，不需要额外配置。DA3 的转换任务复用同一个 ONNX Session 逐帧推理，显存峰值不随视频帧数平方增长；Debug 多帧输出仍使用多视图联合推理。

任务结果保存在哪里

任务结果保存在 Runtime Storage Root 的 jobs/ 下，默认是 ~/.snapform/jobs/。Job Server 接受任务时自动生成 opaque Job ID，并创建同名文件夹；Blender 不预先申请 ID 或目录。Packed Image 和序列帧的临时输入由 Blender 在任务结束后清理，Server 产物直接写入该 Job 目录。视频或序列帧生成的面片会引用其中的序列帧，请保留对应文件夹，不要随意删除。

常见问题

• 从 0.12.0–0.12.2 升级到 0.12.3 后，请重新执行一次 Install Environment，让 Storage Root 中的 Environment 安装修复后的 BlendJob wheel
• 首次使用需要下载模型，如果下载慢或失败，可在 Image Empty 的 SnapForm 右键菜单点击 Download Required Models，也可在 Models panel 里逐项重试
• 安装 Environment 时 uv 下载失败会自动尝试 OmooLab 镜像；Python packages 需要指定镜像时设置 UV_INDEX_URL 后重新安装
• 默认模型下载会在 Hugging Face 与 OmooLab 镜像之间自动回退；某一来源暂时断线不会阻止后续模型尝试另一来源
• 模型直链建连超过 10 秒，或连接后连续 60 秒没有收到数据，会切换到下一来源；不限制总下载时长
• 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image
• 动画面片不动：检查 Empty 的 Image Frames 是否大于 1，并确认播放场景帧

技术文档

Blender 侧只负责界面、任务提交与结果导入，AI 与文件输出由独立 Job Server 执行。详细功能见 文档索引，模块边界、调用流程、项目结构与开发命令见 程序设计、开发与许可证。