模块拆解：快速开始与交互式 Demo

demo.py 负责把一段图片流变成可浏览的 3D 场景

demo.py 是 LingBot-Map 的交互式入口，适合第一次验证模型是否安装正确，也适合用自己的图片序列快速查看重建效果。

它做的事情可以拆成四步：

1. 读取图片序列
   从一个目录中按文件名顺序加载 RGB 图像，例如 000001.jpg、000002.jpg、000003.jpg。

2. 加载 LingBot-Map 权重
   使用本地 checkpoint，或从 HuggingFace / ModelScope 下载后的模型目录加载。

3. 流式执行 3D 重建
   按帧送入模型，维护流式上下文，包括关键帧、轨迹记忆和几何上下文。

4. 启动 viser 浏览器可视化
   在本地启动一个 Web 服务，把相机轨迹、点云 / 几何结果显示在浏览器中。

典型使用场景：

• 快速确认环境、CUDA、模型权重是否可用；
• 用仓库自带示例图片查看 3D 重建效果；
• 用手机、机器人或数据集导出的连续图片测试流式重建；
• 调整关键帧间隔、窗口推理、天空遮罩等参数观察效果变化。

---

demo.py 的输入、模型和浏览器服务

图片序列目录

demo.py 期望输入是一组连续图片，而不是单张图片。目录结构通常类似：

text📋 复制
examples/
└── room/
    ├── 000000.jpg
    ├── 000001.jpg
    ├── 000002.jpg
    ├── 000003.jpg
    └── ...

建议图片文件名使用固定宽度数字编号，方便按时间顺序读取：

text📋 复制
000000.jpg
000001.jpg
000002.jpg

如果文件名是：

text📋 复制
frame_1.jpg
frame_10.jpg
frame_2.jpg

需要注意排序问题，最好提前改成数字递增格式。

---

模型权重路径

README 中提供了两个模型下载入口：

• HuggingFace：robbyant/lingbot-map
• ModelScope：Robbyant/lingbot-map

推荐先下载到本地，例如：

bash📋 复制
mkdir -p checkpoints

huggingface-cli download robbyant/lingbot-map \
  --local-dir checkpoints/lingbot-map

之后在运行 demo.py 时把本地模型目录传进去。

如果网络环境更适合 ModelScope，可以用 ModelScope 下载到本地后传入同样的模型目录路径。

---

viser 浏览器窗口

demo.py 会启动 viser 服务。运行后终端通常会打印一个本地地址，例如：

text📋 复制
http://localhost:8080

在浏览器打开这个地址即可查看重建结果。

常见的交互内容包括：

• 当前重建出的点云 / 几何结构；
• 相机轨迹；
• 每一帧相机位姿；
• 视角旋转、缩放和平移；
• 点大小、可见性等可视化选项。

如果默认端口被占用，可以换一个端口，例如 8090。

---

常用参数对应的功能

不同版本的 demo.py 参数名可能会有小幅变化，运行前建议先看帮助：

bash📋 复制
python demo.py --help

下面是交互式 Demo 中常见参数的含义。

参数	作用	适用场景
--image_dir / --img_dir	图片序列目录	加载示例场景或自己的图片
--model_path / --ckpt	模型权重路径	指向下载后的 LingBot-Map 模型
--port	viser 服务端口	默认端口被占用时修改
--keyframe_interval	关键帧间隔	长序列提速、降低显存
--window_size	窗口推理长度	超长序列减少内存压力
--sky_mask / --mask_sky	天空区域遮罩	户外场景减少天空干扰
--compile	启用编译优化	CUDA 环境稳定后用于提速
--dtype	推理精度，如 bf16	支持 BF16 的 GPU 上节省显存
--backend	注意力 / KV cache 后端	长序列推荐高性能后端，例如 FlashInfer

如果你的版本中参数名不同，以 python demo.py --help 输出为准。

---

用仓库示例图片启动浏览器 Demo

