需要从图像或视频流式重建 3D 点云/相机位姿时用…

在具备 CUDA 环境和 LingBot-Map checkpoint 时，对图像序列或视频做 feed-forward 流式 3D 重建，输出点云、逐点置信度、相机位姿和深度图。

适用场景

解决思路

1. 创建并激活环境：`conda create -n lingbot-map python=3.10 -y`，然后 `conda activate lingbot-map`。
2. 安装 PyTorch：`pip install torch==2.9.1 torchvision==0.24.1 --index-url https://download.pytorch.org/whl/cu128`。
3. 安装 lingbot-map：`git clone https://github.com/Robbyant/lingbot-map.git`，`cd lingbot-map`，`pip install -e .`。
4. 推荐安装 FlashInfer 以加速 paged KV cache attention：`pip install flashinfer-python -i https://flashinfer.ai/whl/cu128/torch2.9/`。
5. 可选安装可视化支持：`pip install -e '.[vis]'`。
6. 可选安装天空掩码依赖：CPU 用 `pip install onnxruntime`，GPU 用 `pip install onnxruntime-gpu`。
7. 下载模型：用 `from huggingface_hub import hf_hub_download`，`model_path = hf_hub_download(repo_id='robbyant/lingbot-map', filename='checkpoint.pt')`；或从 HuggingFace `https://huggingface.co/robbyant/lingbot-map`、ModelScope `https://www.modelscope.cn/models/Robbyant/lingbot-map` 手动下载。
8. 从图像文件夹启动交互式 3D viewer：`python demo.py --model_path /path/to/checkpoint.pt --image_folder /path/to/images/`，浏览器打开 `localhost:8080`。
9. 从视频文件启动：`python demo.py --model_path /path/to/checkpoint.pt --video_path video.mp4 --fps 10`。
10. 室外场景加天空掩码：`python demo.py --model_path /path/to/checkpoint.pt --image_folder /path/to/images/ --mask_sky`。
11. 运行仓库示例场景：分别用 `--image_folder example/church --mask_sky`、`example/oxford --mask_sky`、`example/university4 --mask_sky`。
12. 长序列处理：序列超过 320 帧时设置 `--keyframe_interval 6`，把每第 N 帧存入 KV cache 以省显存；例如 `python demo.py --model_path /path/to/checkpoint.pt --image_folder /path/to/images/ --keyframe_interval 6`。
13. 极长序列（>3000 帧）用窗口模式：`python demo.py --model_path /path/to/checkpoint.pt --video_path video.mp4 --fps 10 --mode windowed --window_size 64`。
14. 没有 FlashInfer 时回退：任何命令加 `--use_sdpa` 使用 PyTorch SDPA。
15. 自定义天空掩码路径：`--mask_sky --sky_mask_dir /path/to/cached_masks/ --sky_mask_visualization_dir /path/to/mask_viz/`。
16. CLI 输入参数：`--model_path` 指定 .pt 检查点；`--image_folder` 指定图像目录；`--video_path` 指定视频；`--fps` 指定视频采样帧率。
17. CLI 推理参数：`--mode` 默认 `streaming`，可选 `windowed`；`--window_size` 默认 `64`；`--keyframe_interval` 默认 `1`；`--use_sdpa` 默认 `False`。
18. CLI 天空参数：`--mask_sky` 启用天空分割掩码；`--sky_mask_dir` 指定缓存天空掩码目录；`--sky_mask_visualization_dir` 保存并排掩码可视化。
19. CLI 可视化参数：`--port` 默认 `8080`；`--conf_threshold` 默认 `1.5` 过滤低置信点；`--point_size` 默认 `0.00001`；`--downsample_factor` 默认 `10` 用于显示降采样。
20. Python 基础流式推理：导入 `torch` 和 `LingBotMap`；`device='cuda' if torch.cuda.is_available() else 'cpu'`；`model = LingBotMap.from_pretrained('/path/to/checkpoint.pt')`；`model = model.to(device).eval()`；定义 transform `T.Compose([T.Resize((378,518)), T.ToTensor(), T.Normalize(mean=[0.485,0.456,0.406], std=[0.229,0.224,0.225])])`；按 `sorted(Path('/path/to/images').glob('*.jpg'))` 遍历；`img = Image.open(img_path).convert('RGB')`；`frame = transform(img).unsqueeze(0).to(device)`；`with torch.no_grad(): output = model.stream(frame)`；`output` 含 `pointmap`、`confidence`、`camera pose`。
21. 以子进程方式调用 demo：`subprocess.run(['python','demo.py','--model_path','/path/to/checkpoint.pt','--image_folder','example/church','--mask_sky','--port','8080'], check=True)`。
22. 视频输入预处理：用 `cv2.VideoCapture(video_path)` 读取视频；取 `video_fps = cap.get(cv2.CAP_PROP_FPS)`；`interval = max(1, int(video_fps / fps))`；逐帧读取，每 `interval` 帧取一帧；`cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)` 后收集返回。
23. 室外重建模式：`--mask_sky --conf_threshold 2.0 --downsample_factor 5`，去除噪声天空点。
24. 长室内序列模式（320–3000 帧）：`--keyframe_interval 6 --conf_threshold 1.5`。
25. 极长视频模式（>3000 帧）：`--video_path long_video.mp4 --fps 5 --mode windowed --window_size 64`。
26. 高质量稠密重建模式：`--conf_threshold 1.0 --downsample_factor 1 --point_size 0.00005`，保留更多点并显示更多细节。
27. CPU/无 FlashInfer 回退模式：`--use_sdpa`。
28. 处理 FlashInfer 不可用：安装 `pip install flashinfer-python -i https://flashinfer.ai/whl/cu128/torch2.9/`，或在任何命令加 `--use_sdpa`。
29. 处理长序列 CUDA OOM：减小内存用 `--keyframe_interval 6`，或切换 `--mode windowed --window_size 32`。
30. 处理天空掩码模型下载失败：手动 `wget https://huggingface.co/JianyuanWang/skyseg/resolve/main/skyseg.onnx`，放到预期路径或用 `--sky_mask_dir` 指定。
31. 处理点云低质量/噪声：提高 `--conf_threshold`，例如 `--conf_threshold 2.5`；室外始终加天空掩码，例如 `--mask_sky --conf_threshold 2.0`。
32. 处理端口被占用：用 `--port 8090` 更换 viewer 端口。
33. 处理图像未加载：确认图像已排序且格式支持 `.jpg`、`.jpeg`、`.png`、`.bmp`、`.webp`。
34. 性能/序列长度指南：<320 帧用默认 `streaming`，全 KV cache；320–3000 帧用 `--keyframe_interval 6`，缓存约减少 6 倍；>3000 帧用 `--mode windowed --window_size 64` 滑动窗口。
35. 性能目标：分辨率 518×378 时约 20 FPS；实际速度需要 CUDA-capable GPU；模型检查点约 4.63 GB。

适用边界 · 注意事项

• 不适合无 CUDA GPU 或无法下载约 4.63GB checkpoint、无法安装 LingBot-Map 依赖的环境；实际速度可能不可用。
• 不适合非流式、无需实时 3D 重建、没有多视角图像或视频序列的任务。
• 室内或无天空场景通常不需要 `--mask_sky`，除非噪声点来自天空区域。