LingBot-Map 流式 3D 重建实战指南：Geometric Context Transformer 的安装、交互式 Demo 与离线渲染全流程

<output_article>

LingBot-Map 流式 3D 重建实战指南：Geometric Context Transformer 的安装、推理与离线渲染全流程

LingBot-Map 是一个前馈式（feed-forward）3D 基础模型，面向流式 3D 重建场景：只需输入一段连续的 RGB 视频或图像序列，即可在线输出相机位姿、深度与三维点云。本文以仓库根目录 README.md 为主体脉络，结合 demo.py、lingbot_map/models/gct_stream.py、lingbot_map/models/gct_stream_window.py 与 demo_render/batch_demo.py 等源码实现，系统讲解从环境安装、模型下载、交互式 Demo 到长序列离线渲染的完整使用方案，以及 KV 缓存、关键帧、窗口拼接对齐等底层原理。读完本文，你将能够独立完成一个上万帧室内/户外视频的流式重建与电影级点云漫游视频渲染。

项目定位与核心特性

LingBot-Map（Geometric Context Transformer for Streaming 3D Reconstruction）是 Robbyant 团队发布的流式重建方法。根据 README.md 的说明，其核心特性集中在三点：

• Geometric Context Transformer：通过 anchor context（尺度锚定帧上下文）、pose-reference window（位姿参考窗口）与 trajectory memory（轨迹记忆），在单一流式框架内统一了坐标定标（coordinate grounding）、稠密几何线索（dense geometric cues）与长距离漂移修正（long-range drift correction）；
• 高效流式推理：采用前馈式架构 + paged KV cache attention，在 518×378 分辨率下以约 20 FPS 的帧率稳定处理超过 10,000 帧的长序列；
• 领先的重建精度：在与流式方法及迭代优化方法的公开基准对比中表现更优。

此外，仓库还随附了一套覆盖 KITTI、Oxford Spires、VBR、Droid-W、TUM、7-Scenes、ETH3D、Tanks and Temples、NRGBD 的评估基准（见 benchmark/），以及开箱即用的示例场景与离线渲染管线。

仓库结构速览

在开始之前，先对仓库关键路径建立整体认知：

路径	作用
demo.py	交互式流式推理入口（viser 浏览器查看器）
lingbot_map/	核心模型包：aggregator/、heads/、layers/、models/、vis/ 等
demo_render/batch_demo.py	长序列离线推理 + 点云漫游视频渲染的一体化入口
demo_render/config/	渲染场景预设（default.yaml、indoor.yaml、outdoor_drive.yaml）
benchmark/	评估基准：prepare → run → evaluate 三阶段流水线
example/	开箱即用的示例场景（courthouse / university / loop）

环境安装

README.md 提供了完整的安装步骤，共 5 步。

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

PyTorch 2.8.0 是推荐版本，因为离线渲染所依赖的 NVIDIA Kaolin 提供了 torch-2.8.0_cu128 的预编译 wheel。如果只用 demo.py，也可使用更新版本的 PyTorch，但此时批量渲染需要从源码编译 Kaolin。其他 CUDA 版本可参考 PyTorch 官方安装指引自行选择匹配的版本。

3. 安装 lingbot-map 本体

pip install -e .

从 pyproject.toml 可以看到基础依赖为 Pillow、huggingface_hub、einops、safetensors、opencv-python、tqdm、scipy，Python 版本要求 ≥ 3.10。

4. 安装 FlashInfer（推荐）

FlashInfer 提供 paged KV cache attention，是流式推理高效运行的关键后端。它是一个纯 Python 包，首次使用时 JIT 编译 CUDA kernel，因此单个 wheel 可跨 CUDA/PyTorch 版本使用：

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

--index-url https://pypi.org/simple 仅在默认 pip 源是内部镜像且缺少 flashinfer-python 时需要。可选地，可安装 CUDA 专属 JIT 缓存加速首次使用：pip install flashinfer-jit-cache -f https://flashinfer.ai/whl/cu128/flashinfer-jit-cache/。 若未安装 FlashInfer，模型会自动回退到 PyTorch 原生 SDPA 注意力后端（配合 --use_sdpa 显式指定）。

5. 可视化依赖（可选）

pip install -e ".[vis]"

该 extra 依赖包含 viser>=0.2.23、trimesh、matplotlib、onnxruntime、requests（见 pyproject.toml）。

模型下载

模型权重发布在 HuggingFace 与 ModelScope 上，共有两个 checkpoint：

