AnyImage/README.md

# AnyImage

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

完整使用说明请从[文档首页](docs/index.md)开始；首次使用请依次阅读
[安装与首次配置](docs/installation.md)和[五分钟上手](docs/quick-start.md)。


## 它能做什么

- 从 Image Empty 套索提取不规则区域，通过 Poisson 或 Teddy / Chordal Axis 生成封闭 Balloon，并可用 BEN2 分析轮廓、MoGe-2 添加可调深度；源 Empty 保持不变
- 一键把 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. 打开 3D 视图右侧的 `AnyImage` 面板：使用官方源点击 `Install Environment`，使用国内镜像点击 `Install Environment (Mirror)`

扩展不内置 uv 或 AI 运行库。首次使用会先下载并校验固定版本的 uv，随后自动安装轻量的 ONNX Runtime 环境，再下载 `MoGe-2 ViT-S Normal` 和
`BEN2 Base`；不安装 PyTorch，也不下载各模型的 Python 源码包。其他 AI 模型可在
`Models` panel 中按需下载，请保持网络畅通，首次安装需要一些时间。
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`。官方按钮固定使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像按钮固定使用 CNB uv Release、CNB Python 解释器镜像和清华 PyPI，两种方式都不竞速或自动切换。MoGe-2 与 BEN2 属于 post-install，各自使用独立进度，不计入 Environment 的这轮 0–100%，其模型下载源逻辑不受按钮选择影响。
任一必需模型在两个来源都下载失败时，`Install Environment` 会明确报错；Environment 本身仍会保留。
选中 Image Empty 后，右键 `AnyImage` 子菜单会在缺少 `MoGe-2 ViT-S Normal` 或 `BEN2 Base`
时显示 `Download Required Models`，一次补齐缺失项，不会重复下载已经就绪的模型。
Environment 未安装时，同一位置显示两个安装按钮。Environment 或必需模型未就绪时，
菜单仍显示 `Convert to Depth Plane`、`Convert to Surface` 和 `Remove Background`，但三个入口都会保持禁用。
`Balloon Mesh (Lasso)` 默认是 Blender 本地几何功能，在上述状态下仍可使用；开启 `Contour` 或 `Depth` 后，才需要 Environment 与对应的 BEN2 或 MoGe-2 模型。
这些 UI 状态直接检查 Storage Root 的 `models/` 文件，不会仅因打开菜单或面板而启动 Job Server。

## 快速上手

### 转换为立体面片

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` 控制。

### 套索生成 Balloon

选中单张图片的 Image Empty，右键打开 `AnyImage` 子菜单并选择 `Balloon Lasso Tool`。Blender 会激活 3D Viewport 左侧工具栏底部、紧邻 Add Cube、且不增加分隔空隙的独立 Balloon Lasso，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 或更高版本后，请重新执行一次 `Install Environment`，重建不再单独安装 BlendJob 的 Server Environment
- 首次使用需要下载模型，如果下载慢或失败，可在 Image Empty 的 `AnyImage` 右键菜单点击
  `Download Required Models`，也可在 `Models` panel 里逐项重试
- 安装 Environment 时下载状态会显示平均速度；网络适合海外源时选择 `Install Environment`，国内网络选择 `Install Environment (Mirror)`。每个按钮固定使用对应来源，失败时不会自动切换
- 默认模型下载会在 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` 的文档相关文件变化时部署。