@talmolab/sleap-io.js 0.1.2 → 0.1.3

package/dist/instance-D_5PPN1y.d.ts

@@ -0,0 +1,126 @@
+declare class Node {
+    name: string;
+    constructor(name: string);
+}
+declare class Edge {
+    source: Node;
+    destination: Node;
+    constructor(source: Node, destination: Node);
+    at(index: number): Node;
+}
+declare class Symmetry {
+    nodes: Set<Node>;
+    constructor(nodes: Iterable<Node>);
+    at(index: number): Node;
+}
+type NodeOrIndex = Node | string | number;
+declare class Skeleton {
+    nodes: Node[];
+    edges: Edge[];
+    symmetries: Symmetry[];
+    name?: string;
+    private nameToNode;
+    private nodeToIndex;
+    constructor(options: {
+        nodes: Array<Node | string>;
+        edges?: Array<Edge | [NodeOrIndex, NodeOrIndex]>;
+        symmetries?: Array<Symmetry | [NodeOrIndex, NodeOrIndex]>;
+        name?: string;
+    } | Array<Node | string>);
+    rebuildCache(nodes?: Node[]): void;
+    get nodeNames(): string[];
+    index(node: NodeOrIndex): number;
+    node(node: NodeOrIndex): Node;
+    get edgeIndices(): Array<[number, number]>;
+    get symmetryNames(): Array<[string, string]>;
+    matches(other: Skeleton): boolean;
+    addEdge(source: NodeOrIndex, destination: NodeOrIndex): void;
+    addSymmetry(left: NodeOrIndex, right: NodeOrIndex): void;
+    private edgeFrom;
+    private symmetryFrom;
+}
+
+declare class Track {
+    name: string;
+    constructor(name: string);
+}
+type Point = {
+    xy: [number, number];
+    visible: boolean;
+    complete: boolean;
+    name?: string;
+};
+type PredictedPoint = Point & {
+    score: number;
+};
+type PointsArray = Point[];
+type PredictedPointsArray = PredictedPoint[];
+declare function pointsEmpty(length: number, names?: string[]): PointsArray;
+declare function predictedPointsEmpty(length: number, names?: string[]): PredictedPointsArray;
+declare function pointsFromArray(array: number[][], names?: string[]): PointsArray;
+declare function predictedPointsFromArray(array: number[][], names?: string[]): PredictedPointsArray;
+declare class Instance {
+    points: PointsArray;
+    skeleton: Skeleton;
+    track?: Track | null;
+    fromPredicted?: PredictedInstance | null;
+    trackingScore: number;
+    constructor(options: {
+        points: PointsArray | Record<string, number[]>;
+        skeleton: Skeleton;
+        track?: Track | null;
+        fromPredicted?: PredictedInstance | null;
+        trackingScore?: number;
+    });
+    static fromArray(points: number[][], skeleton: Skeleton): Instance;
+    static fromNumpy(options: {
+        pointsData: number[][];
+        skeleton: Skeleton;
+        track?: Track | null;
+        fromPredicted?: PredictedInstance | null;
+        trackingScore?: number;
+    }): Instance;
+    static empty(options: {
+        skeleton: Skeleton;
+    }): Instance;
+    get length(): number;
+    get nVisible(): number;
+    getPoint(target: number | string | Node): Point;
+    numpy(options?: {
+        invisibleAsNaN?: boolean;
+    }): number[][];
+    toString(): string;
+    get isEmpty(): boolean;
+    overlapsWith(other: Instance, iouThreshold?: number): boolean;
+    boundingBox(): [number, number, number, number] | null;
+}
+declare class PredictedInstance extends Instance {
+    score: number;
+    constructor(options: {
+        points: PredictedPointsArray | Record<string, number[]>;
+        skeleton: Skeleton;
+        track?: Track | null;
+        score?: number;
+        trackingScore?: number;
+    });
+    static fromArray(points: number[][], skeleton: Skeleton, score?: number): PredictedInstance;
+    static fromNumpy(options: {
+        pointsData: number[][];
+        skeleton: Skeleton;
+        track?: Track | null;
+        score?: number;
+        trackingScore?: number;
+    }): PredictedInstance;
+    static empty(options: {
+        skeleton: Skeleton;
+    }): PredictedInstance;
+    numpy(options?: {
+        scores?: boolean;
+        invisibleAsNaN?: boolean;
+    }): number[][];
+    toString(): string;
+}
+declare function pointsFromDict(pointsDict: Record<string, number[]>, skeleton: Skeleton): PointsArray;
+declare function predictedPointsFromDict(pointsDict: Record<string, number[]>, skeleton: Skeleton): PredictedPointsArray;
+
+export { Edge as E, Instance as I, Node as N, PredictedInstance as P, Skeleton as S, Track as T, type Point as a, type PredictedPoint as b, type PointsArray as c, type PredictedPointsArray as d, predictedPointsEmpty as e, pointsFromArray as f, predictedPointsFromArray as g, pointsFromDict as h, predictedPointsFromDict as i, Symmetry as j, type NodeOrIndex as k, pointsEmpty as p };

