nan
7d39fe8c5e
- Implemented cotangent Poisson field and Poisson balloon profile in cutout_profile.py. - Added teddy balloon heights calculation and related functions in cutout_teddy.py. - Introduced interaction utilities for image editing in interaction.py. - Developed depth normalization and analysis functions in cutout_depth.py. - Created a validation script for cutout assets in validate_cutout_asset.py.
165 lines
20 KiB
Markdown
165 lines
20 KiB
Markdown
# AnyImage
|
||
|
||
AnyImage 是一个 Blender 扩展，可以把一张照片、一段视频或一组序列帧快速变成有真实深度的立体面片。
|
||
|
||
完整使用说明请从[文档首页](docs/index.md)开始；首次使用请依次阅读
|
||
[安装与首次配置](docs/installation.md)和[五分钟上手](docs/quick-start.md)。
|
||
|
||
|
||
## 它能做什么
|
||
|
||
- 在 3D View、Node Editor 与绘画模式中按 `Ctrl+V`（macOS 为 `Cmd+V`）直接粘贴并 Pack 剪贴板图片
|
||
- 不运行 AI，把 Image Empty 转换为可实时调整 Thickness 与 Subdivide 的 Mesh Plane
|
||
- 用 Cutout 套索从 Image Empty 生成 Surface、Balloon、Depth Balloon 或 Depth Surface；四种结果共用单面基础薄片、局部方向与清理逻辑
|
||
- 用 Image Box / Lasso / Line / Polyline 直接清理 Image Empty；按 `F` 反选，也可用 BEN2 细化选区
|
||
- Image 编辑会直接更新未共享的图片；图片被多个 Image Empty 共用时，只为当前 Empty 分离编辑结果
|
||
- 用 Image Perspective 勾勒四个角点，把透视四边形矫正为矩形裁切图，并沿用源 Image Empty 的空间朝向
|
||
- 一键把 Image Empty 转换为立体面片：让 AI 估算深度，或直接用原图作为深度
|
||
- 把单张 Image Empty 转换为透视纹理网格，并自动匹配原对象的 Transform 与 Offset
|
||
- 一键去除图片背景，成成透明前景图
|
||
- 用三档 ONNX 模型将图片、视频或序列帧逐帧放大 4 倍
|
||
- 支持视频与序列帧输入，逐帧处理，动画也能得到逐帧对应的立体面片
|
||
- 主要转换操作集中在右键菜单，剪贴板图片可直接用系统粘贴快捷键导入
|
||
|
||
## 安装
|
||
|
||
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` 和默认高清模型 `Real-ESRGAN General WDN x4v3`；不安装 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` 会显示在右键菜单最上方。Mesh / Depth / Surface 转换为一组，Remove Background 与 Upscale 作为图片处理归为下一组，环境入口位于最后。Environment 或必需模型未就绪时，点击 `Convert to Depth Plane…`、`Convert to Surface…`、`Remove Background` 或 `Upscale` 会打开对应准备对话框：Environment 未安装时入口显示 `Set Up AI Environment…`，安装 Environment 与默认模型；Environment 已安装但默认模型缺失时入口显示 `Download Required Models…`，只补齐缺失模型。全部就绪后，菜单入口改为 `AI Environment Settings…`，并打开 AnyImage 扩展偏好设置。
|
||
|
||
扩展偏好设置先显示 Environment 状态与 Diagnostics，再依次提供默认展开、可折叠的 Depth & Normal、Remove Background、Upscale 和 Cutout 功能区。Depth Model 按三档 MoGe-2、两档 DA3 排列；选择 DA3 时会提示该模型不能生成 normal。可选模型的状态与下载按钮位于对应模型选择项下方，BEN2 则归在 Remove Background。共享的 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`。完整说明见[粘贴剪贴板图片](docs/clipboard-image.md)。
|
||
|
||
### 转换为普通图片平面
|
||
|
||
选中 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](docs/mesh-plane.md)。
|
||
|
||
### 转换为立体面片
|
||
|
||
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` 都使用色色图片的 `Alpha > 0.5` 划分前景范围，范围外由 `Background Depth` 控制。
|
||
|
||
### 编辑图片选区
|
||
|
||
在 3D Viewport 左侧工具栏选择 Image Mask 工具组。Box 拖出矩形，Lasso 手绘轮廓，Line 清理有向直线的一侧，Polyline 逐点构建多边形。点击另一张 Image Empty 时只切换选择；点击当前 Active 图片、空白处或非图片物体时，才开始编辑当前图片。没有 Active 图片时会提示先选择 Image Empty，切换其他工具会取消当前绘制。
|
||
|
||
Lasso 绘制时与 Box、Line、Polyline 一样显示白色虚线轮廓和淡灰半透明填充；凹形选区不显示内部投射线，自交选区则按最终操作的填充规则显示交叠区域。Cutout 预览与最终几何都使用非零环绕规则：同方向重叠保留，反方向抵消成孔。Lasso 只有在鼠标移动至少 2 px 时才采点，停留不会持续增加点数；近似共线的连续点会在线合并，填充和虚线段也只在轨迹变化时重算。绘制中按 `F` 切换反选：默认保留选区内，反选后保留选区外。Line 按住 `Ctrl` 以 5° 吸附；Polyline 可单击起点圆环或按 `Enter` 完成。`Refine Selection` 只用于 Box / Lasso：先用 BEN2 将几何选区收紧到其中的前景，再应用反选。结果直接替换当前 Empty 的图片，按最终非零 Alpha 紧裁切，并更新显示尺寸与 Image Offset；对象 Transform 不变。透明区保留源 RGB，避免纹理过滤产成黑边。未形成有效区域的单击会静默结束；有效选区没有可见像素时只显示警告，不修改图片。
|
||
|
||
### 四点透视矫正
|
||
|
||
`Image Perspective` 是紧随 Image Mask 工具组之后的独立工具。四个角可以按任意顺序点击，完成后会在源图片坐标中自动求出不交错的凸四边形，并以原图 X/Y 方向确定输出旋转。绘制时显示白色虚线和半透明选区面，`Backspace` 删除最近一个角点，右键或 `Esc` 取消；切换其他工具也会立即退出。首次点击遵循同一选择规则。Perspective 不依赖当前 View 的相机内参，因此透视和正交 View 都可以使用。
|
||
|
||
第四个角点按下时会在 Viewport 中央显示带蓝色边框的矫正图片预览，中央显示当前比例，下方显示鼠标操作提示；鼠标同时移到 Viewport 中心，为左右两个方向保留相同的调节空间。水平移动连续调整宽高比，按住 `Ctrl` 吸附到 `1:1`、`4:3`、`3:4`、`16:9`、`9:16`，下一次左键确认并创建；`Backspace` 返回第三点，右键或 `Esc` 取消。初始比例取四边形两组对边的平均长度比。预览使用一次成成的 512 × 512 临时图片，移动鼠标时只改变 UI 显示比例。
|
||
|
||
确认后，工具把选区透视矫正为矩形图片，按最终非零 Alpha 范围裁切并 Pack 到 `.blend`。结果 Empty 保持源图的朝向和深度，以四边形在源图上的 bounding box 近似确定中心与显示范围，不再尝试从当前 View 反解真实空间矩形。四边形完全位于源图范围外，或矫正结果没有可见 Alpha 像素时，只显示警告且不创建结果。输出最长边不超过 8192 px，总像素不超过约 16 MP。
|
||
|
||
Image Perspective 是 deform 工具，不提供 Refine 或反选。它与其他 Image 工具共享选图、绘制样式、紧裁切和 Empty 写回逻辑。
|
||
|
||
完整操作说明见 [Image 编辑工具](docs/image-tools.md)。
|
||
|
||
### Cutout 基础面与四种形状
|
||
|
||
在 Object Mode 的 3D Viewport 左侧工具栏选择 `Cutout`，沿 Image Empty 绘制后可从四个方向选择 Surface、Balloon、Depth Balloon 或 Depth Surface；双击会选择完整图片。`Point Spacing` 以完整原图像素为单位控制规则三角格点间距，裁切范围大小不会改变密度。未启用 `Refine Selection` 时，几何只跟随套索；启用后才使用 BEN2 Alpha 收紧选区。`Normal` 默认关闭；启用后才通过 MoGe-2 生成 normal 纹理。未启用 Refine 且关闭 Normal 时，Surface 与 Balloon 完全在 Blender 内生成，不启动 BlendJob。
|
||
|
||
四种结果的源网格统一为真正的单面薄片，并分别使用 `O Image Surface`、`O Image Balloon`、`O Image Depth Balloon`、`O Image Depth Surface` 四个独立 Geometry Nodes。局部纸面统一位于 YZ 平面，局部 `+X` 朝纸面内侧，局部 `-X` 是外侧和深度箭头方向；对象原点统一位于裁切图片中心，对象矩阵补偿后薄片仍落在源 Image Empty 的原位置。`Thickness = 0` 时保留单面；Surface 与 Depth Surface 的 Thickness 是场景距离，Balloon 与 Depth Balloon 的 Thickness 是 `o_balloon` 高度倍率，默认 `1` 保留算法原值。加厚按整片连通区域处理，内部三角边不生成侧壁。Surface 与 Depth Surface 会以边界三角边的中位长度为目标宽度，沿 Thickness 方向自动增加侧壁分段，使侧壁面片尽量接近正方形；Balloon 与 Depth Balloon 不增加这些分段线。
|
||
|
||
四个修改器都有默认折叠的 `Options` 面板，`Cleanup` 统一放在其中。节点按 Mesh Island 累计离散面面积，并以基础面三角形的中位面积自动估算 Point Spacing 尺度；默认 `1` 会删除面积小于约一个点间距平方的孤立小面，因此无需在 Cutout 创建后写入绝对场景单位阈值。Depth Balloon 的 `Base Plane`，以及 Depth Surface 的 `Depth Continuity`、`Smooth` 也收纳在该面板。
|
||
|
||
四种 Cutout 形态都会在创建基础网格时计算 Balloon profile，并统一写入 `FLOAT/POINT` 属性 `o_balloon`；不再写入 `o_boundary`。AnyImage 扩展 Preferences 的 **Balloon Profile** 可选择 Poisson 或 Teddy，两个 Balloon 节点组只读取属性，不再自行估算轮廓。两个 Depth 形状都从内部打包的浮点深度图片采样，不把深度写成点属性；内部深度 Image datablock 统一使用 `_depth.exr` 后缀，`Depth Image` socket 在修改器中隐藏。
|
||
|
||
Depth Balloon 的 Base Plane 位于当前裁切后网格的中心，而不是原图中心。默认朝向由选区内有效 MoGe 深度进行稳健平面回归；细长选区会保留长轴趋势，同时抑制缺少空间支撑的短轴倾角。Single Arrow 沿局部 `-X` 指向实际深度方向；沿箭头移动的场景距离与前表面的同向位移严格一致。Geometry Nodes 会先用 Base Plane 校正深度，再让 `Depth Scale` 乘整个校正结果；因此 `Depth Scale = 0` 时 Base Plane 和深度图都不再改变深度分支。`Double Sided` 默认关闭，使背面保持 Balloon 厚度，开启后则把受 Base Plane 调整后的最终前表面关于对象局部 YZ 平面完整镜像；Base Plane 只定义正面的朝向与基线，不会移动对称中心。Depth Surface 先按深度图片位移和断层剔除，再清理新产生的小岛、加厚并执行展开的 O Smooth 结构；`Iterations` 默认 `1`，`Depth Continuity` 默认 `0`。
|
||
|
||
Surface、Balloon 与 Depth Balloon 的 MoGe normal 会依据最终网格 TBN 烘成 tangent-space 纹理；Depth Surface 直接使用适配新局部轴向的 object-space normal。完整说明见 [Cutout](docs/cutout.md)。
|
||
|
||
### 去除背景
|
||
|
||
选中 Image Empty 后，右键打开 `AnyImage` 子菜单并选择 `Remove Background`，完成后 Empty 会自动
|
||
换成透明前景图。
|
||
|
||
### 高清放大
|
||
|
||
选中 Image Empty 后，在右键 `AnyImage` 菜单中点击 `Upscale`。它使用扩展偏好设置中选择的模型进行 4× 放大，支持单图、Movie 和 Image Sequence，并保留源 Alpha。
|
||
|
||
|
||
[阅读高清放大指南](docs/upscale.md)
|
||
|
||
### 转换为透视网格
|
||
|
||
选中单张图片的 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.5` 才视为前景；三角形三个顶点必须全部为前景，任一顶点 Alpha 小于 `0.5`
|
||
都会删除该面并且不再交给 Geometry Nodes；Surface 材质使用成成的色色图片。匹配相机默认不创建；开启后会作为 Surface 的子级。
|
||
MoGe-2 的像素级 normal 会作为 object-space normal 贴图接入 `O Image Layer`，并与原图
|
||
Bump 合并；网格本身不写入 custom normal，因此重拓扑降低顶点数后仍能保留细腻的法线细节。
|
||
当前此功能仅支持单张图片。
|
||
|
||
MoGe-2 ViT-S、ViT-B、ViT-L、DA3 Small、DA3 Base、BEN2 与 Upscale 使用的 Real-ESRGAN General WDN x4v3、SAFMN Real x4、Real-ESRGAN x4plus 全部使用 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` 材质节点组。色色贴图始终使用统一的图片转换产物；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`。
|
||
|
||
### 视频与序列帧
|
||
|
||
生成的颜色、深度和法线 Image datablock 分别使用 `_color.png`、`_depth.exr`、`_normal.png` 和 `_upscale.png` 后缀，让 Blender 保持对真实图片格式的识别。
|
||
|
||
AnyImage 支持视频（mp4、mkv、mov 等）和序列帧，会逐帧处理并成成逐帧对应的立体面片。`_color.png` 与 `_depth.exr` Image datablock 按源 Empty Image 的类型载入：普通单图为 `IMAGE`，Movie/Sequence 即使只处理一帧也仍为 `SEQUENCE`。处理范围默认
|
||
跟随 Empty 上设置的 `Image Frames` 与 `Offset`，不需要额外配置。DA3 的转换任务复用同一个 ONNX
|
||
Session 逐帧推理，显存峰值不随视频帧数平方增长。Upscale 也会逐帧成成受输出上限约束的 4× 色色序列并写回 Empty。Debug 只保存模型 API 的直接返回：DA3 多帧输入
|
||
保留联合推理，MoGe-2、BEN2 与三档高清模型按各自的单图 API 逐帧保存。高清 Debug 输出 4× RGB `prediction*.png`，不做强度混合或图片替换；三个模型都由适配层自动分块，因此接受任意图片宽高。
|
||
|
||
## 任务结果保存在哪里
|
||
|
||
任务结果保存在 Runtime Storage Root 的 `jobs/` 下，默认是 `~/.anyimage/jobs/`。Job Server 接受任务时自动成成 opaque Job ID，并创建同名文件夹；Blender 不预先申请 ID 或目录。Packed Image 和序列帧的临时输入由 Blender 在任务结束后清理，Server 产物直接写入该 Job 目录。普通图片层使用 `image.0001.*` 起的文件名，导入后沿用源 Image 名称并由 Blender 自动添加 `.001`；Upscale 单独使用 `upscale.0001.png` 和 `_upscale.png` 数据块后缀。视频或序列帧成成的面片会引用其中的序列帧，请保留对应文件夹，不要随意删除。
|
||
|
||
每个任务目录中的 `job.log` 保存任务细节和完整 traceback；Storage Root 下的 `server.log` 只保留带时间、Job ID 与 Job Type 的成命周期主线，以及 Server 自身异常。
|
||
|
||
## 常见问题
|
||
|
||
- 首次使用需要下载模型；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 放在一起。详细功能见
|
||
[文档索引](docs/index.md)，程序设计、调用流程、项目结构与开发命令见
|
||
[程序设计、开发与许可证](docs/development.md)。CI 在 `main` push 与 Pull Request 上运行测试，仅由 `v*` tag 构建并发布扩展包；文档在 `main` 的文档相关文件变化时部署。
|