tempest-react-sdk 0.11.0 → 0.13.0

package/dist/vision.d.ts

@@ -0,0 +1,1030 @@
+import type * as ort from 'onnxruntime-web';
+
+/**
+ * Per-class NMS — boxes are suppressed only by other boxes of the same class.
+ *
+ * Mirrors `torchvision.ops.batched_nms`.
+ *
+ * @param boxes Flat array of length `4 * N` in xyxy order.
+ * @param scores Detection score per box, length `N`.
+ * @param idxs Class index per box, length `N`. Boxes with different `idxs`
+ *   never suppress each other.
+ * @param iouThreshold IoU threshold for suppression within a class.
+ */
+export declare function batchedNms(boxes: Float32Array, scores: Float32Array, idxs: Int32Array, iouThreshold: number): Int32Array;
+
+/**
+ * Axis-aligned bounding box in absolute pixel coordinates (xyxy format).
+ *
+ * Coordinates refer to the original input image (before any internal resize),
+ * so callers can map detections back onto their source image without any
+ * additional bookkeeping.
+ */
+export declare class BoundingBox {
+    readonly x1: number;
+    readonly y1: number;
+    readonly x2: number;
+    readonly y2: number;
+    constructor(x1: number, y1: number, x2: number, y2: number);
+    /** Box width in pixels (clamped to non-negative). */
+    get width(): number;
+    /** Box height in pixels (clamped to non-negative). */
+    get height(): number;
+    /** Box area in pixels squared. */
+    get area(): number;
+    /** The box as `[x1, y1, x2, y2]` in absolute pixels (Ultralytics-style). */
+    get xyxy(): readonly [number, number, number, number];
+    /**
+     * The box as `[cx, cy, w, h]` with `(cx, cy)` at the center.
+     *
+     * Matches Ultralytics' `boxes.xywh` and YOLO's native head format. For the
+     * top-left `[x, y, w, h]` convention, use {@link asXywh}.
+     */
+    get xywh(): readonly [number, number, number, number];
+    /**
+     * The box as `[x1, y1, x2, y2]` normalized to `[0, 1]`.
+     *
+     * @param origShape `[height, width]` of the source image, in pixels.
+     */
+    xyxyn(origShape: readonly [number, number]): readonly [number, number, number, number];
+    /**
+     * The box as `[cx, cy, w, h]` normalized to `[0, 1]`.
+     *
+     * @param origShape `[height, width]` of the source image, in pixels.
+     */
+    xywhn(origShape: readonly [number, number]): readonly [number, number, number, number];
+    /** Returns `[x1, y1, x2, y2]`. */
+    asXyxy(): readonly [number, number, number, number];
+    /**
+     * Returns `[x, y, width, height]` with `(x, y)` at the **top-left**.
+     *
+     * Note: this is the top-left convention. Ultralytics' `xywh` getter uses
+     * **center** coordinates — for that, read {@link xywh}.
+     */
+    asXywh(): readonly [number, number, number, number];
+    /** Returns `[x1, y1, x2, y2]` truncated to integers, useful for slicing arrays. */
+    asIntXyxy(): readonly [number, number, number, number];
+}
+
+/**
+ * Bulk numpy-style view of detected boxes for a single image.
+ *
+ * Mirrors Ultralytics' `Boxes` interface. Coordinates in {@link xyxy} and
+ * {@link xywh} are absolute pixels in the original image; the `*n` variants
+ * are normalized to `[0, 1]` using `origShape`.
+ */
+export declare class Boxes {
+    readonly xyxy: Float32Array;
+    readonly cls: Int32Array;
+    readonly conf: Float32Array;
+    readonly origShape: readonly [number, number];
+    /**
+     * @param xyxy Flat array of length `4 * N` in `[x1, y1, x2, y2, ...]` order.
+     * @param cls One class index per box, length `N`.
+     * @param conf One confidence per box, length `N`.
+     * @param origShape `[height, width]` of the original image.
+     */
+    constructor(xyxy: Float32Array, cls: Int32Array, conf: Float32Array, origShape: readonly [number, number]);
+    /** Number of detected boxes. */
+    get length(): number;
+    /** `[N, 4]` shape of the `xyxy` view. */
+    get shape(): readonly [number, number];
+    /** Boxes as `[N, 4]` `[cx, cy, w, h]` flat array in absolute pixels. */
+    get xywh(): Float32Array;
+    /** Boxes as `[N, 4]` `[x1, y1, x2, y2]` normalized to `[0, 1]`. */
+    get xyxyn(): Float32Array;
+    /** Boxes as `[N, 4]` `[cx, cy, w, h]` normalized to `[0, 1]`. */
+    get xywhn(): Float32Array;
+    /**
+     * Concatenated `[N, 6]` array of `[x1, y1, x2, y2, conf, cls]`.
+     *
+     * Matches Ultralytics' `boxes.data`.
+     */
+    get data(): Float32Array;
+}
+
+/**
+ * Output of an image classification inference.
+ */
+export declare interface ClassificationResult {
+    readonly classId: number;
+    readonly className: string;
+    readonly confidence: number;
+    /** Alias for `classId` (Ultralytics-style). */
+    readonly cls: number;
+    /** Alias for `className`. */
+    readonly name: string;
+    /** Alias for `confidence` (Ultralytics-style). */
+    readonly conf: number;
+    /** The original input image as an HWC RGB uint8 array. */
+    readonly image: RGBImage;
+    /**
+     * Probabilities per class, sorted in descending order. The first entry
+     * mirrors `classId`, `className`, and `confidence`. When `topK` was passed
+     * to `predict`, the array is truncated to that length.
+     */
+    readonly probabilities: readonly ClassProbability[];
+}
+
+/**
+ * Per-image classification envelope (Ultralytics-style `Results`).
+ */
+export declare class ClassificationResults {
+    readonly probs: Probs;
+    readonly result: ClassificationResult;
+    readonly names: Readonly<Record<number, string>>;
+    readonly origImg: RGBImage;
+    readonly origShape: readonly [number, number];
+    readonly path: string | null;
+    readonly speed: Readonly<Record<string, number>>;
+    constructor(probs: Probs, result: ClassificationResult, names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Record<string, number>>);
+    /** Top-1 class index (Ultralytics-style alias). */
+    get cls(): number;
+    /** Top-1 confidence (Ultralytics-style alias). */
+    get conf(): number;
+    /** Top-1 class name. */
+    get name(): string;
+    /** Per-class probability list, sorted descending (legacy field). */
+    get probabilities(): readonly ClassificationResult["probabilities"][number][];
+}
+
+/**
+ * Image classifier wrapping an ONNX model with ImageNet-style preprocessing.
+ *
+ * `predict()` returns `Promise<ClassificationResults[]>` (length 1 for a
+ * single image), mirroring Ultralytics' API. The envelope exposes a `probs`
+ * collection (`top1`, `top1conf`, `top5`, `top5conf`, `data`) plus the
+ * legacy per-class probability list with names already resolved.
+ *
+ * Defaults: 224×224 RGB input, `float32` normalized with ImageNet mean/std,
+ * NCHW layout, batch size 1, softmax applied to the raw output.
+ *
+ * @example
+ * ```typescript
+ * const clf = await Classifier.create("/models/resnet50.onnx", {
+ *   labels: ["tench", "goldfish", ...]  // 1000 ImageNet labels
+ * });
+ * const r = (await clf.predict("/images/dog.jpg"))[0];
+ * console.log(r.cls, r.conf, r.name);
+ * console.log(r.probs.top5, r.probs.top5conf);
+ * ```
+ */
+export declare class Classifier extends VisionTask {
+    private readonly _labels;
+    private readonly _names;
+    private readonly _inputSize;
+    private readonly _mean;
+    private readonly _std;
+    private readonly _applySoftmax;
+    private constructor();
+    /** Load the model and resolve labels. */
+    static create(model: ModelSource, options: ClassifierOptions): Promise<Classifier>;
+    /** Class labels indexed by class id. */
+    get labels(): readonly string[];
+    /** Class id → class name dict (matches Ultralytics' `model.names`). */
+    get names(): Readonly<Record<number, string>>;
+    /** Number of classes the model can predict. */
+    get numClasses(): number;
+    /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
+    call(image: ImageInput, options?: ClassifierPredictOptions): Promise<ClassificationResults[]>;
+    /** Run classification on a single image. */
+    predict(image: ImageInput, options?: ClassifierPredictOptions): Promise<ClassificationResults[]>;
+    private _preprocess;
+    private _postprocess;
+}
+
+export declare interface ClassifierOptions extends OrtSessionOptions {
+    /** Class label spec — see {@link resolveLabels}. */
+    readonly labels: LabelSpec;
+    /**
+     * Number of classes the model can predict. Required when `labels` is `null`
+     * or when you want to validate that the supplied labels match the model.
+     */
+    readonly numClasses?: number;
+    /** Model input `[width, height]` in pixels. Defaults to `[224, 224]`. */
+    readonly inputSize?: readonly [number, number];
+    /** Per-channel RGB mean used for normalization. Defaults to ImageNet. */
+    readonly mean?: readonly [number, number, number];
+    /** Per-channel RGB standard deviation. Defaults to ImageNet. */
+    readonly std?: readonly [number, number, number];
+    /**
+     * If `true` (default), apply softmax to the raw model output. Set to
+     * `false` for models whose final layer already produces a probability
+     * distribution.
+     */
+    readonly applySoftmax?: boolean;
+}
+
+export declare interface ClassifierPredictOptions {
+    /**
+     * If set, the per-class probability list in `results[0].result.probabilities`
+     * is truncated to the top-K entries. The bulk `probs` view always exposes
+     * the full vector.
+     */
+    readonly topK?: number;
+}
+
+/**
+ * Probability assigned to a single class for a classification prediction.
+ *
+ * `cls` / `name` / `conf` are Ultralytics-style aliases populated alongside
+ * the verbose `classId` / `className` / `probability` fields.
+ */
+export declare interface ClassProbability {
+    readonly classId: number;
+    readonly className: string;
+    readonly probability: number;
+    /** Alias for `classId` (Ultralytics-style). */
+    readonly cls: number;
+    /** Alias for `className`. */
+    readonly name: string;
+    /** Alias for `probability` (Ultralytics-style). */
+    readonly conf: number;
+}
+
+/** COCO 2017 80-class labels in canonical class-id order. */
+export declare const COCO_CLASSES: readonly string[];
+
+export declare interface DecodedAnchors {
+    /** Indices into the original `numAnchors` axis, in descending confidence order. */
+    readonly anchorIndices: Int32Array;
+    /** `[k, 4]` boxes in original-image pixel coords, flat row-major xyxy. */
+    readonly boxesXyxy: Float32Array;
+    /** Predicted class id per survivor. */
+    readonly classIds: Int32Array;
+    /** Confidence per survivor. */
+    readonly confidences: Float32Array;
+}
+
+export declare interface DecodedDetection {
+    readonly bbox: BoundingBox;
+    readonly classId: number;
+    readonly confidence: number;
+}
+
+export declare interface DecodedSegmentation {
+    readonly bbox: BoundingBox;
+    readonly classId: number;
+    readonly confidence: number;
+    /** Binary mask cropped to `bbox`. Width/height match `bbox.asIntXyxy()` extents. */
+    readonly mask: Mask;
+}
+
+/**
+ * Decode an anchor-free YOLO detection output into a list of detections.
+ *
+ * Works for **YOLOv8 / v9 / v10 / v11 / v12** detect heads.
+ *
+ * Expected raw shape: `[1, 4 + numClasses, N]`. `numClasses` is inferred
+ * from the channel count.
+ */
+export declare function decodeYolo(output: Float32Array, outputDims: readonly number[], options: DecodeYoloOptions): DecodedDetection[];
+
+/**
+ * Shared YOLO per-anchor decode used by both detection and segmentation
+ * (v8 / v9 / v10 / v11 / v12).
+ *
+ * Only the first `4 + numClasses` channels are read; later channels (e.g.
+ * mask coefficients) are ignored — callers can fetch them via the returned
+ * {@link DecodedAnchors.anchorIndices}.
+ *
+ * @param data Flat per-anchor output, length `channels * numAnchors`.
+ * @param dims Dims as reported by ORT, e.g. `[1, 84, 8400]` (det) or
+ *   `[1, 116, 8400]` (seg). The leading batch dim must be 1.
+ */
+export declare function decodeYoloAnchors(data: Float32Array, dims: readonly number[], options: DecodeYoloAnchorsOptions): DecodedAnchors;
+
+export declare interface DecodeYoloAnchorsOptions {
+    /** Number of class-score channels following the 4 box channels. */
+    readonly numClasses: number;
+    readonly originalWidth: number;
+    readonly originalHeight: number;
+    readonly padLeft: number;
+    readonly padTop: number;
+    readonly scale: number;
+    readonly confThreshold: number;
+    readonly iouThreshold: number;
+    readonly maxDetections: number;
+}
+
+export declare interface DecodeYoloOptions {
+    readonly originalWidth: number;
+    readonly originalHeight: number;
+    readonly padLeft: number;
+    readonly padTop: number;
+    readonly scale: number;
+    readonly confThreshold: number;
+    readonly iouThreshold: number;
+    readonly maxDetections: number;
+}
+
+/**
+ * Decode YOLO segmentation raw outputs into a list of segmented instances.
+ *
+ * Compatible with YOLOv8-seg / YOLOv11-seg.
+ *
+ * @param perAnchorData Flat `output0`, length `(4 + numClasses + numMaskCoefs) * numAnchors`.
+ * @param perAnchorDims Dims as reported by ORT, e.g. `[1, 116, 8400]`.
+ * @param prototypeData Flat `output1`, length `numMaskCoefs * maskH * maskW`.
+ * @param prototypeDims Dims as reported by ORT, e.g. `[1, 32, 160, 160]`.
+ */
+export declare function decodeYoloSeg(perAnchorData: Float32Array, perAnchorDims: readonly number[], prototypeData: Float32Array, prototypeDims: readonly number[], options: DecodeYoloSegOptions): DecodedSegmentation[];
+
+export declare interface DecodeYoloSegOptions {
+    readonly numClasses: number;
+    /** Model input `[width, height]` (post-letterbox). */
+    readonly inputWidth: number;
+    readonly inputHeight: number;
+    /** Original image `[width, height]`. */
+    readonly originalWidth: number;
+    readonly originalHeight: number;
+    /** Letterbox horizontal padding in input-tensor pixels. */
+    readonly padLeft: number;
+    /** Letterbox vertical padding in input-tensor pixels. */
+    readonly padTop: number;
+    /** Letterbox scale factor. */
+    readonly scale: number;
+    readonly confThreshold: number;
+    readonly iouThreshold: number;
+    readonly maxDetections: number;
+    /** Probability cutoff applied to the soft mask. Defaults to `0.5`. */
+    readonly maskThreshold?: number;
+}
+
+/**
+ * @deprecated since 0.2.0 — use {@link decodeYolo}. Same behavior; the
+ * decoder covers v8/v9/v10/v11/v12 detect heads. Will be removed in 0.3.0.
+ */
+export declare function decodeYoloV8(output: Float32Array, outputDims: readonly number[], options: DecodeYoloOptions): DecodedDetection[];
+
+/**
+ * @deprecated since 0.2.0 — use {@link decodeYoloAnchors}. Will be removed in 0.3.0.
+ */
+export declare function decodeYoloV8Anchors(data: Float32Array, dims: readonly number[], options: DecodeYoloAnchorsOptions): DecodedAnchors;
+
+/** @deprecated since 0.2.0 — use {@link DecodeYoloAnchorsOptions}. */
+export declare type DecodeYoloV8AnchorsOptions = DecodeYoloAnchorsOptions;
+
+/** @deprecated since 0.2.0 — use {@link DecodeYoloOptions}. */
+export declare type DecodeYoloV8Options = DecodeYoloOptions;
+
+/** @deprecated since 0.2.0 — use {@link decodeYoloSeg}. Will be removed in 0.3.0. */
+export declare function decodeYoloV8Seg(perAnchorData: Float32Array, perAnchorDims: readonly number[], prototypeData: Float32Array, prototypeDims: readonly number[], options: DecodeYoloSegOptions): DecodedSegmentation[];
+
+/** @deprecated since 0.2.0 — use {@link DecodeYoloSegOptions}. */
+export declare type DecodeYoloV8SegOptions = DecodeYoloSegOptions;
+
+/**
+ * Default execution provider preference order for browser ORT.
+ *
+ * `webgpu` is tried first when available; ORT-Web falls back to `wasm`
+ * automatically when WebGPU is not supported by the browser or device.
+ */
+export declare const DEFAULT_PROVIDERS: readonly string[];
+
+/**
+ * Single detected object produced by an object-detection model.
+ */
+export declare interface DetectionResult {
+    readonly classId: number;
+    readonly className: string;
+    readonly confidence: number;
+    readonly bbox: BoundingBox;
+    /** Alias for `classId` (Ultralytics-style). */
+    readonly cls: number;
+    /** Alias for `className`. */
+    readonly name: string;
+    /** Alias for `confidence` (Ultralytics-style). */
+    readonly conf: number;
+    /** Alias for `bbox` (Ultralytics-style). */
+    readonly box: BoundingBox;
+    /**
+     * The original image cropped to `bbox`, HWC RGB uint8. Empty boxes
+     * (zero area) yield a zero-sized `RGBImage`.
+     */
+    readonly croppedImage: RGBImage;
+}
+
+/**
+ * Per-image detection envelope (Ultralytics-style `Results`).
+ *
+ * Iterating yields per-instance {@link DetectionResult} entries, so legacy
+ * code that did `for (const d of detector.predict(img))` only needs an
+ * extra `[0]` to bridge:
+ *
+ * ```typescript
+ * for (const d of (await detector.predict(img))[0]) {
+ *   console.log(d.cls, d.conf, d.box.xyxy);
+ * }
+ * ```
+ *
+ * For numpy-style bulk access, use the `boxes` collection.
+ */
+export declare class DetectionResults implements Iterable<DetectionResult> {
+    readonly boxes: Boxes;
+    readonly detections: readonly DetectionResult[];
+    readonly names: Readonly<Record<number, string>>;
+    readonly origImg: RGBImage;
+    readonly origShape: readonly [number, number];
+    readonly path: string | null;
+    readonly speed: Readonly<Record<string, number>>;
+    constructor(boxes: Boxes, detections: readonly DetectionResult[], names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Record<string, number>>);
+    /** Number of surviving detections. */
+    get length(): number;
+    /** Index into the per-instance detections. */
+    get(index: number): DetectionResult | undefined;
+    [Symbol.iterator](): Iterator<DetectionResult>;
+}
+
+/**
+ * Object detector for anchor-free YOLO ONNX models (v8/v9/v10/v11/v12).
+ *
+ * `predict()` returns `Promise<DetectionResults[]>` (length 1 for a single
+ * image), mirroring Ultralytics' `YOLO("img.jpg")`. Iterate the envelope for
+ * per-instance dataclasses, or use the bulk `boxes` view (`.xyxy`, `.xywh`,
+ * `.xyxyn`, `.xywhn`, `.cls`, `.conf`).
+ *
+ * @example
+ * ```typescript
+ * const det = await Detector.create("/models/yolov8n.onnx");
+ * const results = await det.predict("/images/street.jpg");
+ * const r = results[0];
+ * console.log(r.boxes.xyxy, r.boxes.cls, r.boxes.conf, r.names);
+ * for (const d of r) {
+ *   console.log(d.cls, d.conf, d.box.xyxy);
+ * }
+ * ```
+ */
+export declare class Detector extends VisionTask {
+    private readonly _head;
+    private readonly _labels;
+    private readonly _names;
+    private readonly _inputSize;
+    private readonly _confThreshold;
+    private readonly _iouThreshold;
+    private readonly _maxDetections;
+    private constructor();
+    /** Load the model and resolve labels. */
+    static create(model: ModelSource, options?: DetectorOptions): Promise<Detector>;
+    /** The decoder family used to interpret the model's output. */
+    get head(): DetectorHead;
+    /** Class labels indexed by class id. */
+    get labels(): readonly string[];
+    /** Class id → class name dict (matches Ultralytics' `model.names`). */
+    get names(): Readonly<Record<number, string>>;
+    /** Number of classes the model predicts. */
+    get numClasses(): number;
+    /**
+     * Alias for {@link predict} — call the detector like a torch `nn.Module`.
+     *
+     * Use as `det.call(img)` since JavaScript class instances are not callable;
+     * for direct invocation, prefer `det.predict(img)`. The full
+     * {@link DetectorPredictOptions} (including `classes`) is supported.
+     */
+    call(image: ImageInput, options?: DetectorPredictOptions): Promise<DetectionResults[]>;
+    /** Run detection on a single image. */
+    predict(image: ImageInput, options?: DetectorPredictOptions): Promise<DetectionResults[]>;
+    private _preprocess;
+    private _buildResult;
+    private _buildBoxes;
+}
+
+/**
+ * Decoder family for the model's detection head.
+ *
+ * - `"yolo"`: anchor-free YOLO head with output shape `[1, 4 + nc, N]` —
+ *   covers YOLOv8, v9, v10, v11, v12, v26 detect exports.
+ *
+ * The SDK does **not** auto-detect the head from the model — the caller is
+ * responsible for picking a head that matches their export. Future families
+ * (v5/v6/v7 with `[1, N, 5+nc]`) will be added as new literal members.
+ */
+export declare type DetectorHead = "yolo";
+
+export declare interface DetectorOptions extends OrtSessionOptions {
+    /**
+     * Decoder family for the detection head. Default `"yolo"` covers
+     * YOLOv8/v9/v10/v11/v12/v26.
+     */
+    readonly head?: DetectorHead;
+    /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */
+    readonly labels?: LabelSpec;
+    /** Number of classes — used to validate the supplied labels. */
+    readonly numClasses?: number;
+    /** Model input `[width, height]` for letterboxing. Defaults to `[640, 640]`. */
+    readonly inputSize?: readonly [number, number];
+    /** Default minimum class score to keep a candidate. */
+    readonly confThreshold?: number;
+    /** Default IoU threshold for non-maximum suppression. */
+    readonly iouThreshold?: number;
+    /** Maximum number of detections per image. */
+    readonly maxDetections?: number;
+}
+
+export declare interface DetectorPredictOptions {
+    /** Override the default confidence threshold. */
+    readonly confThreshold?: number;
+    /** Override the default IoU threshold. */
+    readonly iouThreshold?: number;
+    /**
+     * If set, keep only detections whose `classId` is in this list.
+     * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.
+     */
+    readonly classes?: readonly number[];
+}
+
+/**
+ * Convert an HWC BGR uint8 buffer (OpenCV layout) to the SDK's HWC RGB.
+ *
+ * Use when you receive image bytes from `cv2.imencode` over the wire and
+ * want to feed them to the SDK without going through a canvas decode.
+ *
+ * @param bgr Flat BGR Uint8Array of length `width * height * 3`.
+ */
+export declare function fromCv2(bgr: Uint8Array, width: number, height: number): RGBImage;
+
+/** Anything {@link loadImage} accepts as an image input. */
+export declare type ImageInput = string | Blob | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas | ImageBitmap | ImageData | RGBImage;
+
+/** Raised when an input image cannot be decoded into the canonical format. */
+export declare class ImageLoadError extends OrtVisionError {
+}
+
+/** Raised when ONNX Runtime fails while executing a model. */
+export declare class InferenceError extends OrtVisionError {
+}
+
+/** Raised when class labels cannot be resolved from the supplied spec. */
+export declare class LabelMapError extends OrtVisionError {
+}
+
+/**
+ * Class label resolution: presets, lists, dicts, or auto-generated.
+ *
+ * Tasks call {@link resolveLabels} once at construction time to turn whatever
+ * the caller passed (preset name, array, dict, or `null`) into an ordered
+ * array of class names indexed by class id.
+ *
+ * In the browser there is no filesystem, so this module does not load labels
+ * from a path — fetch the file yourself and pass an array.
+ */
+/**
+ * Anything accepted by {@link resolveLabels}.
+ *
+ * - `string[]` / `readonly string[]`: explicit names indexed by class id.
+ * - `Record<number, string>`: sparse mapping (gaps filled with `class_<id>`).
+ * - `string`: a preset name (e.g. `"coco"`).
+ * - `null` / `undefined`: auto-generate `class_0` ... `class_{numClasses-1}`.
+ */
+export declare type LabelSpec = readonly string[] | Record<number, string> | string | null | undefined;
+
+/**
+ * Resize preserving aspect ratio, padding to `(targetWidth, targetHeight)`
+ * with a constant fill color.
+ *
+ * Standard YOLO preprocessing — returning `scale` and `padLeft`/`padTop`
+ * lets callers map detections back to the original image coordinates.
+ */
+export declare function letterbox(image: RGBImage, targetWidth: number, targetHeight: number, fill?: readonly [number, number, number]): LetterboxResult;
+
+export declare interface LetterboxResult {
+    /** The padded image at the target size. */
+    readonly image: RGBImage;
+    /** The factor applied to the original image (`< 1` if downscaled). */
+    readonly scale: number;
+    /** Horizontal padding in pixels (left side; right side has the same or +1). */
+    readonly padLeft: number;
+    /** Vertical padding in pixels (top side). */
+    readonly padTop: number;
+}
+
+/**
+ * Load an image from any supported source into a HWC uint8 RGB array.
+ *
+ * @throws {@link ImageLoadError} if the source cannot be decoded or has an unsupported shape.
+     */
+ export declare function loadImage(source: ImageInput): Promise<RGBImage>;
+
+ /**
+  * Single-channel binary or grayscale mask, laid out row-major.
+  *
+  * `data.length` must equal `width * height`. For binary masks, values are
+  * `0` (background) or `255` (foreground); soft masks may use the full
+  * `[0, 255]` range.
+  */
+ export declare class Mask {
+     readonly data: Uint8Array;
+     readonly width: number;
+     readonly height: number;
+     constructor(data: Uint8Array, width: number, height: number);
+ }
+
+ /**
+  * Per-instance binary masks for a single image.
+  *
+  * Each mask is cropped to its instance's bounding box. To paint masks onto
+  * a full-image canvas, use `xyxy[i]` as the top-left target.
+  */
+ export declare class Masks {
+     readonly data: ReadonlyArray<{
+         readonly data: Uint8Array;
+         readonly width: number;
+         readonly height: number;
+     }>;
+     readonly xyxy: Float32Array;
+     readonly origShape: readonly [number, number];
+     /**
+      * @param data Per-instance binary masks (`Mask` objects from `types.ts`).
+      * @param xyxy Flat `[N, 4]` of bounding-box coordinates in original pixels.
+      * @param origShape `[height, width]` of the original image.
+      */
+     constructor(data: ReadonlyArray<{
+         readonly data: Uint8Array;
+         readonly width: number;
+         readonly height: number;
+     }>, xyxy: Float32Array, origShape: readonly [number, number]);
+     /** Number of instance masks. */
+     get length(): number;
+     /** `[N]` shape of the masks collection. */
+     get shape(): readonly [number];
+     [Symbol.iterator](): Iterator<{
+         readonly data: Uint8Array;
+         readonly width: number;
+         readonly height: number;
+     }>;
+ }
+
+ /** Raised when an ONNX model cannot be loaded into an inference session. */
+ export declare class ModelLoadError extends OrtVisionError {
+ }
+
+ /** Anything `InferenceSession.create` accepts. */
+ export declare type ModelSource = string | ArrayBufferLike | Uint8Array;
+
+ /**
+  * Greedy non-maximum suppression on axis-aligned bounding boxes.
+  *
+  * Mirrors `torchvision.ops.nms` (keeps boxes with the highest score, drops
+  * any subsequent box whose IoU exceeds the threshold).
+  *
+  * @param boxes Flat array of length `4 * N` in xyxy order: `[x1,y1,x2,y2, ...]`.
+  * @param scores Detection score per box, length `N`.
+  * @param iouThreshold Boxes with IoU above this threshold relative to a kept box are suppressed.
+  * @returns Indices of kept boxes, in descending score order.
+  */
+ export declare function nms(boxes: Float32Array, scores: Float32Array, iouThreshold: number): Int32Array;
+
+ /**
+  * Convert a uint8 image to a normalized float32 array (HWC layout preserved).
+  *
+  * Applies `(pixel * scale - mean) / std` channel-wise.
+  */
+ export declare function normalize(image: RGBImage, mean: readonly [number, number, number], std: readonly [number, number, number], scale?: number): Float32Array;
+
+ /**
+  * Wrap an ONNX Runtime Web `InferenceSession` with convenient metadata access.
+  *
+  * The wrapper exposes input/output names, manages execution-provider
+  * selection, and provides a typed {@link OrtSession.run} method.
+  */
+ export declare class OrtSession {
+     private readonly _session;
+     readonly providers: readonly string[];
+     private constructor();
+     /**
+      * Load an ONNX model into an ORT inference session.
+      *
+      * @param model Either a URL string fetched by ORT, or a `Uint8Array`/`ArrayBuffer` containing the model bytes.
+      * @param options Provider list and pass-through `SessionOptions`.
+      * @throws {@link ModelLoadError} if the model cannot be loaded.
+          */
+      static create(model: ModelSource, options?: OrtSessionOptions): Promise<OrtSession>;
+      /** Names of the model's inputs, in declaration order. */
+      get inputNames(): readonly string[];
+      /** Name of the first (and usually only) input. */
+      get inputName(): string;
+      /** Names of the model's outputs, in declaration order. */
+      get outputNames(): readonly string[];
+      /** The underlying `onnxruntime-web` session, for advanced use cases. */
+      get raw(): ort.InferenceSession;
+      /**
+       * Run inference and return all outputs.
+       *
+       * @param feeds Map of input name to `ort.Tensor`. Keys must match {@link inputNames}.
+       * @throws {@link InferenceError} if ORT raises any error during execution.
+           */
+       run(feeds: Record<string, ort.Tensor>): Promise<Record<string, ort.Tensor>>;
+      }
+
+      export declare interface OrtSessionOptions {
+          /** Execution providers in preference order. `undefined` uses {@link DEFAULT_PROVIDERS}. */
+          readonly providers?: readonly string[];
+          /** Optional ORT session options forwarded to `InferenceSession.create`. */
+          readonly sessionOptions?: ort.InferenceSession.SessionOptions;
+      }
+
+      /**
+       * Exceptions raised by the SDK.
+       *
+       * All exceptions inherit from {@link OrtVisionError}, so callers can catch
+       * the base class to handle any SDK-originated failure uniformly.
+       */
+      export declare class OrtVisionError extends Error {
+          constructor(message: string, options?: ErrorOptions);
+      }
+
+      /**
+       * Top-k classification probabilities for a single image.
+       *
+       * Mirrors Ultralytics' `Probs` interface.
+       */
+      export declare class Probs {
+          readonly data: Float32Array;
+          /** @param data `[numClasses]` per-class probabilities, indexed by class id. */
+          constructor(data: Float32Array);
+          /** Number of classes. */
+          get length(): number;
+          /** `[numClasses]` shape of the underlying vector. */
+          get shape(): readonly [number];
+          /** Index of the most probable class. */
+          get top1(): number;
+          /** Probability of the top-1 class. */
+          get top1conf(): number;
+          /** Indices of the top-5 most probable classes, descending. */
+          get top5(): Int32Array;
+          /** Probabilities of the top-5 classes, descending. */
+          get top5conf(): Float32Array;
+          private _topK;
+      }
+
+      /** Raised when a requested execution provider is not available. */
+      export declare class ProviderNotAvailableError extends OrtVisionError {
+      }
+
+      /** Resize an image to `(targetWidth, targetHeight)` using high-quality canvas resampling. */
+      export declare function resize(image: RGBImage, targetWidth: number, targetHeight: number): RGBImage;
+
+      /**
+       * Resolve a labels specification into an ordered array of class names.
+       *
+       * @throws {@link LabelMapError} if the spec is invalid, the preset is unknown,
+           *   or the resolved length disagrees with `numClasses`.
+           */
+       export declare function resolveLabels(spec: LabelSpec, options?: ResolveLabelsOptions): readonly string[];
+
+       export declare interface ResolveLabelsOptions {
+           /**
+            * Expected number of classes.
+            *
+            * - When `spec` is `null`/`undefined`, this is required to auto-generate names.
+            * - When `spec` is provided, it validates that the resolved length matches.
+            */
+           readonly numClasses?: number;
+       }
+
+       /**
+        * Resolve the execution providers to pass to `InferenceSession.create`.
+        *
+        * @param requested Explicit provider list in preference order; `undefined` returns the default.
+        */
+       export declare function resolveProviders(requested?: readonly string[]): string[];
+
+       /**
+        * Public output types returned by the SDK's vision tasks.
+        *
+        * These types form the contract between the SDK and its callers. They mirror
+        * the Python `ort-vision-sdk` output dataclasses 1-to-1.
+        *
+        * Naming is intentionally compatible with the Ultralytics / torchvision idiom
+        * (`cls`, `conf`, `box`, `xyxy`, `xywh`, normalized variants) so code ported
+        * from those projects keeps working with minimal edits. The original verbose
+        * names (`classId`, `className`, `confidence`, `bbox`) are still populated for
+        * backwards compatibility.
+        */
+       /**
+        * HWC RGB uint8 image — the canonical image format used across the SDK.
+        *
+        * `data.length` must equal `width * height * 3`. The buffer is laid out row
+        * by row, top-to-bottom, with each pixel as `[R, G, B]`.
+        */
+       export declare class RGBImage {
+           readonly data: Uint8Array;
+           readonly width: number;
+           readonly height: number;
+           constructor(data: Uint8Array, width: number, height: number);
+       }
+
+       /**
+        * Single segmented instance produced by an instance-segmentation model.
+        *
+        * Mirrors {@link DetectionResult} and adds the per-instance binary mask
+        * plus a "ready-to-display" background-removed crop.
+        */
+       export declare interface SegmentationResult {
+           readonly classId: number;
+           readonly className: string;
+           readonly confidence: number;
+           readonly bbox: BoundingBox;
+           /** Alias for `classId` (Ultralytics-style). */
+           readonly cls: number;
+           /** Alias for `className`. */
+           readonly name: string;
+           /** Alias for `confidence` (Ultralytics-style). */
+           readonly conf: number;
+           /** Alias for `bbox` (Ultralytics-style). */
+           readonly box: BoundingBox;
+           /**
+            * Binary mask cropped to `bbox`. Values are `0` (background) or `255`
+            * (foreground). Empty boxes yield a zero-sized `Mask`.
+            */
+           readonly mask: Mask;
+           /**
+            * The original image cropped to `bbox` with background pixels (where
+            * `mask.data[i] === 0`) zeroed out. Empty boxes yield a zero-sized
+            * `RGBImage`.
+            */
+           readonly segmentedImage: RGBImage;
+       }
+
+       /**
+        * Per-image instance-segmentation envelope (Ultralytics-style `Results`).
+        *
+        * Iterating yields per-instance {@link SegmentationResult} entries. `boxes`
+        * and `masks` mirror Ultralytics' bulk-array views.
+        */
+       export declare class SegmentationResults implements Iterable<SegmentationResult> {
+           readonly boxes: Boxes;
+           readonly masks: Masks;
+           readonly detections: readonly SegmentationResult[];
+           readonly names: Readonly<Record<number, string>>;
+           readonly origImg: RGBImage;
+           readonly origShape: readonly [number, number];
+           readonly path: string | null;
+           readonly speed: Readonly<Record<string, number>>;
+           constructor(boxes: Boxes, masks: Masks, detections: readonly SegmentationResult[], names: Readonly<Record<number, string>>, origImg: RGBImage, origShape: readonly [number, number], path?: string | null, speed?: Readonly<Record<string, number>>);
+           /** Number of surviving instances. */
+           get length(): number;
+           /** Index into the per-instance results. */
+           get(index: number): SegmentationResult | undefined;
+           [Symbol.iterator](): Iterator<SegmentationResult>;
+       }
+
+       /**
+        * Instance segmenter for YOLO seg ONNX models (v8-seg / v11-seg / ...).
+        *
+        * The model is expected to expose two outputs:
+        *
+        * 1. `output0`: `(1, 4 + numClasses + numMaskCoefs, numAnchors)` — per-anchor
+        *    predictions (boxes, class scores, mask coefficients).
+        * 2. `output1`: `(1, numMaskCoefs, maskH, maskW)` — prototype masks.
+        *
+        * `predict()` returns `Promise<SegmentationResults[]>` (length 1 for a
+        * single image), mirroring Ultralytics' API. The envelope exposes:
+        *
+        * - `boxes`: bulk numpy view (`xyxy`, `xywh`, `xyxyn`, `xywhn`, `cls`, `conf`).
+        * - `masks`: per-instance binary masks cropped to each box.
+        * - per-instance {@link SegmentationResult} via iteration.
+        *
+        * @example
+        * ```typescript
+        * const seg = await Segmenter.create("/models/yolov8n-seg.onnx");
+        * const r = (await seg.predict("/images/street.jpg"))[0];
+        * for (const inst of r) {
+        *   console.log(inst.cls, inst.conf, inst.box.xyxy);
+        * }
+        * ```
+        */
+       export declare class Segmenter extends VisionTask {
+           private readonly _head;
+           private readonly _labels;
+           private readonly _names;
+           private readonly _inputSize;
+           private readonly _confThreshold;
+           private readonly _iouThreshold;
+           private readonly _maxDetections;
+           private readonly _maskThreshold;
+           private constructor();
+           /** Load the model and resolve labels. */
+           static create(model: ModelSource, options?: SegmenterOptions): Promise<Segmenter>;
+           /** The decoder family used to interpret the model's output. */
+           get head(): SegmenterHead;
+           /** Class labels indexed by class id. */
+           get labels(): readonly string[];
+           /** Class id → class name dict (matches Ultralytics' `model.names`). */
+           get names(): Readonly<Record<number, string>>;
+           /** Number of classes the model predicts. */
+           get numClasses(): number;
+           /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
+           call(image: ImageInput, options?: SegmenterPredictOptions): Promise<SegmentationResults[]>;
+           /** Run instance segmentation on a single image. */
+           predict(image: ImageInput, options?: SegmenterPredictOptions): Promise<SegmentationResults[]>;
+           private _preprocess;
+           private _splitOutputs;
+           private _buildResult;
+           private _buildBoxes;
+           private _buildMasks;
+       }
+
+       /**
+        * Decoder family for the segmentation head.
+        *
+        * - `"yolo-seg"`: YOLO instance-segmentation head with two outputs —
+        *   `[1, 4 + nc + nm, N]` per-anchor predictions plus `[1, nm, mh, mw]`
+        *   prototype masks. Covers YOLOv8-seg, v11-seg, v26-seg.
+        *
+        * The SDK does **not** auto-detect this — the caller is responsible for
+        * picking a head that matches their export.
+        */
+       export declare type SegmenterHead = "yolo-seg";
+
+       export declare interface SegmenterOptions extends OrtSessionOptions {
+           /**
+            * Decoder family for the segmentation head. Default `"yolo-seg"` covers
+            * YOLOv8-seg/v11-seg/v26-seg.
+            */
+           readonly head?: SegmenterHead;
+           /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */
+           readonly labels?: LabelSpec;
+           /** Number of classes — used to validate the supplied labels. */
+           readonly numClasses?: number;
+           /** Model input `[width, height]` for letterboxing. Defaults to `[640, 640]`. */
+           readonly inputSize?: readonly [number, number];
+           /** Default minimum class score to keep a candidate. */
+           readonly confThreshold?: number;
+           /** Default IoU threshold for non-maximum suppression. */
+           readonly iouThreshold?: number;
+           /** Maximum number of instances per image. */
+           readonly maxDetections?: number;
+           /** Probability cutoff applied to soft masks. Defaults to `0.5`. */
+           readonly maskThreshold?: number;
+       }
+
+       export declare interface SegmenterPredictOptions {
+           readonly confThreshold?: number;
+           readonly iouThreshold?: number;
+           /**
+            * If set, keep only instances whose `classId` is in this list.
+            * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.
+            */
+           readonly classes?: readonly number[];
+       }
+
+       /**
+        * Classification head postprocessing — softmax + top-k.
+        */
+       /** Apply numerically-stable softmax to a 1-D vector of logits. */
+       export declare function softmax(logits: Float32Array | readonly number[]): Float32Array;
+
+       /**
+        * Transpose interleaved HWC data to planar CHW layout.
+        *
+        * @param hwc Source array of length `width * height * channels`.
+        */
+       export declare function toCHW(hwc: Float32Array, width: number, height: number, channels?: number): Float32Array;
+
+       /**
+        * Convert the SDK's HWC RGB image to an HWC BGR `Uint8Array` (OpenCV layout).
+        *
+        * Useful for round-tripping data to a Python OpenCV consumer.
+        */
+       export declare function toCv2(image: RGBImage): Uint8Array;
+
+       /** Convert a uint8 image to a `Float32Array` in `[0, 1]` (HWC layout preserved). */
+       export declare function toFloat32(image: RGBImage, scale?: number): Float32Array;
+
+       /** Wrap a Float32 buffer into an `ort.Tensor`. */
+       export declare function toFloat32Tensor(data: Float32Array, dims: readonly number[]): ort.Tensor;
+
+       /**
+        * Return the top-k entries of a 1-D probability vector, sorted descending.
+        *
+        * @param k Number of entries to return; `null` returns all entries.
+        */
+       export declare function topK(probabilities: Float32Array, k: number | null): TopKResult;
+
+       export declare interface TopKResult {
+           readonly indices: Int32Array;
+           readonly values: Float32Array;
+       }
+
+       /**
+        * Convert an HWC uint8 image to a CHW `Float32Array` scaled to `[0, 1]`.
+        *
+        * Mirrors `torchvision.transforms.ToTensor()` semantics: HWC → CHW,
+        * `uint8 → float32 / 255`. Useful as input to YOLO-style detectors that
+        * don't require ImageNet normalization.
+        *
+        * @returns CHW `Float32Array` of length `width * height * 3`.
+        */
+       export declare function toTensor(image: RGBImage): Float32Array;
+
+       export declare const VERSION: string;
+
+       export declare abstract class VisionTask {
+           protected readonly _session: OrtSession;
+           protected constructor(_session: OrtSession);
+           /** The underlying {@link OrtSession} used to run inference. */
+           get session(): OrtSession;
+       }
+
+       export { }