# Media Depth 系统现状说明

更新时间：2026-05-20

## 1. 项目定位

Media Depth 是一个图片/视频深度图生成与点云导出的本地项目。当前主体功能包括：

- 使用 Depth Anything V1 生成单图或批量图片深度图。
- 使用 Depth Anything V2 生成单图或批量图片深度图。
- 使用 Depth Anything V3，也就是 DA3，对图片、图片目录、视频、COLMAP 数据等生成深度、相机、NPZ、GLB 等结果。
- 使用根目录工具把原图和灰度深度图转换为 PLY 点云文件。
- 使用根目录批处理脚本统一调度 V1/V2 的多个 encoder，并批量导出深度图和点云。

## 2. 当前目录结构

- `Depth-Anything-V1-main/`：Depth Anything V1 代码目录。
- `Depth-Anything-V2-main/`：Depth Anything V2 代码目录。
- `Depth-Anything-V3-main/`：Depth Anything V3/DA3 代码目录，原 `Depth-Anything-3-main-待处理/` 已改名。
- `Data/`：默认样例输入目录。
- `1_Batch_Gen_All_Depth(跑之前删除结果文件夹).py`：批量运行 V1/V2 深度图生成。
- `2_Batch_Gen_All_PLY.py`：批量扫描深度图结果并生成 PLY。
- `Tool_Gen_3d_points_Cloud.py`：单组原图和深度图生成 PLY 的底层工具。
- `README.md`：项目快速运行说明。
- `使用手册-All.txt`：原有简版运行指南。
- `.gitignore`：Git 排除规则，避免提交权重、运行结果、大视频和安装包。

## 3. Conda 环境

当前已创建环境：

```bash
conda activate Media_Depth
```

环境关键信息：

- Python：3.12
- PyTorch：2.7.1+cu118
- torchvision：0.22.1+cu118
- CUDA 编译工具：conda 环境内 CUDA 11.8
- NumPy：1.26.4
- OpenCV：4.11.0
- xformers：0.0.31.post1
- gsplat：1.5.2
- open3d：0.19.0

CUDA 验证已通过，PyTorch 可以识别 GPU，测试机器上检测到 NVIDIA GeForce RTX 3090。

## 4. 权重放置情况

权重文件和 checkpoints 不提交到 Git。当前本地目录中有可用权重，但备份仓库中不包含这些文件。

V1 权重放置目录：

```text
Depth-Anything-V1-main/checkpoints/
```

V2 权重放置目录：

```text
Depth-Anything-V2-main/checkpoints/
```

V3/DA3 权重放置目录：

```text
Depth-Anything-V3-main/checkpoints/
```

DA3 每个模型目录中应至少包含：

```text
config.json
model.safetensors
```

当前已验证使用的是：

```text
Depth-Anything-V3-main/checkpoints/DA3-SMALL
```

## 5. V1 运行状态

V1 已验证可以顺利运行。

验证命令类型：

```bash
cd Depth-Anything-V1-main
python run.py \
  --encoder vits \
  --img-path ../Data/09-19-54.mp4.00_02_12_09.Still001.png \
  --outdir /tmp/media_depth_v1_vits \
  --pred-only \
  --grayscale
```

验证结果：

- 命令执行成功。
- 已生成灰度深度图。
- 使用 `vits` 权重完成单张样例推理。

## 6. V2 运行状态

V2 已验证可以顺利运行。

验证命令类型：

```bash
cd Depth-Anything-V2-main
python run.py \
  --encoder vits \
  --img-path ../Data/09-19-54.mp4.00_02_12_09.Still001.png \
  --outdir /tmp/media_depth_v2_vits \
  --pred-only \
  --grayscale
```

验证结果：

- 命令执行成功。
- 已生成灰度深度图。
- 使用 `vits` 权重完成单张样例推理。

## 7. V3/DA3 运行状态

V3/DA3 已验证可以顺利运行。

已修复的问题：