模型名	说明
lingbot-map	平衡型 checkpoint（论文、基准与离线 Demo 默认使用），在短序列与长序列之间取得均衡表现
lingbot-map-stage1	Stage-1 训练 checkpoint，可加载到 VGGT 模型上进行双向推理（c2w）

下载后将 .pt 文件路径记录备用，后续所有命令都会用到 --model_path /path/to/lingbot-map.pt。

快速开始

安装并下载权重后，一条命令即可启动首个场景的交互式重建：

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

该命令会启动基于 viser 的浏览器交互查看器（默认地址 http://localhost:8080），边推理边可视化相机轨迹与重建点云。

交互式 Demo（demo.py）详解

自带示例场景

仓库在 example/ 下提供了三个可直接运行的示例场景：

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

# University 场景
python demo.py --model_path /path/to/lingbot-map.pt \
    --image_folder example/university --mask_sky

# Loop 场景（回环闭合轨迹）
python demo.py --model_path /path/to/lingbot-map.pt \
    --image_folder example/loop

其中 example/loop 特意设计为回环（loop closure）轨迹，用于演示模型在轨迹闭合处的位姿一致性与漂移校正能力；courthouse 与 university 则分别代表室内与室外场景。

从 Droid-W 数据的动态演示

如需在更具挑战性的动态序列上体验，可从 HuggingFace 的 robbyant/lingbot-map-demo 数据集下载演示视频帧，然后执行（开启天空分割、相机头 4 次优化迭代、每 2 帧取 1 帧输入）：

python demo.py \
    --image_folder /path/to/dynamic \
    --model_path /path/to/lingbot-map.pt \
    --camera_num_iterations 4 \
    --mask_sky \
    --stride 2

--stride 2 表示每 2 帧采样 1 帧作为输入，降低序列密度以适配快速运动数据。

流式推理与关键帧间隔（--keyframe_interval）

长序列（超过 320 帧）推理时，KV cache 内存与模型训练时的 RoPE 位置范围是核心约束。README 明确指出：模型在 320 视角上使用 video RoPE 训练，当 KV cache 存储超过 320 个视角时性能会下降。--keyframe_interval 通过只保留每第 N 帧作为关键帧来压缩 KV cache 内存——非关键帧依然产生完整预测，但不会写入 KV cache。

在 demo.py 中，当 --keyframe_interval 未显式指定时会自动计算：流式模式下若帧数 num_frames > 320，自动取 ceil(num_frames / 320)（见 demo.py 第 480-488 行）。对应底层实现位于 lingbot_map/models/gct_stream.py 的 inference_streaming：非关键帧前调用 _set_skip_append(True)，使注意力层"attend 到 [cached_kv + current_kv] 但不把当前帧写入缓存"，随后恢复标志位。

推理范围说明：模型默认不做状态重置（state resetting），因此最大推理范围受训练数据中可见的最长距离约束；超出后需要状态重置。若观察到位姿坍缩（pose collapse），切换到窗口模式 --mode windowed——多数情况下单独调节 --keyframe_interval 即可，其余窗口参数保持默认。

窗口化推理（超长序列，>3000 帧）

当序列超过约 3000 帧时，推荐使用窗口化推理，每个窗口拥有独立的 KV cache 并按需重叠：

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

demo.py 会把 --video_path 的视频按目标 --fps 抽帧保存到 <视频名>_frames/ 目录后再送入模型（见 demo.py 的 load_images）。窗口模式下 window_size 统计的是 KV cache 槽位（关键帧数）而非实际帧数，实际覆盖帧数为 scale_frames + (window_size - scale_frames) × keyframe_interval。

天空分割（--mask_sky）

天空分割用 ONNX 天空分割模型滤除重建点云中的天空点，显著提升室外场景的视觉效果。

环境准备：

# 安装 onnxruntime（必需）
pip install onnxruntime        # CPU 版
# 或
pip install onnxruntime-gpu    # GPU 版（大图像集更快）

默认情况下，根目录的 demo.py 以当前工作目录下的 skyseg.onnx 作为天空分割模型路径；若该文件缺失，首次运行会自动从 HuggingFace 下载。若下载失败或未生成常规文件，天空分割会以 RuntimeError 终止并提示模型路径、下载地址与手动设置指引——绝不会在未遮罩天空的情况下静默继续。

手动恢复（保持默认路径）：

wget -O skyseg.onnx 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

使用显式模型路径：

python demo.py --model_path /path/to/checkpoint.pt \
    --image_folder /path/to/images/ --mask_sky \
    --sky_model /absolute/path/to/skyseg.onnx

天空掩码会缓存到 <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/

