@talmolab/sleap-io.js 0.1.3 → 0.1.4

package/dist/index.d.ts

@@ -241,10 +241,118 @@ declare class Mp4BoxVideoBackend implements VideoBackend {
     private addToCache;
 }
 
+/**
+ * Streaming HDF5 file access via Web Worker.
+ *
+ * This module provides a high-level API for accessing remote HDF5 files
+ * using HTTP range requests for efficient streaming. The actual HDF5
+ * operations run in a Web Worker where synchronous XHR is allowed.
+ *
+ * @module
+ */
+/**
+ * Options for opening a streaming HDF5 file.
+ */
+interface StreamingH5Options {
+    /** URL to h5wasm IIFE bundle. Defaults to CDN. */
+    h5wasmUrl?: string;
+    /** Filename hint for the HDF5 file. */
+    filenameHint?: string;
+}
+/**
+ * A streaming HDF5 file handle that uses a Web Worker for range request access.
+ *
+ * This class provides an API similar to h5wasm.File but operates via message
+ * passing to a worker where createLazyFile enables HTTP range requests.
+ */
+declare class StreamingH5File {
+    private worker;
+    private messageId;
+    private pendingMessages;
+    private _keys;
+    private _isOpen;
+    constructor();
+    private handleMessage;
+    private handleError;
+    private send;
+    /**
+     * Initialize the h5wasm module in the worker.
+     */
+    init(options?: StreamingH5Options): Promise<void>;
+    /**
+     * Open a remote HDF5 file for streaming access.
+     *
+     * @param url - URL to the HDF5 file (must support HTTP range requests)
+     * @param options - Optional settings
+     */
+    open(url: string, options?: StreamingH5Options): Promise<void>;
+    /**
+     * Whether a file is currently open.
+     */
+    get isOpen(): boolean;
+    /**
+     * Get the root-level keys in the file.
+     */
+    keys(): string[];
+    /**
+     * Get the keys (children) at a given path.
+     */
+    getKeys(path: string): Promise<string[]>;
+    /**
+     * Get an attribute value.
+     */
+    getAttr(path: string, name: string): Promise<unknown>;
+    /**
+     * Get all attributes at a path.
+     */
+    getAttrs(path: string): Promise<Record<string, unknown>>;
+    /**
+     * Get dataset metadata (shape, dtype) without reading values.
+     */
+    getDatasetMeta(path: string): Promise<{
+        shape: number[];
+        dtype: string;
+    }>;
+    /**
+     * Read a dataset's value.
+     *
+     * @param path - Path to the dataset
+     * @param slice - Optional slice specification (array of [start, end] pairs)
+     */
+    getDatasetValue(path: string, slice?: Array<[number, number] | []>): Promise<{
+        value: unknown;
+        shape: number[];
+        dtype: string;
+    }>;
+    /**
+     * Close the file and terminate the worker.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Check if streaming via Web Worker is supported in the current environment.
+ */
+declare function isStreamingSupported(): boolean;
+/**
+ * Open a remote HDF5 file with streaming support.
+ *
+ * @param url - URL to the HDF5 file
+ * @param options - Optional settings
+ * @returns A StreamingH5File instance
+ */
+declare function openStreamingH5(url: string, options?: StreamingH5Options): Promise<StreamingH5File>;
+
 type SlpSource = string | ArrayBuffer | Uint8Array | File | FileSystemFileHandle;
 type StreamMode = "auto" | "range" | "download";
 type OpenH5Options = {
+    /**
+     * Streaming mode for remote files:
+     * - "auto": Try range requests, fall back to download
+     * - "range": Use HTTP range requests (requires Worker support in browser)
+     * - "download": Always download the entire file
+     */
     stream?: StreamMode;
+    /** Filename hint for the HDF5 file */
     filenameHint?: string;
 };
 
@@ -550,4 +658,4 @@ declare function checkFfmpeg(): Promise<boolean>;
  */
 declare function renderVideo(source: Labels | LabeledFrame[], outputPath: string, options?: VideoOptions): Promise<void>;
 
-export { Camera, CameraGroup, type ColorScheme, type ColorSpec, FrameGroup, Instance, InstanceContext, InstanceGroup, LabeledFrame, Labels, type LabelsDict, LabelsSet, MARKER_FUNCTIONS, type MarkerShape, Mp4BoxVideoBackend, NAMED_COLORS, PALETTES, type PaletteName, PredictedInstance, type RGB, type RGBA, RecordingSession, RenderContext, type RenderOptions, Skeleton, SuggestionFrame, Track, Video, type VideoBackend, type VideoFrame, type VideoOptions, checkFfmpeg, decodeYamlSkeleton, determineColorScheme, drawCircle, drawCross, drawDiamond, drawSquare, drawTriangle, encodeYamlSkeleton, fromDict, fromNumpy, getMarkerFunction, getPalette, labelsFromNumpy, loadSlp, loadVideo, makeCameraFromDict, renderImage, renderVideo, resolveColor, rgbToCSS, rodriguesTransformation, saveImage, saveSlp, toDataURL, toDict, toJPEG, toNumpy, toPNG };
+export { Camera, CameraGroup, type ColorScheme, type ColorSpec, FrameGroup, Instance, InstanceContext, InstanceGroup, LabeledFrame, Labels, type LabelsDict, LabelsSet, MARKER_FUNCTIONS, type MarkerShape, Mp4BoxVideoBackend, NAMED_COLORS, PALETTES, type PaletteName, PredictedInstance, type RGB, type RGBA, RecordingSession, RenderContext, type RenderOptions, Skeleton, StreamingH5File, SuggestionFrame, Track, Video, type VideoBackend, type VideoFrame, type VideoOptions, checkFfmpeg, decodeYamlSkeleton, determineColorScheme, drawCircle, drawCross, drawDiamond, drawSquare, drawTriangle, encodeYamlSkeleton, fromDict, fromNumpy, getMarkerFunction, getPalette, isStreamingSupported, labelsFromNumpy, loadSlp, loadVideo, makeCameraFromDict, openStreamingH5, renderImage, renderVideo, resolveColor, rgbToCSS, rodriguesTransformation, saveImage, saveSlp, toDataURL, toDict, toJPEG, toNumpy, toPNG };

package/dist/index.js

@@ -1203,6 +1203,383 @@ var Mp4BoxVideoBackend = class {
   }
 };
 
