@playcanvas/splat-transform 0.16.1 → 1.0.0

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

@@ -0,0 +1,3 @@
+import { DataTable } from './data-table';
+declare const combine: (dataTables: DataTable[]) => DataTable;
+export { combine };

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

@@ -0,0 +1,32 @@
+type TypedArray = Int8Array | Uint8Array | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array;
+type ColumnType = 'int8' | 'uint8' | 'int16' | 'uint16' | 'int32' | 'uint32' | 'float32' | 'float64';
+declare class Column {
+    name: string;
+    data: TypedArray;
+    constructor(name: string, data: TypedArray);
+    get dataType(): ColumnType | null;
+    clone(): Column;
+}
+type Row = {
+    [colName: string]: number;
+};
+declare class DataTable {
+    columns: Column[];
+    constructor(columns: Column[]);
+    get numRows(): number;
+    getRow(index: number, row?: Row, columns?: Column[]): Row;
+    setRow(index: number, row: Row, columns?: Column[]): void;
+    get numColumns(): number;
+    get columnNames(): string[];
+    get columnData(): TypedArray[];
+    get columnTypes(): ColumnType[];
+    getColumn(index: number): Column;
+    getColumnIndex(name: string): number;
+    getColumnByName(name: string): Column | null;
+    hasColumn(name: string): boolean;
+    addColumn(column: Column): void;
+    removeColumn(name: string): boolean;
+    clone(): DataTable;
+    permuteRows(indices: Uint32Array | number[]): DataTable;
+}
+export { Column, DataTable, TypedArray, ColumnType, Row };

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

@@ -0,0 +1,3 @@
+import { DataTable } from './data-table';
+declare const sortMortonOrder: (dataTable: DataTable, indices: Uint32Array) => void;
+export { sortMortonOrder };

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

@@ -0,0 +1,17 @@
+import { DataTable } from './data-table';
+type ColumnStats = {
+    min: number;
+    max: number;
+    median: number;
+    mean: number;
+    stdDev: number;
+    nanCount: number;
+    infCount: number;
+};
+type SummaryData = {
+    version: number;
+    rowCount: number;
+    columns: Record<string, ColumnStats>;
+};
+declare const computeSummary: (dataTable: DataTable) => SummaryData;
+export { computeSummary, type ColumnStats, type SummaryData };

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

@@ -0,0 +1,4 @@
+import { Quat, Vec3 } from 'playcanvas';
+import { DataTable } from './data-table';
+declare const transform: (dataTable: DataTable, t: Vec3, r: Quat, s: number) => void;
+export { transform };

package/dist/lib/gpu/gpu-clustering.d.ts

@@ -0,0 +1,8 @@
+import { GraphicsDevice } from 'playcanvas';
+import { DataTable } from '../data-table/data-table.js';
+declare class GpuClustering {
+    execute: (points: DataTable, centroids: DataTable, labels: Uint32Array) => Promise<void>;
+    destroy: () => void;
+    constructor(device: GraphicsDevice, numColumns: number, numCentroids: number);
+}
+export { GpuClustering };

package/dist/lib/index.d.ts

