@playcanvas/splat-transform 0.10.2 → 0.11.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,18 +25,10 @@ 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.{ply|compressed.ply|splat|ksplat|spz|sog|meta.json|mjs}> [ACTIONS]  ...  <output.{ply|compressed.ply|sog|meta.json|csv|html}> [ACTIONS]
 ```
 
 **Key points:**
@@ -48,13 +40,13 @@ splat-transform [GLOBAL]  <input.{ply|compressed.ply|splat|ksplat}> [ACTIONS]  .
 | 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
+-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         x                   Uniformly scale splats by factor x.
+-n, --filterNaN                         Remove any Gaussian containing any NaN or Inf values.
 -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
+-b, --filterBands   n {0|1|2|3}         Strip spherical-harmonic bands > n.
+-x, --filterBox     mx,my,mz,Mx,My,Mz   Remove gaussians outside the bounding box given its min (mx, my, mz) and max (Mx, My, Mz).
+-o, --filterSphere  x,y,z,radius        Remove gaussians outside the bounding sphere centered at (x, y, z) with size radius.
+-P, --params name=value[,name=value...] 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
+-h, --help                              Show help and exit.
+-v, --version                           Show version and exit.
+-w, --overwrite                         Overwrite output file if it already exists.
 -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.
+-i, --iterations    n                   Specify the number of iterations n when compressing spherical harmonics. More iterations generally lead to better results. Default is 10.
+-p, --cameraPos     x,y,z               Specify the viewer starting position. Default is (2, 2, -2).
+-e, --cameraTarget  x,y,z               Specify the viewer starting target. Default is (0, 0, 0).
 ```
 
 ## Examples
@@ -111,6 +105,12 @@ 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
 ```