feat(cutout_tool): Implement cutout region to shape functionality
- Added interaction helpers for cutout region validation and shape menu interaction. - Created main operator for converting image regions into cutout shapes, including AI artifact generation. - Introduced object creation logic for cutout shapes, handling depth and normal textures. - Defined cutout shape identifiers and node groups for various shape types. - Implemented depth texture writing and prediction artifact generation for MoGe-2. - Developed server jobs for generating cutout artifacts, depth planes, and refining image regions. - Added region refinement logic to enhance gesture masks using BEN2.
This commit is contained in:
@@ -1,72 +1,51 @@
|
||||
# Job 产物
|
||||
|
||||
Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通图片、JSON 或 NPZ；Blender 只根据 Job 返回值读取需要的文件，并创建最终数据块。
|
||||
|
||||
## 产物流向
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Input["媒体输入"] --> Job["Server Job"]
|
||||
Job --> Color["PNG 颜色 / Alpha"]
|
||||
Job --> Field["NPZ 深度场"]
|
||||
Job --> Meta["JSON bounds"]
|
||||
Color --> Import["Blender response()"]
|
||||
Field --> Import
|
||||
Meta --> Import
|
||||
Import --> Data["Image / Mesh / Material"]
|
||||
```
|
||||
Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通图片、JSON 或 Debug NPZ；Blender 只读取 Job 返回值明确声明的文件，再创建最终 Image、Mesh、Material 与 Object。
|
||||
|
||||
## 正式 Job
|
||||
|
||||
| Job | 主要文件 | 消费方 |
|
||||
| --- | --- | --- |
|
||||
| Job | 主要文件 | Blender 消费方式 |
|
||||
| | | |
|
||||
| `remove-background` | `image.0001.png` 起 | 替换 Image Empty 的颜色数据 |
|
||||
| `upscale-image` | `upscale.0001.png` 起 | 按共享引用情况替换当前 Image Empty 的颜色数据，并沿用原 Image 命名语义 |
|
||||
| `refine-image-mask` | `image.png`、`bounds.json` | Image Box / Lasso 读取细化 Alpha 与原图坐标 |
|
||||
| `generate-depth-plane` | `image.0001.*`、`image_geometry.npz` | 创建颜色图、深度图、材质和 Plane |
|
||||
| `generate-region-data` | 可选的 `region.png`、`region_bounds.json`、`image_geometry.npz`、`normal.png` | Blender 主线程构建 Cutout Shape 与贴图 |
|
||||
| `upscale-image` | `upscale.0001.png` 起 | 替换或新建高清颜色数据 |
|
||||
| `refine-image-region` | `image.png`、`bounds.json` | Image Box / Lasso 读取 Fit to Foreground 结果 |
|
||||
| `generate-depth-plane-geometry` | `image.0001.*`、`z-depth.exr`、`depth.json` | 创建 Depth Plane |
|
||||
| `generate-cutout-artifacts` | 可选 Region、Depth 与 Normal 文件 | 创建 Cutout Shape 与材质 |
|
||||
|
||||
两个几何 Job 都不输出 Blender 网格。`generate-depth-plane` 生成完整图片的颜色副本与深度场；`generate-region-data` 只生成请求的 AI 产物。轮廓提取、约束三角化以及 Mesh、Material 和 Geometry Nodes 创建都在 Blender 主线程完成。
|
||||
两个 Depth Job 都不输出 Blender 网格。Server 保存可由 Blender 直接加载的模型空间 EXR；轮廓提取、三角化、Depth 标定以及 Blender 数据创建仍在主线程完成。
|
||||
|
||||
## 深度场
|
||||
## Depth 与 Normal 文件
|
||||
|
||||
`image_geometry.npz` 是 Depth Plane、Depth Balloon 与 Depth Surface 共用的模型中间结果。Blender 侧统一通过 `operators/common/mesh_result.py` 的 `load_image_geometry()` 读取为 `ImageGeometry`，功能模块不分别解释字段：
|
||||
MoGe-2 Prediction 只存在于 Server 内存。`geometry/prediction_artifacts.py` 共享一次推理，并按请求写出以下文件：
|
||||
|
||||
| 字段 | 含义 |
|
||||
| 文件 | 内容 |
|
||||
| --- | --- |
|
||||
| `points` | 每个模型像素的相机空间 XYZ |
|
||||
| `depth` | 相机深度 |
|
||||
| `intrinsics` | 像素坐标下的 3×3 相机内参 |
|
||||
| `valid` | 模型与数值检查后的有效区域 |
|
||||
| `calibration_valid` | 用于结果定位或深度基准的区域；Cutout 时与 Region 相交 |
|
||||
| `image_size` | 深度场宽高 |
|
||||
| `reference_depth` | 校准区域中的参考深度 |
|
||||
| `vector-depth.exr` | RGB 保存相机空间 XYZ，Alpha 保存有效区 |
|
||||
| `z-depth.exr` | RGB 重复保存相机 Z，Alpha 保存有效区 |
|
||||
| `depth.json` | 保存 `image_size`、3×3 `intrinsics` 与 `reference_depth` |
|
||||
| `tangent-normal.png` | Tangent Space Normal Map |
|
||||
| `object-normal.png` | Object Space Normal Map |
|
||||
|
||||
Server 保留模型空间数据，不提前换算 Blender 单位。Depth Plane 在导入时根据 Image Empty 平面范围和相机内参锚定点场；Cutout 深度形状则计算 `Uniform Scale` 和局部坐标，再把相机点写入 Packed 浮点 Image 供 Geometry Nodes 采样。
|
||||
Blender 通过 `operators/common/depth_data.py` 直接加载 EXR，设为 Non-Color 并 Pack；不会从 NumPy 点场再创建一张 Depth Image。Job 文件名不改变 Blender 数据块命名：Depth 与 Normal 仍分别使用 `depth_data_name()` 和 `normal_data_name()`。Blender 读取 Z 与 Alpha 只用于最终 Region 的本地标定，Geometry Nodes 直接采样已加载的 EXR。
|
||||
|
||||
## Cutout Region 产物
|
||||
|
||||
Blender 侧先把 `RegionPath` 栅格化为 `RegionMask`，再将 Region 裁切为带有效 Alpha 的临时 RGBA 输入。Server 不接收路径或 Mask 协议，只按需产生 AI 数据：
|
||||
Blender 先把 `RegionPath` 栅格化为 `RegionMask`，再把局部 RGBA 作为 Server 输入。Server 不接收 Path 或 Mask 对象协议：
|
||||
|
||||
- 启用 Refine 时，`region.png` 保存细化后的局部 RGBA，`region_bounds.json` 保存它在输入裁切图中的范围；
|
||||
- Depth Shape 使用 `image_geometry.npz`；
|
||||
- Tangent 或 Object Normal 使用 `normal.png`。
|
||||
- 开启 Fit to Foreground 时，`region.png` 保存 Fit to Foreground 后的局部 RGBA，`region_bounds.json` 保存它相对输入裁切图的范围；
|
||||
- 需要 Vector Depth 时请求 `vector-depth.exr` 与 `depth.json`；
|
||||
- 需要 Z Depth 时请求 `z-depth.exr` 与 `depth.json`；
|
||||
- Normal Map 按空间请求 `tangent-normal.png` 或 `object-normal.png`。
|
||||
|
||||
Blender 将局部范围与原始 `RegionMask.bounds` 合成回源图坐标，并直接从源 Image 创建最终 Color Image。未启用 Refine、Depth 或 Normal 时不提交 Job。
|
||||
未启用 Fit to Foreground，且不需要 Depth 或 Normal Map 时，Surface 与 Balloon 不提交 Job。最终颜色图仍由 Blender 从源 Image 裁切，并把 Alpha 乘以最终 `RegionMask`。
|
||||
|
||||
## Debug 产物
|
||||
|
||||
Debug Job 保留模型适配层的直接输出，不执行正式功能的 Blender 导入：
|
||||
|
||||
| Job | 文件 |
|
||||
| --- | --- |
|
||||
| | |
|
||||
| `debug-da3` | `prediction.npz` |
|
||||
| `debug-moge2` | `prediction*.npz` |
|
||||
| `debug-ben2` | `foreground*.png` |
|
||||
| `debug-upscale` | `prediction*.png` |
|
||||
|
||||
这些文件用于验证模型、Device 和适配层。正式 Job 会继续派生 Region、Alpha、深度场或可导入图片，因此两者的文件结构有意不同。
|
||||
|
||||
## 单图与序列
|
||||
|
||||
正式颜色序列从 `image.0001.*` 开始，Upscale 使用独立的 `upscale.0001.png` 前缀。Remove Background 与 Upscale 的动画结果继续引用 Job 目录；单图结果通常在 Blender 导入后 Pack 到 `.blend`。不要清理仍被工程引用的序列目录。
|
||||
Debug Job 只用于直接检查模型适配层，不参与正式对象创建流程。
|
||||
|
||||
Reference in New Issue
Block a user