nan
2b79a342b0
- Introduced `test_cutout.py` to validate cutout pie menu behavior, image lasso options, and mesh detail calculations. - Added `test_mesh.py` to ensure correct tangent normal rasterization, plane source topology, and depth surface evaluations. - Created `test_mesh_blender.py` to verify material node groups, tangent baking, and local cutout building from Blender images. - Implemented tests for handling alpha regions and ensuring geometry nodes maintain expected behavior.
9.6 KiB
功能参考
本页概览 AnyImage 的能力。安装步骤见安装与首次配置，实际操作见工作流选择与各使用指南。
工作流
| 工作流 | 适合 | 输入 | 结果 |
|---|---|---|---|
| Clipboard Image | 无需先另存即可使用系统剪贴板图片 | 剪贴板中的静态图片 | Reference Image、Plane、图片节点或笔刷 Texture |
| Mesh Plane | 不需要深度的图片卡片与背景板 | 单图、视频、序列帧 | 带图片材质和 Geometry Nodes 的普通平面 |
| Depth Plane | 快速制作可调节的立体图片 | 单图、视频、序列帧 | 带颜色、深度与 Geometry Nodes 的面片 |
| Surface | 从单张图片恢复透视空间 | 单图 | 相机空间网格、材质与可选匹配相机 |
| Remove Background | 提取透明前景 | 单图、视频、序列帧 | 透明图片或透明序列 |
| Upscale | 在安全输出上限内增加图片像素 | 单图、视频、序列帧 | 三档模型生成的高清图片或序列 |
| Image Mask | 用 Box、Lasso、Line 或 Polyline 直接清理图片 | 静态 Image Empty | 原位更新并 Pack 的透明裁切图 |
| Image Perspective | 四点透视矫正裁切 | 静态 Image Empty | Pack 的矩形裁切图 |
| Cutout | 套索选择区域并生成四种网格形状 | 静态 Image Empty | 带孔洞与原图 UV 的规则三角基础面 |
| Balloon | 沿轮廓绘制鼓起造型 | 静态 Image Empty | 带原图 UV 的封闭网格 |
| Debug | 检查模型原始输出 | 模型支持的图片或帧序列 | 保存在 Job 目录中的原始 Prediction |
Depth Plane 与 Surface 可使用 DA3 或 MoGe-2。DA3 提供相对深度和相机信息；MoGe-2 还提供 metric depth、法线与有效区域。BEN2 为去背景和可选前景处理提供 Alpha。
Blender 交互
复制图片后，在支持的编辑器中按 Ctrl+V（macOS 为 Cmd+V）即可粘贴；图片会 Pack 到当前 .blend。3D View 的 Object Mode 默认创建 Reference Image，也可在 Redo 面板切换为 Plane；Shader Editor、Compositor 与 Geometry Nodes 创建对应图片节点，Sculpt、Vertex Paint 与 Texture Paint 则设置笔刷 Texture。详见粘贴剪贴板图片。
主要功能位于 Image Empty 的 AnyImage 右键菜单；AnyImage 使用 prepend 注册，显示在右键菜单最上方。
Convert to Mesh Plane 位于 Convert to Depth Plane 上方，不需要 AI Environment。它生成基础四边形，并由 O Mesh Plane 修改器实时处理 Thickness 与 Subdivide；Thickness 为 0 时保持单面。操作会立即执行；创建后可在 Last Operation 中调整 Shadeless 与 Keep Original。
Cutout 复用 Image Lasso 的反选与 Refine 流程，但自交选区使用非零环绕填充：同方向重叠保留，反方向内环形成孔洞。基础面以均匀六角格点填充平滑约束轮廓，Pixel Size 控制内部密度，短轮廓会自适应边界采样以免有效小区域消失。未启用 Refine 的 Cutout 与 Balloon 只按套索建面，不把原图 Alpha 计入几何；同时关闭 Normal 时在 Blender 内完成遮罩、轮廓和建面，不启动 BlendJob。套索或 Refine Alpha 只作为几何 mask，材质颜色使用当前 Empty Image 的未裁切副本，MoGe 深度与法线始终分析完整图片；若图片来自 Upscale，AI 分析回溯到放大前的原图，避免放大不必要地增加计算量和伪细节。Normal 默认关闭，启用后才用 MoGe-2 写入 normal；Depth Surface 保留 MoGe 原生 object-space 像素，Cutout、Balloon 与 Depth Balloon 根据成品网格 TBN 烘成不同的 tangent-space 像素。Depth 类型始终使用 Job 生成深度，但同样由该选项决定是否写入 normal。Refine 启用后由 BEN2 返回原图画布内的最终 Alpha，Blender 再从该 Alpha 建面，框外套索区域不会保留。详细操作与计算边界见 Cutout。
O Image Depth Surface 的平滑阶段直接展开 O Essentials O Smooth 的 Repeat Zone 与双域边界判断结构，不嵌套组节点；内部固定按 Pin Sharp = 1、Pin Boundary = 1 计算，不暴露这两个参数，Iterations 默认 1、最小可设为 0。Depth Continuity 默认 0；Thickness 固定正面，只向背面挤出。
Balloon 作为不依赖 AI 的基础工具单独排列；Mesh Plane、Depth Plane 与 Surface 属于转换组，Remove Background 与 Upscale 由分割线归入图片处理组。Depth Plane、Surface、Remove Background 与 Upscale 四个 AI 功能在缺少 Environment 或默认模型时仍可点击：缺 Environment 时转入 Set Up AI Environment…，只缺默认模型时转入 Download Required Models…。全部就绪后，菜单底部显示 AI Environment Settings…，用于打开 AnyImage 扩展偏好设置。Upscale 菜单项同时显示当前图片分辨率，不弹出属性对话框；模型与输出长边上限统一读取 Preferences 的 Default Upscale Model 和 Maximum Upscale Size，Operator 不注册 Last Operation 重做面板。高清结果再次执行时从保存的原图重新生成并替换当前版本，不级联处理已有结果；名称始终基于原图，透明图片保留放大后的 Alpha。Depth Plane、Surface 与 Cutout 的深度或法线推理也会沿用该原图引用；高清结果继续用于颜色材质和选区显示。
转换任务完成后，AnyImage 在一个 Undo 步骤中创建网格、图片、材质和修改器。源 Image Empty 是否保留由转换选项决定。
Image Box、Lasso、Line 与 Polyline 组成 Mask 工具组，并共用 EditImageMask。四者用 F 切换反选；Refine Selection 只用于 Box / Lasso。Perspective 是位于 Mask 组与 Balloon Lasso 之间的独立工具，将任意顺序输入的四个角矫正为指定比例的矩形。结果直接更新当前 Image Empty，并 Pack 到 .blend。
操作步骤见 Image 编辑工具；处理管线与模块职责见 Image 工具技术实现。
Balloon 默认在 Blender 内部生成，无需 Environment 或模型。Tool Settings 提供模式、厚度、采样距离、材质复用、Contour、Depth 与 MoGe-2 Depth Model；AI 未就绪时只禁用这三个控件，并在 Tool Settings 中显示安装按钮。Depth 会把物理距离相对化并稳健拟合初始基面，保留未截断的正负起伏。Base Plane 子 Empty 的旋转定义基面朝向，沿自身局部 Z 移动定义 middle level。
O Balloon Shape 计算 修正厚度 = abs(原 X) × Thickness，并将修正深度校准为 (0.5 × 相对基面深度 + 原始 Balloon 最大半厚度) × Depth Strength。固定的原始半厚度不乘 Thickness，因此 Thickness 与 Depth Strength 分别只控制各自分支。节点以归一化原 X 距离经 Smoother Step 得到中心程度，再插值厚度与深度。Double Sided Depth 默认关闭，背面保持 Balloon 厚度。MoGe 相机轴 normal 会在 Blender 评估最终 Balloon 后按平滑 TBN 烘为原图尺寸的 tangent-space 纹理，并通过统一 O Image Layer 的 Normal Scale 补偿网格无法表达的细节；Normal Scale 默认 1，Bump Scale 默认 0，未连接 normal 时使用中性默认值。
新建 Balloon 材质会用 Custom Properties 保存源 Image datablock 和可选 normal Image 的直接引用。Reuse Material 优先按这些标记匹配，不依赖材质或节点组名称；普通与 Depth 材质分别复用。Depth Balloon 的共享 normal 会逐次合并新套索的有效区域，避免复用材质时丢失其他套索的法线。
动画
Depth Plane、Remove Background 和 Upscale 支持 Movie 与 Image Sequence。它们按 Image Empty 的帧范围处理素材，并生成与场景帧对应的颜色或深度序列。
Blender 无法整体 Pack 图片序列，因此动画结果会继续引用 Job 目录。保存或移动 .blend 时，应同时保留这些外部文件。详见动画与序列帧。
运行环境
AI 任务在独立 Python Environment 中通过 ONNX Runtime 执行。Blender 负责界面、任务提交和结果导入，Job Server 负责模型与文件处理。
默认 Storage Root 为 ~/.anyimage，其中保存 Environment、模型、日志和 Job 结果。连续使用同一模型会复用已加载的 Session；切换到另一模型族时释放旧 Session，使 Server 最多保留当前使用的一套模型。
安装、下载和推理都在后台运行，并通过状态栏提供进度与取消操作。详细设计见Job Server。
模型与调试
正式功能使用以下 ONNX 模型：
- MoGe-2 ViT-S、ViT-B、ViT-L Normal
- DA3 Small、DA3 Base
- BEN2 Base
- Real-ESRGAN General WDN x4v3、SAFMN Real x4、Real-ESRGAN x4plus
Upscale 提供 Real-ESRGAN General WDN x4v3、SAFMN Real x4 和 Real-ESRGAN x4plus 三档 4× RGB 模型。默认 WDN 偏速度和保守细节，SAFMN 居中，x4plus 的细节更明显；三者也保留对应 Debug 入口用于模型直通比较。正式功能会独立放大并合并源 Alpha，默认把输出长边限制在 4096 px，可在 Preferences 提高到 8192 px，并始终受约 32 MP 硬上限约束。
首次安装会准备 MoGe-2 ViT-S Normal、BEN2 Base 与 Real-ESRGAN General WDN x4v3，其他模型可从 AnyImage 扩展偏好设置按需下载。
Debug 工作流保存模型 API 的直接返回，适合验证模型、设备与输入。三档高清模型对每张输入保存 prediction*.png，不加入降噪强度、Alpha 合成或 Blender 图片写回。三个模型统一由适配层以 256×256、16 像素上下文执行重叠分块，因而都接受任意图片宽高。Depth Plane 和 Surface 则在模型结果之上继续生成 Blender 可用的贴图与几何。文件字段见输出格式。