@tableslayer/ui 0.1.3 → 0.1.4

package/src/lib/components/Stage/components/MapLayer/dataSources/GifDataSource.ts

@@ -0,0 +1,265 @@
+import { decompressFrames, parseGIF } from 'gifuct-js';
+import * as THREE from 'three';
+import type { Size } from '../../../types';
+import type { IMapDataSource } from './IMapDataSource';
+
+interface GifFrame {
+  dims: {
+    width: number;
+    height: number;
+    left: number;
+    top: number;
+  };
+  patch: Uint8ClampedArray;
+  delay: number;
+  disposalType?: number;
+}
+
+/**
+ * Data source for loading and animating GIF images as textures in a 3D scene.
+ *
+ * This class implements the IMapDataSource interface to provide GIF animation
+ * capabilities for map layers. It handles GIF parsing, frame decompression,
+ * and real-time animation rendering using HTML5 Canvas and Three.js textures.
+ */
+export class GifDataSource implements IMapDataSource {
+  /** Canvas element used for rendering the GIF frames */
+  private gifCanvas: HTMLCanvasElement | null = null;
+  /** 2D rendering context for the main GIF canvas */
+  private gifCtx: CanvasRenderingContext2D | null = null;
+  /** Temporary canvas used for patch rendering of individual frames */
+  private tempCanvas: HTMLCanvasElement | null = null;
+  /** 2D rendering context for the temporary canvas */
+  private tempCtx: CanvasRenderingContext2D | null = null;
+  /** Three.js texture created from the GIF canvas */
+  private texture: THREE.CanvasTexture | null = null;
+  /** Dimensions of the GIF image */
+  private size: Size | null = null;
+  /** Array of decompressed GIF frames */
+  private frames: GifFrame[] = [];
+  /** Index of the currently displayed frame */
+  private currentFrameIndex = 0;
+  /** Animation frame ID for canceling the animation loop */
+  private animationId: number | null = null;
+  /** Timestamp when the animation started for timing calculations */
+  private startTime = 0;
+  /** Timestamp of the last frame render */
+  private lastFrameTime = 0;
+  /** The total time the animation has been playing */
+  private totalPlayTime = 0;
+
+  /**
+   * Gets the Three.js texture containing the animated GIF.
+   *
+   * @returns The canvas texture with the current frame, or null if not loaded
+   */
+  getTexture(): THREE.Texture | null {
+    return this.texture;
+  }
+
+  /**
+   * Gets the dimensions of the GIF image.
+   *
+   * @returns The width and height of the GIF, or null if not loaded
+   */
+  getSize(): Size | null {
+    return this.size;
+  }
+
+  /**
+   * Loads and initializes a GIF from a URL.
+   *
+   * This method fetches the GIF data, parses it, decompresses the frames,
+   * sets up the rendering canvases, and starts the animation loop.
+   *
+   * @param url - The URL of the GIF file to load
+   * @returns A promise that resolves when the GIF is loaded and ready
+   * @throws Error if the GIF cannot be fetched, parsed, or has no frames
+   */
+  async load(url: string): Promise<void> {
+    // Dispose of previous resources
+    this.dispose();
+
+    return new Promise(async (resolve, reject) => {
+      try {
+        // Fetch the GIF data
+        const response = await fetch(url);
+        const arrayBuffer = await response.arrayBuffer();
+
+        // Parse the GIF
+        const gif = parseGIF(arrayBuffer);
+        this.frames = decompressFrames(gif, true);
+
+        if (this.frames.length === 0) {
+          throw new Error('No frames found in GIF');
+        }
+
+        // Get dimensions from the first frame
+        const firstFrame = this.frames[0];
+        this.size = {
+          width: firstFrame.dims.width,
+          height: firstFrame.dims.height
+        };
+
+        // Create canvas for rendering
+        this.gifCanvas = document.createElement('canvas');
+        this.gifCanvas.width = this.size.width;
+        this.gifCanvas.height = this.size.height;
+
+        // Create temporary canvas for patch rendering
+        this.tempCanvas = document.createElement('canvas');
+        this.tempCtx = this.tempCanvas.getContext('2d')!;
+
+        // Create texture from canvas
+        this.texture = new THREE.CanvasTexture(this.gifCanvas);
+        this.texture.colorSpace = THREE.SRGBColorSpace;
+
+        // Start animation
+        this.startAnimation();
+
+        resolve();
+      } catch (error) {
+        console.error('Failed to load GIF:', error);
+        reject(error);
+      }
+    });
+  }
+
+  /**
+   * Starts the GIF animation loop.
+   *
+   * This method initializes the animation by setting up the rendering context,
+   * starting the timing mechanism, and beginning the animation frame loop.
+   * The animation automatically loops when all frames have been displayed.
+   */
+  private startAnimation(): void {
+    if (!this.gifCanvas || this.frames.length === 0) return;
+
+    this.gifCtx = this.gifCanvas.getContext('2d')!;
+    this.startTime = performance.now();
+    this.lastFrameTime = this.startTime;
+    this.currentFrameIndex = -1;
+    this.totalPlayTime = 0;
+
+    const animate = () => {
+      this.animationId = requestAnimationFrame(animate);
+
+      const currentTime = performance.now();
+      const elapsedTime = currentTime - this.lastFrameTime;
+      this.lastFrameTime = currentTime;
+
+      const currentFrame = this.frames[this.currentFrameIndex];
+      const frameDelay = currentFrame?.delay ?? 0;
+
+      this.totalPlayTime += elapsedTime;
+
+      // If the current frame has played for its duration, advance to the next frame
+      if (this.totalPlayTime >= frameDelay) {
+        this.totalPlayTime -= frameDelay;
+        this.currentFrameIndex++;
+
+        // Loop back to the beginning
+        if (this.currentFrameIndex >= this.frames.length) {
+          this.currentFrameIndex = 0;
+        }
+
+        this.renderFrame(this.currentFrameIndex);
+
+        // Update texture
+        if (this.texture) {
+          this.texture.needsUpdate = true;
+        }
+      }
+    };
+
+    // Start the animation loop
+    this.animationId = requestAnimationFrame(animate);
+  }
+
+  /**
+   * Renders a specific frame of the GIF animation.
+   *
+   * This method handles frame disposal methods and delegates the actual
+   * drawing to the drawPatch method.
+   *
+   * @param frameIndex - The index of the frame to render
+   */
+  private renderFrame(frameIndex: number): void {
+    const frame = this.frames[frameIndex];
+
+    // Clear canvas if disposal method requires it (like the example)
+    if (frame.disposalType === 2) {
+      this.gifCtx!.clearRect(0, 0, this.gifCanvas!.width, this.gifCanvas!.height);
+    }
+
+    // Draw the patch using the temporary canvas approach
+    this.drawPatch(frame);
+  }
+
+  /**
+   * Draws a frame patch onto the main canvas.
+   *
+   * This method uses a temporary canvas to efficiently render individual
+   * frame patches at their correct positions within the GIF.
+   *
+   * @param frame - The frame object containing patch data and dimensions
+   */
+  private drawPatch(frame: GifFrame): void {
+    const dims = frame.dims;
+
+    // Resize temp canvas if needed
+    if (!this.tempCanvas || dims.width !== this.tempCanvas.width || dims.height !== this.tempCanvas.height) {
+      this.tempCanvas!.width = dims.width;
+      this.tempCanvas!.height = dims.height;
+    }
+
+    // Create ImageData for the patch
+    const frameImageData = this.tempCtx!.createImageData(dims.width, dims.height);
+
+    // Set the patch data
+    frameImageData.data.set(frame.patch);
+
+    // Put the patch data on the temp canvas
+    this.tempCtx!.putImageData(frameImageData, 0, 0);
+
+    // Draw the temp canvas onto the main canvas at the correct position
+    this.gifCtx!.drawImage(this.tempCanvas!, dims.left, dims.top);
+  }
+
+  /**
+   * Disposes of all resources used by this data source.
+   *
+   * This method stops the animation loop, disposes of the Three.js texture,
+   * clears all canvas references, and resets internal state. It should be
+   * called before loading a new GIF or when the data source is no longer needed.
+   */
+  dispose(): void {
+    // Stop animation
+    if (this.animationId) {
+      cancelAnimationFrame(this.animationId);
+      this.animationId = null;
+    }
+
+    // Dispose of texture
+    if (this.texture) {
+      this.texture.dispose();
+      this.texture = null;
+    }
+
+    // Clear canvas
+    if (this.gifCanvas) {
+      this.gifCanvas = null;
+    }
+
+    // Clear temp canvas
+    if (this.tempCanvas) {
+      this.tempCanvas = null;
+      this.tempCtx = null;
+    }
+
+    // Clear frames
+    this.frames = [];
+    this.currentFrameIndex = 0;
+    this.size = null;
+  }
+}

