nan
9586b35440
- Added properties for Omoo DA3 settings in properties.py, including input path, video frames, model selection, and export format. - Created runtime management in runtime.py, handling model downloads, job paths, and command execution for reconstruction. - Developed status bar functionality in status_bar.py to display job progress and status. - Implemented worker.py for image and video processing, including frame extraction and model inference. - Added comprehensive unit tests covering addon registration, model handling, export processes, and UI interactions. - Included a lock file for dependency management with uv.
155 lines
5.9 KiB
Markdown
155 lines
5.9 KiB
Markdown
# 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 下载前会在界面显示。
|