@talmolab/sleap-io.js 0.1.3 → 0.1.5

package/dist/{chunk-CDU5QGU6.js → chunk-23DE7GPK.js}

@@ -364,6 +364,9 @@ function parseJsonAttr(attr) {
   if (value && typeof value === "object" && "buffer" in value) {
     return JSON.parse(textDecoder.decode(new Uint8Array(value.buffer)));
   }
+  if (value && typeof value === "object") {
+    return value;
+  }
   return JSON.parse(String(value));
 }
 function trimHdf5String(str) {

package/dist/index.d.ts

@@ -241,13 +241,147 @@ 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;
 };
 
+/**
+ * Load an SLP file.
+ *
+ * When loading from a URL in a browser with `h5.stream` set to 'range' or 'auto',
+ * this function automatically uses HTTP range requests for efficient streaming.
+ * Only the annotation data needed is downloaded, not the entire file.
+ *
+ * @param source - Path, URL, ArrayBuffer, File, or FileSystemFileHandle
+ * @param options - Loading options
+ * @param options.openVideos - Whether to open video backends (default: true, but false for streaming)
+ * @param options.h5 - HDF5 options including streaming mode
+ * @param options.h5.stream - 'auto' | 'range' | 'download' (default: 'auto')
+ *
+ * @example
+ * ```typescript
+ * // Load from URL with streaming (uses range requests automatically)
+ * const labels = await loadSlp('https://example.com/labels.slp', {
+ *   h5: { stream: 'range' }
+ * });
+ *
+ * // Force full download
+ * const labels = await loadSlp('https://example.com/labels.slp', {
+ *   h5: { stream: 'download' }
+ * });
+ * ```
+ */
 declare function loadSlp(source: SlpSource, options?: {
     openVideos?: boolean;
     h5?: OpenH5Options;
@@ -550,4 +684,41 @@ 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 };
+/**
+ * Streaming SLP file reader using HTTP range requests.
+ *
+ * This module provides a streaming alternative to `readSlp` that uses
+ * `StreamingH5File` for efficient range request-based file access.
+ * Only the data actually needed is downloaded, rather than the entire file.
+ *
+ * @module
+ */
+
+/**
+ * Options for streaming SLP file loading.
+ */
+interface StreamingSlpOptions {
+    /** URL hint for h5wasm CDN */
+    h5wasmUrl?: string;
+    /** Filename hint for the HDF5 file */
+    filenameHint?: string;
+}
+/**
+ * Read an SLP file using HTTP range requests for efficient streaming.
+ *
+ * This function downloads only the data needed (metadata, frames, instances, points)
+ * rather than the entire file. Embedded videos are NOT loaded - only metadata.
+ *
+ * @param url - URL to the SLP file (must support HTTP range requests)
+ * @param options - Optional settings
+ * @returns Labels object with all annotation data
+ *
+ * @example
+ * ```typescript
+ * const labels = await readSlpStreaming('https://example.com/labels.slp');
+ * console.log(`Loaded ${labels.labeledFrames.length} frames`);
+ * ```
+ */
+declare function readSlpStreaming(url: string, options?: StreamingSlpOptions): Promise<Labels>;
+
+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, readSlpStreaming, renderImage, renderVideo, resolveColor, rgbToCSS, rodriguesTransformation, saveImage, saveSlp, toDataURL, toDict, toJPEG, toNumpy, toPNG };

package/dist/index.js

