AnyImage/README.md

AnyImage

AnyImage 是一个 Blender 扩展，可以把一张照片、一段视频或一组序列帧快速变成有真实深度的立体面片。

完整使用说明请从文档首页开始；首次使用请依次阅读 安装与首次配置和五分钟上手。

它能做什么

• 在 3D View、Node Editor 与绘画模式中按 Ctrl+V（macOS 为 Cmd+V）直接粘贴并 Pack 剪贴板图片
• 不运行 AI，把 Image Empty 转换为可实时调整 Thickness 与 Subdivide 的 Mesh Plane
• 从 Image Empty 套索提取不规则区域，通过 Poisson 或 Teddy / Chordal Axis 生成封闭 Balloon，并可用 BEN2 分析轮廓、MoGe-2 添加可调深度；源 Empty 保持不变
• 用 Image Box / Lasso 原位提取 Image Empty 内容，按矩形或手绘范围裁切并 Pack 新图，也可用 BEN2 进一步收紧 Alpha
• 一键把 Image Empty 转换为立体面片：让 AI 估算深度，或直接用原图作为深度
• 把单张 Image Empty 转换为透视纹理网格，并自动匹配原对象的 Transform 与 Offset
• 一键去除图片背景，生成透明前景图
• 支持视频与序列帧输入，逐帧处理，动画也能得到逐帧对应的立体面片
• 主要转换操作集中在右键菜单，剪贴板图片可直接用系统粘贴快捷键导入

安装

1. 下载对应系统的扩展压缩包
2. 打开 Blender，进入 Preferences > Extensions
3. 点击 Install from Disk，选择下载的压缩包
4. 在扩展偏好设置中确认 Storage Root 与 Device（保持默认即可）；Device 默认取本机 最快的 DirectML provider；Apple M4 或更新芯片可选 MPS/CoreML，其他 Mac 只提供 CPU
5. 选中 Image Empty，在右键 AnyImage 子菜单中点击 Set Up AI Environment…；也可以从扩展偏好设置进入

扩展不内置 uv 或 AI 运行库。Set Up AI Environment… 会先说明下载内容、约 600 MB 的下载量、约 1 GB 的磁盘占用和预计等待时间，并可勾选 Use Mirror。确认后会下载并校验固定版本的 uv，自动安装轻量的 ONNX Runtime 环境，再下载 MoGe-2 ViT-S Normal 和 BEN2 Base；不安装 PyTorch，也不下载各模型的 Python 源码包。Use Mirror 只切换 uv、Python 和 Python 包的下载源，模型仍使用自己的下载源与备用镜像规则。

Environment Bootstrap 使用连续的 0–100%：uv 为 1–20%、Python 为 20–50%、packages 为 50–98%，最终验证为 98–100%。三个阶段显示真实的 1/3、2/3、3/3，下载占各阶段的 84–87%；开始与最终验证不显示编号，单阶段状态不显示 1/1。MoGe-2 与 BEN2 属于 post-install，各自使用独立进度，不计入 Environment 的这轮 0–100%。任一必需模型在两个来源都下载失败时，安装任务会明确报错；Environment 本身仍会保留。

选中 Image Empty 后，右键 AnyImage 子菜单依次显示 Balloon、三个 AI 功能和环境入口。Environment 或必需模型未就绪时，点击 Convert to Depth Plane…、Convert to Surface… 或 Remove Background 会打开对应准备对话框：Environment 未安装时入口显示 Set Up AI Environment…，安装 Environment 与默认模型；Environment 已安装但默认模型缺失时入口显示 Download Required Models…，只补齐缺失模型。全部就绪后，菜单入口改为 AI Environment Settings…，并打开 AnyImage 扩展偏好设置。

其他 AI 模型统一在 AnyImage 扩展偏好设置中按需下载。Balloon Lasso Tool 的本地几何功能始终可用；AI 未就绪时，只禁用 Tool Settings 中的 Contour、Depth 与 Depth Model，并在同处根据状态显示 Set Up AI Environment… 或 Download Required Models…。共享的 AI 状态检测直接检查 Environment 和 Storage Root 的 models/ 文件，不会仅因打开菜单或设置而启动 Job Server。

快速上手

粘贴剪贴板图片

复制图片后，在 3D View、Shader Editor、Compositor 或 Geometry Nodes 中按 Ctrl+V；macOS 使用 Cmd+V。AnyImage 会根据当前上下文创建 Reference Image、带材质的 Plane、图片节点或笔刷 Texture，并将图片 Pack 到当前 .blend。完整说明见粘贴剪贴板图片。

