Add new functionality for image rectification and depth metadata handling
- Implemented a preview tool for rectifying images with interactive aspect controls in `preview.py`. - Added tests for depth metadata loading to ensure consistent schema usage in `test_depth_metadata.py`. - Developed comprehensive tests for cutout calibration processes in `test_cutout_calibration.py`, including stability checks and depth calibration. - Created tests for frame compositing operations in `test_frame_compositing.py`, ensuring correct handling of depth and transparency. - Introduced material slot inheritance functionality in `material_slots.py` to manage geometry material assignments. - Built shared shader nodes for material processing in `shader.py`, including roughness and bump mapping setups.
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
| 模块 | 职责 |
|
||||
| --- | --- |
|
||||
| `__init__.py` | 注册类型、工具、菜单、快捷键与 Runtime |
|
||||
| `menu.py`、`panel.py` | Image Empty 上下文菜单与 Job Server 面板 |
|
||||
| `menu.py`、`panel.py` | Image Empty 与 Shader Image Texture 上下文菜单与 Job Server 面板 |
|
||||
| `preferences.py` | 扩展设置及读取入口 |
|
||||
| `properties.py` | Scene 手势状态、视频帧数、模型状态与枚举 |
|
||||
| `common/` | Blender 侧公共能力 |
|
||||
@@ -12,15 +12,6 @@
|
||||
|
||||
## 注册与配置
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[register] --> B[按 CLASSES 顺序注册类型]
|
||||
B --> C[注册 Frame、Mask、Rectify、Cutout 工具]
|
||||
C --> D[挂载 Scene.anyimage_settings]
|
||||
D --> E[挂载 View3D 与 Outliner 菜单及剪贴板快捷键]
|
||||
E --> F[注册 JobRuntime]
|
||||
```
|
||||
|
||||
注销先关闭 Runtime 和交互入口，再移除 Scene 属性，按 `CLASSES` 逆序注销类型。设备、存储目录、模型、材质显示适配和功能上限统一通过 `preferences.py` 读取。
|
||||
|
||||
**Maximum AI Input Size** 限制模型分析图和 Upscale 可提交源图；**Maximum Frame Resolution** 限制 Frame 输出；**Maximum Cutout Mesh Resolution** 限制轮廓网格采样。三者各自作用于对应数据阶段。
|
||||
@@ -40,4 +31,4 @@ flowchart TD
|
||||
|
||||
Plane、Frame、Mask、Rectify 和无需 AI 的 Cutout 在 Blender 内执行。Server 的 `jobs/` 编排任务，`models/` 负责模型适配，`geometry/` 处理深度与法线产物。Server 模块通过内部相对导入共享能力，Blender 侧通过 `common/` 复用。
|
||||
|
||||
MoGe-2 输出统一为 `GeometryFrame`：包含 Depth、Validity、Intrinsics，以及按需提供的 Normal 和 Points。产物写入器消费同一个 Frame，保持深度、法线和相机数据一致。参见 [Runtime](runtime.md) 与 [产物协议](outputs.md)。
|
||||
MoGe-2 与 MoGe-3 输出统一为 `GeometryFrame`：包含 Depth、Validity、Intrinsics，以及按需提供的 Normal 和 Points。产物写入器消费同一个 Frame，保持深度、法线和相机数据一致。参见 [Runtime](runtime.md) 与 [产物协议](outputs.md)。
|
||||
|
||||
@@ -6,6 +6,9 @@
|
||||
| --- | --- |
|
||||
| `ai.py` | 环境和模型就绪检查、输入路径校验、`production_device()`、`moge2_parameters()` 与安装 UI |
|
||||
| `image.py` | `image_rgba()`、动画帧设置、Job 输入准备、像素采样、结果 Image 和 `replace_empty_image()` |
|
||||
| `color_image.py` | 材质颜色与 AI 分析输入的准备和清理 |
|
||||
| `hdr_image.py` | HDR 去背景分析输入及浮点颜色保留 |
|
||||
| `image_target.py` | Image Empty 与 Shader Image Texture 编辑目标 |
|
||||
| `selection.py` | `SelectionPath`、`SelectionMask`、non-zero winding 栅格化与 Alpha 修整 |
|
||||
| `viewport.py` | 原生点选、屏幕投影、`ImageGesture`、Lasso / Brush / Polyline 与 Overlay |
|
||||
| `depth.py` | 深度图片和元数据加载、相机坐标与显示范围的尺度换算 |
|
||||
@@ -15,22 +18,9 @@
|
||||
|
||||
## 图像生命周期
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Image 与 Image Empty] --> B[image_rgba 读取业务像素]
|
||||
B --> C{处理位置}
|
||||
C -- 本地 --> D[像素算法]
|
||||
C -- Server --> E[prepare_image_input 或 prepare_image_bounds_input]
|
||||
E --> F[Job 输出文件]
|
||||
F --> G[加载并 Pack]
|
||||
D --> G
|
||||
G --> H[replace_empty_image]
|
||||
H --> I[保留身份、共享引用、帧设置和画框]
|
||||
```
|
||||
|
||||
业务像素采用 Top-down RGBA，`image_pixels()` 使用 Blender 像素顺序。预乘采样用于投影插值；文件或 Packed 图像的业务读取保留隐藏 RGB。直接编辑结果通过统一入口处理共享 Image、失败恢复和源数据清理。
|
||||
|
||||
`prepare_image_input()` 返回路径及临时标记；`cleanup_image_input()` 与创建方配对。Cutout 的 `prepare_image_bounds_input()` 复用已读取的源 RGBA，输出指定几何 bounds 的矩形图片。
|
||||
`prepare_image_input()` 返回路径及临时标记；`cleanup_image_input()` 与创建方配对。`color_image.py` 的 `prepare_material_color_input()` 准备材质颜色，`material_analysis_input()` 提供分析输入；Cutout 按几何 bounds 裁切。
|
||||
|
||||
## 手势与 Selection
|
||||
|
||||
|
||||
@@ -15,11 +15,11 @@ uv run pytest
|
||||
| Frame、Mask、Rectify、Plane、Cutout | 对应 `test_*_tool.py`、`test_*_operators.py` 与对象、投影、网格测试 |
|
||||
| 图像身份、Alpha、材质与 Undo | 图像编辑集成、共享替换、材质适配与 Undo 测试 |
|
||||
| Server | `test_job_server.py`、`test_server_jobs.py`、`test_media_input.py`、`test_geometry_artifacts.py` |
|
||||
| 模型 | `test_model_manager.py`、目录、下载、推理与各 ONNX 模型测试 |
|
||||
| 节点资产 | 布局检查、Depth Plane 模式、深度分离与 Cutout 体积求值 |
|
||||
| 工具与包协议 | 扩展 Manifest、打包、模型同步、节点启动器和文档命令测试 |
|
||||
| 模型 | `test_model_manager.py`、下载、推理与各 ONNX 模型测试 |
|
||||
| 节点资产 | 布局前后功能等价、深度分离与 Cutout 体积求值 |
|
||||
| 工具与包协议 | 扩展 Manifest、打包、模型同步与节点启动器 |
|
||||
|
||||
Blender Stub 共用 `blender_test_support.py`；Server 和实际 Blender 几何 fixture 按使用范围存放在对应 support 模块。测试命名描述功能、触发条件与可观察结果。
|
||||
Blender Stub 共用 `tests/support/blender.py`；Server 和实际 Blender 几何 fixture 按使用范围存放在对应 support 模块。测试命名描述功能、触发条件与可观察结果。
|
||||
|
||||
## 发布命令
|
||||
|
||||
@@ -27,14 +27,14 @@ Blender Stub 共用 `blender_test_support.py`；Server 和实际 Blender 几何
|
||||
| --- | --- |
|
||||
| `uv run pack` | 生成 Windows、macOS arm64、Linux 扩展包 |
|
||||
| `uv run pack --prepare` | 为本机同步扩展 wheel 与 Manifest |
|
||||
| `uv run build-nodes` | 构建、验证节点资产并运行测试 |
|
||||
| `uv run sync-models` | 准备、校验并上传模型声明的文件 |
|
||||
| `uv run node-group build` | 构建、验证节点资产并运行测试 |
|
||||
| `uv run model sync` | 准备、校验并上传模型声明的文件 |
|
||||
| `uv run docs -dev` | 本地预览文档 |
|
||||
| `uv run docs` | 通过 Mike 发布项目版本并更新 latest |
|
||||
|
||||
`tools/pack.py` 从 `pyproject.toml` 读取依赖，按平台与 Blender Python 版本解析 wheel，使用 Blender 提供的 NumPy。产物命名为 `AnyImage.v<version>.<platform>.zip`，写入 `dist/`。本地 BlendJob wheel 内容变化后运行 `uv lock --refresh`，并核对锁文件、Manifest 与打包测试。
|
||||
|
||||
`tools/models/cli.py` 根据模型目录选择上游 ONNX 或本地导出流程；`tools/models/exports.py` 处理对应 PyTorch 权重导出。文件校验依据声明大小和 SHA-256，上传使用逐文件复制。`--prepare-only` 用于本地准备。
|
||||
`tools/models/cli.py` 根据模型目录选择上游 ONNX 或本地导出流程；`tools/models/exports.py` 处理对应 PyTorch 权重导出。文件校验依据声明大小和 SHA-256，上传使用逐文件复制。`uv run model prepare` 用于本地准备。
|
||||
|
||||
## CI 与文档导航
|
||||
|
||||
|
||||
@@ -2,16 +2,6 @@
|
||||
|
||||
AnyImage 在 Blender 主线程处理交互、像素编辑和数据创建，通过 BlendJob 把模型推理交给独立 Job Server。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Image Empty 或剪贴板图片] --> B[Operator 与手势工具]
|
||||
B --> C{需要 AI？}
|
||||
C -- 是 --> D[准备文件与普通字典参数]
|
||||
D --> E[JobRuntime → Job Server]
|
||||
E --> F[图片与相机元数据]
|
||||
F --> G[Blender 主线程导入]
|
||||
C -- 否 --> G
|
||||
G --> H[Image 编辑或 Mesh 与材质创建]
|
||||
```
|
||||
|
||||
| 主题 | 对应职责 |
|
||||
|
||||
@@ -1,11 +1,26 @@
|
||||
# 节点资产
|
||||
|
||||
## 资产清单
|
||||
|
||||
节点组文件在 `tools/nodes/groups`
|
||||
|
||||
| 节点组 | 构建模块 |
|
||||
| ------------------------ | ------------------------- |
|
||||
| `O Image Plane` | `image_plane.py` |
|
||||
| `O Image Depth Plane` | `image_depth_plane.py` |
|
||||
| `O Image Relief Plane` | `image_relief_plane.py` |
|
||||
| `O Image Layer` | `image_layer.py` |
|
||||
| `O Image Depth Layer` | `image_depth_layer.py` |
|
||||
| `O Shadeless` | `shadeless.py` |
|
||||
| `O Image Cutout` | `image_cutout.py` |
|
||||
| `O Image Depth Cutout` | `image_depth_cutout.py` |
|
||||
| `O Image Depth Balloon` | `image_depth_balloon.py` |
|
||||
| `O Image Depth Panorama` | `image_depth_panorama.py` |
|
||||
|
||||
## 构建节点资产
|
||||
|
||||
生产节点组由 `uv run node-group build` 构建到 `src/anyimage/assets/O_AnyImage.blend`
|
||||
|
||||
节点组文件在 `tools/nodes/groups`
|
||||
|
||||
节点组规则：
|
||||
|
||||
- 字段默认直接连接，多个消费者可复用同一输出；按消费位置的几何、域、类型和输入属性版本验证求值等价性
|
||||
@@ -20,52 +35,9 @@
|
||||
- socket `subtype` 按业务语义设置：长度用 `DISTANCE`，`0–1` 比例用 `FACTOR`，`0–100` 用 `PERCENTAGE`；无对应范围语义时保留默认
|
||||
- 接口或布局变更须验证 socket 顺序与结构、未使用输出隐藏及几何求值；纯布局变更比较运算、默认值和实际连接，确认功能不变
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[字段生产与消费] --> B{需要按名称访问}
|
||||
B -->|是| C[命名属性]
|
||||
B -->|否| D{目标上下文重新求值是否等价}
|
||||
D -->|是| E[字段直连并显式转换域]
|
||||
D -->|否| F[调整消费顺序或在源几何采样]
|
||||
F --> G{仍需保存源数据}
|
||||
G -->|否| E
|
||||
G -->|是| H[仅存储必要命名数据]
|
||||
H --> I[最后消费者后精确清理]
|
||||
```
|
||||
|
||||
## 字段与临时属性
|
||||
|
||||
平滑循环按固定源位置查询原边界索引，并在当前边界网格上消费位置；拓扑不变的边界与影响权重直接求值。Depth Plane 由 UV 矩形判断原边界，Panorama 的闭合源球面以 False 表示原边界。
|
||||
|
||||
厚度构建使用源顶点索引排列构造网格，完成挤出与合并后按索引从源表面采样位置、厚度和法线。Depth Cutout 的中心、圆化、结构及膨胀字段在投影源表面求值。
|
||||
|
||||
| 属性 | 域 / 类型 | 写入与最后消费 |
|
||||
| --- | --- | --- |
|
||||
| `.o_anyimage_depth_cut` | CORNER / BOOLEAN | 三个深度组在 Split Edges 前保存切分标记，供投影调整射线，投影后精确清理 |
|
||||
| `.o_anyimage_original_boundary` | POINT / BOOLEAN | Depth Cutout 在切分前保存任意输入轮廓，供切口平滑保护原边界，平滑后精确清理 |
|
||||
| `UVMap` | CORNER / FLOAT2 | Image Plane 与 Panorama 的输出 UV，供材质读取 |
|
||||
| `o_normal_scale` | POINT 或 FACE / FLOAT | Cutout 输出法线掩码，Depth Cutout 合并背面与侧壁后统一写入，供形状和材质消费 |
|
||||
|
||||
|
||||
## 资产清单
|
||||
|
||||
| 节点组 | 构建模块 |
|
||||
| --- | --- |
|
||||
| `O Image Plane` | `image_plane.py` |
|
||||
| `O Image Depth Plane` | `image_depth_plane.py` |
|
||||
| `O Image Relief Plane` | `image_relief_plane.py` |
|
||||
| `O Image Layer` | `image_layer.py` |
|
||||
| `O Image Depth Layer` | `image_depth_layer.py` |
|
||||
| `O Shadeless` | `shadeless.py` |
|
||||
| `O Image Cutout` | `image_cutout.py` |
|
||||
| `O Image Depth Cutout` | `image_depth_cutout.py` |
|
||||
| `O Image Depth Balloon` | `image_depth_balloon.py` |
|
||||
| `O Image Depth Panorama` | `image_depth_panorama.py` |
|
||||
|
||||
|
||||
## 构建资产脚本
|
||||
|
||||
`tools/nodes/build.py` 按依赖顺序构建资产，调用 `arrangement/` 统一排列几何节点组后保存。`common/` 提供共用构建函数，`preview/` 导出交互预览。
|
||||
`tools/nodes/build.py` 按依赖顺序构建资产，调用 `arrangement/` 统一排列几何节点组后保存。`common/` 提供共用构建函数，其中 `material_slots.py` 继承几何材质槽，`shader.py` 构建材质着色节点，`preview/` 导出交互预览。
|
||||
|
||||
保存后，`check.py` 在独立 Blender 进程中重新加载资产并做基本几何求值。接口、默认值和详细几何行为由 `tests/` 检查。
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ AI 环境管理从当前安装状态出发，补齐独立运行环境和必需
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Entry["Set Up AI Environment"] --> Status["读取环境与必需模型状态"]
|
||||
Entry["Set Up AI Server"] --> Status["读取环境与必需模型状态"]
|
||||
Status --> Ready{"是否全部就绪？"}
|
||||
Ready -- "是" --> Done["结束"]
|
||||
Ready -- "否" --> Environment{"运行环境是否就绪？"}
|
||||
@@ -29,7 +29,7 @@ flowchart TD
|
||||
|
||||
环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和 Python 包的下载源，模型使用模型目录中声明的来源。
|
||||
|
||||
安装完成后继续进入模型下载，不在 Blender Python 中加载 ONNX Runtime 或模型依赖。
|
||||
安装完成后通过 `post_install()` 下载默认模型，模型依赖加载于独立 Server 环境。
|
||||
|
||||
### 下载模型
|
||||
|
||||
@@ -39,4 +39,4 @@ Job 在 `server/app.py` 注册；`server/model_catalog.py` 保存模型名称、
|
||||
|
||||
### 释放模型缓存
|
||||
|
||||
`ai_setup.py` 中的 `ClearModels` 调用 `runtime.clear_resource("model_manager")`，释放 Server 中已加载的模型 Session。它不会删除磁盘上的模型文件，下次推理仍可从现有文件重新加载。
|
||||
`ai_setup.py` 中的 `ClearModels` 调用 `runtime.clear_resource("model_manager")`，释放 Server 中已加载的模型 Session。下次推理从模型目录重新加载 Session。
|
||||
|
||||
14
docs/internals/operators/convert-to-panorama.md
Normal file
14
docs/internals/operators/convert-to-panorama.md
Normal file
@@ -0,0 +1,14 @@
|
||||
# Panorama 转换
|
||||
|
||||
`operators/convert_to_panorama/` 将静态 2:1 等距柱状 Image Empty 转换为径向深度表面。`operators.py` 提交任务，`object.py` 导入对象，`__init__.py` 汇总导出与注册清单。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[准备颜色与分析图] --> B[generate-panorama-geometry]
|
||||
B --> C[采样 12 个透视视图并推理]
|
||||
C --> D[融合径向距离与有效性]
|
||||
D --> E[写出 depth.exr 与 depth.json]
|
||||
E --> F[创建材质与 O Image Depth Panorama]
|
||||
```
|
||||
|
||||
任务使用 Preferences 选择的几何模型。源颜色由 Blender 侧保存，Server 的 `geometry/panorama.py` 负责视图采样与距离融合，`jobs/panorama.py` 编排推理和产物写入。
|
||||
@@ -1,23 +1,21 @@
|
||||
# Plane 转换
|
||||
|
||||
`operators/convert_to_plane/operators.py` 提供 `ConvertToPlane`、`ConvertToDepthPlane` 与 `GenerateDepthPlane`。对象和材质导入位于 `object.py`，基础矩形网格位于 `image_plane.py`。
|
||||
`operators/convert_to_plane/operators.py` 提供 `ConvertToPlane`、`ConvertToDepthPlane`、`ConvertToReliefPlane` 与 `GenerateDepthPlane`。`object.py` 导入对象和材质，`image_plane.py` 构建基础矩形网格，`__init__.py` 汇总导出与注册清单。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Image Empty] --> B{转换类型}
|
||||
B -- Plane --> C[复制 Color 与动画设置]
|
||||
C --> D[中心原点四边形与 O Image Plane]
|
||||
B -- Depth Plane --> E[检查静态图与 AI 就绪状态]
|
||||
E --> F[generate-depth-plane-geometry]
|
||||
F --> G[Color、depth.exr、depth.json、Tangent Normal]
|
||||
G --> H[加载并 Pack 数据]
|
||||
H --> I[O Image Depth Plane 与材质]
|
||||
D --> J[替换源 Empty 并保留世界位置]
|
||||
I --> J
|
||||
A[Image Empty] --> B[准备材质颜色]
|
||||
B --> C{转换类型}
|
||||
C -- Plane --> D[四边形与 O Image Plane]
|
||||
C -- Depth 或 Relief --> E[静态图提交几何 Job]
|
||||
E --> F[加载深度、元数据与法线]
|
||||
F --> G[对应节点修改器与材质]
|
||||
D --> H[创建对象并替换源 Empty]
|
||||
G --> H
|
||||
```
|
||||
|
||||
普通 Plane 支持图片、视频和序列，材质保留 Image User 帧设置。基础四边形以局部中心为原点，对象矩阵补偿原 Image Empty 显示范围；节点组生成细分与厚度，材质位于 Mesh 第 0 个槽。
|
||||
普通 Plane 支持图片、视频和序列，材质保留 Image User 帧设置。基础网格以局部中心为原点，对象矩阵补偿源 Empty 的显示范围。
|
||||
|
||||
Depth Plane 从 Preferences 取得 MoGe-2 模型、分辨率级别与 AI 输入上限，一次推理生成相机 XYZ 深度和切线法线。`create_depth_plane_from_result()` 创建颜色材质与深度修改器，并在失败时清理未使用的数据块。
|
||||
Depth 与 Relief 从 Preferences 读取几何模型、分辨率级别和 AI 输入上限。`create_depth_plane_from_result()` 导入产物并创建修改器。`O Image Depth Plane` 使用相机 XYZ 与对象空间法线构建深度表面；`O Image Relief Plane` 使用深度 Z 与切线空间法线构建浮雕。
|
||||
|
||||
`O Image Depth Plane` 提供默认 Relief 和 Camera：Relief 读取深度 Z 形成固定底面的地形；Camera 使用相机 XYZ 投影并沿平滑法线形成壳。两个模式各自保存 Thickness。完整接口见[节点资产](../node-assets.md)，文件协议见[Job 产物](../outputs.md)。
|
||||
节点构建见[节点资产](../node-assets.md)，文件协议见[Job 产物](../outputs.md)。
|
||||
|
||||
@@ -4,7 +4,7 @@ Cutout 在静态 Image Empty 上圈定 Selection，按轮廓创建 Flat、Solid
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Lasso 拖动并提交 SelectionPath] --> B[选择 Shape]
|
||||
A[Lasso 或 Polyline 提交 SelectionPath] --> B[选择 Shape]
|
||||
B --> C[栅格化 SelectionMask 并读取源 RGBA]
|
||||
C --> D{需要 Depth 或 Normal？}
|
||||
D -- 是 --> E[准备 bounds 矩形 RGBA]
|
||||
@@ -28,11 +28,13 @@ flowchart TD
|
||||
|
||||
`geometry.py` 从内容 Alpha 提取连通轮廓和孔洞，按 Mesh Detail 采样并生成 `BaseShape`。Low、Medium、High、Ultra 分别以 32、16、8、4 个源像素作为基础间距，并受 Maximum Cutout Mesh Resolution 限制。
|
||||
|
||||
`fine_mesh.py` 负责 Fine Outline 的细节保留与约束网格，`polygon.py` 提供轮廓运算。Balloon Profile 按 Preferences 选择 Poisson 或 Teddy，生成所有预设共用的 POINT 属性 `o_balloon`。
|
||||
`fine_mesh.py` 负责 Fine Outline 的细节保留与约束网格，`polygon.py` 提供轮廓运算。`balloon.py` 负责 Balloon Profile，按 Preferences 选择 Poisson 或 Teddy，生成所有预设共用的 POINT 属性 `o_balloon`。
|
||||
|
||||
`depth_calibration.py` 负责深度参考平面、尺度与方向校准；`geometry.py` 保留轮廓和网格生成。
|
||||
|
||||
## AI 与对象创建
|
||||
|
||||
Server 接收 Selection bounds 内保留源 Alpha 的 RGBA，一次 MoGe-2 推理按 `generate_depth` 与 `normal_mode` 返回产物。深度边缘延展使用所选 Alpha Threshold，Normal 使用原预测；AI 输入上限只影响分析分辨率。
|
||||
Server 接收 Selection bounds 内保留源 Alpha 的 RGBA，一次 MoGe 推理按 `generate_depth` 与 `normal_mode` 返回产物。深度参考区域使用所选 Alpha Threshold，Normal 使用原预测；AI 输入上限只影响分析分辨率。
|
||||
|
||||
`object.py` 的 `create_shape_object()` 消费 BaseShape、Color、Depth 和 Normal，加载对应节点组。基础网格位于局部 XY，向图片内部为 -Z；选择 +X 时节点与对象矩阵配对变换，保持世界几何一致。Object Normal 同步按方向转换。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Frame 多图合成
|
||||
|
||||
`operators/frame_tool.py` 定义 `FrameImages` 和 `FrameTool`。Frame 将选中的静态 Image Empty 按当前视图合成为一张图片。
|
||||
`operators/frame_tool/operators.py` 定义 `FrameImages` 和 `FrameTool`。`projection.py` 负责视图投影、交叠和结果平面定位，`compositing.py` 负责像素深度排序与边界覆盖采样，`__init__.py` 导出类型及注册清单。Frame 将选中的静态 Image Empty 按当前视图合成为一张图片。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
|
||||
@@ -5,11 +5,12 @@
|
||||
| `operators/ai_setup.py` | [AI 环境管理](ai-setup.md) |
|
||||
| `operators/clipboard_image/` | [剪贴板图片](clipboard-image.md) |
|
||||
| `operators/convert_to_plane/` | [Plane 与 Depth Plane](convert-to-plane.md) |
|
||||
| `operators/convert_to_panorama/` | [Panorama](convert-to-panorama.md) |
|
||||
| `operators/cutout_tool/` | [Cutout](cutout-tool.md) |
|
||||
| `operators/frame_tool.py` | [Frame 多图合成](frame.md) |
|
||||
| `operators/frame_tool/operators.py` | [Frame 多图合成](frame.md) |
|
||||
| `operators/mask_tool.py` | [Mask Alpha 编辑](mask.md) |
|
||||
| `operators/rectify_tool.py` | [Rectify 透视校正](rectify.md) |
|
||||
| `operators/rectify_tool/operators.py` | [Rectify 透视校正](rectify.md) |
|
||||
| `operators/remove_background.py` | [Remove Background](remove-background.md) |
|
||||
| `operators/upscale.py` | [Upscale](upscale.md) |
|
||||
|
||||
单文件功能按业务命名；复杂功能包在 `operators.py` 定义 Operator、对应 WorkSpaceTool 和入口协调逻辑，其余模块承载具体实现。包的 `__init__.py` 汇总导出，类型在 `operators/__init__.py` 和扩展 `__init__.py` 汇总注册。AI Operator 使用普通字典提交任务，并在主线程响应中读取文件和修改 Blender 数据。
|
||||
单文件功能按业务命名；复杂功能包在 `operators.py` 定义 Operator、对应 WorkSpaceTool 和入口协调逻辑，其余模块承载具体实现。包的 `__init__.py` 汇总导出与 `CLASSES` 注册清单，类型在 `operators/__init__.py` 和扩展 `__init__.py` 汇总注册。AI Operator 使用普通字典提交任务，并在主线程响应中读取文件和修改 Blender 数据。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Rectify 透视校正
|
||||
|
||||
`operators/rectify_tool.py` 定义 `RectifyImagePerspective` 与 `RectifyTool`，将图片内的四角区域校正为矩形。
|
||||
`operators/rectify_tool/operators.py` 定义 `RectifyImagePerspective` 与 `RectifyTool`，将图片内的四角区域校正为矩形。`geometry.py` 负责四角验证与像素校正，`preview.py` 负责预览图、Overlay 和宽高比控制，`__init__.py` 导出类型及注册清单。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
|
||||
@@ -1,37 +1,19 @@
|
||||
# Remove Background
|
||||
|
||||
Remove Background 从当前 Image Empty 准备单图或多帧输入，运行 BEN2 生成前景 Alpha，再用结果 Image 替换原图。
|
||||
|
||||
## 执行过程
|
||||
`operators/remove_background.py` 从 Image Empty 或当前 Shader Image Texture 准备输入。`RemoveImageBackground` 协调设置与输入，`RunBackgroundRemoval` 提交 Job 并应用结果。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Empty["Image Empty"] --> Prepare["准备图片、视频或序列输入"]
|
||||
Prepare --> Job["remove-background Job"]
|
||||
Job --> Frames["逐帧运行 BEN2"]
|
||||
Frames --> Result["写出 PNG 结果序列"]
|
||||
Result --> Import["创建结果 Image"]
|
||||
Import --> Replace["替换 Empty.data"]
|
||||
A[ImageEditTarget 取得编辑目标] --> B[准备图像输入]
|
||||
B --> C[remove-background Job]
|
||||
C --> D[所选背景模型生成前景 Alpha]
|
||||
D --> E{输入类型}
|
||||
E -- 普通媒体 --> F[PNG 结果序列]
|
||||
E -- HDR --> G[alpha.npy]
|
||||
F --> H[应用结果与 Undo]
|
||||
G --> H
|
||||
```
|
||||
|
||||
Packed 图片和内存中修改过的单图会先导出临时文件；文件图片、视频和序列沿用原路径。
|
||||
`server/jobs/remove_background.py` 展开媒体并调用 `server/models/background.py`，支持 BiRefNet 和 BEN2。模型前景 Alpha 与源 Alpha 合成。
|
||||
|
||||
## 节点说明
|
||||
|
||||
### 准备媒体输入
|
||||
|
||||
入口是 `operators/remove_background.py` 中的 `RemoveImageBackground`。它检查当前对象、AI Environment 和帧数，再调用 `common/image.py` 的 `prepare_image_input()`。多帧输入会先写入 Scene 中的抽帧设置。
|
||||
|
||||
准备完成后，内部 Operator `RunBackgroundRemoval` 保存输入路径、源对象名和临时文件清理标记。
|
||||
|
||||
### 运行 BEN2
|
||||
|
||||
`RunBackgroundRemoval` 提交 `remove-background` Job。`server/jobs/remove_background.py` 使用公共媒体输入层展开单图、视频或序列，并逐帧调用 `server/models/ben2.py`。
|
||||
|
||||
BEN2 推理前先用源 Alpha 屏蔽透明区域，模型输出的前景 Alpha 再与源 Alpha 合成，RGB 保持源图内容。多帧结果按连续文件名写入 Job 目录。
|
||||
|
||||
### 导入并替换结果
|
||||
|
||||
Job 返回后，`remove_background.py` 的 `apply_background_response()` 调用 `common/image.py` 创建单图或序列 Image，并恢复源 Image User 的帧起点、偏移和循环设置。
|
||||
|
||||
`replace_empty_image()` 随后替换 `Empty.data`，提交一个 Remove Background Undo 步骤，并清理本次创建的临时输入。
|
||||
普通结果通过 `ImageEditTarget` 保留共享图像引用与帧设置。HDR 使用 `common/hdr_image.py` 的 `HdrBackgroundInput` 准备分析输入，并将返回 Alpha 应用于原浮点 RGB。Operator 负责临时输入清理。
|
||||
|
||||
@@ -1,21 +1,15 @@
|
||||
# Upscale
|
||||
|
||||
`operators/upscale.py` 从当前 Image Empty 生成 2× 结果并替换原图，支持单图、视频与序列帧。
|
||||
`operators/upscale.py` 从 Image Empty 或当前 Shader Image Texture 生成 2× 结果。普通媒体支持单图、视频和序列帧。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[检查源图长边小于 AI 输入上限] --> B[冻结 Preferences 模型与尺寸设置]
|
||||
B --> C[准备媒体输入]
|
||||
C --> D[upscale-image 逐帧处理]
|
||||
D --> E{所选模型}
|
||||
E -- Real-ESRGAN 或 SAFMN --> F[256×256 tile 与边缘上下文执行 4× RGB 推理]
|
||||
E -- PiSA-SR --> G[分阶段生成推理，细节强度 0.7]
|
||||
F --> H[统一缩放到源图 2×]
|
||||
G --> H
|
||||
H --> I[原 Alpha 独立 Lanczos 缩放并回填]
|
||||
I --> J[写出 upscale 序列并替换 Image]
|
||||
A[检查源图尺寸并冻结模型设置] --> B[准备媒体输入]
|
||||
B --> C[upscale-image 逐帧处理]
|
||||
C --> D[分块执行 4× RGB 推理]
|
||||
D --> E[统一缩放为源图 2×]
|
||||
E --> F[原 Alpha 独立 Lanczos 缩放]
|
||||
F --> G[ImageEditTarget 应用结果并提交 Undo]
|
||||
```
|
||||
|
||||
`server/models/upscale.py` 统一处理输入上限、模型分派和最终 RGB/Alpha 尺寸。`onnx_upscale.py` 处理常规 4× 模型，`onnx_pisa_sr.py` 处理 PiSA-SR。多帧与多 tile 只在最后一次运行请求内存收缩。
|
||||
|
||||
Provider 资源错误会释放当前 Upscale Session，并返回降低输入上限或切换 CPU 的提示。响应通过 `common/image.py` 加载、Pack、保留图像共享与帧设置，并提交 Undo。
|
||||
`server/models/upscale.py` 处理输入上限和最终尺寸，`onnx_upscale.py` 执行 Real-ESRGAN 与 HAT 模型。ModelManager 管理 Session；Provider 资源错误会释放当前 Session 并返回处理建议。
|
||||
|
||||
@@ -1,43 +1,40 @@
|
||||
# Job 产物
|
||||
|
||||
Server 把结果写入 Job 目录，返回以相对文件名为值的字典。Blender 主线程通过 JobResult 读取文件，再创建或更新 Image、Mesh、Material 和 Object。
|
||||
Server 将结果写入 Job 目录，返回以相对文件名为值的字典。Blender 主线程通过 JobResult 读取文件，创建或更新 Image、Mesh、Material 和 Object。
|
||||
|
||||
| Job | 文件 | 消费方 |
|
||||
| --- | --- | --- |
|
||||
| `remove-background` | `image.0001.png` 起 | Image Empty 替换 |
|
||||
| `upscale-image` | `upscale.0001.png` 起 | 2× Image Empty 替换 |
|
||||
| `generate-depth-plane-geometry` | `image.0001.*`、`depth.exr`、`depth.json`、`tangent-normal.png` | Plane 对象与材质 |
|
||||
| `generate-cutout-artifacts` | 按请求提供深度、元数据和法线 | Cutout 对象与材质 |
|
||||
| `remove-background` | PNG 序列或 `alpha.npy` | ImageEditTarget 或 HDR Alpha 编辑 |
|
||||
| `upscale-image` | `upscale.0001.png` 起 | 图像替换 |
|
||||
| `generate-depth-plane-geometry` | `depth.exr`、`depth.json` 和法线 | Depth / Relief Plane |
|
||||
| `generate-cutout-artifacts` | 按请求提供深度、元数据和法线 | Cutout |
|
||||
| `generate-panorama-geometry` | `depth.exr`、`depth.json` | Panorama |
|
||||
|
||||
## 深度与法线协议
|
||||
|
||||
| 返回字段 | 文件 | 内容 |
|
||||
| --- | --- | --- |
|
||||
| `depth` | `depth.exr` | float32 RGB 保存相机空间 XYZ，Alpha 保存 Validity |
|
||||
| `depth_metadata` | `depth.json` | `image_size`、3×3 `intrinsics`、`reference_depth` |
|
||||
| `tangent_normal` | `tangent-normal.png` | 切线空间法线 |
|
||||
| `object_normal` | `object-normal.png` | Cutout 原生 XY / Z 坐标的对象空间法线 |
|
||||
| 返回字段 | 内容 |
|
||||
| --- | --- |
|
||||
| `depth` | float32 EXR，透视产物 RGB 保存相机空间 XYZ，Alpha 保存源 Alpha × 模型有效性 |
|
||||
| `depth_metadata` | JSON，透视产物包含 `image_size`、3×3 `intrinsics`、`reference_depth` |
|
||||
| `tangent_normal` | `tangent-normal.png`，切线空间法线 |
|
||||
| `object_normal` | `object-normal.png`，对象空间法线 |
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[矩形源 RGBA] --> B[限尺寸并合成黑底模型输入]
|
||||
B --> C[MoGe-2 GeometryFrame]
|
||||
C --> D[原预测生成 Normal]
|
||||
C --> E{Cutout 深度？}
|
||||
E -- 是 --> F[按源 Alpha 延展轮廓深度]
|
||||
E -- 否 --> G[完整相机 Points]
|
||||
F --> G
|
||||
G --> H[depth.exr 与 depth.json]
|
||||
D --> I[Blender 加载并 Pack]
|
||||
H --> I
|
||||
A[源 RGB 与 Alpha] --> B[限尺寸 RGB 推理]
|
||||
B --> C[GeometryFrame]
|
||||
C --> D[写出深度与法线]
|
||||
A --> E[Alpha 有效性与参考区域]
|
||||
E --> D
|
||||
D --> F[Blender 加载并 Pack]
|
||||
```
|
||||
|
||||
`depth_texture.py` 保存完整有限 Points；模型 Mask 转为 `0/1` Validity。参考深度取有效、有限、正深度且满足源 Alpha 条件的样本中位数：整图使用 Alpha ≥ 0.1，Cutout 使用所选 Alpha Threshold 并要求 Alpha > 0。非法字段和空参考区域抛出错误。
|
||||
参考深度取满足模型有效性、有限正深度与 Alpha 阈值的样本中位数。`common/depth.py` 加载 EXR，设置 Non-Color 和 CHANNEL_PACKED。Depth Plane 使用对象空间法线，Relief Plane 使用切线空间法线。
|
||||
|
||||
`common/depth.py` 加载深度并配置 Non-Color、CHANNEL_PACKED 与 Pack。Relief 和 Depth Balloon 读取 B/Z，Camera 与 Depth Solid 读取 XYZ，共用同一 EXR。
|
||||
Panorama 的 EXR RGB 保存径向距离，Alpha 保存源 Alpha 与融合有效性；元数据包含 `projection: equirectangular` 和 `image_size`。
|
||||
|
||||
## Selection 与颜色
|
||||
## 颜色与图像编辑
|
||||
|
||||
Cutout 提交几何 bounds 内的原始 RGBA。Blender 在创建网格时组合源 Alpha 和 `SelectionMask`；颜色图保留矩形源 RGBA，法线可见区域取源 Alpha。AI 分析尺寸与颜色分辨率分别处理。
|
||||
`common/color_image.py` 为 Plane、Panorama 和 Cutout 准备独立的材质颜色与 AI 分析输入。Cutout 使用 Selection bounds 内的源图；网格创建时组合源 Alpha 与 SelectionMask。颜色分辨率与分析尺寸分别处理。
|
||||
|
||||
Remove Background、Upscale、Frame、Mask、Rectify 通过 `common/image.py` 的编辑结果入口保留源 Image 名称和共享引用语义。Plane 与 Cutout 的材质贴图使用 Color、Depth、Normal 命名函数。
|
||||
`ImageEditTarget` 统一 Image Empty 和 Shader Image Texture 的编辑目标及共享引用。HDR 去背景通过 `HdrBackgroundInput` 保留 Blender 浮点 RGB，并应用 Server 返回的连续 Alpha。
|
||||
|
||||
@@ -1,53 +1,36 @@
|
||||
# Job Runtime 与 Server
|
||||
|
||||
`runtime.py` 配置 BlendJob `JobRuntime` 和独立 Python 3.12 Environment。`server/app.py` 注册 Job，`model_manager.py` 作为 `model_manager` Resource 管理下载文件与缓存 Session。
|
||||
`runtime.py` 配置 BlendJob `JobRuntime` 和独立 Python 3.12 Environment。`server/app.py` 注册 Job，`model_manager.py` 管理模型文件与缓存 Session。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Operator request] --> B[JobRuntime]
|
||||
B --> C[Server 单 Worker 队列]
|
||||
C --> D[Job 调用媒体与模型模块]
|
||||
D --> E[写入 jobs/job-id 目录]
|
||||
E --> F[主线程 response]
|
||||
A[Operator request] --> B[JobRuntime 队列]
|
||||
B --> C[Server Job 调用媒体与模型模块]
|
||||
C --> D[写入 Job 目录]
|
||||
D --> E[主线程 response 导入结果]
|
||||
```
|
||||
|
||||
Job 在阶段和帧边界检查取消，进度通过 `context.progress()` 返回。视频临时帧由 `media/input.py` 的上下文管理器清理，Blender 导出的临时输入由对应 Operator 清理。
|
||||
|
||||
## Job 与数据模块
|
||||
|
||||
| Job | 实现与用途 |
|
||||
| --- | --- |
|
||||
| `download-model`、`download-required-models` | `app.py` 调用 ModelManager 下载单个或缺失模型 |
|
||||
| `remove-background` | `jobs/remove_background.py`，生成 BEN2 前景 |
|
||||
| `upscale-image` | `jobs/upscale.py`，生成 2× 图像或序列 |
|
||||
| `generate-depth-plane-geometry` | `jobs/depth_plane.py`，复制整图颜色并生成深度、元数据与切线法线 |
|
||||
| `generate-cutout-artifacts` | `jobs/cutout.py`，按请求生成 Cutout 深度和法线 |
|
||||
| `download-model`、`download-required-models` | `app.py` 下载单个或缺失模型 |
|
||||
| `remove-background` | `jobs/remove_background.py` 生成前景 Alpha |
|
||||
| `upscale-image` | `jobs/upscale.py` 生成 2× 图像或序列 |
|
||||
| `generate-depth-plane-geometry` | `jobs/depth_plane.py` 生成深度、元数据和法线 |
|
||||
| `generate-cutout-artifacts` | `jobs/cutout.py` 按请求生成深度和法线 |
|
||||
| `generate-panorama-geometry` | `jobs/panorama.py` 生成全景径向深度 |
|
||||
|
||||
`media/` 处理单图、序列、视频与输入尺寸。Depth Plane 和 Cutout 按单张静态图片工作；Remove Background 与 Upscale 逐帧处理动画输入。
|
||||
`media/` 展开单图、序列与视频，并限制分析尺寸。Job 在阶段与帧边界检查取消，通过 `context.progress()` 返回进度。媒体上下文清理抽取的临时帧，Operator 清理 Blender 导出的临时输入。
|
||||
|
||||
`geometry/prediction_artifacts.py` 将限尺寸后的 RGBA 合成到黑底，运行一次 MoGe-2，再调用深度、法线和元数据写入器。Cutout 的深度分支通过 `edge_depth.py` 延展轮廓附近的深度；法线使用原预测。文件字段见 [Job 产物](outputs.md)。
|
||||
`geometry/prediction_artifacts.py` 缩放源 RGB 后运行一次 MoGe，将同一预测交给深度、法线和元数据写入器。源 Alpha 用于产物有效性和参考深度采样。文件协议见 [Job 产物](outputs.md)。
|
||||
|
||||
## 模型与缓存
|
||||
|
||||
| 用途 | 模型 | Session 分类 |
|
||||
| --- | --- | --- |
|
||||
| Depth 与 Normal | MoGe-2 ViT-S / ViT-B / ViT-L Normal | geometry |
|
||||
| Remove Background | BEN2 | ben2 |
|
||||
| Upscale | Real-ESRGAN WDN、SAFMN、Real-ESRGAN x4plus、PiSA-SR | upscale |
|
||||
| Depth 与 Normal | MoGe-2 ViT-S / ViT-B Normal、MoGe-3 ViT-L | geometry |
|
||||
| Remove Background | BiRefNet Lite、BEN2、BiRefNet HR Matting | background |
|
||||
| Upscale | Real-ESRGAN WDN、Real-ESRGAN x4plus、HAT GAN x4 Sharper | upscale |
|
||||
|
||||
`model_catalog.py` 声明文件来源、许可、大小和 SHA-256。`model_download.py` 下载文件并校验；ModelManager 按模型路径和设备缓存各类最近使用的 Session，切换模型或设备时释放对应类别。
|
||||
`model_catalog.py` 声明文件来源、许可、大小和 SHA-256；`model_download.py` 下载并校验。ModelManager 按模型路径和设备缓存 Session，切换模型或设备时释放对应类别。Clear Models 或关闭 Server 时释放已加载资源。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[取得缓存 Session] --> B[运行单图、多帧或 tile]
|
||||
B --> C[最后一次推理]
|
||||
C --> D[CUDA 收缩空闲 arena]
|
||||
D --> E[保留 Session 供后续复用]
|
||||
E --> F[Clear Models 或关闭 Server 时释放]
|
||||
```
|
||||
|
||||
Windows 默认 DirectML，macOS arm64 默认 CPU 并支持选择 CoreML。MoGe-2 为 CoreML 配置静态 shape 分区，其余计算由 CPU 执行。PiSA-SR 在 CoreML 上返回明确的支持限制；其分阶段 Session 在切换阶段、取消和清理时关闭。
|
||||
|
||||
## Environment 与存储
|
||||
|
||||
首次安装通过 `post_install()` 下载默认 MoGe-2、BEN2 与 Real-ESRGAN WDN。Storage Root 默认 `~/.anyimage`，其中保存 `.venv/`、`models/`、`jobs/` 及环境状态和日志。设置入口与安装流程见 [AI 环境管理](operators/ai-setup.md)。
|
||||
首次安装通过 `post_install()` 下载默认 MoGe-2、BiRefNet Lite 与 Real-ESRGAN WDN。Storage Root 默认 `~/.anyimage`，保存环境、模型、Job 产物和日志。设置入口见 [AI 环境管理](operators/ai-setup.md)。
|
||||
|
||||
Reference in New Issue
Block a user