长序列与离线渲染

🎥 离线渲染流程（`demo_render/batch_demo.py`）

当你的序列对于交互式 viser 查看器而言过长时，请使用此流程——例如上文中精选的室内漫游。demo_render/batch_demo.py 是一体化的离线入口：给它一个视频或一个图像文件夹，它就会运行模型推理，并用一条命令生成一个无头（headless）的点云穿越 MP4。它与 demo.py 共享相同的 PyTorch / FlashInfer / 检查点技术栈。

对于受限于较小显存或 GPU 资源的用户，你也可以参考以下实现：https://github.com/ureeey/lingbot-map-rtx4060-8g/commit/eeee84a89cc97c1e39b736b46df4ee315275700b

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

渲染 Python 依赖

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

render 会引入 open3d>=0.19 和 pyyaml（核心的 numpy<2 约束来自基础的 lingbot-map 安装）。此流程中的天空掩膜使用 onnxruntime-gpu 进行批量分割；如果你尚未安装 CPU 版的 onnxruntime，请安装它：

pip install onnxruntime-gpu

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

--index-url https://pypi.org/simple 可绕过任何可能会提供 PyPI 占位 wheel（导入时会抛出 ImportError）的内部镜像。 NVIDIA Kaolin 不为 PyTorch 2.9.x 发布预编译 wheel——如果你出于其他原因使用 2.9，请从源码构建 Kaolin（pip install --no-build-isolation git+https://github.com/NVIDIAGameWorks/kaolin.git，需要本地 CUDA toolkit）。对于其他 torch/CUDA 组合，请参见 NVIDIA Kaolin installation。

ffmpeg

sudo apt install ffmpeg    # or: brew install ffmpeg

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 下载示例视频。

    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 缓存。`window_size` 计数的是 KV 缓存槽位，而非实际帧数——前 `num_scale_frames`（=8）个槽位存放 scale 帧，其余 `128 − 8 = 120` 个槽位存放关键帧。因此当 `keyframe_interval = 13` 时，一个窗口覆盖 `8 + 120 × 13 = 1568` 个实际帧。
`--keyframe_interval 13`	仅将每第 13 帧缓存为关键帧。非关键帧仍会输出逐帧预测，但不会增大 KV 缓存
`--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 的右上角标记一个 `<i> / <N> Frames` 计数器。
`--save_predictions`	在 MP4 旁边持久化逐帧的 NPZ 文件。便于检查，或日后用不同的相机/叠加层设置重新渲染。

相机路径（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 帧进行插值。

注意：当 --config 加载一个 YAML 预设时，传入任意一个塑造片段的 CLI 参数（--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`	各场景的成功/时长摘要

🎥 离线渲染流程（demo_render/batch_demo.py）​

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

渲染 Python 依赖​

Kaolin​

ffmpeg​

CUDA 扩展​

实例演示 — 长室内漫游（约 25 000 帧，13 分钟）​

相机路径（YAML）​

YAML 结构​

可用模式​

单镜头 YAML 示例​

输出文件​