@@ -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 } from './read';
+export { writeFile, getOutputFormat } from './write';
+export type { OutputFormat } from './write';
+export { processDataTable } from './process';
+export type { ProcessAction } from './process';
+export { ReadStream, MemoryReadFileSystem, UrlReadFileSystem, ZipReadFileSystem } from './io/read';
+export type { ReadSource, ReadFileSystem, ProgressCallback } 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/io/read/file-system.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Abstract base class for streaming data from a source.
+ * Uses a pull-based model where the consumer provides the buffer.
+ */
+declare abstract class ReadStream {
+    /**
+     * Size hint for buffer pre-allocation in readAll().
+     * May be undefined if size is unknown.
+     */
+    readonly expectedSize: number | undefined;
+    /**
+     * Total bytes read from this stream so far.
+     */
+    bytesRead: number;
+    /**
+     * @param expectedSize - Optional size hint for buffer pre-allocation
+     */
+    constructor(expectedSize?: number);
+    /**
+     * Pull data into the provided buffer.
+     * @param target - Buffer to fill with data
+     * @returns Number of bytes read, or 0 for EOF
+     */
+    abstract pull(target: Uint8Array): Promise<number>;
+    /**
+     * Read entire stream into a single buffer.
+     * Uses expectedSize hint if available, grows dynamically if needed.
+     * @returns Complete data as Uint8Array
+     */
+    readAll(): Promise<Uint8Array>;
+    /**
+     * Release resources and abort any pending operations.
+     */
+    close(): void;
+}
+/**
+ * Interface representing a readable data source.
+ * Provides size information and creates streams for reading.
+ */
+interface ReadSource {
+    /**
+     * The size of the source in bytes, or undefined if unknown.
+     * For compressed sources (e.g., gzipped HTTP), this may be approximate.
+     */
+    readonly size: number | undefined;
+    /**
+     * Whether range reads are supported.
+     * If false, read() must be called with no arguments or start=0.
+     */
+    readonly seekable: boolean;
+    /**
+     * Create a stream for reading data, optionally with a byte range.
+     * @param start - Starting byte offset (inclusive), defaults to 0
+     * @param end - Ending byte offset (exclusive), defaults to size/EOF
+     * @returns A ReadStream for pulling data
+     * @throws Error if range requested on non-seekable source
+     */
+    read(start?: number, end?: number): ReadStream;
+    /**
+     * Release any resources held by this source.
+     */
+    close(): void;
+}
+/**
+ * Progress callback for tracking read operations.
+ * @param bytesLoaded - Bytes loaded so far
+ * @param totalBytes - Total bytes if known, undefined otherwise
+ */
+type ProgressCallback = (bytesLoaded: number, totalBytes: number | undefined) => void;
+/**
+ * Interface for a file system that can create readable sources.
+ * Implementations exist for various backends (URL, Node FS, Zip, Memory).
+ */
+interface ReadFileSystem {
+    /**
+     * Create a readable source for the given path/identifier.
+     * @param filename - Path or identifier for the resource
+     * @param progress - Optional callback for progress reporting
+     * @returns Promise resolving to a ReadSource
+     */
+    createSource(filename: string, progress?: ProgressCallback): Promise<ReadSource>;
+}
+/**
+ * Read an entire file into memory.
+ * Convenience helper that handles source creation, reading, and cleanup.
+ * @param fs - The file system to read from
+ * @param filename - Path or identifier for the resource
+ * @returns Promise resolving to file contents as Uint8Array
+ */
+declare const readFile: (fs: ReadFileSystem, filename: string) => Promise<Uint8Array>;
+export { ReadStream, type ReadSource, type ReadFileSystem, type ProgressCallback, readFile };

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

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

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

@@ -0,0 +1,22 @@
+import { type ReadFileSystem, type ProgressCallback, type ReadSource } from './file-system';
+/**
+ * ReadFileSystem for reading from named memory buffers.
+ * Useful for testing or when data is already in memory.
+ */
+declare class MemoryReadFileSystem implements ReadFileSystem {
+    private buffers;
+    /**
+     * Store a named buffer.
+     * @param name - Name/path for the buffer
+     * @param data - Data to store
+     */
+    set(name: string, data: Uint8Array): void;
+    /**
+     * Get a stored buffer by name.
+     * @param name - Name/path of the buffer
+     * @returns The stored data or undefined
+     */
+    get(name: string): Uint8Array | undefined;
+    createSource(filename: string, progress?: ProgressCallback): Promise<ReadSource>;
+}
+export { MemoryReadFileSystem };

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

@@ -0,0 +1,14 @@
+import { type ReadFileSystem, type ProgressCallback, type ReadSource } from './file-system';
+/**
+ * ReadFileSystem for reading from URLs using fetch.
+ * Supports optional base URL for relative paths.
+ */
+declare class UrlReadFileSystem implements ReadFileSystem {
+    private baseUrl;
+    /**
+     * @param baseUrl - Optional base URL to prepend to filenames
+     */
+    constructor(baseUrl?: string);
+    createSource(filename: string, progress?: ProgressCallback): Promise<ReadSource>;
+}
+export { UrlReadFileSystem };

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

