From 6ca084ee4ac2b2162b08a3ac03a807305aef0097 Mon Sep 17 00:00:00 2001 From: nan Date: Wed, 16 Sep 2026 10:44:19 +0800 Subject: [PATCH] docs: update architecture and operator documentation for clarity and accuracy --- docs/internals/architecture.md | 6 ++-- docs/internals/common.md | 8 ++--- docs/internals/development.md | 6 ++-- docs/internals/index.md | 2 -- docs/internals/node-assets.md | 30 +++++++++-------- docs/internals/operators/ai-setup.md | 2 +- docs/internals/operators/clipboard-image.md | 6 ++-- .../operators/convert-to-panorama.md | 2 +- docs/internals/operators/convert-to-plane.md | 2 +- docs/internals/operators/cutout-tool.md | 32 ++++++++++--------- docs/internals/operators/index.md | 2 +- docs/internals/operators/mask.md | 2 +- docs/internals/operators/remove-background.md | 4 +-- docs/internals/operators/upscale.md | 6 ++-- docs/internals/outputs.md | 10 +++--- docs/internals/runtime.md | 12 +++---- 16 files changed, 67 insertions(+), 65 deletions(-) diff --git a/docs/internals/architecture.md b/docs/internals/architecture.md index b0b86a0..4741310 100644 --- a/docs/internals/architecture.md +++ b/docs/internals/architecture.md @@ -5,16 +5,16 @@ | `__init__.py` | 注册类型、工具、菜单、快捷键与 Runtime | | `menu.py`、`panel.py` | Image Empty 与 Shader Image Texture 上下文菜单与 Job Server 面板 | | `preferences.py` | 扩展设置及读取入口 | -| `properties.py` | Scene 手势状态、视频帧数、模型状态与枚举 | +| `properties.py` | Scene 手势状态、模型状态查询、枚举与 Operator 属性构造 | | `common/` | Blender 侧公共能力 | | `operators/` | 交互、任务参数、结果导入和 Undo | | `server/` | 独立环境内的媒体处理、推理和产物写出 | ## 注册与配置 -注销先关闭 Runtime 和交互入口，再移除 Scene 属性，按 `CLASSES` 逆序注销类型。设备、存储目录、模型、材质显示适配和功能上限统一通过 `preferences.py` 读取。 +注销先关闭 Runtime、快捷键与工具，再移除菜单和 Scene 属性，按 `CLASSES` 逆序注销类型。设备、存储目录、模型、材质显示适配和功能上限统一通过 `preferences.py` 读取。 -**Maximum AI Input Size** 限制模型分析图和 Upscale 可提交源图；**Maximum Frame Resolution** 限制 Frame 输出；**Maximum Cutout Mesh Resolution** 限制轮廓网格采样。三者各自作用于对应数据阶段。 +**Maximum AI Input Size** 限制模型分析输入和 Upscale 可提交源图的长边；**Maximum Frame Resolution** 限制 Frame 输出长边；**Minimum Relative Edge Length** 与 **Boundary Padding** 控制 Cutout 的网格密度和轮廓边界采样。 ## 执行边界 diff --git a/docs/internals/common.md b/docs/internals/common.md index b7c4a85..0452421 100644 --- a/docs/internals/common.md +++ b/docs/internals/common.md @@ -5,20 +5,20 @@ | 模块 | 职责与主要入口 | | --- | --- | | `ai.py` | 环境和模型就绪检查、输入路径校验、`production_device()`、`moge2_parameters()` 与安装 UI | -| `image.py` | `image_rgba()`、动画帧设置、Job 输入准备、像素采样、结果 Image 和 `replace_empty_image()` | +| `image.py` | `image_rgba()`、Image User 帧设置读取、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` | 深度图片和元数据加载、相机坐标与显示范围的尺度换算 | -| `material.py` | Image Layer、Normal、Alpha、Shadeless 和动画材质 | +| `material.py` | Image Layer、Normal、Alpha、Shadeless 与 Depth 材质 | | `object.py` | Modifier 输入设置与结果对象激活、源对象替换 | | `node.py` | `node_asset_path()` 与 `load_node_group()` | ## 图像生命周期 -业务像素采用 Top-down RGBA，`image_pixels()` 使用 Blender 像素顺序。预乘采样用于投影插值；文件或 Packed 图像的业务读取保留隐藏 RGB。直接编辑结果通过统一入口处理共享 Image、失败恢复和源数据清理。 +业务像素采用 Top-down RGBA，`image_pixels()` 使用 Blender 像素顺序。预乘采样用于投影插值；文件或 Packed 图像的业务读取保留隐藏 RGB。`ImageEditTarget` 校验目标身份后经 `replace_empty_image()` 或 `replace_texture_image()` 提交：未共享的 Image 原地替换内容，共享时改用新的 Image 数据块，失败时回滚源数据。 `prepare_image_input()` 返回路径及临时标记；`cleanup_image_input()` 与创建方配对。`color_image.py` 的 `prepare_material_color_input()` 准备材质颜色，`material_analysis_input()` 提供分析输入；Cutout 按几何 bounds 裁切。 @@ -39,6 +39,6 @@ Brush 的圆形印记和连接条由 `brush_footprint_polygons()` 生成，供 ## 材质、节点与对象 -`create_image_material()` 连接颜色、法线、Alpha 和动画帧设置；材质显示适配读取当前 Preferences。`set_modifier_input()` 按实际 RNA 输入形式设置值，`finalize_object_result()` 完成结果对象激活和源对象处理。 +`create_image_material()` 按 Shadeless、Normal 和 Depth 组合节点、连接颜色与 Alpha；材质显示适配读取当前 Preferences。`set_modifier_input()` 按实际 RNA 输入形式设置值，`finalize_object_result()` 完成结果对象激活和源对象处理。Image 替换路径保留 Empty 的矩阵、显示尺寸、偏移和 Image User 帧设置。 Geometry Nodes 从 `src/anyimage/assets/O_AnyImage.blend` 按公开名称加载。构建与布局职责见[节点资产](node-assets.md)，深度字段见[Job 产物](outputs.md)。 diff --git a/docs/internals/development.md b/docs/internals/development.md index e102869..74f17c0 100644 --- a/docs/internals/development.md +++ b/docs/internals/development.md @@ -14,9 +14,9 @@ uv run pytest | 扩展注册、设置、安装和 Job 交互 | `test_addon_registration.py`、`test_preferences.py`、`test_ai_setup.py`、`test_job_operator.py` | | 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` | +| Server | `test_job_server.py`、`test_server_jobs.py`、`test_input_validation.py`、`test_geometry_artifacts.py` | | 模型 | `test_model_manager.py`、下载、推理与各 ONNX 模型测试 | -| 节点资产 | 布局前后功能等价、深度分离与 Cutout 体积求值 | +| 节点资产 | 布局与接口等价、几何求值、Cutout 与临时属性清理 | | 工具与包协议 | 扩展 Manifest、打包、模型同步与节点启动器 | Blender Stub 共用 `tests/support/blender.py`；Server 和实际 Blender 几何 fixture 按使用范围存放在对应 support 模块。测试命名描述功能、触发条件与可观察结果。 @@ -42,7 +42,7 @@ Blender Stub 共用 `tests/support/blender.py`；Server 和实际 Blender 几何 flowchart TD A[main push、Pull Request 或手动触发] --> B[test.yml 运行测试] C[v 前缀 Tag] --> D[build.yml 测试、打包并发布 ZIP] - E[main 文档路径变化或手动触发] --> F[docs.yml 构建站点并部署 Cloudflare] + E[main 文档路径变化或手动触发] --> F[docs.yml 构建站点并部署到 Cloudflare Workers] ``` 站点导航由 `mkdocs.yml` 显式维护，页面移动时同步导航和相对链接。节点资产的脚本职责及检查入口见[节点资产](node-assets.md)。 diff --git a/docs/internals/index.md b/docs/internals/index.md index 98e52df..28cd02d 100644 --- a/docs/internals/index.md +++ b/docs/internals/index.md @@ -2,8 +2,6 @@ AnyImage 在 Blender 主线程处理交互、像素编辑和数据创建，通过 BlendJob 把模型推理交给独立 Job Server。 -``` - | 主题 | 对应职责 | | --- | --- | | [程序架构](architecture.md) | 进程、注册、配置与主线程边界 | diff --git a/docs/internals/node-assets.md b/docs/internals/node-assets.md index 772b46a..0572002 100644 --- a/docs/internals/node-assets.md +++ b/docs/internals/node-assets.md @@ -2,20 +2,20 @@ ## 资产清单 -节点组文件在 `tools/nodes/groups` +节点组由 `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` | +| 节点组 | 构建模块 | +| ------------------------- | --------------------------- | +| `O Image Plane` | `image_plane.py` | +| `O Image Depth Plane` | `image_depth_plane.py` | +| `O Image Relief Plane` | `image_relief_plane.py` | +| `O Image Cutout` | `image_cutout.py` | +| `O Image Depth Cutout` | `image_depth_cutout.py` | +| `O Image Cutout Symmetry` | `image_cutout_symmetry.py` | +| `O Image Layer` | `image_layer.py` | +| `O Image Depth Layer` | `image_depth_layer.py` | +| `O Shadeless` | `shadeless.py` | +| `O Image Depth Panorama` | `image_depth_panorama.py` | ## 构建节点资产 @@ -37,13 +37,15 @@ ## 构建资产脚本 -`tools/nodes/build.py` 按依赖顺序构建资产，调用 `arrangement/` 统一排列几何节点组后保存。`common/` 提供共用构建函数，其中 `material_slots.py` 继承几何材质槽，`shader.py` 构建材质着色节点，`preview/` 导出交互预览。 +`tools/nodes/build.py` 按依赖顺序构建资产，调用 `arrangement/` 统一排列几何节点组后保存。`common/` 提供共用构建函数：`nodes.py` 创建接口与节点，`depth_surface.py`、`cutout.py` 等组装几何，`shader.py` 构建材质着色节点，`material_slots.py` 继承几何材质槽；`tools/nodes/preview/` 导出交互预览。 保存后，`check.py` 在独立 Blender 进程中重新加载资产并做基本几何求值。接口、默认值和详细几何行为由 `tests/` 检查。 ```bash uv run node-group build --blender "/path/to/blender" uv run node-group build --skip-tests +uv run node-group check +uv run node-group preview ``` 脚本按 `--blender`、环境变量 `BLENDER_BIN`、项目 `.env`、`PATH` 的顺序查找 Blender。无法自动找到时，在项目根目录的 `.env` 中配置： diff --git a/docs/internals/operators/ai-setup.md b/docs/internals/operators/ai-setup.md index 4e154d9..e8feeea 100644 --- a/docs/internals/operators/ai-setup.md +++ b/docs/internals/operators/ai-setup.md @@ -27,7 +27,7 @@ flowchart TD ### 安装独立环境 -环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和 Python 包的下载源，模型使用模型目录中声明的来源。 +环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和安装包的下载源，模型使用模型目录中声明的来源。 安装完成后通过 `post_install()` 下载默认模型，模型依赖加载于独立 Server 环境。 diff --git a/docs/internals/operators/clipboard-image.md b/docs/internals/operators/clipboard-image.md index c8769a6..401f16e 100644 --- a/docs/internals/operators/clipboard-image.md +++ b/docs/internals/operators/clipboard-image.md @@ -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 diff --git a/docs/internals/operators/convert-to-panorama.md b/docs/internals/operators/convert-to-panorama.md index 4a3e3fc..e255346 100644 --- a/docs/internals/operators/convert-to-panorama.md +++ b/docs/internals/operators/convert-to-panorama.md @@ -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 diff --git a/docs/internals/operators/convert-to-plane.md b/docs/internals/operators/convert-to-plane.md index 97724f1..fc96da6 100644 --- a/docs/internals/operators/convert-to-plane.md +++ b/docs/internals/operators/convert-to-plane.md @@ -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 与切线空间法线构建浮雕。 diff --git a/docs/internals/operators/cutout-tool.md b/docs/internals/operators/cutout-tool.md index 68de1b3..937f150 100644 --- a/docs/internals/operators/cutout-tool.md +++ b/docs/internals/operators/cutout-tool.md @@ -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)。 diff --git a/docs/internals/operators/index.md b/docs/internals/operators/index.md index b80a7df..cf57cb0 100644 --- a/docs/internals/operators/index.md +++ b/docs/internals/operators/index.md @@ -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 数据。 diff --git a/docs/internals/operators/mask.md b/docs/internals/operators/mask.md index 4561c26..95b030e 100644 --- a/docs/internals/operators/mask.md +++ b/docs/internals/operators/mask.md @@ -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 删除末点。 diff --git a/docs/internals/operators/remove-background.md b/docs/internals/operators/remove-background.md index 4b678ad..563edc9 100644 --- a/docs/internals/operators/remove-background.md +++ b/docs/internals/operators/remove-background.md @@ -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 负责临时输入清理。 diff --git a/docs/internals/operators/upscale.md b/docs/internals/operators/upscale.md index db63593..7624c37 100644 --- a/docs/internals/operators/upscale.md +++ b/docs/internals/operators/upscale.md @@ -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 缩放] diff --git a/docs/internals/outputs.md b/docs/internals/outputs.md index 7516485..6d37dd9 100644 --- a/docs/internals/outputs.md +++ b/docs/internals/outputs.md @@ -4,8 +4,8 @@ Server 将结果写入 Job 目录，返回以相对文件名为值的字典。Bl | Job | 文件 | 消费方 | | --- | --- | --- | -| `remove-background` | PNG 序列或 `alpha.npy` | ImageEditTarget 或 HDR Alpha 编辑 | -| `upscale-image` | `upscale.0001.png` 起 | 图像替换 | +| `remove-background` | `foreground.png` 或 `alpha.npy` | ImageEditTarget 或 HDR Alpha 编辑 | +| `upscale-image` | `upscale.png` | 图像替换 | | `generate-depth-plane-geometry` | `depth.exr`、`depth.json` 和法线 | Depth / Relief Plane | | `generate-cutout-artifacts` | 按请求提供深度、元数据和法线 | Cutout | | `generate-panorama-geometry` | `depth.exr`、`depth.json` | Panorama | @@ -15,7 +15,7 @@ Server 将结果写入 Job 目录，返回以相对文件名为值的字典。Bl | 返回字段 | 内容 | | --- | --- | | `depth` | float32 EXR，透视产物 RGB 保存相机空间 XYZ，Alpha 保存源 Alpha × 模型有效性 | -| `depth_metadata` | JSON，透视产物包含 `image_size`、3×3 `intrinsics`、`reference_depth` | +| `depth_metadata` | JSON，包含 `image_size` 与 3×3 `intrinsics` | | `tangent_normal` | `tangent-normal.png`，切线空间法线 | | `object_normal` | `object-normal.png`，对象空间法线 | @@ -24,12 +24,12 @@ flowchart TD A[源 RGB 与 Alpha] --> B[限尺寸 RGB 推理] B --> C[GeometryFrame] C --> D[写出深度与法线] - A --> E[Alpha 有效性与参考区域] + A --> E[源 Alpha 写入有效通道] E --> D D --> F[Blender 加载并 Pack] ``` -参考深度取满足模型有效性、有限正深度与 Alpha 阈值的样本中位数。`common/depth.py` 加载 EXR，设置 Non-Color 和 CHANNEL_PACKED。Depth Plane 使用对象空间法线，Relief Plane 使用切线空间法线。 +参考深度由 `common/depth.py` 从产物计算：先按 Alpha 阈值和有限正深度筛选样本，剔除超过样本中位数 1.1 倍的远处背景，再取 95 分位数；无可用样本时返回基准值。加载后设置 Non-Color 和 CHANNEL_PACKED。Depth Plane 使用对象空间法线，Relief Plane 使用切线空间法线。 Panorama 的 EXR RGB 保存径向距离，Alpha 保存源 Alpha 与融合有效性；元数据包含 `projection: equirectangular` 和 `image_size`。 diff --git a/docs/internals/runtime.md b/docs/internals/runtime.md index 32458bd..702cce8 100644 --- a/docs/internals/runtime.md +++ b/docs/internals/runtime.md @@ -13,15 +13,15 @@ flowchart TD | Job | 实现与用途 | | --- | --- | | `download-model`、`download-required-models` | `app.py` 下载单个或缺失模型 | -| `remove-background` | `jobs/remove_background.py` 生成前景 Alpha | -| `upscale-image` | `jobs/upscale.py` 生成 2× 图像或序列 | +| `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/` 展开单图、序列与视频，并限制分析尺寸。Job 在阶段与帧边界检查取消，通过 `context.progress()` 返回进度。媒体上下文清理抽取的临时帧，Operator 清理 Blender 导出的临时输入。 +`media/` 校验输入图片并限制分析尺寸，Server 只处理静态图片。Job 在阶段边界检查取消，通过 `context.progress()` 返回进度，Operator 清理 Blender 导出的临时输入。 -`geometry/prediction_artifacts.py` 缩放源 RGB 后运行一次 MoGe，将同一预测交给深度、法线和元数据写入器。源 Alpha 用于产物有效性和参考深度采样。文件协议见 [Job 产物](outputs.md)。 +`geometry/prediction_artifacts.py` 缩放源 RGB 后运行一次 MoGe，将同一预测交给深度、法线和元数据写入器；源 Alpha 写入深度与法线产物的有效通道。参考深度由 Blender 侧按产物 Alpha 计算，文件协议见 [Job 产物](outputs.md)。 ## 模型与缓存 @@ -29,8 +29,8 @@ flowchart TD | --- | --- | --- | | 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 | +| Upscale | Real-ESRGAN WDN、Real-ESRGAN x4plus、HAT Sharper | upscale | `model_catalog.py` 声明文件来源、许可、大小和 SHA-256；`model_download.py` 下载并校验。ModelManager 按模型路径和设备缓存 Session，切换模型或设备时释放对应类别。Clear Models 或关闭 Server 时释放已加载资源。 -首次安装通过 `post_install()` 下载默认 MoGe-2、BiRefNet Lite 与 Real-ESRGAN WDN。Storage Root 默认 `~/.anyimage`，保存环境、模型、Job 产物和日志。设置入口见 [AI 环境管理](operators/ai-setup.md)。 +首次安装通过 `post_install()` 下载默认 MoGe-2 ViT-S Normal、BiRefNet Lite 与 Real-ESRGAN General WDN x4v3。Storage Root 默认 `~/.anyimage`，保存环境、模型、Job 产物和日志。设置入口见 [AI 环境管理](operators/ai-setup.md)。