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 provider；Apple M4 或更新芯片可选 MPS/CoreML，其他 Mac 只提供 CPU
5. 打开 3D 视图右侧的 SnapForm 面板：使用官方源点击 Install Environment，使用国内镜像点击 Install Environment (Mirror)

扩展不内置 uv 或 AI 运行库。首次使用会先下载并校验固定版本的 uv，随后自动安装轻量的 ONNX Runtime 环境，再下载 MoGe-2 ViT-S Normal 和 BEN2 Base；不安装 PyTorch，也不下载各模型的 Python 源码包。其他 AI 模型可在 Models panel 中按需下载，请保持网络畅通，首次安装需要一些时间。 Environment Bootstrap 使用连续的 0–100%：uv 为 1–20%、Python 为 20–50%、packages 为 50–98%，最终验证为 98–100%。三个阶段显示真实的 1/3、2/3、3/3，下载占各阶段的 84–87%；开始与最终验证不显示编号，单阶段状态不显示 1/1。官方按钮固定使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像按钮固定使用 CNB uv Release、CNB Python 解释器镜像和清华 PyPI，两种方式都不竞速或自动切换。MoGe-2 与 BEN2 属于 post-install，各自使用独立进度，不计入 Environment 的这轮 0–100%，其模型下载源逻辑不受按钮选择影响。 任一必需模型在两个来源都下载失败时，Install Environment 会明确报错；Environment 本身仍会保留。 选中 Image Empty 后，右键 SnapForm 子菜单会在缺少 MoGe-2 ViT-S Normal 或 BEN2 Base 时显示 Download Required Models，一次补齐缺失项，不会重复下载已经就绪的模型。 Environment 未安装时，同一位置显示两个安装按钮。Environment 或必需模型未就绪时， 菜单仍显示 Convert to Depth Plane、Convert to Surface 和 Remove Background，但三个入口都会保持禁用。 这些 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 删除背景
   • Shadeless 使用 O Shadeless 节点组显示不受场景灯光影响的贴图颜色
   • Keep Original 默认关闭，位于分割线下方；开启后保留源 Image Empty
4. 点击确认，稍等片刻就得到带位移的立体面片。O DA3 Depth Plane 与 O MoGe2 Depth Plane 都使用 .color 的 Alpha > 0.5 划分前景范围，范围外由 Background Depth 控制。

去除背景

选中 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。Server 通过统一的 Surface 输出流程构建 DA3 与 MoGe-2 源网格：MoGe-2 使用深度断层 mask，DA3 保留 confidence 与边拉伸 数据。两者再由独立的 Geometry Nodes 修改器完成剔面、快速重拓扑、Relax 与 UV 重投；顶层 Iterations 可设为 0。开启 Remove Background 时，BEN2 Alpha 只要大于 0 就视为前景；三角形三个顶点必须全部为前景，任一顶点 Alpha 为 0 都会删除该面并且不再交给 Geometry Nodes；Surface 材质使用 .color。匹配相机默认不创建；开启后会作为 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 加速；Apple M4 或更新芯片可使用 CoreML 的 MLProgram 模型格式，较早或无法识别的 Mac 只提供 CPU；provider 不可用时会回退到 ONNX Runtime CPU， 并在任务状态中显示实际 provider。

转换对话框提供模型与 Create Matching Camera、Remove Background、Shadeless；DA3 显示 Resolution Scale，MoGe-2 显示 Resolution Level， 以及分割线下方的 Keep Original。 界面会显示计算所得的实际 Process Res。剔除和重拓扑参数直接在 Geometry Nodes 修改器中调整；Shadeless 与 Depth Plane 共用 O Shadeless 材质节点组。颜色贴图始终使用统一的 .color 转换产物；Remove Background 只决定是否由 BEN2 修改 Alpha。颜色贴图会按当前场景的 View Transform 选择对应输入色彩空间：AgX、ACES 1.3、ACES 2.0、Filmic、Khronos PBR Neutral 分别使用 AgX Base sRGB、ACES 1.3 sRGB、ACES 2.0 sRGB、Filmic sRGB、Khronos PBR Neutral sRGB；无法匹配当前 View Transform 时回退 sRGB。普通材质的 Bump Scale 会在材质组内乘以 0.001，并按透视表面的深度空间缩放。Surface 与 Depth Plane 的 Layer Color 同时驱动 Principled BSDF 的 Base Color、Subsurface Radius 和 Emission Color，Layer Normal 同时驱动 Normal 与 Coat Normal；Subsurface、Emission、Coat 的其他设置保持默认。Surface attributes 统一使用 o_ 前缀；Server 准备过程显示 Preparing surface data n/6，可看到当前阶段与总步骤；Surface 与 Depth 单帧模型推理都不显示多余的 1/1。

视频与序列帧

SnapForm 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并生成逐帧对应的立体面片。.color 与 .depth 按源 Empty Image 的类型载入：普通单图为 IMAGE，Movie/Sequence 即使只处理一帧也仍为 SEQUENCE。处理范围默认 跟随 Empty 上设置的 Image Frames 与 Offset，不需要额外配置。DA3 的转换任务复用同一个 ONNX Session 逐帧推理，显存峰值不随视频帧数平方增长。Debug 只保存模型 API 的直接返回：DA3 多帧输入 保留联合推理，MoGe-2 与 BEN2 按各自的单图 API 逐帧保存。

任务结果保存在哪里

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

常见问题

• 从 0.12.0–0.12.5 升级到 0.12.6 或更高版本后，请重新执行一次 Install Environment，重建不再单独安装 BlendJob 的 Server Environment
• 首次使用需要下载模型，如果下载慢或失败，可在 Image Empty 的 SnapForm 右键菜单点击 Download Required Models，也可在 Models panel 里逐项重试
• 安装 Environment 时下载状态会显示平均速度；网络适合海外源时选择 Install Environment，国内网络选择 Install Environment (Mirror)。每个按钮固定使用对应来源，失败时不会自动切换
• 默认模型下载会在 Hugging Face 与 OmooLab 镜像之间自动回退；某一来源暂时断线不会阻止后续模型尝试另一来源
• 模型直链建连超过 10 秒，或连接后连续 60 秒没有收到数据，会切换到下一来源；不限制总下载时长
• 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image
• 动画面片不动：检查 Empty 的 Image Frames 是否大于 1，并确认播放场景帧

技术文档

Blender 侧只负责界面、任务提交与结果导入，AI 与文件输出由独立 Job Server 执行。详细功能见 文档索引，模块边界、调用流程、项目结构与开发命令见 程序设计、开发与许可证。CI 在 main push 与 Pull Request 上运行测试，仅由 v* tag 构建并发布扩展包；文档在 main 的文档相关文件变化时部署。