AnyImage/docs/technical.md

SnapForm 技术文档

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

SnapForm 是一套从图片快速构建空间结构的 Blender Extension。目前以 Depth Anything 3 作为首个 AI 能力，在独立 Runtime 中运行 DA3，可将官方导出结果保存在独立 job 目录， 也可把 Image Empty 转换成带几何与材质置换的立体面片。Debug 面板还可运行 BEN2 背景剔除功能测试。

当前功能

• 使用 Blender Extension manifest，可通过 Install from Disk 安装
• 在独立 Python Runtime 的常驻 HTTP AI Host 中运行 Torch、DA3 与 BEN2，避免污染 Blender Python 进程
• Blender 使用内置 urllib.request 访问仅监听 127.0.0.1 的 Host；请求带随机 Token
• 常驻 Host 复用 Torch、CUDA、BEN2 与最近使用的 DA3 模型，连续执行时不再重复加载
• 多个 Blender 实例自动连接同一个共享 Host；Host 面板显示状态、端口、客户端与模型缓存，并提供安装、启动、清理、重启和停止控制
• Runtime、模型和任务结果默认保存在 ~/.snapform，可由多个 Blender 版本共享
• 支持 DA3 Small、Base、Large 1.1、Giant 1.1 和 Nested Giant Large 1.1
• 支持 BEN2 Base 单图背景剔除测试，输出透明 PNG 与推理耗时
• 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
• 视频按顺序截取前若干帧，可设置参与重建的最大帧数
• Host > Models 默认折叠，展开后可逐项查看和下载所有可用模型
• Runtime 已就绪时不额外占用面板空间；模型列表每个模型只占一行
• Debug 默认折叠，内部的 DA3 与 BEN2 测试项也分别默认折叠
• 使用一个导出类型下拉菜单和一个 Export 按钮
• 只显示当前格式的专属参数；GLB 与 PLY 设置不会同时出现
• Debug 的模型选项按格式过滤；PLY 只提供两个带 Gaussian head 的 Giant 模型
• Debug 与 Convert to Depth Plane 的模型选项直接显示下载状态；未下载模型带 (Missing)，已下载模型保持原名
• 分别调用 DA3 的 glb、gs_ply、depth_vis 和 mini_npz exporter
• Image Empty 右键菜单可直接运行 DA3，根据 mini_npz 深度生成面片
• Image Empty 右键菜单可直接运行 BEN2，保留原图并换用新建的透明背景图片
• Image Empty 支持视频与序列帧输入：Convert to Depth Plane 逐帧估计深度， Remove Background 逐帧抠图，入口保持不变
• 视频生成的序列帧以外部文件引用保留在 job 目录（Blender 无法整体 Pack 序列帧）； Displace 修改器与材质 Image Texture 均可按场景帧播放序列帧
• 使用浮点深度贴图、Simple Subdivision、Displace Modifier 和原图 Bump 构建立体面片
• 转换对话框可选择推理模式、处理分辨率和面片网格细分
• Debug 的 DA3 导出或 BEN2 背景剔除完成后只打开对应 job 文件夹，不向当前 Blender 文件添加任何数据
• 完整保留每次任务生成的所有官方文件
• 安装和模型下载使用后台子进程；推理提交给常驻 AI Host，状态栏实时显示阶段、百分比进度条与取消按钮
• 后台任务运行时，Install、Download 和 Export 按钮保持原位置并变灰，任务完成后恢复

使用