package/dist/lite.d.ts

@@ -0,0 +1,209 @@
+import { S as Skeleton, T as Track } from './instance-D_5PPN1y.js';
+export { E as Edge, N as Node, j as Symmetry } from './instance-D_5PPN1y.js';
+
+/**
+ * jsfive-based HDF5 file interface.
+ * Pure JavaScript implementation for Workers-compatible environments.
+ */
+type JsfiveSource = ArrayBuffer | Uint8Array;
+
+/**
+ * Shared parsing functions for SLP file metadata.
+ * Used by both the full h5wasm-based reader and the lite jsfive-based reader.
+ */
+
+/**
+ * Video metadata extracted from videos_json without creating backends.
+ */
+interface VideoMetadata {
+    /** Original filename or "." for embedded */
+    filename: string;
+    /** HDF5 dataset path for embedded videos */
+    dataset?: string;
+    /** Video format (e.g., "mp4", "hdf5") */
+    format?: string;
+    /** Video width in pixels */
+    width?: number;
+    /** Video height in pixels */
+    height?: number;
+    /** Number of color channels */
+    channels?: number;
+    /** Frames per second */
+    fps?: number;
+    /** Total number of frames */
+    frameCount?: number;
+    /** Channel order (e.g., "RGB", "BGR") */
+    channelOrder?: string;
+    /** Whether video is embedded in the SLP file */
+    embedded: boolean;
+    /** Source video metadata if this is derived */
+    sourceVideo?: {
+        filename: string;
+    };
+}
+/**
+ * Suggestion frame metadata.
+ */
+interface SuggestionMetadata {
+    /** Video index */
+    video: number;
+    /** Frame index within the video */
+    frameIdx: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Camera metadata from recording sessions.
+ */
+interface CameraMetadata {
+    /** Camera name */
+    name?: string;
+    /** Rotation vector (Rodrigues) */
+    rvec: number[];
+    /** Translation vector */
+    tvec: number[];
+    /** 3x3 intrinsic camera matrix */
+    matrix?: number[][];
+    /** Lens distortion coefficients */
+    distortions?: number[];
+}
+/**
+ * Recording session metadata.
+ */
+interface SessionMetadata {
+    /** Camera definitions with calibration */
+    cameras: CameraMetadata[];
+    /** Mapping of camera name/key to video index */
+    videosByCamera: Record<string, number>;
+    /** Additional session metadata */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * Lightweight SLP file reader using jsfive (pure JavaScript).
+ *
+ * This module provides Workers-compatible SLP file reading without WASM.
+ * It can extract all metadata but cannot read pose coordinates (which
+ * require compound dataset support).
+ *
+ * @example
+ * ```typescript
+ * import { loadSlpMetadata } from '@talmolab/sleap-io.js/lite';
+ *
+ * const response = await fetch('https://example.com/file.slp');
+ * const buffer = await response.arrayBuffer();
+ * const metadata = await loadSlpMetadata(buffer);
+ *
+ * console.log('Skeletons:', metadata.skeletons.map(s => s.name));
+ * console.log('Frames:', metadata.counts.labeledFrames);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Metadata extracted from an SLP file without loading pose data.
+ */
+interface SlpMetadata {
+    /** SLEAP version that created this file (e.g., "1.3.4") */
+    version: string;
+    /** HDF5 format ID (e.g., 1.2) */
+    formatId: number;
+    /** Skeleton definitions with nodes, edges, and symmetries */
+    skeletons: Skeleton[];
+    /** Track definitions */
+    tracks: Track[];
+    /** Video metadata (without loaded backends) */
+    videos: VideoMetadata[];
+    /** Suggestion frame metadata */
+    suggestions: SuggestionMetadata[];
+    /** Multi-camera recording session metadata */
+    sessions: SessionMetadata[];
+    /** Dataset counts */
+    counts: {
+        /** Number of labeled frames */
+        labeledFrames: number;
+        /** Total number of instances (user + predicted) */
+        instances: number;
+        /** Number of user-labeled points */
+        points: number;
+        /** Number of predicted points */
+        predictedPoints: number;
+    };
+    /** Whether any video has embedded image data */
+    hasEmbeddedImages: boolean;
+    /** Raw provenance data (SLEAP version, build info, etc.) */
+    provenance?: Record<string, unknown>;
+}
+/**
+ * Load SLP file metadata using jsfive (no WASM required).
+ *
+ * This is a lightweight alternative to `loadSlp()` for environments
+ * that don't support WebAssembly compilation (e.g., Cloudflare Workers).
+ *
+ * Returns metadata only - does NOT include:
+ * - Actual pose coordinates (requires compound dataset reading)
+ * - Video frame data (requires VLEN sequence reading)
+ * - Instance-frame relationships
+ * - Instance scores
+ *
+ * @param source - ArrayBuffer or Uint8Array containing the SLP file
+ * @param options - Optional configuration
+ * @param options.filename - Filename hint for embedded video paths
+ * @returns SlpMetadata object with skeletons, counts, video info
+ * @throws Error if the file is not a valid SLP file
+ *
+ * @example
+ * ```typescript
+ * const buffer = await fetch('file.slp').then(r => r.arrayBuffer());
+ * const metadata = await loadSlpMetadata(buffer);
+ *
+ * console.log(`${metadata.skeletons.length} skeleton(s)`);
+ * console.log(`${metadata.counts.labeledFrames} labeled frames`);
+ * console.log(`${metadata.counts.instances} instances`);
+ * ```
+ */
+declare function loadSlpMetadata(source: JsfiveSource, options?: {
+    filename?: string;
+}): Promise<SlpMetadata>;
+/**
+ * Validate that a buffer contains a valid SLP file.
+ *
+ * Performs quick structural validation without fully parsing the file.
+ * Returns true if valid, throws an error with details if invalid.
+ *
+ * @param source - ArrayBuffer or Uint8Array containing the SLP file
+ * @returns true if the file is a valid SLP file
+ * @throws Error with details if the file is invalid
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateSlpBuffer(buffer);
+ *   console.log('Valid SLP file');
+ * } catch (e) {
+ *   console.error('Invalid:', e.message);
+ * }
+ * ```
+ */
+declare function validateSlpBuffer(source: JsfiveSource): boolean;
+/**
+ * Check if a buffer looks like an HDF5 file.
+ *
+ * Performs a quick magic number check without fully parsing.
+ * This is faster than validateSlpBuffer for initial filtering.
+ *
+ * @param source - ArrayBuffer or Uint8Array to check
+ * @returns true if the buffer starts with the HDF5 magic number
+ *
+ * @example
+ * ```typescript
+ * if (isHdf5Buffer(buffer)) {
+ *   // Might be an SLP file, do full validation
+ *   const metadata = await loadSlpMetadata(buffer);
+ * }
+ * ```
+ */
+declare function isHdf5Buffer(source: JsfiveSource): boolean;
+
+export { type CameraMetadata, type JsfiveSource, type SessionMetadata, Skeleton, type SlpMetadata, type SuggestionMetadata, Track, type VideoMetadata, isHdf5Buffer, loadSlpMetadata, validateSlpBuffer };

package/dist/lite.js

@@ -0,0 +1,178 @@
+import {
+  Edge,
+  Node,
+  Skeleton,
+  Symmetry,
+  Track,
+  parseJsonAttr,
+  parseSessionsMetadata,
+  parseSkeletons,
+  parseSuggestions,
+  parseTracks,
+  parseVideosMetadata
+} from "./chunk-CDU5QGU6.js";
+
+// src/codecs/slp/jsfive.ts
+import * as hdf5 from "jsfive";
+function openJsfiveFile(source, filename) {
+  let buffer;
+  if (source instanceof Uint8Array) {
+    const slice = source.buffer.slice(source.byteOffset, source.byteOffset + source.byteLength);
+    buffer = slice;
+  } else {
+    buffer = source;
+  }
+  const file = new hdf5.File(buffer, filename ?? "data.slp");
+  return {
+    get: (path) => {
+      try {
+        const item = file.get(path);
+        if (!item) return null;
+        return item;
+      } catch {
+        return null;
+      }
+    },
+    keys: file.keys,
+    close: () => {
+    }
+  };
+}
+function isDataset(item) {
+  if (!item) return false;
+  return "value" in item || "shape" in item;
+}
+function getAttrs(item) {
+  if (!item) return {};
+  return item.attrs ?? {};
+}
+function getShape(item) {
+  if (!item || !isDataset(item)) return [];
+  return item.shape ?? [];
+}
+function getValue(item) {
+  if (!item || !isDataset(item)) return null;
+  try {
+    return item.value;
+  } catch {
+    return null;
+  }
+}
+
+// src/lite.ts
+async function loadSlpMetadata(source, options) {
+  const file = openJsfiveFile(source, options?.filename);
+  try {
+    const requiredKeys = ["metadata", "frames", "instances", "points"];
+    for (const key of requiredKeys) {
+      if (!file.keys.includes(key)) {
+        throw new Error(`Invalid SLP file: missing /${key}`);
+      }
+    }
+    const metadataGroup = file.get("metadata");
+    if (!metadataGroup) {
+      throw new Error("Invalid SLP file: missing /metadata group");
+    }
+    const metadataAttrs = getAttrs(metadataGroup);
+    const formatId = Number(
+      metadataAttrs.format_id?.value ?? metadataAttrs.format_id ?? 1
+    );
+    const metadataJson = parseJsonAttr(metadataAttrs.json);
+    if (!metadataJson) {
+      throw new Error("Invalid SLP file: missing metadata.attrs.json");
+    }
+    const skeletons = parseSkeletons(metadataJson);
+    const tracksDataset = file.get("tracks_json");
+    const tracksValue = getValue(tracksDataset);
+    const tracks = Array.isArray(tracksValue) ? parseTracks(tracksValue) : [];
+    const videosDataset = file.get("videos_json");
+    const videosValue = getValue(videosDataset);
+    const labelsPath = options?.filename ?? "slp-data.slp";
+    let videos = Array.isArray(videosValue) ? parseVideosMetadata(videosValue, labelsPath) : [];
+    videos = videos.map((video) => {
+      if (!video.embedded || !video.dataset) return video;
+      const videoDs = file.get(video.dataset);
+      if (!videoDs || !isDataset(videoDs)) return video;
+      const attrs = getAttrs(videoDs);
+      const enriched = { ...video };
+      if (attrs.format !== void 0) enriched.format = String(attrs.format);
+      if (attrs.width !== void 0) enriched.width = Number(attrs.width);
+      if (attrs.height !== void 0) enriched.height = Number(attrs.height);
+      if (attrs.channels !== void 0) enriched.channels = Number(attrs.channels);
+      const shape = getShape(videoDs);
+      if (shape.length > 0) {
+        enriched.frameCount = shape[0];
+      }
+      return enriched;
+    });
+    const suggestionsDataset = file.get("suggestions_json");
+    const suggestionsValue = getValue(suggestionsDataset);
+    const suggestions = Array.isArray(suggestionsValue) ? parseSuggestions(suggestionsValue) : [];
+    const sessionsDataset = file.get("sessions_json");
+    const sessionsValue = getValue(sessionsDataset);
+    const sessions = Array.isArray(sessionsValue) ? parseSessionsMetadata(sessionsValue) : [];
+    const framesDs = file.get("frames");
+    const instancesDs = file.get("instances");
+    const pointsDs = file.get("points");
+    const predPointsDs = file.get("pred_points");
+    const counts = {
+      labeledFrames: getShape(framesDs)[0] ?? 0,
+      instances: getShape(instancesDs)[0] ?? 0,
+      points: getShape(pointsDs)[0] ?? 0,
+      predictedPoints: getShape(predPointsDs)[0] ?? 0
+    };
+    const hasEmbeddedImages = videos.some(
+      (v) => v.embedded && (v.format || v.width)
+    );
+    return {
+      version: metadataJson.version ?? "unknown",
+      formatId,
+      skeletons,
+      tracks,
+      videos,
+      suggestions,
+      sessions,
+      counts,
+      hasEmbeddedImages,
+      provenance: metadataJson.provenance
+    };
+  } finally {
+    file.close();
+  }
+}
+function validateSlpBuffer(source) {
+  const file = openJsfiveFile(source);
+  try {
+    const requiredKeys = ["metadata", "frames", "instances", "points"];
+    const missingKeys = requiredKeys.filter((k) => !file.keys.includes(k));
+    if (missingKeys.length > 0) {
+      throw new Error(`Invalid SLP file: missing ${missingKeys.join(", ")}`);
+    }
+    const metadata = file.get("metadata");
+    if (!metadata) {
+      throw new Error("Invalid SLP file: cannot read metadata group");
+    }
+    const attrs = getAttrs(metadata);
+    if (!attrs.json) {
+      throw new Error("Invalid SLP file: missing metadata.attrs.json");
+    }
+    return true;
+  } finally {
+    file.close();
+  }
+}
+function isHdf5Buffer(source) {
+  const bytes = source instanceof Uint8Array ? source : new Uint8Array(source);
+  if (bytes.length < 8) return false;
+  return bytes[0] === 137 && bytes[1] === 72 && bytes[2] === 68 && bytes[3] === 70 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10;
+}
+export {
+  Edge,
+  Node,
+  Skeleton,
+  Symmetry,
+  Track,
+  isHdf5Buffer,
+  loadSlpMetadata,
+  validateSlpBuffer
+};

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@talmolab/sleap-io.js",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./lite": {
+      "types": "./dist/lite.d.ts",
+      "import": "./dist/lite.js"
     }
   },
   "main": "./dist/index.js",
@@ -17,14 +21,16 @@
     "url": "https://github.com/talmolab/sleap-io.js.git"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
+    "build": "tsup src/index.ts src/lite.ts --format esm --dts",
     "test": "vitest",
     "test:coverage": "vitest --run --coverage",
     "lint": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
     "h5wasm": "^0.8.8",
+    "jsfive": "^0.3.10",
     "mp4box": "^0.5.4",
+    "skia-canvas": "^3.0.8",
     "yaml": "^2.6.1"
   },
   "devDependencies": {
@@ -33,5 +39,8 @@
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^2.1.8"
-  }
+  },
+  "trustedDependencies": [
+    "skia-canvas"
+  ]
 }