@@ -0,0 +1,51 @@
+import { type ReadFileSystem, type ProgressCallback, type ReadSource } from './file-system';
+/**
+ * Metadata for a zip file entry.
+ */
+type ZipEntry = {
+    name: string;
+    compressedSize: number;
+    uncompressedSize: number;
+    offset: number;
+    method: number;
+};
+/**
+ * Virtual filesystem for reading files from a zip archive.
+ * Wraps any ReadSource and provides memory-efficient streaming access.
+ */
+declare class ZipReadFileSystem implements ReadFileSystem {
+    private source;
+    private entries;
+    private parsePromise;
+    private closed;
+    constructor(source: ReadSource);
+    /**
+     * Parse the central directory from the zip file.
+     * Called lazily on first createSource() or list() call.
+     * @returns Map of entry names to ZipEntry metadata
+     */
+    private parseDirectory;
+    /**
+     * Get the data offset for an entry by reading its local header.
+     * @param entry - Zip entry metadata
+     * @returns Byte offset where entry data begins
+     */
+    private getDataOffset;
+    createSource(filename: string, _progress?: ProgressCallback): Promise<ReadSource>;
+    /**
+     * List all entries in the zip file.
+     * @returns Array of entry names
+     */
+    list(): Promise<string[]>;
+    /**
+     * Get entry metadata.
+     * @param filename - Entry name
+     * @returns Entry metadata or undefined if not found
+     */
+    getEntry(filename: string): Promise<ZipEntry | undefined>;
+    /**
+     * Close the zip filesystem and underlying source.
+     */
+    close(): void;
+}
+export { ZipReadFileSystem };

package/dist/lib/io/write/crc.d.ts

@@ -0,0 +1,7 @@
+declare class Crc {
+    reset: () => void;
+    update: (data: Uint8Array) => void;
+    value: () => number;
+    constructor();
+}
+export { Crc };

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

@@ -0,0 +1,9 @@
+interface Writer {
+    write(data: Uint8Array): void | Promise<void>;
+    close(): void | Promise<void>;
+}
+interface FileSystem {
+    createWriter(filename: string): Writer | Promise<Writer>;
+    mkdir(path: string): Promise<void>;
+}
+export { type FileSystem, type Writer };

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

@@ -0,0 +1,4 @@
+export { type FileSystem, type Writer } from './file-system';
+export { writeFile } from './write-helpers';
+export { MemoryFileSystem } from './memory-file-system';
+export { ZipFileSystem } from './zip-file-system';

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

@@ -0,0 +1,7 @@
+import { type FileSystem, type Writer } from './file-system';
+declare class MemoryFileSystem implements FileSystem {
+    results: Map<string, Uint8Array>;
+    createWriter(filename: string): Writer;
+    mkdir(path: string): Promise<void>;
+}
+export { MemoryFileSystem };

package/dist/lib/io/write/write-helpers.d.ts

@@ -0,0 +1,3 @@
+import { type FileSystem } from './file-system';
+declare const writeFile: (fs: FileSystem, filename: string, data: Uint8Array | string) => Promise<void>;
+export { writeFile };

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

@@ -0,0 +1,8 @@
+import { type FileSystem, type Writer } from './file-system';
+declare class ZipFileSystem implements FileSystem {
+    close: () => Promise<void>;
+    createWriter: (filename: string) => Promise<Writer>;
+    mkdir: (path: string) => Promise<void>;
+    constructor(writer: Writer);
+}
+export { ZipFileSystem };

package/dist/lib/process.d.ts

@@ -0,0 +1,52 @@
+import { Vec3 } from 'playcanvas';
+import { DataTable } from './data-table/data-table';
+type Translate = {
+    kind: 'translate';
+    value: Vec3;
+};
+type Rotate = {
+    kind: 'rotate';
+    value: Vec3;
+};
+type Scale = {
+    kind: 'scale';
+    value: number;
+};
+type FilterNaN = {
+    kind: 'filterNaN';
+};
+type FilterByValue = {
+    kind: 'filterByValue';
+    columnName: string;
+    comparator: 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'neq';
+    value: number;
+};
+type FilterBands = {
+    kind: 'filterBands';
+    value: 0 | 1 | 2 | 3;
+};
+type FilterBox = {
+    kind: 'filterBox';
+    min: Vec3;
+    max: Vec3;
+};
+type FilterSphere = {
+    kind: 'filterSphere';
+    center: Vec3;
+    radius: number;
+};
+type Param = {
+    kind: 'param';
+    name: string;
+    value: string;
+};
+type Lod = {
+    kind: 'lod';
+    value: number;
+};
+type Summary = {
+    kind: 'summary';
+};
+type ProcessAction = Translate | Rotate | Scale | FilterNaN | FilterByValue | FilterBands | FilterBox | FilterSphere | Param | Lod | Summary;
+declare const processDataTable: (dataTable: DataTable, processActions: ProcessAction[]) => DataTable;
+export { ProcessAction, processDataTable };