package/src/lib/components/Stage/components/MapLayer/dataSources/IMapDataSource.ts

@@ -0,0 +1,55 @@
+import type * as THREE from 'three';
+import type { Size } from '../../../types';
+
+/**
+ * Interface for map data sources that provide textures for map layers.
+ *
+ * This interface defines the contract that all map data sources must implement.
+ * It provides a unified way to handle different types of media (images, videos, GIFs)
+ * as textures in a 3D map environment.
+ */
+export interface IMapDataSource {
+  /**
+   * Gets the texture to be displayed on the map plane.
+   *
+   * This can be a static texture, a video texture, or a canvas texture
+   * depending on the implementation. The texture is used to render the
+   * data source on a 3D plane in the scene.
+   *
+   * @returns The texture to be displayed on the map plane, or null if not loaded
+   */
+  getTexture(): THREE.Texture | null;
+
+  /**
+   * Gets the dimensions of the map source.
+   *
+   * Returns the width and height of the data source, which is used
+   * to properly size and position the map layer in the 3D scene.
+   *
+   * @returns The dimensions of the map source, or null if not loaded
+   */
+  getSize(): Size | null;
+
+  /**
+   * Loads the data source from a URL.
+   *
+   * This method handles the loading of different media types (images, videos, GIFs)
+   * from a given URL. The implementation should handle any necessary parsing,
+   * decompression, or setup required for the specific media type.
+   *
+   * @param url - The URL of the data source to load
+   * @returns A promise that resolves when the data source is loaded and ready
+   * @throws Error if the data source cannot be loaded or processed
+   */
+  load(url: string): Promise<void>;
+
+  /**
+   * Cleans up resources used by the data source.
+   *
+   * This method should dispose of any textures, canvases, video elements,
+   * or other resources that were created during the loading process.
+   * It should be called when the data source is no longer needed to
+   * prevent memory leaks.
+   */
+  dispose(): void;
+}

