SplatTransform - 3D Gaussian Splat Converter

SplatTransform is an open source CLI tool and JavaScript module for reading gaussian splat PLY files and writing them to PLY, Compressed PLY, CSV, and SOGS format.

Multiple files may be combined and transformed before being written to the output.

Installation

CLI Usage

Install the package globally for CLI usage:

npm install -g @playcanvas/splat-transform

Module Usage

Install the package locally for module usage:

npm install @playcanvas/splat-transform

Then import and use in your code:

import { readPly, process, writeSogs, Vec3 } from "@playcanvas/splat-transform";

// Read and transform data
const fileData = await readPly(fileHandle);
const processed = process(fileData.elements[0].dataTable, [
  { kind: "scale", value: 0.5 },
  { kind: "translate", value: new Vec3(0, 0, 10) },
]);

// Write output
await writeSogs(outputFile, processed, "output.meta.json", 10, "cpu");

See README-MODULE.md for detailed module documentation.

Usage

splat-transform [GLOBAL]  <input.{ply|splat|ksplat}> [ACTIONS]  ...  <output.{ply|compressed.ply|meta.json|csv}> [ACTIONS]

Key points:

• Every time an *.ply* appears, it becomes the current working set; the following ACTIONS are applied in the order listed
• The last file on the command line is treated as the output; anything after it is interpreted as actions that modify the final result

Supported Formats

Input:

• .ply - Standard PLY format
• .splat - Binary splat format (antimatter15 format)
• .ksplat - Compressed binary splat format (mkkellogg format)

Output:

• .ply - Standard PLY format
• .compressed.ply - Compressed PLY format
• meta.json - SOGS format (JSON + WebP images)
• .csv - Comma-separated values

Actions

Actions can be repeated and applied in any order:

-t, --translate  x,y,z                  Translate splats by (x, y, z)
-r, --rotate     x,y,z                  Rotate splats by Euler angles (deg)
-s, --scale      x                      Uniformly scale splats by factor x
-n, --filterNaN                         Remove any Gaussian containing NaN/Inf
-c, --filterByValue name,cmp,value      Keep splats where <name> <cmp> <value>
                                        cmp ∈ {lt,lte,gt,gte,eq,neq}
-b, --filterBands  {0|1|2|3}            Strip spherical-harmonic bands > N

Global Options

-w, --overwrite                         Overwrite output file if it already exists
-h, --help                              Show help and exit
-v, --version                           Show version and exit
-g, --no-gpu                            Disable gpu when compressing spherical harmonics.
-i, --iterations  <number>              Specify the number of iterations when compressing spherical harmonics. More iterations generally lead to better results. Default is 10.

Examples

Basic Operations

# Simple format conversion
splat-transform input.ply output.csv

# 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

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

Transformations

# 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

Filtering

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

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

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

Advanced Usage

# Combine multiple files with different transforms
splat-transform -w cloudA.ply -r 0,90,0 cloudB.ply -s 2 merged.compressed.ply

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

Getting Help

# Show version
splat-transform --version

# Show help
splat-transform --help