@playcanvas/splat-transform 2.0.4 → 2.0.6

package/README.md

@@ -69,7 +69,7 @@ splat-transform [GLOBAL] input [ACTIONS]  ...  output [ACTIONS]
 
 ## Actions
 
-Actions can be repeated and applied in any order:
+Actions execute in the order specified and can be repeated. Any action may appear after any input or output file:
 
 ```none
 -t, --translate        <x,y,z>          Translate Gaussians by (x, y, z)
@@ -89,17 +89,19 @@ Actions can be repeated and applied in any order:
                                           Use n% to keep a percentage of Gaussians
 -G, --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)
+                                          Default: size=0.05, opacity=0.1, min=0.004 (1/255).
+                                          Bare flag (no value) uses all defaults.
 -D, --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
+                                          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, --lod              <n>              Specify the level of detail, n >= 0
+-l, --lod              <n>              Tag the Gaussians with LOD level n (n >= 0)
 -m, --summary                           Print per-column statistics to stdout
 -M, --morton-order                      Reorder Gaussians by Morton code (Z-order curve)
 ```
 
-## Global Options
+## General Options
 
 ```none
 -h, --help                              Show this help and exit
@@ -109,29 +111,80 @@ Actions can be repeated and applied in any order:
     --mem                               Show memory usage in progress output
     --tty                               Interactive bar rendering (default on a TTY; --no-tty to disable)
 -w, --overwrite                         Overwrite output file if it exists
--i, --iterations       <n>              Iterations for SOG SH compression (more=better). Default: 10
+```
+
+## GPU Options
+
+Used by SOG compression and GPU voxelization (`--filter-cluster`, `--filter-floaters`, `.voxel.json` output).
+
+```none
 -L, --list-gpus                         List available GPU adapters and exit
--g, --gpu              <n|cpu>          Select device for SOG compression: GPU adapter index | 'cpu'
+-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)
+```
+
+## SOG Compression Options
+
+Apply when writing `.sog`, `meta.json`, `lod-meta.json`, or `.html` outputs.
+
+```none
+-i, --iterations       <n>              Iterations for SH compression (more=better). Default: 10
+```
+
+## HTML Viewer Output Options
+
+Apply when writing `.html` outputs.
+
+```none
 -E, --viewer-settings  <settings.json>  HTML viewer settings JSON file
 -U, --unbundled                         Generate unbundled HTML viewer with separate files
+```
+
+> [!NOTE]
+> See the [SuperSplat Viewer Settings Schema](https://github.com/playcanvas/supersplat-viewer?tab=readme-ov-file#settings-schema) for details on how to pass data to the `-E` option.
+
+## LCC Input Options
+
+Apply when reading `.lcc` files.
+
+```none
 -O, --lod-select       <n,n,...>        Comma-separated LOD levels to read from LCC input
+```
+
+## LOD Output Options
+
+Apply when writing `lod-meta.json` (multi-LOD streaming SOG bundle).
+
+```none
 -C, --lod-chunk-count  <n>              Approximate number of Gaussians per LOD chunk in K. Default: 512
 -X, --lod-chunk-extent <n>              Approximate size of an LOD chunk in world units (m). Default: 16
-    --voxel-params     [size,opacity]   Voxel size and opacity threshold for .voxel.json. Default: 0.05,0.1
-    --voxel-external-fill [size]        Fill exterior voxels by dilation from seed. Default size: 1.6
-    --voxel-floor-fill [radius]         Fill each column upward from bottom until hitting solid (runs before carve).
+```
+
+## Voxel Output Options
+
+Apply when writing `.voxel.json` (sparse voxel octree for collision detection). See the [Collision Mesh Guide](guides/COLLISION.md) for a deep dive on each step and tuning.
+
+```none
+    --voxel-params     [size,opacity]   Voxel size and opacity threshold. Default: 0.05,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 [radius]         Fill each column upward from bottom until hitting solid (exterior scenes).
                                           Optional radius (world units): only patch XZ areas surrounded by floor
                                           within 2*radius; large empty exterior areas are left alone.
                                           Default radius: 1.6
-    --voxel-carve [h,r]                 Carve navigable space using capsule flood fill from seed.
+    --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 processing and --filter-cluster. Default: 0,0,0
--K, --collision-mesh [smooth|faces]     Generate collision mesh (.collision.glb). Default shape: smooth.
+    --seed-pos         <x,y,z>          Seed position for voxel fill/carve and --filter-cluster.
+                                          Default: 0,0,0
+-K, --collision-mesh   [smooth|faces]   Generate collision mesh (.collision.glb). Default: smooth
 ```
 
-> [!NOTE]
-> See the [SuperSplat Viewer Settings Schema](https://github.com/playcanvas/supersplat-viewer?tab=readme-ov-file#settings-schema) for details on how to pass data to the `-E` option.
-
 ## Examples
 
 ### Basic Operations
@@ -244,22 +297,54 @@ splat-transform gen-grid.mjs -p width=10,height=10,scale=10,color=0.1 scenes/gri
 
 ### Voxel Format
 
-The voxel format stores sparse voxel octree data for collision detection. It consists of two files: `.voxel.json` (metadata) and `.voxel.bin` (binary octree data).
+The voxel format stores sparse voxel octree data for collision detection. It consists of two files: `.voxel.json` (metadata) and `.voxel.bin` (binary octree data). Pass `-K` to also emit a `.collision.glb` mesh derived from the voxel grid.
+
+For a step-by-step walkthrough of each option (with illustrations), see the [Collision Mesh Guide](guides/COLLISION.md).
+
+#### Recommended pipeline
 
 ```bash
-# Generate voxel collision data from a splat file
-splat-transform input.ply output.voxel.json
+splat-transform input.ply \
+    --filter-cluster --seed-pos x,y,z \
+    [--voxel-external-fill | --voxel-floor-fill] [--voxel-carve] \
+    [-K [smooth|faces]] \
+    output.voxel.json
+```
 
-# Generate voxel data with custom resolution and opacity threshold
-splat-transform --voxel-params 0.1,0.3 input.ply output.voxel.json
+`--filter-cluster` isolates the central scene and discards stray floaters before voxelization. `--seed-pos` is shared by `--filter-cluster` and the voxel fill/carve passes — set it once to a known-walkable point inside the scene.
 
-# Generate voxel data with exterior fill and carve
-splat-transform --voxel-external-fill --voxel-carve input.ply output.voxel.json
+#### Interior scenes (rooms, indoor scans)
+
+Use `--voxel-external-fill` to seal the void around the room interior, then `--voxel-carve` to hollow out the navigable space:
+
+```bash
+splat-transform room.ply \
+    --filter-cluster --seed-pos 0,1,0 \
+    --voxel-external-fill --voxel-carve \
+    -K room.voxel.json
+```
+
+#### Exterior scenes (outdoor objects, terrain)
+
+Use `--voxel-floor-fill` to fill the ground beneath surfaces, optionally followed by `--voxel-carve`:
+
+```bash
+splat-transform terrain.ply \
+    --filter-cluster --seed-pos 0,0,0 \
+    --voxel-floor-fill \
+    -K terrain.voxel.json
+```
+
+#### Other examples
+
+```bash
+# Voxelize with custom resolution and opacity threshold
+splat-transform --voxel-params 0.1,0.3 input.ply output.voxel.json
 
-# Generate voxel data with custom seed position and carve parameters
+# Custom carve capsule (height, radius)
 splat-transform --seed-pos 1,0,0 --voxel-carve 2.0,0.3 input.ply output.voxel.json
 
-# Generate voxel data with a watertight voxel-face collision mesh
+# Watertight voxel-face collision mesh
 splat-transform -K faces input.ply output.voxel.json
 ```
 

package/dist/cli.mjs

@@ -17494,11 +17494,11 @@ class CompressedChunk {
 /**
  * The splat-transform version (semver MAJOR.MINOR.PATCH).
  */
-const version = '2.0.4';
+const version = '2.0.6';
 /**
  * The splat-transform revision (short Git hash of HEAD at build time).
  */
-const revision = 'fa46db3';
+const revision = 'aa3dbae';
 
 const generatedByString = `Generated by splat-transform ${version}`;
 const chunkProps = [
@@ -19486,13 +19486,17 @@ class GpuDilation {
         // Extract: clear bufferA, dispatch extract from sparse src into bufferA.
         this.dispatchClear(slot, slot.bufferA, numWords);
         this.dispatchExtract(slot, minBx, minBy, minBz, outerBx, outerBy, outerBz, numXWords);
-        // Tiny throwaway readback forces a queue submit between extract
-        // and dilate. WITHOUT this, atomicOr writes from the extract pass
-        // aren't reliably visible to the next dilate pass (apparent
-        // missing memory barrier in PlayCanvas/Dawn for cross-pass atomic
-        // writes). Promise is intentionally not awaited — only the
-        // implicit submit+barrier matters. 16 bytes ≈ negligible PCIe.
-        slot.bufferA.read(0, 16, null, true).catch(() => { });
+        // Force a queue submission boundary between the extract pass (which
+        // writes bufferA via atomicOr — bound as `storage, read_write` with
+        // `array<atomic<u32>>`) and the dilate-X pass (which reads bufferA
+        // bound as `storage, read` with `array<u32>`). Without this, the
+        // atomic writes are not reliably visible to the next pass — dilation
+        // produces empty output. Other inter-pass transitions in this
+        // pipeline (clear→extract, dilateX→Z→Y, Y→compact) rely on automatic
+        // intra-encoder synchronization without issue. Verified raw Dawn
+        // synchronizes this case correctly, so the bug is somewhere in
+        // PlayCanvas's compute dispatch / bind-group path.
+        this.device.submit();
         // X-pass: A → B
         this.dispatchX(slot, slot.bufferA, slot.bufferB, numXWords, outerNy, outerNz, halfExtentXZ);
         // Z-pass: B → A
@@ -20907,8 +20911,16 @@ const binIndices = (parent, lod) => {
  */
 const writeLod = async (options, fs) => {
     const { filename, iterations, createDevice, chunkCount, chunkExtent } = options;
-    const dataTable = convertToSpace(options.dataTable, Transform.IDENTITY, true);
-    const envDataTable = options.envDataTable ? convertToSpace(options.envDataTable, Transform.IDENTITY, true) : null;
+    // Operate in PLY space so per-leaf bounds in tree.bound are in the same
+    // coordinate frame as the SOG chunk data emitted by writeSog (which also
+    // converts to Transform.PLY). Without this, view-dependent streaming
+    // built on tree.bound picks the wrong chunks because the bounds are
+    // 180°-Z-rotated relative to the splat positions inside them.
+    // This intentionally mutates the input tables to avoid doubling peak
+    // memory during LOD export. Callers should treat writeLod as consuming its
+    // DataTable inputs.
+    const dataTable = convertToSpace(options.dataTable, Transform.PLY, true);
+    const envDataTable = options.envDataTable ? convertToSpace(options.envDataTable, Transform.PLY, true) : null;
     const outputDir = dirname(filename);
     // ensure top-level output folder exists
     await fs.mkdir(outputDir);
@@ -26420,8 +26432,14 @@ const voxelizeToBuffer = async (bvh, gpuVoxelization, gridBounds, voxelResolutio
     const buffer = new BlockMaskBuffer();
     const bStride = numBlocksX * numBlocksY;
     const batchSize = 16;
-    const MEGA_MAX_BATCHES = 512;
-    const MEGA_MAX_INDICES = 4 * 1024 * 1024;
+    // Caps for one mega-flush. Sized to keep a single compute dispatch's
+    // wall-clock comfortably under Windows D3D12 TDR (~2s watchdog) on slower
+    // GPUs without materially affecting throughput on fast GPUs (the
+    // double-buffered slots keep the GPU fed across the extra flushes).
+    // Output is bit-identical regardless: each batch's full Gaussian list rides
+    // with it, and slot buffers grow on demand to accommodate any oversize batch.
+    const MEGA_MAX_BATCHES = 256;
+    const MEGA_MAX_INDICES = 2 * 1024 * 1024;
     const maxBlocks = GpuVoxelization.MAX_BLOCKS_PER_BATCH;
     const numSlots = GpuVoxelization.NUM_SLOTS;
     const slotIndexArrays = [];
@@ -28227,21 +28245,32 @@ const cropToNavigable = (grid, gridBounds, voxelResolution) => {
         return { grid, gridBounds };
     }
     const { minBx, minBy, minBz, maxBx, maxBy, maxBz } = navBounds;
-    const cropMaxBx = maxBx + 1;
-    const cropMaxBy = maxBy + 1;
-    const cropMaxBz = maxBz + 1;
-    if (minBx === 0 && minBy === 0 && minBz === 0 &&
+    // Pad by 1 block on each side so the cropped grid retains the solid wall
+    // blocks immediately surrounding the navigable cavity. Matches the
+    // MARGIN = 1 pattern used by carve() before this re-crop strips it. The
+    // collision-mesh extractors treat out-of-grid as empty, so without this
+    // padding the mesh has holes wherever the cavity reaches the cropped
+    // boundary; with it, the mesh extractor sees a real SOLID→EMPTY
+    // transition at the cavity edge and emits a sealed wall there.
+    const MARGIN = 1;
+    const cropMinBx = Math.max(0, minBx - MARGIN);
+    const cropMinBy = Math.max(0, minBy - MARGIN);
+    const cropMinBz = Math.max(0, minBz - MARGIN);
+    const cropMaxBx = Math.min(nbx, maxBx + 1 + MARGIN);
+    const cropMaxBy = Math.min(nby, maxBy + 1 + MARGIN);
+    const cropMaxBz = Math.min(nbz, maxBz + 1 + MARGIN);
+    if (cropMinBx === 0 && cropMinBy === 0 && cropMinBz === 0 &&
         cropMaxBx === nbx && cropMaxBy === nby && cropMaxBz === nbz) {
         return { grid, gridBounds };
     }
     const cropBar = logger.bar('Cropping grid', grid.types.length);
-    const croppedGrid = grid.cropTo(minBx, minBy, minBz, cropMaxBx, cropMaxBy, cropMaxBz, done => cropBar.update(done));
+    const croppedGrid = grid.cropTo(cropMinBx, cropMinBy, cropMinBz, cropMaxBx, cropMaxBy, cropMaxBz, done => cropBar.update(done));
     cropBar.end();
     const blockSize = 4 * voxelResolution;
-    const croppedMin = new Vec3(gridBounds.min.x + minBx * blockSize, gridBounds.min.y + minBy * blockSize, gridBounds.min.z + minBz * blockSize);
+    const croppedMin = new Vec3(gridBounds.min.x + cropMinBx * blockSize, gridBounds.min.y + cropMinBy * blockSize, gridBounds.min.z + cropMinBz * blockSize);
     const croppedBounds = {
         min: croppedMin,
-        max: new Vec3(croppedMin.x + (cropMaxBx - minBx) * blockSize, croppedMin.y + (cropMaxBy - minBy) * blockSize, croppedMin.z + (cropMaxBz - minBz) * blockSize)
+        max: new Vec3(croppedMin.x + (cropMaxBx - cropMinBx) * blockSize, croppedMin.y + (cropMaxBy - cropMinBy) * blockSize, croppedMin.z + (cropMaxBz - cropMinBz) * blockSize)
     };
     return { grid: croppedGrid, gridBounds: croppedBounds };
 };
@@ -28368,13 +28397,27 @@ const writeVoxel = async (options, fs) => {
         gpuVoxelization = new GpuVoxelization(device);
         gpuVoxelization.uploadAllGaussians(pcDataTable, extentsResult.extents);
         // Align grid bounds to block boundaries BEFORE voxelization so the
-        // block coordinates used during voxelization match what the reader expects.
-        // When fillExterior runs, pad by halfExtent + 1 voxels per side so the
-        // boundary-face flood seeds survive the dilation (notably below the floor).
+        // block coordinates used during voxelization match what the reader
+        // expects. fillExterior and fillFloor both need a margin of empty
+        // voxels outside the splat's tight 3-sigma extents to do their job:
+        // fillExterior so the boundary-face flood seeds survive its dilation
+        // (notably below the floor), fillFloor so its column walk has empty
+        // XZ columns to convert into wall pillars and the dilation halo to
+        // extend the floor footprint outward.
+        //
+        // Lateral pad combines both as `dilation_radius + 1` voxels per side.
+        // Vertical pad is only contributed by exteriorPad — fillFloor's
+        // dilation is XZ-only, and Y padding would extend the wall pillars
+        // above the splat's natural ceiling and below its floor.
         const exteriorPad = hasFillExterior ?
             (Math.ceil(navExteriorRadius / voxelResolution) + 1) * voxelResolution :
             0;
-        let gridBounds = alignGridBounds(bounds.min.x - exteriorPad, bounds.min.y - exteriorPad, bounds.min.z - exteriorPad, bounds.max.x + exteriorPad, bounds.max.y + exteriorPad, bounds.max.z + exteriorPad, voxelResolution);
+        const floorPad = hasFloorFill ?
+            (Math.ceil(floorFillDilation / voxelResolution) + 1) * voxelResolution :
+            0;
+        const padXZ = Math.max(exteriorPad, floorPad);
+        const padY = exteriorPad;
+        let gridBounds = alignGridBounds(bounds.min.x - padXZ, bounds.min.y - padY, bounds.min.z - padXZ, bounds.max.x + padXZ, bounds.max.y + padY, bounds.max.z + padXZ, voxelResolution);
         const buffer = await voxelizeToBuffer(bvh, gpuVoxelization, gridBounds, voxelResolution, opacityCutoff);
         bvh = null;
         pcDataTable = null;
@@ -29051,6 +29094,17 @@ const createDevice = async (adapterName) => {
         stencil: false
     });
     await graphicsDevice.createDevice();
+    // Surface Dawn's device-lost reason directly. PlayCanvas logs this only via
+    // Debug.warn (debug builds) and then attempts to recreate the device, which
+    // can fail noisily (e.g. DXGI_ERROR_DEVICE_REMOVED on D3D12 TDR) and bury
+    // the original cause. Skip the `destroyed` reason — that fires on intentional
+    // device.destroy() during normal shutdown.
+    // @ts-ignore - wgpu is private on WebgpuGraphicsDevice but exposed in practice
+    graphicsDevice.wgpu?.lost?.then((info) => {
+        if (info?.reason === 'destroyed')
+            return;
+        logger.error(`WebGPU device was lost: reason=${info.reason || 'unknown'}, message=${info.message || '(none)'}`);
+    });
     return graphicsDevice;
 };
 
@@ -29706,98 +29760,71 @@ SUPPORTED INPUTS
 SUPPORTED OUTPUTS
     .ply   .compressed.ply   .sog   meta.json   lod-meta.json   .glb   .csv   .html   .voxel.json   null
 
-ACTIONS (can be repeated, in any order)
+ACTIONS (executed in order; can be repeated)
     -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
+    -r, --rotate           <x,y,z>          Rotate Gaussians by Euler angles, 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 and most Inf values;
-                                              retains +Infinity in opacity and -Infinity in scale_*
+    -N, --filter-nan                        Remove Gaussians with NaN values and most Inf values
     -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>
+    -S, --filter-sphere    <x,y,z,radius>   Remove Gaussians outside sphere
+    -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 0-1, linear scale, linear color 0-1).
-                                              Append _raw for raw PLY values (e.g. opacity_raw).
-    -F, --decimate         <n|n%>           Simplify to n Gaussians via progressive pairwise merging
-                                              Use n% to keep a percentage of Gaussians
-    -G, --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)
-    -D, --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
+    -F, --decimate         <n|n%>           Simplify to n (or n%) Gaussians via pairwise merging
+    -G, --filter-floaters  [size,op,min]    Remove Gaussians not contributing to any solid voxel. Default: 0.05,0.1,0.004
+    -D, --filter-cluster   [res,op,min]     Keep only the connected cluster at --seed-pos. Default: 1.0,0.999,0.1
     -p, --params           <key=val,...>    Pass parameters to .mjs generator script
-    -l, --lod              <n>              Specify the level of detail, n >= 0
+    -l, --lod              <n>              Tag the Gaussians with LOD level n (n >= 0)
     -m, --summary                           Print per-column statistics to stdout
     -M, --morton-order                      Reorder Gaussians by Morton code (Z-order curve)
 
-GLOBAL OPTIONS
+GENERAL
     -h, --help                              Show this help and exit
     -v, --version                           Show version and exit
     -q, --quiet                             Suppress non-error output
         --verbose                           Show debug-level diagnostics
         --mem                               Show peak memory in progress output
-        --tty                               Interactive bar rendering (default on a TTY; --no-tty to disable)
+        --tty                               Interactive bar rendering (--no-tty to disable)
     -w, --overwrite                         Overwrite output file if it exists
-    -i, --iterations       <n>              Iterations for SOG SH compression (more=better). Default: 10
-    -L, --list-gpus                         List available GPU adapters and exit
-    -g, --gpu              <n|cpu>          Select device for SOG compression: GPU adapter index | 'cpu'
-    -E, --viewer-settings  <settings.json>  HTML viewer settings JSON file
-    -U, --unbundled                         Generate unbundled HTML viewer with separate files
-    -O, --lod-select       <n,n,...>        Comma-separated LOD levels to read from LCC input
-    -C, --lod-chunk-count  <n>              Approximate number of Gaussians per LOD chunk in K. Default: 512
-    -X, --lod-chunk-extent <n>              Approximate size of an LOD chunk in world units (m). Default: 16
-        --voxel-params     [size,opacity]   Voxel size and opacity threshold for .voxel.json. Default: 0.05,0.1
-        --voxel-external-fill [size]        Fill exterior voxels by dilation from seed. Default size: 1.6
-        --voxel-floor-fill [size]           Fill below-floor voxels by upward column walk from bottom. Default size: 1.6
-        --voxel-carve [h,r]                 Carve navigable space using capsule flood fill from seed. Default: 1.6,0.2
-        --seed-pos         <x,y,z>          Seed position for voxel processing and --filter-cluster. Default: 0,0,0
-    -K, --collision-mesh   [smooth|faces]   Generate collision mesh (.collision.glb). Default shape: smooth
-
-EXAMPLES
-    # Scale then translate
-    splat-transform bunny.ply -s 0.5 -t 0,0,10 bunny-scaled.ply
-
-    # Merge two files with transforms and compress to SOG format
-    splat-transform -w cloudA.ply -r 0,90,0 cloudB.ply -s 2 merged.sog
 
-    # Generate unbundled HTML viewer with separate CSS, JS and SOG files
-    splat-transform -U bunny.ply bunny-viewer.html
-
-    # Generate synthetic splats using a generator script
-    splat-transform gen-grid.mjs -p width=500,height=500,scale=0.1 grid.ply
-
-    # Generate LOD with custom chunk size and node split size
-    splat-transform -O 0,1,2 -C 1024 -X 32 input.lcc output/lod-meta.json
+GPU (used by SOG compression and GPU voxelization: --filter-cluster, --filter-floaters, .voxel.json output)
+    -L, --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)
 
-    # Generate voxel data
-    splat-transform input.ply output.voxel.json
+SOG COMPRESSION (.sog, meta.json, lod-meta.json, .html outputs)
+    -i, --iterations       <n>              SH compression iterations (more=better). Default: 10
 
-    # Generate voxel data with collision mesh
-    splat-transform -K input.ply output.voxel.json
+HTML VIEWER OUTPUT (.html)
+    -E, --viewer-settings  <settings.json>  HTML viewer settings JSON file
+    -U, --unbundled                         Generate unbundled HTML viewer with separate files
 
-    # Generate voxel data with voxel-face collision mesh
-    splat-transform -K faces input.ply output.voxel.json
+LCC INPUT (.lcc)
+    -O, --lod-select       <n,n,...>        Comma-separated LOD levels to read
 
-    # Generate voxel data with custom resolution and opacity threshold
-    splat-transform --voxel-params 0.1,0.3 input.ply output.voxel.json
+LOD OUTPUT (lod-meta.json)
+    -C, --lod-chunk-count  <n>              Approximate Gaussians per LOD chunk in K. Default: 512
+    -X, --lod-chunk-extent <n>              Approximate LOD chunk size in world units. Default: 16
 
-    # Generate voxel data with exterior fill and carve
-    splat-transform --voxel-external-fill --voxel-carve input.ply output.voxel.json
+VOXEL OUTPUT (.voxel.json)
+        --voxel-params     [size,opacity]   Voxel size + opacity threshold. Default: 0.05,0.1
+        --voxel-external-fill [size]        Seal exterior voxels via boundary flood fill (interior scenes). Default: 1.6
+        --voxel-floor-fill [radius]         Fill columns upward from bottom (exterior scenes). Default: 1.6
+        --voxel-carve      [h,r]            Carve navigable space via capsule flood fill from seed. Default: 1.6,0.2
+        --seed-pos         <x,y,z>          Seed position for voxel fill/carve and --filter-cluster. Default: 0,0,0
+    -K, --collision-mesh   [smooth|faces]   Generate collision mesh (.collision.glb). Default: smooth
 
-    # Generate voxel data with custom seed position and carve parameters
-    splat-transform --seed-pos 1,0,0 --voxel-carve 2.0,0.3 input.ply output.voxel.json
+EXAMPLES
+    # Convert formats
+    splat-transform input.ply output.sog
 
-    # Print statistical summary, then write output
-    splat-transform bunny.ply --summary output.ply
+    # Merge files with transforms
+    splat-transform -w a.ply -r 0,90,0 b.ply -s 2 merged.sog
 
-    # Print summary without writing a file (discard output)
-    splat-transform bunny.ply -m null
+    # Generate voxel collision data
+    splat-transform input.ply --filter-cluster output.voxel.json
 
-    # Read input from a URL and write to a local file
-    splat-transform https://example.com/scene.ply scene.sog
+    More examples: https://github.com/playcanvas/splat-transform#examples
 `;
 const main = async () => {
     const startTime = performance.now();