WorldGS 使用文档
WorldGS 是一款面向真实空间重建的端云一体工具。从手机拍摄到电脑高清训练，从自动空三到一键分享，帮助你将房间、街景、文物或任何记忆场景快速转化为可浏览、可分享的 3D 空间。
项目介绍
什么是 WorldGS
WorldGS 由手机端 App 与桌面端 Receiver 组成。手机端负责素材采集、本地质检、快速预览与轻量重建；桌面端负责素材同步、自定义脚本与高清离线训练。所有数据在传输和训练过程中遵循本地优先原则，敏感素材无需上传公网。
核心流程遵循「手机采集 → 本地质检与快速预览 → 自动训练 → 成果查看 → 一键分享」五步闭环。普通用户可仅凭手机完成全部流程；专业用户则能通过桌面端接入自定义算法脚本，获得更高精度与更灵活的后处理能力。
核心能力
手机端一键重建
导入视频或图片即可自动完成空三解算与 3D 重建，支持快速、标准、高清三种质量模式。
实时空三预览
解算过程中可查看相机位姿与稀疏点云，及时发现缺角并返回补拍。
桌面端深度加工
通过扫码或局域网同步素材到电脑，利用更强算力进行高清离线训练。
自定义训练脚本
上传 .sh / .py / .zip 脚本，指定入口与参数，WorldGS Receiver 自动传参、执行并注册结果。
链接分享与在线浏览
训练完成后生成公开链接，接收方无需安装 App 即可在浏览器中查看 3D 空间。
本地优先
素材同步依赖局域网，训练脚本在本地执行，敏感数据不上公网，保护隐私安全。
适用场景
| 场景 | 推荐模式 | 说明 |
|---|---|---|
| 家庭回忆 / 旅行随拍 | 快速预览 / 标准重建 | 围绕房间、庭院或景点拍摄，数分钟即可生成可分享的 3D 记忆。 |
| 文物 / 展品数字化 | 标准重建 / 高清重建 | 稳定环绕拍摄，捕捉表面纹理与几何细节，用于线上展示或存档。 |
| 建筑 / 室内测量 | 高清重建 + 桌面端 | 同步到电脑进行高分辨率训练，获得更精确的空间结构与尺度。 |
| 算法研究与定制 | 自定义脚本 | 在桌面端挂载自己的 SfM 或 Gaussian Splatting 脚本，灵活调整参数。 |
快速开始
普通用户：拍视频重建记忆
只需三步，即可用手机把一段视频变成可浏览的 3D 空间。
- 打开 App 并导入视频：点击底部「+」，选择已拍好的视频或直接调用相机拍摄。
- 选择质量模式并等待重建：推荐首次使用「标准重建」，App 会自动完成空三解算与 Gaussian Splatting 训练。
- 查看并分享成果：训练完成后进入「成果」页，点击「分享」生成公开链接，发送给好友即可在线浏览。
拍摄时保持手机稳定、缓慢移动，相邻画面重叠 60% 以上，重建效果会更完整。
专业用户：采集与补拍
当你对覆盖范围或精度有更高要求时，可按以下流程操作。
- 规划采集路线：围绕目标拍摄 2–3 圈，分别覆盖高、中、低三个高度，确保关键结构都有影像。
- 实时检查空三结果：解算完成后查看相机位姿与稀疏点云，检查是否存在未覆盖区域。
- 针对缺角补拍：返回缺失角度补充 5–10 秒短片，App 会自动合并新旧素材重新解算。
- 切换高清模式输出：补拍完成后选择「高清重建」，获得更密集的高斯点云与更清晰的渲染。
离线训练：电脑高清处理
需要更高算力或自定义脚本时，可将素材同步到桌面端进行离线训练。
- 安装 Receiver：从下载页面获取对应 macOS 版本并完成安装。
- 连接同一局域网：确保手机与电脑接入同一 Wi-Fi 或有线网络。
- 扫码同步素材：在桌面端打开「扫码上传」页面，用手机 App 扫描屏幕二维码开始传输。
- 选择脚本并训练：在「活动任务」中选择任务与脚本，点击「开始训练」，等待本地训练完成。
同步完成后，训练过程无需联网。桌面端训练日志、进度与预计剩余时间会实时显示。
功能详解
采集与引导
WorldGS 手机端支持导入视频、图片或直接调用相机拍摄。App 内置采集引导，会提示移动速度、重叠率与画面稳定性。建议围绕目标物体或空间缓慢移动，保持相邻画面之间有 60% 以上的重叠区域。
- 光线充足、纹理丰富的场景重建效果更好
- 避免大面积反光、透明或纯色的物体表面
- 移动速度均匀，避免画面模糊
- 纹理重复区域（如一排相同的窗户）可能影响匹配
空三与点云
导入素材后，WorldGS 自动执行运动恢复结构（SfM）解算，估算相机位姿并生成稀疏点云。解算过程中可实时查看位姿分布，若发现某角度覆盖不足，可立即返回补拍。
空三成功后会进入 Gaussian Splatting 训练阶段。手机端默认在本地完成轻量训练，桌面端则可调用更强算力进行高清迭代。
训练模式
WorldGS 提供三种训练模式，分别对应不同的输出精度、耗时与设备要求。
| 模式 | 分辨率 | 迭代次数 | 高斯数量 | SH 阶数 | 适用场景 |
|---|---|---|---|---|---|
| 快速预览 | 768px | 600 iter | 120k gaussians | SH 1 | 快速验证拍摄效果、低功耗设备 |
| 标准重建 | 960px | 3000 iter | 500k gaussians | SH 2 | 日常分享、社交传播 |
| 高清重建 | 1440px | 8000 iter | 2M gaussians | SH 3 | 高精度存档、桌面端深度处理 |
成果查看与分享
训练完成后，成果会出现在「成果」页。点击即可进入 3D 浏览器，支持缩放、旋转、全屏查看。点击「分享」可生成唯一公开链接，接收方无需安装任何软件即可在浏览器中查看 3D 空间。
你也可以随时停止分享或重新训练优化效果。分享链接默认长期有效，停止分享后链接立即失效。
手机与电脑同步
当需要更高精度或使用自定义脚本时，可将素材从手机同步到桌面端。同步内容包含以下类型：
- 原素材：拍摄得到的原始图片或视频帧
- COLMAP 素材：解算后的相机位姿与点云数据
- 空三报告：包含重投影误差、匹配数等质量指标
- 训练成功 PLY：Gaussian Splatting 输出的点云模型
- 训练报告：训练日志、Loss 曲线与参数配置
确保手机与电脑连接在同一局域网，桌面端打开「扫码上传」页面，用手机 App 扫描二维码即可开始传输。
常见问题
安装与升级
WorldGS 支持哪些平台？
手机端目前支持 Android 8 及以上；桌面端支持 macOS（Apple 芯片与 Intel）。Windows 版本正在开发中。
各平台安装包有多大？
Android 安装包约 63MB；macOS ARM 版本约 161MB；macOS Intel 版本约 181MB。桌面端安装后若进行离线训练，会根据脚本额外下载模型依赖。
如何升级到最新版本？
Android 用户可在 App 内「设置 → 关于」检查更新；macOS 用户下载新版 .dmg 覆盖安装即可，历史任务与成果会自动保留。
采集与拍摄
拍摄时画面需要注意什么？
保持稳定、缓慢移动，相邻帧重叠 60% 以上；避免过曝、过暗、反光和透明表面；纹理重复区域（如一排相同的窗户）可能影响匹配。
一段视频最长可以多久？
手机端对单次导入的视频长度没有硬性限制，但建议控制在 3 分钟以内，以获得较快的空三与训练速度。超过 5 分钟的素材推荐同步到桌面端处理。
发现缺角后如何补拍？
在空三预览界面查看相机位姿分布，找到未覆盖的角度后返回拍摄 5–10 秒短片，再次导入即可自动合并解算。
训练与重建
训练一般需要多长时间？
快速预览约 1–3 分钟，标准重建约 5–15 分钟，高清重建在桌面端根据算力可能需要 30 分钟以上。首次使用建议先用快速预览验证拍摄质量。
训练失败最常见的原因是什么？
通常是空三解算失败导致，原因包括画面模糊、重叠不足、纹理缺失或动态物体过多。可尝试补拍或切换到光线更好的环境。
训练成功的 PLY 文件保存在哪里？
手机端保存在 App 私有存储的「输出」目录，可通过成果页直接浏览；桌面端保存在 Receiver 设置中指定的输出目录，默认位于 ~/Documents/WorldGS/outputs。
同步与分享
分享链接多久有效？
分享链接默认长期有效。你可以在「成果」页随时停止分享，停止后链接立即失效，已访问的页面也会无法加载。
手机与电脑无法同步怎么办？
请检查两台设备是否连接同一局域网；关闭防火墙或允许 WorldGS Receiver 通过；尝试重启桌面端并重新扫描二维码。若仍失败，可使用数据线导出素材后手动导入桌面端。
接收方需要安装 App 才能查看吗？
不需要。分享链接可在主流浏览器中直接打开并交互浏览 3D 空间，支持桌面与移动端浏览器。