AnyImage/docs/features.md

功能与使用

本文档面向开发者和需要了解内部实现细节的用户，从原 README 迁移而来。普通用户请阅读项目根目录的 README.md。

SnapForm 是一套从图片快速构建空间结构的 Blender Extension。目前以 Depth Anything 3 作为首个 AI 能力，在独立 Environment 中运行 DA3，可将官方导出结果保存在独立 job 目录， 也可把 Image Empty 转换成带几何与材质置换的立体面片。MoGe-2 作为独立深度来源，保留其 metric depth、normal、mask 与 intrinsics 输出，不复用 DA3 Prediction 后处理。Debug 面板还可运行 BEN2 背景剔除功能测试。

当前功能

• 使用 Blender Extension manifest，可通过 Install from Disk 安装
• 在独立 Environment 中通过常驻 Server 运行 ONNX Runtime；MoGe-2、DA3 与 BEN2 的模型执行及后处理完全不使用 PyTorch，避免污染 Blender Python 进程
• Server 的深度模型缓存只保留 DA3 或 MoGe-2 其中一个，切换时主动释放前一个；BEN2 使用独立缓存， 可与当前深度模型共存
• Blender 使用内置 urllib.request 访问仅监听 127.0.0.1 的 Server；连接由随机端口与 Instance ID 归属当前 Runtime
• 常驻 Server 复用 ONNX Runtime session、BEN2 与最近使用的深度模型，连续执行时不再重复加载
• 每个 Blender 实例持有自己的 Job Server；Job Server 面板显示状态与模型缓存，并提供安装、启动、清理、重启和停止控制
• Environment、模型和任务结果默认保存在 ~/.snapform，可由多个 Blender 版本共享
• 当前仅启用 FP32 DA3 Small 和 Base；它们不随首次安装下载，Giant 1.1 与 Nested Giant Large 1.1 暂停使用
• 支持 BEN2 Base 单图背景剔除测试，输出透明 PNG 与推理耗时
• 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
• 视频按顺序截取前若干帧，可设置参与重建的最大帧数
• Models panel 默认折叠，展开后可逐项查看和下载所有可用模型
• Environment 已安装时不额外占用面板空间；模型列表每个模型只占一行
• Debug 默认折叠，内部的 DA3、MoGe-2 与 BEN2 也分别默认折叠
• 使用一个输出类型下拉菜单和一个 Generate Output 按钮
• DA3 与 MoGe-2 Debug 都先选择单一 Output Format，只显示当前格式的专属参数；GLB 与 PLY 不会在一次测试中同时生成
• Debug 的模型选项按格式过滤；PLY 只提供两个带 Gaussian head 的 Giant 模型
• Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带 (Missing)，已下载模型保持原名
• 分别调用 DA3 的 glb、gs_ply、depth_vis 和 mini_npz exporter
• Textured Surface (GLB) 直接使用 DA3 Prediction 中的深度、置信度和相机参数，把相邻像素 组成三角面并写入 mesh.glb；每个输入帧生成一张独立纹理网格，不做多视图融合
• Image Empty 右键菜单可直接运行 DA3，根据 mini_npz 深度生成面片
• Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
• 缺少必需的 MoGe-2 ViT-S Normal 或 BEN2 Base 时，Image Empty 的 SnapForm 右键子菜单显示 Download Required Models；单次任务只下载缺失项，并在补齐前禁用 Convert to Depth Plane
• 菜单、模型面板和转换对话框直接检查 Storage Root 的 models/ 必需文件，显示模型状态时不会启动 Job Server
• Image Empty 支持视频与序列帧输入：Convert to Depth Plane 逐帧估计深度， Remove Background 逐帧抠图，入口保持不变。DA3 转换时每帧独立执行 ONNX 推理并复用模型 Session； Debug 多帧任务继续联合推理，以保留跨视图相机与深度关系
• 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）； Geometry Nodes 与材质 Image Texture 均可按场景帧播放序列帧
• 使用浮点深度贴图、O DA3 Depth Plane Geometry Nodes 和原图 Bump 构建立体面片
• 转换对话框选择推理模式、处理分辨率与背景移除；细分和置换方式在 Geometry Nodes 修改器中调整
• Debug 的 DA3 输出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不修改当前场景
• 完整保留每次任务生成的所有官方文件
• 安装和模型下载使用后台子进程；推理提交给常驻 Server，状态栏实时显示阶段、百分比进度条与取消按钮
• 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复

使用