package/dist/lib/read.d.ts

@@ -0,0 +1,14 @@
+import { DataTable } from './data-table/data-table';
+import { ReadFileSystem } from './io/read';
+import { Options, Param } from './types';
+type InputFormat = 'mjs' | 'ksplat' | 'splat' | 'sog' | 'ply' | 'spz' | 'lcc';
+declare const getInputFormat: (filename: string) => InputFormat;
+type ReadFileOptions = {
+    filename: string;
+    inputFormat: InputFormat;
+    options: Options;
+    params: Param[];
+    fileSystem: ReadFileSystem;
+};
+declare const readFile: (readFileOptions: ReadFileOptions) => Promise<DataTable[]>;
+export { readFile, getInputFormat, type InputFormat };

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

@@ -0,0 +1,5 @@
+import type { PlyData } from './read-ply';
+import { DataTable } from '../data-table/data-table';
+declare const isCompressedPly: (ply: PlyData) => boolean;
+declare const decompressPly: (ply: PlyData) => DataTable;
+export { isCompressedPly, decompressPly };

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

@@ -0,0 +1,4 @@
+import { DataTable } from '../data-table/data-table';
+import { ReadSource } from '../io/read';
+declare const readKsplat: (source: ReadSource) => Promise<DataTable>;
+export { readKsplat };

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

@@ -0,0 +1,5 @@
+import { DataTable } from '../data-table/data-table';
+import { ReadFileSystem } from '../io/read';
+import { Options } from '../types';
+declare const readLcc: (fileSystem: ReadFileSystem, filename: string, options: Options) => Promise<DataTable[]>;
+export { readLcc };

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

@@ -0,0 +1,4 @@
+import { DataTable } from '../data-table/data-table';
+import { Param } from '../types';
+declare const readMjs: (moduleUrl: string, params: Param[]) => Promise<DataTable>;
+export { readMjs };

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

@@ -0,0 +1,11 @@
+import { DataTable } from '../data-table/data-table';
+import { ReadSource } from '../io/read';
+type PlyData = {
+    comments: string[];
+    elements: {
+        name: string;
+        dataTable: DataTable;
+    }[];
+};
+declare const readPly: (source: ReadSource) => Promise<DataTable>;
+export { PlyData, readPly };

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

@@ -0,0 +1,10 @@
+import { DataTable } from '../data-table/data-table';
+import { ReadFileSystem } from '../io/read';
+/**
+ * Read a SOG file from a ReadFileSystem.
+ * @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
+ */
+declare const readSog: (fileSystem: ReadFileSystem, filename: string) => Promise<DataTable>;
+export { readSog };

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

@@ -0,0 +1,4 @@
+import { DataTable } from '../data-table/data-table';
+import { ReadSource } from '../io/read';
+declare const readSplat: (source: ReadSource) => Promise<DataTable>;
+export { readSplat };

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

@@ -0,0 +1,4 @@
+import { DataTable } from '../data-table/data-table';
+import { ReadSource } from '../io/read';
+declare const readSpz: (source: ReadSource) => Promise<DataTable>;
+export { readSpz };

package/dist/lib/spatial/b-tree.d.ts

@@ -0,0 +1,22 @@
+import { DataTable } from '../data-table/data-table';
+declare class Aabb {
+    min: number[];
+    max: number[];
+    constructor(min?: number[], max?: number[]);
+    largestAxis(): number;
+    largestDim(): number;
+    fromCentroids(centroids: DataTable, indices: Uint32Array): this;
+}
+interface BTreeNode {
+    count: number;
+    aabb: Aabb;
+    indices?: Uint32Array;
+    left?: BTreeNode;
+    right?: BTreeNode;
+}
+declare class BTree {
+    centroids: DataTable;
+    root: BTreeNode;
+    constructor(centroids: DataTable);
+}
+export { BTreeNode, BTree };

package/dist/lib/spatial/k-means.d.ts

@@ -0,0 +1,7 @@
+import { GraphicsDevice } from 'playcanvas';
+import { DataTable } from '../data-table/data-table';
+declare const kmeans: (points: DataTable, k: number, iterations: number, device?: GraphicsDevice) => Promise<{
+    centroids: DataTable;
+    labels: Uint32Array<ArrayBuffer>;
+}>;
+export { kmeans };

