Add tools and tests for AnyImage model management and documentation
- Implement sync_models.py for preparing and uploading ONNX artifacts. - Create build_node.py for building and validating Blender scripts. - Add docs.py for building and previewing documentation with Mike or MkDocs. - Introduce model_exports.py for exporting PyTorch models to ONNX format. - Develop pack.py for packaging the project with dependencies for different platforms. - Add test_sync_models.py to validate sync_models functionality. - Add test_tool_commands.py to ensure repository tools have correct command scripts. - Initialize tools package with __init__.py.
This commit is contained in:
BIN
docs/assets/logo.png
LFS
Normal file
BIN
docs/assets/logo.png
LFS
Normal file
Binary file not shown.
@@ -25,10 +25,10 @@ AnyImage 的扩展偏好设置按功能分组。Environment 区包含：
|
||||
Environment 检测后显示 Diagnostics。Depth & Normal、Remove Background、Upscale 与 Cutout 是默认展开的可折叠功能区，各自包含对应设置和模型状态。其中：
|
||||
|
||||
- **Default Upscale Model**：Upscale 使用的模型，默认是 General WDN x4v3。
|
||||
- **Maximum AI Input Size**：Upscale、Depth、Normal Map 与 Fit to Foreground 的 AI 输入长边上限，默认 2048 px；只缩放分析输入，不降低颜色贴图分辨率。
|
||||
- **Maximum AI Input Size**：Upscale、Depth、Normal Map 与 Fit to Foreground 的 AI 输入长边上限，默认 2048 px；颜色贴图保留原始分辨率。
|
||||
- **Maximum Cutout Mesh Resolution**：所有 Cutout Shape 的网格采样长边上限，默认 1024，独立于 AI 输入尺寸。
|
||||
|
||||
Depth & Normal 只列出三档 MoGe-2，Depth Plane 与 Cutout Depth / Normal Map 使用同一个显式选择，不存在生产回退。可选模型的 **Ready** 状态或 **Download** 按钮位于选择项下方；Cutout 区提供独立网格上限与 Balloon Profile。
|
||||
Depth & Normal 提供三档 MoGe-2，Depth Plane 与 Cutout Depth / Normal Map 共用当前选择。可选模型的 **Ready** 状态或 **Download** 按钮位于选择项下方；Cutout 区提供独立网格上限与 Balloon Profile。
|
||||
|
||||
如果准备把 Storage Root 放到其他磁盘，建议在首次安装 Environment 之前修改。更换目录后，旧目录中的环境和模型不会自动移动。
|
||||
|
||||
@@ -51,11 +51,10 @@ Depth & Normal 只列出三档 MoGe-2，Depth Plane 与 Cutout Depth / Normal Ma
|
||||
|
||||
完成后可以用以下方式确认：
|
||||
|
||||
- **Job Server** 不再显示 “Environment is not installed”。
|
||||
- AnyImage 扩展偏好设置中的 MoGe-2 ViT-S Normal、BEN2 Base 和 Real-ESRGAN General WDN x4v3 显示 **Ready**。
|
||||
- 选中 Image Empty 后，右键菜单底部显示 **AI Environment Settings…**。
|
||||
|
||||
**Convert to Depth Plane**、**Remove Background** 和 **Upscale** 在 AI 未就绪时仍可点击，点击后会根据状态转入 **Set Up AI Environment…** 或 **Download Required Models…**。普通 Plane、Image 编辑，以及未启用 **Fit to Foreground** / **Generate Normal Map** 的 Cutout Surface 与 Balloon 不要求安装 AI Environment。
|
||||
点击 **Convert to Depth Plane**、**Remove Background** 或 **Upscale** 时，AnyImage 会根据状态进入 **Set Up AI Environment…** 或 **Download Required Models…**。普通 Plane、Image 编辑和基础 Cutout Surface / Balloon 直接在 Blender 中执行。
|
||||
|
||||
## 下一步
|
||||
|
||||
|
||||
@@ -10,11 +10,11 @@
|
||||
|
||||
打开 **Edit > Preferences > Extensions > AnyImage**。第一次使用建议保持默认：
|
||||
|
||||
- **Mesh Depth Model**：MoGe-2 ViT-S Normal
|
||||
- **Depth & Normal Model**：MoGe-2 ViT-S Normal
|
||||
- **MoGe Resolution Level**：5
|
||||
- **Device**：使用自动列出的首选设备
|
||||
|
||||
这些是扩展级默认值，转换时不会再弹出参数对话框。
|
||||
转换直接使用这些扩展级默认值。
|
||||
|
||||
## 3. 开始转换
|
||||
|
||||
@@ -31,10 +31,3 @@
|
||||
- **Depth Amount** 控制深度位移强度。
|
||||
|
||||
建议先用较低 Subdivide 调整 Depth Amount，再按成品需要增加细分。
|
||||
|
||||
## 接下来可以尝试
|
||||
|
||||
- 只需要普通图片卡片：[Plane](../guides/mesh-plane.md)
|
||||
- 先获得透明前景：[去除背景](../guides/remove-background.md)
|
||||
- 从局部选择生成透视表面：[Cutout](../guides/cutout.md)
|
||||
- 了解深度数据如何进入节点：[Convert to Plane 实现原理](../internals/operators/convert-to-plane.md)
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
# 视频与序列帧
|
||||
|
||||
AnyImage 对 Movie 与 Image Sequence 提供三类工作流：直接转换为普通 Plane、逐帧去除背景、逐帧高清放大。Depth Plane 与 Cutout 当前只支持静态图片。
|
||||
|
||||
## 支持范围
|
||||
|
||||
| 工作流 | 视频 / 序列帧 | 结果 |
|
||||
| --- | --- | --- |
|
||||
| Convert to Plane | 支持 | 保留源 Image 的播放设置 |
|
||||
| Remove Background | 支持 | 透明 PNG 序列 |
|
||||
| Upscale | 支持 | 4× PNG 序列 |
|
||||
| Convert to Depth Plane | 不支持 | 仅静态图片 |
|
||||
| Cutout / Image Tools | 不支持 | 仅静态图片 |
|
||||
|
||||
## 处理范围
|
||||
|
||||
逐帧 Job 从 Image Empty 的图片设置读取：
|
||||
|
||||
- **Image Frames**：处理帧数；
|
||||
- **Offset**：源素材起始偏移；
|
||||
- **Start**：结果在场景中的播放起点；
|
||||
- **Cyclic**：是否循环播放。
|
||||
|
||||
显式把 Image Frames 设为 `1` 时，只处理一帧。Remove Background 与 Upscale 复用同一模型 Session 逐帧执行，内存峰值主要取决于单帧尺寸。
|
||||
|
||||
## 保存工程
|
||||
|
||||
Blender 无法把整组图片序列完整 Pack 到 `.blend`。Remove Background 与 Upscale 的动画结果会继续引用 Storage Root 中的 Job 目录。
|
||||
|
||||
!!! danger
|
||||
删除或移动仍被工程引用的 Job 目录，会导致动画序列丢失。
|
||||
|
||||
长期保存时，可以连同对应 Job 目录一起复制工程，或先把序列移动到项目素材目录，再用 Blender 的外部数据工具重新定位路径。
|
||||
@@ -1,43 +0,0 @@
|
||||
# 粘贴剪贴板图片
|
||||
|
||||
复制图片后，直接在 Blender 当前编辑器按 `CTRL + V`；macOS 使用 `CMD + V`。AnyImage 会根据上下文决定如何使用图片，并将它 Pack 到当前 `.blend`。
|
||||
|
||||
## 支持的上下文
|
||||
|
||||
| 上下文 | 结果 |
|
||||
| --- | --- |
|
||||
| 3D View / Object Mode | 创建 Reference Image 或带材质的 Plane |
|
||||
| Sculpt | 设置为笔刷 Texture |
|
||||
| Vertex Paint | 设置为笔刷 Texture |
|
||||
| Texture Paint | 设置为笔刷 Texture |
|
||||
| Shader Editor | 创建 Image Texture 节点 |
|
||||
| Compositor | 创建 Image 节点 |
|
||||
| Geometry Nodes | 创建 Image Texture 节点 |
|
||||
|
||||
## 在 3D View 中
|
||||
|
||||
图片会放在鼠标所在的屏幕位置，并使用当前 3D Cursor 作为视图深度参考。默认导入为 `Reference Image`。
|
||||
|
||||
如果在操作面板中切换为 `Plane`，会创建基础四边形和 `O Mesh Plane` Geometry Nodes 修改器。操作面板只保留：
|
||||
|
||||
- **Import As**：在 Reference Image 与 Plane 之间切换
|
||||
- **Shadeless**：让图片不受场景灯光影响
|
||||
|
||||
`Thickness` 与 `Subdivide` 直接在 Geometry Nodes 修改器中调整，不作为粘贴参数。
|
||||
|
||||
## 在 Node Editor 中
|
||||
|
||||
节点创建在鼠标位置。不同节点编辑器会选择对应的图片节点类型，不需要先保存临时图片再手动浏览文件。
|
||||
|
||||
## 与 Blender 原生粘贴共存
|
||||
|
||||
如果刚刚使用 `CTRL + C` 复制了 Blender 内部数据，随后按 `CTRL + V` 时会优先让 Blender 处理原生粘贴。只有剪贴板中存在新的图片数据时，图片粘贴功能才接管操作。
|
||||
|
||||
## 平台说明
|
||||
|
||||
- Windows：直接支持
|
||||
- macOS：使用 `CMD + V`
|
||||
- Linux Wayland：需要 `wl-clipboard`
|
||||
- Linux X11：需要 `xclip`
|
||||
|
||||
剪贴板中没有可用图片时，操作会放行，不阻断 Blender 的其他粘贴行为。
|
||||
@@ -1,61 +0,0 @@
|
||||
# Cutout
|
||||
|
||||
Cutout 用套索从一张 Image Empty 中选择区域，再生成 Surface、Balloon、Depth Balloon 或 Depth Surface。它适合从图片局部制作薄片、鼓包或带透视深度的网格。
|
||||
|
||||
## 创建
|
||||
|
||||
1. 在 Object Mode 的 3D Viewport 左侧工具栏选择 **Cutout**。
|
||||
2. 沿 Image Empty 按住左键绘制；双击图片可选择完整画面。
|
||||
3. 松开左键后，从饼菜单选择 Shape。
|
||||
|
||||
绘制时按 `F` 切换反选，右键或 `Esc` 取消。Cutout 使用非零环绕填充：反向绘制的内环可以形成孔洞。
|
||||
|
||||
## 选择 Shape
|
||||
|
||||
| Shape | 结果特点 | 是否需要深度模型 |
|
||||
| --- | --- | --- |
|
||||
| Surface | 保持平面轮廓，可增加真实厚度 | 否 |
|
||||
| Balloon | 按轮廓平滑鼓起 | 否 |
|
||||
| Depth Balloon | 在 Balloon 上加入图片深度高度 | 是，固定使用 MoGe-2 |
|
||||
| Depth Surface | 使用相机点形成透视表面 | 是，使用 Preferences 中的 Mesh Depth Model |
|
||||
|
||||
四种结果都保留源 Image Empty，并在同一位置创建新网格。它们共享选区轮廓、UV、材质和基础三角网格，因此可以从同一张图多次生成不同 Shape 进行比较。
|
||||
|
||||
无论是否启用 Fit to Foreground，套索超出图片的部分都不会生成网格，源图中 `Alpha <= 0.1` 的像素也始终从 Region 中排除。双击使用完整画面时同样只为 `Alpha > 0.1` 的 Region 生成网格。
|
||||
|
||||
## 工具设置
|
||||
|
||||
选项按执行意图排列：
|
||||
|
||||
- **Fit to Foreground**：用 BEN2 把几何套索贴合到其中的前景主体，默认关闭。
|
||||
- **Mesh Sampling Spacing**：相邻网格采样点大约对应多少源图像素；数值越小，三角网格越密。
|
||||
- **Generate Normal Map**：是否使用 MoGe-2 生成法线贴图，默认关闭；空间由 Shape 自动决定。
|
||||
|
||||
Surface 与 Balloon 在 **Generate Normal Map**、**Fit to Foreground** 都关闭时完全在 Blender 中生成，不需要 AI Environment。开启任一 AI 选项，或选择 Depth Shape 时，会提交后台任务。
|
||||
|
||||
Mesh Sampling Spacing 先按完整源图换算期望密度，再由 Cutout 区的 **Maximum Cutout Mesh Resolution** 限制裁切区域的最长采样边。这个网格上限对 Surface、Balloon 与 Depth Shape 完全相同。**Maximum AI Input Size** 只限制 Fit to Foreground、Depth 和 Normal Map 的模型分析图；颜色贴图始终保留原裁切分辨率。建议先用默认 `32` 观察形状，轮廓需要更细时再逐步减小。
|
||||
|
||||
## 调整修改器
|
||||
|
||||
四个 Shape 都使用同一个 `O Image Cutout` Geometry Nodes 修改器。创建时 Shape 菜单已经设为饼菜单所选类型；切换 Shape 后，Blender 只显示该类型实际使用的输入。常用参数包括：
|
||||
|
||||
- **Thickness**：Surface / Depth Surface 使用场景距离；Balloon / Depth Balloon 使用鼓起高度倍率。
|
||||
- **Cleanup**：碎岛面积阈值；创建时根据 Mesh Sampling Spacing 和图片平面尺寸自动写入。为便于在修改器中调节，显示值放大了 `100` 倍，节点内部会还原为实际面积，因此这次显示缩放不会改变默认清理效果。
|
||||
- **Smooth Iterations**：位于外层，控制平滑次数，默认 `0`；**Smooth** 位于 Options 中，控制每次平滑的混合强度。四种 Shape 都可使用。
|
||||
- **Depth Scale**：Depth Shape 的深度强度；`0` 回到基础平面或 Balloon。
|
||||
|
||||
两个 Depth Shape 共用 **Base Plane Depth**；Depth Balloon 还提供 **Depth Direction**。生成前会检查最终 Region 输入的 Alpha：`Alpha < 0.1` 的像素达到 `5%` 时，根据有效 Region 自适应 Base Plane Depth，并为 Depth Balloon 拟合 Direction；不足 `5%` 时使用稳定的固定基准。这个判断不依赖双击全图或 Fit to Foreground。插件自动写入的 Depth Image 与 Uniform Scale 位于折叠的 Data 面板，一般无需手动修改。
|
||||
|
||||
Balloon 的轮廓高度算法由扩展 Preferences 中的 **Balloon Profile** 控制：Poisson 更平滑，Teddy 更强调轮廓骨架。修改默认值只影响之后创建的 Shape。
|
||||
|
||||
## Fit to Foreground 与 Normal Map
|
||||
|
||||
Fit to Foreground 只在“套索与源图可见 Alpha 的交集”内收紧最终 Region，不把 AI 生成的颜色写回原图。材质使用按最终 Region 包围矩形裁切的当前 Image Empty 源图，保留源颜色和原 Alpha，不把 RegionMask 写入 Alpha。
|
||||
|
||||
Normal Map 关闭时使用几何法线。开启后，Depth Surface 自动使用 Object Space，把模型法线编码到 Cutout 对象局部轴；Surface、Balloon 与 Depth Balloon 自动使用 Tangent Space，作为相对图片平面的浮雕细节。用户不直接选择 Normal Space，两种路径都不根据 Geometry Nodes 的成品网格再次烘焙。Normal Map 保持模型分析分辨率，Color Image 仍保留原始裁切分辨率；Depth 与 Normal Map 同时需要时共享同一次 Prediction，不会重复运行模型。
|
||||
|
||||
## 当前范围
|
||||
|
||||
Cutout 只支持静态图片。图片工具创建的透明结果和 Upscale 结果都可以继续作为输入；Cutout 始终以当前 Image Empty 的实际图片为颜色来源。
|
||||
|
||||
轮廓、深度场、节点资产与法线空间的实现见 [Cutout Tool 实现原理](../internals/operators/cutout-tool.md)。
|
||||
@@ -1,36 +0,0 @@
|
||||
# Depth Plane
|
||||
|
||||
Depth Plane 将一张静态图片转换为带深度位移的网格，适合快速场景搭建、2.5D 合成和立体插画。
|
||||
|
||||
## 创建
|
||||
|
||||
1. 在 3D View 中选中 Image Empty。
|
||||
2. 右键选择 **AnyImage > Convert to Depth Plane**。
|
||||
3. 等待状态栏提示任务完成。
|
||||
|
||||
转换不会弹出设置对话框。深度模型和分辨率使用 **Edit > Preferences > Extensions > AnyImage > Depth & Normal** 中的默认值。
|
||||
|
||||
## 选择模型
|
||||
|
||||
### MoGe-2
|
||||
|
||||
默认推荐。MoGe-2 估算尺度一致的深度与相机信息，使用 **MoGe Resolution Level** 控制处理精度。第一次使用建议保持 `5`。
|
||||
|
||||
## 调整结果
|
||||
|
||||
生成对象使用扩展资产中的 `O Image Depth Plane` Geometry Nodes 修改器：
|
||||
|
||||
- **Subdivide**：控制基础平面细分级别；
|
||||
- **Thickness**：增加背面和侧壁，`0` 输出单面；
|
||||
- **Depth Amount**：控制图片深度位移强度。
|
||||
|
||||
结果颜色来自当前 Image Empty，深度由所选模型分析。转换会以一个 Undo 步骤替换源 Empty；如果需要保留原对象，请在转换前复制一份。
|
||||
|
||||
## 当前输入范围
|
||||
|
||||
Depth Plane 当前只支持静态图片。视频与序列帧可以转换为普通 [Plane](mesh-plane.md)，或使用 [Remove Background / Upscale](animation.md) 逐帧处理。
|
||||
|
||||
实现中的深度场、坐标锚定和节点流程见 [Convert to Plane 实现原理](../internals/operators/convert-to-plane.md)。
|
||||
## 分析分辨率与颜色
|
||||
|
||||
Depth 输入还受 Environment 区的 **Maximum AI Input Size** 约束，默认最大长边为 `2048 px`。超过时只会等比缩放模型分析输入；结果材质仍使用原始颜色图片，不会改用限制后的临时图。
|
||||
@@ -1,54 +0,0 @@
|
||||
# 常见问题
|
||||
|
||||
## 找不到 AnyImage 右键菜单
|
||||
|
||||
AnyImage 菜单只会在选中 Image Empty 时出现。确认对象类型是 Empty，并且显示方式为 Image。普通 Mesh、图片编辑器中的图片或未选中的 Image Empty 都不会显示入口。
|
||||
|
||||
## 转换入口是灰色的
|
||||
|
||||
通常有以下原因：
|
||||
|
||||
- 另一个 AnyImage 任务正在运行。
|
||||
- 当前对象不是 Image Empty。
|
||||
|
||||
Environment 或默认模型缺失不会让四个 AI 功能变灰；点击功能会根据状态打开 **Set Up AI Environment…** 或 **Download Required Models…**。Balloon 的 **Contour**、**Depth** 与 Depth Model 会在 AI 未就绪时单独禁用，同一位置提供安装按钮。
|
||||
|
||||
## Environment 安装失败
|
||||
|
||||
- 海外源访问不稳定时重新打开 **Set Up AI Environment…**，勾选 **Use Mirror**。
|
||||
- 检查 Blender 的 **Online Access** 是否开启。
|
||||
- 确认 Storage Root 至少有约 1 GB 可用空间且可写。
|
||||
- 查看 Storage Root 下的 `install.log`。
|
||||
|
||||
安装模型失败不会删除已经成功创建的 Environment。可以稍后使用 **Download Required Models…** 补齐默认模型，或在 AnyImage 扩展偏好设置中逐项重试。
|
||||
|
||||
## 模型下载很慢或失败
|
||||
|
||||
模型会尝试 Hugging Face 和 OmooLab 备用来源。检查网络、代理和磁盘空间后重新点击 Download。模型直链连接或长时间无数据时会自动尝试下一来源。
|
||||
|
||||
## 第一次转换较慢
|
||||
|
||||
第一次任务需要启动 Job Server 并把模型载入内存。Server 运行且模型仍在缓存中时，后续同类任务通常会更快。
|
||||
|
||||
## Upscale 很卡或提示内存不足
|
||||
|
||||
三个高清模型都使用分块推理，但完整输出数组、PNG 编码和 Blender 图片载入仍取决于输入与 4× 结果尺寸。Environment 区的 **Maximum AI Input Size** 默认限制输入长边为 `2048 px`；可以降低该值，或改用 CPU。DirectML 或其他 provider 无法分配资源时，任务也会提示降低这个全局值。
|
||||
## Depth Plane 太平或深度方向反了
|
||||
|
||||
在 Geometry Nodes 修改器中调整 **Depth Scale**。增大绝对值会加强深度，使用负值可以反转前后关系。
|
||||
|
||||
## Cutout Depth Surface 边缘破碎或细节太多
|
||||
|
||||
先增大 **Mesh Sampling Spacing** 降低基础网格密度，再调整 **Cleanup** 清理小块，并用 **Smooth** 稳定表面。必要时降低模型分辨率。
|
||||
|
||||
## 动画面片不播放
|
||||
|
||||
检查源 Image Empty 的 **Image Frames** 是否大于 `1`，并确认场景时间正在变化。生成后的动画还需要对应 Job 文件夹存在；文件被移动或删除时应重新定位序列。
|
||||
|
||||
## 可以删除 jobs 文件夹吗
|
||||
|
||||
静态图的部分结果会 Pack 到 `.blend`，但视频与序列帧会直接引用 Job 文件。只有确认没有工程继续引用对应目录时才应删除。
|
||||
|
||||
## 如何完全撤销一次转换
|
||||
|
||||
转换完成后直接按 `Ctrl+Z`。AnyImage 会把网格、材质、图片和修改器的创建合并为一次 Blender Undo 操作。
|
||||
@@ -1,82 +0,0 @@
|
||||
# Image 编辑工具
|
||||
|
||||
Image Box、Lasso、Line、Polyline 与 Perspective 直接编辑静态 Image Empty，并把结果 Pack 到当前 `.blend`。前四个工具组成 Mask 工具组；Perspective 是紧随其后的独立工具。
|
||||
|
||||
## 选择工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
| --- | --- |
|
||||
| **Image Box** | 用矩形保留或清理图片区域 |
|
||||
| **Image Lasso** | 手绘自由选区 |
|
||||
| **Image Line** | 用一条直线清理一侧 |
|
||||
| **Image Polyline** | 逐点构建精确多边形 |
|
||||
| **Image Perspective** | 将任意顺序输入的四个角矫正为矩形 |
|
||||
|
||||
在 3D Viewport 左侧工具栏长按 Image Mask 图标，可以在 Box、Lasso、Line 与 Polyline 之间切换。**Fit to Foreground** 只显示在 Box / Lasso；Line / Polyline 保持几何直线边界。Perspective 使用独立图标。
|
||||
|
||||
<div class="screenshot-placeholder" markdown>
|
||||
**截图占位：Image 工具组与 Tool Settings**
|
||||
|
||||
显示包含四个工具的 Image Mask 组、独立 Perspective，以及 Box / Lasso 的 Fit to Foreground。
|
||||
|
||||
目标文件：`images/image-tools/tool-group.png`
|
||||
</div>
|
||||
|
||||
## 选择图片
|
||||
|
||||
直接在当前 Active 图片上开始绘制。如果第一次点击的是另一张 Image Empty，这次点击只会选中它；下一次操作才开始编辑。点击空白处或非图片对象时，继续编辑当前 Active 图片，不会移动对象。
|
||||
|
||||
没有 Active Image Empty 时，工具会提示先选择图片。切换到其他工具会立即取消正在进行的绘制。
|
||||
|
||||
## 清理选区
|
||||
|
||||
### Box 与 Lasso
|
||||
|
||||
- Box：按住左键拖出矩形，松开后执行。
|
||||
- Lasso：按住左键绘制轮廓，松开后执行。
|
||||
|
||||
### Line
|
||||
|
||||
从起点拖到终点，松开后保留直线左侧的内容。按住 `Ctrl` 以 5° 为单位吸附方向；需要另一侧时按 `F` 翻转。
|
||||
|
||||
### Polyline
|
||||
|
||||
逐点单击构建多边形。鼠标接近起点时会显示闭合圆环；单击圆环或按 `Enter` 完成，`Backspace` 删除最近一点。
|
||||
|
||||
绘制过程中按 `F` 切换反选。反选是一个持续到本次操作完成的状态，不需要按住：
|
||||
|
||||
- 关闭：保留选区内；
|
||||
- 开启：保留选区外。
|
||||
|
||||
Cutout、Box 与 Lasso 分别保存各自的 **Fit to Foreground** 设置；在一个工具中切换不会改变另外两个工具。启用后，BEN2 会先把几何 Region 收紧到其中的前景，再应用反选。例如框住一个苹果并开启反选，最终会清理苹果本身、保留其余内容。Line / Polyline 不提供 Fit to Foreground，以保持直线边界和明确的裁切方向。
|
||||
|
||||
结果会直接更新当前 Empty 的图片，并把画布紧裁切到最终可见 Alpha。只有一个 Image Empty 使用该图片时，工具更新原 Image；两个或更多 Image Empty 共用它时，工具为当前 Empty 创建独立结果，其他 Empty 保持不变。对象 Transform 不变，显示尺寸与 Image Offset 会更新，使剩余像素保持在原图片平面上的位置。透明区只修改 Alpha，保留源 RGB 供纹理过滤使用。未形成有效区域的单击会静默结束；有效选区没有可见像素时只显示警告，不修改图片。
|
||||
|
||||
<div class="screenshot-placeholder" markdown>
|
||||
**截图占位：Polyline 与反选**
|
||||
|
||||
显示半透明选区面、虚线边界，以及状态栏中的 `F toggles Invert`。
|
||||
|
||||
目标文件：`images/image-tools/polyline-invert.png`
|
||||
</div>
|
||||
|
||||
## 四点透视
|
||||
|
||||
1. 任意顺序单击四个角点。
|
||||
2. 第四点后，在 Viewport 中央检查矫正预览。
|
||||
3. 左右移动鼠标调整宽高比；按住 `Ctrl` 可吸附到 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`。
|
||||
4. 左键确认。
|
||||
|
||||
`Backspace` 返回上一步，右键或 `Esc` 取消。四点会自动排序，点击顺序不会改变输出旋转。
|
||||
|
||||
Perspective 只执行图片 Homography 与紧裁切，不提供 Fit to Foreground，也不尝试从当前 View 推导真实相机。结果保持源 Empty 的 Transform，并按原四边形覆盖范围近似更新显示位置与尺寸。选区完全位于图片外或没有可见像素时不会执行。
|
||||
|
||||
<div class="screenshot-placeholder" markdown>
|
||||
**截图占位：Perspective 比例确认**
|
||||
|
||||
显示中央图片预览、蓝色边框、当前比例与底部操作提示。
|
||||
|
||||
目标文件：`images/image-tools/perspective-aspect.png`
|
||||
</div>
|
||||
|
||||
实现结构与像素规则见 [Image Tool 实现原理](../internals/operators/image-tool.md)。
|
||||
@@ -1,27 +0,0 @@
|
||||
# Plane
|
||||
|
||||
Plane 把 Image Empty 转换为带图片材质的普通网格，不运行 AI，也不生成深度估算。它适合广告牌、图片卡片、背景板，以及视频或序列贴图。
|
||||
|
||||
## 创建
|
||||
|
||||
1. 在 3D View 中选中 Image Empty。
|
||||
2. 右键选择 **AnyImage > Convert to Plane**。
|
||||
3. 在 Last Operation 中按需调整 **Subdivide**。
|
||||
|
||||
转换会立即创建结果并替换源 Empty。新对象继承原对象的 Transform、图片显示比例和 Offset；需要保留源 Empty 时，请先复制对象。
|
||||
|
||||
## Geometry Nodes
|
||||
|
||||
结果使用 `O Mesh Plane` 修改器：
|
||||
|
||||
- **Subdivide** 使用二分级别控制网格密度，`3` 表示短边约 `8` 段；
|
||||
- **Thickness** 沿平面法线增加厚度，`0` 输出真正的单面；
|
||||
- **Material** 由 AnyImage 自动连接。
|
||||
|
||||
原始 Mesh 数据只有一个四边形，细分和厚度都由修改器实时生成，可以在转换后继续调整。
|
||||
|
||||
## 剪贴板 Plane
|
||||
|
||||
在 3D View 中粘贴剪贴板图片，并在 Last Operation 把 **Import As** 改为 **Plane**，也会创建同样的基础网格和 `O Mesh Plane` 修改器。该入口还可选择 **Shadeless**；Image Empty 的 Convert to Plane 入口不提供 Shadeless 选项。
|
||||
|
||||
模块与节点分工见 [Convert to Plane 实现原理](../internals/operators/convert-to-plane.md)。
|
||||
@@ -1,66 +0,0 @@
|
||||
# 模型、设备与存储
|
||||
|
||||
AnyImage 把运行环境、模型和任务结果放在 Blender 之外，多个 Blender 版本可以共享同一套数据。
|
||||
|
||||
## 功能与模型设置
|
||||
|
||||
打开 **Edit > Preferences > Extensions > AnyImage**，可以查看和下载模型。右键菜单中的 **AI Environment Settings…** 会直接打开这里。Environment 检测后紧接 Diagnostics；其余设置分为默认展开、可折叠的 Depth & Normal、Remove Background、Upscale 和 Cutout 功能区，模型不会再集中显示在单独列表中。
|
||||
|
||||
- **Ready** 表示模型文件已经就绪。
|
||||
- **Download** 用于按需下载模型。
|
||||
- Depth & Normal 与 Upscale 的下载按钮位于当前模型选择项下方；切换选择后，可直接下载对应模型。
|
||||
- Depth & Normal 只列出三档 MoGe-2；Depth Plane 与 Cutout 共用这个显式选择。
|
||||
- Remove Background 使用的 BEN2 固定模型显示在对应功能区；Cutout 区只包含 Balloon Profile。
|
||||
- 默认安装会准备 MoGe-2 ViT-S Normal、BEN2 Base 和 Real-ESRGAN General WDN x4v3。
|
||||
- 更大的 MoGe-2，以及可选的 SAFMN Real x4、Real-ESRGAN x4plus 需要时再下载即可。
|
||||
- 可公开取得的 ONNX 制品使用经过大小与 SHA-256 校验的原址，并以 OmooLab R2 为镜像；不会把源码仓库名称推测成 Hugging Face 下载地址。
|
||||
- Real-ESRGAN General WDN x4v3 与 SAFMN Real x4 的上游只发布 PyTorch 权重，当前 ONNX 均从官方权重导出并仅从 R2 下载。
|
||||
|
||||
较大的模型不一定适合所有图片。建议先用默认模型完成构图，再针对细节与性能需求比较其他模型。
|
||||
|
||||
## AI 输入与 Cutout 网格尺寸
|
||||
|
||||
Environment 区的 **Maximum AI Input Size** 默认 `2048 px`，可在 `256–8192 px` 之间调整。它是 Upscale 的可执行源图长边上限，也是 Depth、Normal Map 与 Fit to Foreground 模型分析输入的最大长边；颜色贴图仍使用原始分辨率。Cutout 区的 **Maximum Cutout Mesh Resolution** 默认 `1024`，独立限制所有 Shape 的网格采样密度，不会因为某个 Shape 是否使用 AI 而改变含义。
|
||||
## Device
|
||||
|
||||
扩展偏好设置中的 **Device** 控制 Depth Plane、Cutout 的 AI 增强、Remove Background 和 Upscale 等正式任务。
|
||||
|
||||
- Windows 通常优先使用 DirectML。
|
||||
- Apple Silicon macOS 通常优先使用 CoreML。
|
||||
- Provider 不可用时会回退到 CPU。
|
||||
|
||||
Debug 面板中的 **Debug Device** 只影响 Debug 任务，不会覆盖正式任务的 Device。
|
||||
|
||||
## Session 缓存
|
||||
|
||||
连续使用同一模型和 Device 时，Server 会复用已经加载的 ONNX Session。缓存分为 BEN2、几何模型和 Upscale 三个族，每个族只保留最近使用的一套；同族切换模型或 Device 时释放旧 Session。如果高清推理遇到 provider 资源错误，也会立即卸载该 Session。
|
||||
|
||||
## Storage Root
|
||||
|
||||
默认 Storage Root 是 `~/.anyimage`，主要包含：
|
||||
|
||||
```text
|
||||
~/.anyimage/
|
||||
├── .venv/ # 独立 Python Environment
|
||||
├── models/ # 模型文件
|
||||
├── jobs/ # 每次任务的结果与 job.log
|
||||
├── install.log # Environment 安装日志
|
||||
└── server.log # 带 Job ID 的任务主线与 Job Server 日志
|
||||
```
|
||||
|
||||
更改 Storage Root 相当于切换到另一套环境、模型和任务数据。AnyImage 不会自动移动旧目录。
|
||||
|
||||
## Job 文件夹
|
||||
|
||||
每个任务会在 `jobs/` 下创建一个独立目录。单张图生成的关键贴图通常会 Pack 到 `.blend`；视频和序列帧则继续引用 Job 目录中的文件。
|
||||
|
||||
可以清理已经确认不再使用的任务目录，但清理前应检查是否有 `.blend` 仍引用其中的序列帧。
|
||||
|
||||
## 日志
|
||||
|
||||
遇到安装或 Server 问题时：
|
||||
|
||||
- 在扩展偏好设置中点击 **Open Server Log** 查看带时间、Job ID 与 Job Type 的运行主线。
|
||||
- 具体 Job 的 Handler 细节和完整 traceback 查看 `jobs/<job-id>/job.log`。
|
||||
- Environment 安装问题查看 Storage Root 下的 `install.log`。
|
||||
- 修改 Storage Root 后，确认你检查的是当前目录中的日志。
|
||||
@@ -1,23 +0,0 @@
|
||||
# 去除背景
|
||||
|
||||
Remove Background 使用 BEN2 为 Image Empty 生成透明前景，不创建网格。
|
||||
|
||||
## 使用
|
||||
|
||||
1. 选中 Image Empty。
|
||||
2. 在 3D View 中右键选择 **AnyImage > Remove Background**。
|
||||
3. 等待状态栏提示任务完成。
|
||||
|
||||
结果替换当前 Empty 的图片，对象 Transform、显示尺寸、Offset 和播放设置保持不变。单图结果会 Pack 到 `.blend`；视频或序列帧结果继续引用 Job 目录。
|
||||
|
||||
## Alpha 处理
|
||||
|
||||
推理前，AnyImage 会用输入 Alpha 遮住透明区域中的 RGB。结果颜色仍来自源图，只采用 BEN2 生成的前景 Alpha；源图已有透明度时，两者会相乘。因此 Image Mask 或外部软件已经清理的范围不会被重新扩张。
|
||||
|
||||
当前入口不提供 BEN2 的额外细化参数。需要手动控制范围时，可以先使用 [Image Box / Lasso](image-tools.md)，也可以在结果材质中继续调整 Alpha。
|
||||
|
||||
## 图片序列
|
||||
|
||||
Remove Background 支持单图、Movie 和 Image Sequence。处理帧数、偏移和播放起点见[视频与序列帧](animation.md)。
|
||||
|
||||
任务与结果替换流程见 [Remove Background 实现原理](../internals/operators/remove-background.md)。
|
||||
@@ -1,27 +0,0 @@
|
||||
# 高清放大
|
||||
|
||||
Upscale 用 ONNX 模型把 Image Empty 的 RGB 放大 4 倍，不创建网格。它支持单图、Movie 和 Image Sequence，并以 Lanczos 独立放大源 Alpha 后重新合并。
|
||||
|
||||
## 使用
|
||||
|
||||
1. 在 AnyImage 扩展偏好设置中选择 **Default Upscale Model**。
|
||||
2. 按需要设置 Environment 区的 **Maximum AI Input Size**；默认 `2048 px`，最高 `8192 px`。
|
||||
3. 选中 Image Empty，在右键 **AnyImage** 菜单中点击 **Upscale**。
|
||||
|
||||
菜单项只显示本次操作预计生成的 4× 尺寸。当前图片长边必须小于全局上限；达到上限后 Upscale 会置灰，因此默认设置下单次结果长边小于 `8192 px`。完成后，当前 Empty 会直接使用放大结果；原 Image 没有其他引用时沿用原名并移除旧数据，存在其他引用时则为当前 Empty 保留独立结果。
|
||||
|
||||
## 模型选择
|
||||
|
||||
- **Real-ESRGAN General WDN x4v3**：默认模型，速度快，细节处理较保守。
|
||||
- **SAFMN Real x4**：速度与细节较均衡。
|
||||
- **Real-ESRGAN x4plus**：生成的细节更明显。
|
||||
|
||||
后两项可在扩展偏好设置中按需下载。
|
||||
|
||||
AnyImage 不追踪高清结果的原图引用，Upscale 始终处理当前 Image。只要当前长边仍小于全局上限，就可以再次放大；达到上限后不能继续执行。
|
||||
|
||||
把高清结果继续转换为 Depth Plane 时，颜色材质和分析都以当前 Image 为来源，分析输入仍遵守全局上限；Cutout 同样只缩放裁切后的分析输入，不会把限制后的临时图用作 Color。
|
||||
|
||||
如果显存或内存不足，请降低 **Maximum AI Input Size**，或改用 CPU。
|
||||
|
||||
分块推理、Alpha 合并与输入限制见 [Upscale 实现原理](../internals/operators/upscale.md)。
|
||||
@@ -1,41 +0,0 @@
|
||||
# 选择工作流
|
||||
|
||||
先确定需要的是图片数据、普通平面、整图深度，还是局部网格。
|
||||
|
||||
| 工作流 | 输入 | 结果 | AI |
|
||||
| --- | --- | --- | --- |
|
||||
| Clipboard Image | 剪贴板静态图 | Reference、Plane、节点或笔刷纹理 | 不需要 |
|
||||
| Convert to Plane | 单图、Movie、Sequence | 带材质的普通网格 | 不需要 |
|
||||
| Convert to Depth Plane | 静态图 | 带深度位移的整图面片 | MoGe-2 |
|
||||
| Cutout | 静态图局部选区 | 四种局部 Shape | 按 Shape 与选项决定 |
|
||||
| Remove Background | 单图、Movie、Sequence | 透明图片或序列 | BEN2 |
|
||||
| Upscale | 单图、Movie、Sequence | 4× 图片或序列 | Upscale 模型 |
|
||||
| Image Mask / Perspective | 静态图 | 原位更新的裁切或矫正图 | Fit to Foreground 时使用 BEN2 |
|
||||
|
||||
## 普通 Plane
|
||||
|
||||
只需要图片卡片、背景板或视频贴图时，选择 **Convert to Plane**。它不分析深度，Thickness 与 Subdivide 可以在 Geometry Nodes 中随时调整。
|
||||
|
||||
[阅读 Plane 指南](mesh-plane.md)
|
||||
|
||||
## Depth Plane
|
||||
|
||||
需要把整张静态图快速变成可调浮雕时，选择 **Convert to Depth Plane**。深度模型与分辨率在扩展 Preferences 中设置。
|
||||
|
||||
[阅读 Depth Plane 指南](depth-plane.md)
|
||||
|
||||
## Cutout
|
||||
|
||||
只需要图片局部，或希望按轮廓生成 Balloon / Depth Surface 时，使用工具栏中的 **Cutout**。普通 Surface 与 Balloon 可以完全在 Blender 内完成，Fit to Foreground、Generate Normal Map 与 Depth Shape 按需调用 AI。
|
||||
|
||||
[阅读 Cutout 指南](cutout.md)
|
||||
|
||||
## 图片处理
|
||||
|
||||
只想得到透明前景，不需要网格时使用 [Remove Background](remove-background.md)。需要增加像素尺寸时使用 [Upscale](upscale.md)。两者都支持 Movie 和 Image Sequence。
|
||||
|
||||
## Image 编辑
|
||||
|
||||
Box、Lasso、Line 和 Polyline 适合直接清理 Alpha；Perspective 适合把图片中的四边形内容矫正为矩形。结果都会写回当前 Image Empty，并保持对象 Transform。
|
||||
|
||||
[阅读 Image 编辑工具](image-tools.md)
|
||||
@@ -10,45 +10,3 @@ AnyImage 是一款 Blender 扩展，可以粘贴和编辑图片、创建普通 P
|
||||
- 用 **Cutout** 从套索选区生成 Surface、Balloon 与两种 Depth Shape
|
||||
- 用 **Image Tools / Perspective** 直接清理或矫正 Image Empty
|
||||
- 用 **Remove Background / Upscale** 处理单图、视频和序列帧
|
||||
|
||||
!!! info "运行环境与 Blender 分离"
|
||||
AI 计算运行在独立 Environment 中，不会把 ONNX Runtime 等依赖安装进 Blender Python。Blender 只负责界面、任务提交和结果导入。
|
||||
|
||||
## 从这里开始
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- **安装 AnyImage**
|
||||
|
||||
下载与你的系统匹配的扩展包，完成 Environment 与默认模型配置。
|
||||
|
||||
[阅读安装指南](getting-started/installation.md)
|
||||
|
||||
- **五分钟上手**
|
||||
|
||||
从导入一张静态图片开始，创建第一个 Depth Plane。
|
||||
|
||||
[开始第一个作品](getting-started/quick-start.md)
|
||||
|
||||
- **选择工作流**
|
||||
|
||||
对比 Plane、Depth Plane、Cutout、去背景、高清放大和图片编辑。
|
||||
|
||||
[查看工作流](guides/workflows.md)
|
||||
|
||||
- **了解实现**
|
||||
|
||||
从项目主干、进程边界和功能模块了解内部实现。
|
||||
|
||||
[阅读内部实现总览](internals/index.md)
|
||||
|
||||
</div>
|
||||
|
||||
## 使用要求
|
||||
|
||||
- Blender 4.5 或更高版本
|
||||
- Windows x64、macOS Apple Silicon 或 Linux x64
|
||||
- 安装 Environment 与模型时需要网络连接
|
||||
- AI 功能需要对应模型；普通 Plane、基础 Image 编辑与不带 AI 选项的 Cutout Surface / Balloon 可离线使用
|
||||
|
||||
遇到安装、模型或任务问题时，查看[常见问题](guides/faq.md)。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 程序架构
|
||||
|
||||
AnyImage 由 Blender 交互层、BlendJob Runtime 和独立 Job Server 三部分组成。这个分层让 Blender Python 不需要加载 ONNX Runtime、Pillow 或模型权重，同时保证所有 Blender 数据仍在主线程创建和修改。
|
||||
AnyImage 由 Blender 交互层、BlendJob Runtime 和独立 Job Server 三部分组成。AI 依赖运行在 Server Environment 中，Blender 数据在主线程创建和修改。
|
||||
|
||||
## 对应文件
|
||||
|
||||
@@ -12,17 +12,18 @@ src/anyimage/
|
||||
├── preferences.py # Storage Root、Device 与功能默认值
|
||||
├── properties.py # Scene 状态、模型状态与动态枚举
|
||||
├── runtime.py # Environment 和 JobRuntime
|
||||
├── common/ # Blender 侧共享原子能力
|
||||
├── operators/ # Blender 侧业务入口
|
||||
└── server/ # 独立计算端
|
||||
```
|
||||
|
||||
## 职责边界
|
||||
## 职责
|
||||
|
||||
| 层次 | 负责 | 不负责 |
|
||||
| --- | --- | --- |
|
||||
| Blender 交互层 | UI、手势、RNA 状态、输入准备、结果导入、Undo | 在 Blender 进程加载 AI 依赖 |
|
||||
| BlendJob Runtime | Environment、Server 生命周期、队列、进度、取消、Job 目录 | AnyImage 的图像与几何业务 |
|
||||
| Job Server | 媒体解码、ONNX 推理、数组派生、文件输出 | 创建 Blender 对象或访问 `bpy` |
|
||||
| 层次 | 职责 |
|
||||
| --- | --- |
|
||||
| Blender 交互层 | UI、手势、RNA 状态、输入准备、结果导入和 Undo |
|
||||
| BlendJob Runtime | Environment、Server 生命周期、队列、进度、取消和 Job 目录 |
|
||||
| Job Server | 媒体解码、ONNX 推理、数组派生和文件输出 |
|
||||
|
||||
Operator 向 Server 发送普通字典。Server 返回文件名和 Job 目录；Operator 的 `response()` 再读取这些文件，并在 Blender 主线程中创建 Image、Mesh、Material 和 Geometry Nodes Modifier。
|
||||
|
||||
@@ -58,12 +59,8 @@ sequenceDiagram
|
||||
Op->>Op: 导入数据并提交 Undo
|
||||
```
|
||||
|
||||
这条边界也决定了模块依赖方向：`server/` 不导入 `bpy` 或 `operators/`；Blender 侧可以读取 Server 产物，但不会复用 Server 中的 Blender 无关算法来创建 RNA 数据。
|
||||
`server/` 保持纯 Python 实现；Operator 在 Blender 主线程读取产物并创建 RNA 数据。
|
||||
|
||||
## 共享能力 { #shared-capabilities }
|
||||
## 共享能力
|
||||
|
||||
`operators/common/` 只保存多个生产功能真实复用的稳定原子能力；完整工作流、功能参数和专用算法留在所属模块。公共层不保留旧路径转发函数，也不为了测试或资产工具建立入口。
|
||||
|
||||
全部可由功能模块调用的函数见[Common 公共函数](common.md)。该索引只列 `common/` 外部的生产调用，不重复列出公共模块内部辅助函数；创建新功能前先核对该页，避免重新实现 Image 引用分流、像素方向、Job 输入生命周期、数据块命名、节点资产加载和对象激活逻辑。
|
||||
|
||||
新增公共函数前应确认至少有两个真实消费者，或它是两个公共流程共同依赖的原子能力。只有单一功能使用的逻辑应留在所属模块；删除或移动能力时同步清理注册、测试、工具脚本和文档，不保留兼容胶水。
|
||||
`common/` 提供 Blender 侧复用的 Image 数据、Region、Depth、Object 和 AI Job 原子能力。公开函数见[Common 公共函数](common.md)。
|
||||
|
||||
@@ -1,12 +1,10 @@
|
||||
# Common 公共函数
|
||||
|
||||
`src/anyimage/operators/common/` 集中已经被多个功能复用的 Blender 侧原子能力，目的是让开发新功能时能够先查找并复用现有实现，避免重复造轮子。
|
||||
|
||||
本页只列功能模块直接调用的公共函数，不列 `common/` 内部辅助函数、测试或资产工具专用函数，也不列公共类型。
|
||||
`src/anyimage/common/` 提供多个功能复用的 Blender 侧原子能力。
|
||||
|
||||
## Image 数据块
|
||||
|
||||
`image_data.py` 处理 Blender `Image` 数据块及其在 Image Empty 上的使用方式，包括像素读取、动画帧、Job 输入、结果 Image 创建和 Empty 引用替换。它不处理 Viewport 手势或 Region 算法。
|
||||
`image_data.py` 处理 Blender `Image` 数据块及其在 Image Empty 上的使用方式，包括像素读取、动画帧、Job 输入、结果 Image 创建和 Empty 引用替换。
|
||||
|
||||
| 函数 | 职责 |
|
||||
| --- | --- |
|
||||
@@ -30,16 +28,14 @@
|
||||
| `image_data.replace_empty_image()` | 执行 Image Empty 结果替换、共享引用分流、旧数据清理、帧设置继承和可选画布对齐。 |
|
||||
| `image_data.image_empty_bounds()` | 计算 Image Empty 在对象局部坐标中的实际显示边界。 |
|
||||
|
||||
`load_*_result_image()` 和 `create_pixel_result_image()` 只创建结果 Image；`replace_empty_image()` 负责把结果提交给当前 Empty。两者分别表达“创建产物”和“替换引用”。
|
||||
|
||||
## Image Region 与视图交互
|
||||
|
||||
这组公共能力使用固定术语：
|
||||
|
||||
- Region 是用户在图片空间圈定的业务范围；`RegionPath` 保存路径点、反选状态和填充规则。
|
||||
- `RegionMask` 是 Region 的栅格化结果，只包含局部像素权重 `values` 和源图 `bounds`。
|
||||
- Mask 只表示二维像素权重或 Alpha 运算，不作为手势、协议或业务范围的别名。
|
||||
- Selection 只用于 Blender 对象选择；图片业务范围统一称为 Region，细化动作称为 Fit to Foreground。
|
||||
- Mask 表示二维像素权重或 Alpha 运算。
|
||||
- Selection 表示 Blender 对象选择；图片业务范围称为 Region，细化动作称为 Fit to Foreground。
|
||||
|
||||
`image_interaction.py` 处理 3D Viewport 中的点击、坐标投影、`ImageRegionGesture`、工具设置和预览绘制；`image_region.py` 负责图片空间 Region 的值、栅格化和 Alpha 裁切。前者负责用户如何圈定 Region，后者负责 Region 如何变成 Mask。
|
||||
|
||||
@@ -71,7 +67,7 @@
|
||||
|
||||
## Depth 产物
|
||||
|
||||
`depth_data.py` 负责 Blender 侧共享的 Depth 文件加载和相机尺度换算；Server 已经写好 EXR，Blender 不再从点场创建第二张 Depth Image。
|
||||
`depth_data.py` 负责 Blender 侧共享的 Depth 文件加载和相机尺度换算，直接加载 Server 写出的 EXR。
|
||||
|
||||
| 函数 | 职责 |
|
||||
| --- | --- |
|
||||
@@ -80,23 +76,22 @@
|
||||
| `depth_data.camera_depth_values()` | 从已加载 Depth Image 读取用于本地标定的 Z 与有效区。 |
|
||||
| `depth_data.depth_uniform_scale()` | 根据相机内参、参考深度和 Image Empty 范围计算统一尺度。 |
|
||||
|
||||
## Mesh 结果构建
|
||||
## Object 构建
|
||||
|
||||
`mesh_result.py` 集中 Convert to Plane 与 Cutout 共同使用的结果构建能力：创建材质、加载节点资产、设置修改器输入，并完成结果对象替换。
|
||||
`object.py` 集中 Convert to Plane 与 Cutout 共用的材质、Modifier 和结果 Object 构建能力；`node.py` 负责加载节点资产。
|
||||
|
||||
| 函数 | 职责 |
|
||||
| --- | --- |
|
||||
| `mesh_result.create_image_material()` | 从 Image Empty 创建包含颜色、位移、Normal Map、Alpha 和动画设置的完整材质。 |
|
||||
| `mesh_result.load_asset_node_group()` | 从随扩展分发的 Blend 资产加载指定 Node Group。 |
|
||||
| `mesh_result.modifier_input_identifier()` | 按接口名称解析 Geometry Nodes Modifier 输入 Identifier。 |
|
||||
| `mesh_result.set_modifier_input()` | 跨受支持 Blender RNA 形式设置 Modifier 输入。 |
|
||||
| `mesh_result.finalize_object_result()` | 激活结果对象，并按需替换或保留源 Empty。 |
|
||||
| `node.load_node_group()` | 从随扩展分发的 Blend 资产加载指定 Node Group。 |
|
||||
| `object.create_image_material()` | 从 Image Empty 创建包含颜色、位移、Normal Map、Alpha 和动画设置的完整材质。 |
|
||||
| `object.modifier_input_identifier()` | 按接口名称解析 Geometry Nodes Modifier 输入 Identifier。 |
|
||||
| `object.set_modifier_input()` | 跨受支持 Blender RNA 形式设置 Modifier 输入。 |
|
||||
| `object.finalize_object_result()` | 激活结果对象，并按需替换或保留源 Empty。 |
|
||||
|
||||
节点资产构建和验证专用函数位于 `tools/node_assets/`，不属于运行时公共能力。
|
||||
|
||||
## AI 任务准备
|
||||
|
||||
`ai_job.py` 处理多个 AI 功能共同使用的任务准备，包括输入路径校验、Environment 与模型检查、Device 选择和模型请求参数组装。DA3 参数只供 Debug Operator 使用；正式几何流程只组装 MoGe-2 参数。它不包含业务 Operator、结果导入或 Undo 操作。
|
||||
`ai_job.py` 处理多个 AI 功能共同使用的任务准备，包括输入路径校验、Environment 与模型检查、Device 选择和模型请求参数组装。
|
||||
|
||||
| 函数 | 职责 |
|
||||
| --- | --- |
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 开发与发布
|
||||
|
||||
AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模块、Manifest 和打包逻辑。AI Runtime 使用另一套 Python 3.12 Environment，不应与仓库开发环境混为一谈。
|
||||
AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模块、Manifest 和打包逻辑。AI Runtime 使用独立的 Python 3.12 Environment。
|
||||
|
||||
## 对应文件
|
||||
|
||||
@@ -9,11 +9,14 @@ AnyImage 的仓库环境用于测试 Blender 侧代码、Server 纯 Python 模
|
||||
├── pyproject.toml
|
||||
├── uv.lock
|
||||
├── .python-version
|
||||
├── pack.py
|
||||
├── sync_models.py
|
||||
├── tools/
|
||||
│ ├── pack.py
|
||||
│ ├── model_exports.py
|
||||
│ ├── sync_models.py
|
||||
│ ├── build_node.py
|
||||
│ └── node_assets/
|
||||
├── src/anyimage/blender_manifest.toml
|
||||
├── tests/
|
||||
├── tools/node_assets/
|
||||
└── .github/workflows/
|
||||
├── test.yml
|
||||
├── build.yml
|
||||
@@ -40,10 +43,10 @@ uv run pytest tests/test_addon.py tests/test_manifest.py tests/test_pack.py -v
|
||||
## 扩展打包
|
||||
|
||||
```bash
|
||||
uv run python pack.py
|
||||
uv run pack
|
||||
```
|
||||
|
||||
`pack.py` 为 `windows-x64`、`macos-arm64` 和 `linux-x64` 分别解析依赖 wheel，生成平台专属 Manifest，再把 `src/anyimage/` 与 wheel 写入 `dist/`：
|
||||
`tools/pack.py` 为 `windows-x64`、`macos-arm64` 和 `linux-x64` 分别解析依赖 wheel，生成平台专属 Manifest，再把 `src/anyimage/` 与 wheel 写入 `dist/`：
|
||||
|
||||
```text
|
||||
dist/
|
||||
@@ -54,21 +57,29 @@ dist/
|
||||
|
||||
本地 `src/anyimage/wheels/` 是 wheel 解析的优先来源，用于携带尚未发布的 BlendJob 构建。依赖、wheel 或 Manifest 变化后，需要同时检查 `pyproject.toml`、`uv.lock`、`blender_manifest.toml` 和打包测试；本地 wheel 内容变化后运行 `uv lock --refresh`。
|
||||
|
||||
## 模型发布
|
||||
|
||||
```bash
|
||||
uv run sync_models
|
||||
```
|
||||
|
||||
`tools/sync_models.py` 从公开原址下载已有 ONNX；Real-ESRGAN General WDN x4v3 与 SAFMN Real x4 则从官方 PyTorch 权重调用 `tools/model_exports.py` 构建。所有制品通过固定大小、SHA-256、ONNX Checker 和 PyTorch/ONNX Runtime 数值对比后，逐文件上传到 R2。添加 `--prepare-only` 可仅准备和验证制品。
|
||||
|
||||
## 文档
|
||||
|
||||
```bash
|
||||
uv run --only-group docs mkdocs serve
|
||||
uv run --only-group docs mkdocs build --strict
|
||||
uv run mkdocs serve
|
||||
uv run mkdocs build --strict
|
||||
```
|
||||
|
||||
站点导航由 `mkdocs.yml` 显式维护，因此移动页面时必须同时更新导航和相对链接。Mike 仍可用于本地版本化发布；CI 则直接构建严格模式站点并部署到 Cloudflare Worker。
|
||||
站点导航由 `mkdocs.yml` 显式维护，因此移动页面时必须同时更新导航和相对链接。本地版本化发布使用 Mike；CI 构建严格模式站点并部署到 Cloudflare Worker。
|
||||
|
||||
## CI
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Main["push main / Pull Request"] --> Test["uv run --frozen pytest"]
|
||||
Tag["push v* tag"] --> Release["测试 → pack.py → Release ZIP"]
|
||||
Tag["push v* tag"] --> Release["测试 → tools/pack.py → Release ZIP"]
|
||||
Docs["main 上文档变更"] --> Site["mkdocs --strict → Cloudflare"]
|
||||
```
|
||||
|
||||
@@ -76,6 +87,6 @@ flowchart TD
|
||||
|
||||
## 许可证
|
||||
|
||||
AnyImage Extension 代码采用 GPL-3.0-or-later，完整文本见仓库 `LICENSE`。模型权重保持各自上游许可证；模型目录声明下载来源、文件校验和许可信息，技术文档不复制可能变化的制品清单。
|
||||
AnyImage Extension 代码采用 GPL-3.0-or-later，完整文本见仓库 `LICENSE`。模型权重保持各自上游许可证；模型目录声明下载来源、文件校验和许可信息。
|
||||
|
||||
Geometry Nodes 资产必须由 Blender 构建和验证，见[节点资产](node-assets.md)。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 内部实现总览
|
||||
|
||||
AnyImage 的实现围绕一条清晰边界展开：Blender 进程负责交互与数据创建，独立 Job Server 负责模型推理和文件处理。两侧通过 BlendJob 传递可序列化参数与 Job 目录中的产物，不跨进程传递 Blender RNA 数据。
|
||||
Blender 进程负责交互与数据创建，独立 Job Server 负责模型推理和文件处理。两侧通过 BlendJob 传递可序列化参数与 Job 目录中的产物。
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
@@ -16,8 +16,6 @@ flowchart TD
|
||||
|
||||
## 项目主干
|
||||
|
||||
总览只展示稳定边界；各功能包的具体文件在对应实现页中展开。
|
||||
|
||||
```text
|
||||
.
|
||||
├── src/anyimage/
|
||||
@@ -26,24 +24,21 @@ flowchart TD
|
||||
│ ├── preferences.py # 扩展级配置
|
||||
│ ├── properties.py # Scene 状态与模型枚举
|
||||
│ ├── runtime.py # BlendJob Runtime 配置
|
||||
│ ├── common/ # Blender 侧共享原子能力
|
||||
│ ├── operators/ # 交互、任务提交与结果导入
|
||||
│ ├── server/ # 无 Blender 依赖的计算端
|
||||
│ ├── assets/ # 随扩展分发的节点资产
|
||||
│ └── wheels/ # 随扩展分发的 BlendJob wheel
|
||||
├── tools/ # Blender 资产构建与验证
|
||||
├── tests/ # Python 自动化测试
|
||||
├── pack.py # 多平台扩展打包
|
||||
└── sync_models.py # ONNX 模型同步
|
||||
├── tools/ # 打包、模型同步与 Blender 节点资产
|
||||
└── tests/ # Python 自动化测试
|
||||
```
|
||||
|
||||
## 文档分层
|
||||
|
||||
- [程序架构](architecture.md)：注册、配置、线程和模块边界。
|
||||
- [Common 公共函数](common.md)：仅列生产功能从 `operators/common/` 外部调用的函数。
|
||||
- [Common 公共函数](common.md)：仅列生产功能从 `common/` 外部调用的函数。
|
||||
- [Job Runtime 与 Server](runtime.md)：任务生命周期、媒体输入和模型 Session。
|
||||
- [Operator 实现索引](operators/index.md)：按 `src/anyimage/operators/` 中的完整功能拆分实现页。
|
||||
- [Job 产物](outputs.md)：文件用途和 Blender 导入关系。
|
||||
- [开发与发布](development.md)：本地环境、测试、打包和 CI。
|
||||
- [节点资产](node-assets.md)：Geometry Nodes 的构建、加载与验证。
|
||||
|
||||
内部实现文档描述模块之间的职责和主要数据流。[Common 公共函数](common.md)按真实外部调用列出开发新功能时应优先复用的稳定入口；函数级分支、参数校验与异常处理仍以源码和测试为准。
|
||||
|
||||
@@ -1,60 +1,52 @@
|
||||
# 节点资产
|
||||
|
||||
AnyImage 将生产功能使用的可复用 Geometry Nodes 和 Shader 节点组统一构建到 `O_AnyImage.blend`，运行时只按名称加载，不动态创建节点组。
|
||||
生产节点组由脚本构建到 `src/anyimage/assets/O_AnyImage.blend`；运行时只加载，不创建节点组。
|
||||
|
||||
## 对应文件
|
||||
## 构建
|
||||
|
||||
```text
|
||||
src/anyimage/
|
||||
├── assets/O_AnyImage.blend
|
||||
├── operators/common/mesh_result.py # 运行时资产加载与 Modifier 输入
|
||||
└── operators/convert_to_plane/nodes.py # Plane 节点资产名称与加载入口
|
||||
|
||||
tools/node_assets/
|
||||
├── build.py # 统一构建入口
|
||||
├── node_graph.py # Cutout 资产构建专用节点图函数
|
||||
├── build_mesh_plane.py
|
||||
├── build_depth_plane.py
|
||||
├── build_material_layers.py
|
||||
├── build_shadeless.py
|
||||
├── build_cutout.py
|
||||
├── validate.py # 资产清单与基础接口
|
||||
├── validate_mesh_plane.py
|
||||
└── validate_cutout.py
|
||||
```
|
||||
|
||||
## 构建与加载
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
Scripts["tools/node_assets/build_*.py"] --> Build["Blender 后台构建"]
|
||||
Build --> Blend["assets/O_AnyImage.blend"]
|
||||
Blend --> Loader["operators/common/mesh_result.py"]
|
||||
Loader --> Modifier["运行时 Node Group / Modifier"]
|
||||
```
|
||||
|
||||
使用 Blender 而不是普通 Python 执行：
|
||||
在项目根目录执行：
|
||||
|
||||
```bash
|
||||
BLENDER_BIN="/c/Program Files/Blender Foundation/Blender 4.5/blender.exe"
|
||||
|
||||
"$BLENDER_BIN" --background --python tools/node_assets/build.py
|
||||
"$BLENDER_BIN" --background --python tools/node_assets/validate.py
|
||||
"$BLENDER_BIN" --background --python tools/node_assets/validate_mesh_plane.py
|
||||
"$BLENDER_BIN" --background --python tools/node_assets/validate_cutout.py
|
||||
uv run build_node
|
||||
```
|
||||
|
||||
`build.py` 从空 Factory 文件开始，依次构建 `O Mesh Plane`、`O Image Depth Plane`、`O Image Layer`、`O Image Depth Layer`、`O Shadeless`、四个 Cutout 内部节点组与公开修改器节点组 `O Image Cutout`，再保存唯一资产文件。`O Image Cutout` 用 Menu Switch 包装四个内部组；运行时 Loader 只加载这个稳定入口，Blender 4.5 根据 Shape 菜单依赖只显示当前分支实际使用的输入。
|
||||
脚本依次构建资产、运行三项 Blender 验证和完整测试，任一步失败即退出。
|
||||
|
||||
## 验证范围
|
||||
脚本按 `--blender`、环境变量 `BLENDER_BIN`、项目 `.env`、`PATH` 的顺序查找 Blender。无法自动找到时，在项目根目录的 `.env` 中配置：
|
||||
|
||||
基础验证检查完整发布资产清单、节点树类型、Modifier 标记、接口顺序和 Fake User。专项验证继续检查：
|
||||
```dotenv
|
||||
BLENDER_BIN="/absolute/path/to/blender"
|
||||
```
|
||||
|
||||
- Mesh Plane 的接口、细分、Thickness 和几何求值；
|
||||
- `O Image Cutout` 的公开接口、Shape 菜单和四个内部组的依赖关系；
|
||||
- 节点不重叠、主要连线保持从左向右；
|
||||
- 局部 Group Input 未使用输出隐藏；
|
||||
- Cleanup 只在四条分支之前执行，Smooth 只在菜单选择之后执行；
|
||||
- Repeat Zone 数量和四种 Shape 的关键几何求值稳定。
|
||||
`.env` 已被 Git 忽略。临时指定路径或跳过 Python 测试：
|
||||
|
||||
节点资产接口变化时，应运行全部四个 Blender 入口和完整 Python 测试。只修改 Python、Markdown 或打包逻辑时无需重建 `.blend`。Blender 自动生成的 `.blend1` 等备份不属于发布资产。
|
||||
```bash
|
||||
uv run build_node --blender "/path/to/blender"
|
||||
uv run build_node --skip-tests
|
||||
```
|
||||
|
||||
## 资产清单
|
||||
|
||||
| 节点组 | 构建模块 |
|
||||
| --- | --- |
|
||||
| `O Mesh Plane` | `build_mesh_plane.py` |
|
||||
| `O Image Depth Plane` | `build_depth_plane.py` |
|
||||
| `O Image Layer`、`O Image Depth Layer` | `build_material_layers.py` |
|
||||
| `O Shadeless` | `build_shadeless.py` |
|
||||
| `O Image Cutout` | `build_cutout.py` |
|
||||
| `O Image Surface`、`O Image Balloon` | `build_cutout.py` |
|
||||
| `O Image Depth Balloon`、`O Image Depth Surface` | `build_cutout.py` |
|
||||
|
||||
构建从空 Factory 文件生成全部节点组，关闭 `.blend1` 备份，并覆盖唯一发布资产。
|
||||
|
||||
## 修改节点组
|
||||
|
||||
1. 修改 `tools/node_assets/build_*.py`；
|
||||
2. 更新对应验证；
|
||||
3. 运行一键构建脚本；
|
||||
4. 搜索并清理旧名称、接口和路径；
|
||||
5. 检查 `.blend`、代码、测试和文档差异。
|
||||
|
||||
接口、节点、连线、默认值或布局变化时必须重建。只修改运行时 Python、Markdown 或打包逻辑时无需重建。
|
||||
|
||||
`O_AnyImage.blend1` 等备份不应提交或打包。
|
||||
|
||||
@@ -23,11 +23,11 @@ flowchart TD
|
||||
|
||||
入口位于 `src/anyimage/operators/ai_setup.py`。`SetupAIEnvironment` 通过 `properties.py` 中的 `ai_status()` 读取环境和模型状态，并根据结果结束、安装环境或调用 `DownloadRequiredModels`。对话框同时显示预计下载量和缺失模型名称。
|
||||
|
||||
`runtime.py` 提供当前 Environment 与 Server 状态；Server 正忙时不会启动新的安装流程。`OpenAIEnvironmentSettings` 也在 `ai_setup.py` 中，它只负责打开 AnyImage 的扩展首选项。
|
||||
`runtime.py` 提供当前 Environment 与 Server 状态；Server 正忙时不会启动新的安装流程。`OpenAIEnvironmentSettings` 打开 AnyImage 的扩展首选项。
|
||||
|
||||
### 安装独立环境
|
||||
|
||||
环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。普通源与中国镜像使用同一条安装流程，`use_mirror` 只决定 uv、Python 和 Python 包的下载源，不改变模型来源。
|
||||
环境尚未就绪时，`SetupAIEnvironment` 调用 Runtime 注册的安装 Operator。`use_mirror` 决定 uv、Python 和 Python 包的下载源，模型使用模型目录中声明的来源。
|
||||
|
||||
安装完成后继续进入模型下载，不在 Blender Python 中加载 ONNX Runtime 或模型依赖。
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ flowchart TD
|
||||
Target --> Paint["Brush Texture"]
|
||||
```
|
||||
|
||||
整条流程运行在 Blender 进程中，不使用 Job Server。快捷键会先尊重 Blender 自己的 Copy/Paste；只有系统剪贴板出现新的图片内容时，AnyImage 才接管粘贴。
|
||||
快捷键优先处理 Blender 自己的 Copy/Paste；系统剪贴板出现新的图片内容时，AnyImage 接管粘贴。
|
||||
|
||||
## 节点说明
|
||||
|
||||
@@ -28,7 +28,7 @@ flowchart TD
|
||||
|
||||
### 读取系统图片
|
||||
|
||||
`clipboard.py` 负责平台差异。Windows 读取 DIB 或 DIBV5 并补成 BMP；macOS 和 Linux 调用系统提供的图片导出命令。无论来源平台，输出都收敛为图片字节和扩展名，后续步骤不再判断操作系统。
|
||||
`clipboard.py` 负责平台差异。Windows 读取 DIB 或 DIBV5 并补成 BMP；macOS 和 Linux 调用系统提供的图片导出命令。各平台输出统一为图片字节和扩展名，再交给后续步骤。
|
||||
|
||||
### 创建或复用 Packed Image
|
||||
|
||||
@@ -38,4 +38,4 @@ flowchart TD
|
||||
|
||||
落点仍在 `actions.py` 中完成：3D View 创建 Reference 或 Plane，Node Editor 创建与当前节点树匹配的 Image 节点，绘制模式把 Image 配置为当前画笔的 Texture。鼠标位置和视图位置也在这里换算。
|
||||
|
||||
Plane 路径调用 `convert_to_plane/mesh_plane.py` 创建基础网格，并使用 `convert_to_plane/nodes.py` 提供的 `O Mesh Plane` 节点组。`clipboard_image/__init__.py` 只负责入口和快捷键，具体 Blender 数据始终由 `actions.py` 创建。
|
||||
Plane 路径调用 `convert_to_plane/mesh_plane.py` 创建基础网格，并从节点资产加载 `O Mesh Plane`。`actions.py` 创建 Blender 数据。
|
||||
|
||||
@@ -15,7 +15,7 @@ flowchart TD
|
||||
Import --> Depth["创建 Depth Plane Object"]
|
||||
```
|
||||
|
||||
两条路径共用 Image Empty 的显示范围、颜色材质和基础 Plane。Depth Plane 多出一次 Server Job，并由节点根据相机元数据把 Z Depth 转换为局部位移。正式流程只使用 MoGe-2；DA3 只保留 Debug 入口。
|
||||
两条路径共用 Image Empty 的显示范围、颜色材质和基础 Plane。Depth Plane 通过一次 MoGe-2 Server Job 生成 Z Depth，再由节点根据相机元数据转换为局部位移。
|
||||
|
||||
## 节点说明
|
||||
|
||||
|
||||
@@ -21,11 +21,7 @@ flowchart TD
|
||||
Ready --> Build --> Create
|
||||
```
|
||||
|
||||
Surface 与 Balloon 可以完全在 Blender 中完成；启用 Fit to Foreground、生成 Depth Shape 或 Normal Map 时，中间会经过一次 Server Job。
|
||||
|
||||
两条路径的区别只在中间是否需要 Server 产物。回到 Blender 后，它们都使用最终的 `RegionMask` 构建同一种 `BaseShape`，再由同一入口创建对象。Server 不创建 Blender Mesh，也不访问 `bpy`。
|
||||
|
||||
下文中的 Blender 侧文件相对 `src/anyimage/operators/cutout_tool/`，Server 侧文件相对 `src/anyimage/server/`。
|
||||
Surface 与 Balloon 直接使用 `RegionMask` 构建 `BaseShape`；Fit to Foreground、Depth Shape 和 Normal Map 先通过 Server Job 生成所需产物。
|
||||
|
||||
## 节点说明
|
||||
|
||||
@@ -33,13 +29,13 @@ Surface 与 Balloon 可以完全在 Blender 中完成；启用 Fit to Foreground
|
||||
|
||||
Cutout 工具由 `__init__.py` 注册，交互从 `main.py` 中的 `SelectCutoutRegion` 开始。它接收 Lasso 或双击整图手势，把图片空间路径保存为 `RegionPath`，然后调用 `interaction.py` 打开 Shape 饼菜单。
|
||||
|
||||
`interaction.py` 在这里完成 Region 有效性检查、读取三个工具选项，并根据 **Mesh Sampling Spacing** 换算期望网格分辨率；它不定义 Operator。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 `shape.py`。
|
||||
`interaction.py` 完成 Region 有效性检查、读取三个工具选项，并根据 **Mesh Sampling Spacing** 换算期望网格分辨率。菜单中的 Surface、Balloon、Depth Balloon 和 Depth Surface，以及它们对应的节点分支索引，统一来自 `shape.py`。
|
||||
|
||||
### 栅格化 Region
|
||||
|
||||
用户选定 Shape 后，`main.py` 中的 `CutoutRegionToShape` 接过主线。它使用 `operators/common/image_region.py` 把 `RegionPath` 栅格化为 `RegionMask`：`values` 保存局部像素权重，`bounds` 保存它在源图中的位置。套索外和源图透明区域不会进入最终 Region。
|
||||
用户选定 Shape 后，`main.py` 中的 `CutoutRegionToShape` 接过主线。它使用 `common/image_region.py` 把 `RegionPath` 栅格化为 `RegionMask`：`values` 保存局部像素权重，`bounds` 保存它在源图中的位置。套索外和源图透明区域不会进入最终 Region。
|
||||
|
||||
此时也会应用 **Maximum Cutout Mesh Resolution**。它限制裁切区域的最长采样边，对四种 Shape 一视同仁，与是否使用 AI 无关。
|
||||
此时也会应用 **Maximum Cutout Mesh Resolution**，统一限制四种 Shape 裁切区域的最长采样边。
|
||||
|
||||
### 需要后台生成数据？
|
||||
|
||||
@@ -49,23 +45,23 @@ Cutout 工具由 `__init__.py` 注册，交互从 `main.py` 中的 `SelectCutout
|
||||
- 选择 Depth Balloon 或 Depth Surface；
|
||||
- 开启 **Generate Normal Map**。
|
||||
|
||||
没有开启两个 AI 选项的 Surface 和 Balloon 会直接沿用本地 `RegionMask`。
|
||||
Surface 和 Balloon 的本地路径直接沿用 `RegionMask`。
|
||||
|
||||
### 执行 Fit to Foreground，生成 Depth / Normal 产物
|
||||
|
||||
`main.py` 把请求提交给 `server/jobs/cutout.py`。这个 Job 只生成本次 Shape 实际需要的产物：
|
||||
`main.py` 把请求提交给 `server/jobs/cutout.py`，生成本次 Shape 需要的产物：
|
||||
|
||||
- **Fit to Foreground** 调用 `server/region/refine_region.py`，写出收紧后的 `region.png` 和 `region_bounds.json`；
|
||||
- 需要 Vector Depth 时写出相机空间 XYZ 组成的 `vector-depth.exr`，需要 Z Depth 时写出 `z-depth.exr`，两者都配套 `depth.json`；
|
||||
- **Generate Normal Map** 根据既定空间写出 `tangent-normal.png` 或 `object-normal.png`。
|
||||
|
||||
Depth 与 Normal Map 同时需要时，共享同一次 MoGe-2 Prediction。Prediction 只存在于 Server 内存，Job 目录只保留 Blender 可直接加载的图片和 JSON。Depth Surface 的 Normal Map 编码为 Cutout 对象空间，其正面是对象局部 `-X`；其余 Shape 使用 Tangent Space。Normal Space 由 `main.normal_mode_for_shape()` 根据 Shape 决定，不是单独的用户选项。
|
||||
Depth 与 Normal Map 共享同一次 MoGe-2 Prediction。Depth Surface 的 Normal Map 编码为 Cutout 对象空间，其正面是对象局部 `-X`；其余 Shape 使用 Tangent Space。`main.normal_mode_for_shape()` 根据 Shape 确定 Normal Space。
|
||||
|
||||
**Maximum AI Input Size** 只限制 BEN2 和 MoGe-2 看到的分析图长边。它不改变网格密度，也不降低最终颜色图分辨率。DA3 不进入这条正式路径，只保留 Debug 功能。
|
||||
**Maximum AI Input Size** 约束 BEN2 和 MoGe-2 的分析图长边；网格密度使用 **Maximum Cutout Mesh Resolution**，最终颜色图使用源图裁切分辨率。
|
||||
|
||||
### 构建 BaseShape
|
||||
|
||||
Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，直接加载并 Pack Depth 与 Normal 图片；本地路径则直接使用已有数据。两者最终都进入 `main.create_cutout_shape()`，再调用 `geometry.py` 中的 `build_base_shape()`：
|
||||
Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，加载并 Pack Depth 与 Normal 图片。`main.create_cutout_shape()` 调用 `geometry.py` 中的 `build_base_shape()`：
|
||||
|
||||
1. 从最终 `RegionMask` 提取外轮廓和孔洞；
|
||||
2. 按 Mesh Sampling Spacing 生成轮廓与内部采样点；
|
||||
@@ -77,7 +73,7 @@ Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，直
|
||||
|
||||
### 创建 Blender 对象
|
||||
|
||||
`main.create_cutout_shape()` 把 `BaseShape` 和可选产物交给 `object.py` 的 `create_shape_object()`。这里创建裁切后的 Color Image、Material、Mesh Object，并挂上统一的 `O Image Cutout` Modifier。材质通过 `operators/common/mesh_result.py` 创建，Cutout 使用 `1.2` 的 IOR。Color Image 是按最终 Region 包围矩形裁切的源图 RGBA；RegionMask 不写入颜色图 Alpha，源图原有 Alpha 会原样保留。
|
||||
`main.create_cutout_shape()` 把 `BaseShape` 和可选产物交给 `object.py` 的 `create_shape_object()`。这里创建裁切后的 Color Image、Material、Mesh Object，并挂上统一的 `O Image Cutout` Modifier。材质通过 `common/object.py` 创建，Cutout 使用 `1.2` 的 IOR。Color Image 按最终 Region 包围矩形裁切源图并保留 RGBA。
|
||||
|
||||
| Shape | Modifier 如何形成结果 | 必需后台产物 |
|
||||
| --- | --- | --- |
|
||||
@@ -88,6 +84,6 @@ Job 完成后，`main.py` 在 Blender 主线程读取可选的 RegionMask，直
|
||||
|
||||
Depth Shape 的 Base Plane Depth，以及 Depth Balloon 的 Direction，都由 `object.py` 调用 `geometry.py` 的标定函数，根据最终 Region Alpha 计算。透明像素达到 `5%` 时使用有效 Region 自适应标定，否则使用稳定的固定基准。
|
||||
|
||||
Normal Map 是材质细节，不改变上述四种 Shape 的几何分类。关闭时材质使用几何法线；开启时，`object.py` 把生成的图片和已经确定的 Normal Space 交给材质节点。最后 `main.py` 提交 Undo，整条 Cutout 流程结束。
|
||||
Normal Map 关闭时材质使用几何法线；开启时，`object.py` 把生成的图片和已经确定的 Normal Space 交给材质节点。最后 `main.py` 提交 Undo，整条 Cutout 流程结束。
|
||||
|
||||
Balloon 与 Depth Balloon 的材质会创建 Geometry Attribute 节点，把 `o_balloon` 的 Float 输出直接连接到 `O Image Layer` 已有的 **Normal Scale**；Surface 与 Depth Surface 不建立这条连接。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Debug Operator
|
||||
|
||||
Debug Operator 从面板中的模型参数发起一次原始推理，把结果文件留在 Job 目录中供开发者检查，不创建用户场景对象。
|
||||
Debug Operator 从面板中的模型参数发起一次原始推理，把结果文件写入 Job 目录并打开目录供开发者检查。
|
||||
|
||||
## 执行过程
|
||||
|
||||
@@ -13,7 +13,7 @@ flowchart TD
|
||||
Output --> Directory["打开 Job 目录"]
|
||||
```
|
||||
|
||||
DA3、MoGe-2、BEN2 和 Upscale 都走这条调试路径。它验证模型、设备、请求参数和输出格式，但不代表正式功能的对象创建流程。
|
||||
DA3、MoGe-2、BEN2 和 Upscale 都走这条调试路径，用于验证模型、设备、请求参数和输出格式。
|
||||
|
||||
## 节点说明
|
||||
|
||||
@@ -25,8 +25,8 @@ DA3、MoGe-2、BEN2 和 Upscale 都走这条调试路径。它验证模型、设
|
||||
|
||||
`debug.py` 分别提交 `debug-da3`、`debug-moge2`、`debug-ben2` 和 `debug-upscale` Job。Server 侧由 `server/jobs/debug_predictions.py` 接收请求，再调用相应模型适配器。
|
||||
|
||||
DA3 和 MoGe-2 的可视化与数组输出由 `server/outputs/debug_da3.py`、`server/outputs/debug_moge2.py` 写出；BEN2 与 Upscale 保留模型返回的图片结果。这里允许 DA3 继续存在，但它不会被 Plane、Depth Plane 或 Cutout 的正式 Operator 调用。
|
||||
DA3 和 MoGe-2 的可视化与数组输出由 `server/outputs/debug_da3.py`、`server/outputs/debug_moge2.py` 写出；BEN2 与 Upscale 保存模型返回的图片结果。
|
||||
|
||||
### 查看结果
|
||||
|
||||
任务完成后，`debug.py` 的 `_open_job_directory()` 调用 Blender 的路径打开操作，直接显示该 Job 的目录。响应阶段不导入 Image，不创建 Mesh、Material 或 Modifier，也不修改当前场景。
|
||||
任务完成后，`debug.py` 的 `_open_job_directory()` 调用 Blender 的路径打开操作，直接显示该 Job 的目录。
|
||||
|
||||
@@ -24,13 +24,13 @@ flowchart TD
|
||||
|
||||
`operators/image_tool/__init__.py` 汇总注册类型；`box.py`、`lasso.py`、`line.py` 和 `polyline.py` 分别定义四个 WorkspaceTool。它们都把操作交给 `edit_mask.py` 中的 `EditImageMask`。
|
||||
|
||||
屏幕坐标投射、点击选择、轨迹预览和状态切换来自 `operators/common/image_interaction.py`。Lasso 按移动距离采点并合并近似共线点；Line 扩展为有向半平面；Polyline 在确认时闭合路径。
|
||||
屏幕坐标投射、点击选择、轨迹预览和状态切换来自 `common/image_interaction.py`。Lasso 按移动距离采点并合并近似共线点；Line 扩展为有向半平面；Polyline 在确认时闭合路径。
|
||||
|
||||
### RegionPath → RegionMask
|
||||
|
||||
`EditImageMask` 通过 `operators/common/image_region.py` 把手势整理为 `RegionPath`，再栅格化为 `RegionMask`。凹多边形使用三角剖分，自交路径使用 `EVEN_ODD` 填充。预览缓存只在轨迹变化时更新。
|
||||
`EditImageMask` 通过 `common/image_region.py` 把手势整理为 `RegionPath`，再栅格化为 `RegionMask`。凹多边形使用三角剖分，自交路径使用 `EVEN_ODD` 填充。预览缓存只在轨迹变化时更新。
|
||||
|
||||
Box 和 Lasso 分别读取自己的 **Fit to Foreground** 设置。Line 与 Polyline 强制关闭该选项，因此不会改变直线边界。
|
||||
Box 和 Lasso 分别读取自己的 **Fit to Foreground** 设置。Line 与 Polyline 直接使用几何边界。
|
||||
|
||||
### Fit to Foreground
|
||||
|
||||
@@ -40,6 +40,6 @@ Box 和 Lasso 分别读取自己的 **Fit to Foreground** 设置。Line 与 Poly
|
||||
|
||||
### 源 Alpha × RegionMask
|
||||
|
||||
`edit_mask.py` 保留源 RGB，只把最终 `RegionMask` 乘入源 Alpha，再按非零 Alpha 紧裁切。像素读取、结果 Image 创建和共享引用处理使用 `operators/common/image_data.py`。
|
||||
`edit_mask.py` 保留源 RGB，只把最终 `RegionMask` 乘入源 Alpha，再按非零 Alpha 紧裁切。像素读取、结果 Image 创建和共享引用处理使用 `common/image_data.py`。
|
||||
|
||||
公共 Image Empty 替换入口会同步更新 `empty_display_size` 和 `empty_image_offset`，因此裁切后的内容仍对齐原图片平面，对象 `matrix_world` 不变。Perspective 使用相同的像素写回能力，但属于独立工具和状态。
|
||||
公共 Image Empty 替换入口同步更新 `empty_display_size` 和 `empty_image_offset`，使裁切后的内容对齐原图片平面并保持对象 `matrix_world`。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Operator 实现索引
|
||||
|
||||
`src/anyimage/operators/` 负责 Blender 侧交互、Job 请求组装和结果导入。内部实现按完整功能包或顶层业务模块拆页；`common/` 的边界见[程序架构](../architecture.md)，实际公开入口见[Common 公共函数](../common.md)。
|
||||
`src/anyimage/operators/` 负责 Blender 侧交互、Job 请求组装和结果导入。
|
||||
|
||||
| Operator 路径 | 实现页 | 主要职责 |
|
||||
| --- | --- | --- |
|
||||
@@ -15,4 +15,4 @@
|
||||
| `operators/remove_background.py` | [Remove Background](remove-background.md) | BEN2 去背与结果替换 |
|
||||
| `operators/upscale.py` | [Upscale](upscale.md) | 当前 Image 的 4× 高清与输入长边检查 |
|
||||
|
||||
`operators/__init__.py` 只聚合注册类，不承载独立业务流程。具体类的注册和逆序注销由扩展入口统一管理，整体边界见[程序架构](../architecture.md)。
|
||||
`operators/__init__.py` 聚合注册类，扩展入口按顺序注册并逆序注销。
|
||||
|
||||
@@ -15,7 +15,7 @@ flowchart TD
|
||||
Crop --> Write["Pack 并写回 Empty"]
|
||||
```
|
||||
|
||||
预览只在第四点确认后生成一次；之后拖动鼠标只改变目标宽高比。用户确认时才执行全分辨率 Warp。整个流程在 Blender 进程内完成，不使用 Job Server。
|
||||
第四点确认后生成预览，拖动鼠标调整目标宽高比，用户确认后执行全分辨率 Warp。整个流程在 Blender 进程内完成。
|
||||
|
||||
## 节点说明
|
||||
|
||||
@@ -23,18 +23,18 @@ flowchart TD
|
||||
|
||||
`operators/perspective_tool/__init__.py` 导出注册类型，交互和计算集中在 `edit_perspective.py`。`ImagePerspectiveTool` 启动 `EditImagePerspective`，后者接受任意顺序的四个图片角点，再根据源图 X/Y 方向整理成不交错的凸 Quad。
|
||||
|
||||
图片坐标投射和首次点击选择复用 `operators/common/image_interaction.py`。Perspective 始终把四点称为 Quad，不使用 Image Tool 的 Region 或 Mask 状态。
|
||||
图片坐标投射和首次点击选择复用 `common/image_interaction.py`。四个角点在该流程中统一表示为 Quad。
|
||||
|
||||
### 预览并调整比例
|
||||
|
||||
第四点确定后，`edit_perspective.py` 创建一次 512 × 512 预览纹理。鼠标移动只更新目标宽高比和 HUD，可吸附到常用比例，不会重复重采样源图。
|
||||
第四点确定后，`edit_perspective.py` 创建 512 × 512 预览纹理。鼠标移动更新目标宽高比和 HUD，并可吸附到常用比例。
|
||||
|
||||
输出尺寸根据 Quad 边长和目标比例计算，最长边不超过 8192 px，总像素不超过 16,777,216。
|
||||
|
||||
### 执行 Homography
|
||||
|
||||
确认后，`edit_perspective.py` 计算 Homography，并按 256 行分块处理全分辨率像素。插值使用预乘 Alpha，避免透明边缘混入黑色。Perspective 只做形变，不提供 Fit to Foreground 或反选。
|
||||
确认后，`edit_perspective.py` 计算 Homography，并按 256 行分块处理全分辨率像素。插值使用预乘 Alpha，避免透明边缘混入黑色。
|
||||
|
||||
### 裁切并写回
|
||||
|
||||
Warp 结果按可见 Alpha 紧裁切，再通过 `operators/common/image_data.py` 创建 Packed Image 并替换当前 Empty。结果宽高比可能不同于原 Quad 的轴对齐范围，因此写回时保持中心和覆盖尺度近似一致，而不是复用原图片像素范围。
|
||||
Warp 结果按可见 Alpha 紧裁切，再通过 `common/image_data.py` 创建 Packed Image 并替换当前 Empty。写回时保持中心和覆盖尺度近似一致。
|
||||
|
||||
@@ -14,13 +14,13 @@ flowchart TD
|
||||
Import --> Replace["替换 Empty.data"]
|
||||
```
|
||||
|
||||
Blender 负责媒体输入准备和结果导入，BEN2 推理留在 Server。Packed 图片和内存中修改过的单图会先导出临时文件；可直接读取的文件图片、视频和序列沿用原路径。
|
||||
Packed 图片和内存中修改过的单图会先导出临时文件；文件图片、视频和序列沿用原路径。
|
||||
|
||||
## 节点说明
|
||||
|
||||
### 准备媒体输入
|
||||
|
||||
入口是 `operators/remove_background.py` 中的 `RemoveImageBackground`。它检查当前对象、AI Environment 和帧数，再调用 `operators/common/image_data.py` 的 `prepare_image_input()`。多帧输入会先写入 Scene 中的抽帧设置。
|
||||
入口是 `operators/remove_background.py` 中的 `RemoveImageBackground`。它检查当前对象、AI Environment 和帧数，再调用 `common/image_data.py` 的 `prepare_image_input()`。多帧输入会先写入 Scene 中的抽帧设置。
|
||||
|
||||
准备完成后，内部 Operator `RunBackgroundRemoval` 保存输入路径、源对象名和临时文件清理标记。
|
||||
|
||||
@@ -32,6 +32,6 @@ BEN2 推理前先用源 Alpha 屏蔽透明区域，模型输出的前景 Alpha
|
||||
|
||||
### 导入并替换结果
|
||||
|
||||
Job 返回后，`remove_background.py` 的 `apply_background_response()` 调用 `operators/common/image_data.py` 创建单图或序列 Image，并恢复源 Image User 的帧起点、偏移和循环设置。
|
||||
Job 返回后，`remove_background.py` 的 `apply_background_response()` 调用 `common/image_data.py` 创建单图或序列 Image，并恢复源 Image User 的帧起点、偏移和循环设置。
|
||||
|
||||
同一公共入口随后替换 `Empty.data`。旧 Image 没有其他用户且未启用 Fake User 时会被清理，结果继承原名；否则保留旧数据块。最后提交一个 Remove Background Undo 步骤，并清理本次创建的临时输入。
|
||||
`replace_empty_image()` 随后替换 `Empty.data`，提交一个 Remove Background Undo 步骤，并清理本次创建的临时输入。
|
||||
|
||||
@@ -25,20 +25,20 @@ flowchart TD
|
||||
|
||||
入口位于 `operators/upscale.py`。`UpscaleImage.poll()` 读取 `preferences.py` 中的 **Maximum AI Input Size**；当前 Image 长边必须严格小于该值。菜单显示的预计尺寸来自同一文件的 `upscale_output_size()`。
|
||||
|
||||
执行时，`upscale.py` 冻结当前模型和输入上限，并通过 `operators/common/image_data.py` 准备单图、视频或序列输入。Packed Image 与内存修改结果会导出临时文件，多帧输入保留帧起点和抽帧设置。
|
||||
执行时，`upscale.py` 冻结当前模型和输入上限，并通过 `common/image_data.py` 准备单图、视频或序列输入。Packed Image 与内存修改结果会导出临时文件，多帧输入保留帧起点和抽帧设置。
|
||||
|
||||
### 分块放大 RGB
|
||||
|
||||
`UpscaleImage` 提交 `upscale-image` Job。`server/jobs/upscale.py` 展开媒体帧并逐帧调用模型；`server/models/upscale.py` 负责输入约束、RGB/Alpha 分离和结果合并，`server/models/onnx_upscale.py` 以 256 × 256 分块执行 4× ONNX 推理并带入相邻上下文。
|
||||
|
||||
`server/media/resolution.py` 统一解释输入长边上限。正式 Upscale 在 Blender 侧直接禁用超限图片，因此不会进入预缩放路径，输出长边小于上限的四倍；模型层仍保留同一限制作为任务边界。
|
||||
`server/media/resolution.py` 统一解释输入长边上限。Blender 侧要求源图长边小于该值，结果长边小于该值的四倍。
|
||||
|
||||
### 合并 Alpha
|
||||
|
||||
Alpha 不进入模型，由 `server/models/upscale.py` 使用 Lanczos 放大到目标尺寸，再与 4× RGB 合并为 RGBA。Provider 资源不足时，Server 释放当前 Upscale Session，并返回降低输入上限或改用 CPU 的提示。
|
||||
`server/models/upscale.py` 使用 Lanczos 将 Alpha 放大到目标尺寸，再与 4× RGB 合并为 RGBA。Provider 资源不足时，Server 释放当前 Upscale Session，并返回降低输入上限或改用 CPU 的提示。
|
||||
|
||||
### 导入并替换结果
|
||||
|
||||
响应阶段回到 `operators/upscale.py`，通过 `operators/common/image_data.py` 读取 `upscale.*` 结果序列并替换当前 Empty。源 Image 没有其他用户且未启用 Fake User 时会被清理并由结果继承名称；存在其他用户时只替换当前 Empty 的引用。
|
||||
响应阶段回到 `operators/upscale.py`，通过 `common/image_data.py` 读取 `upscale.*` 结果序列并替换当前 Empty。
|
||||
|
||||
结果不添加 Upscale 专属数据块后缀，也不保留来源引用。后续再次 Upscale 或转换 Depth Plane 时，读取的都是当前结果 Image。
|
||||
后续 Upscale 和 Depth Plane 都以当前结果 Image 为输入。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Job 产物
|
||||
|
||||
Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通图片、JSON 或 Debug NPZ；Blender 只读取 Job 返回值明确声明的文件，再创建最终 Image、Mesh、Material 与 Object。
|
||||
Server 在 Job 目录写入图片、JSON 或 Debug NPZ；Blender 根据 Job 返回值读取文件并创建 Image、Mesh、Material 与 Object。
|
||||
|
||||
## 正式 Job
|
||||
|
||||
@@ -12,7 +12,7 @@ Job 目录是 Server 与 Blender Operator 的交换边界。Server 写入普通
|
||||
| `generate-depth-plane-geometry` | `image.0001.*`、`z-depth.exr`、`depth.json` | 创建 Depth Plane |
|
||||
| `generate-cutout-artifacts` | 可选 Region、Depth 与 Normal 文件 | 创建 Cutout Shape 与材质 |
|
||||
|
||||
两个 Depth Job 都不输出 Blender 网格。Server 保存可由 Blender 直接加载的模型空间 EXR；轮廓提取、三角化、Depth 标定以及 Blender 数据创建仍在主线程完成。
|
||||
Depth Job 保存可由 Blender 直接加载的模型空间 EXR；Blender 主线程负责轮廓提取、三角化、Depth 标定和数据创建。
|
||||
|
||||
## Depth 与 Normal 文件
|
||||
|
||||
@@ -26,7 +26,7 @@ MoGe-2 Prediction 只存在于 Server 内存。`geometry/prediction_artifacts.py
|
||||
| `tangent-normal.png` | Tangent Space Normal Map |
|
||||
| `object-normal.png` | Object Space Normal Map |
|
||||
|
||||
Blender 通过 `operators/common/depth_data.py` 直接加载 EXR，设为 Non-Color 并 Pack；不会从 NumPy 点场再创建一张 Depth Image。Job 文件名不改变 Blender 数据块命名：Depth 与 Normal 仍分别使用 `depth_data_name()` 和 `normal_data_name()`。Blender 读取 Z 与 Alpha 只用于最终 Region 的本地标定，Geometry Nodes 直接采样已加载的 EXR。
|
||||
Blender 通过 `common/depth_data.py` 加载 EXR，设为 Non-Color 并 Pack。Depth 与 Normal 数据块分别由 `depth_data_name()` 和 `normal_data_name()` 命名。Blender 读取 Z 与 Alpha 进行最终 Region 的本地标定，Geometry Nodes 采样已加载的 EXR。
|
||||
|
||||
## Cutout Region 产物
|
||||
|
||||
@@ -37,7 +37,7 @@ Blender 先把 `RegionPath` 栅格化为 `RegionMask`，再把局部 RGBA 作为
|
||||
- 需要 Z Depth 时请求 `z-depth.exr` 与 `depth.json`；
|
||||
- Normal Map 按空间请求 `tangent-normal.png` 或 `object-normal.png`。
|
||||
|
||||
未启用 Fit to Foreground，且不需要 Depth 或 Normal Map 时，Surface 与 Balloon 不提交 Job。最终颜色图仍由 Blender 从源 Image 裁切，并把 Alpha 乘以最终 `RegionMask`。
|
||||
Surface 与 Balloon 的本地路径直接使用 `RegionMask` 构建 Shape。最终颜色图由 Blender 按 Region 范围裁切源 Image，并保留源 RGBA。
|
||||
|
||||
## Debug 产物
|
||||
|
||||
@@ -48,4 +48,4 @@ Blender 先把 `RegionPath` 栅格化为 `RegionMask`，再把局部 RGBA 作为
|
||||
| `debug-ben2` | `foreground*.png` |
|
||||
| `debug-upscale` | `prediction*.png` |
|
||||
|
||||
Debug Job 只用于直接检查模型适配层，不参与正式对象创建流程。
|
||||
Debug Job 保存模型适配层的直接输出。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Job Runtime 与 Server
|
||||
|
||||
AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧只准备输入、提交普通字典参数并导入结果；`server/` 不依赖 `bpy`。
|
||||
AnyImage 使用 BlendJob 管理独立 Python Environment、Server 进程与单 Worker 队列。Blender 侧准备输入、提交普通字典参数并导入结果。
|
||||
|
||||
## 目录职责
|
||||
|
||||
@@ -20,7 +20,7 @@ src/anyimage/
|
||||
└── outputs/ # Debug Prediction 序列化
|
||||
```
|
||||
|
||||
公开 Job 不互相导入实现。`jobs/` 只编排，稳定的原子能力放在对应领域目录中。
|
||||
`jobs/` 编排任务，领域目录提供媒体、Region、Geometry、模型和输出能力。
|
||||
|
||||
## 生命周期
|
||||
|
||||
@@ -52,15 +52,15 @@ Job 在阶段边界调用 `context.check_cancelled()`，并把稳定产物写入
|
||||
|
||||
## 尺寸约束
|
||||
|
||||
`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map、Fit to Foreground 的模型分析图长边；不会降低材质颜色图分辨率。
|
||||
`server/media/resolution.py` 提供 **Maximum AI Input Size**，默认 `2048 px`。它限制 Upscale 的可提交源图长边，以及 Depth、Normal Map、Fit to Foreground 的模型分析图长边；材质颜色图使用原始分辨率。
|
||||
|
||||
Cutout 另有 Blender 侧的 **Maximum Cutout Mesh Resolution**。它限制所有 Cutout Shape 的网格采样密度，包括完全不使用 AI 的 Surface 与 Balloon。两个设置没有隐式绑定。
|
||||
Blender 侧的 **Maximum Cutout Mesh Resolution** 统一限制所有 Cutout Shape 的网格采样密度。
|
||||
|
||||
`generate-depth-plane-geometry` 与 `generate-cutout-artifacts` 只接受一帧，因此 Depth Plane 与 Cutout 是静态图工作流。Remove Background 与 Upscale 继续通过媒体入口处理单图、视频和序列帧。
|
||||
|
||||
## 模型边界
|
||||
## 模型
|
||||
|
||||
正式 Depth Plane、Cutout Depth 与 Normal Map 都只使用 MoGe-2。BEN2 用于 Remove Background 与 Fit to Foreground，Upscale 使用所选高清模型。DA3 只保留 `debug-da3` 及其 Debug 参数、模型下载与适配代码，不进入任何生产 Operator、Job 或自动回退。
|
||||
Depth Plane、Cutout Depth 与 Normal Map 使用 MoGe-2，Remove Background 与 Fit to Foreground 使用 BEN2，Upscale 使用所选高清模型。
|
||||
|
||||
`ModelManager` 按模型族管理下载目录与 ONNX Session，同一族只保留最近使用的模型和 Device，避免同类模型重复占用资源。
|
||||
|
||||
|
||||
@@ -1,55 +0,0 @@
|
||||
# 功能参考
|
||||
|
||||
本页集中列出 AnyImage 当前实现的主要入口。操作建议见[工作流选择](../guides/workflows.md)，内部设计见[内部实现总览](../internals/index.md)。
|
||||
|
||||
## Blender 入口
|
||||
|
||||
| 入口 | 位置 | 输入 |
|
||||
| --- | --- | --- |
|
||||
| Paste Clipboard Image | 3D View / oode Editor 的 `Ctrl+V` 或 `Cmd+V` | 剪贴板静态图 |
|
||||
| Convert to Plane | Image Empty 右键菜单 | 单图、Movie、Sequence |
|
||||
| Convert to Depth Plane | Image Empty 右键菜单 | 静态图 |
|
||||
| Remove Background | Image Empty 右键菜单 | 单图、Movie、Sequence |
|
||||
| Upscale | Image Empty 右键菜单 | 单图、Movie、Sequence |
|
||||
| Image Box / Lasso / Line / Polyline | 3D Viewport 工具栏 | 静态 Image Empty |
|
||||
| Image Perspective | 3D Viewport 工具栏 | 静态 Image Empty |
|
||||
| Cutout | 3D Viewport 工具栏 | 静态 Image Empty |
|
||||
|
||||
右键菜单只在当前对象是 Image Empty 时出现。AI 功能会在 Environment 或默认模型未就绪时转入安装流程；普通 Plane、未启用 Fit to Foreground 的 Image Tools 与基础 Cutout Surface / Balloon 不依赖 Environment。
|
||||
|
||||
## 结果类型
|
||||
|
||||
### Plane
|
||||
|
||||
普通 Plane 使用资产中的 `O Mesh Plane` Geometry Nodes，提供 Subdivide、Thickness 和 Material。Depth Plane 使用同一资产文件中的 `O Image Depth Plane`，增加 Depth Amount 与内部 Depth Image。
|
||||
|
||||
### Cutout Shape
|
||||
|
||||
Cutout 提供四种结果：
|
||||
|
||||
| Shape | `O Image Cutout` 内部分支 | 深度 |
|
||||
| --- | --- | --- |
|
||||
| Surface | `O Image Surface` | 无 |
|
||||
| Balloon | `O Image Balloon` | Balloon Profile |
|
||||
| Depth Balloon | `O Image Depth Balloon` | MoGe-2 高度 |
|
||||
| Depth Surface | `O Image Depth Surface` | MoGe-2 相机点 |
|
||||
|
||||
四种 Shape 共用 `O Image Cutout` 修改器、规则三角基础面、UV 和 `o_balloon` 属性。Shape 菜单选择内部几何分支，Cleanup 在分支前执行且使用便于调节的百倍显示值，Smooth 在分支后执行；Depth Shape 根据 Region 透明比例选择固定或自适应 Base Plane Depth，Generate Normal Map 是启用开关：Depth Surface 自动使用 Object Space，其余 Shape 自动使用 Tangent Space；Fit to Foreground 按需启用 BEN2。
|
||||
|
||||
### 图片结果
|
||||
|
||||
Image Mask 和 Perspective 直接更新当前 Empty 的图片并 Pack。Remove Background 输出透明颜色图或序列。Upscale 通过三档 ONNX 模型把当前 Image 输出为 4× RGBA；当前长边达到全局输入上限时不可执行。
|
||||
|
||||
## 模型
|
||||
|
||||
- MoGe-2 ViT-S / ViT-B / ViT-L Normal
|
||||
- BEN2 Base
|
||||
- Real-ESRGAN General WDN x4v3
|
||||
- SAFMN Real x4
|
||||
- Real-ESRGAN x4plus
|
||||
|
||||
默认安装准备 MoGe-2 ViT-S Normal、BEN2 Base 和 Real-ESRGAN General WDN x4v3。其余模型在扩展 Preferences 中按需下载。
|
||||
|
||||
## Debug
|
||||
|
||||
Server 面板提供 DA3、MoGe-2、BEN2 与 Upscale Debug Job。它们保存模型适配层的直接 Prediction，不创建正式功能对象。文件说明见 [Job 产物](../internals/outputs.md)。
|
||||
@@ -1,27 +1,28 @@
|
||||
@import url("https://fontsapi.zeoseven.com/292/main/result.css");
|
||||
@import url("https://fontsapi.zeoseven.com/293/main/result.css");
|
||||
|
||||
/* [data-md-color-scheme="slate"] {
|
||||
--md-code-hl-string-color: #8b8b8b;
|
||||
--md-code-hl-keyword-color: #ffe8a3;
|
||||
--md-code-hl-number-color: #ffe8a3;
|
||||
--md-typeset-a-color: #ffe8a3;
|
||||
}
|
||||
|
||||
[data-md-color-scheme="default"] {
|
||||
--md-code-hl-string-color: #444444;
|
||||
--md-code-hl-keyword-color: #bd9100;
|
||||
--md-code-hl-number-color: #bd9100;
|
||||
}
|
||||
|
||||
[data-md-color-scheme=slate][data-md-color-primary=black] {
|
||||
--md-typeset-a-color: #ffe8a3;
|
||||
}
|
||||
|
||||
[data-md-color-scheme=default][data-md-color-primary=black] {
|
||||
--md-typeset-a-color: #bd9100;
|
||||
} */
|
||||
|
||||
:root {
|
||||
--md-text-font: "Open Sans", "Noto Sans SC", "Microsoft YaHei", sans-serif;
|
||||
--md-code-font: "Cascadia Code", "SFMono-Regular", Consolas, monospace;
|
||||
}
|
||||
|
||||
.md-typeset h1 {
|
||||
font-weight: 700;
|
||||
letter-spacing: -0.02em;
|
||||
}
|
||||
|
||||
.md-typeset .grid.cards > ul > li {
|
||||
border-radius: 0.5rem;
|
||||
}
|
||||
|
||||
.md-typeset .screenshot-placeholder {
|
||||
margin: 1rem 0;
|
||||
padding: 2.5rem 1.25rem;
|
||||
border: 2px dashed var(--md-default-fg-color--lighter);
|
||||
border-radius: 0.5rem;
|
||||
color: var(--md-default-fg-color--light);
|
||||
text-align: center;
|
||||
background: var(--md-code-bg-color);
|
||||
}
|
||||
|
||||
.md-typeset .screenshot-placeholder p {
|
||||
margin: 0.35rem 0;
|
||||
}
|
||||
--md-text-font: "LXGW WenKai";
|
||||
--md-code-font: "LXGW WenKai Mono";
|
||||
}
|
||||
Reference in New Issue
Block a user