转换为普通图片平面

选中 Image Empty 后，右键选择 AnyImage > Convert to Mesh Plane。该操作不运行 AI，会创建带图片材质和 O Mesh Plane Geometry Nodes 修改器的基础四边形。Thickness 与 Subdivide 都在修改器中实时生成；Subdivide 使用二分级别（3 为短边 8 段），Thickness = 0 时结果为真正的单面。操作会立即执行；创建后可在 Last Operation 中调整 Shadeless 和 Keep Original，调整时保持源图片的世界位置、旋转与缩放。完整说明见 Mesh Plane。

转换为立体面片

1. 在 3D 视图中选中一个 Image Empty（空物体，显示方式为 Image）
2. 右键打开 AnyImage 子菜单，选择 Convert to Depth Plane
3. 在对话框中选择：
   • Depth from：Original 直接用原图，DA3 使用现有 DA3 流程，MoGe-2 生成 metric depth、normal 与有效区域 mask
   • Resolution Scale 使用 1–100%，按原图长边计算 Process Res；结果会限制在 252–1008 并自动对齐到 14 的倍数
   • Remove Background 默认关闭；开启后在转换期间使用 BEN2 删除背景
   • Shadeless 使用 O Shadeless 节点组显示不受场景灯光影响的贴图颜色
   • Keep Original 默认关闭，位于分割线下方；开启后保留源 Image Empty
4. 点击确认，稍等片刻就得到带位移的立体面片。O DA3 Depth Plane 与 O MoGe2 Depth Plane 都使用 .color 的 Alpha > 0.5 划分前景范围，范围外由 Background Depth 控制。

套索提取图片

选中静态图片的 Image Empty，在 3D Viewport 左侧工具栏选择 Image Box / Lasso 工具组。默认的 Image Box 拖出矩形区域；长按工具按钮可切换 Image Lasso 并绘制自由轮廓。两者使用默认鼠标光标，并以类似 Select Tool 的白色虚线显示选区，分别采用 Sculpt Mode 的 Box Mask 与 Lasso Mask 图标，共用相同设置。该工具组与 Balloon Lasso 相邻，并通过一个间隔与前方的 Add Cube 分开。松开左键后会把同一个 Empty 原位更新为新图片并 Pack 到 .blend。Image Box / Lasso 与 Balloon Lasso 都只放在工具栏，不出现在右键 AnyImage 子菜单中。

区域外的 RGBA 会统一设为透明黑，避免后续只读取 RGB 的图像处理重新识别透明区内容。输出画布取最终 Alpha 大于 0 的最小 bounding box，再按 Padding 向四周增加指定的透明像素，默认 0 px。对象原点会移动到新画布中心，显示尺寸与图片比例同步更新，裁切后的像素仍与原图在世界空间重合。Keep Original 默认关闭；开启后保留源 Empty，并创建承载裁切图的副本。Contour 默认关闭；开启后 BEN2 会在 lasso 内进一步细化 Alpha，再计算最终 bounding box。Contour 仅支持静态图片，并需要 AI Environment 与 BEN2。

套索生成 Balloon

选中单张图片的 Image Empty，右键打开 AnyImage 子菜单并选择 Balloon Lasso Tool。Blender 会激活 3D Viewport 左侧工具栏底部、紧邻 Image Box / Lasso 工具组的独立 Balloon Lasso；该工具组与 Add Cube 之间保留一个间隔。Balloon 使用 Poly Build 的绿色图标、Annotate 同款铅笔光标，Tool Header 与状态栏共同提示当前工具状态，不再用黄色外框或强制修改 Shading、Overlay。Blender 的公开 Workspace Tool API 不支持按 Active Object 动态隐藏工具，因此图标在 Object Mode 中保持可见，但只有 Active Object 是 Image Empty 时才能启动 Stroke。

按住左键沿目标轮廓绘制，松开后生成一个带原图 UV 的封闭网格。每次拖动都是一个独立完成的顶层 Extract Balloon Operator，工具本身继续保持激活，下一次拖动会创建另一个 Balloon；因此 Ctrl+Z 只撤销最近一次生成，Ctrl+Shift+Z 重做。每次生成后源 Image Empty 都保持选中和 Active。未绘制时没有持续 Modal 拦截事件，视图导航和其他原生快捷键由 Blender 正常处理；绘制中可用右键或 Esc 取消当前轨迹。选择左侧工具栏中的其他工具即可离开 Balloon Lasso。

