LingBot-Map 教程：先跑短序列，再处理窗口和显存

LingBot-Map 用 Geometric Context Transformer 逐帧预测深度、世界坐标点和相机位姿。它维护几何上下文与 KV cache，并提供短序列浏览器查看器和长视频离线渲染两套入口。

1. 数据从图像到点云怎样流动

输入图像先预处理，初始尺度帧建立参考；后续帧按 streaming 或 windowed 模式更新上下文。模型输出深度、置信度、世界点和相机姿态。demo.py 把结果交给 Viser，默认地址为 http://localhost:8080。

长视频走 demo_render/batch_demo.py，还会涉及 ONNX 天空分割、GPU 点云渲染、Kaolin CUDA 扩展和 ffmpeg。它和最小 demo 的安装成本差别很大。

2. 按官方版本建立最小环境

conda create -n lingbot-map python=3.10 -y
conda activate lingbot-map
pip install torch==2.8.0 torchvision==0.23.0 \
  --index-url https://download.pytorch.org/whl/cu128
pip install -e .
pip install -e ".[vis]"

需要 FlashInfer 时再安装：

pip install --index-url https://pypi.org/simple flashinfer-python

FlashInfer 会在首次使用时 JIT 编译 CUDA kernel。没有它可用 --use_sdpa 回退到 PyTorch 原生注意力。模型 checkpoint 约 4.4GB，官方提供 Hugging Face 与 ModelScope 下载入口；不要把权重下载时间误算成推理延迟。

python demo.py \
  --model_path /path/to/lingbot-map.pt \
  --image_folder example/courthouse \
  --mask_sky

3. 长序列的关键不是只加帧

README 说明 video RoPE 用 320 views 训练，KV cache 持续保存超过该范围的帧时，质量会下降。keyframe_interval 只让每隔若干帧的关键帧进入缓存，非关键帧仍产生预测。超过约 3000 帧时可切到 windowed 模式，并用 overlap_keyframes 保留相邻窗口的上下文。

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

模型默认不做状态重置，推理距离还受训练数据最长距离约束。出现 pose collapse 时，官方建议先调整 keyframe_interval，仍不稳定再用 windowed 模式。它没有声明默认提供全局回环优化，测绘或机器人应用必须自行验证闭环漂移。

4. 显存、网络与输出权限

--offload_to_cpu 默认把逐帧预测移到 CPU；把 num_scale_frames 从 8 降到 2 可减少初始尺度阶段的峰值；把相机迭代从 4 降到 1 会少做三次 refinement。它们都会改变速度或质量，不能只记录“能跑”。

Viewer 端口、输入视频、天空 mask 缓存、逐帧 NPZ 与输出 MP4 都要纳入权限检查。带敏感图像时不要转发 8080 端口，也不要把数据集目录放到共享服务。

5. 与 VGGT 对比

Meta 的 VGGT接收一个到数百张图，一次前馈预测相机、深度、点图和跟踪。LingBot-Map 加入流式状态、分页 KV cache、关键帧和窗口重置，更关注连续长序列。

短批次、多任务几何预测可先评估 VGGT；需要连续视频和长序列状态管理时，LingBot-Map 的接口更贴合。

常见问题