3DGS Campus Tour

基于 COLMAP 相机位姿约束的校园游览系统。

当前工程包含两部分：

• Python 数据管线：解析 gsdata/video114~116 的 COLMAP 二进制，生成训练相机 JSON、场景中心和三种导览路径。
• React + Vite 前端：使用 Three.js 自定义相机播放导览路径，并接入本地 GaussianSplats3D 作为 3DGS 渲染核心。

当场景目录里还没有 .ksplat / .splat 时，前端会自动回退到 COLMAP sparse/0/points3D.ply 点云调试模式，因此当前这三个子场景可以直接预览导览逻辑。

Directory Layout

• gsdata
• GaussianSplats3D
• tools/prepare_campus_data.py
• tools/colmap/extract_camera_poses.py
• tools/colmap/build_camera_path.py
• src/App.jsx
• src/lib/campusViewer.js

Run

1. 安装依赖：

npm install

2. 先把每个 output/point_cloud/finish/point_cloud.ply 转成 .ksplat，再生成前端所需 JSON（默认会扫描 gsdata 下全部 video* 子目录）：

npm run prepare:data

3. 启动开发服务器：

npm run dev

开发模式会自动监听 gsdata/video* 目录变化。你把新的子场景文件夹解压到 gsdata 后，系统会自动重新生成数据并刷新页面，无需再手动执行 prepare:data。

4. 打开 Vite 输出的本地地址。

Data Pipeline

已实现的脚本：

• tools/colmap/read_colmap.py
  • 读取 cameras.bin、images.bin、points3D.bin
• tools/colmap/extract_camera_poses.py
  • 输出 camera_poses.json
  • 支持 single_main / virtual_center
• tools/colmap/analyze_scene_center.py
  • 输出 scene_center.json
• tools/colmap/build_camera_path.py
  • 输出两种路径：
    • replay
    • smoothed

批量运行后会生成：

• public/data/scenes/index.json
• public/data/scenes/video114/scene.json
• public/data/scenes/video115/scene.json
• public/data/scenes/video116/scene.json

Frontend Behavior

• 导览模式：自定义播放器按路径更新 camera.position / camera.up / camera.lookAt
• 自由查看：切换到 Three.js OrbitControls
• 支持：
  • 播放
  • 暂停
  • 停止
  • 时间轴跳转
  • 倍速
  • 路径模式切换
  • 返回最近训练视角
  • 训练相机 / 路径调试可视化

3DGS Asset Drop-in

当前默认会优先把每个子场景里的真实 3DGS 输出：

• gsdata/video114/output/point_cloud/finish/point_cloud.ply

转换成：

• gsdata/video114/output/point_cloud/finish/point_cloud.ksplat

然后由前端优先加载该 .ksplat 文件。

如果你后续把其他真实 3DGS 文件放进某个子场景目录，例如：

• gsdata/video114/campus.ksplat
• gsdata/video115/scene.splat

重新运行：

npm run prepare:data

脚本会自动把该文件写入场景清单的 splatAssetPath，前端就会优先使用 GaussianSplats3D 加载它，而不再使用点云回退。

Notes

• vite.config.js 添加了 /scene-assets/* 中间件，开发和预览时可以直接从工作区读取 gsdata 下的文件。
• GaussianSplats3D/src/worker/SortWorker.js 已加上 Vite 的 wasm ?inline 兼容。
• GaussianSplats3D/util/create-ksplat.js 已改成可直接从源码侧运行，不依赖预构建的 build/ 目录。
• 当前未内置 .ksplat 转换流程；如果你需要，我下一步可以继续补一个从训练结果或外部文件接入的转换/导入流程。