• Mode、Thickness、Resolution (m)、Reuse Material、Contour、Depth 和启用 Depth 后出现的 Depth Model 显示在 Tool Header / Tool Settings
• S：调用 Blender 原生 Radial Control 调节 Thickness；通过 zoom_path 把默认 1.0 映射为约 100 px 的交互圆，软上限为 5.0，不设硬上限
• D：调用 Blender 原生 Radial Control 调节 Resolution；通过独立 zoom_path 把默认 0.1 m 映射为约 100 px 的交互圆，数值越小网格越密

Resolution (m) 会根据 Scene Unit Scale 换算为网格使用的世界距离，因此不同单位设置下仍代表相同的物理采样间距。Poisson 模式使用尺度无关的求解判断，支持 0.02 m 等较密采样。两个 AI 选项默认关闭；Contour 使用 BEN2 Alpha 严格大于 0.5 的最大连通前景重建轮廓，Depth 使用所选 MoGe-2 模型。MoGe 的物理距离会先减去稳健拟合的基面，再换算为不受绝对拍摄距离影响的相对起伏；近侧与远侧信号都保留，不削顶、不截平。

Depth Balloon 使用局部 X 作为深度轴，并创建 <Balloon> Base Plane Single Arrow Empty。Empty 的旋转定义基面朝向，沿自身局部 Z 移动则调整 middle level。默认深度校准为 修正深度 = (0.5 × 相对基面深度 + 原始 Balloon 最大半厚度) × Depth Strength；原始最大半厚度来自生成后的固定网格，不受修改器 Thickness 影响。这在 Thickness = 1 时等价于旧参数的 Depth Strength = 0.5 和两倍半厚度基面偏移。节点再以 Smoother Step 中心程度插值修正厚度与修正深度；Thickness 只控制厚度分支，Depth Strength 只控制深度分支。Double Sided Depth 默认关闭，使背面维持稳定厚度。

MoGe normal 会转换成适配 Balloon UV 的 tangent-space normal.png，由专用 O Balloon Layer 材质补回网格分辨率未能表达的细节；Normal Strength 默认 0.5，可在材质节点中调整。Balloon 材质通过 Custom Properties 直接保存源 Image datablock 引用，不依赖材质名或节点组名识别；勾选 Reuse Material 时优先复用同一 Image、同一材质类型的标记材质。Depth Balloon 共用一张原图尺寸的 normal，后续套索会把自己的有效区域合并进去，重叠区域采用最新结果。旧材质仍保留节点识别回退。当前只支持静态图片。

去除背景

选中 Image Empty 后，右键打开 AnyImage 子菜单并选择 Remove Background，完成后 Empty 会自动 换成透明前景图。该操作在子菜单中使用独立分割区域。

转换为透视网格

选中单张图片的 Image Empty，右键打开 AnyImage 子菜单并选择 Convert to Surface。可选择 MoGe-2 ViT-S、ViT-B、ViT-L 或 DA3 Small、Base，其中 MoGe-2 ViT-S 为默认模型。AnyImage 会按模型输出的 相机内参与三维点建立透视网格，并匹配原 Empty 的可见尺寸、Offset 与 Transform。Server 通过统一的 Surface 输出流程构建 DA3 与 MoGe-2 源网格：MoGe-2 使用深度断层 mask，DA3 保留 confidence 与边拉伸 数据。两者再由独立的 Geometry Nodes 修改器完成剔面、快速重拓扑、Relax 与 UV 重投；顶层 Iterations 可设为 0。开启 Remove Background 时，BEN2 Alpha 只要大于 0 就视为前景；三角形三个顶点必须全部为前景，任一顶点 Alpha 为 0 都会删除该面并且不再交给 Geometry Nodes；Surface 材质使用 .color。匹配相机默认不创建；开启后会作为 Surface 的子级。 MoGe-2 的像素级 normal 会作为 Object Space normal 贴图接入 O MoGe2 Surface Layer，并与原图 Bump 合并；网格本身不写入 custom normal，因此重拓扑降低顶点数后仍能保留细腻的法线细节。 当前此功能仅支持单张图片。

MoGe-2 ViT-S、ViT-B、ViT-L、DA3 Small、DA3 Base 与 BEN2 全部使用 ONNX。模型执行、相机与深度恢复、 点云重投影和网格生成均不依赖 PyTorch。Windows 使用 DirectML 加速；Apple M4 或更新芯片可使用 CoreML 的 MLProgram 模型格式，较早或无法识别的 Mac 只提供 CPU；provider 不可用时会回退到 ONNX Runtime CPU， 并在任务状态中显示实际 provider。