1. 使用 uv run python pack.py 分别构建 windows-x64、macos-x64、macos-arm64、 linux-x64 四个平台的 Extension ZIP（如 SnapForm.v0.10.10.macos-arm64.zip）。 每个包只含对应平台的 uv 二进制，并内置 DA3、BEN2 源码包。
2. 在 Blender 的 Preferences > Extensions 中选择 Install from Disk。
3. 在 Extension Preferences 中确认 uv 路径和 Torch Backend。
4. 在 Host 点击 Install Runtime。首次安装会下载 Python、PyTorch、FastAPI、Uvicorn； DA3、BEN2 源码包与 uv 已内置在扩展中，安装时从 ~/.snapform/sources/ 解包使用， 并默认下载 DA3 Small、DA3 Base 和 BEN2 Base 模型。安装按 8 个阶段依次推进，每段进度 从 0 到 100%：解包内置 uv、创建 Python Runtime、下载 PyTorch、安装 xFormers（macOS 跳过， 内置 DA3 源码包为官方原版并已移除 xformers 硬依赖，自动回退纯 PyTorch 实现）、安装 AI 依赖， 然后是三个模型的下载。进度文字统一为 阶段/总数 阶段名: 状态， 模型下载阶段会实时显示下载速度，例如 6/8 da3 small: downloading 14.2MB/s。 Runtime 就绪后即使模型下载中断也不影响 Host 使用，可稍后在 Models 面板单独补下。 安装不做启动网络预检：若网络无法稳定访问 pypi.org，可在扩展偏好设置的 PyPI Index 中指定镜像源（如清华、阿里），该地址会通过 --pypi-index 传给 bootstrap 并优先使用； 未指定时，pip 安装失败会自动重试一次清华镜像，模型下载由 worker 自行探测回退到 HF 镜像。
5. 在 3D View 按 N，打开 SnapForm 页签。
6. 如需其他模型，展开 Host > Models，找到模型并点击该行的 Download。
7. 展开默认收起的 Debug，选择 Export Format 和本次执行使用的模型。
8. 选择一张图片或一个视频文件。视频可设置从头截取的帧数，然后点击 Export。
9. 测试背景剔除时，确认 Host > Models 中的 BEN2 Base 已就绪，然后在 Debug 的 BEN2 Background Removal 区域选择单张图片并点击 Remove Background。 完成后会打开 job 文件夹，其中的 foreground.png 带透明 Alpha；状态栏显示 BEN2 推理、模型加载与任务总耗时。当前测试固定关闭较慢的 foreground refinement。

Image Empty 去背景

1. 确认 Host > Models 中的 BEN2 Base 已就绪；首次安装 Runtime 时会默认下载。
2. 在 3D View 选中 Image Empty，右键选择 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 数值（未设置时为完整帧数），起始帧跟随 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 目录，否则序列会失效。

Image Empty 转深度面片

1. 在 3D View 选中 Object Type = Empty、Display As = Image 的对象。
2. 右键选择 Convert to Depth Plane，通过 Depth from 选择深度来源：
   • AI Generated：显示 Model、Use Ray Pose 和 Resolution Scale。实际 Process Res 为图片长边像素数 乘以 Resolution Scale；范围为 0.1–1.0，默认 1.0。计算后的 Process Res 会直接显示在 Resolution Scale (… px) 标签中。 转换导出 mini_npz，使用前需要在 Host > Models 下载所选模型，并固定使用 process_res_method="upper_bound_resize"；设备和参考视图策略 继续使用场景设置。Model 下拉菜单只列出已经下载的 DA3 模型；若没有可用模型，对话框会引导到 Host > Models 下载。
   • Original：直接把原图作为深度贴图，不显示估算参数。单张图片不启动 Runtime；视频或 序列帧会启动轻量抽帧任务，把帧抽出来作为 .depth 序列（比直接引用视频稳定）。 Original 是默认深度来源。选择 AI Generated 时，其 Model、Use Ray Pose 与 Resolution Scale 参数会集中显示在独立边框中。两种模式都有默认折叠的 Options，内部依次为 Displace via、 Subdivision、Remove Background 和 Unshaded；Delete Original 保持在折叠项外。 Remove Background 默认关闭，与 Depth from 无关；开启后需要下载 BEN2 Base，并从原图生成、 Pack .foreground 透明图片。它只替换生成面片材质的颜色图片，不修改源 Image Empty 的 Image datablock。AI Generated 仍从原图生成 .depth；例如 img.png 会得到 img.foreground 与 img.depth，不会生成 img.foreground.depth。Original 仍用原图作为 位移来源，不改变原有深度逻辑。 Image Empty 引用视频或序列帧时，AI Generated 会按 Empty 的 Image Frames 数值逐帧估计 深度（未设置时为完整帧数），起始帧跟随 Empty 的 Offset，与 Remove Background 范围一致； Offset 超出视频长度时同样把窗口收进视频内。材质节点与置换贴图的 Start 保持与原 Empty 一致；Original 模式（无 Remove Background）时，单帧会复制原图改名为 .depth 供位移使用， 视频或序列帧则抽帧保存为 job 目录根下的 frame.0001.jpg 等，并作为 .depth 序列使用。 材质颜色使用这些帧导入的 .frame 序列（Frames/Start/Offset 同步），开启 Remove Background 时改用 foreground.0001.png 序列。AI Generated 的深度以 EXR 序列帧 （depth.0001.exr 起）保存在 job 目录根下；Original 模式（含 Remove Background）的位移 使用 frame.* 序列帧，保证逐帧对齐。 Displace via 可选 Modifier（默认）或 Material； Unshaded 默认关闭；Subdivision 默认为 5，并默认删除原对象。
