模块拆解：可视化、天空遮罩与性能优化

模块职责

可视化、天空遮罩与性能优化 这一组功能主要服务于 demo.py 和离线渲染流程，解决三类问题：

1. 把流式重建结果看清楚

   • 控制点云显示密度、置信度过滤、相机轨迹、关键帧、窗口范围等可视化行为。
   • 适合调试重建质量、观察漂移、检查长序列中某一段的几何稳定性。

2. 避免天空区域污染三维点云

   • 对输入图像中的天空区域做分割遮罩。
   • 推理或显示时跳过天空像素对应的点，减少远距离错误点、漂浮点和伪平面。

3. 在不同硬件上跑得更快、更稳

   • 支持 FlashInfer 和 SDPA 注意力后端。
   • 支持 bf16、compile、窗口化推理、关键帧间隔等加速与省显存选项。
   • 面向长序列流式重建，例如几千帧到上万帧视频。

---

点云显示、天空过滤和推理后端的入口

LingBot-Map 的交互式流程主要通过：

bash📋 复制
python demo.py --help

查看完整参数。

性能测试和后端验证主要通过：

bash📋 复制
python gct_profile.py --help

README 中明确给出的性能验证命令是：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16 --compile

其中本模块相关的参数可以分成下面几类。

---

点云可视化参数：先过滤，再显示

点云可视化通常包含以下控制项。不同版本的 demo.py 参数名可能略有差异，实际以 python demo.py --help 为准。

功能	常见参数含义	适用场景
置信度阈值	过滤低置信度 3D 点	去掉漂浮点、边缘错误点
点大小	控制点云渲染时每个点的尺寸	稀疏点云可适当调大，密集点云应调小
最大显示点数	限制可视化中的点数量	长视频、显存或内存紧张时使用
是否显示相机轨迹	显示每帧或关键帧相机位姿	检查漂移、回环前后的轨迹变化
是否显示关键帧	只突出关键帧位置	调试 --keyframe_interval 的效果
窗口范围	只显示最近一段帧的点云	长序列中避免一次性渲染全部点

推荐调试顺序：

1. 先提高置信度阈值，确认主要结构是否稳定。
2. 再调点大小，观察墙面、地面、边缘是否连续。
3. 长视频不要一开始显示全量点云，优先使用窗口化显示。
4. 如果轨迹明显跳变，打开相机轨迹和关键帧显示。

---

天空遮罩：城市、户外场景建议开启

户外数据中，天空区域通常没有稳定的几何深度。若直接参与点云生成，常见问题包括：

• 天空位置生成大量远距离点；
• 楼顶边缘出现漂浮点；
• 远处区域被错误重建成墙面或平面；
• 点云包围盒被天空错误点拉大，影响观察和后处理。

天空遮罩的作用是：

text📋 复制
输入图像
  ↓
天空分割模型 / 天空 mask
  ↓
过滤天空像素
  ↓
只把非天空区域送入点云生成或可视化

适合开启天空遮罩的场景：

场景	是否建议开启
城市街景	建议开启
车载视频	建议开启
无人机户外视频	建议开启
室内房间	通常不需要
地下车库、隧道	通常不需要
夜间弱光户外	需要检查分割效果

天空遮罩不是重建质量的万能修复。如果天空分割模型把建筑、树冠、玻璃幕墙误判为天空，可能会删掉有效结构。调试时建议保存或显示 mask 结果，确认遮罩边界是否合理。

---

FlashInfer 与 SDPA：长序列优先选 FlashInfer

LingBot-Map 使用流式 Transformer 结构，长序列推理时注意力 KV cache 的效率很关键。

当前 README 中给出的建议是：

SDPA 后端已经修复长序列 KV cache 问题，但最佳性能仍推荐 FlashInfer 后端。

两个后端的使用建议如下。

后端	参数	适合场景
FlashInfer	--backend flashinfer	长视频、高 FPS、需要 paged KV cache 的场景
SDPA	--backend sdpa	环境更通用，不想额外安装 FlashInfer 时使用

性能测试命令：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16 --compile

对比 SDPA：

bash📋 复制
python gct_profile.py --backend sdpa --dtype bf16

如果你的环境无法安装 FlashInfer，可以先用 SDPA 跑通流程，再根据显卡、CUDA、PyTorch 版本决定是否切换。

---

显存控制：长视频不要一次性吃满

LingBot-Map 面向流式重建，但长序列仍然需要控制显存。常用手段包括：

使用 bf16

bash📋 复制
--dtype bf16

