LingBot-Map 地图生成项目

项目概述

LingBot-Map 是面向流式三维重建的前馈式三维基础模型，可在单次前向传播中完成相机位姿估计、稠密深度预测与点云重建。模型针对长序列场景设计，在 518×378 分辨率下支持超过 10000 帧的稳定推理，速度约 20 FPS。

核心技术

几何上下文 Transformer

模型在统一的流式框架内融合三类几何线索：

• Anchor Context：在每个推理窗口内提供坐标锚点，建立尺度与全局参考系。
• Pose-Reference Window：对相机位姿进行迭代精修，缓解累计漂移。
• Trajectory Memory：跨窗口传递关键帧轨迹信息，维持长序列一致性。

高效流式推理

采用分页 KV 缓存注意力机制，将非关键帧预测与缓存存储解耦。配合关键帧间隔采样策略，可在显存受限条件下处理远超训练长度的视频流。

环境安装

# 创建 Conda 环境
conda create -n lingbot-map python=3.10 -y
conda activate lingbot-map

# 安装 PyTorch（CUDA 12.8）
pip install torch==2.8.0 torchvision==0.23.0 \
    --index-url https://download.pytorch.org/whl/cu128

# 安装项目本体
pip install -e .

# 推荐安装 FlashInfer（分页 KV 缓存注意力加速）
pip install --index-url https://pypi.org/simple flashinfer-python

FlashInfer 在首次使用时即时编译 CUDA 算子，未安装时模型自动回退到 PyTorch 原生 SDPA（--use_sdpa）。

模型下载

仓库提供两个权重，均发布于 HuggingFace 与 ModelScope：

• lingbot-map：论文与基准测试所用的平衡版本，适用于长短序列。
• lingbot-map-stage1：阶段一权重，可加载进 VGGT 框架进行双向（c2w）推理。

快速上手

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

脚本启动基于 viser 的浏览器交互查看器，默认监听 http://localhost:8080。

交互式 Demo

demo.py 内置三个示例场景：courthouse、university、loop，开箱即可运行。

关键帧间隔：使用 --keyframe_interval 控制每 N 帧保留一次关键帧，降低显存占用。模型默认根据帧数自动调整该参数。

窗口推理（>3000 帧长序列）：

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

天空掩膜：通过 --mask_sky 启用 ONNX 天空分割模型，过滤空中点云。默认从 HuggingFace 自动下载 skyseg.onnx，结果缓存于 <image_folder>_sky_masks/。

性能调优：

• --offload_to_cpu：将逐帧结果卸载至 CPU（默认开启）。
• --num_scale_frames 2：将双向缩放帧从 8 减至 2，降低激活峰值。
• --camera_num_iterations 1：将相机头迭代次数减为 1，KV 缓存缩小 4 倍。

离线渲染管线

demo_render/batch_demo.py 用于交互查看器无法处理的长序列（典型如约 25000 帧、13 分钟的室内漫游视频），可在无界面环境下生成点云漫游 MP4。

额外依赖包括 Kaolin（CUDA 12.8 + PyTorch 2.8.0 预编译包）、onnxruntime-gpu、ffmpeg 以及两个 CUDA 扩展（voxel_morton_ext、frustum_cull_ext）。

长序列室内漫游示例

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 10 --overlap_keyframes 8 \
    --camera_vis default --keyframes_only_points \
    --frame_tag --frame_tag_position top_right \
    --save_predictions

其中 window_size 表示 KV 缓存槽位数（而非实际帧数），减去缩放帧后剩余槽位存放关键帧；相邻窗口通过 overlap_keyframes 共享上下文以稳定跨窗口对齐。

相机轨迹

相机路径通过 YAML 配置文件中 camera.segments 列表描述，支持 follow、birdeye、static、pivot 四种模式。YAML 中可设置视场角、过渡帧数与各片段的偏移参数；通过命令行传递相机相关参数会覆盖 YAML 中的 segments 配置。

评测基准

项目内置 KITTI、Oxford Spires、VBR、Droid-W、TUM-D、7-scenes、ETH3D、Tanks and Temples、NRGBD 等数据集的评测脚本。使用前需通过 preprocess/oxford.py 预处理 Oxford Spires 数据。

许可证与引用

项目采用 Apache License 2.0。学术使用请引用 ECCV 2026 论文 Geometric Context Transformer for Streaming 3D Reconstruction，技术报告可引用 arXiv:2604.14141。