从源码看，掩码处理实现在 lingbot_map/vis/sky_segmentation.py：模型输入统一缩放到 320×320，按 ImageNet 均值/方差归一化后推理，输出分数图再映射为 8-bit 掩码，并对缓存目录写入 .skyseg_cache_version 版本戳以保证缓存一致性。

可视化选项

参数	默认值	说明
--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 保持输出在 GPU）；
• --num_scale_frames 2：将双向尺度帧数从默认 8 降到 2，缩小初始尺度估计阶段的激活峰值。

从 lingbot_map/models/gct_stream.py 的实现看，inference_streaming 支持"逐帧切片再搬到模型设备"的方式，配合 output_device=torch.device('cpu') 使 GPU 峰值显存维持在 O(scale) 或 O(1) 帧量级，而非整个序列——这是超长序列不 OOM 的关键设计。

加速推理：降低相机头的迭代精化步数，用少量位姿精度换取墙钟速度：

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

--camera_num_iterations 默认值为 4；设为 1 会跳过相机头中的 3 次精化 pass（并将相机头 KV cache 缩小 4×）。

torch.compile 加速：README 的 News 中推荐 python demo.py --compile ... 验证加速效果。--compile 会对聚合器中的 frame_blocks、DINOv2 块及全局块的 attn_pre/ffn_residual/proj 等热点模块应用 torch.compile(mode="reduce-overhead")，并配合 CUDA graph 预热（约增加 30~60 秒预热时间，流式模式下约快 5 FPS）。注意 --compile 仅对流式模式生效，且与 expandable_segments 分配器设置存在兼容性约束（详见 demo.py 顶部注释）。

流式推理的源码级原理

从 lingbot_map/models/gct_stream.py 可以清晰看到 GCTStream.inference_streaming 的两阶段设计：

1. Phase 1（尺度估计）：前 num_scale_frames（默认 8）帧作为 scale frames 一次性送入模型，通过 scale token 在彼此之间进行双向注意力，建立全局尺度与坐标基准；
2. Phase 2（逐帧流式）：剩余帧逐帧进入模型，聚合器与相机头均以因果注意力 + KV cache 方式增量处理，每帧产生 pose_enc、depth、depth_conf、world_points、world_points_conf 等预测。

关键帧模式下，非关键帧通过 _set_skip_append 机制"attend 后即丢弃"，将 KV cache 内存增长压缩约 1/keyframe_interval。同时 frame_type（0=scale、1=keyframe、2=non-keyframe）与 is_keyframe 会随预测一同输出，供可视化与下游拼接使用。

窗口化实现位于 lingbot_map/models/gct_stream_window.py 的 inference_windowed：每个窗口独立清理 KV cache、执行"scale 双向 + 流式因果"两阶段，随后通过 _align_and_stitch_windows 进行跨窗口对齐——以两窗口重叠区域中同时为关键帧的帧为锚点，估计相似变换（尺度 s、旋转 R、平移 t），用深度中值比估计尺度，再将所有窗口统一到第一个窗口坐标系后按重叠去重拼接。该文件还实现了基于光流的动态关键帧选择（flow_threshold > 0）：用当前帧深度与两帧位姿反投影计算平均像素位移，位移超过阈值或连续非关键帧数超过 max_non_keyframe_gap 时强制设为关键帧。

离线渲染流水线（demo_render/batch_demo.py）

交互式 viser 查看器不适合超长序列（如 25,000 帧、13 分钟的室内漫游）。此时应使用 demo_render/batch_demo.py：它把"模型推理 + 无头点云漫游 MP4 渲染"合并为一条命令，与 demo.py 共享同一套 PyTorch / FlashInfer / checkpoint 栈。

安装（在主安装基础上扩展）

1. 渲染 Python 依赖

pip install -e ".[vis,render]"

render extra 引入 open3d>=0.19 与 pyyaml。该管线中的天空分割使用 onnxruntime-gpu 与动态批处理的 skyseg_batch.onnx（发布在 robbyant/lingbot-map 模型仓库）：

pip install onnxruntime-gpu
wget -O skyseg_batch.onnx \
  https://huggingface.co/robbyant/lingbot-map/resolve/main/skyseg_batch.onnx

离线渲染器在配置路径缺失时会自动下载 skyseg_batch.onnx；demo_render/batch_demo.py 用 --skyseg_model_path /absolute/path/to/skyseg_batch.onnx 指定，独立的 demo_render/rgbd_scan_render.py 则用 --sky_model 或 YAML 中的 preprocess.sky_model。根目录 demo.py 仍使用单图版 skyseg.onnx。

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

Kaolin 没有 PyTorch 2.9.x 的预编译 wheel，若使用 2.9 需从源码构建（需要本地 CUDA 工具链）。