3. AI Generated 完成后会自动创建面片。面片几何先由 mini_npz 的相机内参与深度确定，再通过对象 Transform 匹配原 Image Empty 的可见尺寸、位置、旋转和 Offset。Original 模式直接使用源 Empty 的可见尺寸、Offset 与 Transform。开启 Delete Original 时，成功生成后 删除源 Empty。生成面片 Object 使用源 Empty 的原名；关闭 Delete Original 时不处理 同名冲突，由 Blender 自动为生成面片追加编号。
4. 短边分段数为 2^Subdivision，长边分段数根据图像宽高比取最接近的整数。例如高:宽为 2:3、Subdivision 为 1 时，直接生成 2×3 个面；Subdivision 为 3 时生成 8×12 个面。随后的 Simple Subdivision 修改器使用原生名称，Viewport Levels 固定为 1，Render Levels 固定为 2，不再随 Resolution Scale 或 Subdivision 动态变化。

所有任务使用统一的状态栏进度显示。变化中的阶段说明显示在右侧的紧凑进度条内部，取消按钮 位于进度条右侧。Image Depth 的阶段包括 Runtime 启动、输入准备、模型加载、深度估算、缓存 写出和面片构建。进度更新会强制刷新状态栏与窗口，无需移动鼠标即可实时显示。安装中断后残留的 半成品 Runtime 会在下次安装前自动清理，不会因为中断而无法再次安装。

导入过程精确保留 NPZ 内深度值之间的差值。例如深度 2.0 和 5.5 在 Displacement Strength = -1 时，沿局部 Z 轴相差 3.5 Blender Unit。它不会把数值压缩到 0..1，也不再提供视觉归一化模式。

面片尺寸以有效深度的中位数 Zref 作为参考截面。先用 mini_npz 中的相机内参计算原始 投影面积，再恢复源图纵横比：

RawWidth  = depth_width  × Zref × abs(Displacement Strength) / fx
RawHeight = depth_height × Zref × abs(Displacement Strength) / fy
Area      = RawWidth × RawHeight
Aspect    = source_image_width / source_image_height
Width     = sqrt(Area × Aspect)
Height    = sqrt(Area / Aspect)

这样即使 DA3 估计出的 fx/fy 不一致，也不会把正方形原图拉成长方形。主点 cx/cy 仍用于 确定原始相机面片，随后对象 XY Transform 将它匹配到源 Image Empty。生成对象会记录 snapform_reference_depth、snapform_camera_plane_width 和 snapform_camera_plane_height，便于检查实际采用的 参考深度和尺寸。

选择 Modifier 时，AI Generated 的 Displace Modifier 深度贴图使用 Extension = Extend， Strength 固定为 -1、Midlevel 固定为 1。Original 把原图指定给 Displace Texture，并设置 Texture Coordinates = UV、Midlevel = 0；其余修改器设置保留 Blender 默认值。 视频与序列帧生成的深度贴图是 SEQUENCE Image；Displace 修改器的 Texture 与材质的 Image Texture 节点都支持序列帧，通过 image_user 的 Frames / Offset / Start 设置把第 i 帧映射到场景 Start+i 帧（Start 沿用 Empty 的 Start），并启用 Auto Refresh，播放时随场景帧逐帧更新。 选择 Material 时，不创建 Displace Modifier；深度 Image Texture 的 Color 连接到 Displacement 节点的 Height，再连接 Material Output 的 Displacement，并把材质 Surface Displacement 设置为 Displacement Only。AI Generated 使用 Midlevel = 1、Scale = -1；Original 使用 Midlevel = 0、Scale = 1，与对应修改器值一致。无论选择哪种呈现方式，原始彩色贴图都会连接 Principled BSDF 的 Base Color，并通过 Bump.Height → Bump.Normal → Principled.Normal 提供表面细节。Bump 的基础 Distance 为 0.001，会乘以面片 Transform 的统一缩放倍率。原图 Color 还会经过 Float Curve 连接到 Principled BSDF 的 Roughness，曲线两端输出分别为 0.5 和 0.1；材质 IOR 保持 Principled BSDF 默认值 1.5。 开启 Unshaded 后，原图 Color 连接 Emission，原图 Alpha 作为 Mix Shader 系数，在 Transparent BSDF 与 Emission 之间混合后连接 Material Output；不创建 Principled BSDF、Bump 或 Float Curve。若 Displace via 选择 Material，深度贴图与 Displacement 节点仍会保留并连接 Material Output 的 Displacement。

