离线渲染与评测基准

模块职责

把交互式重建结果批量渲染成视频和可检查产物

demo_render/batch_demo.py 面向“离线跑一批序列”的场景：不启动交互 UI，按目录或列表读取图像序列 / 视频帧，调用 LingBot-Map 的流式重建推理流程，然后把重建结果、相机轨迹和渲染视角输出到磁盘。

适合这些任务：

• 批量生成论文、项目主页、对比实验用的重建视频；
• 跑长序列，例如几千到几万帧的室内外 walkthrough；
• 在固定参数下重复渲染多个场景，避免手动操作 demo.py；
• 保存中间结果，便于后续评测、可视化或失败排查。

离线渲染流程本身不改变模型结构，核心仍然使用 LingBot-Map 的流式推理能力，包括：

• anchor context；
• pose-reference window；
• trajectory memory；
• KV cache attention；
• 可选的 FlashInfer / SDPA 后端；
• 可选的 --compile 加速。

---

给 KITTI、Oxford Spires 提供统一评测入口

benchmark/ 目录用于复现实验指标。它把数据集读取、模型推理、轨迹 / 几何结果对齐、指标计算和日志保存串起来，减少手写评测脚本带来的差异。

当前基准重点覆盖：

• KITTI；
• Oxford Spires。

其中 Oxford Spires 在评测前需要先走预处理入口：

bash📋 复制
python preprocess/oxford.py --help

预处理的目标是把原始数据整理成评测脚本能直接读取的布局，例如图像序列、时间戳、相机参数、位姿或对齐所需的元数据。

---

关键代码/接口说明

demo_render/batch_demo.py：批处理渲染主入口

典型调用方式：

bash📋 复制
python demo_render/batch_demo.py --help

建议先看本地版本的 --help，因为渲染参数在开发过程中可能会增减。通常需要关注以下几类参数。

参数类别	作用	典型场景
输入路径	指向视频、图像目录或场景列表	一次渲染单个 walkthrough，或批量渲染多个场景
输出路径	保存重建结果、轨迹、日志、渲染视频	后续做评测、归档、对比视频
checkpoint / model	指定 LingBot-Map 权重	本地权重、HuggingFace 下载权重、ModelScope 下载权重
device / dtype	控制 GPU 与精度	cuda + bf16 通常用于高吞吐离线任务
attention backend	选择 KV cache attention 后端	长序列优先考虑 FlashInfer
keyframe interval	控制关键帧间隔	长视频降低计算量，但过大可能影响轨迹和几何质量
window / chunk	控制长序列分块或窗口推理	超过数千帧时避免显存持续增长
sky mask	对室外天空区域做掩码	KITTI、Oxford Spires 等室外数据常用
render options	控制渲染分辨率、帧率、相机路径	输出展示视频或定量检查视频

内部流程可以理解为：

text📋 复制
读取输入场景
  ↓
加载模型权重和推理配置
  ↓
按时间顺序流式送入图像帧
  ↓
更新轨迹记忆、参考窗口和重建状态
  ↓
保存重建结果 / 相机轨迹 / 中间日志
  ↓
按指定视角离线渲染视频或图片序列

批处理脚本通常会把“单个场景失败”和“整个批次失败”区分开。实际跑大批数据时，建议每个场景单独输出日志，方便重跑失败项。

---

benchmark/：数据集评测脚本集合

benchmark/ 下的脚本负责把模型输出转换成数据集指标。常见步骤如下：

text📋 复制
读取数据集配置
  ↓
检查图像、相机参数、时间戳、真值轨迹是否存在
  ↓
运行或读取 LingBot-Map 推理结果
  ↓
把预测轨迹与真值坐标系对齐
  ↓
计算轨迹误差、重建误差或数据集指定指标
  ↓
写入 metrics、日志和可视化结果

先查看可用脚本：

bash📋 复制
find benchmark -maxdepth 2 -type f \( -name "*.py" -o -name "*.sh" \) | sort

再查看具体脚本参数，例如：

bash📋 复制
python benchmark/<script_name>.py --help