package/src/lib/components/Stage/components/MapLayer/dataSources/ImageDataSource.ts

@@ -0,0 +1,87 @@
+import * as THREE from 'three';
+import type { Size } from '../../../types';
+import type { IMapDataSource } from './IMapDataSource';
+
+/**
+ * Data source for loading static images as textures in a 3D scene.
+ *
+ * This class implements the IMapDataSource interface to provide static image
+ * loading capabilities for map layers. It uses Three.js TextureLoader to load
+ * various image formats and create textures suitable for 3D rendering.
+ */
+export class ImageDataSource implements IMapDataSource {
+  /** The loaded texture from the image file */
+  private texture: THREE.Texture | null = null;
+  /** Dimensions of the loaded image */
+  private size: Size | null = null;
+  /** Three.js texture loader instance for loading images */
+  private loader = new THREE.TextureLoader();
+
+  /**
+   * Gets the Three.js texture containing the loaded image.
+   *
+   * @returns The texture with the loaded image, or null if not loaded
+   */
+  getTexture(): THREE.Texture | null {
+    return this.texture;
+  }
+
+  /**
+   * Gets the dimensions of the loaded image.
+   *
+   * @returns The width and height of the image, or null if not loaded
+   */
+  getSize(): Size | null {
+    return this.size;
+  }
+
+  /**
+   * Loads an image from a URL and creates a texture.
+   *
+   * This method uses Three.js TextureLoader to load various image formats
+   * (JPG, PNG, WebP, etc.) and creates a texture with proper color space
+   * settings for 3D rendering.
+   *
+   * @param url - The URL of the image file to load
+   * @returns A promise that resolves when the image is loaded and ready
+   * @throws Error if the image cannot be loaded or processed
+   */
+  async load(url: string): Promise<void> {
+    // Dispose of previous texture if it exists
+    this.dispose();
+
+    return new Promise((resolve, reject) => {
+      this.loader.load(
+        url,
+        (texture) => {
+          texture.colorSpace = THREE.SRGBColorSpace;
+          this.texture = texture;
+          this.size = {
+            width: texture.image.width,
+            height: texture.image.height
+          };
+          resolve();
+        },
+        undefined,
+        (error) => {
+          console.error('Failed to load image:', error);
+          reject(error);
+        }
+      );
+    });
+  }
+
+  /**
+   * Disposes of the loaded texture and resets internal state.
+   *
+   * This method cleans up the Three.js texture to prevent memory leaks
+   * and resets the size information.
+   */
+  dispose(): void {
+    if (this.texture) {
+      this.texture.dispose();
+      this.texture = null;
+    }
+    this.size = null;
+  }
+}

package/src/lib/components/Stage/components/MapLayer/dataSources/VideoDataSource.ts

