【DROID-W】WildGS-SLAM

DROID-W / WildGS-SLAM 项目梳理输入、依赖、运行资源、耗时评估与可视化开启方式1. 项目简介DROID-W也可以理解为 WildGS-SLAM 相关实现是一个结合 DROID-SLAM 前端跟踪、度量深度估计、DINOv2 特征提取以及 3D Gaussian Splatting 建图的 SLAM / 重建系统。整体流程可以粗略分为RGB / Depth 数据输入 ↓ 度量深度估计 Metric3D / DPT2 ↓ DINOv2 特征提取 ↓ DROID 前端跟踪 局部 BA ↓ 全局 BA ↓ 轨迹补全 ↓ 3DGS 建图 / 渲染 / 可视化输出2. 输入数据结构2.1 数据目录格式项目输入数据通常组织为如下结构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 继承链典型配置继承关系如下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.yamlTUM 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.pthDroidNet 主干网络权重必须metric3d_vit_large默认度量深度模型默认使用dpt2_*另一类度量深度模型可选dinov2_reg_small_fineDINOv2 特征提取模型384 维默认使用其中droid.pth是核心权重如果缺失DROID 前端无法正常运行。5. Python 依赖梳理5.1 主要 Python 包类别包版本约束深度学习框架torch,torchvision,torchaudioCUDA 11.8稀疏操作torch-scatter需匹配 torch 版本注意力加速xformers需匹配 torch 版本视觉处理opencv-python4.8.1.78特征提取timm0.9.103D 点云open3d0.17.0点云格式plyfile0.8.1轨迹评估evo任意几何 / 数学kornia,scipy,scikit-learn任意可视化rerun-sdk0.15.1数值计算numpy1.26.4必须2.05.2 关键版本约束这里最需要注意的是numpy 必须 2.0原因是rerun-sdk 0.15.1 对 numpy 版本有限制因此建议固定pipinstallnumpy1.26.4否则可能会出现rerun-sdk、open3d或其他依赖之间的版本冲突。6. 第三方子模块与编译产物项目中包含多个需要编译或正确安装的第三方模块。子模块作用编译产物thirdparty/lietorchSE(3) 李群位姿运算lietorch_backends.cpython-310-*.sothirdparty/diff-gaussian-rasterization-w-pose3DGS 光栅化 位姿优化CUDA.sothirdparty/simple-knn高斯致密化 KNNCUDA.sothirdparty/depth_anything_v2度量深度估计 DPT2Python 模块thirdparty/gaussian_splatting3DGS 渲染工具Python 模块其中lietorch是 DROID-SLAM 类系统中的关键依赖负责 SE(3) 位姿相关计算。7. 主项目 CUDA 扩展DROID-W 主项目还需要编译自己的 CUDA / C 扩展。核心扩展模块为droid_backends它通常由setup.py编译生成。7.1 源文件功能源文件功能src/lib/droid.cppC / Python 绑定入口src/lib/droid_kernels.cu位姿、深度优化Eigen 稀疏 Cholesky BAsrc/lib/correlation_kernels.cu相关体积计算主要用于光流 / 匹配src/lib/altcorr_kernel.cu替代相关核其中correlation_kernels.cu或类似的corr_index_kernel.cu这类文件主要负责 GPU 侧的相关性计算不是可视化入口。也就是说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本机 GPURTX 5060 Ti本机架构sm_120BlackwellCUDA 版本11.8Blackwell 建议 CUDA 12.x仅追踪显存约 6–10 GB追踪 建图显存约 16–24 GB追踪缓冲区最多约 350 个关键帧8.2 CPU 与内存要求系统运行时通常会启动多个子进程Tracker / Mapper / Backend进程通信方式包括mp.Pipe mp.Queue建议机器配置资源建议CPU多核 CPU内存32GBGPU 显存建图建议 16GB存储根据序列和建图输出规模预留空间9. 输出目录结构每个序列运行完成后通常会在输出目录中生成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.txtGround Truth 位姿mono_priors/单目深度和特征先验traj/轨迹输出与评估结果metrics_full_traj.txt轨迹精度指标timer_summary.csv各阶段耗时统计video.npz视频 / 跟踪结果缓存plots_final/最终可视化图表10. 运行命令激活环境conda activate droid-w运行指定场景python run.py--config./configs/Dynamic/TUM_RGBD/freiburg3_walking_xyz.yaml输出路径一般为Outputs/TUM_RGBD/{scene}/轨迹精度指标可查看Outputs/TUM_RGBD/{scene}/traj/metrics_full_traj.txt11. 实测运行时间评估以下是在 TUM RGB-D 数据集上使用 RTX 5060 Ti 实测得到的运行时间。11.1 各阶段耗时分解序列帧数深度估计(s)DINO特征(s)追踪(s)全局BA(s)轨迹填充(s)总计(s)walking_xyz85826.96.594.926.728.7183.7sitting_xyz126030.77.1118.844.377.6278.5sitting_rpy81940.49.5131.930.730.3242.7walking_rpy90845.611.3147.039.333.6276.8walking_halfsphere106546.111.1154.2102.938.4352.711.2 各阶段平均吞吐率阶段平均帧率度量深度估计 Metric3D约 5 FPSDINOv2 特征提取约 21 FPS追踪 / 前端 BA约 6–10 FPS全局 BA取决于关键帧数端到端系统约 3–5 FPS11.3 时间规律总结从实测结果看主要有几个规律现象说明追踪阶段最耗时通常占总耗时约 50%度量深度估计占比中等约占 13–16%DINOv2 特征提取占比较小约占 3–4%全局 BA 与序列长度、关键帧数相关walking_halfsphere的全局 BA 达到 102.9s轨迹填充可能成为瓶颈sitting_xyz轨迹填充达到 77.6s12. fast_mode 快速模式项目中通常提供fast_mode参数用于降低最终精化阶段迭代次数。默认情况可能是final refinement: 20000 iterations开启fast_mode后可能降低为final refinement: 3000 iterations这会显著减少建图阶段耗时。需要注意fast_mode 主要在 mapping.enable: True 时有效也就是说如果只做 tracking不做 mappingfast_mode的收益可能不明显。13. 运行期间如何打开可视化13.1 不建议从corr_index_kernel.cu打开可视化如果你看到的是类似corr_index_kernel.cu correlation_kernels.cu altcorr_kernel.cu这类文件它们主要是 CUDA kernel用于 GPU 相关性计算、光流匹配或相关体积计算。这些文件不负责 GUI 或可视化。因此不要在这里找show_gui visualization rerun viewer更合理的查找位置是run.py configs/*.yaml src / droid / visualization / mapping 相关 Python 文件13.2 推荐先搜索可视化配置项在项目根目录执行grep-Rrerun\|viewer\|visual\|vis\|gui\|show-n\run.py configs src droid thirdparty2/dev/null|head-100如果项目有 Rerun 可视化通常能搜到类似字段rerun use_rerun enable_rerun visualization viewer show_gui vis也可以单独查配置文件grep-Rrerun\|viewer\|visual\|show\|gui-nconfigs2/dev/null13.3 如果配置里有可视化开关假设搜到类似配置visualization:enable:falsererun:enable:falseviewer:enable:false可以改成visualization:enable:truererun:enable:trueviewer:enable:true然后重新运行python run.py--config./configs/Dynamic/TUM_RGBD/freiburg3_walking_xyz.yaml13.4 如果使用 Rerun 可视化因为项目依赖中有rerun-sdk 0.15.1所以运行期间可视化很可能通过 Rerun 实现。可以先启动 Rerun viewerrerun或者检查是否有.rrd输出文件findOutputs-name*.rrd如果有.rrd文件可以用rerun Outputs/TUM_RGBD/{scene}/xxx.rrd如果代码里是rr.spawn()或rr.init(..., spawnTrue)则运行时可能会自动打开 Rerun 窗口。13.5 如果是服务器 / Docker 环境如果在远程服务器、Docker 或无显示器环境下运行直接打开 GUI 可能失败。常见报错包括cannot connect to display GLFW error X11 display not found此时可以检查echo$DISPLAY如果是 Docker需要挂载 X11dockerrun-it\-eDISPLAY$DISPLAY\-v/tmp/.X11-unix:/tmp/.X11-unix:rw\--gpusall\your_image宿主机可能还需要xhost local:docker如果使用 Rerun也可以考虑保存.rrd文件之后在本地打开而不是运行时直接弹窗。14. 推荐调试顺序如果目标是“运行期间看可视化”建议按这个顺序排查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 后离线查看最小排查命令grep-Rrerun\|viewer\|visual\|vis\|gui\|show-n\run.py configs src droid thirdparty2/dev/null|head-10015. 总结DROID-W / WildGS-SLAM 项目可以看作是一个结合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 相关依赖都正常工作。