不同数据集的评测入口可能要求不同字段。不要混用 KITTI 和 Oxford Spires 的目录结构，也不要把预处理前后的 Oxford 数据混在同一个根目录下。

---

preprocess/oxford.py：Oxford Spires 预处理入口

Oxford Spires 数据在评测前需要标准化。预处理入口：

bash📋 复制
python preprocess/oxford.py --help

预处理通常负责：

• 扫描原始数据目录；
• 提取或链接图像帧；
• 整理相机内参、外参或标定文件；
• 生成时间戳索引；
• 转换评测脚本需要的轨迹格式；
• 写出统一的 processed 数据目录。

建议把原始数据和预处理结果分开：

text📋 复制
datasets/
  oxford_spires_raw/
    ...
  oxford_spires_processed/
    ...

这样可以反复清理 processed 目录，而不会误删原始数据。

---

使用示例（可运行）

1. 检查离线渲染和评测入口是否存在

在项目根目录执行：

bash📋 复制
python demo_render/batch_demo.py --help
python preprocess/oxford.py --help

find benchmark -maxdepth 2 -type f \( -name "*.py" -o -name "*.sh" \) | sort

如果这些命令能正常输出帮助信息，说明离线渲染、Oxford 预处理和 benchmark 脚本入口已经可用。

---

2. 渲染一个本地图像序列

假设已经准备好：

text📋 复制
data/example_scene/
  images/
    000000.jpg
    000001.jpg
    000002.jpg
    ...

并且模型权重放在：

text📋 复制
checkpoints/lingbot-map/

可以使用下面的方式启动离线渲染。参数名以本地 --help 为准，如果当前版本的参数名不同，按帮助信息替换即可。

bash📋 复制
export SCENE_DIR=data/example_scene
export CKPT_DIR=checkpoints/lingbot-map
export OUT_DIR=outputs/render/example_scene

mkdir -p "$OUT_DIR"

python demo_render/batch_demo.py \
  --input "$SCENE_DIR" \
  --checkpoint "$CKPT_DIR" \
  --output "$OUT_DIR" \
  --backend flashinfer \
  --dtype bf16 \
  --compile

输出目录一般用于保存：

text📋 复制
outputs/render/example_scene/
  logs/
  trajectory/
  reconstruction/
  render/

具体文件名以脚本实际输出为准。

如果机器没有安装 FlashInfer，可以先用默认后端或 SDPA 后端跑通：

bash📋 复制
python demo_render/batch_demo.py \
  --input "$SCENE_DIR" \
  --checkpoint "$CKPT_DIR" \
  --output "$OUT_DIR" \
  --backend sdpa \
  --dtype bf16

---

3. 长视频按关键帧间隔离线渲染

长视频或超长图像序列可以适当增大关键帧间隔，减少计算量：

bash📋 复制
export SCENE_DIR=data/long_walkthrough
export CKPT_DIR=checkpoints/lingbot-map
export OUT_DIR=outputs/render/long_walkthrough

mkdir -p "$OUT_DIR"

python demo_render/batch_demo.py \
  --input "$SCENE_DIR" \
  --checkpoint "$CKPT_DIR" \
  --output "$OUT_DIR" \
  --backend flashinfer \
  --dtype bf16 \
  --compile \
  --keyframe_interval 5

经验上，keyframe_interval 越大，速度越快，但局部几何和轨迹稳定性可能下降。长序列正式出片前，建议先截取 300～1000 帧做参数试跑。

---

4. 预处理 Oxford Spires

假设原始数据在：

text📋 复制
datasets/oxford_spires_raw/

预处理结果写到：

text📋 复制
datasets/oxford_spires_processed/

执行：

bash📋 复制
export OXFORD_RAW=datasets/oxford_spires_raw
export OXFORD_OUT=datasets/oxford_spires_processed

mkdir -p "$OXFORD_OUT"

python preprocess/oxford.py \
  --input "$OXFORD_RAW" \
  --output "$OXFORD_OUT"

预处理完成后，再运行 Oxford Spires 对应的 benchmark 脚本：

bash📋 复制
find benchmark -maxdepth 2 -type f | grep -i oxford

查看入口参数：

