跳到主要内容

流式三维重建

🎬 交互式演示（demo.py）​

运行 demo.py，通过基于浏览器的 viser 查看器（默认 http://localhost:8080）进行交互式 3D 可视化。

试用示例场景​

example/ 包含四个可直接运行的示例场景：

# courthouse 场景
python demo.py --model_path /path/to/lingbot-map-long.pt \
    --image_folder example/courthouse --mask_sky
# University 场景
python demo.py --model_path /path/to/lingbot-map-long.pt \
    --image_folder example/university --mask_sky
# Loop 场景（回环闭合轨迹）
python demo.py --model_path /path/to/lingbot-map-long.pt \
    --image_folder example/loop
# 带天空掩膜的 Oxford 场景（室外、大规模场景）
python demo.py --model_path /path/to/lingbot-map-long.pt \
    --image_folder example/oxford --mask_sky

🎯 精选：室内漫游（约 25 000 帧，13 分钟）​

该序列对于交互式 viser 查看器而言过长——此片段使用 离线渲染流程 渲染。完整命令请参见该章节。

带关键帧间隔的流式处理​

使用 --keyframe_interval 仅将每第 N 帧保留为关键帧，从而减少 KV 缓存内存。非关键帧仍会产生预测，但不会被存入缓存。这对于超过 320 帧的长序列很有用。模型使用 320 个视角上的 video RoPE 进行训练；KV 缓存超过 320 个视角时性能可能下降，关键帧策略可支持更长序列的推理。

数据集： 从 Hugging Face 上的 robbyant/lingbot-map-demo 下载演示序列。

在上述数据集的 travel 序列上运行的示例（开启天空掩膜、4 次相机优化迭代、每 2 帧设一个关键帧）：

python demo.py \
    --image_folder /path/to/lingbot-map-demo/travel/ \
    --model_path /path/to/lingbot-map-long.pt \
    --mask_sky \
    --camera_num_iterations 4 \
    --keyframe_interval 2

关于推理范围的说明。 默认推理不执行状态重置，因此最大范围受限于训练数据中的最长距离。超过该距离后需要进行状态重置。如果出现位姿崩溃，请切换到窗口模式（--mode windowed）。多数情况下只需调整 --keyframe_interval，其余窗口参数可保持默认值。

窗口化推理（适用于长序列，>3000 帧）​

python demo.py --model_path /path/to/lingbot-map-long.pt \
    --video_path video.mp4 --fps 10 \
    --mode windowed --window_size 128 --overlap_keyframes 16 --keyframe_interval 2

天空掩膜​

天空掩膜使用一个 ONNX 天空分割模型，从重建的点云中过滤掉天空点，从而提升室外场景的可视化质量。

设置：

# 安装 onnxruntime（必需）
pip install onnxruntime        # CPU
# 或
pip install onnxruntime-gpu    # GPU（处理大量图像时更快）

天空分割模型（skyseg.onnx）将在首次使用时从 HuggingFace 自动下载。

用法：

python demo.py --model_path /path/to/checkpoint.pt \
    --image_folder /path/to/images/ --mask_sky

天空掩膜会缓存在 <image_folder>_sky_masks/ 中，因此后续运行会跳过重新生成。你也可以用 --sky_mask_dir 指定自定义缓存目录，或用 --sky_mask_visualization_dir 保存并排的掩膜可视化结果：

python demo.py --model_path /path/to/checkpoint.pt \
    --image_folder /path/to/images/ --mask_sky \
    --sky_mask_dir /path/to/cached_masks/ \
    --sky_mask_visualization_dir /path/to/mask_viz/

可视化选项​

参数默认值描述
--port8080Viser 查看器端口
--conf_threshold1.5用于过滤低置信度点的可见性阈值
--point_size0.00001点云的点大小
--downsample_factor10点云显示的空间下采样系数

性能与内存​

不使用 FlashInfer（SDPA 回退）​

python demo.py --model_path /path/to/checkpoint.pt \
    --image_folder /path/to/images/ --use_sdpa

在有限的 GPU 内存上运行​

如果你遇到内存不足的问题，请尝试以下一项（或两项）：

  • --offload_to_cpu — 在推理期间将逐帧预测卸载到 CPU（默认开启；仅在内存充裕时才使用 --no-offload_to_cpu）。
  • --num_scale_frames 2 — 将双向 scale 帧的数量从默认的 8 降低到 2，从而缩减初始 scale 阶段的激活峰值。

更快的推理​

降低相机头中迭代细化步骤的数量，以少量位姿精度换取更快的实际运行时间：

python demo.py --model_path /path/to/checkpoint.pt \
    --image_folder /path/to/images/ --camera_num_iterations 1

--camera_num_iterations 默认为 4；将其设为 1 会跳过相机头中的三次细化过程（并将其 KV 缓存缩小 4 倍）。