CLI Reference
This page lists every SplatTransform command-line option, grouped the way splat-transform --help prints them. For worked examples, see the Overview and the task guides: Generating Streamed SOG, Collision Mesh Generation and Rendering Images.
Command Syntax
splat-transform [GLOBAL] input [ACTIONS] ... output [ACTIONS]
- Input files become the working set; ACTIONS are applied in order
- The last file is the output; actions after it modify the final result
- Use
nullas the output to discard file output (useful with--statsfor analysis-only runs) - Input filenames may also be
http(s)://URLs, downloaded on demand (.mjsgenerators must be local files)
Supported Formats
SplatTransform detects file format from the file extension:
| Format | Input | Output | Description |
|---|---|---|---|
.ply | ✅ | ✅ | Standard PLY format |
.sog | ✅ | ✅ | Bundled super-compressed SOG format (recommended) |
meta.json | ✅ | ✅ | Unbundled super-compressed format (accompanied by .webp textures). Output filename must be meta.json |
lod-meta.json | ✅ | ✅ | Multi-LOD Streamed SOG bundle (accompanied by per-LOD .sog chunks). Filename must be lod-meta.json |
.compressed.ply | ✅ | ✅ | Compressed PLY format (auto-detected and decompressed on read) |
.spz | ✅ | ✅ | Compressed SPZ splat format (Niantic format, v2–4) |
.lcc | ✅ | ❌ | LCC file format (XGRIDS) |
.lcc2 | ✅ | ❌ | LCC2 file format (XGRIDS, octree) |
.ksplat | ✅ | ❌ | Compressed splat format (mkkellogg format) |
.splat | ✅ | ❌ | Compressed splat format (antimatter15 format) |
.mjs | ✅ | ❌ | Generate a scene using an mjs script (Beta) |
.glb | ❌ | ✅ | Binary glTF with KHR_gaussian_splatting extension, loadable directly by the PlayCanvas Engine |
.csv | ❌ | ✅ | Comma-separated values spreadsheet |
.html | ❌ | ✅ | HTML viewer app (single-page or unbundled) based on SOG |
.voxel.json | ❌ | ✅ | Sparse voxel octree for collision detection. See the Collision Mesh guide. Output filename must end with .voxel.json (the prefix is up to you, e.g. room.voxel.json) |
.webp | ❌ | ✅ | Lossless WebP image rendered from a camera view via GPU rasterizer. See the Rendering Images guide |
null | ❌ | ✅ | Discard output (useful with --stats for analysis-only runs) |
Antialiased and 2DGS Scenes
Scenes trained with antialiasing (a mip-splatting style screen-space filter) or as 2D Gaussian surfels (2DGS) are tagged on read, and the tag is preserved wherever the output format can hold it. --info reports it as model.
- On read: a PLY header comment — Brush's
comment SplatRenderMode: default | mip | 2dgsor Postshot'scomment postshot.anti_aliasing=1(the last one wins) — the SPZ antialiased header bit, or themodelentry of a SOGmeta.json. A PLY withscale_0andscale_1but noscale_2is read as 2DGS regardless of comments, and the missing column is filled with a zero-thickness scale so the rest of the pipeline is unaffected. - On write:
.plyand.compressed.plycarrycomment SplatRenderMode: mip | 2dgs(Brush's spelling, whichever form was read);.sogandmeta.jsoncarry"model": "antialiased" | "2dgs";.spzsets its antialiased bit, and warns that it cannot represent 2DGS. A 2DGS PLY output drops thescale_2column again. Other output formats have nowhere to record the tag and drop it silently. - Rendering:
.webpoutput renders an antialiased scene with its training filter, 0.1 px² by default (--aa-filter-sizeoverrides it), instead of the 0.3 px² dilation, scaling opacity so each splat draws its unfiltered mass, as the PlayCanvas engine does. - Merging: combining inputs whose tags disagree warns and writes the result untagged.
A PLY's other header comments (for example Postshot v1.1.69 or postshot.color.eotf=sRGB) are carried through as well: .ply and .compressed.ply write them back as comment lines, and SOG version 3 output (.sog, meta.json, lod-meta.json) stores them as comments. They are not interpreted, so ones describing coordinates are not updated by transforms.
Opacity Above 1
Decimation merges Gaussians without losing their mass, so a merged Gaussian's opacity can exceed 1 (renderers draw it, up to 1.5625, as an opaque core). A PLY holds opacity as one property: the standard opacity logit (at most 1) for scenes that cannot exceed 1, or opacity_linear, the opacity itself, in place of opacity for decimated scenes and for SOG version 3 input that holds opacity above 1. Tools that don't know opacity_linear cannot read these files; --ply-logit-opacity writes the standard logit instead, clamping opacity above 1. On read, opacity_linear is used when present. SOG version 3 stores opacity above 1 directly; SOG version 2 and the other formats clamp it to 1.
Actions
Actions execute in the order specified and can be repeated. Any action may appear after any input or output file:
-t, --translate <x,y,z> Translate Gaussians by (x, y, z)
-r, --rotate <x,y,z> Rotate Gaussians by Euler angles (x, y, z), in degrees
-s, --scale <factor> Uniformly scale Gaussians by factor
-H, --filter-harmonics <0|1|2|3> Remove spherical harmonic bands > n
-N, --filter-nan Remove Gaussians with NaN values, most Inf values, or a
zero-norm (unrenderable) rotation quaternion;
retains -Infinity in scale_*
-B, --filter-box <x,y,z,X,Y,Z> Remove Gaussians outside box (min, max corners)
-S, --filter-sphere <x,y,z,radius> Remove Gaussians outside sphere (center, radius)
-V, --filter-value <name,cmp,value> Keep Gaussians where <name> <cmp> <value>
cmp ∈ {lt,lte,gt,gte,eq,neq}
opacity, scale_*, f_dc_* use transformed values
(linear opacity, above 1 for merged Gaussians, linear
scale, linear color 0-1). Append _raw for raw PLY values
(e.g. opacity_raw, the opacity logit).
-d, --decimate <n|n%> Simplify to n Gaussians via merge-based decimation,
removing at a uniform rate everywhere.
Use n% to keep a percentage of Gaussians.
Lower memory, and better at depth on uniformly-sized
Gaussians: uniform texture, single objects, snow.
--decimate-adaptive <n|n%> Simplify, allocating removal by local error instead.
Much better on mixed-scale content such as skies,
at higher memory cost.
Both are memory-bounded and streaming: they scale to
scenes of 100M+ Gaussians. Either must be the final
action, and the output must be .ply (write a decimated
PLY first, then convert in a second invocation).
--scratch-dir <path> Directory for intermediate levels when a deep decimation
target exceeds memory. Nothing is written without it.
-F, --filter-floaters [size,op,min] Remove Gaussians not contributing to any solid voxel.
Evaluates each Gaussian at occupied voxel centers.
Default: size=0.05, opacity=0.1, min=0.004 (1/255).
Bare flag (no value) uses all defaults.
-C, --filter-cluster [res,op,min] Keep only the connected cluster at --seed-pos.
GPU-voxelizes at coarse resolution (res world units/voxel).
Default: res=1.0, opacity=0.999, min=0.1.
Bare flag (no value) uses all defaults.
-p, --params <key=val,...> Pass parameters to .mjs generator script
-l, --tag-lod <n> Tag the Gaussians with LOD level n (n >= 0, or -1 for environment)
--stats [text|json] Print file info, per-column statistics and the fill/overdraw ratio to stdout. Default: text
--info [text|json] Print structural metadata (format, per-LOD counts, extra columns) to stdout. Default: text
-m, --morton-order Reorder Gaussians by Morton code (Z-order curve)
CLI Options
These options configure a run as a whole rather than operating on splat data — most groups apply only when reading or writing a specific format.
General Options
-h, --help Show this help and exit
-v, --version Show version and exit
-q, --quiet Suppress non-error output
--verbose Show debug-level diagnostics
--memory Show peak memory in progress output
--tty Interactive bar rendering (default on a TTY; --no-tty to disable)
-w, --overwrite Overwrite output file if it exists
--webp-effort <0-9> Lossless WebP compression effort for image, SOG, HTML and LOD output.
Higher tries harder to reduce size. Default: libwebp's default
lossless settings.
GPU Options
Select the device used for GPU work. See Which Features Need a GPU below for what runs on it.
--list-gpus List available GPU adapters and exit
-g, --gpu <n|cpu> Device for GPU operations: GPU adapter index | 'cpu'
('cpu' disables GPU and is incompatible with
GPU-only features like --filter-cluster)
--gpu-backend <name> Force the WebGPU backend: vulkan | d3d12 | metal.
Default: the platform default (e.g. vulkan works around
Dawn D3D12 bugs on Windows)
Which Features Need a GPU
All GPU work goes through WebGPU. Some features cannot run without it:
--filter-clusterand--filter-floaters..voxel.jsonoutput and--collision-mesh..webpimage output, including--camera-trackframe sequences.
Others use the GPU by default but also run on the CPU with -g cpu:
--decimateand--decimate-adaptive.- SOG output (
.sog,meta.json,lod-meta.jsonand.html). The only step that uses the GPU is k-means clustering of the spherical harmonic coefficients, so inputs without SH bands (for example.splatfiles, or anything passed through--filter-harmonics 0) are written entirely on the CPU. Inputs with SH bands also work with-g cpu, but SH clustering is often 5-10x slower without a GPU.
Selecting a Device
# List available GPU adapters
splat-transform --list-gpus
# Let WebGPU automatically choose the best GPU (default behavior)
splat-transform input.ply output.sog
# Explicitly select a GPU adapter by index
splat-transform -g 0 input.ply output.sog # Use first listed adapter
splat-transform -g 1 input.ply output.sog # Use second listed adapter
# Use the CPU instead (much slower for SH compression, but always available)
splat-transform -g cpu input.ply output.sog
# Force the Vulkan backend (e.g. to work around Dawn D3D12 bugs on Windows)
splat-transform --gpu-backend vulkan input.ply output.sog
When -g is not specified, WebGPU automatically selects the best available GPU. Use --list-gpus to list available adapters with their indices and names. The order and availability of adapters depend on your system and GPU drivers. --gpu-backend also applies to --list-gpus, which then lists only that backend's adapters.
To run splat-transform on a server with an NVIDIA GPU, see the Docker Backend guide.
SOG Compression Options
Apply when writing .sog, meta.json, lod-meta.json, or .html outputs.
-i, --sh-iterations <n> Iterations for SH compression (more=better). Default: 10
--sh-palette-size <n> SH palette entries for .sog / meta.json (more=better, slower). Up to 262144
with SOG v3, 65536 with v2. Default: one per 1024 gaussians, at most 65536
--max-workers <n> Worker threads for SOG and image-sequence encoding (0 = inline/serial). Default: 4
--sog-version <2|3> SOG format version to write. 2 is for older viewers: it drops opacity
above 1, blind data and a 4th SH band. Default: 3 (.html always embeds 2)
--sog-blind <field>[,...] Store columns as per-gaussian blind data (v3): one blind texture per flag,
its fields filling 4 bytes (R,G,B,A) in order. field = <col>[:<enc>]
enc: u8 u16 u24 u32 (unsigned integers), f16 f32 (float bits),
unorm8 unorm16 (float in [0,1], or unorm8[min,max]). Default: the
fewest-byte uint that fits. Repeatable, e.g. --sog-blind id
--sog-blind a:unorm8,b:unorm8,depth:f16
--sog-extras <file.json> Store this JSON as the output's extras (meta.json / lod-meta.json,
SOG v3 only), application-defined data as in glTF. Default: the input's
extras, if any
SPZ Output Options
Apply when writing .spz outputs.
--spz-version <3|4> The SPZ format version to write. Default: 4
PLY Output Options
Apply when writing .ply outputs.
--ply-logit-opacity Write the standard opacity logit even when some gaussian's opacity
exceeds 1 (clamped to 1), instead of opacity_linear. For tools that
don't read opacity_linear
HTML Viewer Output Options
Apply when writing .html outputs.
--viewer-settings <settings.json> HTML viewer settings JSON file
--unbundled Generate unbundled HTML viewer with separate files
See the SuperSplat Viewer Settings Schema for details on how to pass data to the --viewer-settings option. The settings are validated before the page is written, so an invalid file fails the run instead of producing a viewer that renders nothing.
LOD Input Options
Apply when reading lod-meta.json, .lcc, and .lcc2 files.
-L, --select-lod <n,n,...> Comma-separated LOD levels to read from streamed SOG / LCC / LCC2 input
LOD Output Options
Apply when writing lod-meta.json (Streamed SOG output).
--lod-chunk-count <n> Approximate number of Gaussians per LOD chunk in K. Default: 512
--lod-chunk-extent <n> Approximate size of an LOD chunk in world units (m). Default: 16
--lod-chunk-min <n> Gaussians in K below which a chunk is not split for extent. Default: 8
A chunk is split when it holds more than --lod-chunk-count Gaussians, or when it is wider than --lod-chunk-extent and holds more than --lod-chunk-min. The minimum keeps sparse regions such as sky or distant background from being cut into thousands of near-empty chunks: below it, a region stays one chunk however wide it is. Dense regions are unaffected.
See Generating Streamed SOG for an end-to-end walkthrough.
Voxel Output Options
Apply when writing .voxel.json (sparse voxel octree for collision detection). See the Collision Mesh guide for a deep dive on each step and tuning.
--voxel-size <n> Voxel size for .voxel.json. Default: 0.05
--voxel-opacity <n> Voxel opacity threshold for .voxel.json. Default: 0.1
--voxel-external-fill [size] Seal exterior voxels via boundary flood fill (interior scenes).
[size] (world units) is the dilation distance applied
before the flood fill to bridge small wall gaps.
--seed-pos is used to verify the volume is enclosed at
the seed; the fill is skipped if the seed is reachable
from outside.
Default size: 1.6
--voxel-floor-fill [size] Fill each column upward from bottom until hitting solid (exterior scenes).
Optional size (world units): only patch XZ areas surrounded by floor
within 2*size; large empty exterior areas are left alone.
Default size: 1.6
--voxel-carve [h,r] Carve navigable space using capsule flood fill from seed.
Default: height=1.6, radius=0.2
--seed-pos <x,y,z> Seed position for voxel fill/carve and --filter-cluster.
Default: 0,0,0
--collision-mesh [smooth|faces] Generate collision mesh (.collision.glb). Default: smooth
Image Output Options
Apply when writing .webp (lossless WebP rendered via GPU rasterizer). See the Rendering Images guide for examples of each effect.
--projection <pinhole|equirect> Camera projection. Default: pinhole.
equirect = 360°×180° panorama from --camera-pos; --camera-fov must be
omitted; --resolution must be 2:1 (default 2048x1024).
--camera-pos <x,y,z> Camera position in world space. Default: 2,1,-2
--camera-target <x,y,z> Camera target point. Default: 0,0,0
--camera-up <x,y,z> World up vector. Default: 0,1,0
--camera-fov <degrees> Vertical field of view in degrees. Default: 60. Rejected with --projection equirect.
--resolution <WxH> Output resolution, e.g. 1920x1080. Default: 1280x720 (pinhole) or 2048x1024 (equirect)
--camera-near <n> Near clip distance. Default: 0.2 (matches reference 3DGS)
--background <r,g,b[,a]> Background color in [0,1]. Default: 0,0,0,1
--no-compensation Clamp opacity above 1 (from decimation) to 1 and draw every
gaussian at opacity <= 1. For debugging and A/B comparison.
--aa-filter-size <px²> Screen-space filter of scenes trained with anti-aliasing (splat model
antialiased), used in place of the 0.3 px² dilation. Default: 0.1
--f-stop <N> Aperture as a photographic f-stop (e.g. 2.8, 5.6, 11). Enables defocus blur;
smaller = more blur. Pinhole only. Default: disabled (no defocus).
--focus-distance <n> Camera-space Z of the focus plane (world units). Default: distance to --camera-target.
Pinhole only; only meaningful with --f-stop.
--dof-samples <n> Aperture samples per instant with --f-stop. Default: 32. More samples reduce
sampling artifacts at greater cost; multiplies --motion-samples when combined.
--sensor-size <n> Vertical sensor height in world units. Gives --f-stop a physical meaning.
Default: 0.024 (35mm full-frame, world units = meters). Scale to your world:
world unit = decimeter → 0.24, world unit = millimeter → 24.
--camera-pos-end <x,y,z> End camera position. When set, enables camera motion blur: the camera moves
from --camera-pos (shutter open) to --camera-pos-end (shutter close) and the
frame averages renders at instants across the shutter. Default: disabled.
--camera-target-end <x,y,z> End camera target. Default: same as --camera-target. Only with --camera-pos-end.
--camera-up-end <x,y,z> End up vector. Default: same as --camera-up. Only with --camera-pos-end.
--shutter <0..1> Fraction of the start→end segment averaged, centered on its midpoint. Default: 0.5.
With --camera-track, fraction of the frame interval averaged around each frame.
Default for tracks: off. 1.0 = full interval; 0.5 = 180° shutter.
--motion-samples <n> Renders averaged per motion-blurred frame, at evenly spaced instants across
the shutter. Cost is N× a single render; too few show as discrete copies
where the motion between instants exceeds a couple of pixels. Default: 16.
--camera-track <path> Render a camera animation as a frame sequence: a SuperSplat editor project
(.ssproj directory or its document.json), a viewer settings.json with
animTracks, or a JSON { frameRate, frames: [{ position, target, fov, up }] }.
Frames are written as <name>.NNNN.webp. Replaces --camera-pos/--camera-target;
the track's target is the defocus focus point. A frame's up vector tilts the
camera; frames without one use --camera-up. With --shutter, each frame is
motion-blurred over that fraction of the frame interval.
--frames <a[-b]> Inclusive frame range of the track to render. Default: all frames.
See Also
- Splat File Formats — specifications for the PLY, SOG, Streamed SOG, GLB and SPZ formats.
- Voxel Format — specification of
.voxel.json/.voxel.binoutput. - Library Usage — the same operations from JavaScript.