@playcanvas/splat-transform 1.0.0 → 1.1.0

package/dist/index.mjs

@@ -1,5 +1,17 @@
 import { Vec3, Quat, Mat4, Mat3, BindGroupFormat, BindUniformBufferFormat, BindStorageBufferFormat, SHADERSTAGE_COMPUTE, Shader, UniformBufferFormat, SHADERLANGUAGE_WGSL, UniformFormat, UNIFORMTYPE_UINT, StorageBuffer, BUFFERUSAGE_COPY_DST, BUFFERUSAGE_COPY_SRC, Compute, FloatPacking, BoundingBox } from 'playcanvas';
 
+/**
+ * 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'
+ * ```
+ */
 class Column {
     name;
     data;
@@ -24,6 +36,32 @@ class Column {
         return new Column(this.name, this.data.slice());
     }
 }
+/**
+ * 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
+ * ```
+ */
 class DataTable {
     columns;
     constructor(columns) {
@@ -115,7 +153,22 @@ class DataTable {
     }
 }
 
-// combine multiple DataTables into a single DataTable instance
+/**
+ * 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
+ * ```
+ */
 const combine = (dataTables) => {
     if (dataTables.length === 1) {
         // nothing to combine
@@ -341,7 +394,25 @@ class RotateSH {
 const shNames$3 = new Array(45).fill('').map((_, i) => `f_rest_${i}`);
 const v = new Vec3();
 const q$1 = new Quat();
-// apply translation, rotation and scale to a 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);
+ * ```
+ */
 const transform = (dataTable, t, r, s) => {
     const mat = new Mat4().setTRS(t, r, new Vec3(s, s, s));
     const mat3 = new Mat3().setFromQuat(r);
@@ -460,6 +531,23 @@ const computeColumnStats = (data) => {
         infCount
     };
 };
+/**
+ * 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);
+ * ```
+ */
 const computeSummary = (dataTable) => {
     const columns = {};
     for (const column of dataTable.columns) {
@@ -918,6 +1006,17 @@ const COMPRESSION_MODES = [
     }
 ];
 const HARMONICS_COMPONENT_COUNT$1 = [0, 9, 24, 45];
+/**
+ * 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
+ */
 const readKsplat = async (source) => {
     // Load complete file
     const fileBuffer = await source.read().readAll();
@@ -1875,6 +1974,19 @@ const deserializeEnvironment = (raw, compressInfo, hasSH) => {
     }
     return new DataTable(columns);
 };
+/**
+ * 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
+ */
 const readLcc = async (fileSystem, filename, options) => {
     const lccData = await readFile$1(fileSystem, filename);
     const lccText = new TextDecoder().decode(lccData);
@@ -1949,6 +2061,18 @@ const readLcc = async (fileSystem, filename, options) => {
     return result;
 };
 
+/**
+ * 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
+ */
 const readMjs = async (moduleUrl, params) => {
     const module = await import(moduleUrl);
     if (!module) {
@@ -2269,6 +2393,16 @@ const readExact = async (stream, buffer, offset, length) => {
     }
     return totalRead;
 };
+/**
+ * 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
+ */
 const readPly = async (source) => {
     const stream = source.read();
     // we don't support ply text header larger than 128k
@@ -2483,6 +2617,7 @@ const sigmoidInv = (y) => {
  * @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
  */
 const readSog = async (fileSystem, filename) => {
     const decoder = await WebPCodec.create();
@@ -2630,6 +2765,16 @@ const readSog = async (fileSystem, filename) => {
     return new DataTable(columns);
 };
 
+/**
+ * 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
+ */
 const readSplat = async (source) => {
     // Load complete file
     const fileBuffer = await source.read().readAll();
@@ -2753,6 +2898,18 @@ function getFixed24(positionsView, elementIndex, memberIndex) {
     return fixed32;
 }
 const HARMONICS_COMPONENT_COUNT = [0, 9, 24, 45];
+/**
+ * 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
+ */
 const readSpz = async (source) => {
     // Load complete file
     let fileBuffer = await source.read().readAll();
@@ -2989,6 +3146,19 @@ const logger = {
     }
 };
 
+/**
+ * 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'
+ * ```
+ */
 const getInputFormat = (filename) => {
     const lowerFilename = filename.toLowerCase();
     if (lowerFilename.endsWith('.mjs')) {
@@ -3014,6 +3184,30 @@ const getInputFormat = (filename) => {
     }
     throw new Error(`Unsupported input file type: ${filename}`);
 };
+/**
+ * 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
+ * });
+ * ```
+ */
 const readFile = async (readFileOptions) => {
     const { filename, inputFormat, options, params, fileSystem } = readFileOptions;
     let result;
@@ -3208,7 +3402,7 @@ class CompressedChunk {
     }
 }
 
-var version = "1.0.0";
+var version = "1.1.0";
 
 // sort the provided indices into morton order
 const sortMortonOrder = (dataTable, indices) => {
@@ -3327,6 +3521,17 @@ const vertexProps = [
 const shNames$2 = new Array(45).fill('').map((_, i) => `f_rest_${i}`);
 // Size of a chunk in the compressed PLY format (number of splats per chunk)
 const CHUNK_SIZE = 256;
+/**
+ * Writes Gaussian splat data to compressed PLY format.
+ *
+ * Uses quantization and chunking to reduce file size while maintaining
+ * compatibility with PLY-based viewers. Data is sorted using Morton order
+ * for better compression and streaming performance.
+ *
+ * @param options - Options including filename and data table to write.
+ * @param fs - File system for writing the output file.
+ * @ignore
+ */
 const writeCompressedPly = async (options, fs) => {
     const { filename, dataTable } = options;
     const shBands = { '9': 1, '24': 2, '-1': 3 }[shNames$2.findIndex(v => !dataTable.hasColumn(v))] ?? 0;
@@ -3400,6 +3605,16 @@ const writeCompressedPly = async (options, fs) => {
     await writer.close();
 };
 
+/**
+ * Writes Gaussian splat data to a CSV text file.
+ *
+ * Useful for debugging, analysis, or importing into spreadsheet applications.
+ * Each row represents one splat with all column values separated by commas.
+ *
+ * @param options - Options including filename and data table to write.
+ * @param fs - File system for writing the output file.
+ * @ignore
+ */
 const writeCsv = async (options, fs) => {
     const { filename, dataTable } = options;
     const len = dataTable.numRows;
@@ -3471,6 +3686,21 @@ class MemoryWriter {
         };
     }
 }
+/**
+ * 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');
+ * ```
+ */
 class MemoryFileSystem {
     results = new Map();
     createWriter(filename) {
@@ -3537,7 +3767,26 @@ class ZipEntryWriter {
         };
     }
 }
-// FileSystem implementation that writes files into a zip archive
+/**
+ * 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();
+ * ```
+ */
 class ZipFileSystem {
     close;
     createWriter;
@@ -4117,6 +4366,17 @@ const cluster1d = async (dataTable, iterations, device) => {
     };
 };
 let webPCodec;
+/**
+ * Writes Gaussian splat data to the PlayCanvas SOG format.
+ *
+ * SOG (Splat Optimized Graphics) uses WebP lossless compression and k-means
+ * clustering to achieve high compression ratios. Data is stored in textures
+ * for efficient GPU loading.
+ *
+ * @param options - Options including filename, data, and compression settings.
+ * @param fs - File system for writing output files.
+ * @ignore
+ */
 const writeSog = async (options, fs) => {
     const { filename: outputFilename, bundle, dataTable, iterations, createDevice } = options;
     // initialize output stream - use ZipFileSystem for bundled output
@@ -4355,6 +4615,16 @@ const toBase64 = (bytes) => {
     return btoa(binary);
 };
 
+/**
+ * Writes Gaussian splat data as a self-contained HTML viewer.
+ *
+ * Creates an interactive 3D viewer that can be opened directly in a browser.
+ * Uses the PlayCanvas SuperSplat viewer for rendering.
+ *
+ * @param options - Options including filename, data, and viewer settings.
+ * @param fs - File system for writing output files.
+ * @ignore
+ */
 const writeHtml = async (options, fs) => {
     const { filename, dataTable, viewerSettingsJson, bundle, iterations, createDevice } = options;
     const pad = (text, spaces) => {
@@ -4650,6 +4920,17 @@ const binIndices = (parent, lod) => {
     recurse(parent);
     return result;
 };
+/**
+ * Writes Gaussian splat data to multi-LOD format with spatial chunking.
+ *
+ * Creates a hierarchical structure with multiple LOD levels, each stored
+ * in separate SOG files. Includes spatial indexing via a binary tree for
+ * efficient streaming and view-dependent loading.
+ *
+ * @param options - Options including filename, data, and chunking parameters.
+ * @param fs - File system for writing output files.
+ * @ignore
+ */
 const writeLod = async (options, fs) => {
     const { filename, dataTable, envDataTable, iterations, createDevice, chunkCount, chunkExtent } = options;
     const outputDir = dirname(filename);
@@ -4801,6 +5082,16 @@ const columnTypeToPlyType = (type) => {
         case 'uint32': return 'uint';
     }
 };
+/**
+ * Writes Gaussian splat data to a binary PLY file.
+ *
+ * The PLY format is the standard output from 3D Gaussian Splatting training
+ * and is widely supported by visualization tools.
+ *
+ * @param options - Options including filename and PLY data to write.
+ * @param fs - File system for writing the output file.
+ * @ignore
+ */
 const writePly = async (options, fs) => {
     const { filename, plyData } = options;
     const header = [
@@ -4849,6 +5140,20 @@ const writePly = async (options, fs) => {
     await writer.close();
 };
 
+/**
+ * Determines the output format based on file extension and options.
+ *
+ * @param filename - The filename to analyze.
+ * @param options - Options that may affect format selection.
+ * @returns The detected output format.
+ * @throws Error if the file extension is not recognized.
+ *
+ * @example
+ * ```ts
+ * const format = getOutputFormat('scene.ply', {});  // returns 'ply'
+ * const format2 = getOutputFormat('scene.sog', {});  // returns 'sog-bundle'
+ * ```
+ */
 const getOutputFormat = (filename, options) => {
     const lowerFilename = filename.toLowerCase();
     if (lowerFilename.endsWith('.csv')) {
@@ -4874,6 +5179,27 @@ const getOutputFormat = (filename, options) => {
     }
     throw new Error(`Unsupported output file type: ${filename}`);
 };
+/**
+ * Writes Gaussian splat data to a file in the specified format.
+ *
+ * Supports multiple output formats including PLY, compressed PLY, CSV, SOG, LOD, and HTML.
+ *
+ * @param writeOptions - Options specifying the data and format to write.
+ * @param fs - File system abstraction for writing files.
+ *
+ * @example
+ * ```ts
+ * import { writeFile, getOutputFormat, MemoryFileSystem } from '@playcanvas/splat-transform';
+ *
+ * const fs = new MemoryFileSystem();
+ * await writeFile({
+ *     filename: 'output.sog',
+ *     outputFormat: getOutputFormat('output.sog', {}),
+ *     dataTable: myDataTable,
+ *     options: { iterations: 8 }
+ * }, fs);
+ * ```
+ */
 const writeFile = async (writeOptions, fs) => {
     const { filename, outputFormat, dataTable, envDataTable, options, createDevice } = writeOptions;
     logger.log(`writing '${filename}'...`);
@@ -4981,7 +5307,28 @@ const filter = (dataTable, predicate) => {
     }
     return dataTable.permuteRows(indices.subarray(0, index));
 };
-// process a data table with standard options
+/**
+ * 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 }
+ * ]);
+ * ```
+ */
 const processDataTable = (dataTable, processActions) => {
     let result = dataTable;
     for (let i = 0; i < processActions.length; i++) {