下面示例假设仓库中有一个示例图片目录：

text📋 复制
examples/room/

如果你的目录名不同，把命令里的路径替换成实际目录即可。

1. 克隆项目

bash📋 复制
git clone https://github.com/Robbyant/lingbot-map.git
cd lingbot-map

2. 创建 Python 环境

bash📋 复制
conda create -n lingbot-map python=3.11 -y
conda activate lingbot-map

3. 安装依赖

bash📋 复制
pip install -r requirements.txt

如果项目 README 中要求额外安装 CUDA、PyTorch、FlashInfer 或其他依赖，优先按照 README 的安装章节执行。

4. 下载模型

bash📋 复制
mkdir -p checkpoints

huggingface-cli download robbyant/lingbot-map \
  --local-dir checkpoints/lingbot-map

如果没有安装 HuggingFace CLI：

bash📋 复制
pip install -U huggingface_hub

5. 启动交互式 Demo

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir examples/room \
  --port 8080

启动后打开浏览器：

text📋 复制
http://localhost:8080

如果终端打印的是其他地址，以终端输出为准。

---

用自己的图片序列跑一遍

假设你有一段视频，先抽帧到 data/my_room/images：

bash📋 复制
mkdir -p data/my_room/images

ffmpeg -i my_room.mp4 \
  -vf "fps=10" \
  data/my_room/images/%06d.jpg

运行 Demo：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/my_room/images \
  --port 8080

打开：

text📋 复制
http://localhost:8080

这个例子会以 10 FPS 抽帧后的图片作为流式输入。第一次测试时不建议直接使用原视频全部帧，先抽稀可以更快定位环境问题。

---

长序列用关键帧间隔降低压力

对于几千帧甚至上万帧的序列，可以先设置关键帧间隔：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/long_walk/images \
  --keyframe_interval 5 \
  --port 8080

含义是：不是每一帧都作为关键帧进入长期上下文，而是每隔一定帧数保留更关键的几何信息。

适合场景：

• 室内长走廊；
• 机器人持续巡航；
• 手持设备长时间扫描；
• 超过几千帧的连续视频。

一般可以从下面几个值开始试：

text📋 复制
1   质量优先，显存和计算压力最大
3   平衡质量和速度
5   长序列常用
10  快速预览或非常长的视频

---

超长序列使用窗口推理

如果图片数量超过 3000 帧，建议启用窗口化推理，避免上下文过长导致显存增长。

示例：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/very_long_walk/images \
  --keyframe_interval 5 \
  --window_size 3000 \
  --port 8080

窗口推理更适合：

• 10 分钟以上的视频；
• 数万帧图片；
• 显存有限的 GPU；
• 只需要在线查看整体轨迹和重建趋势的场景。

窗口大小不是越大越好。窗口越大，上下文更完整，但显存和耗时也更高。

---

户外数据开启天空遮罩

户外场景中，天空没有稳定几何结构，可能影响深度和点云质量。可以开启天空遮罩：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/outdoor/images \
  --sky_mask \
  --port 8080

适合：

• 街景；
• 园区道路；
• 机器人户外巡检；
• 车载相机数据。

不一定适合：

• 室内场景；
• 天花板纹理明显的场景；
• 天空占比很小的画面。

---

在支持的 GPU 上启用编译优化

README 中提到可以使用 --compile 加速：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir examples/room \
  --compile \
  --port 8080

建议先不加 --compile 跑通一次。确认模型、显卡和可视化都正常后，再开启编译优化。

如果使用 BF16：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir examples/room \
  --dtype bf16 \
  --compile \
  --port 8080

---

FlashInfer 后端适合长序列

LingBot-Map README 中建议长序列使用 FlashInfer 后端以获得更好性能。安装完成后可以这样运行：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/long_walk/images \
  --backend flashinfer \
  --dtype bf16 \
  --keyframe_interval 5 \
  --port 8080

