@speridlabs/visus 2.3.0 → 2.4.0

package/dist/main.d.ts

@@ -1,347 +1,335 @@
-import * as THREE from 'three';
-
-/**
- * Simplified bounding box class that tracks min/max points
- */
-export declare class BoundingBox {
-    min: THREE.Vector3;
-    max: THREE.Vector3;
-    center: THREE.Vector3;
-    /** Half extents (size/2) */
-    halfExtents: THREE.Vector3;
-    /**
-     * Reset the bounding box to its initial state
-     */
-    reset(): void;
-    /**
-     * Expand the bounding box to include the given point
-     * @param point Point to include in the bounding box
-     */
-    expandByPoint(point: THREE.Vector3): void;
-    /**
-     * Expand this bounding box to include another bounding box
-     * @param box Bounding box to include
-     */
-    expandByBox(box: BoundingBox): void;
-    /**
-     * Update the center and half extents based on min/max
-     */
-    private updateDerived;
-    /**
-     * Check if this box contains a point
-     * @param point Point to check
-     * @returns True if the point is inside the box
-     */
-    containsPoint(point: THREE.Vector3): boolean;
-    /**
-     * Create a Three.js Box3 from this bounding box
-     * @returns THREE.Box3 representation
-     */
-    toBox3(): THREE.Box3;
-    /**
-     * Create a clone of this bounding box
-     * @returns New bounding box with the same values
-     */
-    clone(): BoundingBox;
-}
-
-/**
- * Class for loading PLY files with Gaussian Splat data
- */
-export declare class PlyLoader extends THREE.Loader {
-    private requestId;
-    private worker;
-    private pendingCallbacks;
-    constructor(manager?: THREE.LoadingManager);
-    /**
-     * Handles messages received from the parsing worker
-     * @param event The message event from the worker
-     */
-    private onWorkerMessage;
-    /**
-     * Load a PLY file with Gaussian Splat data
-     * @param url URL of the PLY file
-     * @param onLoad Optional callback when loading is complete
-     * @param onProgress Optional progress callback
-     * @param onError Optional error callback
-     */
-    load(url: string, onLoad?: (data: SplatData) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): void;
-    /**
-     * Load a PLY file asynchronously and return a Promise
-     * @param url URL of the PLY file
-     * @param onProgress Optional progress callback
-     * @returns A Promise that resolves with the parsed SplatData
-     */
-    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<SplatData>;
-    /**
-     * Parse PLY buffer data asynchronously using Web Worker
-     * @param buffer ArrayBuffer containing PLY data
-     * @returns Promise that resolves with parsed SplatData
-     */
-    private parseAsync;
-    /**
-     * Terminate the Web Worker and clean up resources
-     */
-    dispose(): void;
-    /**
-     * Creates the self-contained code for the parsing Web Worker
-     * @returns A string containing the JavaScript code for the worker
-     */
-    private createWorkerCode;
-}
-
-export declare class SplatData {
-    numSplats: number;
-    positions: Float32Array;
-    rotations: Float32Array;
-    scales: Float32Array;
-    colors: Float32Array;
-    opacities: Float32Array;
-    boundingBox: BoundingBox;
-    constructor(numSplats?: number);
-    private allocateBuffers;
-    /**
-     * Set data for a specific splat
-     * @param index Splat index
-     * @param position Position vector
-     * @param rotation Quaternion
-     * @param scale Scale vector (expects LOG SCALE)
-     * @param color Color
-     * @param opacity Opacity value
-     */
-    setSplat(index: number, position: THREE.Vector3, rotation: THREE.Quaternion, scale: THREE.Vector3, color: THREE.Color, opacity: number): void;
-    /**
-     * Get a splat's data
-     * @param index Splat index
-     * @returns Object containing splat data (linear scale)
-     */
-    getSplat(index: number): {
-        position: THREE.Vector3;
-        rotation: THREE.Quaternion;
-        scale: THREE.Vector3;
-        color: THREE.Color;
-        opacity: number;
-    };
-    /**
-     * Calculate the bounding box for all splats
-     * NOTE: Currently it only uses positions, not the actual splat bounds
-     */
-    calculateBoundingBox(): BoundingBox;
-    /**
-     * Create a Three.js BufferGeometry from this splat data
-     * This is for visualization/debugging purposes only, not for rendering
-     */
-    createDebugGeometry(): THREE.BufferGeometry;
-}
-
-export declare class SplatMaterial extends THREE.ShaderMaterial {
-    constructor(options?: SplatMaterialOptions);
-    /**
-     * Update the viewport size
-     * @param width Viewport width
-     * @param height Viewport height
-     */
-    updateViewport(width: number, height: number): void;
-    /**
-     * Set transform texture A (positions)
-     * @param texture Texture containing positions
-     */
-    setTransformA(texture: THREE.Texture): void;
-    /**
-     * Set transform texture B (rotation, scale)
-     * @param texture Texture containing rotation and scale data
-     */
-    setTransformB(texture: THREE.Texture): void;
-    /**
-     * Set color texture
-     * @param texture Texture containing colors
-     */
-    setColorTexture(texture: THREE.Texture): void;
-    /**
-     * Set order texture
-     * @param texture Texture containing sort order
-     */
-    setOrderTexture(texture: THREE.Texture): void;
-    /**
-     * Set number of splats to render
-     * @param count Number of splats
-     */
-    setNumSplats(count: number): void;
-}
-
-export declare interface SplatMaterialOptions {
-    alphaTest?: number;
-    alphaHash?: boolean;
-    toneMapped?: boolean;
-}
-
-/**
- * A mesh that renders Gaussian splats
- * Not a real MESH, but a custom geometry with instancing
- */
-export declare class SplatMesh extends THREE.Mesh {
-    sorter: SplatSorter;
-    splatData: SplatData | null;
-    options: SplatMeshOptions;
-    textureManager: TextureManager;
-    material: SplatMaterial;
-    geometry: THREE.InstancedBufferGeometry;
-    private lastCameraPositionLocal;
-    private lastCameraDirectionLocal;
-    private invModelMatrix;
-    private _vpW;
-    private _vpH;
-    private _size;
-    private _camPosW;
-    private _camDirW;
-    private _camPosL;
-    private _camDirL;
-    /** Number of splats combined into a single instanced draw call. */
-    private static INSTANCE_SIZE;
-    /**
-     * Create a new SplatMesh for rendering Gaussian splats
-     * @param splatData The splat data to render
-     * @param options Rendering options
-     */
-    constructor(splatData: SplatData, options?: SplatMeshOptions);
-    private onSorterUpdated;
-    /**
-     * Creates the instanced geometry for rendering splats.
-     * @param totalSplats Total number of splats in the data.
-     * @param instanceSize Number of splats per instance.
-     * @returns InstancedBufferGeometry
-     */
-    private static createInstancedGeometry;
-    /**
-     * Create chunks data (bounding box min/max) for the sorter.
-     * @returns Float32Array containing chunk data [minX, minY, minZ, maxX, maxY, maxZ] or null.
-     */
-    private createChunks;
-    /**
-     * Update the viewport size
-     * @param width Viewport width
-     * @param height Viewport height
-     */
-    updateViewport(width: number, height: number): void;
-    /**
-     * Sorts splats based on camera position and direction.
-     * @param camera The camera to sort against.
-     */
-    sort(camera: THREE.Camera): void;
-    /**
-     * THREE.js hook called before rendering the object.
-     * Used here to trigger sorting and update viewport.
-     * @param renderer The renderer
-     * @param scene The scene
-     * @param camera The camera
-     */
-    onBeforeRender(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera): void;
-    /**
-     * Dispose of resources
-     */
-    dispose(): void;
-}
-
-export declare interface SplatMeshOptions extends SplatMaterialOptions {
-    autoSort?: boolean;
-    keepSplatData?: boolean;
-}
-
-/**
- * Manages sorting of splats based on camera view using a Web Worker.
- */
-export declare class SplatSorter extends THREE.EventDispatcher<{
-    updated: SplatSortUpdateEvent;
-}> {
-    private worker;
-    private centers;
-    private orderTexture;
-    /** Bounding box data for optimization */
-    private chunks;
-    private lastCameraPosition;
-    private lastCameraDirection;
-    constructor();
-    /**
-     * Handles messages received from the sorting worker.
-     * @param event The message event from the worker.
-     */
-    private onWorkerMessage;
-    /**
-     * Initializes the sorter with necessary data and textures.
-     * @param orderTexture The THREE.DataTexture (R32UI) to store the sorted splat indices.
-     * @param centers A Float32Array containing the center position (x, y, z) for each splat.
-     * @param chunks Optional: A Float32Array containing bounding box chunk data [minX, minY, minZ, maxX, maxY, maxZ, ...] for optimization.
-     * @param transferOwnership Optional: If true, transfers ownership of centers buffer to worker (saves memory, main thread loses access). Default: false.
-     */
-    init(orderTexture: THREE.DataTexture, centers: Float32Array, chunks?: Float32Array, transferOwnership?: boolean): void;
-    /**
-     * Applies an optional mapping to filter or reorder splats before sorting.
-     * The sorter will only consider splats whose original indices are present in the mapping.
-     * @param mapping A Uint32Array where each element is the *original* index of a splat to include, or null to reset mapping.
-     */
-    setMapping(mapping: Uint32Array | null): void;
-    /**
-     * Updates the camera parameters used for sorting.
-     * @param position The camera's position in the sorter's local coordinate space.
-     * @param direction The camera's forward direction in the sorter's local coordinate space.
-     */
-    setCamera(position: THREE.Vector3, direction: THREE.Vector3): void;
-    /**
-     * Terminates the Web Worker and cleans up resources.
-     */
-    dispose(): void;
-    /**
-     * Creates the self-contained code for the sorting Web Worker.
-     * @returns A string containing the JavaScript code for the worker.
-     */
-    private createWorkerCode;
-}
-
-/** Event dispatched when the sort is updated */
-declare interface SplatSortUpdateEvent extends THREE.Event {
-    type: 'updated';
-    count: number;
-}
-
-export declare class TextureManager {
-    textureWidth: number;
-    textureHeight: number;
-    transformA: THREE.DataTexture;
-    transformB: THREE.DataTexture;
-    colorTexture: THREE.DataTexture;
-    orderTexture: THREE.DataTexture;
-    /**
-     * Create a new TextureManager for a set of splats
-     * @param splatData The splat data to manage textures for
-     */
-    constructor(splatData: SplatData);
-    /**
-     * Create the transform A texture (positions and quaternion w component)
-     * @param splatData The splat data
-     * @returns DataTexture containing position data
-     */
-    private createTransformATexture;
-    /**
-     * Create the transform B texture (scale and rotation xyz)
-     * @param splatData The splat data
-     * @returns DataTexture containing scale and rotation data
-     */
-    private createTransformBTexture;
-    /**
-     * Create the color texture (RGB and opacity)
-     * @param splatData The splat data
-     * @returns DataTexture containing color data
-     */
-    private createColorTexture;
-    /**
-     * Create the order texture for sorting
-     * @param numSplats Number of splats
-     * @returns DataTexture for storing order indices
-     */
-    private createOrderTexture;
-    dispose(): void;
-}
-
-export declare const VERSION = "0.3.0";
-
-export { }
+import * as THREE from 'three';
+
+/**
+ * Simplified bounding box class that tracks min/max points
+ */
+export declare class BoundingBox {
+    min: THREE.Vector3;
+    max: THREE.Vector3;
+    center: THREE.Vector3;
+    /** Half extents (size/2) */
+    halfExtents: THREE.Vector3;
+    /**
+     * Reset the bounding box to its initial state
+     */
+    reset(): void;
+    /**
+     * Expand the bounding box to include the given point
+     * @param point Point to include in the bounding box
+     */
+    expandByPoint(point: THREE.Vector3): void;
+    /**
+     * Expand this bounding box to include another bounding box
+     * @param box Bounding box to include
+     */
+    expandByBox(box: BoundingBox): void;
+    /**
+     * Update the center and half extents based on min/max
+     */
+    private updateDerived;
+    /**
+     * Check if this box contains a point
+     * @param point Point to check
+     * @returns True if the point is inside the box
+     */
+    containsPoint(point: THREE.Vector3): boolean;
+    /**
+     * Create a Three.js Box3 from this bounding box
+     * @returns THREE.Box3 representation
+     */
+    toBox3(): THREE.Box3;
+    /**
+     * Create a clone of this bounding box
+     * @returns New bounding box with the same values
+     */
+    clone(): BoundingBox;
+}
+
+/**
+ * Class for loading PLY files with Gaussian Splat data
+ */
+export declare class PlyLoader extends THREE.Loader {
+    private requestId;
+    private worker;
+    private pendingCallbacks;
+    constructor(manager?: THREE.LoadingManager);
+    /**
+     * Handles messages received from the parsing worker
+     * @param event The message event from the worker
+     */
+    private onWorkerMessage;
+    /**
+     * Load a PLY file with Gaussian Splat data
+     * @param url URL of the PLY file
+     * @param onLoad Optional callback when loading is complete
+     * @param onProgress Optional progress callback
+     * @param onError Optional error callback
+     */
+    load(url: string, onLoad?: (data: SplatData) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): void;
+    /**
+     * Load a PLY file asynchronously and return a Promise
+     * @param url URL of the PLY file
+     * @param onProgress Optional progress callback
+     * @returns A Promise that resolves with the parsed SplatData
+     */
+    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<SplatData>;
+    /**
+     * Parse PLY buffer data asynchronously using Web Worker
+     * @param buffer ArrayBuffer containing PLY data
+     * @returns Promise that resolves with parsed SplatData
+     */
+    private parseAsync;
+    /**
+     * Terminate the Web Worker and clean up resources
+     */
+    dispose(): void;
+    /**
+     * Creates the self-contained code for the parsing Web Worker
+     * @returns A string containing the JavaScript code for the worker
+     */
+    private createWorkerCode;
+}
+
+/**
+ * Class for loading SOGS (Self Organizing Gaussians) files
+ */
+export declare class SogsLoader extends THREE.Loader {
+    /**
+     * Detect if a buffer is a ZIP file by checking magic bytes
+     * ZIP files start with signature: PK\x03\x04 (0x50 0x4B 0x03 0x04)
+     */
+    private isZipBuffer;
+    /**
+     * Load a SOGS file (meta.json + textures)
+     * @param url URL of the meta.json file
+     * @param onLoad Optional callback when loading is complete
+     * @param onProgress Optional progress callback
+     * @param onError Optional error callback
+     */
+    load(url: string, onLoad?: (data: SplatData) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: ErrorEvent) => void): void;
+    /**
+     * Load a SOGS file asynchronously and return a Promise
+     * @param url URL of the meta.json file
+     * @param onProgress Optional progress callback
+     * @returns A Promise that resolves with the parsed SplatData
+     */
+    loadAsync(url: string, onProgress?: (event: ProgressEvent) => void): Promise<SplatData>;
+    private parseAsync;
+    private parseMetaAsync;
+    private parseZipAsync;
+}
+
+export declare class SplatData {
+    numSplats: number;
+    textureWidth: number;
+    textureHeight: number;
+    ranges: SplatRanges;
+    centers: Float32Array;
+    boundingBox: BoundingBox;
+    packedColor: Uint8Array;
+    packedGeometry: Uint32Array;
+    constructor(numSplats: number, textureWidth: number, textureHeight: number, centers: Float32Array, packedGeometry: Uint32Array, packedColor: Uint8Array, ranges: SplatRanges, boundingBox: BoundingBox);
+    /**
+     * Optional: Reconstruct a full JS object for a specific splat.
+     * Useful for raycasting or debugging.
+     */
+    dispose(): void;
+}
+
+export declare class SplatMaterial extends THREE.ShaderMaterial {
+    constructor(options?: SplatMaterialOptions);
+    setTexWidth(w: number): void;
+    /**
+     * Update the viewport size
+     * @param width Viewport width
+     * @param height Viewport height
+     */
+    updateViewport(width: number, height: number): void;
+    /**
+     * Set the main packed geometry texture (RGBA32UI)
+     */
+    setPackedGeometry(texture: THREE.Texture): void;
+    /**
+     * Set the packed color texture (RGBA8)
+     */
+    setPackedColor(texture: THREE.Texture): void;
+    /**
+     * Set order texture for sorting
+     */
+    setOrderTexture(texture: THREE.Texture): void;
+    /**
+     * Set the ranges needed to decompress the packed floats
+     */
+    setRanges(ranges: SplatRanges): void;
+    /**
+     * Set number of splats to render
+     * @param count Number of splats
+     */
+    setNumSplats(count: number): void;
+}
+
+export declare interface SplatMaterialOptions {
+    alphaTest?: number;
+    alphaHash?: boolean;
+    toneMapped?: boolean;
+}
+
+/**
+ * A mesh that renders Gaussian splats
+ * Not a real MESH, but a custom geometry with instancing
+ */
+export declare class SplatMesh extends THREE.Mesh {
+    sorter: SplatSorter;
+    options: SplatMeshOptions;
+    splatData: SplatData | null;
+    textureManager: TextureManager;
+    material: SplatMaterial;
+    geometry: THREE.InstancedBufferGeometry;
+    private lastCameraPositionLocal;
+    private lastCameraDirectionLocal;
+    private invModelMatrix;
+    private _vpW;
+    private _vpH;
+    private _size;
+    private _camPosW;
+    private _camDirW;
+    private _camPosL;
+    private _camDirL;
+    /** Number of splats combined into a single instanced draw call. */
+    private static INSTANCE_SIZE;
+    /**
+     * Create a new SplatMesh for rendering Gaussian splats
+     * @param splatData The splat data to render
+     * @param options Rendering options
+     */
+    constructor(splatData: SplatData, options?: SplatMeshOptions);
+    private onSorterUpdated;
+    /**
+     * Creates the instanced geometry for rendering splats.
+     * @param totalSplats Total number of splats in the data.
+     * @param instanceSize Number of splats per instance.
+     * @returns InstancedBufferGeometry
+     */
+    private static createInstancedGeometry;
+    /**
+     * Create chunks data (bounding box min/max) for the sorter.
+     * @returns Float32Array containing chunk data [minX, minY, minZ, maxX, maxY, maxZ] or null.
+     */
+    private createChunks;
+    /**
+     * Update the viewport size
+     * @param width Viewport width
+     * @param height Viewport height
+     */
+    updateViewport(width: number, height: number): void;
+    /**
+     * Sorts splats based on camera position and direction.
+     * @param camera The camera to sort against.
+     */
+    sort(camera: THREE.Camera): void;
+    /**
+     * THREE.js hook called before rendering the object.
+     * Used here to trigger sorting and update viewport.
+     * @param renderer The renderer
+     * @param scene The scene
+     * @param camera The camera
+     */
+    onBeforeRender(renderer: THREE.WebGLRenderer, scene: THREE.Scene, camera: THREE.Camera): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+
+export declare interface SplatMeshOptions extends SplatMaterialOptions {
+    autoSort?: boolean;
+    keepSplatData?: boolean;
+}
+
+declare interface SplatRanges {
+    sh0: {
+        min: THREE.Vector3;
+        max: THREE.Vector3;
+    };
+    means: {
+        min: THREE.Vector3;
+        max: THREE.Vector3;
+    };
+    scales: {
+        min: THREE.Vector3;
+        max: THREE.Vector3;
+    };
+}
+
+/**
+ * Manages sorting of splats based on camera view using a Web Worker.
+ */
+export declare class SplatSorter extends THREE.EventDispatcher<{
+    updated: SplatSortUpdateEvent;
+}> {
+    private worker;
+    private centers;
+    private orderTexture;
+    /** Bounding box data for optimization */
+    private chunks;
+    private lastCameraPosition;
+    private lastCameraDirection;
+    constructor();
+    /**
+     * Handles messages received from the sorting worker.
+     * @param event The message event from the worker.
+     */
+    private onWorkerMessage;
+    /**
+     * Initializes the sorter with necessary data and textures.
+     * @param orderTexture The THREE.DataTexture (R32UI) to store the sorted splat indices.
+     * @param centers A Float32Array containing the center position (x, y, z) for each splat.
+     * @param chunks Optional: A Float32Array containing bounding box chunk data [minX, minY, minZ, maxX, maxY, maxZ, ...] for optimization.
+     * @param transferOwnership Optional: If true, transfers ownership of centers buffer to worker (saves memory, main thread loses access). Default: false.
+     */
+    init(orderTexture: THREE.DataTexture, centers: Float32Array, chunks?: Float32Array, transferOwnership?: boolean): void;
+    /**
+     * Applies an optional mapping to filter or reorder splats before sorting.
+     * The sorter will only consider splats whose original indices are present in the mapping.
+     * @param mapping A Uint32Array where each element is the *original* index of a splat to include, or null to reset mapping.
+     */
+    setMapping(mapping: Uint32Array | null): void;
+    /**
+     * Updates the camera parameters used for sorting.
+     * @param position The camera's position in the sorter's local coordinate space.
+     * @param direction The camera's forward direction in the sorter's local coordinate space.
+     */
+    setCamera(position: THREE.Vector3, direction: THREE.Vector3): void;
+    /**
+     * Terminates the Web Worker and cleans up resources.
+     */
+    dispose(): void;
+    /**
+     * Creates the self-contained code for the sorting Web Worker.
+     * @returns A string containing the JavaScript code for the worker.
+     */
+    private createWorkerCode;
+}
+
+/** Event dispatched when the sort is updated */
+declare interface SplatSortUpdateEvent extends THREE.Event {
+    type: 'updated';
+    count: number;
+}
+
+export declare class TextureManager {
+    packedGeometry: THREE.DataTexture;
+    packedColor: THREE.DataTexture;
+    orderTexture: THREE.DataTexture;
+    width: number;
+    height: number;
+    constructor(data: SplatData);
+    private createGeometryTexture;
+    private createColorTexture;
+    private createOrderTexture;
+    dispose(): void;
+}
+
+export declare const VERSION = "0.3.0";
+
+export { }