@playcanvas/splat-transform 1.0.0 → 1.1.0

package/dist/lib/write.d.ts

@@ -2,15 +2,71 @@ import { DataTable } from './data-table/data-table';
 import { type FileSystem } from './io/write';
 import { Options } from './types';
 import { type DeviceCreator } from './writers/write-sog';
+/**
+ * Supported output file formats for Gaussian splat data.
+ *
+ * - `ply` - Standard PLY format
+ * - `compressed-ply` - Compressed PLY format
+ * - `csv` - CSV text format (for debugging/analysis)
+ * - `sog` - PlayCanvas SOG format (separate files)
+ * - `sog-bundle` - PlayCanvas SOG format (bundled into single .sog file)
+ * - `lod` - Multi-LOD format with chunked data
+ * - `html` - Self-contained HTML viewer (separate assets)
+ * - `html-bundle` - Self-contained HTML viewer (all assets embedded)
+ */
 type OutputFormat = 'csv' | 'sog' | 'sog-bundle' | 'lod' | 'compressed-ply' | 'ply' | 'html' | 'html-bundle';
+/**
+ * Options for writing a Gaussian splat file.
+ */
 type WriteOptions = {
+    /** Path to the output file. */
     filename: string;
+    /** The format to write. */
     outputFormat: OutputFormat;
+    /** The splat data to write. */
     dataTable: DataTable;
+    /** Optional environment/skybox splat data (for LOD format). */
     envDataTable?: DataTable;
+    /** Processing options. */
     options: Options;
+    /** Optional function to create a GPU device for compression. */
     createDevice?: DeviceCreator;
 };
+/**
+ * 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'
+ * ```
+ */
 declare const getOutputFormat: (filename: string, options: Options) => OutputFormat;
+/**
+ * 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);
+ * ```
+ */
 declare const writeFile: (writeOptions: WriteOptions, fs: FileSystem) => Promise<void>;
-export { getOutputFormat, writeFile, type OutputFormat };
+export { getOutputFormat, writeFile, type OutputFormat, type WriteOptions };

package/dist/lib/writers/write-compressed-ply.d.ts

@@ -4,5 +4,16 @@ type WriteCompressedPlyOptions = {
     filename: string;
     dataTable: DataTable;
 };
+/**
+ * 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
+ */
 declare const writeCompressedPly: (options: WriteCompressedPlyOptions, fs: FileSystem) => Promise<void>;
 export { writeCompressedPly };

package/dist/lib/writers/write-csv.d.ts

@@ -4,5 +4,15 @@ type WriteCSVOptions = {
     filename: string;
     dataTable: DataTable;
 };
+/**
+ * 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
+ */
 declare const writeCsv: (options: WriteCSVOptions, fs: FileSystem) => Promise<void>;
 export { writeCsv };

package/dist/lib/writers/write-html.d.ts

@@ -9,5 +9,15 @@ type WriteHtmlOptions = {
     iterations: number;
     createDevice?: DeviceCreator;
 };
+/**
+ * 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
+ */
 declare const writeHtml: (options: WriteHtmlOptions, fs: FileSystem) => Promise<void>;
 export { writeHtml };

package/dist/lib/writers/write-lod.d.ts

@@ -10,5 +10,16 @@ type WriteLodOptions = {
     chunkCount: number;
     chunkExtent: number;
 };
+/**
+ * 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
+ */
 declare const writeLod: (options: WriteLodOptions, fs: FileSystem) => Promise<void>;
 export { writeLod };

package/dist/lib/writers/write-ply.d.ts

@@ -4,5 +4,15 @@ type WritePlyOptions = {
     filename: string;
     plyData: PlyData;
 };
+/**
+ * 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
+ */
 declare const writePly: (options: WritePlyOptions, fs: FileSystem) => Promise<void>;
 export { writePly };

package/dist/lib/writers/write-sog.d.ts

@@ -2,8 +2,12 @@ import { GraphicsDevice } from 'playcanvas';
 import { DataTable } from '../data-table/data-table';
 import { type FileSystem } from '../io/write';
 /**
- * A function that creates a GraphicsDevice on demand.
+ * A function that creates a PlayCanvas GraphicsDevice on demand.
+ *
+ * Used for GPU-accelerated k-means clustering during SOG compression.
  * The application is responsible for caching if needed.
+ *
+ * @returns Promise resolving to a GraphicsDevice instance.
  */
 type DeviceCreator = () => Promise<GraphicsDevice>;
 type WriteSogOptions = {
@@ -14,5 +18,16 @@ type WriteSogOptions = {
     iterations: number;
     createDevice?: DeviceCreator;
 };
+/**
+ * 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
+ */
 declare const writeSog: (options: WriteSogOptions, fs: FileSystem) => Promise<void>;
 export { writeSog, type DeviceCreator };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcanvas/splat-transform",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "author": "PlayCanvas<support@playcanvas.com>",
   "homepage": "https://playcanvas.com",
   "description": "Library and CLI tool for 3D Gaussian splat format conversion and transformation",
@@ -18,8 +18,14 @@
   "types": "dist/lib/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/lib/index.d.ts",
-      "import": "./dist/index.mjs"
+      "import": {
+        "types": "./dist/lib/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/lib/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./lib/*": "./lib/*"
   },
@@ -57,13 +63,16 @@
     "publint": "0.3.16",
     "rollup": "4.54.0",
     "tslib": "2.8.1",
+    "typedoc": "0.28.15",
+    "typedoc-plugin-mdn-links": "5.0.10",
     "typescript": "5.9.3"
   },
   "peerDependencies": {
     "playcanvas": ">=2.0.0"
   },
   "scripts": {
-    "build": "rollup -c",
+    "build": "rollup -c && node -e \"fs=require('fs');fs.copyFileSync('dist/lib/index.d.ts','dist/lib/index.d.cts')\"",
+    "docs": "typedoc",
     "lint": "eslint src",
     "lint:fix": "eslint src --fix",
     "publint": "publint",