+// src/codecs/slp/h5-worker.ts
+var H5_WORKER_CODE = `
+// h5wasm streaming worker
+// Uses createLazyFile for HTTP range request streaming
+
+let h5wasmModule = null;
+let FS = null;
+let currentFile = null;
+let mountPath = null;
+
+self.onmessage = async function(e) {
+  const { type, payload, id } = e.data;
+
+  try {
+    switch (type) {
+      case 'init':
+        await initH5Wasm(payload?.h5wasmUrl);
+        respond(id, { success: true });
+        break;
+
+      case 'openUrl':
+        const result = await openRemoteFile(payload.url, payload.filename);
+        respond(id, result);
+        break;
+
+      case 'getKeys':
+        const keys = getKeys(payload.path);
+        respond(id, { success: true, keys });
+        break;
+
+      case 'getAttr':
+        const attr = getAttr(payload.path, payload.name);
+        respond(id, { success: true, value: attr });
+        break;
+
+      case 'getAttrs':
+        const attrs = getAttrs(payload.path);
+        respond(id, { success: true, attrs });
+        break;
+
+      case 'getDatasetMeta':
+        const meta = getDatasetMeta(payload.path);
+        respond(id, { success: true, meta });
+        break;
+
+      case 'getDatasetValue':
+        const data = getDatasetValue(payload.path, payload.slice);
+        respond(id, { success: true, data }, data.transferables);
+        break;
+
+      case 'close':
+        closeFile();
+        respond(id, { success: true });
+        break;
+
+      default:
+        respond(id, { success: false, error: 'Unknown message type: ' + type });
+    }
+  } catch (error) {
+    respond(id, { success: false, error: error.message || String(error) });
+  }
+};
+
+function respond(id, data, transferables) {
+  if (transferables) {
+    self.postMessage({ id, ...data }, transferables);
+  } else {
+    self.postMessage({ id, ...data });
+  }
+}
+
+async function initH5Wasm(h5wasmUrl) {
+  if (h5wasmModule) return;
+
+  // Default to CDN if no URL provided
+  const url = h5wasmUrl || 'https://cdn.jsdelivr.net/npm/h5wasm@0.8.8/dist/iife/h5wasm.js';
+
+  // Import h5wasm IIFE
+  importScripts(url);
+
+  // Wait for module to be ready
+  const Module = await h5wasm.ready;
+  h5wasmModule = h5wasm;
+  FS = Module.FS;
+}
+
+async function openRemoteFile(url, filename = 'data.h5') {
+  if (!h5wasmModule) {
+    throw new Error('h5wasm not initialized');
+  }
+
+  // Close any existing file
+  closeFile();
+
+  // Create mount point
+  mountPath = '/remote-' + Date.now();
+  FS.mkdir(mountPath);
+
+  // Create lazy file - this enables range request streaming!
+  FS.createLazyFile(mountPath, filename, url, true, false);
+
+  // Open with h5wasm
+  const filePath = mountPath + '/' + filename;
+  currentFile = new h5wasm.File(filePath, 'r');
+
+  return {
+    success: true,
+    path: currentFile.path,
+    filename: currentFile.filename,
+    keys: currentFile.keys()
+  };
+}
+
+function getKeys(path) {
+  if (!currentFile) throw new Error('No file open');
+  const item = path === '/' || !path ? currentFile : currentFile.get(path);
+  if (!item) throw new Error('Path not found: ' + path);
+  return item.keys ? item.keys() : [];
+}
+
+function getAttr(path, name) {
+  if (!currentFile) throw new Error('No file open');
+  const item = path === '/' || !path ? currentFile : currentFile.get(path);
+  if (!item) throw new Error('Path not found: ' + path);
+  const attrs = item.attrs;
+  return attrs?.[name] || null;
+}
+
+function getAttrs(path) {
+  if (!currentFile) throw new Error('No file open');
+  const item = path === '/' || !path ? currentFile : currentFile.get(path);
+  if (!item) throw new Error('Path not found: ' + path);
+  return item.attrs || {};
+}
+
+function getDatasetMeta(path) {
+  if (!currentFile) throw new Error('No file open');
+  const dataset = currentFile.get(path);
+  if (!dataset) throw new Error('Dataset not found: ' + path);
+  return {
+    shape: dataset.shape,
+    dtype: dataset.dtype,
+    metadata: dataset.metadata
+  };
+}
+
+function getDatasetValue(path, slice) {
+  if (!currentFile) throw new Error('No file open');
+  const dataset = currentFile.get(path);
+  if (!dataset) throw new Error('Dataset not found: ' + path);
+
+  // Get value or slice
+  let value;
+  if (slice && Array.isArray(slice)) {
+    value = dataset.slice(slice);
+  } else {
+    value = dataset.value;
+  }
+
+  // Prepare for transfer
+  const transferables = [];
+  let transferValue = value;
+
+  if (ArrayBuffer.isView(value)) {
+    // TypedArray - transfer the underlying buffer
+    transferValue = {
+      type: 'typedarray',
+      dtype: value.constructor.name,
+      buffer: value.buffer,
+      byteOffset: value.byteOffset,
+      length: value.length
+    };
+    transferables.push(value.buffer);
+  } else if (value instanceof ArrayBuffer) {
+    transferValue = { type: 'arraybuffer', buffer: value };
+    transferables.push(value);
+  }
+
+  return {
+    value: transferValue,
+    shape: dataset.shape,
+    dtype: dataset.dtype,
+    transferables
+  };
+}
+
+function closeFile() {
+  if (currentFile) {
+    try { currentFile.close(); } catch (e) {}
+    currentFile = null;
+  }
+  if (mountPath && FS) {
+    try { FS.rmdir(mountPath); } catch (e) {}
+    mountPath = null;
+  }
+}
+`;
+function createH5Worker() {
+  const blob = new Blob([H5_WORKER_CODE], { type: "application/javascript" });
+  const url = URL.createObjectURL(blob);
+  const worker = new Worker(url);
+  worker.addEventListener(
+    "error",
+    () => {
+      URL.revokeObjectURL(url);
+    },
+    { once: true }
+  );
+  return worker;
+}
+
+// src/codecs/slp/h5-streaming.ts
+function reconstructValue(data) {
+  if (data && typeof data === "object" && "type" in data) {
+    const typed = data;
+    if (typed.type === "typedarray" && typed.buffer) {
+      const TypedArrayConstructor = getTypedArrayConstructor(typed.dtype || "Uint8Array");
+      return new TypedArrayConstructor(typed.buffer, typed.byteOffset || 0, typed.length);
+    }
+    if (typed.type === "arraybuffer" && typed.buffer) {
+      return typed.buffer;
+    }
+  }
+  return data;
+}
+function getTypedArrayConstructor(name) {
+  const constructors = {
+    Int8Array,
+    Uint8Array,
+    Uint8ClampedArray,
+    Int16Array,
+    Uint16Array,
+    Int32Array,
+    Uint32Array,
+    Float32Array,
+    Float64Array,
+    BigInt64Array,
+    BigUint64Array
+  };
+  return constructors[name] || Uint8Array;
+}
+var StreamingH5File = class {
+  worker;
+  messageId = 0;
+  pendingMessages = /* @__PURE__ */ new Map();
+  _keys = [];
+  _isOpen = false;
+  constructor() {
+    this.worker = createH5Worker();
+    this.worker.onmessage = this.handleMessage.bind(this);
+    this.worker.onerror = this.handleError.bind(this);
+  }
+  handleMessage(e) {
+    const { id, ...data } = e.data;
+    const pending = this.pendingMessages.get(id);
+    if (pending) {
+      this.pendingMessages.delete(id);
+      if (data.success) {
+        pending.resolve(e.data);
+      } else {
+        pending.reject(new Error(data.error || "Worker operation failed"));
+      }
+    }
+  }
+  handleError(e) {
+    console.error("[StreamingH5File] Worker error:", e.message);
+    for (const [id, pending] of this.pendingMessages) {
+      pending.reject(new Error(`Worker error: ${e.message}`));
+      this.pendingMessages.delete(id);
+    }
+  }
+  send(type, payload) {
+    return new Promise((resolve, reject) => {
+      const id = ++this.messageId;
+      this.pendingMessages.set(id, { resolve, reject });
+      this.worker.postMessage({ type, payload, id });
+    });
+  }
+  /**
+   * Initialize the h5wasm module in the worker.
+   */
+  async init(options) {
+    await this.send("init", { h5wasmUrl: options?.h5wasmUrl });
+  }
+  /**
+   * Open a remote HDF5 file for streaming access.
+   *
+   * @param url - URL to the HDF5 file (must support HTTP range requests)
+   * @param options - Optional settings
+   */
+  async open(url, options) {
+    await this.init(options);
+    const filename = options?.filenameHint || url.split("/").pop()?.split("?")[0] || "data.h5";
+    const result = await this.send("openUrl", { url, filename });
+    this._keys = result.keys || [];
+    this._isOpen = true;
+  }
+  /**
+   * Whether a file is currently open.
+   */
+  get isOpen() {
+    return this._isOpen;
+  }
+  /**
+   * Get the root-level keys in the file.
+   */
+  keys() {
+    return this._keys;
+  }
+  /**
+   * Get the keys (children) at a given path.
+   */
+  async getKeys(path) {
+    const result = await this.send("getKeys", { path });
+    return result.keys || [];
+  }
+  /**
+   * Get an attribute value.
+   */
+  async getAttr(path, name) {
+    const result = await this.send("getAttr", { path, name });
+    return result.value?.value ?? result.value;
+  }
+  /**
+   * Get all attributes at a path.
+   */
+  async getAttrs(path) {
+    const result = await this.send("getAttrs", { path });
+    return result.attrs || {};
+  }
+  /**
+   * Get dataset metadata (shape, dtype) without reading values.
+   */
+  async getDatasetMeta(path) {
+    const result = await this.send("getDatasetMeta", { path });
+    const meta = result.meta;
+    return meta;
+  }
+  /**
+   * Read a dataset's value.
+   *
+   * @param path - Path to the dataset
+   * @param slice - Optional slice specification (array of [start, end] pairs)
+   */
+  async getDatasetValue(path, slice) {
+    const result = await this.send("getDatasetValue", { path, slice });
+    const data = result.data;
+    return {
+      value: reconstructValue(data.value),
+      shape: data.shape,
+      dtype: data.dtype
+    };
+  }
+  /**
+   * Close the file and terminate the worker.
+   */
+  async close() {
+    if (this._isOpen) {
+      await this.send("close");
+      this._isOpen = false;
+    }
+    this.worker.terminate();
+    this._keys = [];
+  }
+};
+function isStreamingSupported() {
+  return typeof Worker !== "undefined" && typeof Blob !== "undefined" && typeof URL !== "undefined";
+}
+async function openStreamingH5(url, options) {
+  if (!isStreamingSupported()) {
+    throw new Error("Streaming HDF5 requires Web Worker support");
+  }
+  const file = new StreamingH5File();
+  await file.open(url, options);
+  return file;
+}
+
 // src/codecs/slp/h5.ts
 var isNode = typeof process !== "undefined" && !!process.versions?.node;
 var modulePromise = null;
@@ -3017,6 +3394,7 @@ export {
   RecordingSession,
   RenderContext,
   Skeleton,
+  StreamingH5File,
   SuggestionFrame,
   Symmetry,
   Track,
@@ -3034,10 +3412,12 @@ export {
   fromNumpy,
   getMarkerFunction,
   getPalette,
+  isStreamingSupported,
   labelsFromNumpy,
   loadSlp,
   loadVideo,
   makeCameraFromDict,
+  openStreamingH5,
   pointsEmpty,
   pointsFromArray,
   pointsFromDict,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@talmolab/sleap-io.js",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "exports": {