@talmolab/sleap-io.js 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,127 +1,5 @@
-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;
+import { I as Instance, P as PredictedInstance, S as Skeleton, T as Track } from './instance-D_5PPN1y.js';
+export { E as Edge, N as Node, k as NodeOrIndex, a as Point, c as PointsArray, b as PredictedPoint, d as PredictedPointsArray, j as Symmetry, p as pointsEmpty, f as pointsFromArray, h as pointsFromDict, e as predictedPointsEmpty, g as predictedPointsFromArray, i as predictedPointsFromDict } from './instance-D_5PPN1y.js';
 
 type VideoFrame = ImageData | ImageBitmap | Uint8Array | ArrayBuffer;
 interface VideoBackend {
@@ -363,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;
 };
 
@@ -436,4 +422,240 @@ declare function labelsFromNumpy(data: number[][][][], options: {
 declare function decodeYamlSkeleton(yamlData: string): Skeleton | Skeleton[];
 declare function encodeYamlSkeleton(skeletons: Skeleton | Skeleton[]): string;
 
-export { Camera, CameraGroup, Edge, FrameGroup, Instance, InstanceGroup, LabeledFrame, Labels, type LabelsDict, LabelsSet, Mp4BoxVideoBackend, Node, type NodeOrIndex, type Point, type PointsArray, PredictedInstance, type PredictedPoint, type PredictedPointsArray, RecordingSession, Skeleton, SuggestionFrame, Symmetry, Track, Video, type VideoBackend, type VideoFrame, decodeYamlSkeleton, encodeYamlSkeleton, fromDict, fromNumpy, labelsFromNumpy, loadSlp, loadVideo, makeCameraFromDict, pointsEmpty, pointsFromArray, pointsFromDict, predictedPointsEmpty, predictedPointsFromArray, predictedPointsFromDict, rodriguesTransformation, saveSlp, toDict, toNumpy };
+/**
+ * Context passed to pre/post render callbacks.
+ */
+declare class RenderContext {
+    /** The 2D canvas rendering context */
+    readonly canvas: CanvasRenderingContext2D;
+    /** Current frame index (0 for single images) */
+    readonly frameIdx: number;
+    /** Original frame size [width, height] */
+    readonly frameSize: [number, number];
+    /** Instances in this frame */
+    readonly instances: (Instance | PredictedInstance)[];
+    /** Skeleton edge connectivity as [srcIdx, dstIdx] pairs */
+    readonly skeletonEdges: [number, number][];
+    /** Node names from skeleton */
+    readonly nodeNames: string[];
+    /** Current scale factor */
+    readonly scale: number;
+    /** Offset for cropped views [x, y] */
+    readonly offset: [number, number];
+    constructor(
+    /** The 2D canvas rendering context */
+    canvas: CanvasRenderingContext2D, 
+    /** Current frame index (0 for single images) */
+    frameIdx: number, 
+    /** Original frame size [width, height] */
+    frameSize: [number, number], 
+    /** Instances in this frame */
+    instances: (Instance | PredictedInstance)[], 
+    /** Skeleton edge connectivity as [srcIdx, dstIdx] pairs */
+    skeletonEdges: [number, number][], 
+    /** Node names from skeleton */
+    nodeNames: string[], 
+    /** Current scale factor */
+    scale?: number, 
+    /** Offset for cropped views [x, y] */
+    offset?: [number, number]);
+    /**
+     * Transform world coordinates to canvas coordinates.
+     */
+    worldToCanvas(x: number, y: number): [number, number];
+}
+/**
+ * Context passed to per-instance callbacks.
+ */
+declare class InstanceContext {
+    /** The 2D canvas rendering context */
+    readonly canvas: CanvasRenderingContext2D;
+    /** Index of this instance within the frame */
+    readonly instanceIdx: number;
+    /** Keypoint coordinates as [[x0, y0], [x1, y1], ...] */
+    readonly points: number[][];
+    /** Skeleton edge connectivity */
+    readonly skeletonEdges: [number, number][];
+    /** Node names */
+    readonly nodeNames: string[];
+    /** Track ID (index in tracks array) */
+    readonly trackIdx: number | null;
+    /** Track name if available */
+    readonly trackName: string | null;
+    /** Instance confidence score */
+    readonly confidence: number | null;
+    /** Current scale factor */
+    readonly scale: number;
+    /** Offset for cropped views */
+    readonly offset: [number, number];
+    constructor(
+    /** The 2D canvas rendering context */
+    canvas: CanvasRenderingContext2D, 
+    /** Index of this instance within the frame */
+    instanceIdx: number, 
+    /** Keypoint coordinates as [[x0, y0], [x1, y1], ...] */
+    points: number[][], 
+    /** Skeleton edge connectivity */
+    skeletonEdges: [number, number][], 
+    /** Node names */
+    nodeNames: string[], 
+    /** Track ID (index in tracks array) */
+    trackIdx?: number | null, 
+    /** Track name if available */
+    trackName?: string | null, 
+    /** Instance confidence score */
+    confidence?: number | null, 
+    /** Current scale factor */
+    scale?: number, 
+    /** Offset for cropped views */
+    offset?: [number, number]);
+    /**
+     * Transform world coordinates to canvas coordinates.
+     */
+    worldToCanvas(x: number, y: number): [number, number];
+    /**
+     * Get centroid of valid (non-NaN) points.
+     */
+    getCentroid(): [number, number] | null;
+    /**
+     * Get bounding box of valid points.
+     * Returns [x1, y1, x2, y2] or null if no valid points.
+     */
+    getBbox(): [number, number, number, number] | null;
+}
+
+/** RGB color as [r, g, b] with values 0-255 */
+type RGB = [number, number, number];
+/** RGBA color as [r, g, b, a] with values 0-255 */
+type RGBA = [number, number, number, number];
+/** Flexible color specification */
+type ColorSpec = RGB | RGBA | string | number;
+/** Available color schemes */
+type ColorScheme = "track" | "instance" | "node" | "auto";
+/** Built-in palette names */
+type PaletteName = "standard" | "distinct" | "tableau10" | "viridis" | "rainbow" | "warm" | "cool" | "pastel" | "seaborn";
+/** Marker shape types */
+type MarkerShape = "circle" | "square" | "diamond" | "triangle" | "cross";
+/** Render options for renderImage() */
+interface RenderOptions {
+    colorBy?: ColorScheme;
+    palette?: PaletteName | string;
+    markerShape?: MarkerShape;
+    markerSize?: number;
+    lineWidth?: number;
+    alpha?: number;
+    showNodes?: boolean;
+    showEdges?: boolean;
+    scale?: number;
+    background?: "transparent" | ColorSpec;
+    image?: ImageData | null;
+    width?: number;
+    height?: number;
+    preRenderCallback?: (ctx: RenderContext) => void;
+    postRenderCallback?: (ctx: RenderContext) => void;
+    perInstanceCallback?: (ctx: InstanceContext) => void;
+}
+/** Video rendering options (extends RenderOptions) */
+interface VideoOptions extends RenderOptions {
+    frameInds?: number[];
+    start?: number;
+    end?: number;
+    fps?: number;
+    codec?: string;
+    crf?: number;
+    preset?: string;
+    onProgress?: (current: number, total: number) => void;
+}
+
+/** Named CSS colors */
+declare const NAMED_COLORS: Record<string, RGB>;
+/** Built-in color palettes (port from Python sleap_io/rendering/colors.py) */
+declare const PALETTES: Record<PaletteName, RGB[]>;
+/**
+ * Get n colors from a named palette, cycling if needed.
+ */
+declare function getPalette(name: PaletteName | string, n: number): RGB[];
+/**
+ * Resolve flexible color specification to RGB tuple.
+ */
+declare function resolveColor(color: ColorSpec): RGB;
+/**
+ * Convert RGB to CSS color string.
+ */
+declare function rgbToCSS(rgb: RGB, alpha?: number): string;
+/**
+ * Determine color scheme based on context.
+ * - If tracks available: 'track'
+ * - Else if single image: 'instance'
+ * - Else: 'node' (prevents flicker in video)
+ */
+declare function determineColorScheme(scheme: ColorScheme, hasTracks: boolean, isSingleImage: boolean): ColorScheme;
+
+type DrawMarkerFn = (ctx: CanvasRenderingContext2D, x: number, y: number, size: number, fillColor: string, edgeColor?: string, edgeWidth?: number) => void;
+/**
+ * Draw a circle marker.
+ */
+declare function drawCircle(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, fillColor: string, edgeColor?: string, edgeWidth?: number): void;
+/**
+ * Draw a square marker.
+ */
+declare function drawSquare(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, fillColor: string, edgeColor?: string, edgeWidth?: number): void;
+/**
+ * Draw a diamond marker (rotated square).
+ */
+declare function drawDiamond(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, fillColor: string, edgeColor?: string, edgeWidth?: number): void;
+/**
+ * Draw a triangle marker (pointing up).
+ */
+declare function drawTriangle(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, fillColor: string, edgeColor?: string, edgeWidth?: number): void;
+/**
+ * Draw a cross/plus marker.
+ */
+declare function drawCross(ctx: CanvasRenderingContext2D, x: number, y: number, size: number, fillColor: string, _edgeColor?: string, edgeWidth?: number): void;
+/** Map of marker shape names to drawing functions */
+declare const MARKER_FUNCTIONS: Record<MarkerShape, DrawMarkerFn>;
+/**
+ * Get the drawing function for a marker shape.
+ */
+declare function getMarkerFunction(shape: MarkerShape): DrawMarkerFn;
+
+/**
+ * Render poses on a single frame.
+ *
+ * @param source - Labels, LabeledFrame, or array of Instances to render
+ * @param options - Rendering options
+ * @returns ImageData with rendered poses
+ */
+declare function renderImage(source: Labels | LabeledFrame | (Instance | PredictedInstance)[], options?: RenderOptions): Promise<ImageData>;
+/**
+ * Convert ImageData to PNG buffer (Node.js only).
+ */
+declare function toPNG(imageData: ImageData): Promise<Buffer>;
+/**
+ * Convert ImageData to JPEG buffer (Node.js only).
+ */
+declare function toJPEG(imageData: ImageData, quality?: number): Promise<Buffer>;
+/**
+ * Convert ImageData to data URL.
+ */
+declare function toDataURL(imageData: ImageData, format?: "png" | "jpeg"): string;
+/**
+ * Save ImageData to a file.
+ */
+declare function saveImage(imageData: ImageData, path: string): Promise<void>;
+
+/**
+ * Check if ffmpeg is available in PATH.
+ */
+declare function checkFfmpeg(): Promise<boolean>;
+/**
+ * Render video with pose overlays.
+ * Requires ffmpeg to be installed and in PATH.
+ *
+ * @param source - Labels or array of LabeledFrames to render
+ * @param outputPath - Path to save the output video
+ * @param options - Video rendering options
+ */
+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, 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 };