@playcanvas/splat-transform 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +41 -34
  2. package/dist/index.mjs +2083 -691
  3. package/dist/index.mjs.map +1 -1
  4. package/package.json +17 -17
package/README.md CHANGED
@@ -7,15 +7,16 @@
7
7
  [![Reddit](https://img.shields.io/badge/Reddit-FF4500?style=flat&logo=reddit&logoColor=white&color=black)](https://www.reddit.com/r/PlayCanvas)
8
8
  [![X](https://img.shields.io/badge/X-000000?style=flat&logo=x&logoColor=white&color=black)](https://x.com/intent/follow?screen_name=playcanvas)
9
9
 
10
- | [User Guide](https://developer.playcanvas.com/user-manual/gaussian-splatting/editing/splat-transform/) | [Blog](https://blog.playcanvas.com/) | [Forum](https://forum.playcanvas.com/) | [Discord](https://discord.gg/RSaMRzg) |
10
+ | [User Guide](https://developer.playcanvas.com/user-manual/gaussian-splatting/editing/splat-transform/) | [Blog](https://blog.playcanvas.com/) | [Forum](https://forum.playcanvas.com/) |
11
11
 
12
12
  SplatTransform is an open source CLI tool for converting and editing Gaussian splats. It can:
13
13
 
14
- 📥 Read PLY, Compressed PLY, SPLAT, KSPLAT, SPZ, SOG (bundled .sog or unbundled meta.json) formats
15
- 📤 Write PLY, Compressed PLY, CSV, SOG (bundled or unbundled) and HTML viewer formats
14
+ 📥 Read PLY, Compressed PLY, SOG, SPLAT, KSPLAT and SPZ formats
15
+ 📤 Write PLY, Compressed PLY, SOG, CSV and HTML viewer formats
16
16
  🔗 Merge multiple splats
17
17
  🔄 Apply transformations to input splats
18
- 🎛️ Filter out Gaussians or spherical harmonic bands
18
+ 🎛️ Filter out Gaussians or spherical harmonic bands
19
+ ⚙️ Procedurally generate splats using JavaScript generators
19
20
 
20
21
  ## Installation
21
22
 
@@ -28,12 +29,12 @@ npm install -g @playcanvas/splat-transform
28
29
  ## Usage
29
30
 
30
31
  ```bash
31
- 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]
32
+ splat-transform [GLOBAL] input [ACTIONS] ... output [ACTIONS]
32
33
  ```
33
34
 
34
35
  **Key points:**
35
- - Every time an `*.ply*` appears, it becomes the current working set; the following ACTIONS are applied in the order listed
36
- - The last file on the command line is treated as the output; anything after it is interpreted as actions that modify the final result
36
+ - Input files become the working set; ACTIONS are applied in order
37
+ - The last file is the output; actions after it modify the final result
37
38
 
38
39
  ## Supported Formats
39
40
 
@@ -48,36 +49,39 @@ splat-transform [GLOBAL] <input.{ply|compressed.ply|splat|ksplat|spz|sog|meta.j
48
49
  | `.spz` | ✅ | ❌ | Compressed splat format (Niantic format) |
49
50
  | `.mjs` | ✅ | ❌ | Generate a scene using an mjs script (Beta) |
50
51
  | `.csv` | ❌ | ✅ | Comma-separated values spreadsheet |
51
- | `.html` | ❌ | ✅ | Standalone HTML viewer app |
52
+ | `.html` | ❌ | ✅ | Standalone HTML viewer app (embeds SOG format) |
53
+
52
54
  ## Actions
53
55
 
54
56
  Actions can be repeated and applied in any order:
55
57
 
56
- ```bash
57
- -t, --translate x,y,z Translate splats by (x, y, z)
58
- -r, --rotate x,y,z Rotate splats by euler angles (x, y, z), in degrees.
59
- -s, --scale x Uniformly scale splats by factor x.
60
- -n, --filterNaN Remove any Gaussian containing any NaN or Inf values.
61
- -c, --filterByValue name,cmp,value Keep splats where <name> <cmp> <value>
62
- cmp ∈ {lt,lte,gt,gte,eq,neq}
63
- -b, --filterBands n {0|1|2|3} Strip spherical-harmonic bands > n.
64
- -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).
65
- -o, --filterSphere x,y,z,radius Remove gaussians outside the bounding sphere centered at (x, y, z) with size radius.
66
- -P, --params name=value[,name=value...] Pass parameters to .mjs generator script.
58
+ ```none
59
+ -t, --translate <x,y,z> Translate splats by (x, y, z)
60
+ -r, --rotate <x,y,z> Rotate splats by Euler angles (x, y, z) in degrees
61
+ -s, --scale <factor> Uniformly scale splats by factor
62
+ -H, --filter-harmonics <0|1|2|3> Remove spherical harmonic bands > n
63
+ -N, --filter-nan Remove Gaussians with NaN or Inf values
64
+ -B, --filter-box <x,y,z,X,Y,Z> Remove Gaussians outside box (min, max corners)
65
+ -S, --filter-sphere <x,y,z,radius> Remove Gaussians outside sphere (center, radius)
66
+ -V, --filter-value <name,cmp,value> Keep splats where <name> <cmp> <value>
67
+ cmp ∈ {lt,lte,gt,gte,eq,neq}
68
+ -p, --params <key=val,...> Pass parameters to .mjs generator script
67
69
  ```
68
70
 
69
71
  ## Global Options
70
72
 
71
- ```bash
72
- -h, --help Show help and exit.
73
- -v, --version Show version and exit.
74
- -w, --overwrite Overwrite output file if it already exists.
75
- -g, --no-gpu Disable gpu when compressing spherical harmonics.
76
- -i, --iterations n Specify the number of iterations n when compressing spherical harmonics. More iterations generally lead to better results. Default is 10.
77
- -p, --cameraPos x,y,z Specify the viewer starting position. Default is (2, 2, -2).
78
- -e, --cameraTarget x,y,z Specify the viewer starting target. Default is (0, 0, 0).
73
+ ```none
74
+ -h, --help Show this help and exit
75
+ -v, --version Show version and exit
76
+ -w, --overwrite Overwrite output file if it exists
77
+ -c, --cpu Use CPU for SOG spherical harmonic compression
78
+ -i, --iterations <n> Iterations for SOG SH compression (more=better). Default: 10
79
+ -E, --viewer-settings <settings.json> HTML viewer settings JSON file
79
80
  ```
80
81
 
82
+ > [!NOTE]
83
+ > 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.
84
+
81
85
  ## Examples
82
86
 
83
87
  ### Basic Operations
@@ -111,8 +115,11 @@ splat-transform scene.sog restored.ply
111
115
  # Convert from SOG (unbundled folder) back to PLY
112
116
  splat-transform output/meta.json restored.ply
113
117
 
114
- # Convert to HTML viewer with target and camera location
115
- splat-transform -a 0,0,0 -e 0,0,10 input.ply output.html
118
+ # Convert to standalone HTML viewer
119
+ splat-transform input.ply output.html
120
+
121
+ # Convert to HTML viewer with custom settings
122
+ splat-transform -E settings.json input.ply output.html
116
123
  ```
117
124
 
118
125
  ### Transformations
@@ -132,13 +139,13 @@ splat-transform input.ply -s 2 -t 1,0,0 -r 0,0,45 output.ply
132
139
 
133
140
  ```bash
134
141
  # Remove entries containing NaN and Inf
135
- splat-transform input.ply --filterNaN output.ply
142
+ splat-transform input.ply --filter-nan output.ply
136
143
 
137
144
  # Filter by opacity values (keep only splats with opacity > 0.5)
138
- splat-transform input.ply -c opacity,gt,0.5 output.ply
145
+ splat-transform input.ply -V opacity,gt,0.5 output.ply
139
146
 
140
147
  # Strip spherical harmonic bands higher than 2
141
- splat-transform input.ply --filterBands 2 output.ply
148
+ splat-transform input.ply --filter-harmonics 2 output.ply
142
149
  ```
143
150
 
144
151
  ### Advanced Usage
@@ -148,7 +155,7 @@ splat-transform input.ply --filterBands 2 output.ply
148
155
  splat-transform -w cloudA.ply -r 0,90,0 cloudB.ply -s 2 merged.compressed.ply
149
156
 
150
157
  # Apply final transformations to combined result
151
- splat-transform input1.ply input2.ply output.ply -p 0,0,10 -e 0.5
158
+ splat-transform input1.ply input2.ply output.ply -t 0,0,10 -s 0.5
152
159
  ```
153
160
 
154
161
  ### Generators (Beta)
@@ -156,7 +163,7 @@ splat-transform input1.ply input2.ply output.ply -p 0,0,10 -e 0.5
156
163
  Generator scripts can be used to synthesize gaussian splat data. See [gen-grid.mjs](generators/gen-grid.mjs) for an example.
157
164
 
158
165
  ```bash
159
- splat-transform gen-grid.mjs -P width=10,height=10,scale=10,color=0.1 scenes/grid.ply -w
166
+ splat-transform gen-grid.mjs -p width=10,height=10,scale=10,color=0.1 scenes/grid.ply -w
160
167
  ```
161
168
 
162
169
  ## Getting Help