nan
87d7721128
- 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.
70 lines
4.2 KiB
Markdown
70 lines
4.2 KiB
Markdown
# 程序架构
|
||
|
||
AnyImage 由 Blender 交互层、BlendJob Runtime 和独立 Job Server 三部分组成。这个分层让 Blender Python 不需要加载 ONNX Runtime、Pillow 或模型权重，同时保证所有 Blender 数据仍在主线程创建和修改。
|
||
|
||
## 对应文件
|
||
|
||
```text
|
||
src/anyimage/
|
||
├── __init__.py # 类型、工具、菜单与 Runtime 注册
|
||
├── menu.py # Image Empty 上下文入口
|
||
├── panel.py # Server 与 Debug 面板
|
||
├── preferences.py # Storage Root、Device 与功能默认值
|
||
├── properties.py # Scene 状态、模型状态与动态枚举
|
||
├── runtime.py # Environment 和 JobRuntime
|
||
├── operators/ # Blender 侧业务入口
|
||
└── server/ # 独立计算端
|
||
```
|
||
|
||
## 职责边界
|
||
|
||
| 层次 | 负责 | 不负责 |
|
||
| --- | --- | --- |
|
||
| Blender 交互层 | UI、手势、RNA 状态、输入准备、结果导入、Undo | 在 Blender 进程加载 AI 依赖 |
|
||
| BlendJob Runtime | Environment、Server 生命周期、队列、进度、取消、Job 目录 | AnyImage 的图像与几何业务 |
|
||
| Job Server | 媒体解码、ONNX 推理、数组派生、文件输出 | 创建 Blender 对象或访问 `bpy` |
|
||
|
||
Operator 向 Server 发送普通字典。Server 返回文件名和 Job 目录；Operator 的 `response()` 再读取这些文件，并在 Blender 主线程中创建 Image、Mesh、Material 和 Geometry Nodes Modifier。
|
||
|
||
## 注册与状态
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
Register["anyimage.register()"] --> Types["注册 Preferences / PropertyGroup / Operator / Panel"]
|
||
Types --> Tools["注册 Image Tools 与 Cutout WorkspaceTool"]
|
||
Tools --> RNA["挂载 Scene 与 Image Property"]
|
||
RNA --> Menu["挂载上下文菜单和剪贴板快捷键"]
|
||
Menu --> Runtime["注册 JobRuntime"]
|
||
```
|
||
|
||
`__init__.py` 按依赖顺序注册，并在注销时逆序清理。扩展级设置统一由 `preferences.addon_preferences()` 读取；`runtime.py` 只消费 `configured_storage_root` 回调，不持有 Blender 偏好设置的定位逻辑。交互中的临时状态和 Debug 参数保存在 `Scene.anyimage_settings`。`max_ai_input_size` 与 `max_cutout_mesh_resolution` 都在 `preferences.py` 定义与读取：前者由 Operator 冻结到 AI Job 请求，后者在 Blender 侧统一限制所有 Cutout Shape 的网格采样密度。Upscale 还用 AI 输入上限判断当前 Image 是否允许执行。
|
||
|
||
## 同步与异步路径
|
||
|
||
无需 AI 或媒体处理的功能直接在 Blender 中完成，例如 Plane、普通 Image Mask、Perspective，以及未启用 Fit to Foreground / Generate Normal Map 的 Surface 和 Balloon。需要模型或独立文件处理时，功能 Operator 派生自 `JobOperatorBase`：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User as 用户
|
||
participant Op as Blender Operator
|
||
participant RT as JobRuntime
|
||
participant Job as Server Job
|
||
User->>Op: 执行功能
|
||
Op->>Op: 准备文件与普通字典
|
||
Op->>RT: 提交 Job
|
||
RT->>Job: 排队执行
|
||
Job-->>RT: 写入产物并返回索引
|
||
RT-->>Op: 主线程 response
|
||
Op->>Op: 导入数据并提交 Undo
|
||
```
|
||
|
||
这条边界也决定了模块依赖方向：`server/` 不导入 `bpy` 或 `operators/`；Blender 侧可以读取 Server 产物，但不会复用 Server 中的 Blender 无关算法来创建 RNA 数据。
|
||
|
||
## 共享能力 { #shared-capabilities }
|
||
|
||
`operators/common/` 只保存多个生产功能真实复用的稳定原子能力；完整工作流、功能参数和专用算法留在所属模块。公共层不保留旧路径转发函数，也不为了测试或资产工具建立入口。
|
||
|
||
全部可由功能模块调用的函数见[Common 公共函数](common.md)。该索引只列 `common/` 外部的生产调用，不重复列出公共模块内部辅助函数；创建新功能前先核对该页，避免重新实现 Image 引用分流、像素方向、Job 输入生命周期、数据块命名、节点资产加载和对象激活逻辑。
|
||
|
||
新增公共函数前应确认至少有两个真实消费者，或它是两个公共流程共同依赖的原子能力。只有单一功能使用的逻辑应留在所属模块；删除或移动能力时同步清理注册、测试、工具脚本和文档，不保留兼容胶水。
|