转换对话框提供模型与 Create Matching Camera、Remove Background、Shadeless；DA3 显示 Resolution Scale，MoGe-2 显示 Resolution Level， 以及分割线下方的 Keep Original。 界面会显示计算所得的实际 Process Res。剔除和重拓扑参数直接在 Geometry Nodes 修改器中调整；Shadeless 与 Depth Plane 共用 O Shadeless 材质节点组。颜色贴图始终使用统一的 .color 转换产物；Remove Background 只决定是否由 BEN2 修改 Alpha。颜色贴图会按当前场景的 View Transform 选择对应输入色彩空间：AgX、ACES 1.3、ACES 2.0、Filmic、Khronos PBR Neutral 分别使用 AgX Base sRGB、ACES 1.3 sRGB、ACES 2.0 sRGB、Filmic sRGB、Khronos PBR Neutral sRGB；无法匹配当前 View Transform 时回退 sRGB。普通材质的 Bump Scale 会在材质组内乘以 0.001，并按透视表面的深度空间缩放。Surface 与 Depth Plane 的 Layer Color 同时驱动 Principled BSDF 的 Base Color、Subsurface Radius 和 Emission Color，Layer Normal 同时驱动 Normal 与 Coat Normal；Subsurface、Emission、Coat 的其他设置保持默认。Surface attributes 统一使用 o_ 前缀；Server 准备过程显示 Preparing surface data n/6，可看到当前阶段与总步骤；Surface 与 Depth 单帧模型推理都不显示多余的 1/1。

视频与序列帧

AnyImage 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并生成逐帧对应的立体面片。.color 与 .depth 按源 Empty Image 的类型载入：普通单图为 IMAGE，Movie/Sequence 即使只处理一帧也仍为 SEQUENCE。处理范围默认 跟随 Empty 上设置的 Image Frames 与 Offset，不需要额外配置。DA3 的转换任务复用同一个 ONNX Session 逐帧推理，显存峰值不随视频帧数平方增长。Debug 只保存模型 API 的直接返回：DA3 多帧输入 保留联合推理，MoGe-2 与 BEN2 按各自的单图 API 逐帧保存。

任务结果保存在哪里

任务结果保存在 Runtime Storage Root 的 jobs/ 下，默认是 ~/.anyimage/jobs/。Job Server 接受任务时自动生成 opaque Job ID，并创建同名文件夹；Blender 不预先申请 ID 或目录。Packed Image 和序列帧的临时输入由 Blender 在任务结束后清理，Server 产物直接写入该 Job 目录。视频或序列帧生成的面片会引用其中的序列帧，请保留对应文件夹，不要随意删除。

常见问题

• 从 0.12.0–0.12.5 升级到 0.12.6 或更高版本后，请重新执行一次 Set Up AI Environment…，重建不再单独安装 BlendJob 的 Server Environment
• 首次使用需要下载模型；Environment 已安装但默认模型下载慢或失败时，点击 Download Required Models… 可补齐缺失项，也可在 AnyImage 扩展偏好设置中逐项重试
• 安装 Environment 时下载状态会显示平均速度；网络适合国内镜像时在确认对话框勾选 Use Mirror，否则保持关闭。选择的来源固定用于 uv、Python 和 Python 包，失败时不会自动切换
• 默认模型下载会在 Hugging Face 与 OmooLab 镜像之间自动回退；某一来源暂时断线不会阻止后续模型尝试另一来源
• 模型直链建连超过 10 秒，或连接后连续 60 秒没有收到数据，会切换到下一来源；不限制总下载时长
• 找不到右键入口时，请确认选中了 Empty，且显示方式为 Image
• 动画面片不动：检查 Empty 的 Image Frames 是否大于 1，并确认播放场景帧

技术文档

Blender 侧只负责界面、任务提交与结果导入，AI 与文件输出由独立 Job Server 执行。源码将插件级 runtime.py、menu.py、panel.py 保持在顶层，具体功能与共享图片、材质能力统一放在 operators/；每种任务的结果回写与对应 Operator 放在一起。详细功能见 文档索引，程序设计、调用流程、项目结构与开发命令见 程序设计、开发与许可证。CI 在 main push 与 Pull Request 上运行测试，仅由 v* tag 构建并发布扩展包；文档在 main 的文档相关文件变化时部署。