@playcanvas/splat-transform 0.10.2 → 0.12.0

package/README.md

@@ -11,8 +11,8 @@
 
 SplatTransform is an open source CLI tool for converting and editing Gaussian splats. It can:
 
-📥 Read PLY, Compressed PLY, SPLAT, KSPLAT, SPZ formats  
-📤 Write PLY, Compressed PLY, CSV, SOG and HTML viewer formats  
+📥 Read PLY, Compressed PLY, SPLAT, KSPLAT, SPZ, SOG (bundled .sog or unbundled meta.json) formats  
+📤 Write PLY, Compressed PLY, CSV, SOG (bundled or unbundled) and HTML viewer formats  
 🔗 Merge multiple splats  
 🔄 Apply transformations to input splats  
 🎛️ Filter out Gaussians or spherical harmonic bands
@@ -25,36 +25,28 @@ Install or update to the latest version:
 npm install -g @playcanvas/splat-transform
 ```
 
-> [!IMPORTANT]
-> **Windows Users:** You must have the debug version of the Microsoft Visual C++ runtime installed. This is because splat-transform currently depends on [Dawn](https://dawn.googlesource.com/dawn) which is built against the debug VC runtime. We have logged an [issue](https://issues.chromium.org/issues/443906265) against the Dawn project.
->
-> In the meantime, to work around this problem, you need to install the debug VC runtime as follows:
->
-> 1. Install [Visual Studio 2022 Community](https://visualstudio.microsoft.com/vs/community/)
-> 2. In the installer, select "Desktop development with C++"
-
 ## Usage
 
 ```bash
-splat-transform [GLOBAL]  <input.{ply|compressed.ply|splat|ksplat}> [ACTIONS]  ...  <output.{ply|compressed.ply|sog|meta.json|csv|html}> [ACTIONS]
+splat-transform [GLOBAL] input [ACTIONS]  ...  output [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
+- Input files become the working set; ACTIONS are applied in order
+- The last file is the output; actions after it modify the final result
 
 ## Supported Formats
 
 | Format | Input | Output | Description |
 | ------ | ----- | ------ | ----------- |
 | `.ply` | ✅ | ✅ | Standard PLY format |
+| `.sog` | ✅ | ✅ | Bundled super-compressed format (recommended) |
+| `meta.json` | ✅ | ✅ | Unbundled super-compressed format (accompanied by `.webp` textures) |
 | `.compressed.ply` | ✅ | ✅ | Compressed PLY format (auto-detected and decompressed on read) |
 | `.ksplat` | ✅ | ❌ | Compressed splat format (mkkellogg format) |
 | `.splat` | ✅ | ❌ | Compressed splat format (antimatter15 format) |
 | `.spz` | ✅ | ❌ | Compressed splat format (Niantic format) |
 | `.mjs` | ✅ | ❌ | Generate a scene using an mjs script (Beta) |
-| `.sog` | ❌ | ✅ | Bundled super-compressed format (recommended) |
-| `meta.json` | ❌ | ✅ | Unbundled super-compressed format (also outputs `.webp` images) |
 | `.csv` | ❌ | ✅ | Comma-separated values spreadsheet |
 | `.html` | ❌ | ✅ | Standalone HTML viewer app |
 ## Actions
@@ -62,26 +54,28 @@ splat-transform [GLOBAL]  <input.{ply|compressed.ply|splat|ksplat}> [ACTIONS]  .
 Actions can be repeated and applied in any order:
 
 ```bash
--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
--P, --params name=value[,name=value...] Pass parameters to .mjs generator script
+-t, --translate        <x,y,z>             Translate splats by (x, y, z).
+-r, --rotate           <x,y,z>             Rotate splats by Euler angles (x, y, z), in degrees.
+-s, --scale            <factor>            Uniformly scale splats by factor.
+-N, --filter-nan                           Remove Gaussians with NaN or Inf values.
+-V, --filter-value     <name,cmp,value>    Keep splats where <name> <cmp> <value>
+                                           cmp ∈ {lt,lte,gt,gte,eq,neq}
+-H, --filter-harmonics <0|1|2|3>           Remove spherical harmonic bands > n.
+-B, --filter-box       <mx,my,mz,Mx,My,Mz> Remove Gaussians outside box (min, max corners).
+-S, --filter-sphere    <x,y,z,radius>      Remove Gaussians outside sphere (center, radius).
+-p, --params           <key=val,...>       Pass parameters to .mjs generator script.
 ```
 
 ## Global Options
 
 ```bash
--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.
--p, --cameraPos                         Specify the viewer starting position. Default is 2,2,-2.
--e, --cameraTarget                      Specify the viewer starting target. Default is 0,0,0.
+-h, --help                                 Show this help and exit.
+-v, --version                              Show version and exit.
+-w, --overwrite                            Overwrite output file if it exists.
+-c, --cpu                                  Use CPU for spherical harmonic compression.
+-i, --iterations       <n>                 Iterations for SOG SH compression (more = better). Default: 10.
+-C, --camera-pos       <x,y,z>             HTML viewer camera position. Default: (2, 2, -2).
+-T, --camera-target    <x,y,z>             HTML viewer target position. Default: (0, 0, 0).
 ```
 
 ## Examples
@@ -111,8 +105,14 @@ splat-transform input.ply output.sog
 # Convert to SOG unbundled format
 splat-transform input.ply output/meta.json
 
+# Convert from SOG (bundled) back to PLY
+splat-transform scene.sog restored.ply
+
+# Convert from SOG (unbundled folder) back to PLY
+splat-transform output/meta.json restored.ply
+
 # Convert to HTML viewer with target and camera location
-splat-transform -a 0,0,0 -e 0,0,10 input.ply output.html
+splat-transform -C 0,0,0 -T 0,0,10 input.ply output.html
 ```
 
 ### Transformations
@@ -132,13 +132,13 @@ splat-transform input.ply -s 2 -t 1,0,0 -r 0,0,45 output.ply
 
 ```bash
 # Remove entries containing NaN and Inf
-splat-transform input.ply --filterNaN output.ply
+splat-transform input.ply --filter-nan output.ply
 
 # Filter by opacity values (keep only splats with opacity > 0.5)
-splat-transform input.ply -c opacity,gt,0.5 output.ply
+splat-transform input.ply -V opacity,gt,0.5 output.ply
 
 # Strip spherical harmonic bands higher than 2
-splat-transform input.ply --filterBands 2 output.ply
+splat-transform input.ply --filter-harmonics 2 output.ply
 ```
 
 ### Advanced Usage
@@ -148,7 +148,7 @@ splat-transform input.ply --filterBands 2 output.ply
 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 -p 0,0,10 -e 0.5
+splat-transform input1.ply input2.ply output.ply -t 0,0,10 -s 0.5
 ```
 
 ### Generators (Beta)
@@ -156,7 +156,7 @@ splat-transform input1.ply input2.ply output.ply -p 0,0,10 -e 0.5
 Generator scripts can be used to synthesize gaussian splat data. See [gen-grid.mjs](generators/gen-grid.mjs) for an example.
 
 ```bash
-splat-transform gen-grid.mjs -P width=10,height=10,scale=10,color=0.1 scenes/grid.ply -w
+splat-transform gen-grid.mjs -p width=10,height=10,scale=10,color=0.1 scenes/grid.ply -w
 ```
 
 ## Getting Help