【DROID-W】WildGS-SLAM

DROID-W / WildGS-SLAM 项目梳理：输入、依赖、运行资源、耗时评估与可视化开启方式

1. 项目简介

DROID-W，也可以理解为 WildGS-SLAM 相关实现，是一个结合 DROID-SLAM 前端跟踪、度量深度估计、DINOv2 特征提取以及 3D Gaussian Splatting 建图的 SLAM / 重建系统。

整体流程可以粗略分为：

text 复制代码

RGB / Depth 数据输入
        ↓
度量深度估计 Metric3D / DPT2
        ↓
DINOv2 特征提取
        ↓
DROID 前端跟踪 + 局部 BA
        ↓
全局 BA
        ↓
轨迹补全
        ↓
3DGS 建图 / 渲染 / 可视化输出

2. 输入数据结构

2.1 数据目录格式

项目输入数据通常组织为如下结构：

text 复制代码

dataset/
├── rgb/          
│   └── 彩色图像 PNG / JPG
│
├── depth/        
│   └── 深度图 PNG / EXR / NPY，可选
│
└── mono_priors/
    ├── depths/   
    │   └── 预计算度量深度 {idx:05d}.npy
    │
    └── features/ 
        └── 预计算 DINOv2 特征 {idx:05d}.npy

其中：

目录	作用	是否必须
`rgb/`	输入彩色图像	必须
`depth/`	原始深度图，RGB-D 数据集常见	可选
`mono_priors/depths/`	单目度量深度先验	可选，但推荐
`mono_priors/features/`	DINOv2 图像特征	可选，但推荐

如果没有提前计算 mono_priors，系统通常会在运行阶段自动进行深度估计和特征提取。

3. 配置文件结构

DROID-W 使用 YAML 配置文件控制数据路径、相机参数、运行模式和建图参数。

3.1 三级 YAML 继承链

典型配置继承关系如下：

text 复制代码

configs/droid_w.yaml
    ↓
configs/Dynamic/TUM_RGBD/base.yaml
    ↓
configs/Dynamic/TUM_RGBD/freiburg3_walking_xyz.yaml

对应作用如下：

配置文件	作用
`configs/droid_w.yaml`	全局默认配置，约 171 行
`configs/Dynamic/TUM_RGBD/base.yaml`	TUM RGB-D 数据集公共配置
`configs/Dynamic/TUM_RGBD/freiburg3_walking_xyz.yaml`	具体场景配置

3.2 场景配置主要内容

每个具体场景的 YAML 通常会指定：

配置项	说明
`H, W`	图像高度、宽度
`fx, fy, cx, cy`	相机内参
`data_path`	数据集路径
`output_path`	输出路径
`crop / resize`	分辨率裁剪与缩放参数
`mapping.enable`	是否开启建图
`fast_mode`	是否使用快速模式

4. 预训练模型

运行前需要准备对应的预训练模型。

模型	作用	是否必须
`./pretrained/droid.pth`	DroidNet 主干网络权重	必须
`metric3d_vit_large`	默认度量深度模型	默认使用
`dpt2_*`	另一类度量深度模型	可选
`dinov2_reg_small_fine`	DINOv2 特征提取模型，384 维	默认使用

其中 droid.pth 是核心权重，如果缺失，DROID 前端无法正常运行。

5. Python 依赖梳理

5.1 主要 Python 包

类别	包	版本约束
深度学习框架	`torch`, `torchvision`, `torchaudio`	CUDA 11.8+
稀疏操作	`torch-scatter`	需匹配 torch 版本
注意力加速	`xformers`	需匹配 torch 版本
视觉处理	`opencv-python`	`==4.8.1.78`
特征提取	`timm`	`==0.9.10`
3D 点云	`open3d`	`==0.17.0`
点云格式	`plyfile`	`==0.8.1`
轨迹评估	`evo`	任意
几何 / 数学	`kornia`, `scipy`, `scikit-learn`	任意
可视化	`rerun-sdk`	`==0.15.1`
数值计算	`numpy`	`==1.26.4`，必须 `<2.0`

5.2 关键版本约束

这里最需要注意的是：

text 复制代码

numpy 必须 < 2.0

原因是：

text 复制代码

rerun-sdk 0.15.1 对 numpy 版本有限制

因此建议固定：

bash 复制代码

pip install numpy==1.26.4

否则可能会出现 rerun-sdk、open3d 或其他依赖之间的版本冲突。

6. 第三方子模块与编译产物

项目中包含多个需要编译或正确安装的第三方模块。

子模块	作用	编译产物
`thirdparty/lietorch`	SE(3) 李群位姿运算	`lietorch_backends.cpython-310-*.so`
`thirdparty/diff-gaussian-rasterization-w-pose`	3DGS 光栅化 + 位姿优化	CUDA `.so`
`thirdparty/simple-knn`	高斯致密化 KNN	CUDA `.so`
`thirdparty/depth_anything_v2`	度量深度估计 DPT2	Python 模块
`thirdparty/gaussian_splatting`	3DGS 渲染工具	Python 模块

