--- name: supersplat description: "Use when editing 3D Gaussian Splatting (3DGS) .ply models in browser — cleanup noise/floaters, crop, transform, color-adjust, animate camera, publish online. SuperSplat: open-source browser-based 3DGS editor by PlayCanvas with PLY/compressed PLY/Splat/SOG/SPZ export." tags: - 3d - gaussian-splatting - 3dgs - webgl - webgpu - typescript - playcanvas - editor --- > **项目地址：** > > **在线编辑器：** ｜ **用户手册：** > > **许可证：** MIT ｜ **最新版本：** `v3.5.2`（2026-10-05，详见 [GitHub Releases](https://github.com/playcanvas/supersplat/releases)）｜ **默认分支：** `main` ## 概述 SuperSplat 是「3D 高斯泼溅领域的 Photoshop + 发布平台」：完全基于 Web、免下载安装、源码开源。它专为 3DGS「训练之后、上线之前」的后期处理而生，解决原始 `.ply` 噪点多、体积大、坐标不规范、缺乏清理/动画/发布能力等问题。 - **检查 / 编辑**：加载、查看、选择并删除高斯点（噪点、漂浮物 floaters）；选择工具含矩形/球体/画笔/套索/多边形/洪水填充/吸管，另有测量工具。 - **变换 / 裁剪**：平移/旋转/缩放（带 gizmo）、包围盒裁剪、多模型场景管理。 - **外观优化**：颜色调整（调色板 / 颜色匹配）、直方图、球谐（SH）带数控制。 - **动画**：相机姿态关键帧、时间轴（timeline / track-manager）、动画导出。 - **导出 / 发布**：多格式导出（含量化压缩与新格式），或一键发布到 PlayCanvas 托管获得分享链接。 - **技术栈**：TypeScript + PlayCanvas 引擎（`createGraphicsDevice` 初始化 WebGL2/WebGPU）+ PCUI 组件库 + i18next 国际化 + Rollup 构建。 > 3DGS 由 Inria 2023 年论文《3D Gaussian Splatting for Real-Time Radiance Field Rendering》提出，相比 NeRF 具备实时渲染、训练快、画质高的优势。 > **可嵌入查看器：** `@playcanvas/supersplat-viewer`（npm 包，当前 1.37.0）是 PlayCanvas 提供的可嵌入网页的高斯泼溅查看器，用于在自有网页中加载并展示导出的高斯模型。 --- ## 环境准备 ### 在线使用（推荐，零安装） 直接打开 ，将训练产出的 `.ply`（COLMAP + gaussian-splatting / Postshot / Nerfstudio 等）拖入即可。 ### 本地开发环境 ```bash git clone https://github.com/playcanvas/supersplat.git cd supersplat npm install # 需 Node >= 20.19.0（package.json engines） npm run develop # = watch（Rollup 监听构建）+ serve（静态服务 dist） ``` 浏览器打开本地服务后，按官方 README 要求关掉网络缓存并清理应用缓存，否则容易看到旧版本页面。 --- ## 核心 API 速览 SuperSplat 是应用而不是库，二次开发主要是围绕下面这些模块扩展： | 模块 | 职责 | |------|------| | `src/events.ts` | `Events` 类继承 PlayCanvas `EventHandler`，扩展函数注册/调用，是 UI 与逻辑解耦的核心 | | `src/scene.ts` / `src/pc-app.ts` | `Scene` 基于 `PCApp`，管理一组 Element（`ElementType`：Splat / Camera / grid / 叠加层等） | | `src/splat.ts` / `src/splat-state.ts` | `Splat` 封装 GSplat 资源与每点状态（含 `deleted` / hidden 标记） | | `src/edit-history.ts` / `src/edit-ops.ts` | 撤销/重做历史与编辑操作 | | `src/tools/` | 选择与变换工具集（矩形/球体/画笔/套索/多边形/洪水填充/测量/move/orient/rotate/scale） | | `src/serializer.ts` / `src/splat-serialize.ts` | 元素状态序列化与导出（导出核心） | | `src/export-options.ts` | `ExportType`、`ExportChoices`、`SerializeSettings` 等导出契约 | | `src/ui/` | 基于 `@playcanvas/pcui` 的 `EditorUI`：菜单/工具栏/面板，通过事件与逻辑通信 | | `src/publish.ts` | `PublishWriter`：分片上传与发布到 PlayCanvas 托管 | | `src/iframe-api.ts` | 给嵌入方用的 iframe 消息接口（如场景脏标记、回主页导航） | | `src/main.ts` | 应用入口，按序装配编辑器；用 PlayCanvas `createGraphicsDevice` 初始化 WebGL2/WebGPU | **二次开发要点**：UI 与逻辑通过 `Events` 事件解耦——新增功能通常是「注册事件/函数 + 新增 PCUI 面板组件」，而非直接耦合调用。 --- ## 典型工作流 ### 工作流一：训练后清理并压缩（在线的完整后期流程） 1. **导入** `.ply` 高斯模型 2. **清理**：用选择工具（矩形/套索/画笔/洪水填充等）选中噪点与漂浮物 → 删除（删除仅打 `deleted` 标记，导出时才真正剔除，可撤销恢复） 3. **裁剪**：用包围盒裁掉无关区域 4. **变换**：摆正坐标系、调整朝向与比例（多模型场景可分别变换） 5. **调色**：调整颜色、设置保留的 SH 带数 6. **动画**（可选）：设置相机关键帧与时间轴 7. **导出 / 发布**：选格式导出，或发布到云端；需要重复导出同一配置时用 Re-export ### 工作流二：压体积上网页 1. 删掉噪点（导出时被标记删除的点不写入，点数 = 原始 − 已删除） 2. 勾选 **Compress PLY**（量化压缩） 3. 降低 **SH Bands**（高阶球谐占绝大多数属性，Web 场景常保留 0–1 阶） 4. 按目标查看器选格式：通用加载用压缩 PLY，PlayCanvas/Web 发布用 SOG 或 SPZ 5. 常能把数百 MB 压到几 MB ### 工作流三：导出带查看器的自包含交付 1. 导出类型选 **Viewer App** 2. 选 HTML（单文件）或 ZIP Package 3. 需要时勾选 Animation、设置 Loop Mode（none / repeat / pingpong）、背景色与 FOV 4. 双击 HTML 即可在浏览器观看，或把 ZIP 交给对方直接托管 --- ## 导出格式 导出弹窗（`src/ui/export-popup.ts`，契约见 `src/export-options.ts`）的导出类型为 `ply` / `splat` / `sog` / `spz` / `viewer`： | 格式 | 扩展名 | 特点 | 适用场景 | |------|--------|------|----------| | 标准 PLY | `.ply` | 无损、体积大、通用 | 归档、再编辑、跨工具交换 | | 压缩 PLY | `.compressed.ply` | PlayCanvas 量化压缩（勾选 Compress PLY），体积大幅减小，仍是 PLY | Web 加载、平衡体积与兼容性 | | Splat | `.splat` | antimatter15 紧凑二进制 | 轻量 Web 查看器 | | SOG | `.sog` | Self-Organizing Gaussians，WebP 纹理存储，体积极小（可调 Iterations） | Web 发布、移动端 | | SPZ | `.spz` | Niantic 高斯压缩格式，可选 SPZ 4（最新）或 SPZ 3（legacy gzip） | 生态内互操作、进一步压缩 | | Viewer App | `.html` / `.zip` | 自包含查看器（含动画与循环模式） | 交付演示、无开发环境直接看 | > Re-export 会复用上次的导出配置（`src/export-options.ts` 中除文件名外的选项都从当前场景读取），重复导出同一批参数不必重填。 --- ## 发布到 PlayCanvas 平台 一键发布（`src/publish.ts`、`src/ui/publish-settings-dialog.ts`）获得在线可分享、可嵌入链接： 1. **登录校验**：`fetchUser()` 请求 `/api/id`；未登录引导登录 PlayCanvas 账号。 2. **填写设置**：标题、描述、是否公开列出（`listed`）。 3. **分片上传**：`PublishWriter` 经 `start-upload` → `signed-urls` → 分片 PUT → `complete-upload`。 4. **发布**：调用 `/splats/publish`，格式为 SOG；开启 `generateLods` 则为 `ssog`（多分辨率 LOD，加载更快）。 --- ## 源码结构与构建 常用脚本（`package.json`）： | 命令 | 作用 | |------|------| | `npm run build` | 生产构建（`rollup -c`） | | `npm run watch` | 仅监听构建 | | `npm run serve` | 仅启动静态服务器 | | `npm run develop` | watch + serve（日常开发入口） | | `npm run develop:auto-launch` | 开发并自动拉起浏览器 | | `npm run lint` | ESLint 检查 `src` | | `npm run lint:locales` | 校验语言文件（`scripts/check-locales.mjs`） | 其它位置：语言文件在 `static/locales/*.json`（i18next，`src/ui/localization.ts` 装配）；`rollup.config.mjs` 负责 TypeScript + node-resolve + SCSS + image/json，生产用 terser 压缩、strip 去调试。 --- ## 常见问题（FAQ） | 问题 | 解决 | |------|------| | 删除后文件没变小 | 删除只打标记，**导出时**才真正剔除；导出后点数才下降 | | 想恢复误删的点 | 用撤销（Undo）恢复 `deleted` 标记；导出前务必确认清理无误 | | 隐藏(hidden)与删除区别 | 隐藏的点默认仍会导出，删除的点导出时被剔除 | | 导出文件太大 | 删噪点 + 勾选 Compress PLY + 降低 SH Bands；Web 发布优先压缩 PLY、SOG 或 SPZ | | 本地开发看到旧版本 | 浏览器缓存：按 README 要求关闭网络缓存、清理应用缓存后刷新 | | `npm install` 失败 | 确认 Node ≥ 20.19.0（`package.json` engines 要求） | | 该用哪种格式 | 继续编辑/归档→PLY；网页加载→压缩 PLY / SOG / SPZ；交付演示→Viewer App（HTML/ZIP） | | 找不到 KSplat 导出 | v3.5 的导出类型里已无 `ksplat`，改用 splat / SOG / SPZ；`.ksplat` 只作为旧文件名识别保留 | | 原始 .ply 从哪来 | 3DGS 训练工具（COLMAP+gaussian-splatting、Postshot、Nerfstudio 等）产出 | --- ## AI 使用建议 - 用户提到「高斯泼溅 / 3DGS 编辑」「清理 .ply 噪点」「压缩高斯模型上网页」「SuperSplat 二次开发」时加载本技能。 - 区分**用工具**（在线 superspl.at/editor 的后期处理流程）与**改源码**（本地 `npm run develop` + 事件驱动架构）两类需求。 - 减体积一律建议「删除噪点 + Compress PLY + 降低 SH Bands」组合，并按目标查看器选格式（PLY / 压缩 PLY / splat / SOG / SPZ）。 - 本地开发看到旧页面先查浏览器缓存，而不是怀疑构建没跑。 - 二次开发强调通过 `src/events.ts` 的 `Events` 解耦，新增功能=注册事件+新增 PCUI 面板。 - **不要臆造**：导出类型只有 `ply` / `splat` / `sog` / `spz` / `viewer`（旧的 ksplat 已移除）；源码里没有 `src/sw.ts`，不要再引用 Service Worker 那套说法；模块名以仓库 `src/` 实际文件为准。 --- ## 相关技能 - **ara3d-sdk** — .NET 网格与 BIM 管线（与 3DGS 表示互为补充）：[../ara3d-sdk/SKILL.md](../ara3d-sdk/SKILL.md) - **photo-sphere-viewer** — Web 全景/虚拟导览（另一种「实景」展示路线）：[../photo-sphere-viewer/SKILL.md](../photo-sphere-viewer/SKILL.md) - **cesiumjs** — 3D 地球与大规模三维场景：[../../gis/cesiumjs/SKILL.md](../../gis/cesiumjs/SKILL.md) --- ## 参考资源 - 用户手册： - PlayCanvas 引擎： - 3DGS 论文：《3D Gaussian Splatting for Real-Time Radiance Field Rendering》(Inria, 2023) - 上游中文教程：（3d/supersplat 系列）