# 功能与使用

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

`SnapForm` 是一套从图片快速构建空间结构的 Blender Extension。目前以
[Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
作为首个 AI 能力，在独立 Environment 中运行 DA3，可将模型 API Prediction 保存在独立 job 目录，
也可把 Image Empty 转换成带几何与材质置换的立体面片。MoGe-2 作为独立深度来源，保留其 metric depth、normal、mask 与 intrinsics 输出，不复用 DA3 Prediction 后处理。Debug 面板还可运行
[BEN2](https://github.com/PramaLLC/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` 也分别默认折叠
- DA3、MoGe-2 与 BEN2 分别使用独立 Debug Job，直接保存各自 API 返回，不共享按模型分支的总控函数
- DA3 Debug 保存 Prediction NPZ；MoGe-2 Debug 保存逐帧原始预测 NPZ；BEN2 Debug 保存直接返回的透明前景
- Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带
  `(Missing)`，已下载模型保持原名
- Debug 不运行点云、Surface、深度预览、置信度 percentile 或坐标变换等 SnapForm 后处理
- 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`、`Convert to Surface` 和 `Remove Background`。Environment 未安装时，
  同一位置改为显示 `Install Environment` 与 `Install Environment (Mirror)`，三个禁用的功能入口仍然可见
- 菜单、模型面板和转换对话框直接检查 Storage Root 的 `models/` 必需文件，显示模型状态时不会启动 Job Server
- Image Empty 支持视频与序列帧输入：`Convert to Depth Plane` 逐帧估计深度，
  `Remove Background` 逐帧抠图，入口保持不变。DA3 转换时每帧独立执行 ONNX 推理并复用模型 Session；
  DA3 Debug 多帧任务继续联合推理；MoGe-2 与 BEN2 Debug 按单图 API 逐帧运行
- 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）；
  Geometry Nodes 与材质 Image Texture 均可按场景帧播放序列帧
- 使用浮点深度贴图、`O DA3 Depth Plane` Geometry Nodes 和原图 Bump 构建立体面片
- 转换对话框选择推理模式、处理分辨率与背景移除；细分和置换方式在 Geometry Nodes 修改器中调整
- Debug 的 DA3 输出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不修改当前场景
- Debug 完整保留模型 API 返回的数组字段，不混入 SnapForm 派生几何
- 安装和模型下载使用后台子进程；推理提交给常驻 Server，状态栏实时显示阶段、百分比进度条与取消按钮
- 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复

## 使用

1. 运行 `uv run python pack.py`，分别构建 `windows-x64`、`macos-arm64`、
   `linux-x64` 三个平台的 Extension ZIP（如 `SnapForm.v0.12.14.macos-arm64.zip`）。
   安装包不携带 uv 或 AI 项目源码；首次安装 Environment 时下载固定版本 uv，并校验固定 SHA-256。官方安装按钮使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像按钮使用 CNB uv Release、CNB Python 解释器镜像和清华 PyPI。
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` 或 `Install Environment (Mirror)`。首次安装会下载 Python、ONNX Runtime、FastAPI、Uvicorn；
   uv 由 Job Runtime 的 Environment 安装器下载并校验，DA3、BEN2 与 MoGe 不安装源码包，
   并在 Environment 安装后自动下载 `MoGe-2 ViT-S Normal` 和 FP16 `BEN2 Base` 推荐模型。首次安装
   Environment Bootstrap 的 0–100% 只包含 uv、Python 与 packages：三阶段显示 `1/3`、`2/3`、`3/3`，范围分别为 1–20%、20–50%、50–98%，最终验证使用 98–100%。下载占各阶段的 84–87%；开始与验证不显示编号，单阶段状态不显示 `1/1`。
   两个默认模型由普通的 `post_install(runtime)` 发起正式 Server Job。
   安装完成后直接写入 Environment Manifest，不再额外导入全部组件进行验证；`DA3 Base` 等其他模型可稍后在 `Models` 面板按需下载。
   Environment packages 使用固定的 Resolving、Downloading 与 Installing 状态，原始 uv 输出写入 `install.log`。模型下载显示速度，例如
   `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 失败。
   官方安装固定使用 GitHub、uv 默认 Python 下载源和 PyPI；镜像安装固定使用 CNB uv Release、`python-build-standalone` 镜像和清华 PyPI。两种方式都不测速、不竞速、不自动切换，镜像配置只注入当前安装子进程。模型仍按自身的 Hugging Face 与 OmooLab R2 逻辑下载。
5. 在 3D View 按 `N`，打开 `SnapForm` 页签。
6. 如需其他模型，展开 `Models` panel，找到模型并点击该行的 `Download`。
7. 展开默认收起的 `Debug`，在 DA3、MoGe-2 或 BEN2 区域选择模型与输入，然后直接运行对应 API。
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 使用原图去掉格式后再追加 `.color` 的名称。例如 `img.png` 生成
   `img.color`，`img.png.001` 生成 `img.001.color`。已有同名 datablock 时由
   Blender 自动追加编号。

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

Image Empty 引用视频或序列帧时，Remove Background 直接执行，默认取 Empty 的 Image Frames
数值（未设置时为完整帧数，显式设为 1 时只处理 1 帧），起始帧跟随 Empty 的 Offset；若 Offset 加 Frames 超出视频长度，
会把窗口整体收进视频内（保证实际处理 Frames 帧数），Offset 过小时从第 1 帧开始。输出
`color.0001.png` 等透明序列帧（帧号从 0001 开始，与 Blender 场景帧一一对应），并把
关闭去背景时，原始颜色帧同样以 `color.0001.*` 起始的统一名称写入 job 目录。替换 Empty 的 Image 为
加载这些帧的 SEQUENCE Image，从原 Empty 的 Start 位置开始播放（Start 原样保留）。图片类型只取决于源 Empty：普通单图的单个 `color.0001.*` 仍作为 `IMAGE`，Movie/Sequence 即使只导出一帧也作为 `SEQUENCE`；`.depth` 同样遵循该规则。
Cyclic 沿用原 Empty 的设置。序列帧无法被 Blender 整体 Pack，因此保持外部引用 job 目录；
请保留对应 job 目录，否则序列会失效。