其中 lietorch 是 DROID-SLAM 类系统中的关键依赖，负责 SE(3) 位姿相关计算。

7. 主项目 CUDA 扩展

DROID-W 主项目还需要编译自己的 CUDA / C++ 扩展。

核心扩展模块为：

text 复制代码

droid_backends

它通常由 setup.py 编译生成。

7.1 源文件功能

源文件	功能
`src/lib/droid.cpp`	C++ / Python 绑定入口
`src/lib/droid_kernels.cu`	位姿、深度优化，Eigen 稀疏 Cholesky BA
`src/lib/correlation_kernels.cu`	相关体积计算，主要用于光流 / 匹配
`src/lib/altcorr_kernel.cu`	替代相关核

其中 correlation_kernels.cu 或类似的 corr_index_kernel.cu 这类文件，主要负责 GPU 侧的相关性计算，不是可视化入口。

也就是说：

text 复制代码

corr_index_kernel.cu 不是运行可视化开关的位置

可视化一般由 Python 层、配置文件或 Rerun / Open3D / GUI 模块控制，而不是 CUDA kernel 控制。

8. GPU 与计算资源要求

8.1 GPU 要求

项目	要求
最低架构	`sm_75`，如 RTX 20xx / Quadro RTX
推荐架构	`sm_86+`，如 RTX 30xx / 40xx
本机 GPU	RTX 5060 Ti
本机架构	`sm_120`，Blackwell
CUDA 版本	11.8+，Blackwell 建议 CUDA 12.x
仅追踪显存	约 6--10 GB
追踪 + 建图显存	约 16--24 GB
追踪缓冲区	最多约 350 个关键帧

8.2 CPU 与内存要求

系统运行时通常会启动多个子进程：

text 复制代码

Tracker / Mapper / Backend

进程通信方式包括：

text 复制代码

mp.Pipe + mp.Queue

建议机器配置：

资源	建议
CPU	多核 CPU
内存	32GB+
GPU 显存	建图建议 16GB+
存储	根据序列和建图输出规模预留空间

9. 输出目录结构

每个序列运行完成后，通常会在输出目录中生成：

text 复制代码

Outputs/TUM_RGBD/{scene}/
├── cfg.yaml
├── events.out.tfevents.*
├── gt_poses.txt
├── mono_priors/
├── traj/
│   └── metrics_full_traj.txt
├── timer_summary.csv
├── video.npz
└── plots_final/

常见输出说明如下：

输出文件 / 目录	作用
`cfg.yaml`	当前运行实际使用的配置
`events.out.tfevents.*`	TensorBoard 日志
`gt_poses.txt`	Ground Truth 位姿
`mono_priors/`	单目深度和特征先验
`traj/`	轨迹输出与评估结果
`metrics_full_traj.txt`	轨迹精度指标
`timer_summary.csv`	各阶段耗时统计
`video.npz`	视频 / 跟踪结果缓存
`plots_final/`	最终可视化图表

10. 运行命令

激活环境：

bash 复制代码

conda activate droid-w

运行指定场景：

bash 复制代码

python run.py --config ./configs/Dynamic/TUM_RGBD/freiburg3_walking_xyz.yaml

输出路径一般为：

text 复制代码

Outputs/TUM_RGBD/{scene}/

轨迹精度指标可查看：

text 复制代码

Outputs/TUM_RGBD/{scene}/traj/metrics_full_traj.txt

11. 实测运行时间评估

以下是在 TUM RGB-D 数据集上，使用 RTX 5060 Ti 实测得到的运行时间。

11.1 各阶段耗时分解

序列	帧数	深度估计(s)	DINO特征(s)	追踪(s)	全局BA(s)	轨迹填充(s)	总计(s)
`walking_xyz`	858	26.9	6.5	94.9	26.7	28.7	183.7
`sitting_xyz`	1260	30.7	7.1	118.8	44.3	77.6	278.5
`sitting_rpy`	819	40.4	9.5	131.9	30.7	30.3	242.7
`walking_rpy`	908	45.6	11.3	147.0	39.3	33.6	276.8
`walking_halfsphere`	1065	46.1	11.1	154.2	102.9	38.4	352.7

11.2 各阶段平均吞吐率

阶段	平均帧率
度量深度估计 Metric3D	约 5 FPS
DINOv2 特征提取	约 21 FPS
追踪 / 前端 BA	约 6--10 FPS
全局 BA	取决于关键帧数
端到端系统	约 3--5 FPS

11.3 时间规律总结

从实测结果看，主要有几个规律：

现象	说明
追踪阶段最耗时	通常占总耗时约 50%
度量深度估计占比中等	约占 13--16%
DINOv2 特征提取占比较小	约占 3--4%
全局 BA 与序列长度、关键帧数相关	`walking_halfsphere` 的全局 BA 达到 102.9s
轨迹填充可能成为瓶颈	`sitting_xyz` 轨迹填充达到 77.6s

12. fast_mode 快速模式

项目中通常提供 fast_mode 参数，用于降低最终精化阶段迭代次数。

默认情况可能是：

text 复制代码

final refinement: 20000 iterations

开启 fast_mode 后可能降低为：

