icrdr/AnyImage
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update architecture and operator documentation for clarity and accuracy

Browse Source
This commit is contained in:
马南
2026-09-16 10:44:19 +08:00
parent 7f878a2f3f
commit 6ca084ee4a
16 changed files with 67 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/internals/operators/ai-setup.md
View File

@@ -27,7 +27,7 @@ flowchart TD
### 安装独立环境
环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和 Python 包的下载源，模型使用模型目录中声明的来源。
环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和安装包的下载源，模型使用模型目录中声明的来源。
安装完成后通过 `post_install()` 下载默认模型，模型依赖加载于独立 Server 环境。

6
docs/internals/operators/clipboard-image.md
View File

@@ -16,19 +16,19 @@ flowchart TD
Target --> Paint["Brush Texture"]
```
快捷键优先处理 Blender 自己的 Copy/Paste；系统剪贴板出现新的图片内容时，AnyImage 接管粘贴。
Windows 快捷键优先处理 Blender 自己的 Copy/Paste，系统剪贴板出现新的图片内容时 AnyImage 接管粘贴；macOS 和 Linux 没有系统剪贴板序列号，始终由 AnyImage 处理粘贴。
## 节点说明
### 判断是否交给 Blender
`operators/clipboard_image/operators.py` 定义 `TrackNativeCopy`、`PasteClipboardImage` 和 3D View、Node Editor 快捷键。`TrackNativeCopy` 记录 Blender Copy 时的系统剪贴板变化标记；粘贴时若标记没有变化，`PasteClipboardImage` 返回 `PASS_THROUGH`，让 Blender 继续处理对象或节点粘贴。
`operators/clipboard_image/operators.py` 定义 `TrackNativeCopy`、`PasteClipboardImage` 和 3D View、Node Editor 快捷键。`TrackNativeCopy` 记录 Blender Copy 时的系统剪贴板序列号；粘贴时若序列号没有变化，`PasteClipboardImage` 返回 `PASS_THROUGH`，让 Blender 继续处理对象或节点粘贴。
同一文件随后调用 `actions.target_for_context()` 判断当前编辑器是否支持图片落点。
### 读取系统图片
`clipboard.py` 负责平台差异。Windows 读取 DIB 或 DIBV5 并补成 BMP；macOS 和 Linux 调用系统提供的图片导出命令。各平台输出统一为图片字节和扩展名，再交给后续步骤。
`clipboard.py` 负责平台差异。Windows 依次尝试 PNG、DIBV5 和 DIB，DIB 补成 BMP；macOS 通过 `osascript` 导出 PNG；Linux 依次尝试 `wl-paste` 和 `xclip` 提供的图片格式。各平台输出统一为图片字节和扩展名，再交给后续步骤。
### 创建或复用 Packed Image

2
docs/internals/operators/convert-to-panorama.md
View File

@@ -1,6 +1,6 @@
# Panorama 转换
`operators/convert_to_panorama/` 将静态 2:1 等距柱状 Image Empty 转换为径向深度表面。`operators.py` 提交任务，`object.py` 导入对象，`__init__.py` 汇总导出与注册清单。
`operators/convert_to_panorama/` 将静态等距柱状 Image Empty 转换为径向深度表面，提交前裁剪出最大居中 2:1 区域。`operators.py` 提交任务，`object.py` 导入对象，`__init__.py` 汇总导出与注册清单。
```mermaid
flowchart TD

2
docs/internals/operators/convert-to-plane.md
View File

