# OmooLab DA3

`OmooLab DA3` 是基于
[Depth Anything 3](https://github.com/ByteDance-Seed/Depth-Anything-3)
的 Blender Extension。Extension 在独立 Runtime 中运行 DA3，将官方导出结果保存在
独立 job 目录，并在任务完成后使用系统文件管理器打开该目录。

## 当前功能

- 使用 Blender Extension manifest，可通过 `Install from Disk` 安装
- 在独立 Python Runtime 中运行 Torch 与 DA3，避免污染 Blender Python 进程
- Runtime、模型和任务结果默认保存在 `~/.omoo_da3`，可由多个 Blender 版本共享
- 支持 DA3 Small、Base、Large 1.1、Giant 1.1 和 Nested Giant Large 1.1
- 支持单张 JPG、JPEG、PNG、WEBP 图片或常见视频文件输入
- 视频均匀抽帧，可设置参与重建的最大帧数
- `Setup` 集中管理 Runtime，并逐项列出和下载所有可用模型
- Runtime 已就绪时不额外占用面板空间；模型列表每个模型只占一行
- `Debug` 是独立且默认折叠的 DA3 测试面板
- 使用一个导出类型下拉菜单和一个 `Export` 按钮
- 只显示当前格式的专属参数；GLB 与 PLY 设置不会同时出现
- Debug 的模型选项按格式过滤；PLY 只提供两个带 Gaussian head 的 Giant 模型
- Debug 在模型选项同一行用勾选或警告图标表示下载状态，不显示状态文字、License 和
  已完成任务的文件计数
- 分别调用 DA3 的 `glb`、`gs_ply`、`depth_vis` 和 `mini_npz` exporter
- 导出完成后只打开对应 job 文件夹，不向当前 Blender 文件添加任何数据
- 完整保留每次任务生成的所有官方文件
- 安装、下载和推理均在后台子进程运行，状态栏显示阶段、百分比进度条与取消按钮

Blender 端不读取或转换导出文件，也不会重新反投影深度、构造网格、转换坐标、创建材质或
Geometry Nodes。

## 使用

1. 使用 `uv run python pack.py` 构建 Extension ZIP。
2. 在 Blender 的 `Preferences > Extensions` 中选择 `Install from Disk`。
3. 在 Extension Preferences 中确认 `uv` 路径和 Torch Backend。
4. 点击 `Install Runtime`。首次安装会下载 Python、PyTorch 和 DA3 依赖。
5. 在 3D View 按 `N`，打开 `Omoo DA3` 页签。
6. 在 `Setup` 中找到需要的模型并点击该行的 `Download`。
7. 展开默认收起的 `Debug`，选择 `Export Format` 和本次执行使用的模型。
8. 选择一张图片或一个视频文件。视频可设置均匀抽取的帧数，然后点击 `Export`。

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

每次任务会在 `~/.omoo_da3/jobs/<任务目录>/` 中保留 DA3 官方产物：

```text
<GLB 任务目录>/
└── scene.glb

<PLY 任务目录>/
└── gs_ply/*.ply

<Depth 任务目录>/
└── depth_vis/*.jpg

<Mini NPZ 任务目录>/
└── exports/mini_npz/results.npz
```

建议从 `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 文档](https://github.com/ByteDance-Seed/Depth-Anything-3/blob/main/docs/API.md)。

## Runtime

Extension 本身不包含 Torch。`Install Runtime` 使用 `uv` 创建独立 Python 3.12
环境，并安装：

- PyTorch 2.9.1
- TorchVision 0.24.1
- xFormers 0.0.33.post2（与 PyTorch 2.9.1 对应）
- 固定到已验证 commit 的 Depth Anything 3
- 固定到 DA3 官方推荐 commit 的 `gsplat`；仅安装 PLY 导出所需的纯 Python 部分，
  不编译本机 CUDA rasterizer
- `addict` 2.4.0（补充 DA3 上游包元数据暂未声明的运行依赖）

默认 CUDA Backend 为 CUDA 12.8，也可以选择 CPU。CPU 可以用于验证，但实际推理
通常很慢。

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

```text
~/.omoo_da3/
├── runtime/
├── models/
└── jobs/
```

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

## 开发

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

项目结构：

```text
.
├── pack.py
├── src/
│   └── omoo_da3/
│       ├── blender_manifest.toml
│       ├── bootstrap_runtime.py
│       ├── models.py
│       ├── operators.py
│       ├── panel.py
│       ├── preferences.py
│       ├── properties.py
│       ├── runtime.py
│       └── worker.py
└── tests/
```

## 上游与许可证

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