3. ffmpeg

sudo apt install ffmpeg    # 或：brew install ffmpeg

4. CUDA 扩展（首次运行前必须编译）

cd demo_render/render_cuda_ext && python setup.py build_ext --inplace && cd ../..

这会就地编译 voxel_morton_ext 与 frustum_cull_ext（见 demo_render/render_cuda_ext/setup.py），二者被 rgbd_render 用于 GPU 体素化与视锥剔除。

工作示例：长室内漫游（约 25,000 帧 / 13 分钟）

从 HuggingFace 的 robbyant/lingbot-map-demo 下载示例视频后执行：

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 \
    --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 = 10，一个窗口覆盖 8 + 120 × 10 = 1208 个实际帧
--keyframe_interval 10	只把每第 10 帧缓存为关键帧；非关键帧仍产出逐帧预测但不增长 KV cache
--overlap_keyframes 8	相邻窗口共享 8 个关键帧上下文，内部解析为 max(num_scale_frames, 8 × keyframe_interval) = 80 个实际帧的重叠；keyframe_interval > 1 时推荐设置，以保持跨窗口位姿对齐稳定
--config demo_render/config/indoor.yaml	用室内预设（短深度、更贴近的跟随相机）作为渲染/场景/相机/叠加默认值；用户显式传入的 CLI 参数仍会覆盖 YAML 值
--sky_mask_dir / --sky_mask_visualization_dir	将天空掩码与其并排可视化持久化到磁盘，后续重跑直接复用而不重复 ONNX 分割
--camera_vis default	在渲染视频上叠加轨迹线 + 近期帧点云
--keyframes_only_points	仅把关键帧深度反投影进点云；非关键帧仍贡献轨迹/视锥叠加。超长序列下保持点云稀疏
--frame_tag --frame_tag_position top_right	在 MP4 右上角盖章 <i> / <N> Frames 计数
--save_predictions	将逐帧 NPZ 与 MP4 一同持久化，便于后续用不同相机/叠加设置重渲染

注：README 中该示例的窗口覆盖估算以 keyframe_interval = 13 为例计算（8 + 120 × 13 = 1568 帧）；实际命令使用 --keyframe_interval 10，对应的覆盖帧数为 8 + 120 × 10 = 1208。核心在于理解"窗口槽位 × 关键帧间隔"的换算关系。

快速模式与 Demo 复现：将 keyframe_interval = 10 替换为 image_stride = 10 可加快渲染速度；再取消 demo_render/config/indoor.yaml 中 camera follow 段的注释并把 birdeye 范围设为 [2000, 2500]，即可复现官方演示中的室内飞越效果。

工作示例：户外驾驶场景

python demo_render/batch_demo.py \
    --video_path /data/demo_videos/drive_frames.mp4 \
    --output_folder /data/outputs/drive/ \
    --model_path /path/to/lingbot-map.pt \
    --config demo_render/config/outdoor_drive.yaml \
    --mode windowed --window_size 128 \
    --max_non_keyframe_gap 100 --overlap_keyframes 8 \
    --image_stride 1 \
    --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

与室内漫游相比的差异：

参数	作用
--config demo_render/config/outdoor_drive.yaml	户外预设：开启天空分割、更深的渲染范围（max_depth: 250），并针对车辆轨迹调校了跟随相机 + 结尾俯瞰揭示
--image_stride 1	使用每一帧视频；长或高帧率驾驶视频可增大该值做子采样
--max_non_keyframe_gap 100	连续非关键帧的上限，超过即强制设为关键帧；仅在基于光流的关键帧选择（--flow_threshold > 0）下生效，默认固定间隔模式下无作用

其余参数（--mode windowed --window_size 128、--overlap_keyframes 8、天空掩码缓存、叠加层、--save_predictions）与室内示例完全一致。

工作示例：LingBot-World 场景

该管线同样可直接重建世界模型 LingBot-World 生成的视频（下载 lingbo_world_frames.mp4、lingbo_world2_frames.mp4 示例）：

python demo_render/batch_demo.py \
    --video_path /data/demo_videos/lingbo_world_frames.mp4 \
    --output_folder /data/outputs/lingbo_world/ \
    --model_path /path/to/lingbot-map.pt \
    --config demo_render/config/outdoor_drive.yaml \
    --mode windowed --window_size 128 \
    --max_non_keyframe_gap 100 --overlap_keyframes 8 \
    --image_stride 1 \
    --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

第二个片段只需替换 --video_path、--output_folder（如需隔离缓存掩码再替换 --sky_mask_dir / --sky_mask_visualization_dir）。其余所有参数与户外驾驶场景一致。