@@ -8,13 +8,16 @@ import {
   Track,
   parseJsonAttr,
   parseSkeletons,
+  parseSuggestions,
+  parseTracks,
+  parseVideosMetadata,
   pointsEmpty,
   pointsFromArray,
   pointsFromDict,
   predictedPointsEmpty,
   predictedPointsFromArray,
   predictedPointsFromDict
-} from "./chunk-CDU5QGU6.js";
+} from "./chunk-23DE7GPK.js";
 
 // src/model/labeled-frame.ts
 var LabeledFrame = class {
@@ -1203,6 +1206,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;
@@ -1846,6 +2226,302 @@ function slicePoints(data, start, end, predicted = false) {
   return points;
 }
 
+// src/codecs/slp/read-streaming.ts
+async function readSlpStreaming(url, options) {
+  if (!isStreamingSupported()) {
+    throw new Error("Streaming HDF5 requires Web Worker support (browser environment)");
+  }
+  const file = await openStreamingH5(url, {
+    h5wasmUrl: options?.h5wasmUrl,
+    filenameHint: options?.filenameHint
+  });
+  try {
+    return await readFromStreamingFile(file, url, options?.filenameHint);
+  } finally {
+    await file.close();
+  }
+}
+async function readFromStreamingFile(file, url, filenameHint) {
+  const metadataAttrs = await file.getAttrs("metadata");
+  const formatId = Number(
+    metadataAttrs["format_id"]?.value ?? metadataAttrs["format_id"] ?? 1
+  );
+  const metadataJson = parseJsonAttr(metadataAttrs["json"]);
+  const labelsPath = filenameHint ?? url.split("/").pop()?.split("?")[0] ?? "slp-data.slp";
+  const skeletons = parseSkeletons(metadataJson);
+  const tracks = await readTracksStreaming(file);
+  const videos = await readVideosStreaming(file, labelsPath);
+  const suggestions = await readSuggestionsStreaming(file, videos);
+  const framesData = await readStructDatasetStreaming(file, "frames");
+  const instancesData = await readStructDatasetStreaming(file, "instances");
+  const pointsData = await readStructDatasetStreaming(file, "points");
+  const predPointsData = await readStructDatasetStreaming(file, "pred_points");
+  const labeledFrames = buildLabeledFrames2({
+    framesData,
+    instancesData,
+    pointsData,
+    predPointsData,
+    skeletons,
+    tracks,
+    videos,
+    formatId
+  });
+  return new Labels({
+    labeledFrames,
+    videos,
+    skeletons,
+    tracks,
+    suggestions,
+    sessions: [],
+    // Sessions require complex parsing, skip for now
+    provenance: metadataJson?.provenance ?? {}
+  });
+}
+async function readTracksStreaming(file) {
+  try {
+    const keys = file.keys();
+    if (!keys.includes("tracks_json")) return [];
+    const data = await file.getDatasetValue("tracks_json");
+    const values = normalizeDatasetArray(data.value);
+    return parseTracks(values);
+  } catch {
+    return [];
+  }
+}
+async function readVideosStreaming(file, labelsPath) {
+  try {
+    const keys = file.keys();
+    if (!keys.includes("videos_json")) return [];
+    const data = await file.getDatasetValue("videos_json");
+    const values = normalizeDatasetArray(data.value);
+    const metadataList = parseVideosMetadata(values, labelsPath);
+    return metadataList.map((meta) => new Video({
+      filename: meta.filename,
+      backend: null,
+      // No backend in streaming mode
+      backendMetadata: {
+        dataset: meta.dataset,
+        format: meta.format,
+        shape: meta.frameCount && meta.height && meta.width && meta.channels ? [meta.frameCount, meta.height, meta.width, meta.channels] : void 0,
+        fps: meta.fps,
+        channel_order: meta.channelOrder
+      },
+      sourceVideo: meta.sourceVideo ? new Video({ filename: meta.sourceVideo.filename }) : null,
+      openBackend: false
+    }));
+  } catch {
+    return [];
+  }
+}
+async function readSuggestionsStreaming(file, videos) {
+  try {
+    const keys = file.keys();
+    if (!keys.includes("suggestions_json")) return [];
+    const data = await file.getDatasetValue("suggestions_json");
+    const values = normalizeDatasetArray(data.value);
+    const metadataList = parseSuggestions(values);
+    return metadataList.map((meta) => {
+      const video = videos[meta.video];
+      if (!video) return null;
+      return new SuggestionFrame({
+        video,
+        frameIdx: meta.frameIdx,
+        metadata: meta.metadata
+      });
+    }).filter((s) => s !== null);
+  } catch {
+    return [];
+  }
+}
+async function readStructDatasetStreaming(file, path) {
+  try {
+    const keys = file.keys();
+    if (!keys.includes(path)) return {};
+    const meta = await file.getDatasetMeta(path);
+    const data = await file.getDatasetValue(path);
+    const fieldNames = getFieldNamesFromMeta(meta);
+    return normalizeStructData(data.value, data.shape, fieldNames);
+  } catch {
+    return {};
+  }
+}
+function getFieldNamesFromMeta(meta) {
+  const dtype = meta.dtype;
+  if (typeof dtype === "string") {
+    const namesMatch = dtype.match(/'names':\s*\[([^\]]+)\]/);
+    if (namesMatch) {
+      const namesStr = namesMatch[1];
+      const names = namesStr.match(/'([^']+)'/g);
+      if (names) {
+        return names.map((n) => n.replace(/'/g, ""));
+      }
+    }
+  }
+  if (typeof dtype === "object" && dtype !== null) {
+    const dtypeObj = dtype;
+    if (dtypeObj.compound_type && typeof dtypeObj.compound_type === "object") {
+      const compound = dtypeObj.compound_type;
+      if (compound.members) {
+        return compound.members.map((m) => m.name).filter((n) => !!n);
+      }
+    }
+  }
+  return [];
+}
+function normalizeStructData(value, shape, fieldNames) {
+  if (!value) return {};
+  if (value && typeof value === "object" && !Array.isArray(value) && !ArrayBuffer.isView(value)) {
+    const obj = value;
+    const firstKey = Object.keys(obj)[0];
+    if (firstKey && Array.isArray(obj[firstKey])) {
+      return obj;
+    }
+  }
+  if (ArrayBuffer.isView(value) && shape.length === 2) {
+    const [rowCount, colCount] = shape;
+    const arr = value;
+    if (fieldNames.length === colCount) {
+      const result = {};
+      for (let col = 0; col < colCount; col++) {
+        const colData = [];
+        for (let row = 0; row < rowCount; row++) {
+          colData.push(arr[row * colCount + col]);
+        }
+        result[fieldNames[col]] = colData;
+      }
+      return result;
+    }
+  }
+  if (Array.isArray(value) && value.length > 0 && Array.isArray(value[0])) {
+    const rows = value;
+    if (fieldNames.length) {
+      const result = {};
+      fieldNames.forEach((field, colIdx) => {
+        result[field] = rows.map((row) => row[colIdx]);
+      });
+      return result;
+    }
+  }
+  return {};
+}
+function normalizeDatasetArray(value) {
+  if (Array.isArray(value)) return value;
+  if (ArrayBuffer.isView(value)) {
+    return Array.from(value);
+  }
+  return [];
+}
+function buildLabeledFrames2(options) {
+  const frames = [];
+  const { framesData, instancesData, pointsData, predPointsData, skeletons, tracks, videos, formatId } = options;
+  const frameIds = framesData.frame_id ?? [];
+  const videoIdToIndex = buildVideoIdMap2(framesData, videos);
+  const instanceById = /* @__PURE__ */ new Map();
+  const fromPredictedPairs = [];
+  for (let frameIdx = 0; frameIdx < frameIds.length; frameIdx += 1) {
+    const rawVideoId = Number(framesData.video?.[frameIdx] ?? 0);
+    const videoIndex = videoIdToIndex.get(rawVideoId) ?? rawVideoId;
+    const frameIndex = Number(framesData.frame_idx?.[frameIdx] ?? 0);
+    const instStart = Number(framesData.instance_id_start?.[frameIdx] ?? 0);
+    const instEnd = Number(framesData.instance_id_end?.[frameIdx] ?? 0);
+    const video = videos[videoIndex];
+    if (!video) continue;
+    const instances = [];
+    for (let instIdx = instStart; instIdx < instEnd; instIdx += 1) {
+      const instanceType = Number(instancesData.instance_type?.[instIdx] ?? 0);
+      const skeletonId = Number(instancesData.skeleton?.[instIdx] ?? 0);
+      const trackId = Number(instancesData.track?.[instIdx] ?? -1);
+      const pointStart = Number(instancesData.point_id_start?.[instIdx] ?? 0);
+      const pointEnd = Number(instancesData.point_id_end?.[instIdx] ?? 0);
+      const score = Number(instancesData.score?.[instIdx] ?? 0);
+      const trackingScore = Number(instancesData.tracking_score?.[instIdx] ?? 0);
+      const fromPredicted = Number(instancesData.from_predicted?.[instIdx] ?? -1);
+      const skeleton = skeletons[skeletonId] ?? skeletons[0] ?? new Skeleton({ nodes: [] });
+      const track = trackId >= 0 ? tracks[trackId] : null;
+      let instance;
+      if (instanceType === 0) {
+        const points = slicePoints2(pointsData, pointStart, pointEnd);
+        instance = new Instance({ points: pointsFromArray(points, skeleton.nodeNames), skeleton, track, trackingScore });
+        if (formatId < 1.1) {
+          instance.points.forEach((point) => {
+            point.xy = [point.xy[0] - 0.5, point.xy[1] - 0.5];
+          });
+        }
+        if (fromPredicted >= 0) {
+          fromPredictedPairs.push([instIdx, fromPredicted]);
+        }
+      } else {
+        const points = slicePoints2(predPointsData, pointStart, pointEnd, true);
+        instance = new PredictedInstance({ points: predictedPointsFromArray(points, skeleton.nodeNames), skeleton, track, score, trackingScore });
+        if (formatId < 1.1) {
+          instance.points.forEach((point) => {
+            point.xy = [point.xy[0] - 0.5, point.xy[1] - 0.5];
+          });
+        }
+      }
+      instanceById.set(instIdx, instance);
+      instances.push(instance);
+    }
+    frames.push(new LabeledFrame({ video, frameIdx: frameIndex, instances }));
+  }
+  for (const [instanceId, fromPredictedId] of fromPredictedPairs) {
+    const instance = instanceById.get(instanceId);
+    const predicted = instanceById.get(fromPredictedId);
+    if (instance && predicted instanceof PredictedInstance && instance instanceof Instance) {
+      instance.fromPredicted = predicted;
+    }
+  }
+  return frames;
+}
+function buildVideoIdMap2(framesData, videos) {
+  const videoIds = /* @__PURE__ */ new Set();
+  for (const value of framesData.video ?? []) {
+    videoIds.add(Number(value));
+  }
+  if (!videoIds.size) return /* @__PURE__ */ new Map();
+  const maxId = Math.max(...Array.from(videoIds));
+  if (videoIds.size === videos.length && maxId === videos.length - 1) {
+    const identity = /* @__PURE__ */ new Map();
+    for (let i = 0; i < videos.length; i += 1) {
+      identity.set(i, i);
+    }
+    return identity;
+  }
+  const map = /* @__PURE__ */ new Map();
+  for (let index = 0; index < videos.length; index += 1) {
+    const video = videos[index];
+    const dataset = video.backendMetadata?.dataset ?? "";
+    const parsedId = parseVideoIdFromDataset2(dataset);
+    if (parsedId != null) {
+      map.set(parsedId, index);
+    }
+  }
+  return map;
+}
+function parseVideoIdFromDataset2(dataset) {
+  if (!dataset) return null;
+  const group = dataset.split("/")[0];
+  if (!group.startsWith("video")) return null;
+  const id = Number(group.slice(5));
+  return Number.isNaN(id) ? null : id;
+}
+function slicePoints2(data, start, end, predicted = false) {
+  const xs = data.x ?? [];
+  const ys = data.y ?? [];
+  const visible = data.visible ?? [];
+  const complete = data.complete ?? [];
+  const scores = data.score ?? [];
+  const points = [];
+  for (let i = start; i < end; i += 1) {
+    if (predicted) {
+      points.push([xs[i], ys[i], scores[i], visible[i], complete[i]]);
+    } else {
+      points.push([xs[i], ys[i], visible[i], complete[i]]);
+    }
+  }
+  return points;
+}
+
 // src/codecs/slp/write.ts
 var isNode2 = typeof process !== "undefined" && !!process.versions?.node;
 var FORMAT_ID = 1.4;
@@ -2148,7 +2824,27 @@ function createMatrixDataset(file, name, rows, fieldNames, dtype) {
 }
 
 // src/io/main.ts
+function isProbablyUrl2(source) {
+  return typeof source === "string" && /^https?:\/\//i.test(source);
+}
+function isBrowser4() {
+  return typeof window !== "undefined" && typeof Worker !== "undefined";
+}
 async function loadSlp(source, options) {
+  const streamMode = options?.h5?.stream ?? "auto";
+  if (isProbablyUrl2(source) && isBrowser4() && isStreamingSupported() && (streamMode === "range" || streamMode === "auto")) {
+    try {
+      return await readSlpStreaming(source, {
+        filenameHint: options?.h5?.filenameHint
+      });
+    } catch (e) {
+      if (streamMode === "auto") {
+        console.warn("Streaming failed, falling back to full download:", e);
+      } else {
+        throw e;
+      }
+    }
+  }
   return readSlp(source, { openVideos: options?.openVideos ?? true, h5: options?.h5 });
 }
 async function saveSlp(labels, filename, options) {
@@ -3017,6 +3713,7 @@ export {
   RecordingSession,
   RenderContext,
   Skeleton,
+  StreamingH5File,
   SuggestionFrame,
   Symmetry,
   Track,
@@ -3034,16 +3731,19 @@ export {
   fromNumpy,
   getMarkerFunction,
   getPalette,
+  isStreamingSupported,
   labelsFromNumpy,
   loadSlp,
   loadVideo,
   makeCameraFromDict,
+  openStreamingH5,
   pointsEmpty,
   pointsFromArray,
   pointsFromDict,
   predictedPointsEmpty,
   predictedPointsFromArray,
   predictedPointsFromDict,
+  readSlpStreaming,
   renderImage,
   renderVideo,
   resolveColor,

package/dist/lite.js

@@ -10,7 +10,7 @@ import {
   parseSuggestions,
   parseTracks,
   parseVideosMetadata
-} from "./chunk-CDU5QGU6.js";
+} from "./chunk-23DE7GPK.js";
 
 // src/codecs/slp/jsfive.ts
 import * as hdf5 from "jsfive";

package/package.json

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