SplatTransform

SplatTransform 是开源转换编辑库和 CLI，为格式转换、变换、过滤、碰撞生成和统计提供精确控制，平台无关，可运行于 Node.js 与浏览器。

开源

在 GitHub 以 MIT 开源。

更喜欢网页界面？

superspl.at/convert 的 Convert 是 Web 前端，通过 WebAssembly 本地执行相同操作，无需安装。一次性转换可用界面，脚本批处理用 CLI。

为什么使用？

可解决：

🔄 格式广泛：PLY、SPZ、SOG、流式 SOG，以及 glTF、CSV、独立 HTML 和 WebP，完整列表。 🛠️ 精确变换：平移、旋转、缩放。 🧹 智能过滤：NaN/Inf、值、盒、球、球谐阶数、漂浮点贡献，以及种子点附近连通簇。 📐 简化与重排：内存受限的合并简化，统一或误差自适应，可扩展到亿级；Morton 排序改善局部性。 🧱 碰撞生成：稀疏体素八叉树及运行时物理用 .collision.glb。 🖼️ 图像渲染：可配置视角的无损 WebP、全景、散焦、运动模糊，以及相机轨迹帧序列。 📊 统计：--stats、--info 的逐列与结构信息，用于分析、验证和发布门槛。 📦 合并场景。 ⚙️ 生成器：JavaScript 程序化数据。 🆓 开源：MIT，GitHub 免费提供。

安装

安装或更新最新版：

npm install -g @playcanvas/splat-transform

库用法安装为依赖：

npm install @playcanvas/splat-transform

验证 CLI：

splat-transform --version

Docker 后端及 GPU/Vulkan 配置见 Docker 指南。

快速开始

PLY 转 SOG 用于 Web：

splat-transform scene.ply scene.sog

格式由扩展名识别，操作放在对应文件后并按顺序执行。下面先缩放、上移一单位、去无效单元，再输出：

splat-transform scene.ply -s 0.5 -t 0,1,0 --filter-nan scene.sog

-w 允许覆盖。通式 splat-transform [GLOBAL] input [ACTIONS] ... output [ACTIONS]，详见语法和格式。

指南

CLI 参考：全部选项、格式和 GPU 要求。
流式 SOG：从单 PLY 生成多 LOD。
碰撞网格：体素与物理数据。
图像渲染：视角、全景、景深、模糊、动画。
库用法：Node/浏览器编程，完整 API。
Docker：后端 GPU/Vulkan。

格式本身见数据格式与体素规范，引擎使用流式结果见 LOD 加载。

示例

格式转换

# Convert from .splat format
splat-transform input.splat output.ply

# Convert from .ksplat format
splat-transform input.ksplat output.ply

# Convert to compressed PLY
splat-transform input.ply output.compressed.ply

# Uncompress a compressed PLY back to standard PLY
# (compressed .ply is detected automatically on read)
splat-transform input.compressed.ply output.ply

# Convert to SOG bundled format
splat-transform input.ply output.sog

# Convert to SOG unbundled format
splat-transform input.ply output/meta.json

# Convert from SOG (bundled) back to PLY
splat-transform scene.sog restored.ply

# Convert from SOG (unbundled folder) back to PLY
splat-transform output/meta.json restored.ply

# Convert to standalone HTML viewer (bundled, single file)
splat-transform input.ply output.html

# Convert to unbundled HTML viewer (separate CSS, JS, and SOG files)
splat-transform --unbundled input.ply output.html

# Convert to HTML viewer with custom settings
splat-transform --viewer-settings settings.json input.ply output.html

整个目录需逐文件调用：

# Convert existing KSPLAT assets to PlayCanvas SOG
for file in *.ksplat; do
  splat-transform "$file" "${file%.ksplat}.sog"
done

变换

# Scale and translate
splat-transform bunny.ply -s 0.5 -t 0,0,10 bunny_scaled.ply

# Rotate by 90 degrees around Y axis
splat-transform input.ply -r 0,90,0 output.ply