这里的“原始距离”是 DA3 模型输出的尺度。普通 Small、Base、Large 和 Giant 模型的深度不应 被解释为现实世界的米；需要现实尺度时应选择带 metric depth 的 DA3 Nested Giant Large 1.1。此外，当前结果仍是固定 XY 平面上的深度位移面，不是使用 相机内参逐像素反投影得到的完整 camera-space 网格；中位深度截面为现有 Displace Modifier 工作流提供正确的整体高宽尺度。

生成完成后会直接创建面片，不提供缓存重建入口或单独的导入参数。重新选择 Convert to Depth Plane 会按当前 Depth from 再次转换。 面片、深度 Image、Texture 与 Material 会在同一个 Blender Undo 步骤中创建；转换完成后执行 Ctrl+Z 会完整撤销本次转换，不会越过转换去回退更早的 Image Empty 操作。 开启 Remove Background 时，.foreground Image 的创建、Pack 和深度面片生成也属于 同一个 Undo 步骤。

Image Empty 使用 Packed Image 时，SnapForm 会通过 Blender 写出临时 PNG 交给 DA3， 不会 Unpack 或修改源 Image；任务结束后自动删除临时文件。普通图片仍直接读取源文件。DA3 的原始 results.npz 保留在对应 job 文件夹根下，生成的浮点深度 Image 会 Pack 到 当前 .blend。Depth Image 与 Displace Texture 根据源 Image datablock 命名。例如 Empty Object 名为 obj_img、引用的 Image 名为 img.png 时，Depth Image 与 Texture 都命名为 img.depth； 生成的 Object、Mesh 与 Material 仍命名为 obj_img。Pack 使用 OpenEXR，因而不会把大于 1.0 的原始深度截断。已有同名 datablock 时由 Blender 自动追加 .001 等编号。 视频输入时 Blender 无法整体 Pack 序列帧，因此 .depth 与颜色序列改为引用 job 目录根下的 depth.0001.exr、frame.0001.jpg（.frame）或 foreground.0001.png，并在每帧保留原始 浮点深度；保存 .blend 后再次打开仍需对应 job 目录存在。

选择 PLY 后，模型菜单只会提供 DA3 Giant 1.1 和 DA3 Nested Giant Large 1.1。Small、Base 和 Large 没有 Gaussian head，无法由 DA3 生成 gs_ply。

每个任务在 ~/.snapform/jobs/ 下用独立文件夹包裹（命名格式为 任务类型_时间号，例如 depth-plane_20260807-153000），日志、状态与输出产物都放在该文件夹内：

reconstruct_20260807-153000/
├── reconstruct_20260807-153000.log
├── reconstruct_20260807-153000.json
└── scene.glb

