@playcanvas/splat-transform 0.16.1 → 1.0.0

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2011-2025 PlayCanvas Ltd.
+Copyright (c) 2011-2026 PlayCanvas Ltd.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -9,15 +9,18 @@
 
 | [User Guide](https://developer.playcanvas.com/user-manual/gaussian-splatting/editing/splat-transform/) | [Blog](https://blog.playcanvas.com/) | [Forum](https://forum.playcanvas.com/) |
 
-SplatTransform is an open source CLI tool for converting and editing Gaussian splats. It can:
+SplatTransform is an open source library and CLI tool for converting and editing Gaussian splats. It can:
 
 📥 Read PLY, Compressed PLY, SOG, SPLAT, KSPLAT, SPZ and LCC formats  
 📤 Write PLY, Compressed PLY, SOG, CSV, HTML Viewer and LOD (streaming) formats  
+📊 Generate statistical summaries for data analysis  
 🔗 Merge multiple splats  
 🔄 Apply transformations to input splats  
 🎛️ Filter out Gaussians or spherical harmonic bands  
 ⚙️ Procedurally generate splats using JavaScript generators
 
+The library is platform-agnostic and can be used in both Node.js and browser environments.
+
 ## Installation
 
 Install or update to the latest version:
@@ -26,7 +29,13 @@ Install or update to the latest version:
 npm install -g @playcanvas/splat-transform
 ```
 
-## Usage
+For library usage, install as a dependency:
+
+```bash
+npm install @playcanvas/splat-transform
+```
+
+## CLI Usage
 
 ```bash
 splat-transform [GLOBAL] input [ACTIONS]  ...  output [ACTIONS]
@@ -35,6 +44,7 @@ splat-transform [GLOBAL] input [ACTIONS]  ...  output [ACTIONS]
 **Key points:**
 - 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 `null` as output to discard file output
 
 ## Supported Formats
 
@@ -68,6 +78,7 @@ Actions can be repeated and applied in any order:
                                           cmp ∈ {lt,lte,gt,gte,eq,neq}
 -p, --params           <key=val,...>    Pass parameters to .mjs generator script
 -l, --lod              <n>              Specify the level of detail of this model, n >= 0.
+-m, --summary                           Print per-column statistics to stdout
 ```
 
 ## Global Options
@@ -169,6 +180,23 @@ splat-transform -w cloudA.ply -r 0,90,0 cloudB.ply -s 2 merged.compressed.ply
 splat-transform input1.ply input2.ply output.ply -t 0,0,10 -s 0.5
 ```
 
+### Statistical Summary
+
+Generate per-column statistics for data analysis or test validation:
+
+```bash
+# Print summary, then write output
+splat-transform input.ply --summary output.ply
+
+# Print summary without writing a file (discard output)
+splat-transform input.ply -m null
+
+# Print summary before and after a transform
+splat-transform input.ply --summary -s 0.5 --summary output.ply
+```
+
+The summary includes min, max, median, mean, stdDev, nanCount and infCount for each column in the data.
+
 ### Generators (Beta)
 
 Generator scripts can be used to synthesize gaussian splat data. See [gen-grid.mjs](generators/gen-grid.mjs) for an example.
@@ -211,3 +239,134 @@ splat-transform --version
 # Show help
 splat-transform --help
 ```
+
+---
+
+## Library Usage
+
+SplatTransform exposes a programmatic API for reading, processing, and writing Gaussian splat data.
+
+### Basic Import
+
+```typescript
+import {
+    readFile,
+    writeFile,
+    getInputFormat,
+    getOutputFormat,
+    DataTable,
+    processDataTable
+} from '@playcanvas/splat-transform';
+```
+
+### Key Exports
+
+| Export | Description |
+| ------ | ----------- |
+| `readFile` | Read splat data from various formats |
+| `writeFile` | Write splat data to various formats |
+| `getInputFormat` | Detect input format from filename |
+| `getOutputFormat` | Detect output format from filename |
+| `DataTable`, `Column` | Core data structures for splat data |
+| `combine` | Merge multiple DataTables into one |
+| `transform` | Apply spatial transformations |
+| `processDataTable` | Apply a sequence of processing actions |
+| `computeSummary` | Generate statistical summary of data |
+
+### File System Abstractions
+
+The library uses abstract file system interfaces for maximum flexibility:
+
+**Reading:**
+- `UrlReadFileSystem` - Read from URLs (browser/Node.js)
+- `MemoryReadFileSystem` - Read from in-memory buffers
+- `ZipReadFileSystem` - Read from ZIP archives
+
+**Writing:**
+- `MemoryFileSystem` - Write to in-memory buffers
+- `ZipFileSystem` - Write to ZIP archives
+
+### Example: Reading and Processing
+
+```typescript
+import { Vec3 } from 'playcanvas';
+import {
+    readFile,
+    writeFile,
+    getInputFormat,
+    getOutputFormat,
+    processDataTable,
+    UrlReadFileSystem,
+    MemoryFileSystem
+} from '@playcanvas/splat-transform';
+
+// Read a PLY file from URL
+const fileSystem = new UrlReadFileSystem();
+const inputFormat = getInputFormat('scene.ply');
+
+const dataTables = await readFile({
+    filename: 'https://example.com/scene.ply',
+    inputFormat,
+    options: { iterations: 10 },
+    params: [],
+    fileSystem
+});
+
+// Apply transformations
+const processed = processDataTable(dataTables[0], [
+    { kind: 'scale', value: 0.5 },
+    { kind: 'translate', value: new Vec3(0, 1, 0) },
+    { kind: 'filterNaN' }
+]);
+
+// Write to in-memory buffer
+const memFs = new MemoryFileSystem();
+const outputFormat = getOutputFormat('output.ply', {});
+
+await writeFile({
+    filename: 'output.ply',
+    outputFormat,
+    dataTable: processed,
+    options: {}
+}, memFs);
+
+// Get the output data
+const outputBuffer = memFs.files.get('output.ply');
+```
+
+### Processing Actions
+
+The `processDataTable` function accepts an array of actions:
+
+```typescript
+type ProcessAction =
+    | { kind: 'translate'; value: Vec3 }
+    | { kind: 'rotate'; value: Vec3 }       // Euler angles in degrees
+    | { kind: 'scale'; value: number }
+    | { kind: 'filterNaN' }
+    | { kind: 'filterByValue'; columnName: string; comparator: 'lt'|'lte'|'gt'|'gte'|'eq'|'neq'; value: number }
+    | { kind: 'filterBands'; value: 0|1|2|3 }
+    | { kind: 'filterBox'; min: Vec3; max: Vec3 }
+    | { kind: 'filterSphere'; center: Vec3; radius: number }
+    | { kind: 'lod'; value: number }
+    | { kind: 'summary' };
+```
+
+### Custom Logging
+
+Configure the logger for your environment:
+
+```typescript
+import { logger } from '@playcanvas/splat-transform';
+
+logger.setLogger({
+    log: console.log,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug,
+    progress: (text) => process.stdout.write(text),
+    output: console.log
+});
+
+logger.setQuiet(true); // Suppress non-error output
+```

package/bin/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
 
-import { main } from '../dist/index.mjs';
+import { main } from '../dist/cli.mjs';
 
 await main();

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+declare const main: () => Promise<never>;
+export { main };

package/dist/cli/node-device.d.ts

@@ -0,0 +1,7 @@
+import { GraphicsDevice } from 'playcanvas';
+declare const enumerateAdapters: () => Promise<{
+    index: number;
+    name: string;
+}[]>;
+declare const createDevice: (adapterName?: string) => Promise<GraphicsDevice>;
+export { createDevice, enumerateAdapters };

package/dist/cli/node-file-system.d.ts

@@ -0,0 +1,16 @@
+import { type ReadFileSystem, type ProgressCallback, type ReadSource } from '../lib/io/read';
+import { type FileSystem, type Writer } from '../lib/io/write';
+/**
+ * ReadFileSystem for reading from the local filesystem using Node.js fs module.
+ */
+declare class NodeReadFileSystem implements ReadFileSystem {
+    createSource(filename: string, progress?: ProgressCallback): Promise<ReadSource>;
+}
+/**
+ * FileSystem for writing to the local filesystem using Node.js fs module.
+ */
+declare class NodeFileSystem implements FileSystem {
+    createWriter(filename: string): Promise<Writer>;
+    mkdir(path: string): Promise<void>;
+}
+export { NodeReadFileSystem, NodeFileSystem };