# Chain multiple transformations
splat-transform input.ply -s 2 -t 1,0,0 -r 0,0,45 output.ply

过滤

# Remove entries containing NaN and Inf
splat-transform input.ply --filter-nan output.ply

# Filter by opacity values (keep only splats with opacity > 0.5)
splat-transform input.ply -V opacity,gt,0.5 output.ply

# Strip spherical harmonic bands higher than 2
splat-transform input.ply --filter-harmonics 2 output.ply

# Clean a raw capture and write it straight to SOG for production
splat-transform raw_capture.ply --filter-nan --filter-harmonics 2 production/capture.sog

--filter-floaters 和 --filter-cluster 在 GPU 体素化后移除散点。碰撞指南展示按种子隔离连通场景，同样适用于数据文件输出。

简化

--decimate 通过合并以统一比例减少到目标数量；--decimate-adaptive 按局部误差分配，更适合天空等混合尺度，但内存更高。均必须是最后操作且输出 PLY，其他格式需第二次转换。

# Simplify to 50000 splats via merge-based decimation
splat-transform input.ply --decimate 50000 output.ply

# Simplify to 25% of original splat count
splat-transform input.ply -d 25% output.ply

# Allocate removal by local error (better on mixed-scale content such as skies)
splat-transform input.ply --decimate-adaptive 25% output.ply

# Then convert the decimated PLY for delivery
splat-transform output.ply output.sog

# Deep target on a huge scene: give the intermediate levels somewhere to go
splat-transform huge.ply -d 1% --scratch-dir /mnt/scratch output.ply

内存预算为机器一半 RAM，最多 48 GiB。巨大场景的深度简化中间层超预算时默认报错；设置 --scratch-dir 可写临时 PLY，消费后删除。

简化也用于生成流式 SOG的低细节层。

合并

列多个输入，输入后的操作仅作用该文件，输出后的操作作用合并结果：

# Place each scene before merging
splat-transform \
  environment.ply \
  character.ply -t 2,0,1 -r 0,180,0 \
  props.ply -t -3,0,2 -s 1.2 \
  complete_scene.ply

# Apply final transformations to the combined result
splat-transform input1.ply input2.ply output.ply -t 0,0,10 -s 0.5

检查场景

--info 打印格式、是否确为高斯数据、总数与逐 LOD 数、球谐阶数、抗锯齿或 2DGS 标记、额外列。--stats 再附逐列统计：

# Check what a file contains without writing anything
splat-transform input.ply --info null

# Print stats, then write output
splat-transform input.ply --stats output.ply

# Print stats as JSON for scripting
splat-transform input.ply --stats json null

# Print stats before and after a transform
splat-transform input.ply --stats -s 0.5 --stats output.ply

# Export the cleaned-up data for analysis in a spreadsheet
splat-transform scene.ply --filter-nan -V opacity,gt,0.05 quality_analysis.csv

普通点云 PLY 等可读但非高斯容器的 gaussian 为 false。每 LOD 统计 min、max、median、mean、stdDev、nanCount、infCount 和直方图。fillRatio 为总覆盖面积除以稳健 p1–p99 横截面，近似平均重叠层数。正常场景通常个位到数百，退化或恶意数据可能高数个数量级，可用作自动发布检查。+Infinity 缩放导致无限比率，JSON 为 null，应拒绝。JSON 保留 info 字段并附逐 LOD stats。单次流式计算，median 用 1024 桶近似，误差约列范围千分之一，其余精确。

生成器（测试版）

JavaScript 程序化生成，参见示例脚本。

splat-transform gen-grid.mjs -p width=10,height=10,scale=10,color=0.1 scenes/grid.ply -w

获取帮助

splat-transform --help

问题、功能请求和贡献请到 GitHub，欢迎错误报告和拉取请求。

为什么使用？​

安装​

快速开始​

指南​

示例​

格式转换​

变换​

过滤​

简化​

合并​

检查场景​

生成器（测试版）​

获取帮助​