SplatTransform

SplatTransform preserves tags for scenes trained with antialiasing or as 2DGS (2D Gaussian Splatting) where the output format supports it.

Detection (On Read):

• PLY: Uses header comments (e.g., SplatRenderMode: default | mip | 2dgs or antialiased 0 | 1).
• SPZ: Uses an antialiased header bit.
• SOG: Uses the "model" entry in meta.json.
• 2DGS Detection: A PLY with scale_0/scale_1 but no scale_2 is automatically read as 2DGS.

Preservation (On Write):

• .ply / .compressed.ply: Carries comment SplatRenderMode: mip | 2dgs.
• .sog / meta.json: Carries "model": "antialiased" | "2dgs".
• .spz: Sets its antialiased bit (Note: cannot represent 2DGS and will warn).
• Other formats: Tags are dropped silently.

Note: Combining inputs with different models will trigger a warning and the result will be written untagged.

The project provides two distinct decimation strategies for reducing Gaussian Splat size. The choice depends on your scene content:

• Uniform Decimation (--decimate-uniform / decimateSourceUniform()): Uses KL-style pairwise cost with a full-SH colour term. It performs a uniform 50% matching per level, meaning every region loses the same fraction of Gaussians. It has lower memory requirements and is better for scenes with uniformly-sized Gaussians, such as uniform textures, single objects, or snow.
• Adaptive Decimation (--decimate / decimateSource()): Uses field-L2 cost with a scale-free colour term and re-costed selection. Removal follows local error, allowing redundant regions to collapse deeper than distinct ones. It is superior for mixed-scale content and skies, but has a higher memory cost.

Render a splat scene to a lossless WebP image using GPU acceleration. Supports custom camera positioning, field of view, resolution, and advanced effects like defocus blur and motion blur.

Key Options:

• --camera-pos <x,y,z> / --camera-target <x,y,z>: Set camera view.
• --resolution <WxH>: Set output resolution.
• --background <r,g,b,a>: Set background color.
• --f-stop <n>: Enable defocus blur.
• --projection <equirect|perspective>: Set projection type (e.g., equirect for panoramas).
• --motion-samples <n> / --shutter <n>: Enable camera motion blur.

The CLI follows a specific pattern where input files form a working set, actions are applied in order, and the last file specified is the output. Actions can be placed after any input or output file.

Command Syntax:

splat-transform [GLOBAL] input [ACTIONS] ... output [ACTIONS]

Key Usage Rules:

• Input files: Become the working set.
• Actions: Applied in the order they appear.
• Output file: The last file in the command is the output. Actions appearing after the output file modify the final result.
• Discarding output: Use null as the output filename if you want to discard the file (useful when using --stats for analysis only).

Generate per-column statistics (min, max, median, mean, stdDev, nanCount, infCount, and histograms) for data analysis or automated quality gating. The fillRatio metric is particularly useful for detecting degenerate scenes that might overwhelm a GPU.

Use --stats with the following targets:

• <filename>: Print stats and write the processed file.
• null: Print stats only (discard output).
• json: Print stats in JSON format for scripting.

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

# Print stats without writing a file (discard output)
splat-transform input.ply --stats null

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

If you are modifying the uniform decimation logic and need to ensure it remains bit-for-bit compatible with the reference binary, use the tools/decimate-parity.mjs tool. This tool chains halvings through a reference binary and the current implementation, compares them byte-for-byte, and reports PSNR. It will exit with a non-zero code if any byte mismatch is found.

To run parity checks on specific scenes:

node tools/decimate-parity.mjs sky --ref splat-transform
node tools/decimate-parity.mjs snow --ref splat-transform

You can install SplatTransform as a global CLI tool for command-line conversions, or as a dependency for programmatic use in Node.js or browser environments.

To install the CLI globally:

npm install -g @playcanvas/splat-transform

To install as a library dependency:

npm install @playcanvas/splat-transform

When writing .sog, meta.json, lod-meta.json, or .html outputs, you can tune the Spherical Harmonics (SH) compression and parallelism using these options:

• -i, --sh-iterations <n>: Number of iterations for SH compression. Higher values improve quality. Default is 10.
• --max-workers <n>: Number of worker threads for SOG encoding. Setting this to 0 runs the process inline/serially. Default is 4.