bf16 通常比 fp32 更省显存，也更快。适合 Ampere、Ada、Hopper 等较新的 NVIDIA GPU。

如果显卡不支持 bf16，需要退回项目支持的其他精度配置，例如 fp16 或默认精度，具体以 --help 为准。

增大关键帧间隔

README 中提到可以使用：

bash📋 复制
--keyframe_interval

例如每 5 帧取一个关键帧：

bash📋 复制
--keyframe_interval 5

关键帧间隔越大：

• 推理和缓存压力越低；
• 长视频速度更快；
• 但位姿和局部几何可能更容易丢细节。

建议：

视频类型	建议
慢速室内手持	可以适当增大间隔
快速车载视频	不宜过大
大幅转头、快速旋转	不宜过大
长时间直行街景	可尝试较大间隔

使用窗口化推理

README 中建议长序列，尤其是超过 3000 帧的视频，使用 windowed inference。

窗口化的目的：

• 控制 KV cache 和中间状态规模；
• 限制单次可视化和渲染的数据量；
• 避免长序列一次性占用过多显存；
• 提升非常长视频的稳定性。

适用场景：

text📋 复制
3 000 帧以上：建议使用窗口化
10 000 帧以上：强烈建议使用窗口化
25 000 帧级别：应结合窗口化、关键帧间隔、bf16、后端优化一起使用

---

推理加速：compile、bf16、FlashInfer 组合使用

README 中推荐的加速组合是：

bash📋 复制
python demo.py --compile ...

或：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16 --compile

各选项作用如下：

参数	作用	注意
--compile	使用 PyTorch 编译优化模型执行	首次运行会有编译开销
--dtype bf16	降低显存占用，提高吞吐	需要硬件支持
--backend flashinfer	使用 FlashInfer 注意力后端	需要正确安装 FlashInfer
--backend sdpa	使用 PyTorch SDPA 后端	兼容性更好，性能通常低于 FlashInfer
--keyframe_interval	降低关键帧密度	间隔过大会影响质量
窗口化推理	限制长序列状态规模	需要根据视频长度调窗口大小

推荐优先级：

1. 先确认默认配置能跑通；
2. 再加 --dtype bf16；
3. 再切换 --backend flashinfer；
4. 再加 --compile；
5. 最后针对长视频调整窗口和 --keyframe_interval。

---

使用示例：检查本地 demo 支持哪些可视化参数

在仓库根目录执行：

bash📋 复制
python demo.py --help

如果只想快速找和可视化、天空、性能相关的参数，可以用：

bash📋 复制
python demo.py --help | grep -Ei "vis|visual|point|cloud|sky|mask|backend|dtype|compile|window|keyframe|memory|cache"

这个命令不会启动模型，只用于确认当前代码版本支持哪些参数。

---

使用示例：用 SDPA 后端做一次基准测试

SDPA 不依赖 FlashInfer，适合作为环境检查的第一步。

bash📋 复制
python gct_profile.py --backend sdpa --dtype bf16

如果运行成功，说明：

• PyTorch 环境基本可用；
• 模型主要推理路径可执行；
• bf16 在当前硬件上可用。

如果 bf16 报错，可以先去掉精度参数：

bash📋 复制
python gct_profile.py --backend sdpa

---

使用示例：用 FlashInfer、bf16 和 compile 测试最快路径

README 推荐使用：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16 --compile

适合用于确认：

• FlashInfer 是否安装正确；
• paged KV cache 注意力是否可用；
• torch.compile 在当前 PyTorch / CUDA 环境下是否稳定；
• 长序列推理速度是否达到预期。

首次运行 --compile 会比较慢，因为需要编译图。建议至少观察第二轮或后续稳定速度。

---

使用示例：长序列推理时提高关键帧间隔

假设你的 demo.py 已经按照 README 跑通基础示例，可以在原命令后追加：

bash📋 复制
--keyframe_interval 5

完整形式类似：

bash📋 复制
python demo.py \
  <你的输入参数> \
  --keyframe_interval 5

如果视频很长，可以从较保守的间隔开始：

bash📋 复制
--keyframe_interval 2

再逐步尝试：

bash📋 复制
--keyframe_interval 5

不建议一开始就设得很大。快速运动、转弯、上楼梯、绕物体拍摄时，过大的关键帧间隔可能导致局部几何不稳定。

---

使用示例：开启高性能推理组合

在已经跑通基础 demo 后，可以把性能参数追加到原命令：

