@speridlabs/visus 2.4.2 → 2.5.0

package/dist/main.d.ts

@@ -1,5 +1,93 @@
 import * as THREE from 'three';
 
+export declare class AnimationController implements AnimationState {
+    private _progress;
+    private _isPlaying;
+    private _isComplete;
+    private _startTime;
+    private _duration;
+    private _delay;
+    private _easing;
+    private _type;
+    private _autoPlay;
+    private _center;
+    constructor(options: AnimationOptions);
+    /** Current progress 0-1 (eased) */
+    get progress(): number;
+    get isPlaying(): boolean;
+    get isComplete(): boolean;
+    get type(): AnimationType;
+    get center(): THREE.Vector3;
+    /** Set the animation center point (typically bounding box center) */
+    setCenter(center: THREE.Vector3): void;
+    play(): void;
+    stop(): void;
+    reset(): void;
+    /** Skip to end state */
+    complete(): void;
+    /** Called from onBeforeRender - returns true if uniforms need update */
+    update(currentTime: number): boolean;
+    /** Should auto-play be triggered on load? */
+    shouldAutoPlay(): boolean;
+}
+
+/**
+ * Animation effect definition - SELF-CONTAINED
+ *
+ * Each effect provides its own GLSL code implementing the standard
+ * `applyAnimation` function signature. This code gets injected into
+ * the vertex shader template.
+ */
+declare interface AnimationEffect_2 {
+    type: AnimationType;
+    defaultDuration: number;
+    /**
+     * GLSL code defining the applyAnimation function.
+     *
+     * MUST implement this exact signature:
+     * ```glsl
+     * void applyAnimation(
+     *   inout vec3 position,
+     *   inout vec3 scale,
+     *   inout vec4 color,
+     *   float progress,
+     *   vec3 center
+     * )
+     * ```
+     *
+     * - position: splat center in model space
+     * - scale: splat scales in LOG SPACE (exp() applied AFTER animation)
+     * - color: RGBA color
+     * - progress: animation progress 0-1 (already eased)
+     * - center: bounding box center point
+     *
+     * **IMPORTANT**: `SplatMaterial.setAnimation()` injects a guard
+     * `if (animationProgress < 1.0)` around the call to `applyAnimation()`,
+     * so effect code will NEVER run at exactly `progress == 1.0`.
+     * Effects should be designed such that they converge to a no-op state
+     * as progress approaches 1.0 (e.g., all splats fully revealed, no
+     * additional transformations applied).
+     */
+    shaderCode: string;
+}
+export { AnimationEffect_2 as AnimationEffect }
+
+export declare interface AnimationOptions {
+    delay?: number;
+    duration?: number;
+    autoPlay?: boolean;
+    easing?: EasingType;
+    type: AnimationType;
+}
+
+export declare interface AnimationState {
+    readonly progress: number;
+    readonly isPlaying: boolean;
+    readonly isComplete: boolean;
+}
+
+export declare type AnimationType = 'spread' | 'wave' | 'none';
+
 /**
  * Simplified bounding box class that tracks min/max points
  */
@@ -45,6 +133,10 @@ export declare class BoundingBox {
     clone(): BoundingBox;
 }
 
+export declare type EasingType = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeOutExpo';
+
+export declare const getEffect: (type: AnimationType) => AnimationEffect_2;
+
 /**
  * Class for loading PLY files with Gaussian Splat data
  */
@@ -52,7 +144,7 @@ export declare class PlyLoader extends THREE.Loader {
     private requestId;
     private worker;
     private pendingCallbacks;
-    constructor(manager?: THREE.LoadingManager);
+    constructor(manager?: THREE.LoadingManager, options?: PlyLoaderOptions);
     /**
      * Handles messages received from the parsing worker
      * @param event The message event from the worker
@@ -90,11 +182,15 @@ export declare class PlyLoader extends THREE.Loader {
     private createWorkerCode;
 }
 
+export declare interface PlyLoaderOptions {
+    withCredentials?: boolean;
+}
+
 /**
  * Class for loading SOGS (Self Organizing Gaussians) files
  */
 export declare class SogsLoader extends THREE.Loader {
-    constructor(manager?: THREE.LoadingManager);
+    constructor(manager?: THREE.LoadingManager, options?: SogsLoaderOptions);
     /**
      * Detect if a buffer is a ZIP file by checking magic bytes
      * ZIP files start with signature: PK\x03\x04 (0x50 0x4B 0x03 0x04)
@@ -120,6 +216,10 @@ export declare class SogsLoader extends THREE.Loader {
     private parseZipAsync;
 }
 
+export declare interface SogsLoaderOptions {
+    withCredentials?: boolean;
+}
+
 export declare class SplatData {
     numSplats: number;
     textureWidth: number;
@@ -139,6 +239,7 @@ export declare class SplatData {
 
 export declare class SplatMaterial extends THREE.ShaderMaterial {
     constructor(options?: SplatMaterialOptions);
+    private _shaderTemplate;
     setTexWidth(w: number): void;
     /**
      * Update the viewport size
@@ -167,6 +268,19 @@ export declare class SplatMaterial extends THREE.ShaderMaterial {
      * @param count Number of splats
      */
     setNumSplats(count: number): void;
+    /**
+     * Configure animation effect. Rebuilds shader with effect's GLSL code.
+     * @param effect - Animation effect to use (null to disable)
+     */
+    setAnimation(effect: AnimationEffect_2 | null): void;
+    /**
+     * Set animation progress (0 = start, 1 = complete/no animation)
+     */
+    setAnimationProgress(progress: number): void;
+    /**
+     * Set animation center point
+     */
+    setAnimationCenter(center: THREE.Vector3): void;
 }
 
 export declare interface SplatMaterialOptions {
@@ -184,6 +298,8 @@ export declare class SplatMesh extends THREE.Mesh {
     options: SplatMeshOptions;
     splatData: SplatData | null;
     textureManager: TextureManager;
+    /** Animation controller (null if no animation configured) */
+    animation: AnimationController | null;
     material: SplatMaterial;
     geometry: THREE.InstancedBufferGeometry;
     private lastCameraPositionLocal;
@@ -245,6 +361,8 @@ export declare class SplatMesh extends THREE.Mesh {
 export declare interface SplatMeshOptions extends SplatMaterialOptions {
     autoSort?: boolean;
     keepSplatData?: boolean;
+    /** Animation configuration */
+    animation?: AnimationOptions;
 }
 
 declare interface SplatRanges {