@@ -0,0 +1,150 @@
+import * as THREE from 'three';
+import type { Size } from '../../../types';
+import type { IMapDataSource } from './IMapDataSource';
+
+/**
+ * Data source for loading and playing video files as textures in a 3D scene.
+ *
+ * This class implements the IMapDataSource interface to provide video playback
+ * capabilities for map layers. It creates an HTML video element, sets up
+ * proper video attributes for web playback, and creates a Three.js VideoTexture
+ * for real-time video rendering in 3D space.
+ */
+export class VideoDataSource implements IMapDataSource {
+  /** HTML video element used for video playback */
+  private videoElement: HTMLVideoElement | null = null;
+  /** Three.js video texture created from the video element */
+  private texture: THREE.VideoTexture | null = null;
+  /** Dimensions of the video */
+  private size: Size | null = null;
+
+  /**
+   * Gets the Three.js video texture containing the playing video.
+   *
+   * @returns The video texture with the current video frame, or null if not loaded
+   */
+  getTexture(): THREE.Texture | null {
+    return this.texture;
+  }
+
+  /**
+   * Gets the dimensions of the loaded video.
+   *
+   * @returns The width and height of the video, or null if not loaded
+   */
+  getSize(): Size | null {
+    return this.size;
+  }
+
+  /**
+   * Loads a video from a URL and starts playback.
+   *
+   * This method creates an HTML video element with appropriate attributes
+   * for web playback (autoplay, muted, loop, etc.), sets up event listeners
+   * for loading and error handling, and creates a Three.js VideoTexture
+   * for real-time rendering in 3D space.
+   *
+   * @param url - The URL of the video file to load
+   * @returns A promise that resolves when the video is loaded and ready to play
+   * @throws Error if the video cannot be loaded or played
+   */
+  async load(url: string): Promise<void> {
+    // Dispose of previous resources
+    this.dispose();
+
+    return new Promise((resolve, reject) => {
+      // Create video element
+      this.videoElement = document.createElement('video');
+      // Set crossOrigin to 'anonymous' for CORS-enabled servers
+      // This is required for THREE.VideoTexture to work with cross-origin videos
+      this.videoElement.crossOrigin = 'anonymous';
+      this.videoElement.loop = true;
+      this.videoElement.muted = true;
+      this.videoElement.playsInline = true;
+      this.videoElement.autoplay = true;
+      // Preload the video to ensure it's ready
+      this.videoElement.preload = 'auto';
+
+      // Wait for enough data to be loaded before creating texture
+      // 'canplaythrough' ensures the video has enough data buffered
+      const handleCanPlay = () => {
+        if (this.videoElement && this.videoElement.readyState >= 2) {
+          this.size = {
+            width: this.videoElement.videoWidth,
+            height: this.videoElement.videoHeight
+          };
+
+          // Create video texture only when video is ready
+          this.texture = new THREE.VideoTexture(this.videoElement);
+          this.texture.colorSpace = THREE.SRGBColorSpace;
+          // Set texture parameters for better compatibility
+          this.texture.minFilter = THREE.LinearFilter;
+          this.texture.magFilter = THREE.LinearFilter;
+          this.texture.format = THREE.RGBAFormat;
+          // Disable mipmaps to prevent power-of-two issues
+          this.texture.generateMipmaps = false;
+          // Force texture update on every frame for videos
+          this.texture.needsUpdate = true;
+
+          // Start playback
+          this.videoElement.play().catch((e) => {
+            console.warn('Video autoplay failed:', e);
+          });
+
+          resolve();
+        }
+      };
+
+      // Use canplaythrough for Chrome compatibility
+      this.videoElement.addEventListener('canplaythrough', handleCanPlay, { once: true });
+
+      // Fallback: also listen for loadeddata as some browsers may not fire canplaythrough
+      this.videoElement.addEventListener(
+        'loadeddata',
+        () => {
+          // Give it a small delay to ensure the first frame is ready
+          setTimeout(() => {
+            if (!this.texture && this.videoElement && this.videoElement.readyState >= 2) {
+              handleCanPlay();
+            }
+          }, 100);
+        },
+        { once: true }
+      );
+
+      this.videoElement.addEventListener('error', (error) => {
+        console.error('Failed to load video:', error);
+        reject(error);
+      });
+
+      // Set source with cache busting
+      // Force reload by ensuring the URL is unique
+      this.videoElement.src = url;
+      // Force the browser to reload the video
+      this.videoElement.load();
+    });
+  }
+
+  /**
+   * Disposes of the video element and texture, stopping playback.
+   *
+   * This method stops video playback, removes the video source,
+   * disposes of the Three.js texture, and cleans up all references
+   * to prevent memory leaks.
+   */
+  dispose(): void {
+    if (this.videoElement) {
+      this.videoElement.pause();
+      this.videoElement.removeAttribute('src');
+      this.videoElement.load();
+      this.videoElement = null;
+    }
+
+    if (this.texture) {
+      this.texture.dispose();
+      this.texture = null;
+    }
+
+    this.size = null;
+  }
+}

