nan
b3a07cde32
- Implement JobClient for handling HTTP requests to the JobServer. - Create ModalJobOperatorBase for managing Blender job lifecycle. - Introduce JobContext and JobServer for job management and state handling. - Add ServiceConnection and ServiceController for managing service processes. - Implement job submission, cancellation, and resource management endpoints in the server. - Ensure proper error handling and job state updates throughout the service.
94 lines
6.5 KiB
Markdown
94 lines
6.5 KiB
Markdown
# 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 中按需下载，请保持网络畅通，首次安装需要一些时间。
|
||
安装时 uv、ONNX Environment、MoGe-2 和 BEN2 各自使用独立的 0–100% 进度；下载阶段显示速度与连续字节进度。
|
||
|
||
## 快速上手
|
||
|
||
### 转换为立体面片
|
||
|
||
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_` 前缀；Service 准备过程显示
|
||
`Preparing surface data n/6`，可看到当前阶段与总步骤。
|
||
|
||
### 视频与序列帧
|
||
|
||
SnapForm 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并生成逐帧对应的立体面片。处理范围默认
|
||
跟随 Empty 上设置的 `Image Frames` 与 `Offset`，不需要额外配置。DA3 的转换任务复用同一个 ONNX
|
||
Session 逐帧推理，显存峰值不随视频帧数平方增长；Debug 多帧输出仍使用多视图联合推理。
|
||
|
||
## 任务结果保存在哪里
|
||
|
||
任务结果保存在 `~/.snapform/jobs/` 下。Job Server 接受任务时自动生成 opaque Job ID，并创建同名文件夹；Blender 不预先申请 ID 或目录。Packed Image 和序列帧的临时输入由 Blender 在任务结束后清理，Service 产物直接写入该 Job 目录。视频或序列帧生成的面片会引用其中的序列帧，请保留对应文件夹，不要随意删除。
|
||
|
||
## 常见问题
|
||
|
||
- 首次使用需要下载模型，如果下载慢或失败，稍后在 `Models` panel 里重试即可
|
||
- 安装 Environment 时提示下载超时：新版会自动探测并切换到镜像、失败时自动重试一次；如果仍然
|
||
超时，在扩展偏好设置的 `PyPI Index` 中填入镜像地址（如清华）后重新安装即可
|
||
- 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image
|
||
- 动画面片不动：检查 Empty 的 `Image Frames` 是否大于 1，并确认播放场景帧
|
||
|
||
## 技术文档
|
||
|
||
AI、帧提取与后续模型下载统一提交给当前 Blender 专属的 Job Server。DA3、MoGe-2 与 Debug 的 Request 和 Job Type 分别一一对应，不使用混合 Backend Request。BlendJob 接受任务时创建无类型前缀的 opaque-ID 工作目录，并通过 `JobContext` 交给执行逻辑。运行中进度通过 HTTP 轮询，已加载的 ONNX Session 由 Server 的 Models Resource 统一查询与清理。Environment 安装仍由不依赖 Service 的 Bootstrap 流程完成，不创建 Job 目录。
|
||
|
||
详细功能与技术内容见 [docs/index.md](docs/index.md)。
|
||
可复用的本地 Job Service API 与插件接入方式见 [docs/blendjob.md](docs/blendjob.md)。
|