text 复制代码

final refinement: 3000 iterations

这会显著减少建图阶段耗时。

需要注意：

text 复制代码

fast_mode 主要在 mapping.enable: True 时有效

也就是说，如果只做 tracking，不做 mapping，fast_mode 的收益可能不明显。

13. 运行期间如何打开可视化

13.1 不建议从 `corr_index_kernel.cu` 打开可视化

如果你看到的是类似：

text 复制代码

corr_index_kernel.cu
correlation_kernels.cu
altcorr_kernel.cu

这类文件，它们主要是 CUDA kernel，用于 GPU 相关性计算、光流匹配或相关体积计算。

这些文件不负责 GUI 或可视化。

因此不要在这里找：

text 复制代码

show_gui
visualization
rerun
viewer

更合理的查找位置是：

text 复制代码

run.py
configs/*.yaml
src / droid / visualization / mapping 相关 Python 文件

13.2 推荐先搜索可视化配置项

在项目根目录执行：

bash 复制代码

grep -R "rerun\|viewer\|visual\|vis\|gui\|show" -n \
  run.py configs src droid thirdparty 2>/dev/null | head -100

如果项目有 Rerun 可视化，通常能搜到类似字段：

text 复制代码

rerun
use_rerun
enable_rerun
visualization
viewer
show_gui
vis

也可以单独查配置文件：

bash 复制代码

grep -R "rerun\|viewer\|visual\|show\|gui" -n configs 2>/dev/null

13.3 如果配置里有可视化开关

假设搜到类似配置：

yaml 复制代码

visualization:
  enable: false

rerun:
  enable: false

viewer:
  enable: false

可以改成：

yaml 复制代码

visualization:
  enable: true

rerun:
  enable: true

viewer:
  enable: true

然后重新运行：

bash 复制代码

python run.py --config ./configs/Dynamic/TUM_RGBD/freiburg3_walking_xyz.yaml

13.4 如果使用 Rerun 可视化

因为项目依赖中有：

text 复制代码

rerun-sdk == 0.15.1

所以运行期间可视化很可能通过 Rerun 实现。

可以先启动 Rerun viewer：

bash 复制代码

rerun

或者检查是否有 .rrd 输出文件：

bash 复制代码

find Outputs -name "*.rrd"

如果有 .rrd 文件，可以用：

bash 复制代码

rerun Outputs/TUM_RGBD/{scene}/xxx.rrd

如果代码里是 rr.spawn() 或 rr.init(..., spawn=True)，则运行时可能会自动打开 Rerun 窗口。

13.5 如果是服务器 / Docker 环境

如果在远程服务器、Docker 或无显示器环境下运行，直接打开 GUI 可能失败。

常见报错包括：

text 复制代码

cannot connect to display
GLFW error
X11 display not found

此时可以检查：

bash 复制代码

echo $DISPLAY

如果是 Docker，需要挂载 X11：

bash 复制代码

docker run -it \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix:rw \
  --gpus all \
  your_image

宿主机可能还需要：

bash 复制代码

xhost +local:docker

如果使用 Rerun，也可以考虑保存 .rrd 文件，之后在本地打开，而不是运行时直接弹窗。

14. 推荐调试顺序

如果目标是"运行期间看可视化"，建议按这个顺序排查：

text 复制代码

1. 不要改 corr_index_kernel.cu
2. 先 grep 项目中的 rerun / viewer / visual / gui / show
3. 找到 YAML 或 run.py 中的可视化开关
4. 打开 visualization / rerun / viewer 配置
5. 确认本机 DISPLAY 正常
6. 如果是 Docker，挂载 X11
7. 如果无法实时显示，保存 .rrd / plots / video.npz 后离线查看

最小排查命令：

bash 复制代码

grep -R "rerun\|viewer\|visual\|vis\|gui\|show" -n \
  run.py configs src droid thirdparty 2>/dev/null | head -100

15. 总结

DROID-W / WildGS-SLAM 项目可以看作是一个结合：

text 复制代码

DROID-SLAM 跟踪
+ 单目度量深度估计
+ DINOv2 图像特征
+ 全局 BA
+ 3D Gaussian Splatting 建图

的完整视觉 SLAM / 重建系统。

它的主要特点是：

方面	总结
输入	RGB 图像为核心，可结合深度图和单目先验
配置	使用多级 YAML 继承，便于不同场景复用
依赖	依赖较重，需要 torch、xformers、open3d、rerun、CUDA 扩展
编译	`lietorch`、`droid_backends`、3DGS 相关模块都需要正确编译
资源	建议 16GB+ 显存，32GB+ 内存
速度	端到端约 3--5 FPS
瓶颈	追踪、全局 BA、轨迹填充
可视化	通常在 Python / YAML / Rerun 层开启，不在 CUDA kernel 中开启

如果只是想快速跑通，建议先关闭复杂建图，只跑 tracking；如果要完整复现 WildGS-SLAM 效果，则需要保证度量深度、DINOv2 特征、全局 BA 和 3DGS 相关依赖都正常工作。

【DROID-W】WildGS-SLAM