package/dist/lib/spatial/kd-tree.d.ts

@@ -0,0 +1,18 @@
+import { DataTable } from '../data-table/data-table';
+interface KdTreeNode {
+    index: number;
+    count: number;
+    left?: KdTreeNode;
+    right?: KdTreeNode;
+}
+declare class KdTree {
+    centroids: DataTable;
+    root: KdTreeNode;
+    constructor(centroids: DataTable);
+    findNearest(point: Float32Array, filterFunc?: (index: number) => boolean): {
+        index: number;
+        distanceSqr: number;
+        cnt: number;
+    };
+}
+export { KdTreeNode, KdTree };

package/dist/lib/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Options for read/write operations.
+ */
+type Options = {
+    /** Number of iterations for SOG SH compression (higher = better quality). Default: 10 */
+    iterations: number;
+    /** LOD levels to read from LCC input */
+    lodSelect: number[];
+    /** Viewer settings JSON for HTML output */
+    viewerSettingsJson?: any;
+    /** Whether to generate unbundled HTML output with separate files */
+    unbundled: boolean;
+    /** Approximate number of Gaussians per LOD chunk (in thousands). Default: 512 */
+    lodChunkCount: number;
+    /** Approximate size of an LOD chunk in world units (meters). Default: 16 */
+    lodChunkExtent: number;
+};
+/**
+ * Parameter passed to MJS generator scripts.
+ */
+type Param = {
+    name: string;
+    value: string;
+};
+export type { Options, Param };

package/dist/lib/utils/base64.d.ts

@@ -0,0 +1,2 @@
+declare const toBase64: (bytes: Uint8Array) => string;
+export { toBase64 };

package/dist/lib/utils/logger.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Logger interface for injectable logging implementation.
+ */
+interface Logger {
+    /** Log normal messages. */
+    log(...args: any[]): void;
+    /** Log warning messages. */
+    warn(...args: any[]): void;
+    /** Log error messages. */
+    error(...args: any[]): void;
+    /** Log debug/verbose messages. */
+    debug(...args: any[]): void;
+    /** Output text without newline (for progress indicators). */
+    progress(text: string): void;
+    /** Output data to stdout (for piping). */
+    output(text: string): void;
+}
+/**
+ * Global logger instance with injectable implementation.
+ * Use setLogger() to provide a custom implementation (e.g., Node.js with process.stdout).
+ * Use setQuiet() to suppress log/warn/progress output.
+ */
+declare const logger: {
+    /**
+     * Set a custom logger implementation.
+     * @param l - The logger implementation to use.
+     */
+    setLogger(l: Logger): void;
+    /**
+     * Set quiet mode. When quiet, log/warn/progress are suppressed. Errors always show.
+     * @param q - Whether to enable quiet mode.
+     */
+    setQuiet(q: boolean): void;
+    /**
+     * Log normal messages. Suppressed in quiet mode.
+     * @param args - The arguments to log.
+     */
+    log(...args: any[]): void;
+    /**
+     * Log warning messages. Suppressed in quiet mode.
+     * @param args - The arguments to log.
+     */
+    warn(...args: any[]): void;
+    /**
+     * Log error messages. Always shown, even in quiet mode.
+     * @param args - The arguments to log.
+     */
+    error(...args: any[]): void;
+    /**
+     * Log debug/verbose messages. Suppressed in quiet mode.
+     * @param args - The arguments to log.
+     */
+    debug(...args: any[]): void;
+    /**
+     * Output text without newline (for progress indicators). Suppressed in quiet mode.
+     * @param text - The text to output.
+     */
+    progress(text: string): void;
+    /**
+     * Output data to stdout (for piping). Always shown, even in quiet mode.
+     * @param text - The text to output.
+     */
+    output(text: string): void;
+};
+export { logger };
+export type { Logger };

package/dist/lib/utils/math.d.ts

@@ -0,0 +1,2 @@
+declare const sigmoid: (v: number) => number;
+export { sigmoid };

package/dist/lib/utils/rotate-sh.d.ts

@@ -0,0 +1,6 @@
+import { Mat3 } from 'playcanvas';
+declare class RotateSH {
+    apply: (result: Float32Array | number[], src?: Float32Array | number[]) => void;
+    constructor(mat: Mat3);
+}
+export { RotateSH };