相机路径（YAML）

虚拟相机路径由 --config 指向的 YAML 预设中的 camera.segments 列表描述，编辑 YAML 即可设计专属镜头，无需改动 CLI。内置预设位于 demo_render/config/：default.yaml、indoor.yaml、outdoor_drive.yaml，复制一份后编辑 camera: 块即可。

YAML 结构：

camera:
  fov: 60.0          # 相机视场角（度）
  transition: 30     # 相邻 segment 之间混合的帧数
  segments:
    - mode: follow            # 跟随输入轨迹的追踪相机
      frames: [0, 1500]       # 该 segment 覆盖的渲染帧范围（-1 = 结尾）
      back_offset: 0.3        # 位于输入相机后方多远（场景尺度比例）
      up_offset: 0.08         # 在输入相机之上抬高多少
      look_offset: 0.4        # lookat 目标指向前方多远
      smooth_window: 30       # 轨迹平滑窗口（帧）
    - mode: birdeye           # 升空俯瞰整个场景
      frames: [1500, 1800]
      reveal_height_mult: 2.5 # 俯瞰高度 = 场景尺度 × 该系数
    - mode: follow            # 回落至追踪相机
      frames: [1800, -1]
      back_offset: 0.3
      up_offset: 0.08
      look_offset: 0.4

transition 控制相邻 segment 间混合的帧数；frames: [0, -1] 表示"整个序列"。

可用模式：

mode	行为	可调字段
follow	追踪相机以平滑偏移跟随输入轨迹，最适合漫游镜头	back_offset、up_offset、look_offset、smooth_window、scale_frames
birdeye	俯瞰整个场景，适合英雄/总览镜头	reveal_height_mult
static	固定 eye + lookat，从 segment 起始帧自动推导	—
pivot	固定 eye，lookat 沿轨迹扫过	—

单镜头 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: 下按顺序列出多个 segment，相邻 segment 用 transition 帧插值过渡。

注意：当 --config 加载 YAML 预设时，若在命令行传入任何镜头整形参数（--camera_mode、--back_offset、--up_offset、--look_offset、--smooth_window、--follow_scale_frames、--birdeye_start、--birdeye_duration、--reveal_height_mult），会丢弃 YAML 中的 segments 并改用这些参数重建相机路径。要保持完全 YAML 驱动，请勿在命令行传入上述任一参数。

输出文件

对给定输出名（如 <scene> 或 <video_name>）：

文件	说明
<name>_pointcloud.mp4	渲染出的点云漫游视频
<name>_pointcloud_rgb.mp4	原始 RGB 帧编码为视频
<name>_pointcloud_config.yaml	本次运行的完整配置快照
batch_results.json	逐场景成功 / 耗时汇总

附带评估基准（benchmark）

仓库随附一套完整评估基准（见 benchmark/README.md），采用 prepare → run → evaluate 三阶段流水线（可选 report 生成），默认使用 lingbot-map.pt：

python prepare.py  --config configs/oxford.yaml
python run.py      --config configs/oxford.yaml
python evaluate.py --config configs/oxford.yaml
# 可选：生成报告
python report.py --workspace /path/to/workspace

已支持的基准确认包括 ETH3D、7-Scenes、Neural RGB-D、Oxford Spires（数据需先用 preprocess/oxford.py 准备）、KITTI、VBR、DROID-W、TUM RGB-D、Tanks and Temples。评估覆盖三类指标：轨迹（ATE / RPE-trans / RPE-rot）、位姿 AUC（AUC@3/5/15/30，支持 macro/micro 聚合）与点云（accuracy / completeness / chamfer / precision / recall / F1）。配置采用"基准确认 → 数据集覆盖 → 方法覆盖"三层 YAML 合并机制，牛津场景的官方轨迹可视化示例见 benchmark/assets/traj/。

许可证与引用

本项目以 Apache License 2.0 发布（见 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}
}

小结

LingBot-Map 把"坐标定标、稠密几何线索、长距离漂移校正"统一进一个前馈流式框架：短序列用 demo.py 交互式流式推理即可，长序列（数千到数万帧）则切换到 --mode windowed 窗口化推理并配合 --keyframe_interval 控制 KV cache 增长；需要输出电影级漫游视频时，用 demo_render/batch_demo.py 一条命令完成推理与渲染。理解"窗口槽位 = 关键帧数"、尺度帧与关键帧的换算关系、以及跨窗口相似变换对齐这三条主线，就能在任意分辨率与长度的序列上稳定复现高质量的流式 3D 重建结果。 </output_article>