@playcanvas/splat-transform 0.17.1 → 1.1.0

package/dist/lib/data-table/combine.d.ts

@@ -1,3 +1,19 @@
 import { DataTable } from './data-table';
+/**
+ * Combines multiple DataTables into a single DataTable.
+ *
+ * Merges rows from all input tables. Columns are matched by name and type;
+ * columns that don't exist in all tables will have undefined values for
+ * rows from tables lacking that column.
+ *
+ * @param dataTables - Array of DataTables to combine.
+ * @returns A new DataTable containing all rows from all input tables.
+ *
+ * @example
+ * ```ts
+ * const combined = combine([tableA, tableB, tableC]);
+ * console.log(combined.numRows); // tableA.numRows + tableB.numRows + tableC.numRows
+ * ```
+ */
 declare const combine: (dataTables: DataTable[]) => DataTable;
 export { combine };

package/dist/lib/data-table/data-table.d.ts

@@ -1,5 +1,23 @@
+/**
+ * Union of all typed array types supported for column data.
+ */
 type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
+/**
+ * String identifiers for typed array element types.
+ */
 type ColumnType = 'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'float32' | 'float64';
+/**
+ * A named column of typed array data within a DataTable.
+ *
+ * Columns store homogeneous numeric data efficiently using JavaScript typed arrays.
+ *
+ * @example
+ * ```ts
+ * const positions = new Column('x', new Float32Array([1.0, 2.0, 3.0]));
+ * console.log(positions.name);     // 'x'
+ * console.log(positions.dataType); // 'float32'
+ * ```
+ */
 declare class Column {
     name: string;
     data: TypedArray;
@@ -7,9 +25,39 @@ declare class Column {
     get dataType(): ColumnType | null;
     clone(): Column;
 }
+/**
+ * A row object mapping column names to numeric values.
+ * @ignore
+ */
 type Row = {
     [colName: string]: number;
 };
+/**
+ * A table of columnar data representing Gaussian splat properties.
+ *
+ * DataTable is the core data structure for splat data. Each column represents
+ * a property (e.g., position, rotation, color) as a typed array, and all columns
+ * must have the same number of rows.
+ *
+ * Standard columns include:
+ * - Position: `x`, `y`, `z`
+ * - Rotation: `rot_0`, `rot_1`, `rot_2`, `rot_3` (quaternion)
+ * - Scale: `scale_0`, `scale_1`, `scale_2` (log scale)
+ * - Color: `f_dc_0`, `f_dc_1`, `f_dc_2` (spherical harmonics DC)
+ * - Opacity: `opacity` (logit)
+ * - Spherical Harmonics: `f_rest_0` through `f_rest_44`
+ *
+ * @example
+ * ```ts
+ * const table = new DataTable([
+ *     new Column('x', new Float32Array([0, 1, 2])),
+ *     new Column('y', new Float32Array([0, 0, 0])),
+ *     new Column('z', new Float32Array([0, 0, 0]))
+ * ]);
+ * console.log(table.numRows);    // 3
+ * console.log(table.numColumns); // 3
+ * ```
+ */
 declare class DataTable {
     columns: Column[];
     constructor(columns: Column[]);

package/dist/lib/data-table/summary.d.ts

@@ -1,17 +1,50 @@
 import { DataTable } from './data-table';
+/**
+ * Statistical summary for a single column.
+ */
 type ColumnStats = {
+    /** Minimum value (excluding NaN/Inf). */
     min: number;
+    /** Maximum value (excluding NaN/Inf). */
     max: number;
+    /** Median value. */
     median: number;
+    /** Arithmetic mean. */
     mean: number;
+    /** Standard deviation. */
     stdDev: number;
+    /** Count of NaN values. */
     nanCount: number;
+    /** Count of Infinity values. */
     infCount: number;
 };
+/**
+ * Statistical summary for an entire DataTable.
+ */
 type SummaryData = {
+    /** Summary format version. */
     version: number;
+    /** Total number of rows. */
     rowCount: number;
+    /** Per-column statistics keyed by column name. */
     columns: Record<string, ColumnStats>;
 };
+/**
+ * Computes statistical summary for all columns in a DataTable.
+ *
+ * For each column, calculates min, max, median, mean, standard deviation,
+ * and counts of NaN/Infinity values. Useful for data validation and analysis.
+ *
+ * @param dataTable - The DataTable to analyze.
+ * @returns Summary data with per-column statistics.
+ *
+ * @example
+ * ```ts
+ * const summary = computeSummary(dataTable);
+ * console.log(summary.rowCount);
+ * console.log(summary.columns['x'].mean);
+ * console.log(summary.columns['opacity'].nanCount);
+ * ```
+ */
 declare const computeSummary: (dataTable: DataTable) => SummaryData;
 export { computeSummary, type ColumnStats, type SummaryData };

package/dist/lib/data-table/transform.d.ts

@@ -1,4 +1,23 @@
 import { Quat, Vec3 } from 'playcanvas';
 import { DataTable } from './data-table';
+/**
+ * Applies a spatial transformation to splat data in-place.
+ *
+ * Transforms position, rotation, scale, and spherical harmonics data.
+ * The transformation is applied as: scale first, then rotation, then translation.
+ *
+ * @param dataTable - The DataTable to transform (modified in-place).
+ * @param t - Translation vector.
+ * @param r - Rotation quaternion.
+ * @param s - Uniform scale factor.
+ *
+ * @example
+ * ```ts
+ * import { Vec3, Quat } from 'playcanvas';
+ *
+ * // Scale by 2x, rotate 90° around Y, translate up
+ * transform(dataTable, new Vec3(0, 5, 0), new Quat().setFromEulerAngles(0, 90, 0), 2.0);
+ * ```
+ */
 declare const transform: (dataTable: DataTable, t: Vec3, r: Quat, s: number) => void;
 export { transform };

package/dist/lib/index.d.cts

@@ -0,0 +1,34 @@
+export { Column, DataTable } from './data-table/data-table';
+export type { TypedArray, ColumnType, Row } from './data-table/data-table';
+export { combine } from './data-table/combine';
+export { transform } from './data-table/transform';
+export { computeSummary } from './data-table/summary';
+export type { ColumnStats, SummaryData } from './data-table/summary';
+export { readFile, getInputFormat } from './read';
+export type { InputFormat, ReadFileOptions } from './read';
+export { writeFile, getOutputFormat } from './write';
+export type { OutputFormat, WriteOptions } from './write';
+export { processDataTable } from './process';
+export type { ProcessAction, Translate, Rotate, Scale, FilterNaN, FilterByValue, FilterBands, FilterBox, FilterSphere, Param as ProcessParam, Lod, Summary } from './process';
+export { ReadStream, MemoryReadFileSystem, UrlReadFileSystem, ZipReadFileSystem } from './io/read';
+export type { ReadSource, ReadFileSystem, ProgressCallback, ZipEntry } from './io/read';
+export { MemoryFileSystem, ZipFileSystem } from './io/write';
+export type { FileSystem, Writer } from './io/write';
+export { readKsplat } from './readers/read-ksplat';
+export { readLcc } from './readers/read-lcc';
+export { readMjs } from './readers/read-mjs';
+export { readPly } from './readers/read-ply';
+export { readSog } from './readers/read-sog';
+export { readSplat } from './readers/read-splat';
+export { readSpz } from './readers/read-spz';
+export { writeSog } from './writers/write-sog';
+export type { DeviceCreator } from './writers/write-sog';
+export { writePly } from './writers/write-ply';
+export { writeCompressedPly } from './writers/write-compressed-ply';
+export { writeCsv } from './writers/write-csv';
+export { writeHtml } from './writers/write-html';
+export { writeLod } from './writers/write-lod';
+export type { Options, Param } from './types';
+export { logger } from './utils/logger';
+export type { Logger } from './utils/logger';
+export { WebPCodec } from './utils/webp-codec';

package/dist/lib/index.d.ts

@@ -5,13 +5,13 @@ export { transform } from './data-table/transform';
 export { computeSummary } from './data-table/summary';
 export type { ColumnStats, SummaryData } from './data-table/summary';
 export { readFile, getInputFormat } from './read';
-export type { InputFormat } from './read';
+export type { InputFormat, ReadFileOptions } from './read';
 export { writeFile, getOutputFormat } from './write';
-export type { OutputFormat } from './write';
+export type { OutputFormat, WriteOptions } from './write';
 export { processDataTable } from './process';
-export type { ProcessAction } from './process';
+export type { ProcessAction, Translate, Rotate, Scale, FilterNaN, FilterByValue, FilterBands, FilterBox, FilterSphere, Param as ProcessParam, Lod, Summary } from './process';
 export { ReadStream, MemoryReadFileSystem, UrlReadFileSystem, ZipReadFileSystem } from './io/read';
-export type { ReadSource, ReadFileSystem, ProgressCallback } from './io/read';
+export type { ReadSource, ReadFileSystem, ProgressCallback, ZipEntry } from './io/read';
 export { MemoryFileSystem, ZipFileSystem } from './io/write';
 export type { FileSystem, Writer } from './io/write';
 export { readKsplat } from './readers/read-ksplat';

package/dist/lib/io/read/index.d.ts

@@ -2,4 +2,4 @@ export { ReadStream, type ReadSource, type ReadFileSystem, type ProgressCallback
 export { dirname, join } from 'pathe';
 export { MemoryReadFileSystem } from './memory-file-system';
 export { UrlReadFileSystem } from './url-file-system';
-export { ZipReadFileSystem } from './zip-file-system';
+export { ZipReadFileSystem, type ZipEntry } from './zip-file-system';

package/dist/lib/io/read/zip-file-system.d.ts

@@ -48,4 +48,4 @@ declare class ZipReadFileSystem implements ReadFileSystem {
      */
     close(): void;
 }
-export { ZipReadFileSystem };
+export { ZipReadFileSystem, type ZipEntry };

package/dist/lib/io/write/memory-file-system.d.ts

@@ -1,4 +1,19 @@
 import { type FileSystem, type Writer } from './file-system';
+/**
+ * A file system that writes files to in-memory buffers.
+ *
+ * Useful for generating output without writing to disk, such as when
+ * creating data for download or further processing.
+ *
+ * @example
+ * ```ts
+ * const fs = new MemoryFileSystem();
+ * await writeFile({ filename: 'output.ply', ... }, fs);
+ *
+ * // Get the generated data
+ * const data = fs.results.get('output.ply');
+ * ```
+ */
 declare class MemoryFileSystem implements FileSystem {
     results: Map<string, Uint8Array>;
     createWriter(filename: string): Writer;

package/dist/lib/io/write/zip-file-system.d.ts

@@ -1,4 +1,24 @@
 import { type FileSystem, type Writer } from './file-system';
+/**
+ * A file system that writes files into a ZIP archive.
+ *
+ * Creates a ZIP file containing all written files. Used internally
+ * for bundled output formats like .sog files.
+ *
+ * @example
+ * ```ts
+ * const outputWriter = await fs.createWriter('bundle.zip');
+ * const zipFs = new ZipFileSystem(outputWriter);
+ *
+ * // Write files into the zip
+ * const writer = await zipFs.createWriter('data.json');
+ * await writer.write(jsonData);
+ * await writer.close();
+ *
+ * // Finalize the zip
+ * await zipFs.close();
+ * ```
+ */
 declare class ZipFileSystem implements FileSystem {
     close: () => Promise<void>;
     createWriter: (filename: string) => Promise<Writer>;

package/dist/lib/process.d.ts

@@ -1,52 +1,147 @@
 import { Vec3 } from 'playcanvas';
 import { DataTable } from './data-table/data-table';
+/**
+ * Translate splats by a 3D vector offset.
+ */
 type Translate = {
+    /** Action type identifier. */
     kind: 'translate';
+    /** Translation offset. */
     value: Vec3;
 };
+/**
+ * Rotate splats by Euler angles.
+ */
 type Rotate = {
+    /** Action type identifier. */
     kind: 'rotate';
+    /** Euler angles in degrees (x, y, z). */
     value: Vec3;
 };
+/**
+ * Uniformly scale all splats.
+ */
 type Scale = {
+    /** Action type identifier. */
     kind: 'scale';
+    /** Scale factor. */
     value: number;
 };
+/**
+ * Remove splats containing NaN or Infinity values.
+ */
 type FilterNaN = {
+    /** Action type identifier. */
     kind: 'filterNaN';
 };
+/**
+ * Filter splats by comparing a column value.
+ */
 type FilterByValue = {
+    /** Action type identifier. */
     kind: 'filterByValue';
+    /** Name of the column to compare. */
     columnName: string;
+    /** Comparison operator. */
     comparator: 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'neq';
+    /** Value to compare against. */
     value: number;
 };
+/**
+ * Remove spherical harmonic bands above a threshold.
+ */
 type FilterBands = {
+    /** Action type identifier. */
     kind: 'filterBands';
+    /** Maximum SH band to keep (0-3). */
     value: 0 | 1 | 2 | 3;
 };
+/**
+ * Keep only splats within a bounding box.
+ */
 type FilterBox = {
+    /** Action type identifier. */
     kind: 'filterBox';
+    /** Minimum corner of the box. */
     min: Vec3;
+    /** Maximum corner of the box. */
     max: Vec3;
 };
+/**
+ * Keep only splats within a sphere.
+ */
 type FilterSphere = {
+    /** Action type identifier. */
     kind: 'filterSphere';
+    /** Center of the sphere. */
     center: Vec3;
+    /** Radius of the sphere. */
     radius: number;
 };
+/**
+ * Parameter for .mjs generator modules.
+ */
 type Param = {
+    /** Action type identifier. */
     kind: 'param';
+    /** Parameter name. */
     name: string;
+    /** Parameter value. */
     value: string;
 };
+/**
+ * Assign a LOD level to all splats.
+ */
 type Lod = {
+    /** Action type identifier. */
     kind: 'lod';
+    /** LOD level to assign. */
     value: number;
 };
+/**
+ * Print a statistical summary to the logger.
+ */
 type Summary = {
+    /** Action type identifier. */
     kind: 'summary';
 };
+/**
+ * A processing action to apply to splat data.
+ *
+ * Actions can transform, filter, or analyze the data:
+ * - `translate` - Move splats by a Vec3 offset
+ * - `rotate` - Rotate splats by Euler angles (degrees)
+ * - `scale` - Uniformly scale splats
+ * - `filterNaN` - Remove splats with NaN/Inf values
+ * - `filterByValue` - Keep splats matching a column condition
+ * - `filterBands` - Remove spherical harmonic bands above a threshold
+ * - `filterBox` - Keep splats within a bounding box
+ * - `filterSphere` - Keep splats within a sphere
+ * - `lod` - Assign LOD level to all splats
+ * - `summary` - Print statistical summary to logger
+ */
 type ProcessAction = Translate | Rotate | Scale | FilterNaN | FilterByValue | FilterBands | FilterBox | FilterSphere | Param | Lod | Summary;
+/**
+ * Applies a sequence of processing actions to splat data.
+ *
+ * Actions are applied in order and can include transformations (translate, rotate, scale),
+ * filters (NaN, value, box, sphere, bands), and analysis (summary).
+ *
+ * @param dataTable - The input splat data.
+ * @param processActions - Array of actions to apply in sequence.
+ * @returns The processed DataTable (may be a new instance if filtered).
+ *
+ * @example
+ * ```ts
+ * import { Vec3 } from 'playcanvas';
+ *
+ * const processed = processDataTable(dataTable, [
+ *     { kind: 'scale', value: 0.5 },
+ *     { kind: 'translate', value: new Vec3(0, 1, 0) },
+ *     { kind: 'filterNaN' },
+ *     { kind: 'filterByValue', columnName: 'opacity', comparator: 'gt', value: 0.1 }
+ * ]);
+ * ```
+ */
 declare const processDataTable: (dataTable: DataTable, processActions: ProcessAction[]) => DataTable;
-export { ProcessAction, processDataTable };
+export { processDataTable, type ProcessAction, type Translate, type Rotate, type Scale, type FilterNaN, type FilterByValue, type FilterBands, type FilterBox, type FilterSphere, type Param, type Lod, type Summary };

package/dist/lib/read.d.ts

@@ -1,14 +1,70 @@
 import { DataTable } from './data-table/data-table';
 import { ReadFileSystem } from './io/read';
 import { Options, Param } from './types';
+/**
+ * Supported input file formats for Gaussian splat data.
+ *
+ * - `ply` - PLY format (standard 3DGS training output)
+ * - `splat` - Antimatter15 splat format
+ * - `ksplat` - Kevin Kwok's compressed splat format
+ * - `spz` - Niantic Labs compressed format
+ * - `sog` - PlayCanvas SOG format (WebP-compressed)
+ * - `lcc` - XGrids LCC format
+ * - `mjs` - JavaScript module generator
+ */
 type InputFormat = 'mjs' | 'ksplat' | 'splat' | 'sog' | 'ply' | 'spz' | 'lcc';
+/**
+ * Determines the input format based on file extension.
+ *
+ * @param filename - The filename to analyze.
+ * @returns The detected input format.
+ * @throws Error if the file extension is not recognized.
+ *
+ * @example
+ * ```ts
+ * const format = getInputFormat('scene.ply');  // returns 'ply'
+ * const format2 = getInputFormat('scene.splat');  // returns 'splat'
+ * ```
+ */
 declare const getInputFormat: (filename: string) => InputFormat;
+/**
+ * Options for reading a Gaussian splat file.
+ */
 type ReadFileOptions = {
+    /** Path to the input file. */
     filename: string;
+    /** The format of the input file. */
     inputFormat: InputFormat;
+    /** Processing options. */
     options: Options;
+    /** Parameters for generator modules (.mjs files). */
     params: Param[];
+    /** File system abstraction for reading files. */
     fileSystem: ReadFileSystem;
 };
+/**
+ * Reads a Gaussian splat file and returns its data as one or more DataTables.
+ *
+ * Supports multiple input formats including PLY, splat, ksplat, spz, SOG, and LCC.
+ * Some formats (like LCC) may return multiple DataTables for different LOD levels.
+ *
+ * @param readFileOptions - Options specifying the file to read and how to read it.
+ * @returns Promise resolving to an array of DataTables containing the splat data.
+ *
+ * @example
+ * ```ts
+ * import { readFile, getInputFormat, UrlReadFileSystem } from '@playcanvas/splat-transform';
+ *
+ * const filename = 'scene.ply';
+ * const fileSystem = new UrlReadFileSystem('https://example.com/');
+ * const tables = await readFile({
+ *     filename,
+ *     inputFormat: getInputFormat(filename),
+ *     options: {},
+ *     params: [],
+ *     fileSystem
+ * });
+ * ```
+ */
 declare const readFile: (readFileOptions: ReadFileOptions) => Promise<DataTable[]>;
-export { readFile, getInputFormat, type InputFormat };
+export { readFile, getInputFormat, type InputFormat, type ReadFileOptions };

package/dist/lib/readers/read-ksplat.d.ts

@@ -1,4 +1,15 @@
 import { DataTable } from '../data-table/data-table';
 import { ReadSource } from '../io/read';
+/**
+ * Reads a .ksplat file containing compressed Gaussian splat data.
+ *
+ * The .ksplat format (Kevin Kwok's format) uses spatial bucketing and
+ * quantization to achieve high compression ratios while preserving quality.
+ * Supports multiple compression modes and spherical harmonics bands.
+ *
+ * @param source - The read source providing access to the .ksplat file data.
+ * @returns Promise resolving to a DataTable containing the splat data.
+ * @ignore
+ */
 declare const readKsplat: (source: ReadSource) => Promise<DataTable>;
 export { readKsplat };

package/dist/lib/readers/read-lcc.d.ts

@@ -1,5 +1,18 @@
 import { DataTable } from '../data-table/data-table';
 import { ReadFileSystem } from '../io/read';
 import { Options } from '../types';
+/**
+ * Reads an XGrids LCC format containing multi-LOD Gaussian splat data.
+ *
+ * The LCC format uses a quadtree spatial structure with multiple LOD levels.
+ * Each LOD level is stored separately in data.bin with optional spherical
+ * harmonics in shcoef.bin. Environment splats are stored in environment.bin.
+ *
+ * @param fileSystem - File system for reading the LCC files.
+ * @param filename - Path to the meta.lcc file.
+ * @param options - Options including LOD selection via `lodSelect`.
+ * @returns Promise resolving to an array of DataTables, one per LOD level plus environment.
+ * @ignore
+ */
 declare const readLcc: (fileSystem: ReadFileSystem, filename: string, options: Options) => Promise<DataTable[]>;
 export { readLcc };

package/dist/lib/readers/read-mjs.d.ts

@@ -1,4 +1,16 @@
 import { DataTable } from '../data-table/data-table';
 import { Param } from '../types';
+/**
+ * Reads splat data from a JavaScript module generator.
+ *
+ * The module must export a `Generator` class with a static `create(params)` method
+ * that returns an object with `count`, `columnNames`, and `getRow(index, row)` properties.
+ * This allows programmatic generation of splat data.
+ *
+ * @param moduleUrl - URL or path to the JavaScript module.
+ * @param params - Parameters to pass to the generator's create method.
+ * @returns Promise resolving to a DataTable containing the generated splat data.
+ * @ignore
+ */
 declare const readMjs: (moduleUrl: string, params: Param[]) => Promise<DataTable>;
 export { readMjs };

package/dist/lib/readers/read-ply.d.ts

@@ -7,5 +7,15 @@ type PlyData = {
         dataTable: DataTable;
     }[];
 };
+/**
+ * Reads a PLY file containing Gaussian splat data.
+ *
+ * Supports both standard PLY files and compressed PLY format. The PLY format is
+ * the standard output from 3D Gaussian Splatting training pipelines.
+ *
+ * @param source - The read source providing access to the PLY file data.
+ * @returns Promise resolving to a DataTable containing the splat data.
+ * @ignore
+ */
 declare const readPly: (source: ReadSource) => Promise<DataTable>;
 export { PlyData, readPly };

package/dist/lib/readers/read-sog.d.ts

@@ -5,6 +5,7 @@ import { ReadFileSystem } from '../io/read';
  * @param fileSystem - The file system to read from
  * @param filename - Path to meta.json (relative paths resolved from its directory)
  * @returns DataTable with Gaussian splat data
+ * @ignore
  */
 declare const readSog: (fileSystem: ReadFileSystem, filename: string) => Promise<DataTable>;
 export { readSog };

package/dist/lib/readers/read-splat.d.ts

@@ -1,4 +1,14 @@
 import { DataTable } from '../data-table/data-table';
 import { ReadSource } from '../io/read';
+/**
+ * Reads an Antimatter15 .splat file containing Gaussian splat data.
+ *
+ * The .splat format stores each splat as 32 bytes with position, scale, color,
+ * opacity, and rotation data in a compact binary format.
+ *
+ * @param source - The read source providing access to the .splat file data.
+ * @returns Promise resolving to a DataTable containing the splat data.
+ * @ignore
+ */
 declare const readSplat: (source: ReadSource) => Promise<DataTable>;
 export { readSplat };

package/dist/lib/readers/read-spz.d.ts

@@ -1,4 +1,16 @@
 import { DataTable } from '../data-table/data-table';
 import { ReadSource } from '../io/read';
+/**
+ * Reads a .spz file containing Niantic Labs compressed Gaussian splat data.
+ *
+ * The .spz format uses GZIP compression and fixed-point encoding to achieve
+ * compact file sizes. Supports version 2 and 3 of the format.
+ *
+ * @see https://github.com/nianticlabs/spz
+ *
+ * @param source - The read source providing access to the .spz file data.
+ * @returns Promise resolving to a DataTable containing the splat data.
+ * @ignore
+ */
 declare const readSpz: (source: ReadSource) => Promise<DataTable>;
 export { readSpz };

package/dist/lib/types.d.ts

@@ -17,6 +17,7 @@ type Options = {
 };
 /**
  * Parameter passed to MJS generator scripts.
+ * @ignore
  */
 type Param = {
     name: string;