1. 运行 uv run python pack.py，分别构建 windows-x64、macos-arm64、 linux-x64 三个平台的 Extension ZIP（如 SnapForm.v0.12.6.macos-arm64.zip）。 安装包不携带 uv 或 AI 项目源码；首次安装 Environment 时下载固定版本 uv，官方源建连超过 3 秒后回退 OmooLab 镜像，并校验固定 SHA-256。
2. 在 Blender 的 Preferences > Extensions 中选择 Install from Disk。
3. 在 Extension Preferences 中确认 Storage Root 与 Device。Device 是正式功能 （Image Empty 右键菜单）使用的推理设备，默认取本机最快的 DirectML/CoreML provider，否则 CPU，且只列出 本机支持的设备。
4. 在 Job Server 点击 Install Environment。首次安装会下载 Python、ONNX Runtime、FastAPI、Uvicorn； uv 由 Job Runtime 的 Environment 安装器下载并校验，DA3、BEN2 与 MoGe 不安装源码包， 并在 Environment 安装后自动下载 MoGe-2 ViT-S Normal 和 FP16 BEN2 Base 推荐模型。首次安装 依次显示 Environment、MoGe-2 ViT-S Normal 与 BEN2 Base；每项都独立从 0 走到 100%， 进入下一项时进度条归零，模型 post-install 不显示 2/2 等阶段编号。uv、Python Environment 与 packages 合并在第一轮， 两个默认模型由普通的 post_install(runtime) 发起正式 Server Job。 安装完成后直接写入 Environment Manifest，不再额外导入全部组件进行验证；DA3 Base 等其他模型可稍后在 Models 面板按需下载。 依赖安装显示当前安装输出；模型下载显示速度，例如 Downloading DA3 Small 14.2 MB/s；镜像来源显示为 Downloading DA3 Small (mirror) 14.2 MB/s。下载按字节连续推进，重试或切换镜像时进度不会倒退。 Environment 安装阶段与 Models 面板单独下载使用相同的模型名称格式，不会改写为通用的 Downloading packages。 Environment 安装后即使模型下载中断也仍会保留，但 Install Environment 会以失败结束并显示模型下载错误。 可稍后在 Image Empty 的 SnapForm 右键菜单用 Download Required Models 一次补齐缺失的 MoGe-2 ViT-S 与 BEN2，也可在 Models 面板单独补下。 安装不做启动网络预检；每个模型都先尝试 Hugging Face，失败后尝试 OmooLab R2，两者都失败时当前 Job 失败。 下载源不写入持久状态；需要手动指定依赖镜像时可通过 UV_INDEX_URL 环境变量覆盖。
5. 在 3D View 按 N，打开 SnapForm 页签。
6. 如需其他模型，展开 Models panel，找到模型并点击该行的 Download。
7. 展开默认收起的 Debug，选择 Output Type 和本次执行使用的模型。
8. 选择一张图片或一个视频文件。视频可设置从头截取的帧数，然后点击 Generate Output。
9. 测试背景剔除时，确认 Models panel 中的 BEN2 Base 已就绪，然后在 Debug 的 BEN2 区域选择单张图片并点击 Remove Background。 完成后会打开 job 文件夹，其中的 foreground.png 带透明 Alpha；状态栏显示 BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。

Image Empty 去背景

1. 确认 Models panel 中的 BEN2 Base 已就绪；首次安装 Environment 时会默认下载。
2. 在 3D View 选中 Image Empty，右键打开 SnapForm 子菜单并选择 Remove Background。
3. 完成后以 Fake User 保留原 Image datablock，新建并 Pack 一张透明 PNG 到当前 .blend，然后只把 当前 Empty 的 data 换成新图；Empty 的 Transform、显示尺寸、Offset 及其他设置保持不变。
4. 新 Image 使用原图去掉格式后再追加 .foreground 的名称。例如 img.png 生成 img.foreground，img.png.001 生成 img.001.foreground。已有同名 datablock 时由 Blender 自动追加编号。

原图已 Pack 时会先写出临时 PNG 交给 BEN2，任务结束后删除临时输入；原 Image 仍保持 Pack 状态和原始内容。BEN2 的 foreground.png 也会保留在对应 job 目录中。

Image Empty 引用视频或序列帧时，Remove Background 直接执行，默认取 Empty 的 Image Frames 数值（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset；若 Offset 加 Frames 超出视频长度， 会把窗口整体收进视频内（保证实际处理 Frames 帧数），Offset 过小时从第 1 帧开始。输出 foreground.0001.png 等透明序列帧（帧号从 0001 开始，与 Blender 场景帧一一对应），并把 源帧以 frame.0001.jpg 等命名复制到 job 目录根下供材质颜色导入。替换 Empty 的 Image 为 加载这些帧的 SEQUENCE Image，从原 Empty 的 Start 位置开始播放（Start 原样保留）， Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因此保持外部引用 job 目录； 请保留对应 job 目录，否则序列会失效。