feat: Introduce Balloon Lasso Tool for mesh extraction
- Added BalloonTool workspace tool to facilitate the extraction of balloon meshes in the 3D viewport. - Implemented ActivateBalloonTool operator to activate the Balloon Lasso Tool. - Refactored BalloonLasso operator into ExtractBalloon for better clarity and functionality. - Enhanced properties for balloon extraction, including mode, thickness, resolution, and material reuse options. - Updated SnapFormSettings to include new balloon-related properties. - Improved material and image handling for balloon extraction, ensuring compatibility and reusability. - Added tests to validate the registration and functionality of the new balloon tools and properties.
This commit is contained in:
@@ -1,73 +1,66 @@
|
||||
# Depth Plane
|
||||
|
||||
本页记录 Depth Plane 的数据、节点和材质实现。日常操作与参数说明请阅读
|
||||
[Depth Plane 使用指南](guide-depth-plane.md)。
|
||||
Depth Plane 把图片映射为带深度位移的面片，适合快速获得可调节的立体效果。操作方法见[Depth Plane 使用指南](guide-depth-plane.md)。
|
||||
|
||||
## Image Empty 转深度面片
|
||||
## 数据流
|
||||
|
||||
1. 在 3D View 选中 `Object Type = Empty`、`Display As = Image` 的对象。
|
||||
2. 右键打开 `SnapForm` 子菜单并选择 `Convert to Depth Plane`，通过 `Depth from` 选择深度来源：
|
||||
- `DA3`：显示 Model 和 Resolution Scale。ONNX 模型使用 camera decoder 恢复相机。Process Res 先以原图长边乘以
|
||||
Resolution Scale，再钳制到 `252–1008`，最后对齐到最接近的 `14` 倍数。Resolution Scale 以百分比
|
||||
显示，范围为 `1–100%`，默认 `100%`；界面只在标签中实时显示最终 Process Res。
|
||||
转换导出 `mini_npz`，使用前需要在
|
||||
`Models` panel 下载所选模型，并固定使用 `process_res_method="upper_bound_resize"`；设备和参考视图策略
|
||||
继续使用场景设置。Model 下拉菜单只列出已经下载的 DA3 模型；若没有可用模型，对话框会引导到
|
||||
`Models` panel 下载。
|
||||
- MoGe-2：使用所选模型输出 metric depth、normal、validity mask 与 normalized intrinsics。Depth Plane 不保存体积较大的 points；Surface 会在 AI 进程内用内置 NumPy 网格构建生成 mesh.npz。Debug 则逐帧保存 API 直接返回的 points、depth、normal、mask 与 intrinsics，不生成网格或预览。
|
||||
- `Original`：直接把原图作为深度贴图，不显示估算参数。仅在开启 `Remove Background` 时运行 BEN2
|
||||
取得前景 Alpha；视频或序列帧按需同时抽取原始帧与前景序列，把原始帧作为 `.depth` 序列。
|
||||
`MoGe-2 ViT-S` 是默认深度来源。选择 `DA3` 时，其 Model 与 Resolution Scale
|
||||
参数会集中显示在独立边框中。`Remove Background` 与 `Shadeless` 直接显示，不再使用 Options 折叠；
|
||||
`Keep Original` 默认关闭，并在分割线下方保持为最后一项。仅当开启 `Remove Background` 时才需要
|
||||
`BEN2 Base`，并把 `.color` 的 Alpha 作为独立 Mask，不在 Server 中改写深度值。无论颜色层是直接
|
||||
复制原图，还是由 BEN2 为单图或序列修改 Alpha，Server 都统一写为 `color.0001.*`；Blender 只导入
|
||||
这一份 `.color`，不复用源 Empty 的 Image。颜色贴图会按当前场景的 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`。
|
||||
Image Empty 引用视频或序列帧时，DA3 与 MoGe-2 会按 Empty 的 Image Frames 数值逐帧估计
|
||||
深度（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset，与背景蒙版范围一致；
|
||||
DA3 会复用同一个 ONNX Session 对每帧独立推理，再合并为原有序列输出，避免多帧 Attention 的平方级显存占用。
|
||||
DA3 与 MoGe-2 均先用未经抠图的原始 RGB 生成深度，再运行可选 BEN2；BEN2 Alpha 只参与最终输出过滤和材质 Mask。
|
||||
该行为只用于 Depth Plane 转换；Surface 仅支持单张图片。Debug 中 DA3 多帧输入联合推理，
|
||||
MoGe-2 与 BEN2 按单图 API 逐帧运行。
|
||||
Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty
|
||||
一致；Original 模式的视频或序列帧使用 `color.0001.*` 颜色层同时作为颜色与深度输入；开启
|
||||
Remove Background 时同名颜色层包含 BEN2 修改后的 Alpha。
|
||||
DA3 动画深度以 EXR 序列帧（`depth.0001.exr` 起）保存在 Job 目录根下；MoGe-2 动画只为置换数据创建 `moge_depth.0001.exr` 起的 EXR 序列。MoGe-2 的 `results.npz` 保留完整 depth、normal 与 mask 数组，Server 另外输出对应 PNG 预览。
|
||||
DA3 与 MoGe-2 的单帧推理进度只显示模型与阶段名称，不追加 `1/1`；多帧时继续显示当前帧与总数。`Shadeless`、`Remove Background` 与 `Keep Original` 均默认关闭，因此默认删除原对象。`Shadeless` 会以 `O Shadeless` 节点组替代普通 Principled BSDF 路径，并继续通过 Alpha 与 Transparent BSDF 混合。
|
||||
3. DA3 或 MoGe-2 完成后会自动创建面片。DA3 面片几何先由 `mini_npz` 的相机内参与深度确定，再通过对象
|
||||
Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty
|
||||
的可见尺寸、Offset 与 Transform。DA3 会把用于匹配画面尺寸的缩放预乘到 `.depth` 数值，
|
||||
XY 缩放烘焙到 Mesh，Z 不参与平面匹配；最终对象 Scale 为 `(1, 1, 1)`，视觉深度与旧逻辑一致。
|
||||
关闭 `Keep Original` 时，成功生成后删除源 Empty。生成面片 Object 使用源 Empty 的原名；开启
|
||||
`Keep Original` 时不处理
|
||||
同名冲突，由 Blender 自动为生成面片追加编号。
|
||||
4. Blender 只创建保留图像纵横比的最低密度基础网格，再把 `O DA3 Depth Plane` 作为 Geometry Nodes
|
||||
修改器添加到对象。节点组与 `O DA3 Surface` 一同保存在 `O_SnapForm.blend`，关闭
|
||||
`show_group_selector`，不为每个对象复制节点组。MoGe-2 使用单独的 `O MoGe2 Depth Plane`，处理
|
||||
网格细分、metric depth 位移和材质设置；材质使用 `O MoGe2 Depth Plane Layer`，直接接入模型 normal。
|
||||
`O MoGe2 Depth Plane` 与 DA3 一样通过隐藏的 Color Image 读取 `.color` Alpha，以 `Alpha > 0.5`
|
||||
划分前景范围，并在范围外改用 `Background Depth`。两个修改器公开以下参数：
|
||||
- `Displacement`：位于 Geometry 之后的第一项，菜单包含 `Geometry`（默认）与 `Material`。`Geometry`
|
||||
在节点组内沿法线修改网格，`Material` 保持网格平面并启用材质置换；
|
||||
- `Subdivision`：位于第二项，默认 `5`。节点读取基础平面的 Bounding Box，短边分段数为 `2^Subdivision`，
|
||||
长边按宽高比计算并四舍五入；例如 16:9 图片在等级 `5` 时生成 `57×32` 个面；
|
||||
- `Background Depth`：默认 `-1`，允许正负值，Structure Type 为 `Single`，直接显示且不再放在 Panel 中。前景 Mask 外的结构或
|
||||
材质置换使用该值；是否存在背景只取决于转换所得色彩贴图的 `Alpha > 0.5` 二值结果；
|
||||
- `Depth Scale`：默认 `1`，允许正负值，Structure Type 为 `Single`，同时控制 Geometry 与 Material
|
||||
两条置换路径。
|
||||
Grid 重建后通过隐藏的 Material 输入重新赋予转换材质，并对所有面执行 Shade Smooth。
|
||||
材质使用显式指向 `UVMap` 的 UV Map 节点连接颜色、前景 Mask 与深度 Image Texture，不依赖活动 UV。
|
||||
前景深度先与 `Background Depth` 取 Maximum，再按色彩贴图 Alpha 与背景深度混合，
|
||||
深度分支在混合前使用 `Alpha > 0.5` 转为二值 Mask，避免半透明前景被背景深度拉扯；
|
||||
材质表面 Alpha 同样使用二值 Mask。材质置换使用相同的二值和钳制顺序。
|
||||
节点组还会把 `o_material_displacement` 与 `o_background_depth` 写入点域，材质通过
|
||||
`Geometry` 类型的 Attribute 节点读取。点域会为顶点保存重复值，但能在应用修改器后继续保留参数；
|
||||
相比自适应网格本身，其占用很小。Depth Image 与 Color Image 是修改器隐藏数据输入，
|
||||
由导入流程自动设置。
|
||||
`.color` 与 `.depth` 的 Blender Image 类型只依据源 Empty Image：普通单图使用 `IMAGE`，Movie 或 Sequence 使用 `SEQUENCE`；即使动画源这次只处理一帧也仍为 `SEQUENCE`，不按输出文件数量推断。视频与序列帧还会为 Depth 与 Color 共同写入隐藏的 `Frame`、`Frame Start`、`Frames` 与 `Cyclic`。
|
||||
节点组内部不再使用 Scene Time。只有原 Image Empty 是视频或序列时，导入流程才直接给修改器的 `Frame`
|
||||
socket 添加 Scripted Expression Driver `frame`；静态图保持默认值 `1`，不创建 Driver。导入内容已经
|
||||
是截取后的帧，因此 Offset 在节点组内恒定为 `0`。
|
||||
节点组根据 `Frame` 计算从 `1` 开始的 Image Texture Frame：场景帧与 Start 都为 `1` 时读取图片第 `1` 帧；非循环输入
|
||||
钳制到有效范围；循环输入使用 Floored Modulo，让 `Frame Start` 前后的负、正相对帧都映射到
|
||||
`1…Frames`，因此开始帧之前也会循环播放。Geometry 置换会像材质 Image Texture 一样随场景帧刷新。
|
||||
```mermaid
|
||||
flowchart LR
|
||||
Input["Image Empty"] --> Depth{"深度来源"}
|
||||
Depth --> DA3["DA3"]
|
||||
Depth --> MoGe["MoGe-2"]
|
||||
Depth --> Original["Original"]
|
||||
DA3 --> Layers["颜色层 + 深度层"]
|
||||
MoGe --> Layers
|
||||
Original --> Layers
|
||||
Layers --> Import["Blender 导入"]
|
||||
Import --> Mesh["基础面片"]
|
||||
Import --> Nodes["Geometry Nodes"]
|
||||
Import --> Material["材质"]
|
||||
```
|
||||
|
||||
Server 为每帧准备颜色、深度和可选前景 Alpha。Blender 导入这些数据，创建基础面片，并用 Geometry Nodes 与材质分别完成几何位移和表面细节。
|
||||
|
||||
## 深度来源
|
||||
|
||||
| 来源 | 深度含义 | 额外数据 | 适合 |
|
||||
| --- | --- | --- | --- |
|
||||
| DA3 | 相对深度 | 相机内参与置信度 | 通用单图与动画 |
|
||||
| MoGe-2 | Metric depth | 法线、Mask、相机内参 | 更稳定的尺度与表面法线 |
|
||||
| Original | 原图亮度 | 可选 BEN2 Alpha | 已准备好高度图的素材 |
|
||||
|
||||
DA3 和 MoGe-2 都以未经抠图的 RGB 估计深度。启用 Remove Background 后，BEN2 Alpha 用于颜色透明度和前景 Mask，深度本身保持模型输出。
|
||||
|
||||
视频与序列帧逐帧推理并复用同一个模型 Session，因此显存主要由单帧分辨率决定。DA3 Debug 的多帧联合推理属于另一条工作流。
|
||||
|
||||
## Blender 结果
|
||||
|
||||
转换会创建以下数据：
|
||||
|
||||
- 与源 Image Empty 对齐的面片
|
||||
- `.depth` 与 `.color` Image datablock
|
||||
- 使用 `O DA3 Depth Plane` 或 `O MoGe2 Depth Plane` 的 Geometry Nodes 修改器
|
||||
- 连接颜色、Alpha、Bump 与材质位移的材质
|
||||
|
||||
Geometry Nodes 提供深度范围、细分、重拓扑、平滑、背景深度和位移强度等控制。深度 Mask 在几何和材质路径中使用相同阈值，以保持轮廓一致。
|
||||
|
||||
材质与图片名称以源 Image datablock 为基名。对象 Transform、显示尺寸和 Offset 会转换为面片的空间位置与比例。
|
||||
|
||||
## 单图与动画文件
|
||||
|
||||
单图深度使用 OpenEXR Pack 到 `.blend`，以保留浮点范围。Packed Image 会先导出临时输入，任务结束后清理，源 Image 保持不变。
|
||||
|
||||
动画使用 Job 目录中的外部序列：
|
||||
|
||||
```text
|
||||
<job-id>/
|
||||
├── color.0001.jpg/png
|
||||
├── depth.0001.exr
|
||||
└── results.npz
|
||||
```
|
||||
|
||||
MoGe-2 动画的深度序列使用 `moge_depth.0001.exr`。这些文件是 `.blend` 的运行时依赖，详见[动画与序列帧](animation.md)。
|
||||
|
||||
## 适用范围
|
||||
|
||||
Depth Plane 是固定平面上的深度位移，不是完整的逐像素 camera-space 重建。它强调可编辑性和动画支持；需要透视网格时使用 [Surface](surface.md)。
|
||||
|
||||
Reference in New Issue
Block a user