https://github.com/user-attachments/assets/fe39e095-af2c-4ec9-b68d-a8ba97e505ab ### 🗺️ 认识 LingBot-Map！我们构建了一个用于流式 3D 重建的前馈 3D 基础模型！ 🏗️🌍 LingBot-Map 主要侧重于： - **几何上下文 Transformer**：在架构上通过锚点上下文、位姿参考窗口和轨迹记忆，在单个流式框架内统一了坐标对齐、密集几何线索和远程漂移校正。 - **高效流式推理**：采用具有分页 KV cache 注意力机制的前馈架构，在超过 10,000 帧的长序列中，能够以 518×378 分辨率实现稳定的约 20 FPS 推理。 - **最先进的重建**：在多个基准测试上，与现有的流式和基于迭代优化的方法相比，均展现出卓越的性能。 ## 📑 目录

点击展开

- [📰 新闻](#-news) - [📋 待办事项](#-todo) - [⚙️ 安装说明](#️-installation) - [📦 模型下载](#-model-download) - [🚀 快速开始](#-quick-start) - [🎬 交互式演示 (`demo.py`)](#-interactive-demo-demopy) - [尝试示例场景](#try-the-example-scenes) - [带关键帧间隔的流式推理](#streaming-with-keyframe-interval) - [窗口化推理（适用于长序列，>3000 帧）](#windowed-inference-for-long-sequences-3000-frames) - [天空遮罩](#sky-masking) - [可视化选项](#visualization-options) - [性能与内存](#performance--memory) - [🎥 离线渲染流水线 (`demo_render/batch_demo.py`)](#-offline-rendering-pipeline-demo_renderbatch_demopy) - [📜 License](#-license) - [📖 引用](#-citation) - [✨ 致谢](#-acknowledgments)

## 📰 新闻 - **2026-05-25** — 📊 **评估基准已发布**。我们发布了 KITTI 和 Oxford Spires 的评估脚本 — 具体流水线请参见 [benchmark/](benchmark/)，并在评估前运行 [`preprocess/oxford.py`](preprocess/oxford.py) 来准备 Oxford Spires 数据。 - **2026-04-29** — 📹 **长视频演示已发布**。我们发布了一个使用离线渲染流水线渲染的超长视频示例（约 25,000 帧，13 分钟的室内漫游） — 命令、参数说明及渲染输出请参见[实际示例](#worked-example--long-indoor-walkthrough-25-000-frames-13-minutes)。 - **2026-04-27** — 🚀 **LingBot-Map 已加速**。拉取最新的 `main` 分支并运行 `python demo.py --compile ...` 或 `python gct_profile.py --backend flashinfer --dtype bf16 --compile` 以在你的硬件上进行验证。 - **2026-04-24** — 修复了 FlashInfer KV cache 中当 `--keyframe_interval > 1` 时会默默缓存非关键帧的错误。**现在，当运行超过 320 帧时，你应该会看到更好的位姿和重建质量**。 ## 📋 待办事项 - ✅ 发布评估基准 - ✅ Oxford Spires 数据集 - ✅ KITTI 数据集 - ✅ VBR 数据集 - ✅ Droid-W 数据集 - ✅ TUM-D 数据集 - ✅ 7-scenes 数据集 - ✅ ETH3D 数据集 - ✅ Tanks and Temples 数据集 - ✅ NRGBD 数据集 - ✅ 发布演示脚本 - ✅ 室内长视频演示 ([精选室内漫游](#-featured-indoor-walkthrough-25-000-frames-13-minutes)) - ✅ 室外长视频演示 - ✅ LingBot-World 演示 - ✅ 航拍长视频演示 ## ⚙️ 安装说明 **1. 创建 conda 环境** ``` conda create -n lingbot-map python=3.10 -y conda activate lingbot-map ``` **2. 安装 PyTorch (CUDA 12.8)** ``` pip install torch==2.8.0 torchvision==0.23.0 --index-url https://download.pytorch.org/whl/cu128 ``` **3. 安装 lingbot-map** ``` pip install -e . ``` **4. 安装 FlashInfer（推荐）** FlashInfer 为高效的流式推理提供分页 KV cache 注意力机制。它是一个纯 Python 包，在首次使用时会 JIT 编译 CUDA 内核，因此单个 wheel 文件即可兼容不同的 CUDA/PyTorch 版本： ``` pip install --index-url https://pypi.org/simple flashinfer-python ``` **5. 可视化依赖（可选）** ``` pip install -e ".[vis]" ``` ## 📦 模型下载 | 模型名称 | Huggingface 仓库 | ModelScope 仓库 | 描述 | | :--- | :--- | :--- | :--- | | lingbot-map-long | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | 更适合长序列和大规模场景（推荐）。 | | lingbot-map | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | 均衡的 checkpoint — 在长序列和短序列之间折中各项综合性能。 | | lingbot-map-stage1 | [robbyant/lingbot-map](https://huggingface.co/robbyant/lingbot-map) | [Robbyant/lingbot-map](https://www.modelscope.cn/models/Robbyant/lingbot-map) | lingbot-map 的第一阶段训练 checkpoint — 可加载到 VGGT 模型中用于双向推理 (c2w)。 | ## 🚀 快速开始 安装完成后，使用单个命令运行你的第一个场景： ``` python demo.py --model_path /path/to/lingbot-map-long.pt \ --image_folder example/courthouse --mask_sky ``` 这将在 `http://localhost:8080` 启动一个交互式的 [viser](https://github.com/nerfstudio-project/viser) 查看器。请查看下方的[交互式演示](#-interactive-demo-demopy)以获取完整的场景和参数列表，或者跳转到[离线渲染流水线](#-offline-rendering-pipeline-demo_renderbatch_demopy)进行长序列的批量渲染。 ## 🎬 交互式演示 (`demo.py`) 运行 `demo.py`，通过基于浏览器的 [viser](https://github.com/nerfstudio-project/viser) 查看器进行交互式 3D 可视化（默认地址 `http://localhost:8080`）。 ### 尝试示例场景 我们在 `example/` 中提供了四个可以直接运行的示例场景： ``` # courthouse 场景 python demo.py --model_path /path/to/lingbot-map-long.pt \ --image_folder example/courthouse --mask_sky ``` https://github.com/user-attachments/assets/aa10f7ab-8024-43c7-92f8-d56159ec85c8 ``` # University 场景 python demo.py --model_path /path/to/lingbot-map-long.pt \ --image_folder example/university --mask_sky ``` https://github.com/user-attachments/assets/212a1744-6ff5-4ccf-9bd4-728608248b57 ``` # Loop 场景（loop closure trajectory） python demo.py --model_path /path/to/lingbot-map-long.pt \ --image_folder example/loop ``` https://github.com/user-attachments/assets/5ae0a292-b081-40c6-838c-b7c1a0538d75 ``` # 带 sky masking 的 Oxford 场景（outdoor，large scale 场景） python demo.py --model_path /path/to/lingbot-map-long.pt \ --image_folder example/oxford --mask_sky ``` https://github.com/user-attachments/assets/6b8daa95-9ed4-40b2-9902-7435779b886d #### 🎯 精选内容：室内漫游（约 25,000 帧，13 分钟） *序列对于交互式 viser 查看器来说太长了 — 此片段是使用[离线渲染流水线](#-offline-rendering-pipeline-demo_renderbatch_demopy)渲染的。完整命令请参见该章节。* 我们将在后续提供更多示例。 ### 带关键帧间隔的流式推理 使用 `--keyframe_interval` 仅将每 N 帧保留为关键帧，从而减少 KV cache 内存。非关键帧仍然会生成预测，但不会存储在缓存中。这对于超过 320 帧的长序列非常有用（我们在 320 个视角上使用 video RoPE 进行训练，因此当 KV cache 存储超过 320 个视角时，性能会下降。使用关键帧策略允许在更长的序列上进行推理。）。 **数据集：** 从 Hugging Face 上的 [robbyant/lingbot-map-demo](https://huggingface.co/datasets/robbyant/lingbot-map-demo/tree/main) 下载演示序列。 在上面数据集的 `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 ``` https://github.com/user-attachments/assets/d350b590-d036-4363-af8c-7af3918338ef ### 窗口化推理（适用于长序列，>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（required） pip install onnxruntime # CPU # 或 pip install onnxruntime-gpu # GPU (faster for large image sets) ``` 天空分割模型 (`skyseg.onnx`) 将在首次使用时从 [HuggingFace](https://huggingface.co/JianyuanWang/skyseg/resolve/main/skyseg.onnx) 自动下载。 **用法：** ``` python demo.py --model_path /path/to/checkpoint.pt \ --image_folder /path/to/images/ --mask_sky ``` 天空掩码将缓存在 `_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/ ``` ### 可视化选项 | 参数 | 默认值 | 描述 | |:---|:---|:---| | `--port` | `8080` | Viser 查看器端口 | | `--conf_threshold` | `1.5` | 用于过滤低置信度点的可见性阈值 | | `--point_size` | `0.00001` | 点云点大小 | | `--downsample_factor` | `10` | 用于点云显示的空间下采样 | ### 性能与内存 #### 不使用 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`** — 将双向缩放帧的数量从默认的 8 减少到 2，从而缩减初始缩放阶段的激活内存峰值。 #### 更快的推理 降低相机头中迭代细化步骤的数量，以牺牲少量的位姿精度来换取实际运行速度： ``` python demo.py --model_path /path/to/checkpoint.pt \ --image_folder /path/to/images/ --camera_num_iterations 1 ``` `--camera_num_iterations` 默认为 `4`；将其设置为 `1` 会跳过相机头中的三个细化过程（并将其 KV cache 缩小 4 倍）。 ## 🎥 离线渲染流水线 (`demo_render/batch_demo.py`) 当你的序列对于交互式 viser 查看器来说太长时，请使用此流水线 — 例如[上方的精选室内漫游](#-featured-indoor-walkthrough-25-000-frames-13-minutes)。`demo_render/batch_demo.py` 是一体化的离线入口点：只需为其提供视频或图像文件夹，它就运行模型推理，并通过单个命令生成无头的点云漫游 MP4 视频。它与 `demo.py` 共享相同的 PyTorch / FlashInfer / checkpoint 技术栈。 如果你的 VRAM 或 GPU 使用受限，也可以参考以下实现：https://github.com/ureeey/lingbot-map-rtx4060-8g/commit/eeee84a89cc97c1e39b736b46df4ee315275700b ### 安装说明（在主安装基础上扩展） **1. 渲染 Python 依赖** ``` pip install -e ".[vis,render]" ``` `render` 会引入 `open3d>=0.19` 和 `pyyaml`（核心的 `numpy<2` 限制来自基础的 `lingbot-map` 安装）。此流水线中的天空遮罩使用 `onnxruntime-gpu` 进行批量分割；如果你还没有 CPU 版本的 `onnxruntime`，请安装它： ``` pip install onnxruntime-gpu ``` **2. Kaolin** — 匹配上文推荐的 PyTorch 2.8.0 + CUDA 12.8： ``` pip install --index-url https://pypi.org/simple \ kaolin -f https://nvidia-kaolin.s3.us-east-2.amazonaws.com/torch-2.8.0_cu128.html ``` **3. ffmpeg** ``` sudo apt install ffmpeg # or: brew install ffmpeg ``` **4. CUDA 扩展**（首次运行前必装） ``` cd demo_render/render_cuda_ext && python setup.py build_ext --inplace && cd ../.. ``` 这将在本地构建 `voxel_morton_ext` `frustum_cull_ext` — 它们都会被 `rgbd_render` 导入，用于 GPU 体素化和视锥剔除。 ### 实际示例 — 长室内漫游（约 25,000 帧，13 分钟） **数据集：** 从 Hugging Face 上的 [robbyant/lingbot-map-demo](https://huggingface.co/datasets/robbyant/lingbot-map-demo/tree/main) 下载示例视频。 ``` python demo_render/batch_demo.py \ --video_path /data/demo_videos/indoor_travel.MP4 \ --output_folder /data/outputs/indoor_travel/ \ --model_path /path/to/lingbot-map.pt \ --config demo_render/config/indoor.yaml \ --mode windowed --window_size 128 \ --keyframe_interval 13 --overlap_keyframes 8 \ --sky_mask_dir /data/outputs/sky_masks \ --sky_mask_visualization_dir /data/outputs/sky_mask_viz \ --camera_vis default --keyframes_only_points \ --frame_tag --frame_tag_position top_right \ --save_predictions ``` 参数详细说明： | 参数 | 使用原因 | |---|---| | `--mode windowed --window_size 128` | 一旦序列超过约 320 帧的 RoPE 训练范围，就需要进行滑动窗口推理；每个窗口都会重置 KV cache。**`window_size` 计算的是 KV cache 槽位，而不是实际帧数** — 前 `num_scale_frames` (=8) 个槽位用于容纳缩放帧，其余 `128 − 8 = 120` 个槽位用于容纳关键帧。因此，当 `keyframe_interval = 13` 时，一个窗口可覆盖 `8 + 120 × 13 = 1568` 个实际帧。 | | `--keyframe_interval 13` | 仅将每 13 帧缓存为关键帧。非关键帧仍然会发出逐帧预测，但不会增加 KV cache| | `--overlap_keyframes 8` | 相邻窗口共享 8 个关键帧的上下文，在内部转换为 `max(num_scale_frames, 8 × keyframe_interval) = 8 × 13 = 104` 个实际帧的重叠。当 `keyframe_interval > 1` 时推荐使用，以保持跨窗口的位姿对齐稳定。 | | `--config demo_render/config/indoor.yaml` | 从室内预设（较短景深、更紧凑的跟随相机）中读取渲染/场景/相机/覆盖层的默认参数。用户显式传递的任何 CLI 参数仍将覆盖 YAML 中的值。 | | `--sky_mask_dir` / `--sky_mask_visualization_dir` | 将天空遮罩及其并排可视化结果持久化到磁盘，以便后续重新运行时直接复用它们，而不是重新运行 ONNX 分割。（渲染流水线仅在使用天空遮罩时才会调用它们 — 即由 YAML 预设或通过 `--mask_sky` 开启）。 | | `--camera_vis default` | 在渲染的视频上覆盖轨迹尾迹 + 最近帧的点云。 | | `--keyframes_only_points` | 仅将关键帧深度投影到点云中；非关键帧仍将其位姿贡献给轨迹/视锥覆盖图。对于极长的序列，可以保持点云稀疏。 | | `--frame_tag --frame_tag_position top_right` | 在 MP4 的右上角加盖 ` / Frames` 帧计数器。 | | `--save_predictions` | 将逐帧 NPZ 与 MP4 一起保存。对于后续检查或使用不同的相机/覆盖设置重新渲染非常有用。 | ### 相机轨迹 (YAML) 虚拟相机路径由通过 `--config` 传入的 YAML 预设中的 `camera.segments` 列表描述。编辑 YAML 即可设计你自己的镜头 — 无需触碰 CLI 参数。 内置预设位于 `demo_render/config/` 中：`default.yaml`, `indoor.yaml`, `indoor_overview.yaml`, `outdoor_large.yaml`, `outdoor_large_overview.yaml`, `surrounding.yaml`, `lingbo_world.yaml`。复制其中一个并编辑 `camera:` 块即可。 #### YAML 结构 ``` camera: fov: 60.0 # camera field of view in degrees transition: 30 # frames blended between adjacent segments segments: - mode: follow # chase cam following the input trajectory frames: [0, 1500] # rendered-frame range this segment covers (-1 = end) back_offset: 0.3 # how far behind the input camera (fraction of scene scale) up_offset: 0.08 # vertical lift above the input camera look_offset: 0.4 # how far ahead the lookat target points smooth_window: 30 # trajectory smoothing window in frames - mode: birdeye # rise up for a top-down reveal of the whole scene frames: [1500, 1800] reveal_height_mult: 2.5 # birdeye height = scene scale × this factor - mode: follow # drop back into chase cam frames: [1800, -1] back_offset: 0.3 up_offset: 0.08 look_offset: 0.4 ``` `transition` 控制相邻片段之间进行混合的帧数；`frames: [0, -1]` 表示“整个序列”。 #### 可用模式 | `mode` | 行为 | 可调字段 | |---|---|---| | `follow` | 跟随相机以平滑的偏移量追踪输入轨迹。最适合漫游的电影级选项。 | `back_offset`, `up_offset`, `look_offset`, `smooth_window`, `scale_frames` | | `birdeye` | 整个场景的俯视图展示。适合主视觉 / 概览镜头。 | `reveal_height_mult` | | `static` | 固定视点 + 注视点，根据片段的起始帧自动推导。 | — | | `pivot` | 固定视点，注视点沿轨迹扫掠。 | — | #### 单镜头 YAML 示例 **纯跟随**（最常见）： ``` camera: fov: 60.0 segments: - mode: follow frames: [0, -1] back_offset: 0.3 up_offset: 0.08 look_offset: 0.4 smooth_window: 30 ``` **完全俯视**（适合概览 / 主视觉镜头）： ``` camera: fov: 60.0 segments: - mode: birdeye frames: [0, -1] reveal_height_mult: 2.5 ``` **带俯视插入的跟随**：只需在 `segments:` 下按顺序列出多个片段 — 相邻片段将使用 `transition` 帧进行插值。 ### 输出文件 对于给定的输出名称（例如 `` 或 ``）： | 文件 | 描述 | |------|-------------| | `_pointcloud.mp4` | 渲染后的点云漫游视频 | | `_pointcloud_rgb.mp4` | 编码为视频的原始 RGB 帧 | | `_pointcloud_config.yaml` | 本次运行的完整配置快照 | | `batch_results.json` | 每个场景的成功/时长总结 | ## 📜 License 本项目基于 Apache License 2.0 协议发布。详情请参阅 [LICENSE](LICENSE.txt) 文件。 ## 📖 引用 ``` @article{chen2026geometric, title={Geometric Context Transformer for Streaming 3D Reconstruction}, author={Chen, Lin-Zhuo and Gao, Jian and Chen, Yihang and Cheng, Ka Leong and Sun, Yipengjing and Hu, Liangxiao and Xue, Nan and Zhu, Xing and Shen, Yujun and Yao, Yao and Xu, Yinghao}, journal={arXiv preprint arXiv:2604.14141}, year={2026} } ``` ## ✨ 致谢 我们感谢 Shangzhan Zhang、Jianyuan Wang、Yudong Jin、Christian Rupprecht 和 Xun Cao 提供的有益讨论与支持。 本工作基于以下优秀的开源项目构建： - [VGGT](https://github.com/facebookresearch/vggt) - [DINOv2](https://github.com/facebookresearch/dinov2) - [Flashinfer](https://github.com/flashinfer-ai/flashinfer)