- `Depth-Anything-V3-main/src/depth_anything_3/cli.py` 中，`image`、`images`、`colmap`、`video` 命令曾把 `ref_view_strategy` 错写成未定义的 `reference_view_strategy`。
- 该问题会导致相关命令直接 `NameError`。
- 当前已修正为 `ref_view_strategy=ref_view_strategy`。

验证命令类型：

```bash
cd Depth-Anything-V3-main
da3 auto ../Data/09-19-54.mp4.00_02_12_09.Still001.png \
  --model-dir checkpoints/DA3-SMALL \
  --device cuda \
  --export-format mini_npz \
  --export-dir /tmp/media_depth_da3_auto \
  --auto-cleanup \
  --process-res 224
```

```bash
cd Depth-Anything-V3-main
da3 image ../Data/09-19-54.mp4.00_02_12_09.Still001.png \
  --model-dir checkpoints/DA3-SMALL \
  --device cuda \
  --export-format mini_npz \
  --export-dir /tmp/media_depth_da3_image \
  --auto-cleanup \
  --process-res 224
```

验证结果：

- `da3 auto` 执行成功。
- `da3 image` 执行成功。
- 两个命令均生成 `results.npz`。
- 目录改名为 `Depth-Anything-V3-main` 后，需要重新执行一次 editable 安装，确保 `da3` 命令指向新路径。

## 8. PLY 点云导出状态

PLY 导出已验证可以顺利运行。

验证命令类型：

```bash
python Tool_Gen_3d_points_Cloud.py \
  --img_path_ori /home/wkmgc/Desktop/Depth/Data \
  --img_path_depth /tmp/media_depth_v1_vits \
  --outdir /tmp/media_depth_ply \
  --appendix "" \
  --label-type Depth \
  --z-scale 0.7
```

验证结果：

- 命令执行成功。
- 已生成 `.ply` 文件。
- PLY 文件头正常。
- 样例点数为 `8294400`。

## 9. 常用运行方式

批量生成 V1/V2 深度图：

```bash
python "1_Batch_Gen_All_Depth(跑之前删除结果文件夹).py" --img-path ./Data
```

批量生成 PLY：

```bash
python 2_Batch_Gen_All_PLY.py \
  --img-path ./Data \
  --z-scale 0.7 \
  --brightness 1.0 \
  --saturation 1.0 \
  --gamma 1.0
```

V3/DA3 单图：

```bash
cd Depth-Anything-V3-main
da3 image ../Data/09-19-54.mp4.00_02_12_09.Still001.png \
  --model-dir checkpoints/DA3-SMALL \
  --device cuda \
  --export-format mini_npz \
  --export-dir workspace/gallery/test_image \
  --auto-cleanup
```

V3/DA3 自动识别输入类型：

```bash
cd Depth-Anything-V3-main
da3 auto ../Data/09-19-54.mp4.00_02_12_09.Still001.png \
  --model-dir checkpoints/DA3-SMALL \
  --device cuda \
  --export-format mini_npz-glb \
  --export-dir workspace/gallery/test_auto \
  --auto-cleanup
```

## 10. Git 与 Gitea 备份状态

当前项目已使用 Git 管理，并已推送到 Gitea：

```text
http://192.168.31.5:5002/admin/Media_Depth.git
```

当前备份策略：

- 提交源码、脚本、说明文档和小样例。
- 不提交 checkpoints。
- 不提交 `.pth`、`.pt`、`.safetensors`、`.onnx`、`.engine` 等模型权重。
- 不提交运行结果目录。
- 不提交 zip、视频、PDF、安装程序等大文件。

## 11. 当前结论

截至 2026-05-20，当前系统状态是：

- V1 可以顺利运行。
- V2 可以顺利运行。
- V3/DA3 可以顺利运行。
- PLY 点云导出可以顺利运行。
- `Depth-Anything-3-main-待处理` 已改名为 `Depth-Anything-V3-main`。
- Gitea 备份可用，且未把权重和大文件提交进去。