package/src/lib/components/Stage/components/MapLayer/dataSources/dataSourceFactory.ts

@@ -0,0 +1,48 @@
+import { GifDataSource } from './GifDataSource';
+import { ImageDataSource } from './ImageDataSource';
+import type { IMapDataSource } from './IMapDataSource';
+import { VideoDataSource } from './VideoDataSource';
+
+/**
+ * Factory function that creates the appropriate data source based on file extension.
+ *
+ * This function analyzes the URL's file extension to determine which type of
+ * data source to create. It supports various media formats:
+ * - Video formats (mp4, webm, mov, avi) → VideoDataSource
+ * - GIF animations → GifDataSource
+ * - Image formats (jpg, jpeg, png, webp, bmp, tiff) → ImageDataSource
+ * - Unknown formats default to ImageDataSource
+ *
+ * @param url - The URL of the media file to load
+ * @returns An instance of the appropriate data source implementation
+ *
+ * @example
+ * ```typescript
+ * const dataSource = createDataSource('https://example.com/image.jpg');
+ * await dataSource.load('https://example.com/image.jpg');
+ * ```
+ */
+export function createDataSource(url: string): IMapDataSource {
+  const urlWithoutParams = url.split('?')[0];
+  const extension = urlWithoutParams.split('.').pop()?.toLowerCase() || '';
+
+  switch (extension) {
+    case 'mp4':
+    case 'webm':
+    case 'mov':
+    case 'avi':
+      return new VideoDataSource();
+
+    case 'gif':
+      return new GifDataSource();
+
+    case 'jpg':
+    case 'jpeg':
+    case 'png':
+    case 'webp':
+    case 'bmp':
+    case 'tiff':
+    default:
+      return new ImageDataSource();
+  }
+}

package/src/lib/components/Stage/components/MapLayer/dataSources/index.ts

@@ -0,0 +1,16 @@
+/**
+ * Map Layer Data Sources Module
+ *
+ * This module provides a unified interface for loading different types of media
+ * as textures in 3D map layers. It includes implementations for static images,
+ * video files, and animated GIFs, along with a factory function to automatically
+ * select the appropriate data source based on file extension.
+ *
+ * @module MapLayerDataSources
+ */
+
+export { createDataSource } from './dataSourceFactory';
+export { GifDataSource } from './GifDataSource';
+export { ImageDataSource } from './ImageDataSource';
+export type { IMapDataSource } from './IMapDataSource';
+export { VideoDataSource } from './VideoDataSource';

package/src/lib/components/Stage/components/MapLayer/types.ts

@@ -0,0 +1,58 @@
+import * as THREE from 'three';
+
+export enum MapLayerType {
+  None = 0,
+  FogOfWar = 1,
+  Marker = 2,
+  Annotation = 3,
+  Measurement = 4
+}
+
+/**
+ * Props for the Map layer
+ */
+export interface MapLayerProps {
+  /**
+   * The position of the map relative to the scene
+   */
+  offset: {
+    x: number;
+    y: number;
+  };
+
+  /**
+   * Rotation of the map relative to the scene in degrees
+   */
+  rotation: number;
+
+  /**
+   * Url for the map image
+   */
+  url: string;
+
+  /**
+   * Indicates if the map should autoplay (for video assets)
+   * @default true
+   */
+  autoplay?: boolean;
+
+  /**
+   * The scale of the map relative to the scene
+   */
+  zoom: number;
+}
+
+export interface MapLayerExports {
+  getCompositeMapTexture: () => THREE.Texture | null;
+  fit: () => void;
+  fill: () => void;
+  mapSize: { width: number; height: number } | null;
+  fogOfWar: {
+    clear: () => void;
+    reset: () => void;
+    toPng: () => Promise<Blob>;
+    toRLE: () => Promise<Uint8Array>;
+    fromRLE: (rleData: Uint8Array, width: number, height: number) => Promise<void>;
+    isDrawing: () => boolean;
+  };
+}