内容
# 🛰 世界扫描器
**将无人机和手机视频转换为可探索的 3D 世界 — 完全在您的 Mac 上运行。**
将 FPV 无人机剪辑（或任何漫游视频）放到本地仪表板上，即可获得交互式 3D 重建：飞过点云，以高斯飞溅的形式查看，并重放扫描世界的相机飞行路径。无需云端，无需 GPU 渲染，无需账号 — 所有操作都在 Apple Silicon 笔记本电脑上运行。
基于 [LingBot-Map](https://github.com/Robbyant/lingbot-map)（[论文](https://arxiv.org/abs/2604.14141)）构建，一个前馈流式 3D 重建模型，在此处移植到 macOS 上运行（详见下文）。
## 功能
| | |
|---|---|
|  |  |
| **轨迹模式** — 相机的路径显示为重建世界中的一条带状线，带有方向标记、飞行跟踪器和俯瞰小地图 | **飞溅模式** — 场景显示为 3D 高斯飞溅（内置即时模糊转换；可选 HQ 训练 via OpenSplat） |
1. **拖放视频** → 选择 **无人机**（快速运动，6 帧/秒采样）或 **漫游**（4 帧/秒）。
2. 模型观察帧并预测每个帧的 **相机姿态** 和 **稠密深度图**，将它们融合到彩色点云中 — 单次前馈传递，无需 COLMAP，无需离线优化。
3. **探索** 场景有三种方式 — 点、飞溅、轨迹 — 直接从场景卡中。每种场景还导出其他工具的标准格式：
`points.ply`，nerfstudio `transforms.json`，以及 COLMAP 文本模型。
还包含一个 **MCP 服务器**，允许 Claude Code 以对话式驱动相同的管道（“重建此视频”，“从上方渲染法院” — 图像返回到聊天中）。
## 快速入门（Apple Silicon Mac）
```bash
git clone https://github.com/hem-318/world-scanner.git && cd world-scanner
./setup.sh # Homebrew 工具 + Python 环境 + 4.6 GB 模型（sha256 验证）+ 补丁
demo-kit/run_dashboard.sh
# → http://localhost:8100 — 在其上放置视频
```
系统要求：Apple Silicon Mac（测试：M1 Pro，16 GB，macOS 27），[Homebrew](https://brew.sh)，约 15 GB 可用磁盘空间。第一次重建无需下载其他内容。
<details>
<summary><b>CLI 使用和其他入口点</b></summary>
```bash
# 带有上游交互式查看器的捆绑示例场景（viser）：
demo-kit/run_demo.sh --image_folder "$PWD/lingbot-map/example/courthouse" \
--first_k 80 --num_scale_frames 2 --kv_cache_sliding_window 16 \
--offload_to_cpu --port 8081 --export_dir "$PWD/scenes/courthouse"
# 无头：视频 → 仅导出
demo-kit/run_demo.sh --video_path ~/Movies/flight.mp4 --fps 6 --first_k 100 \
--num_scale_frames 2 --kv_cache_sliding_window 16 --offload_to_cpu \
--no_viewer --export_dir "$PWD/scenes/flight"
# 任意导出场景的即时飞溅：
lingbot-map/.venv/bin/python demo-kit/points_to_splats.py scenes/flight
```
**MCP：** `.mcp.json` 在此文件夹中为 Claude Code 会话注册 `lingbot-map` 服务器 — 工具：`reconstruct`，`make_splats`，`render_view`，`open_viewer`，`list_scenes`.
完整运行手册及所有测量数据：[demo-kit/README-mac.md](demo-kit/README-mac.md).
</details>
## macOS 移植的工作原理
上游项目针对 NVIDIA CUDA + FlashInfer。此仓库携带一个小补丁（[demo-kit/patches/](demo-kit/patches/)，由 `setup.sh` 自动应用），使其在 Mac 上运行：
- 设备选择 `cuda → mps → cpu`，带有 `--device` 覆盖；SDPA 注意力替换 FlashInfer 离开 NVIDIA；CUDA 图编译和 CUDA 独有调用受到保护
- RoPE 频率表为 complex128，Apple 的 MPS 后端无法存储 — 它们在 CPU 上以完整精度构建，并作为 complex64 传输（对于推理是无损的，因为它只读取 `.real`/`.imag` 以 fp32）
- `--export_dir` / `--no_viewer` 钩子提供导出和无头管道
**性能，在 M1 Pro（16 GB）上测量：** CPU fp32 约 7–11 秒/帧（80 帧场景：约 9 分钟，8.7 M 点，峰值 3.9 GB RAM）。MPS 推理在补丁后运行，但会耗尽 16 GB 机器上的 20 GB 分配器水位标记 — 可能在 32 GB+ Mac 上可行。OpenSplat HQ 训练是 CPU 绑定的（约 13 秒/步），无需完整 Xcode；安装 Xcode 并使用 `-DGPU_RUNTIME=MPS` 重新构建以获得 Metal 速度。
## 仓库布局
```
demo-kit/ 此仓库添加的所有内容
├── dashboard/ FastAPI 应用 + 单页 UI（上传、作业、场景卡）
├── splat_viewer/ 浏览器高斯飞溅查看器（three.js，由 setup.sh 移植）
├── export_predictions.py 模型输出 → PLY / nerfstudio / COLMAP
├── points_to_splats.py 即时点 → 高斯转换器
├── render_scene.py 无头 numpy 渲染器（用于 MCP 图像回复）
├── mcp_server.py Claude Code 集成
├── patches/ macOS 移植上游（git am 格式）
└── tests/ 上述所有内容的 pytest 套件
docs/ 设计规范、实施计划、截图
setup.sh 一键引导
```
重建结果存储在 `scenes/<name>/`（gitignored），模型存储在 `models/`（gitignored）。
## 鸣谢与许可
- [LingBot-Map](https://github.com/Robbyant/lingbot-map) — 模型、权重和演示代码（Apache-2.0）；论文：*Geometric Context Transformer for Streaming 3D Reconstruction*（[arXiv:2604.14141](https://arxiv.org/abs/2604.14141)）
- [OpenSplat](https://github.com/pierotofy/OpenSplat)（可选 HQ 飞溅训练），
[GaussianSplats3D](https://github.com/mkkellogg/GaussianSplats3D)，
[three.js](https://threejs.org)，[viser](https://viser.studio)
本仓库的代码和 macOS 补丁均以 **Apache-2.0** 许可（参见 [LICENSE](LICENSE)）。
