feat: Add BEN2 background removal functionality and integrate into SnapForm
- Introduced BEN2 model for background removal in the panel and properties. - Updated runtime to handle background removal commands and model downloads. - Implemented background removal logic in worker, including image processing and saving results. - Enhanced tests to cover new background removal features and ensure proper integration. - Updated version to 0.9.28 to reflect new features and improvements.
This commit is contained in:
53
README.md
53
README.md
@@ -3,7 +3,8 @@
|
||||
`SnapForm` 是一套从图片快速构建空间结构的 Blender Extension。目前以
|
||||
[Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
|
||||
作为首个 AI 能力，在独立 Runtime 中运行 DA3，可将官方导出结果保存在独立 job 目录，
|
||||
也可把 Image Empty 转换成带几何与材质置换的立体面片。
|
||||
也可把 Image Empty 转换成带几何与材质置换的立体面片。Debug 面板还可运行
|
||||
[BEN2](https://github.com/PramaLLC/BEN2) 背景剔除功能测试。
|
||||
|
||||
## 当前功能
|
||||
|
||||
@@ -11,11 +12,12 @@
|
||||
- 在独立 Python Runtime 中运行 Torch 与 DA3，避免污染 Blender Python 进程
|
||||
- Runtime、模型和任务结果默认保存在 `~/.snapform`，可由多个 Blender 版本共享
|
||||
- 支持 DA3 Small、Base、Large 1.1、Giant 1.1 和 Nested Giant Large 1.1
|
||||
- 支持 BEN2 Base 单图背景剔除测试，输出透明 PNG 与推理耗时
|
||||
- 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
|
||||
- 视频均匀抽帧，可设置参与重建的最大帧数
|
||||
- `Setup` 集中管理 Runtime，并逐项列出和下载所有可用模型
|
||||
- Runtime 已就绪时不额外占用面板空间；模型列表每个模型只占一行
|
||||
- `Debug` 是独立且默认折叠的 DA3 测试面板
|
||||
- `Debug` 是独立且默认折叠的 AI 功能测试面板
|
||||
- 使用一个导出类型下拉菜单和一个 `Export` 按钮
|
||||
- 只显示当前格式的专属参数；GLB 与 PLY 设置不会同时出现
|
||||
- Debug 的模型选项按格式过滤；PLY 只提供两个带 Gaussian head 的 Giant 模型
|
||||
@@ -23,10 +25,11 @@
|
||||
`(Missing)`，已下载模型保持原名
|
||||
- 分别调用 DA3 的 `glb`、`gs_ply`、`depth_vis` 和 `mini_npz` exporter
|
||||
- Image Empty 右键菜单可直接运行 DA3，根据 `mini_npz` 深度生成面片
|
||||
- Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
|
||||
- 使用浮点深度贴图、Simple Subdivision、Displace Modifier 和原图 Bump
|
||||
构建立体面片
|
||||
- 转换对话框可选择推理模式、处理分辨率和面片网格细分
|
||||
- Debug 导出完成后只打开对应 job 文件夹，不向当前 Blender 文件添加任何数据
|
||||
- Debug 的 DA3 导出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不向当前 Blender 文件添加任何数据
|
||||
- 完整保留每次任务生成的所有官方文件
|
||||
- 安装、模型下载和推理均在后台子进程运行，状态栏实时显示阶段、百分比进度条与取消按钮
|
||||
- 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复
|
||||
@@ -36,11 +39,27 @@
|
||||
1. 使用 `uv run python pack.py` 构建 Extension ZIP。
|
||||
2. 在 Blender 的 `Preferences > Extensions` 中选择 `Install from Disk`。
|
||||
3. 在 Extension Preferences 中确认 `uv` 路径和 Torch Backend。
|
||||
4. 点击 `Install Runtime`。首次安装会下载 Python、PyTorch 和 DA3 依赖。
|
||||
4. 点击 `Install Runtime`。首次安装会下载 Python、PyTorch、DA3 和 BEN2 依赖。
|
||||
5. 在 3D View 按 `N`，打开 `SnapForm` 页签。
|
||||
6. 在 `Setup` 中找到需要的模型并点击该行的 `Download`。
|
||||
7. 展开默认收起的 `Debug`，选择 `Export Format` 和本次执行使用的模型。
|
||||
8. 选择一张图片或一个视频文件。视频可设置均匀抽取的帧数，然后点击 `Export`。
|
||||
9. 测试背景剔除时，在 `Setup` 下载 `BEN2 Base`，然后在 `Debug` 的
|
||||
`BEN2 Background Removal` 区域选择单张图片并点击 `Remove Background`。
|
||||
完成后会打开 job 文件夹，其中的 `foreground.png` 带透明 Alpha；状态栏显示
|
||||
BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。
|
||||
|
||||
## Image Empty 去背景
|
||||
|
||||
1. 在 `Setup` 下载 `BEN2 Base`。
|
||||
2. 在 3D View 选中 Image Empty，右键选择 `Remove Background`。
|
||||
3. 完成后以 Fake User 保留原 Image datablock，新建并 Pack 一张透明 PNG 到当前 `.blend`，然后只把
|
||||
当前 Empty 的 `data` 换成新图；Empty 的 Transform、显示尺寸、Offset 及其他设置保持不变。
|
||||
4. 新 Image 使用原图去掉格式后再追加 `.rb` 的名称。例如 `img.png` 生成 `img.rb`，
|
||||
`img.png.001` 生成 `img.001.rb`。已有同名 datablock 时由 Blender 自动追加编号。
|
||||
|
||||
原图已 Pack 时会先写出临时 PNG 交给 BEN2，任务结束后删除临时输入；原 Image 仍保持 Pack
|
||||
状态和原始内容。BEN2 的 `foreground.png` 也会保留在对应 job 目录中。
|
||||
|
||||
## Image Empty 转深度面片
|
||||
|
||||
@@ -52,11 +71,17 @@
|
||||
转换导出 `mini_npz`，使用前需要在
|
||||
`Setup` 下载所选模型，并固定使用 `process_res_method="upper_bound_resize"`；设备和参考视图策略
|
||||
继续使用场景设置。
|
||||
- `Original`：直接把原图作为深度贴图，不显示估算参数，也不启动 Runtime 或要求源图片存在于磁盘。
|
||||
`Original` 是默认深度来源。选择 `AI Generated` 时，其 Model、Use Ray Pose 和 Resolution Scale
|
||||
参数会集中显示在独立边框中。两种模式始终显示 Displace via、Subdivision 与 Delete Original。
|
||||
- `Original`：直接把原图作为深度贴图，不显示估算参数。Remove Background 关闭时不启动
|
||||
Runtime，也不要求源图片存在于磁盘。
|
||||
`Original` 是默认深度来源。选择 `AI Generated` 时，其 Model、Use Ray Pose 与 Resolution Scale
|
||||
参数会集中显示在独立边框中。两种模式始终显示 Remove Background、Displace via、Unshaded、
|
||||
Subdivision 与 Delete Original。
|
||||
Remove Background 默认关闭，与 Depth from 无关；开启后需要下载 `BEN2 Base`，并从原图生成、
|
||||
Pack `.rb` 透明图片。它只替换生成面片材质的颜色图片，不修改源 Image Empty 的 Image datablock。
|
||||
AI Generated 仍从原图生成 `.depth`；例如 `img.png` 会得到 `img.rb` 与 `img.depth`，不会生成
|
||||
`img.rb.depth`。Original 仍用原图作为位移来源，不改变原有深度逻辑。
|
||||
Displace via 可选 `Modifier`（默认）或 `Material`；
|
||||
Subdivision 默认为 `5`，并默认删除原对象。
|
||||
Unshaded 默认关闭；Subdivision 默认为 `5`，并默认删除原对象。
|
||||
3. AI Generated 完成后会自动创建面片。面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
|
||||
Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
|
||||
的可见尺寸、Offset 与 Transform。开启 `Delete Original` 时，成功生成后
|
||||
@@ -105,6 +130,9 @@ Principled BSDF 的 `Base Color`，并通过
|
||||
`0.001`，会乘以面片 Transform 的统一缩放倍率。原图 Color 还会经过 `Float Curve` 连接到
|
||||
Principled BSDF 的 `Roughness`，曲线两端输出分别为 `0.5` 和 `0.1`；材质 IOR 保持
|
||||
Principled BSDF 默认值 `1.5`。
|
||||
开启 `Unshaded` 后，Surface 改为原图 Color 直接连接 Emission，再连接 Material Output；不创建
|
||||
Principled BSDF、Bump 或 Float Curve。若 Displace via 选择 `Material`，深度贴图与 Displacement
|
||||
节点仍会保留并连接 Material Output 的 Displacement。
|
||||
|
||||
这里的“原始距离”是 DA3 模型输出的尺度。普通 Small、Base、Large 和 Giant 模型的深度不应
|
||||
被解释为现实世界的米；需要现实尺度时应选择带 metric depth 的
|
||||
@@ -116,6 +144,8 @@ Principled BSDF 默认值 `1.5`。
|
||||
`Convert to Depth Plane` 会按当前 Depth from 再次转换。
|
||||
面片、深度 Image、Texture 与 Material 会在同一个 Blender Undo 步骤中创建；转换完成后执行
|
||||
`Ctrl+Z` 会完整撤销本次转换，不会越过转换去回退更早的 Image Empty 操作。
|
||||
开启 Remove Background 时，`.rb` Image 的创建、Pack 和深度面片生成也属于
|
||||
同一个 Undo 步骤。
|
||||
|
||||
Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PNG 交给 DA3，
|
||||
不会 Unpack 或修改源 Image；任务结束后自动删除临时文件。普通图片仍直接读取源文件。DA3 的原始
|
||||
@@ -129,7 +159,7 @@ Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PN
|
||||
`DA3 Nested Giant Large 1.1`。Small、Base 和 Large 没有 Gaussian head，无法由
|
||||
DA3 生成 `gs_ply`。
|
||||
|
||||
每次任务会在 `~/.snapform/jobs/<任务目录>/` 中保留 DA3 官方产物：
|
||||
每次任务会在 `~/.snapform/jobs/<任务目录>/` 中保留输出产物：
|
||||
|
||||
```text
|
||||
<GLB 任务目录>/
|
||||
@@ -143,6 +173,9 @@ DA3 生成 `gs_ply`。
|
||||
|
||||
<Mini NPZ 任务目录>/
|
||||
└── exports/mini_npz/results.npz
|
||||
|
||||
<BEN2 背景剔除任务目录>/
|
||||
└── foreground.png
|
||||
```
|
||||
|
||||
建议从 `DA3 Base` 开始。它使用 Apache 2.0 模型权重；`DA3 Large 1.1` 权重采用
|
||||
@@ -185,6 +218,7 @@ Extension 本身不包含 Torch。`Install Runtime` 使用 `uv` 创建独立 Pyt
|
||||
- TorchVision 0.24.1
|
||||
- xFormers 0.0.33.post2（与 PyTorch 2.9.1 对应）
|
||||
- 固定到已验证 commit 的 Depth Anything 3
|
||||
- 固定到已验证 commit 的 BEN2
|
||||
- 固定到 DA3 官方推荐 commit 的 `gsplat`；仅安装 PLY 导出所需的纯 Python 部分，
|
||||
不编译本机 CUDA rasterizer
|
||||
- `addict` 2.4.0（补充 DA3 上游包元数据暂未声明的运行依赖）
|
||||
@@ -236,5 +270,6 @@ uv run python pack.py
|
||||
## 上游与许可证
|
||||
|
||||
- Depth Anything 3 代码采用 Apache 2.0。
|
||||
- BEN2 代码与模型权重采用 MIT License。
|
||||
- 本 Extension 代码采用 GPL-3.0-or-later。
|
||||
- 模型权重许可证由所选 Hugging Face 模型仓库决定，Extension 下载前会在界面显示。
|
||||
|
||||
Reference in New Issue
Block a user