bash📋 复制
python benchmark/<oxford_eval_script>.py --help

然后按脚本要求传入 processed 数据路径、模型权重和输出目录。

---

5. 运行 KITTI 评测

假设 KITTI 已整理到：

text📋 复制
datasets/kitti/

先找到 KITTI 评测入口：

bash📋 复制
find benchmark -maxdepth 2 -type f | grep -i kitti

查看参数：

bash📋 复制
python benchmark/<kitti_eval_script>.py --help

一个常见的评测调用形态如下，实际参数名以脚本帮助为准：

bash📋 复制
export KITTI_ROOT=datasets/kitti
export CKPT_DIR=checkpoints/lingbot-map
export EVAL_OUT=outputs/benchmark/kitti

mkdir -p "$EVAL_OUT"

python benchmark/<kitti_eval_script>.py \
  --data_root "$KITTI_ROOT" \
  --checkpoint "$CKPT_DIR" \
  --output "$EVAL_OUT" \
  --backend flashinfer \
  --dtype bf16

评测完成后，通常需要检查：

bash📋 复制
find "$EVAL_OUT" -maxdepth 3 -type f | sort

重点看：

• metrics 文件；
• 每个序列的日志；
• 失败序列列表；
• 轨迹对齐后的可视化结果；
• 渲染或重建中间产物。

---

注意边界

长序列优先关注显存和 KV cache 后端

LingBot-Map 支持长序列流式推理，但离线渲染时仍然会受到显存、分辨率、窗口长度和后端实现影响。

建议顺序：

1. 先用较短片段确认参数；
2. 长序列优先尝试 flashinfer 后端；
3. 显存不足时降低分辨率、增大 keyframe_interval，或启用窗口化 / 分块推理；
4. 不要直接用最高分辨率和全帧关键帧跑几万帧，失败后排查成本很高。

---

keyframe_interval 会影响速度和质量

keyframe_interval > 1 可以提升吞吐，但也会减少进入关键帧缓存和参考窗口的信息量。

适合：

• 长视频预览；
• 快速出片；
• 对局部细节要求不高的批量任务。

不适合：

• 精评测；
• 强转弯、快速运动、强遮挡序列；
• 需要高精度轨迹的实验。

做 benchmark 时，应该固定该参数并写入日志，否则不同实验之间不可比。

---

室外数据建议检查天空区域处理

KITTI 和 Oxford Spires 这类室外数据经常包含大面积天空。天空区域缺少稳定几何约束，可能影响重建和可视化。

如果脚本提供 sky mask 相关参数，建议：

• 在室外序列启用；
• 在室内序列关闭或确认不会误伤墙面 / 天花板；
• 保留 mask 可视化结果，方便排查异常。

---

评测前确认坐标系和时间戳

评测脚本通常需要把预测结果和数据集真值对齐。以下问题会直接导致指标异常：

• 图像帧顺序错乱；
• 时间戳不连续或不匹配；
• 相机内参用错；
• 左右相机混用；
• 预处理后路径仍指向旧数据；
• 预测轨迹和真值轨迹坐标系未对齐。

如果某个序列指标明显离群，优先检查数据读取和对齐日志，而不是直接调整模型参数。

---

Oxford Spires 需要先预处理再评测

不要直接把 Oxford Spires 原始目录传给 benchmark，除非脚本明确支持原始格式。推荐固定流程：

text📋 复制
raw data
  ↓ preprocess/oxford.py
processed data
  ↓ benchmark
metrics / logs

预处理输出目录建议一次只对应一个版本的原始数据和一个版本的预处理脚本。更新代码后如果指标变化明显，应重新跑预处理并记录 commit。

---

离线渲染输出不等于评测结果

demo_render/batch_demo.py 主要服务可视化和批量出片；benchmark/ 才是指标计算入口。

可以用离线渲染结果辅助检查：

• 轨迹是否突然漂移；
• 重建是否断层；
• 天空或动态物体是否带来噪声；
• 长序列后半段是否质量下降。

但正式报告指标时，应使用 benchmark 目录下的数据集评测脚本，并保存完整命令、配置和日志。