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,26 +1,28 @@
|
||||
# Job Runtime 与 Server
|
||||
|
||||
AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程和任务队列。Blender 侧只配置 Runtime 与提交参数；`server/` 是不依赖 `bpy` 的计算包，可以在独立解释器中导入。
|
||||
AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧只准备输入、提交普通字典参数并导入结果；`server/` 不依赖 `bpy`。
|
||||
|
||||
## 对应文件
|
||||
## 目录职责
|
||||
|
||||
```text
|
||||
src/anyimage/
|
||||
├── runtime.py # Environment 与 JobRuntime 配置
|
||||
└── server/
|
||||
├── app.py # Job 注册和共享资源
|
||||
├── app.py # 公开 Job 注册
|
||||
├── model_catalog.py # 模型声明
|
||||
├── model_download.py # 下载、校验与镜像回退
|
||||
├── model_manager.py # 模型目录与 Session 缓存
|
||||
├── media/input.py # 图片、视频和序列输入
|
||||
├── jobs/ # app.py 可提交的公开任务
|
||||
├── region/ # BEN2 Region 细化
|
||||
├── model_download.py # 下载与校验
|
||||
├── model_manager.py # 模型目录与 Session 生命周期
|
||||
├── jobs/ # 公开协议与流程编排
|
||||
├── media/ # 图片、视频、序列帧和尺寸处理
|
||||
├── region/ # 通用 BEN2 Region 细化
|
||||
├── geometry/ # Depth / Normal 文件产物与相机元数据
|
||||
├── models/ # 模型适配与 ONNX 推理
|
||||
├── geometry/ # 深度反投影与法线纹理编码
|
||||
└── outputs/ # Debug Prediction 序列化
|
||||
```
|
||||
|
||||
## 任务生命周期
|
||||
公开 Job 不互相导入实现。`jobs/` 只编排，稳定的原子能力放在对应领域目录中。
|
||||
|
||||
## 生命周期
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
@@ -32,56 +34,51 @@ flowchart TD
|
||||
Directory --> Response["Operator response()"]
|
||||
```
|
||||
|
||||
Runtime 在首次任务或显式启动时拉起 Server。任务在队列中串行执行，进度、取消和日志由 BlendJob 提供；AnyImage Job 在阶段边界调用 `context.check_cancelled()`，并把业务产物写入当前 Job 目录。Operator 完成响应后再清理 Blender 侧为 Packed Image 准备的临时输入。
|
||||
Job 在阶段边界调用 `context.check_cancelled()`，并把稳定产物写入当前 Job 目录。Blender 响应完成后，再由输入所有者清理临时 Packed Image 文件。
|
||||
|
||||
`server/app.py` 是任务清单的唯一入口：
|
||||
## 公开 Job
|
||||
|
||||
| Job | 主要用途 |
|
||||
| --- | --- |
|
||||
| `download-model`、`download-required-models` | 准备模型文件 |
|
||||
| `remove-background` | BEN2 透明前景 |
|
||||
| `remove-background` | 生成 BEN2 透明前景 |
|
||||
| `upscale-image` | 4× 图片或帧序列 |
|
||||
| `refine-image-mask` | 为 Image Box / Lasso 细化 Region |
|
||||
| `generate-depth-plane` | 为 Depth Plane 生成颜色副本与深度场 |
|
||||
| `generate-region-data` | 按需为 Cutout Region 生成 Refine、Depth 或 Normal |
|
||||
| `refine-image-region` | 为 Image Box / Lasso 执行 Fit to Foreground |
|
||||
| `generate-depth-plane-geometry` | 为 Depth Plane 复制颜色并生成 Z Depth 与相机元数据 |
|
||||
| `generate-cutout-artifacts` | 按需执行 Fit to Foreground，并生成 Depth 或 Normal 文件产物 |
|
||||
| `debug-*` | 保存模型适配层的直接输出 |
|
||||
|
||||
## 媒体输入
|
||||
`generate-depth-plane-geometry` 对应 `jobs/depth_plane.py`；`generate-cutout-artifacts` 对应 `jobs/cutout.py`。共享的 MoGe-2 推理编排位于 `geometry/prediction_artifacts.py`，Depth EXR 与元数据写入位于 `geometry/depth_texture.py`，Normal 编码位于 `geometry/normal_texture.py`，Fit to Foreground 的通用实现位于 `region/refine_region.py`。
|
||||
|
||||
`server/media/input.py` 把单图、视频和图片目录统一为有序帧路径，并用上下文管理器负责临时帧目录的生命周期。帧展开是媒体输入的内部能力，不再暴露没有业务消费者的独立 Job。`server/media/resolution.py` 提供默认 `2048` 的共用输入长边限制；Upscale Operator 只允许长边小于该值的当前 Image 进入正式任务，Depth Plane 与 Cutout 则只限制模型分析输入，不降低颜色贴图分辨率。
|
||||
## 尺寸约束
|
||||
|
||||
`generate-depth-plane` 与 `generate-region-data` 只接受一帧，因此 Depth Plane 与 Cutout 都是静态图工作流。Remove Background 与 Upscale 通过同一媒体入口处理单图、视频和序列帧。
|
||||
`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map、Fit to Foreground 的模型分析图长边；不会降低材质颜色图分辨率。
|
||||
|
||||
公开 Job 按稳定的计算边界划分，不按界面入口机械映射。Depth Plane 使用 `jobs/generate_depth_plane.py`，Cutout 使用 `jobs/generate_region_data.py`，四个 Debug Job 共享 `jobs/debug_predictions.py`。Job 只负责协议和编排；可复用的输入、AI Region、模型与几何数据能力分别位于 `media/`、`region/`、`models/` 和 `geometry/`，Job 之间不互相导入实现。
|
||||
Cutout 另有 Blender 侧的 **Maximum Cutout Mesh Resolution**。它限制所有 Cutout Shape 的网格采样密度，包括完全不使用 AI 的 Surface 与 Balloon。两个设置没有隐式绑定。
|
||||
|
||||
## 模型层
|
||||
`generate-depth-plane-geometry` 与 `generate-cutout-artifacts` 只接受一帧，因此 Depth Plane 与 Cutout 是静态图工作流。Remove Background 与 Upscale 继续通过媒体入口处理单图、视频和序列帧。
|
||||
|
||||
Job 只编排流程，模型适配层把不同推理 API 统一为内存对象：
|
||||
## 模型边界
|
||||
|
||||
- DA3 适配为深度、置信度、相机内外参与相机点。
|
||||
- MoGe-2 适配为深度、法线、有效区域、相机内参与可选相机点。
|
||||
- BEN2 返回带 Alpha 的前景图。
|
||||
- Upscale 返回保留源 Alpha 的 4× RGBA 图。
|
||||
正式 Depth Plane、Cutout Depth 与 Normal Map 都只使用 MoGe-2。BEN2 用于 Remove Background 与 Fit to Foreground，Upscale 使用所选高清模型。DA3 只保留 `debug-da3` 及其 Debug 参数、模型下载与适配代码，不进入任何生产 Operator、Job 或自动回退。
|
||||
|
||||
`ModelManager` 管理下载目录和 ONNX Session。缓存按 BEN2、几何模型和 Upscale 三个族分开；每个族只保留最近一次使用的模型与 Device，切换同族模型时释放旧 Session。这样连续任务可以复用模型，同时避免同一类模型重复占用资源。
|
||||
`ModelManager` 按模型族管理下载目录与 ONNX Session，同一族只保留最近使用的模型和 Device，避免同类模型重复占用资源。
|
||||
|
||||
## Environment 与 Storage Root
|
||||
|
||||
`runtime.py` 声明 Python 3.12 环境和固定版本的 NumPy、Pillow、PyAV、trimesh、Hugging Face Hub 与 ONNX Runtime。Windows 安装 DirectML 版本，其他平台安装标准 ONNX Runtime。首次安装后依次下载默认 MoGe-2、BEN2 和 Real-ESRGAN WDN 模型。
|
||||
|
||||
Storage Root 默认是 `~/.anyimage`：
|
||||
`runtime.py` 声明独立 Python 3.12 环境和固定依赖。首次安装会准备默认 MoGe-2、BEN2 与 Real-ESRGAN WDN 模型。Storage Root 默认是 `~/.anyimage`：
|
||||
|
||||
```text
|
||||
~/.anyimage/
|
||||
├── .venv/ # 独立 Environment
|
||||
├── models/ # 模型目录
|
||||
├── jobs/ # Job 产物与 job.log
|
||||
├── .venv/
|
||||
├── models/
|
||||
├── jobs/
|
||||
├── environment.json
|
||||
├── manifest.json
|
||||
├── install.log
|
||||
└── server.log
|
||||
```
|
||||
|
||||
Storage Root 由扩展偏好设置提供给 Runtime。切换路径等同于切换整套 Environment、模型和任务数据，不会自动迁移旧目录。
|
||||
切换 Storage Root 等同于切换整套 Environment、模型与任务数据，不自动迁移旧目录。
|
||||
|
||||
各 Job 的稳定产物见 [Job 产物](outputs.md)。
|
||||
|
||||
Reference in New Issue
Block a user