Skip to main content

How to use Splat Transform

This guide helps you install splat-transform and provides a set of useful commands that you can use in different situations.

Prerequisite​

To use the following commands, you need npm. Install it for your device using the official guide:

NPM Installation Guide

If you already have npm installed, open your shell or terminal and verify the installation by running:

npm -v

If the output shows a version number such as 11.4.2, npm is installed correctly. If the command is not recognized, npm was not installed properly.

In addition to that you need the SplatTransform CLI Tool from PlayCanvas. You can install splat-transform using the following command to install the framework globally:

npm install -g @playcanvas/splat-transform

Check your installation afterwards via the command

splat-transform --version

The output should be again a Version number such as 0.15

Before you start​

Before you start working with your assets, keep the following points in mind to make using the CLI tool easier:

  1. Avoid spaces in folder and file names so you don’t have to escape special characters.
  2. Open the terminal/shell inside the target folder so you don’t need to type full paths
    (Windows/macOS: right-click → Open Terminal).
  3. Try to avoid using the -w parameter, as it may overwrite files you did not intend to replace.

Basic Usage​

General usage of splat-transform:

splat-transform input [ACTIONS BEFORE] output [ACTIONS AFTERWARDS]
  • ACTIONS BEFORE are all filters or operations that run before the conversion or file creation.
  • ACTIONS AFTERWARDS are all filters or operations that run after the conversion or file creation.

Useful Actions​

Open Overview of Parameters​

If you need an overview of all available parameters inside the console, use the following command:

splat-transform -h

Filter NaN Gaussians​

It is recommended to add the --filter-nan or -N flag to remove Gaussians that contain NaN or Inf values.

Example:

splat-transform your-file.ply -N  your-output-filename.ply

Overwrite Existing Files​

If you forgot a parameter or need to quickly replace an already generated file or folder, you can either delete it manually or simply overwrite it using:

splat-transform your-file.ply -w your-file.ply

Filter Harmonics​

When generating a low-resolution PLY for collisions, it's recommended to remove all harmonics. The following command strips all SH harmonics:

splat-transform your-file.ply -H 0 your-output-file.ply
Want to learn more?

Additional parameter descriptions can be found on the official Page of SplatTransform CLI Tool of PlayCanvas.

SOG Generation​

Open the terminal or shell in your current directory otherwise you need to navigate to the folder where the PLY is located.

Following Command converts your PLY to an SOG if you are in the current directory

splat-transform your-file.ply your-output-filename.sog

Following Command converts your .compressed.ply to an SOG if you are in the current directory

splat-transform your-file.compressed.ply your-output-filename.sog

LOD Generation​

A step-by-step Guide can be found in section Prepare Your LOD Files.

Generate Collision for LCC and LOD​

To create a collision, a small workaround is currently required, since integration of the .lci collision file has not yet been implemented.

important

This workaround works for both LOD and LCC.

Workaround with LCC Dataset:

  1. Open the LCC inside a text editor (windows: notepad, mac:notes or TextEdit)
  2. Search for the term totalLevel
  3. Use this number and subtract it by 1 (e.g. totalLevel: 7 would be 6)
  4. Use following Command to generate a low-resolution PLY 
splat-transform your-lcc-data.lcc -O 6 low-resolution.ply

Optional: If you want also to include your environment use this command:

splat-transform your-lcc-data.lcc -O 6 -E environment.bin low-resolution.ply
  1. Upload the low-resolution version of your splat as a separate entity and generate a Collision
  2. Download the collision and add it to your LCC

Workaround with PLY Dataset:

  1. Generate a low-resolution version of your splat.
  2. Upload a low-resolution version of your splat (approx. 1-2 million splats) as a separate entity (preferably in a separate space)
  3. Use the "Generate Collision" button on that entity to create the collision mesh.
  4. Download or locate the generated collision file.
  5. Upload this collision file to your LOD entity.