如果 FlashInfer 安装失败或当前显卡不支持，可以先使用默认后端跑通 Demo。

---

浏览器里重点看这几个结果

打开 viser 页面后，建议按这个顺序检查：

1. 相机轨迹是否连续
   如果轨迹突然跳变，通常说明输入帧顺序、画面质量或运动幅度有问题。

2. 点云是否和场景轮廓一致
   室内墙面、地面、桌椅等应该能形成大致稳定结构。

3. 尺度是否明显漂移
   很长的序列中如果后半段开始弯曲或漂移，可以尝试调小 keyframe_interval 或使用更合适的窗口大小。

4. 天空、玻璃、反光区域是否产生噪点
   户外开启天空遮罩，室内反光区域需要尽量避免占据画面主体。

5. 浏览器是否卡顿
   如果点太多，可以降低可视化点数、增大关键帧间隔，或缩短输入序列。

---

常见问题和边界条件

图片必须有足够视差

LingBot-Map 是从连续视觉输入中重建 3D。下面这些输入效果通常不好：

• 多张几乎完全相同的图片；
• 原地旋转但没有平移；
• 快速运动导致严重模糊；
• 大面积纯色墙面；
• 黑暗、过曝或强反光画面。

更好的输入方式：

• 缓慢移动相机；
• 保持相邻帧有重叠；
• 避免突然转身；
• 画面中保留稳定纹理。

---

帧顺序错误会直接影响轨迹

确保文件排序就是时间顺序。推荐命名：

text📋 复制
000000.jpg
000001.jpg
000002.jpg
...

不推荐：

text📋 复制
1.jpg
2.jpg
10.jpg

因为某些排序方式下可能变成：

text📋 复制
1.jpg
10.jpg
2.jpg

可以用下面命令检查前几帧排序：

bash📋 复制
ls data/my_room/images | head -20

---

分辨率越高不一定越好

README 中提到模型可在 518×378 分辨率下进行高效流式推理。实际使用时：

• 分辨率太低：细节少，几何质量下降；
• 分辨率太高：显存、推理时间和浏览器压力增加；
• 首次测试：建议使用 README 推荐或 Demo 默认分辨率。

如果自己的图片是 4K，建议先缩放后测试：

bash📋 复制
mkdir -p data/my_room_resized/images

ffmpeg -i my_room.mp4 \
  -vf "fps=10,scale=518:-2" \
  data/my_room_resized/images/%06d.jpg

---

端口被占用时换一个端口

如果启动时报端口占用：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir examples/room \
  --port 8090

然后打开：

text📋 复制
http://localhost:8090

---

远程服务器需要端口转发

如果 Demo 跑在远程服务器上，本地浏览器不能直接访问 localhost:8080。可以使用 SSH 端口转发：

bash📋 复制
ssh -L 8080:localhost:8080 user@server_ip

然后在本地浏览器打开：

text📋 复制
http://localhost:8080

---

显存不足时优先调整这几项

如果出现 CUDA OOM，可以按顺序处理：

1. 减少输入帧数；
2. 增大 --keyframe_interval；
3. 开启 --window_size；
4. 使用 --dtype bf16；
5. 降低图片分辨率；
6. 暂时关闭高开销可视化选项；
7. 使用更大显存的 GPU。

示例：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/long_walk/images \
  --dtype bf16 \
  --keyframe_interval 8 \
  --window_size 2000 \
  --port 8080

---

先跑短序列，再跑长序列

建议第一次只放 100～300 张图片：

bash📋 复制
mkdir -p data/debug/images

find data/my_room/images -maxdepth 1 -type f | sort | head -300 | while read f; do
  cp "$f" data/debug/images/
done

确认 Demo 正常后再运行完整序列：

bash📋 复制
python demo.py \
  --model_path checkpoints/lingbot-map \
  --image_dir data/debug/images \
  --port 8080

这样可以更快定位问题，避免一开始就在长视频上等待很久。