reconstruct_20260807-153000/
├── reconstruct_20260807-153000.log
├── reconstruct_20260807-153000.json
└── gs_ply/*.ply

reconstruct_20260807-153000/
├── reconstruct_20260807-153000.log
├── reconstruct_20260807-153000.json
└── depth_vis/*.jpg

reconstruct_20260807-153000/
├── reconstruct_20260807-153000.log
├── reconstruct_20260807-153000.json
└── results.npz

remove-background_20260807-153000/
├── remove-background_20260807-153000.log
├── remove-background_20260807-153000.json
├── foreground.png            单图结果
├── foreground.0001.png…      视频/序列帧结果
├── frame.0001.jpg…           视频/序列帧的源帧副本
└── depth.0001.exr…           AI 深度序列帧

建议从 DA3 Base 开始。它使用 Apache 2.0 模型权重；DA3 Large 1.1 权重采用 CC BY-NC 4.0，仅限非商业用途。

输出格式说明

Export Format 下拉菜单分别把以下原始 export_format 传给 DA3：

• GLB：glb
• PLY：gs_ply，同时传入 infer_gs=True
• Depth Images：depth_vis
• Mini NPZ：mini_npz

界面使用 DA3 API 的参数名、选项和默认值。GLB 专属设置仅在选择 GLB 时显示， gs_views_interval 仅在选择 PLY (3DGS) 时显示：

• process_res=504
• process_res_method="upper_bound_resize"
• use_ray_pose=False
• ref_view_strategy="saddle_balanced"
• conf_thresh_percentile=40.0
• num_max_points=1_000_000
• show_cameras=True
• export_kwargs["gs_ply"]["gs_views_interval"]=1

DA3 官方 glb 是彩色点云与可选相机线框；gs_ply 是带 Gaussian 属性的 PLY； depth_vis 是原图与着色深度图的并排预览；mini_npz 保存深度、置信度和可用的相机参数。 GLB 任务会关闭其默认附带的深度预览，使四种 job 产物保持分离。

官方格式与限制可参阅 DA3 Python API 文档。

Runtime

Extension 本身不包含 Torch。Install Runtime 使用 uv 创建独立 Python 3.12 环境，并安装。机器上即使没有安装 uv 或 Python 也没关系：安装程序由 Blender 自带的 Python 启动，缺 uv 时会自动下载官方独立二进制（约 30MB），再用它下载 Python 3.12 与全部依赖。uv 会缓存在扩展存储目录下，后续安装直接复用。 安装不做网络预检，直接开始；环境变量仍可切换镜像与代理：PIP_INDEX_URL（PyPI 镜像）、 SNAPFORM_TORCH_INDEX（PyTorch 索引）、HF_ENDPOINT（Hugging Face 镜像）、 HTTP(S)_PROXY/ALL_PROXY（代理）。未指定 PyPI 镜像时， pip 安装失败会自动依次重试镜像（清华、阿里云）；模型下载不预探测，官方 Hugging Face 失败后自动回退 ModelScope（modelscope.cn，仓库名与 Hugging Face 一致）。 GitHub 不再参与安装：DA3、BEN2、uv 已内置，缺少内置文件会直接报错提示重新安装，不再下载兜底。 单独下载模型时遵循同样的顺序：Hugging Face（可用 HF_ENDPOINT 指定其他镜像）失败后自动切换到 ModelScope。 Windows 上代理若只在系统设置里而未写入环境变量，安装程序会尝试自动从系统代理注入子进程。

• PyTorch 2.9.1
• TorchVision 0.24.1
• xFormers 0.0.33.post2（与 PyTorch 2.9.1 对应，仅 Windows/Linux；macOS 无 wheel 自动跳过）
• 固定到已验证 commit 的 Depth Anything 3
• 固定到已验证 commit 的 BEN2
• FastAPI 0.139.2 与 Uvicorn 0.51.0
• DA3 与 BEN2 源码包随扩展打包，安装时复制到 ~/.snapform/sources/ 后由 uv 本地安装 （无需访问 GitHub）；SnapForm 直接调用 DA3 底层 export 接口，gs_ply 导出不会触发 gs_video 渲染，因此不需要 gsplat 与 C++ 编译工具链
• sources/ 下的 DA3/BEN2 源码包保持官方原版（固定 commit）；sources/patches/<包名>/ 存放 SnapForm 对源码的覆盖文件（移除 xformers 硬依赖、export 入口改懒加载、 射线位姿的 3×3 QR 分解在 MPS 上改走 CPU）， pack.py 打包时自动套入官方包，扩展 zip 内才是修补后的版本；更新上游只需替换官方包 并核对覆盖文件是否仍适用
• addict 2.4.0（补充 DA3 上游包元数据暂未声明的运行依赖）

默认 CUDA Backend 为 CUDA 12.8，也可以选择 CPU。CPU 可以用于验证，但实际推理 通常很慢。 CUDA 12.8 的 PyTorch wheel 自带 CUDA 运行库，无需安装 CUDA Toolkit；只需要 NVIDIA 驱动 ≥ 570（数据中心显卡可用更老驱动）。驱动不满足或没有 NVIDIA 显卡时， 设备会自动回退到 CPU（macOS 为 MPS），只有显式选择 CUDA 才会报错。

macOS（Apple Silicon）会自动从 PyPI 安装 CPU 版 PyTorch，推理设备默认使用 MPS （Apple Metal）加速，也可以在设备选项里切换 CPU。PyTorch 自 2.3 起不再提供 Intel Mac（x86_64）轮子，Intel Mac 暂不支持。DA3 射线位姿估计中的 3×3 QR 分解在 MPS 上尚未实现，SnapForm 的覆盖文件会单独把该分解放到 CPU 执行，其余推理仍走 MPS。

Extension 启用后只会查找已有的共享 AI Host，不会主动启动新进程。第一次执行 AI 操作或在侧边栏 手动点击 Start 时才会启动 Host。Host 只绑定回环地址，并让操作系统分配动态端口；第一个实例把 端口、进程和随机 Token 写入 host.json，其余 Blender 通过标准库 urllib.request 连接同一个 Host。host.lock 保证同一 Storage Root 同时只有一个 Host，Token 则阻止同机其他进程直接调用接口。Host 全局同时只执行一个 AI 任务。

每个 Blender 会注册独立客户端并每 5 秒发送心跳。正常关闭 Blender 时先注销自身；如果当前 Host 就是由这个 Blender 启动的，会直接终止它，无需等待。异常退出的客户端会在 10 秒后过期；Host 在最后一个客户端离开后仍会保留模型缓存等待 20 秒再退出，作为 Host 由其他进程启动等场景的兜底。 取消任务不会重启 Host，并会保留已经加载的模型； 如果取消发生在一次不可中断的 Torch 调用中，任务会在该调用返回后的最近检查点结束。

侧边栏 Host 面板以 Running (Clients: n) 表示空闲服务，以 Running (Busy) 表示正在执行任务， 并显示缓存模型和活动任务。空闲且只有当前 Blender 连接时，可以清理模型缓存、重启或停止 Host； 多客户端或任务执行期间不会允许破坏共享服务。

BEN2 在首次使用后保持加载；DA3 保留最近使用的一个模型。切换 DA3 模型时会释放旧模型；加载时如果 显存不足，会先释放另一类缓存模型并重试。

Runtime Schema 已升级，旧 Runtime 需要重新执行 Install Runtime 才能安装 HTTP Host 依赖。 Host 的启动和崩溃日志写入 ~/.snapform/ai-host.log。

Runtime、模型和任务结果默认保存在用户主目录的 ~/.snapform：

~/.snapform/
├── runtime/
├── models/
├── jobs/
├── ai-host.log
├── host.json       # Host 运行时存在
└── host.lock       # Host 运行时持有

不同 Blender 版本安装相同 Extension 后会共用这个目录。也可以在 Extension Preferences 的 Storage Root 中修改共享位置。不要把模型写入 Extension 安装目录， 因为该目录可能只读，并且升级时会被替换。不要同时从多个 Blender 实例执行 Install Runtime；推理 Host、任务队列和模型读取可以共享。

开发

uv run python -m unittest discover -s tests -v
uv run python pack.py

项目结构：

.
├── pack.py
├── sources/                官方 DA3/BEN2 源码包、patches 覆盖文件与各平台 uv 二进制
├── src/
│   └── snapform/
│       ├── blender_manifest.toml
│       ├── ai_host.py
│       ├── bootstrap_runtime.py
│       ├── models.py
│       ├── image_depth.py
│       ├── operators.py
│       ├── panel.py
│       ├── preferences.py
│       ├── properties.py
│       ├── runtime.py
│       └── worker.py
└── tests/

上游与许可证

• Depth Anything 3 代码采用 Apache 2.0。
• BEN2 代码与模型权重采用 MIT License。
• 本 Extension 代码采用 GPL-3.0-or-later。
• 模型权重许可证由所选 Hugging Face 模型仓库决定，Extension 下载前会在界面显示。