@@ -14,7 +14,7 @@ flowchart TD
G --> H
```
普通 Plane 支持图片、视频和序列，材质保留 Image User 帧设置。基础网格以局部中心为原点，对象矩阵补偿源 Empty 的显示范围。
三种转换都只接受静态图片。基础网格以局部中心为原点，对象矩阵补偿源 Empty 的显示范围。
Depth 与 Relief 从 Preferences 读取几何模型、分辨率级别和 AI 输入上限。`create_depth_plane_from_result()` 导入产物并创建修改器。`O Image Depth Plane` 使用相机 XYZ 与对象空间法线构建深度表面；`O Image Relief Plane` 使用深度 Z 与切线空间法线构建浮雕。

32
docs/internals/operators/cutout-tool.md
View File

@@ -1,6 +1,6 @@
# Cutout
Cutout 在静态 Image Empty 上圈定 Selection，按轮廓创建 Flat、Solid、Depth Solid 或 Depth Balloon。入口位于 `operators/cutout_tool/operators.py`，菜单与采样级别映射位于 `interaction.py`，标识和资产对应关系位于 `shape.py`。
Cutout 在静态 Image Empty 上圈定 Selection，按轮廓创建 Flat、Solid、Depth Symmetry 或 Depth Solid。入口位于 `operators/cutout_tool/operators.py`，Shape 菜单位于 `interaction.py`，预设标识与节点组对应关系位于 `shape.py`。
```mermaid
flowchart TD
@@ -10,32 +10,34 @@ flowchart TD
D -- 是 --> E[准备 bounds 矩形 RGBA]
E --> F[generate-cutout-artifacts]
F --> G[加载 Depth、Metadata 与 Normal]
G --> H[源 Alpha 与 SelectionMask 组合]
D -- 否 --> H
H --> I[轮廓、采样、约束三角化与 o_balloon]
I --> J[BaseShape]
D -- 否 --> H[源 Alpha 与 SelectionMask 组合]
G --> H
H --> I[边界映射、轮廓提取与质量三角化]
I --> J[BaseShape 与 o_balloon]
J --> K[创建材质、对象与对应节点修改器]
```
| 预设 | 节点组 | AI 产物 |
| --- | --- | --- |
| Flat | `O Image Cutout`，Thickness 0 | 可选 Tangent Normal |
| Solid | `O Image Cutout`，Thickness 1 | 可选 Tangent Normal |
| Depth Solid | `O Image Depth Cutout` | Depth 与 Object Normal |
| Depth Balloon | `O Image Depth Balloon` | Depth 与 Tangent Normal |
| Flat | `O Image Cutout`，Thickness 0 | 可选切线空间法线 |
| Solid | `O Image Cutout`，Thickness 1 | 可选切线空间法线 |
| Depth Symmetry | `O Image Depth Cutout` 与 `O Image Cutout Symmetry` | 深度与对象空间法线 |
| Depth Solid | `O Image Depth Cutout` | 深度与对象空间法线 |
Flat 与 Solid 可以不带 AI 产物生成；Depth 预设和 Normal Map 需要就绪的几何模型，Shape 菜单按该状态提供选项。
## 轮廓与网格
`geometry.py` 从内容 Alpha 提取连通轮廓和孔洞，按 Mesh Detail 采样并生成 `BaseShape`。Low、Medium、High、Ultra 分别以 32、16、8、4 个源像素作为基础间距，并受 Maximum Cutout Mesh Resolution 限制。
`geometry.py` 从内容 Alpha 提取连通轮廓与孔洞，按 Edge Length 生成 `BaseShape`。Edge Length 是世界空间的网格目标边长，Minimum Relative Edge Length 会按内容范围提高其下界。
`fine_mesh.py` 负责 Fine Outline 的细节保留与约束网格，`polygon.py` 提供轮廓运算。`balloon.py` 负责 Balloon Profile，按 Preferences 选择 Poisson 或 Teddy，生成所有预设共用的 POINT 属性 `o_balloon`。
`mesh.py` 负责轮廓分离、孔洞处理、质量三角化和边界支撑，`polygon.py` 提供轮廓简化，`tangle.py` 是随包分发的 Delaunay 三角化核心。Fine Outline 展开时保留小孔与细节轮廓，关闭时填洞并简化。
`depth_calibration.py` 负责深度参考平面、尺度与方向校准；`geometry.py` 保留轮廓和网格生成。
`balloon.py` 负责 Balloon Profile，按 Preferences 选择 Poisson 或 Teddy，生成所有预设共用的 POINT 属性 `o_balloon`。`boundary_padding.py` 按 Boundary Padding 沿结构内法线重采样轮廓附近的颜色与深度。
## AI 与对象创建
Server 接收 Selection bounds 内保留源 Alpha 的 RGBA，一次 MoGe 推理按 `generate_depth` 与 `normal_mode` 返回产物。深度参考区域使用所选 Alpha Threshold，Normal 使用原预测；AI 输入上限只影响分析分辨率。
Server 接收 Selection bounds 内保留源 Alpha 的 RGBA，一次 MoGe 推理按 `generate_depth` 与 `normal_mode` 返回产物。深度参考区域使用所选 Alpha Threshold，Normal 使用原预测；Maximum AI Input Size 只影响分析分辨率。
`object.py` 的 `create_shape_object()` 消费 BaseShape、Color、Depth 和 Normal，加载对应节点组。基础网格位于局部 XY，向图片内部为 -Z；选择 +X 时节点与对象矩阵配对变换，保持世界几何一致。Object Normal 同步按方向转换。
`object.py` 的 `create_shape_object()` 消费 BaseShape、Color、Depth 和 Normal，加载对应节点组。基础网格位于局部 XZ 平面，厚度沿 Y 展开；对象矩阵把网格放入 Image Empty 的图片平面，Depth Symmetry 额外叠加对称节点组与方向参数。Object Normal 随方向同步转换。
材质使用 IOR 1.2，颜色进入 Image Layer，`o_normal_scale` 控制法线影响。Depth Solid 使用正面 FACE 标记，其他适用预设使用轮廓权重。节点计算见[节点资产](../node-assets.md)。
材质使用 IOR 1.2，颜色与法线接入 Image Layer，法线按切线或对象空间解释。节点计算见[节点资产](../node-assets.md)。

2
docs/internals/operators/index.md
View File

@@ -13,4 +13,4 @@
| `operators/remove_background.py` | [Remove Background](remove-background.md) |
| `operators/upscale.py` | [Upscale](upscale.md) |
单文件功能按业务命名；复杂功能包在 `operators.py` 定义 Operator、对应 WorkSpaceTool 和入口协调逻辑，其余模块承载具体实现。包的 `__init__.py` 汇总导出与 `CLASSES` 注册清单，类型在 `operators/__init__.py` 和扩展 `__init__.py` 汇总注册。AI Operator 使用普通字典提交任务，并在主线程响应中读取文件和修改 Blender 数据。
单文件功能按业务命名；复杂功能包在 `operators.py` 定义 Operator 和入口协调逻辑，交互式工具同时定义 WorkSpaceTool，其余模块承载具体实现。包的 `__init__.py` 汇总导出与 `CLASSES` 注册清单，类型在 `operators/__init__.py` 和扩展 `__init__.py` 汇总注册。AI Operator 使用普通字典提交任务，并在主线程响应中读取文件和修改 Blender 数据。

2
docs/internals/operators/mask.md
View File

@@ -15,7 +15,7 @@ flowchart TD
| 模式 | 源 Alpha A 与覆盖 M 的结果 |
| --- | --- |
| Set | `A × M` |
| Add | `max(A, M)` |
| Extend | `max(A, M)` |
| Subtract | `A × (1 − M)` |
Brush 拖动时维护简化屏幕路径、圆形印记与连接条的并集预览；释放时一次生成图片覆盖。Polyline 使用逐点路径，至少三个点后通过闭合圈、双击或 Enter 完成，Backspace 删除末点。

4
docs/internals/operators/remove-background.md
View File

@@ -8,12 +8,12 @@ flowchart TD
B --> C[remove-background Job]
C --> D[所选背景模型生成前景 Alpha]
D --> E{输入类型}
E -- 普通媒体 --> F[PNG 结果序列]
E -- 普通图片 --> F[透明 PNG 前景]
E -- HDR --> G[alpha.npy]
F --> H[应用结果与 Undo]
G --> H
```
`server/jobs/remove_background.py` 展开媒体并调用 `server/models/background.py`，支持 BiRefNet 和 BEN2。模型前景 Alpha 与源 Alpha 合成。
`server/jobs/remove_background.py` 读取单张输入并调用 `server/models/background.py`，支持 BiRefNet 和 BEN2。模型前景 Alpha 与源 Alpha 合成。
普通结果通过 `ImageEditTarget` 保留共享图像引用与帧设置。HDR 使用 `common/hdr_image.py` 的 `HdrBackgroundInput` 准备分析输入，并将返回 Alpha 应用于原浮点 RGB。Operator 负责临时输入清理。

6
docs/internals/operators/upscale.md
View File

@@ -1,11 +1,11 @@
# Upscale
`operators/upscale.py` 从 Image Empty 或当前 Shader Image Texture 生成 2× 结果。普通媒体支持单图、视频和序列帧。
`operators/upscale.py` 从 Image Empty 或当前 Shader Image Texture 生成 2× 结果，源图长边必须小于 Maximum AI Input Size。
```mermaid
flowchart TD
A[检查源图尺寸并冻结模型设置] --> B[准备媒体输入]
B --> C[upscale-image 逐帧处理]
A[检查源图尺寸并冻结模型设置] --> B[准备图片输入]
B --> C[upscale-image 单张处理]
C --> D[分块执行 4× RGB 推理]
D --> E[统一缩放为源图 2×]
E --> F[原 Alpha 独立 Lanczos 缩放]