bash📋 复制
python demo.py \
  <你的输入参数> \
  --backend flashinfer \
  --dtype bf16 \
  --compile

如果 FlashInfer 不可用，改成：

bash📋 复制
python demo.py \
  <你的输入参数> \
  --backend sdpa \
  --dtype bf16 \
  --compile

如果 --compile 首次启动时间过长，调试阶段可以先关闭：

bash📋 复制
python demo.py \
  <你的输入参数> \
  --backend sdpa \
  --dtype bf16

---

使用示例：户外视频开启天空遮罩

先确认当前版本的天空遮罩参数名：

bash📋 复制
python demo.py --help | grep -Ei "sky|mask|seg"

然后在原 demo 命令后追加对应选项。形式通常类似：

bash📋 复制
python demo.py \
  <你的输入参数> \
  <天空遮罩相关参数>

建议先跑一小段户外数据，并检查：

• 天空是否被完整遮住；
• 楼顶、树枝、电线有没有被误删；
• 点云中远处漂浮点是否明显减少；
• 点云包围盒是否恢复到合理范围。

如果遮罩质量不好，宁可关闭天空遮罩，也不要让错误 mask 删除关键结构。

---

使用示例：长视频的推荐组合

对于几千帧以上的视频，可以使用下面的思路组合参数：

bash📋 复制
python demo.py \
  <你的输入参数> \
  --backend flashinfer \
  --dtype bf16 \
  --compile \
  --keyframe_interval 5

如果视频超过 3000 帧，应同时查看 demo.py --help 中是否提供窗口化参数：

bash📋 复制
python demo.py --help | grep -Ei "window|chunk|segment"

然后按本地参数名开启窗口化推理。

推荐排查顺序：

1. 先用短片段跑通；
2. 再开 bf16；
3. 再开 flashinfer；
4. 再开 compile；
5. 再上完整长视频；
6. 最后调整窗口大小和关键帧间隔。

---

注意边界：可视化结果不是完整评测结果

点云可视化主要用于观察和调试，不等同于严格评测。

需要注意：

• 点大小会影响视觉观感，但不会改变真实几何误差；
• 置信度阈值过高会让点云看起来更干净，但也可能隐藏缺失问题；
• 只看局部窗口可能看不出全局漂移；
• 天空遮罩会改变可视化点云分布，评测时要保证配置一致；
• 离线渲染结果和交互式 demo 的显示策略可能不同。

---

注意边界：FlashInfer 版本和 CUDA 环境要匹配

--backend flashinfer 依赖 FlashInfer 安装和 CUDA 环境。

常见问题：

现象	可能原因
import FlashInfer 失败	未安装或 Python 环境不一致
CUDA kernel 报错	CUDA、PyTorch、FlashInfer 版本不匹配
SDPA 能跑，FlashInfer 不能跑	FlashInfer 后端环境问题
首次运行很慢	--compile 正在编译，不一定是卡死

排查建议：

bash📋 复制
python gct_profile.py --backend sdpa --dtype bf16

先确认 SDPA 路径可用，再测试：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16

最后再加：

bash📋 复制
python gct_profile.py --backend flashinfer --dtype bf16 --compile

---

注意边界：SDPA 后端已经修复，但长序列仍推荐 FlashInfer

README 中的更新说明提到：

• SDPA KV cache bug 已修复；
• SDPA 在长序列上表现已经改善；
• 最佳性能仍推荐 FlashInfer。

因此可以这样选择：

目标	推荐
快速跑通	SDPA
兼容性优先	SDPA
长视频性能	FlashInfer
低显存高吞吐	FlashInfer + bf16
最快推理	FlashInfer + bf16 + compile

---

注意边界：keyframe_interval 不是越大越好

--keyframe_interval 可以降低计算压力，但会影响时序信息密度。

可能出现的问题：

• 快速运动时轨迹不稳；
• 转角处结构断裂；
• 小物体或细节丢失；
• 局部点云错位；
• 长时间漂移更难纠正。

建议从小到大试：

text📋 复制
1 → 2 → 5 → 10

如果质量下降明显，回退到上一个稳定值。

---

注意边界：天空遮罩可能误删有效结构

天空遮罩适合户外，但不适合盲目开启。

容易误判的区域：

• 白色墙面；
• 玻璃幕墙；
• 远处浅色建筑；
• 雾天、雪天、强曝光区域；
• 树冠和天空交界处；
• 夜晚路灯附近的亮区。

如果发现建筑上沿被切掉，或者树、塔、电线消失，应检查 mask，而不是只调点云阈值。