tempest-react-sdk 0.36.0 → 0.38.0

package/dist/vision/tasks/segmenter.js

@@ -2,13 +2,15 @@ import { Mask as e, RGBImage as t } from "../types.js";
 import { SpeedTimer as n } from "../core/timing.js";
 import { Boxes as r, Masks as i, SegmentationResults as a } from "../results.js";
 import { resolveLabels as o } from "../labels.js";
-import { OrtSession as s } from "../core/session.js";
-import { loadImage as c } from "../io/image.js";
-import { letterbox as l, toCHW as u, toFloat32 as d, toFloat32Tensor as f } from "../preprocess/image.js";
-import { decodeYoloSeg as p } from "../postprocess/segmentation.js";
-import { VisionTask as m } from "./base.js";
+import { detectionNumClasses as s, resolveInputSize as c } from "../core/graph.js";
+import { modelNames as l } from "../core/metadata.js";
+import { OrtSession as u } from "../core/session.js";
+import { loadImage as d } from "../io/image.js";
+import { letterbox as f, toCHW as p, toFloat32 as m, toFloat32Tensor as h } from "../preprocess/image.js";
+import { decodeYoloSeg as g } from "../postprocess/segmentation.js";
+import { VisionTask as _ } from "./base.js";
 //#region src/vision/tasks/segmenter.ts
-var h = class h extends m {
+var v = class v extends _ {
 	_head;
 	_labels;
 	_names;
@@ -23,9 +25,13 @@ var h = class h extends m {
 	static async create(e, t = {}) {
 		let n = t.head ?? "yolo-seg";
 		if (n !== "yolo-seg") throw Error(`Unsupported segmenter head '${n}'. Supported: 'yolo-seg'.`);
-		let r = await s.create(e, t), i = o(t.labels ?? "coco", { numClasses: t.numClasses }), a = {};
+		let r = await u.create(e, t), i = o(t.labels ?? l(r.metadata) ?? "coco", { numClasses: t.numClasses ?? s(r.outputShape) ?? void 0 }), a = {};
 		for (let e = 0; e < i.length; e++) a[e] = i[e];
-		return new h(r, n, i, a, t.inputSize ?? [640, 640], t.confThreshold ?? .25, t.iouThreshold ?? .45, t.maxDetections ?? 300, t.maskThreshold ?? .5);
+		return new v(r, n, i, a, c({
+			graphShape: r.inputShape,
+			requested: t.inputSize,
+			fallback: [640, 640]
+		}), t.confThreshold ?? .25, t.iouThreshold ?? .45, t.maxDetections ?? 300, t.maskThreshold ?? .5);
 	}
 	get head() {
 		return this._head;
@@ -36,6 +42,9 @@ var h = class h extends m {
 	get names() {
 		return this._names;
 	}
+	get inputSize() {
+		return this._inputSize;
+	}
 	get numClasses() {
 		return this._labels.length;
 	}
@@ -43,35 +52,35 @@ var h = class h extends m {
 		return this.predict(e, t);
 	}
 	async predict(e, t = {}) {
-		let r = new n(), i = typeof e == "string" ? e : null, o = await c(e);
+		let r = new n(), i = typeof e == "string" ? e : null, o = await d(e);
 		r.stage("load");
-		let { tensor: s, scale: l, padLeft: u, padTop: d } = this._preprocess(o);
+		let { tensor: s, scale: c, padLeft: l, padTop: u } = this._preprocess(o);
 		r.stage("preprocess");
 		let f = await this._session.run({ [this._session.inputName]: s });
 		r.stage("inference");
-		let { perAnchor: m, prototypes: h } = this._splitOutputs(f), g = p(m.data, m.dims, h.data, h.dims, {
+		let { perAnchor: p, prototypes: m } = this._splitOutputs(f), h = g(p.data, p.dims, m.data, m.dims, {
 			numClasses: this._labels.length,
 			inputWidth: this._inputSize[0],
 			inputHeight: this._inputSize[1],
 			originalWidth: o.width,
 			originalHeight: o.height,
-			padLeft: u,
-			padTop: d,
-			scale: l,
+			padLeft: l,
+			padTop: u,
+			scale: c,
 			confThreshold: t.confThreshold ?? this._confThreshold,
 			iouThreshold: t.iouThreshold ?? this._iouThreshold,
 			maxDetections: this._maxDetections,
 			maskThreshold: this._maskThreshold
-		}), _ = (t.classes === void 0 ? g : (() => {
+		}), _ = (t.classes === void 0 ? h : (() => {
 			let e = new Set(t.classes);
-			return g.filter((t) => e.has(t.classId));
+			return h.filter((t) => e.has(t.classId));
 		})()).map((e) => this._buildResult(o, e.bbox, e.classId, e.confidence, e.mask)), v = [o.height, o.width], y = this._buildBoxes(_, v), b = this._buildMasks(_, v);
 		return r.stage("postprocess"), [new a(y, b, _, this._names, o, v, i, r.speed())];
 	}
 	_preprocess(e) {
-		let [t, n] = this._inputSize, r = l(e, t, n);
+		let [t, n] = this._inputSize, r = f(e, t, n);
 		return {
-			tensor: f(u(d(r.image), r.image.width, r.image.height, 3), [
+			tensor: h(p(m(r.image), r.image.width, r.image.height, 3), [
 				1,
 				3,
 				r.image.height,
@@ -146,6 +155,6 @@ var h = class h extends m {
 	}
 };
 //#endregion
-export { h as Segmenter };
+export { v as Segmenter };
 
 //# sourceMappingURL=segmenter.js.map

package/dist/vision/tasks/segmenter.js.map

@@ -1 +1 @@
-{"version":3,"file":"segmenter.js","names":[],"sources":["../../../src/vision/tasks/segmenter.ts"],"sourcesContent":["/**\n * Instance-segmentation task using YOLO seg ONNX models (v8-seg / v11-seg / ...).\n */\n\nimport type * as ort from \"onnxruntime-web\";\n\nimport { type ModelSource, type OrtSessionOptions, OrtSession } from \"../core/session\";\nimport { SpeedTimer } from \"../core/timing\";\nimport { type ImageInput, loadImage } from \"../io/image\";\nimport { type LabelSpec, resolveLabels } from \"../labels\";\nimport { decodeYoloSeg } from \"../postprocess/segmentation\";\nimport { letterbox, toCHW, toFloat32, toFloat32Tensor } from \"../preprocess/image\";\nimport { Boxes, Masks, SegmentationResults } from \"../results\";\nimport { VisionTask } from \"./base\";\nimport { type BoundingBox, type SegmentationResult, Mask, RGBImage } from \"../types\";\n\n/**\n * Decoder family for the segmentation head.\n *\n * - `\"yolo-seg\"`: YOLO instance-segmentation head with two outputs —\n *   `[1, 4 + nc + nm, N]` per-anchor predictions plus `[1, nm, mh, mw]`\n *   prototype masks. Covers YOLOv8-seg, v11-seg, v26-seg.\n *\n * The SDK does **not** auto-detect this — the caller is responsible for\n * picking a head that matches their export.\n */\nexport type SegmenterHead = \"yolo-seg\";\n\nexport interface SegmenterOptions extends OrtSessionOptions {\n    /**\n     * Decoder family for the segmentation head. Default `\"yolo-seg\"` covers\n     * YOLOv8-seg/v11-seg/v26-seg.\n     */\n    readonly head?: SegmenterHead;\n    /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */\n    readonly labels?: LabelSpec;\n    /** Number of classes — used to validate the supplied labels. */\n    readonly numClasses?: number;\n    /** Model input `[width, height]` for letterboxing. Defaults to `[640, 640]`. */\n    readonly inputSize?: readonly [number, number];\n    /** Default minimum class score to keep a candidate. */\n    readonly confThreshold?: number;\n    /** Default IoU threshold for non-maximum suppression. */\n    readonly iouThreshold?: number;\n    /** Maximum number of instances per image. */\n    readonly maxDetections?: number;\n    /** Probability cutoff applied to soft masks. Defaults to `0.5`. */\n    readonly maskThreshold?: number;\n}\n\nexport interface SegmenterPredictOptions {\n    readonly confThreshold?: number;\n    readonly iouThreshold?: number;\n    /**\n     * If set, keep only instances whose `classId` is in this list.\n     * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.\n     */\n    readonly classes?: readonly number[];\n}\n\n/**\n * Instance segmenter for YOLO seg ONNX models (v8-seg / v11-seg / ...).\n *\n * The model is expected to expose two outputs:\n *\n * 1. `output0`: `(1, 4 + numClasses + numMaskCoefs, numAnchors)` — per-anchor\n *    predictions (boxes, class scores, mask coefficients).\n * 2. `output1`: `(1, numMaskCoefs, maskH, maskW)` — prototype masks.\n *\n * `predict()` returns `Promise<SegmentationResults[]>` (length 1 for a\n * single image), mirroring Ultralytics' API. The envelope exposes:\n *\n * - `boxes`: bulk numpy view (`xyxy`, `xywh`, `xyxyn`, `xywhn`, `cls`, `conf`).\n * - `masks`: per-instance binary masks cropped to each box.\n * - per-instance {@link SegmentationResult} via iteration.\n *\n * @example\n * ```typescript\n * const seg = await Segmenter.create(\"/models/yolov8n-seg.onnx\");\n * const r = (await seg.predict(\"/images/street.jpg\"))[0];\n * for (const inst of r) {\n *   console.log(inst.cls, inst.conf, inst.box.xyxy);\n * }\n * ```\n */\nexport class Segmenter extends VisionTask {\n    private constructor(\n        session: OrtSession,\n        private readonly _head: SegmenterHead,\n        private readonly _labels: readonly string[],\n        private readonly _names: Readonly<Record<number, string>>,\n        private readonly _inputSize: readonly [number, number],\n        private readonly _confThreshold: number,\n        private readonly _iouThreshold: number,\n        private readonly _maxDetections: number,\n        private readonly _maskThreshold: number,\n    ) {\n        super(session);\n    }\n\n    /** Load the model and resolve labels. */\n    static async create(model: ModelSource, options: SegmenterOptions = {}): Promise<Segmenter> {\n        const head: SegmenterHead = options.head ?? \"yolo-seg\";\n        if (head !== \"yolo-seg\") {\n            throw new Error(`Unsupported segmenter head '${head}'. Supported: 'yolo-seg'.`);\n        }\n        const session = await OrtSession.create(model, options);\n        const labels = resolveLabels(options.labels ?? \"coco\", {\n            numClasses: options.numClasses,\n        });\n        const names: Record<number, string> = {};\n        for (let i = 0; i < labels.length; i++) {\n            names[i] = labels[i] as string;\n        }\n        return new Segmenter(\n            session,\n            head,\n            labels,\n            names,\n            options.inputSize ?? [640, 640],\n            options.confThreshold ?? 0.25,\n            options.iouThreshold ?? 0.45,\n            options.maxDetections ?? 300,\n            options.maskThreshold ?? 0.5,\n        );\n    }\n\n    /** The decoder family used to interpret the model's output. */\n    get head(): SegmenterHead {\n        return this._head;\n    }\n\n    /** Class labels indexed by class id. */\n    get labels(): readonly string[] {\n        return this._labels;\n    }\n\n    /** Class id → class name dict (matches Ultralytics' `model.names`). */\n    get names(): Readonly<Record<number, string>> {\n        return this._names;\n    }\n\n    /** Number of classes the model predicts. */\n    get numClasses(): number {\n        return this._labels.length;\n    }\n\n    /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */\n    async call(\n        image: ImageInput,\n        options: SegmenterPredictOptions = {},\n    ): Promise<SegmentationResults[]> {\n        return this.predict(image, options);\n    }\n\n    /** Run instance segmentation on a single image. */\n    async predict(\n        image: ImageInput,\n        options: SegmenterPredictOptions = {},\n    ): Promise<SegmentationResults[]> {\n        const timer = new SpeedTimer();\n        const path = typeof image === \"string\" ? image : null;\n        const original = await loadImage(image);\n        timer.stage(\"load\");\n        const { tensor, scale, padLeft, padTop } = this._preprocess(original);\n        timer.stage(\"preprocess\");\n        const outputs = await this._session.run({ [this._session.inputName]: tensor });\n        timer.stage(\"inference\");\n\n        const { perAnchor, prototypes } = this._splitOutputs(outputs);\n\n        const decodedAll = decodeYoloSeg(\n            perAnchor.data as Float32Array,\n            perAnchor.dims,\n            prototypes.data as Float32Array,\n            prototypes.dims,\n            {\n                numClasses: this._labels.length,\n                inputWidth: this._inputSize[0],\n                inputHeight: this._inputSize[1],\n                originalWidth: original.width,\n                originalHeight: original.height,\n                padLeft,\n                padTop,\n                scale,\n                confThreshold: options.confThreshold ?? this._confThreshold,\n                iouThreshold: options.iouThreshold ?? this._iouThreshold,\n                maxDetections: this._maxDetections,\n                maskThreshold: this._maskThreshold,\n            },\n        );\n\n        const decoded =\n            options.classes !== undefined\n                ? (() => {\n                      const allowed = new Set(options.classes);\n                      return decodedAll.filter((d) => allowed.has(d.classId));\n                  })()\n                : decodedAll;\n\n        const detections = decoded.map((d) =>\n            this._buildResult(original, d.bbox, d.classId, d.confidence, d.mask),\n        );\n\n        const orig: readonly [number, number] = [original.height, original.width];\n        const boxes = this._buildBoxes(detections, orig);\n        const masks = this._buildMasks(detections, orig);\n        timer.stage(\"postprocess\");\n        return [\n            new SegmentationResults(\n                boxes,\n                masks,\n                detections,\n                this._names,\n                original,\n                orig,\n                path,\n                timer.speed(),\n            ),\n        ];\n    }\n\n    private _preprocess(image: RGBImage): {\n        tensor: ort.Tensor;\n        scale: number;\n        padLeft: number;\n        padTop: number;\n    } {\n        const [tw, th] = this._inputSize;\n        const lb = letterbox(image, tw, th);\n        const f32 = toFloat32(lb.image);\n        const chw = toCHW(f32, lb.image.width, lb.image.height, 3);\n        return {\n            tensor: toFloat32Tensor(chw, [1, 3, lb.image.height, lb.image.width]),\n            scale: lb.scale,\n            padLeft: lb.padLeft,\n            padTop: lb.padTop,\n        };\n    }\n\n    private _splitOutputs(outputs: Record<string, ort.Tensor>): {\n        perAnchor: ort.Tensor;\n        prototypes: ort.Tensor;\n    } {\n        let perAnchor: ort.Tensor | undefined;\n        let prototypes: ort.Tensor | undefined;\n        for (const name of this._session.outputNames) {\n            const t = outputs[name];\n            if (t === undefined) continue;\n            if (t.dims.length === 3 && perAnchor === undefined) {\n                perAnchor = t;\n            } else if (t.dims.length === 4 && prototypes === undefined) {\n                prototypes = t;\n            }\n        }\n        if (perAnchor === undefined || prototypes === undefined) {\n            const shapes = this._session.outputNames.map(\n                (n) => `${n}: ${JSON.stringify(outputs[n]?.dims ?? [])}`,\n            );\n            throw new Error(\n                `Segmenter expected one 3-D and one 4-D output, got [${shapes.join(\", \")}].`,\n            );\n        }\n        return { perAnchor, prototypes };\n    }\n\n    private _buildResult(\n        original: RGBImage,\n        bbox: BoundingBox,\n        classId: number,\n        confidence: number,\n        mask: Mask,\n    ): SegmentationResult {\n        const [x1, y1, x2, y2] = bbox.asIntXyxy();\n        const cx1 = Math.max(0, x1);\n        const cy1 = Math.max(0, y1);\n        const cx2 = Math.min(original.width, x2);\n        const cy2 = Math.min(original.height, y2);\n\n        let segmentedImage: RGBImage;\n        let finalMask = mask;\n        if (cx2 > cx1 && cy2 > cy1 && mask.data.length > 0) {\n            const cropW = cx2 - cx1;\n            const cropH = cy2 - cy1;\n            const mw = Math.min(mask.width, cropW);\n            const mh = Math.min(mask.height, cropH);\n            const segData = new Uint8Array(mw * mh * 3);\n            for (let row = 0; row < mh; row++) {\n                const srcRowOffset = ((cy1 + row) * original.width + cx1) * 3;\n                const dstRowOffset = row * mw * 3;\n                const maskRowOffset = row * mask.width;\n                for (let col = 0; col < mw; col++) {\n                    const m = mask.data[maskRowOffset + col];\n                    if (m !== 0) {\n                        const s = srcRowOffset + col * 3;\n                        const d = dstRowOffset + col * 3;\n                        segData[d] = original.data[s];\n                        segData[d + 1] = original.data[s + 1];\n                        segData[d + 2] = original.data[s + 2];\n                    }\n                }\n            }\n            segmentedImage = new RGBImage(segData, mw, mh);\n            if (mw !== mask.width || mh !== mask.height) {\n                const trimmed = new Uint8Array(mw * mh);\n                for (let row = 0; row < mh; row++) {\n                    trimmed.set(\n                        mask.data.subarray(row * mask.width, row * mask.width + mw),\n                        row * mw,\n                    );\n                }\n                finalMask = new Mask(trimmed, mw, mh);\n            }\n        } else {\n            finalMask = new Mask(new Uint8Array(0), 0, 0);\n            segmentedImage = new RGBImage(new Uint8Array(0), 0, 0);\n        }\n\n        const className = this._names[classId] ?? `class_${classId}`;\n\n        return {\n            classId,\n            className,\n            confidence,\n            bbox,\n            cls: classId,\n            name: className,\n            conf: confidence,\n            box: bbox,\n            mask: finalMask,\n            segmentedImage,\n        };\n    }\n\n    private _buildBoxes(\n        detections: readonly SegmentationResult[],\n        origShape: readonly [number, number],\n    ): Boxes {\n        const n = detections.length;\n        const xyxy = new Float32Array(n * 4);\n        const cls = new Int32Array(n);\n        const conf = new Float32Array(n);\n        for (let i = 0; i < n; i++) {\n            const d = detections[i] as SegmentationResult;\n            xyxy[i * 4] = d.bbox.x1;\n            xyxy[i * 4 + 1] = d.bbox.y1;\n            xyxy[i * 4 + 2] = d.bbox.x2;\n            xyxy[i * 4 + 3] = d.bbox.y2;\n            cls[i] = d.classId;\n            conf[i] = d.confidence;\n        }\n        return new Boxes(xyxy, cls, conf, origShape);\n    }\n\n    private _buildMasks(\n        detections: readonly SegmentationResult[],\n        origShape: readonly [number, number],\n    ): Masks {\n        const xyxy = new Float32Array(detections.length * 4);\n        for (let i = 0; i < detections.length; i++) {\n            const d = detections[i] as SegmentationResult;\n            xyxy[i * 4] = d.bbox.x1;\n            xyxy[i * 4 + 1] = d.bbox.y1;\n            xyxy[i * 4 + 2] = d.bbox.x2;\n            xyxy[i * 4 + 3] = d.bbox.y2;\n        }\n        return new Masks(\n            detections.map((d) => d.mask),\n            xyxy,\n            origShape,\n        );\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"segmenter.js","names":[],"sources":["../../../src/vision/tasks/segmenter.ts"],"sourcesContent":["/**\n * Instance-segmentation task using YOLO seg ONNX models (v8-seg / v11-seg / ...).\n */\n\nimport type * as ort from \"onnxruntime-web\";\n\nimport { type ModelSource, type OrtSessionOptions, OrtSession } from \"../core/session\";\nimport { SpeedTimer } from \"../core/timing\";\n\nimport { type ImageInput, loadImage } from \"../io/image\";\nimport { detectionNumClasses, resolveInputSize } from \"../core/graph\";\nimport { modelNames } from \"../core/metadata\";\nimport { type LabelSpec, resolveLabels } from \"../labels\";\nimport { decodeYoloSeg } from \"../postprocess/segmentation\";\nimport { letterbox, toCHW, toFloat32, toFloat32Tensor } from \"../preprocess/image\";\nimport { Boxes, Masks, SegmentationResults } from \"../results\";\nimport { VisionTask } from \"./base\";\nimport { type BoundingBox, type SegmentationResult, Mask, RGBImage } from \"../types\";\n\n/**\n * Decoder family for the segmentation head.\n *\n * - `\"yolo-seg\"`: YOLO instance-segmentation head with two outputs —\n *   `[1, 4 + nc + nm, N]` per-anchor predictions plus `[1, nm, mh, mw]`\n *   prototype masks. Covers YOLOv8-seg, v11-seg, v26-seg.\n *\n * The SDK does **not** auto-detect this — the caller is responsible for\n * picking a head that matches their export.\n */\nexport type SegmenterHead = \"yolo-seg\";\n\nexport interface SegmenterOptions extends OrtSessionOptions {\n    /**\n     * Decoder family for the segmentation head. Default `\"yolo-seg\"` covers\n     * YOLOv8-seg/v11-seg/v26-seg.\n     */\n    readonly head?: SegmenterHead;\n    /** Class label spec — see {@link resolveLabels}. Defaults to the COCO 80-class preset. */\n    readonly labels?: LabelSpec;\n    /** Number of classes — used to validate the supplied labels. */\n    readonly numClasses?: number;\n    /**\n     * Model input `[width, height]` in pixels for letterboxing.\n     *\n     * Only used when the model's graph leaves its spatial axes dynamic: a graph\n     * that declares a static size always wins, since that is the only shape ONNX\n     * Runtime will accept. Defaults to `[640, 640]`.\n     */\n    readonly inputSize?: readonly [number, number];\n    /** Default minimum class score to keep a candidate. */\n    readonly confThreshold?: number;\n    /** Default IoU threshold for non-maximum suppression. */\n    readonly iouThreshold?: number;\n    /** Maximum number of instances per image. */\n    readonly maxDetections?: number;\n    /** Probability cutoff applied to soft masks. Defaults to `0.5`. */\n    readonly maskThreshold?: number;\n}\n\nexport interface SegmenterPredictOptions {\n    readonly confThreshold?: number;\n    readonly iouThreshold?: number;\n    /**\n     * If set, keep only instances whose `classId` is in this list.\n     * Mirrors Ultralytics' `model.predict(img, classes=[0, 16])`.\n     */\n    readonly classes?: readonly number[];\n}\n\n/**\n * Instance segmenter for YOLO seg ONNX models (v8-seg / v11-seg / ...).\n *\n * The model is expected to expose two outputs:\n *\n * 1. `output0`: `(1, 4 + numClasses + numMaskCoefs, numAnchors)` — per-anchor\n *    predictions (boxes, class scores, mask coefficients).\n * 2. `output1`: `(1, numMaskCoefs, maskH, maskW)` — prototype masks.\n *\n * `predict()` returns `Promise<SegmentationResults[]>` (length 1 for a\n * single image), mirroring Ultralytics' API. The envelope exposes:\n *\n * - `boxes`: bulk numpy view (`xyxy`, `xywh`, `xyxyn`, `xywhn`, `cls`, `conf`).\n * - `masks`: per-instance binary masks cropped to each box.\n * - per-instance {@link SegmentationResult} via iteration.\n *\n * @example\n * ```typescript\n * const seg = await Segmenter.create(\"/models/yolov8n-seg.onnx\");\n * const r = (await seg.predict(\"/images/street.jpg\"))[0];\n * for (const inst of r) {\n *   console.log(inst.cls, inst.conf, inst.box.xyxy);\n * }\n * ```\n */\nexport class Segmenter extends VisionTask {\n    private constructor(\n        session: OrtSession,\n        private readonly _head: SegmenterHead,\n        private readonly _labels: readonly string[],\n        private readonly _names: Readonly<Record<number, string>>,\n        private readonly _inputSize: readonly [number, number],\n        private readonly _confThreshold: number,\n        private readonly _iouThreshold: number,\n        private readonly _maxDetections: number,\n        private readonly _maskThreshold: number,\n    ) {\n        super(session);\n    }\n\n    /** Load the model and resolve labels. */\n    static async create(model: ModelSource, options: SegmenterOptions = {}): Promise<Segmenter> {\n        const head: SegmenterHead = options.head ?? \"yolo-seg\";\n        if (head !== \"yolo-seg\") {\n            throw new Error(`Unsupported segmenter head '${head}'. Supported: 'yolo-seg'.`);\n        }\n        const session = await OrtSession.create(model, options);\n        const labels = resolveLabels(options.labels ?? modelNames(session.metadata) ?? \"coco\", {\n            numClasses: options.numClasses ?? detectionNumClasses(session.outputShape) ?? undefined,\n        });\n        const names: Record<number, string> = {};\n        for (let i = 0; i < labels.length; i++) {\n            names[i] = labels[i] as string;\n        }\n        return new Segmenter(\n            session,\n            head,\n            labels,\n            names,\n            resolveInputSize({\n                graphShape: session.inputShape,\n                requested: options.inputSize,\n                fallback: [640, 640],\n            }),\n            options.confThreshold ?? 0.25,\n            options.iouThreshold ?? 0.45,\n            options.maxDetections ?? 300,\n            options.maskThreshold ?? 0.5,\n        );\n    }\n\n    /** The decoder family used to interpret the model's output. */\n    get head(): SegmenterHead {\n        return this._head;\n    }\n\n    /** Class labels indexed by class id. */\n    get labels(): readonly string[] {\n        return this._labels;\n    }\n\n    /** Class id → class name dict (matches Ultralytics' `model.names`). */\n    get names(): Readonly<Record<number, string>> {\n        return this._names;\n    }\n\n    /**\n     * The `[width, height]` this task preprocesses to.\n     *\n     * Resolved at creation time from the model's graph when it declares a static\n     * input, so reading it back tells you the resolution inference really runs at\n     * — not merely what was requested.\n     */\n    get inputSize(): readonly [number, number] {\n        return this._inputSize;\n    }\n\n    /** Number of classes the model predicts. */\n    get numClasses(): number {\n        return this._labels.length;\n    }\n\n    /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */\n    async call(\n        image: ImageInput,\n        options: SegmenterPredictOptions = {},\n    ): Promise<SegmentationResults[]> {\n        return this.predict(image, options);\n    }\n\n    /** Run instance segmentation on a single image. */\n    async predict(\n        image: ImageInput,\n        options: SegmenterPredictOptions = {},\n    ): Promise<SegmentationResults[]> {\n        const timer = new SpeedTimer();\n        const path = typeof image === \"string\" ? image : null;\n        const original = await loadImage(image);\n        timer.stage(\"load\");\n        const { tensor, scale, padLeft, padTop } = this._preprocess(original);\n        timer.stage(\"preprocess\");\n        const outputs = await this._session.run({ [this._session.inputName]: tensor });\n        timer.stage(\"inference\");\n\n        const { perAnchor, prototypes } = this._splitOutputs(outputs);\n\n        const decodedAll = decodeYoloSeg(\n            perAnchor.data as Float32Array,\n            perAnchor.dims,\n            prototypes.data as Float32Array,\n            prototypes.dims,\n            {\n                numClasses: this._labels.length,\n                inputWidth: this._inputSize[0],\n                inputHeight: this._inputSize[1],\n                originalWidth: original.width,\n                originalHeight: original.height,\n                padLeft,\n                padTop,\n                scale,\n                confThreshold: options.confThreshold ?? this._confThreshold,\n                iouThreshold: options.iouThreshold ?? this._iouThreshold,\n                maxDetections: this._maxDetections,\n                maskThreshold: this._maskThreshold,\n            },\n        );\n\n        const decoded =\n            options.classes !== undefined\n                ? (() => {\n                      const allowed = new Set(options.classes);\n                      return decodedAll.filter((d) => allowed.has(d.classId));\n                  })()\n                : decodedAll;\n\n        const detections = decoded.map((d) =>\n            this._buildResult(original, d.bbox, d.classId, d.confidence, d.mask),\n        );\n\n        const orig: readonly [number, number] = [original.height, original.width];\n        const boxes = this._buildBoxes(detections, orig);\n        const masks = this._buildMasks(detections, orig);\n        timer.stage(\"postprocess\");\n        return [\n            new SegmentationResults(\n                boxes,\n                masks,\n                detections,\n                this._names,\n                original,\n                orig,\n                path,\n                timer.speed(),\n            ),\n        ];\n    }\n\n    private _preprocess(image: RGBImage): {\n        tensor: ort.Tensor;\n        scale: number;\n        padLeft: number;\n        padTop: number;\n    } {\n        const [tw, th] = this._inputSize;\n        const lb = letterbox(image, tw, th);\n        const f32 = toFloat32(lb.image);\n        const chw = toCHW(f32, lb.image.width, lb.image.height, 3);\n        return {\n            tensor: toFloat32Tensor(chw, [1, 3, lb.image.height, lb.image.width]),\n            scale: lb.scale,\n            padLeft: lb.padLeft,\n            padTop: lb.padTop,\n        };\n    }\n\n    private _splitOutputs(outputs: Record<string, ort.Tensor>): {\n        perAnchor: ort.Tensor;\n        prototypes: ort.Tensor;\n    } {\n        let perAnchor: ort.Tensor | undefined;\n        let prototypes: ort.Tensor | undefined;\n        for (const name of this._session.outputNames) {\n            const t = outputs[name];\n            if (t === undefined) continue;\n            if (t.dims.length === 3 && perAnchor === undefined) {\n                perAnchor = t;\n            } else if (t.dims.length === 4 && prototypes === undefined) {\n                prototypes = t;\n            }\n        }\n        if (perAnchor === undefined || prototypes === undefined) {\n            const shapes = this._session.outputNames.map(\n                (n) => `${n}: ${JSON.stringify(outputs[n]?.dims ?? [])}`,\n            );\n            throw new Error(\n                `Segmenter expected one 3-D and one 4-D output, got [${shapes.join(\", \")}].`,\n            );\n        }\n        return { perAnchor, prototypes };\n    }\n\n    private _buildResult(\n        original: RGBImage,\n        bbox: BoundingBox,\n        classId: number,\n        confidence: number,\n        mask: Mask,\n    ): SegmentationResult {\n        const [x1, y1, x2, y2] = bbox.asIntXyxy();\n        const cx1 = Math.max(0, x1);\n        const cy1 = Math.max(0, y1);\n        const cx2 = Math.min(original.width, x2);\n        const cy2 = Math.min(original.height, y2);\n\n        let segmentedImage: RGBImage;\n        let finalMask = mask;\n        if (cx2 > cx1 && cy2 > cy1 && mask.data.length > 0) {\n            const cropW = cx2 - cx1;\n            const cropH = cy2 - cy1;\n            const mw = Math.min(mask.width, cropW);\n            const mh = Math.min(mask.height, cropH);\n            const segData = new Uint8Array(mw * mh * 3);\n            for (let row = 0; row < mh; row++) {\n                const srcRowOffset = ((cy1 + row) * original.width + cx1) * 3;\n                const dstRowOffset = row * mw * 3;\n                const maskRowOffset = row * mask.width;\n                for (let col = 0; col < mw; col++) {\n                    const m = mask.data[maskRowOffset + col];\n                    if (m !== 0) {\n                        const s = srcRowOffset + col * 3;\n                        const d = dstRowOffset + col * 3;\n                        segData[d] = original.data[s];\n                        segData[d + 1] = original.data[s + 1];\n                        segData[d + 2] = original.data[s + 2];\n                    }\n                }\n            }\n            segmentedImage = new RGBImage(segData, mw, mh);\n            if (mw !== mask.width || mh !== mask.height) {\n                const trimmed = new Uint8Array(mw * mh);\n                for (let row = 0; row < mh; row++) {\n                    trimmed.set(\n                        mask.data.subarray(row * mask.width, row * mask.width + mw),\n                        row * mw,\n                    );\n                }\n                finalMask = new Mask(trimmed, mw, mh);\n            }\n        } else {\n            finalMask = new Mask(new Uint8Array(0), 0, 0);\n            segmentedImage = new RGBImage(new Uint8Array(0), 0, 0);\n        }\n\n        const className = this._names[classId] ?? `class_${classId}`;\n\n        return {\n            classId,\n            className,\n            confidence,\n            bbox,\n            cls: classId,\n            name: className,\n            conf: confidence,\n            box: bbox,\n            mask: finalMask,\n            segmentedImage,\n        };\n    }\n\n    private _buildBoxes(\n        detections: readonly SegmentationResult[],\n        origShape: readonly [number, number],\n    ): Boxes {\n        const n = detections.length;\n        const xyxy = new Float32Array(n * 4);\n        const cls = new Int32Array(n);\n        const conf = new Float32Array(n);\n        for (let i = 0; i < n; i++) {\n            const d = detections[i] as SegmentationResult;\n            xyxy[i * 4] = d.bbox.x1;\n            xyxy[i * 4 + 1] = d.bbox.y1;\n            xyxy[i * 4 + 2] = d.bbox.x2;\n            xyxy[i * 4 + 3] = d.bbox.y2;\n            cls[i] = d.classId;\n            conf[i] = d.confidence;\n        }\n        return new Boxes(xyxy, cls, conf, origShape);\n    }\n\n    private _buildMasks(\n        detections: readonly SegmentationResult[],\n        origShape: readonly [number, number],\n    ): Masks {\n        const xyxy = new Float32Array(detections.length * 4);\n        for (let i = 0; i < detections.length; i++) {\n            const d = detections[i] as SegmentationResult;\n            xyxy[i * 4] = d.bbox.x1;\n            xyxy[i * 4 + 1] = d.bbox.y1;\n            xyxy[i * 4 + 2] = d.bbox.x2;\n            xyxy[i * 4 + 3] = d.bbox.y2;\n        }\n        return new Masks(\n            detections.map((d) => d.mask),\n            xyxy,\n            origShape,\n        );\n    }\n}\n"],"mappings":"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"}

package/dist/vision.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./vision/use-camera-stream.cjs"),t=require("./vision/core/exceptions.cjs"),n=require("./vision/types.cjs"),r=require("./vision/core/timing.cjs"),i=require("./vision/results.cjs"),a=require("./vision/labels.cjs"),o=require("./vision/core/providers.cjs"),s=require("./vision/core/session.cjs"),c=require("./vision/io/image.cjs"),l=require("./vision/preprocess/image.cjs"),u=require("./vision/postprocess/classification.cjs"),d=require("./vision/postprocess/detection.cjs"),f=require("./vision/postprocess/segmentation.cjs"),p=require("./vision/tasks/base.cjs"),m=require("./vision/tasks/classifier.cjs"),h=require("./vision/tasks/detector.cjs"),g=require("./vision/tasks/segmenter.cjs"),_=require("./vision/index.cjs"),v=require("./vision/luminance.cjs"),y=require("./vision/use-live-luminance.cjs");exports.BoundingBox=n.BoundingBox,exports.Boxes=i.Boxes,exports.COCO_CLASSES=a.COCO_CLASSES,exports.ClassificationResults=i.ClassificationResults,exports.Classifier=m.Classifier,exports.DEFAULT_PROVIDERS=o.DEFAULT_PROVIDERS,exports.DetectionResults=i.DetectionResults,exports.Detector=h.Detector,exports.ImageLoadError=t.ImageLoadError,exports.InferenceError=t.InferenceError,exports.LUMINANCE_SAMPLE_MAX_EDGE=v.LUMINANCE_SAMPLE_MAX_EDGE,exports.LabelMapError=t.LabelMapError,exports.LowLuminanceError=v.LowLuminanceError,exports.Mask=n.Mask,exports.Masks=i.Masks,exports.ModelLoadError=t.ModelLoadError,exports.OrtSession=s.OrtSession,exports.OrtVisionError=t.OrtVisionError,exports.Probs=i.Probs,exports.ProviderNotAvailableError=t.ProviderNotAvailableError,exports.RGBImage=n.RGBImage,exports.SegmentationResults=i.SegmentationResults,exports.Segmenter=g.Segmenter,exports.SpeedTimer=r.SpeedTimer,exports.VERSION=_.VERSION,exports.VisionTask=p.VisionTask,exports.batchedNms=d.batchedNms,exports.computeImageLuminance=v.computeImageLuminance,exports.decodeYolo=d.decodeYolo,exports.decodeYoloAnchors=d.decodeYoloAnchors,exports.decodeYoloSeg=f.decodeYoloSeg,exports.decodeYoloV8=d.decodeYoloV8,exports.decodeYoloV8Anchors=d.decodeYoloV8Anchors,exports.decodeYoloV8Seg=f.decodeYoloV8Seg,exports.fromCv2=l.fromCv2,exports.isLuminanceAcceptable=v.isLuminanceAcceptable,exports.letterbox=l.letterbox,exports.loadImage=c.loadImage,exports.nms=d.nms,exports.normalize=l.normalize,exports.resize=l.resize,exports.resolveLabels=a.resolveLabels,exports.resolveProviders=o.resolveProviders,exports.softmax=u.softmax,exports.toCHW=l.toCHW,exports.toCv2=l.toCv2,exports.toFloat32=l.toFloat32,exports.toFloat32Tensor=l.toFloat32Tensor,exports.toTensor=l.toTensor,exports.topK=u.topK,exports.useCameraStream=e.useCameraStream,exports.useLiveLuminance=y.useLiveLuminance;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./vision/use-camera-stream.cjs"),t=require("./vision/core/exceptions.cjs"),n=require("./vision/types.cjs"),r=require("./vision/core/timing.cjs"),i=require("./vision/results.cjs"),a=require("./vision/labels.cjs"),o=require("./vision/core/graph.cjs"),s=require("./vision/core/metadata.cjs"),c=require("./vision/core/providers.cjs"),l=require("./vision/core/session.cjs"),u=require("./vision/io/image.cjs"),d=require("./vision/preprocess/image.cjs"),f=require("./vision/postprocess/classification.cjs"),p=require("./vision/postprocess/detection.cjs"),m=require("./vision/postprocess/segmentation.cjs"),h=require("./vision/tasks/base.cjs"),g=require("./vision/tasks/classifier.cjs"),_=require("./vision/tasks/detector.cjs"),v=require("./vision/tasks/segmenter.cjs"),y=require("./vision/index.cjs"),b=require("./vision/luminance.cjs"),x=require("./vision/use-live-luminance.cjs");exports.BoundingBox=n.BoundingBox,exports.Boxes=i.Boxes,exports.COCO_CLASSES=a.COCO_CLASSES,exports.ClassificationResults=i.ClassificationResults,exports.Classifier=g.Classifier,exports.DEFAULT_PROVIDERS=c.DEFAULT_PROVIDERS,exports.DetectionResults=i.DetectionResults,exports.Detector=_.Detector,exports.ImageLoadError=t.ImageLoadError,exports.InferenceError=t.InferenceError,exports.LUMINANCE_SAMPLE_MAX_EDGE=b.LUMINANCE_SAMPLE_MAX_EDGE,exports.LabelMapError=t.LabelMapError,exports.LowLuminanceError=b.LowLuminanceError,exports.Mask=n.Mask,exports.Masks=i.Masks,exports.ModelLoadError=t.ModelLoadError,exports.OrtSession=l.OrtSession,exports.OrtVisionError=t.OrtVisionError,exports.Probs=i.Probs,exports.ProviderNotAvailableError=t.ProviderNotAvailableError,exports.RGBImage=n.RGBImage,exports.SegmentationResults=i.SegmentationResults,exports.Segmenter=v.Segmenter,exports.SpeedTimer=r.SpeedTimer,exports.VERSION=y.VERSION,exports.VisionTask=h.VisionTask,exports.batchedNms=p.batchedNms,exports.classificationNumClasses=o.classificationNumClasses,exports.computeImageLuminance=b.computeImageLuminance,exports.declaredShapesFrom=o.declaredShapesFrom,exports.decodeYolo=p.decodeYolo,exports.decodeYoloAnchors=p.decodeYoloAnchors,exports.decodeYoloSeg=m.decodeYoloSeg,exports.decodeYoloV8=p.decodeYoloV8,exports.decodeYoloV8Anchors=p.decodeYoloV8Anchors,exports.decodeYoloV8Seg=m.decodeYoloV8Seg,exports.detectionNumClasses=o.detectionNumClasses,exports.fromCv2=d.fromCv2,exports.isLuminanceAcceptable=b.isLuminanceAcceptable,exports.letterbox=d.letterbox,exports.loadImage=u.loadImage,exports.modelNames=s.modelNames,exports.nms=p.nms,exports.normalize=d.normalize,exports.readModelMetadata=s.readModelMetadata,exports.resize=d.resize,exports.resolveInputSize=o.resolveInputSize,exports.resolveLabels=a.resolveLabels,exports.resolveProviders=c.resolveProviders,exports.softmax=f.softmax,exports.spatialInputSize=o.spatialInputSize,exports.toCHW=d.toCHW,exports.toCv2=d.toCv2,exports.toFloat32=d.toFloat32,exports.toFloat32Tensor=d.toFloat32Tensor,exports.toTensor=d.toTensor,exports.topK=f.topK,exports.useCameraStream=e.useCameraStream,exports.useLiveLuminance=x.useLiveLuminance;

package/dist/vision.d.ts

@@ -116,6 +116,16 @@ export declare type CameraStreamErrorKind = "unsupported" | "permission-denied"
 /** Lifecycle status of the camera stream. */
 export declare type CameraStreamStatus = "idle" | "loading" | "ready" | "error";
 
+/**
+ * Infer how many classes a classification head emits.
+ *
+ * A classifier declares `(B, nc)`, so the count is the last static axis.
+ *
+ * @param shape Declared shape of the model's first output.
+ * @returns The class count, or `null` when the last axis is dynamic or absent.
+ */
+export declare function classificationNumClasses(shape: DeclaredShape): number | null;
+
 /**
  * Output of an image classification inference.
  */
@@ -191,11 +201,19 @@ export declare class Classifier extends VisionTask {
     private readonly _applySoftmax;
     private constructor();
     /** Load the model and resolve labels. */
-    static create(model: ModelSource, options: ClassifierOptions): Promise<Classifier>;
+    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>>;
+    /**
+     * The `[width, height]` this task preprocesses to.
+     *
+     * Resolved at creation time from the model's graph when it declares a static
+     * input, so reading it back tells you the resolution inference really runs at
+     * — not merely what was requested.
+     */
+    get inputSize(): readonly [number, number];
     /** Number of classes the model can predict. */
     get numClasses(): number;
     /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
@@ -207,14 +225,29 @@ export declare class Classifier extends VisionTask {
 }
 
 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.
+     * Class label spec — see {@link resolveLabels}.
+     *
+     * Optional: when omitted, the names the export baked into the model are used
+     * (Ultralytics writes them as `names` in the metadata map). Only when the
+     * model carries none does this fall back to generated `class_<id>` labels.
+     * Passing a spec always wins, for a model whose names are wrong or absent.
+     */
+    readonly labels?: LabelSpec;
+    /**
+     * Number of classes the model can predict.
+     *
+     * Optional: inferred from the classification head's declared output shape
+     * `(B, nc)`. Pass it to validate that the supplied labels match the model.
      */
     readonly numClasses?: number;
-    /** Model input `[width, height]` in pixels. Defaults to `[224, 224]`. */
+    /**
+     * Model input `[width, height]` in pixels.
+     *
+     * Only used when the model's graph leaves its spatial axes dynamic: a graph
+     * that declares a static size always wins, since that is the only shape ONNX
+     * Runtime will accept. 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];
@@ -277,6 +310,26 @@ export declare const COCO_CLASSES: readonly string[];
  */
 export declare function computeImageLuminance(source: LuminanceSource, reusableCanvas?: HTMLCanvasElement): number;
 
+/**
+ * One declared dimension: a number when the graph pins it, `null` when the
+ * dimension is symbolic (dynamic).
+ */
+export declare type DeclaredDim = number | null;
+
+/** A declared input/output shape, dynamic axes appearing as `null`. */
+export declare type DeclaredShape = readonly DeclaredDim[];
+
+/**
+ * Convert ORT value metadata into declared shapes.
+ *
+ * @param metadata Metadata as reported by `InferenceSession.inputMetadata`, or
+ *   `undefined` on ORT builds that predate it (added in onnxruntime 1.21).
+ * @returns One shape per value, in declaration order. Non-tensor values and
+ *   builds without metadata yield empty shapes, which read as "nothing
+ *   declared" everywhere downstream.
+ */
+export declare function declaredShapesFrom(metadata: readonly ort.InferenceSession.ValueMetadata[] | undefined): readonly DeclaredShape[];
+
 export declare interface DecodedAnchors {
     /** Indices into the original `numAnchors` axis, in descending confidence order. */
     readonly anchorIndices: Int32Array;
@@ -414,6 +467,19 @@ export declare type DecodeYoloV8SegOptions = DecodeYoloSegOptions;
  */
 export declare const DEFAULT_PROVIDERS: readonly string[];
 
+/**
+ * Infer how many classes a YOLO detection/segmentation head emits.
+ *
+ * Such a head declares `(B, 4 + nc, N)` — four box coordinates stacked above one
+ * score per class, over `N` candidate anchors. `N` is in the thousands and the
+ * batch is 1, so the channel axis is the smallest static axis above 1.
+ *
+ * @param shape Declared shape of the model's first output.
+ * @returns The class count, or `null` when the shape leaves it undeterminable —
+ *   fully dynamic, or too small to hold boxes plus at least one class.
+ */
+export declare function detectionNumClasses(shape: DeclaredShape): number | null;
+
 /**
  * Single detected object produced by an object-detection model.
  */
@@ -504,6 +570,14 @@ export declare class Detector extends VisionTask {
     get labels(): readonly string[];
     /** Class id → class name dict (matches Ultralytics' `model.names`). */
     get names(): Readonly<Record<number, string>>;
+    /**
+     * The `[width, height]` this task preprocesses to.
+     *
+     * Resolved at creation time from the model's graph when it declares a static
+     * input, so reading it back tells you the resolution inference really runs at
+     * — not merely what was requested.
+     */
+    get inputSize(): readonly [number, number];
     /** Number of classes the model predicts. */
     get numClasses(): number;
     /**
@@ -548,7 +622,13 @@ export declare interface DetectorOptions extends OrtSessionOptions {
     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]`. */
+    /**
+     * Model input `[width, height]` in pixels for letterboxing.
+     *
+     * Only used when the model's graph leaves its spatial axes dynamic: a graph
+     * that declares a static size always wins, since that is the only shape ONNX
+     * Runtime will accept. Defaults to `[640, 640]`.
+     */
     readonly inputSize?: readonly [number, number];
     /** Default minimum class score to keep a candidate. */
     readonly confThreshold?: number;
@@ -737,6 +817,21 @@ export declare interface LetterboxResult {
  export declare class ModelLoadError extends OrtVisionError {
  }
 
+ /**
+  * Read the class names an export baked into the model metadata.
+  *
+  * Ultralytics writes `names` as the Python `repr` of a `dict[int, str]` — e.g.
+  * `"{0: 'deworm', 1: 'not_deworm'}"`. The value is parsed structurally (never
+  * evaluated), and anything unparseable, non-`dict`, or not keyed by contiguous
+  * integers from zero is rejected whole rather than half-applied: a partial name
+  * map would silently mislabel predictions.
+  *
+  * @param metadata A model's custom metadata map.
+  * @returns Class names in class-id order, or `null` when the model carries no
+  *   usable `names` entry.
+  */
+ export declare function modelNames(metadata: Readonly<Record<string, string>> | undefined): readonly string[] | null;
+
  /** Anything `InferenceSession.create` accepts. */
  export declare type ModelSource = string | ArrayBufferLike | Uint8Array;
 
@@ -763,18 +858,21 @@ export declare interface LetterboxResult {
  /**
   * 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.
+  * The wrapper exposes input/output names and the shapes the graph declares,
+  * manages execution-provider selection, provides a typed {@link OrtSession.run}
+  * method, and releases the native session through {@link OrtSession.release}.
   */
  export declare class OrtSession {
      private readonly _session;
      readonly providers: readonly string[];
+     private readonly _metadata;
      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`.
+      * @param model Either a URL string, or a `Uint8Array`/`ArrayBuffer` containing the model bytes.
+      * @param options Provider list, pass-through `SessionOptions`, and whether to
+      *   read the model's metadata map (see {@link OrtSessionOptions.readMetadata}).
       * @throws {@link ModelLoadError} if the model cannot be loaded.
           */
       static create(model: ModelSource, options?: OrtSessionOptions): Promise<OrtSession>;
@@ -784,6 +882,51 @@ export declare interface LetterboxResult {
       get inputName(): string;
       /** Names of the model's outputs, in declaration order. */
       get outputNames(): readonly string[];
+      /**
+       * Shapes the graph declares for its inputs, in declaration order.
+       *
+       * Dynamic (symbolic) axes appear as `null`. Empty shapes mean the runtime
+       * reported no metadata — either a non-tensor input, or an `onnxruntime-web`
+       * older than 1.21, which predates input metadata.
+       */
+      get inputShapes(): readonly DeclaredShape[];
+      /**
+       * Shape the graph declares for its first input, dynamic axes as `null`.
+       *
+       * Empty when the runtime reports no metadata for it.
+       */
+      get inputShape(): DeclaredShape;
+      /**
+       * Shapes the graph declares for its outputs, in declaration order.
+       *
+       * Dynamic (symbolic) axes appear as `null`. Reading them is how a task can
+       * tell how many classes a head emits without being told.
+       */
+      get outputShapes(): readonly DeclaredShape[];
+      /**
+       * Shape the graph declares for its first output, dynamic axes as `null`.
+       *
+       * Empty when the runtime reports no metadata for it.
+       */
+      get outputShape(): DeclaredShape;
+      /**
+       * The model's custom metadata map — `names`, `task`, `imgsz`, ... for an
+       * Ultralytics export.
+       *
+       * Read from the model's bytes at load time, since the runtime does not expose
+       * it. Empty when the session was created with `readMetadata: false`, from a
+       * URL that could not be fetched here, or from a model carrying no metadata.
+       */
+      get metadata(): Readonly<Record<string, string>>;
+      /**
+       * Release the native session and free its memory.
+       *
+       * Call it when a session is discarded while the page lives on — rebuilding a
+       * task at a different input size, swapping in a newer model. A failure from
+       * the runtime is ignored: a session being torn down has nothing left to fail
+       * at, and the caller is already moving on.
+       */
+      release(): Promise<void>;
       /** The underlying `onnxruntime-web` session, for advanced use cases. */
       get raw(): ort.InferenceSession;
       /**
@@ -800,6 +943,17 @@ export declare interface LetterboxResult {
           readonly providers?: readonly string[];
           /** Optional ORT session options forwarded to `InferenceSession.create`. */
           readonly sessionOptions?: ort.InferenceSession.SessionOptions;
+          /**
+           * Whether to read the model's custom metadata map (`names`, `task`, `imgsz`).
+           * Defaults to `true`.
+           *
+           * The runtime does not expose that map, so it is read from the file itself —
+           * which means a URL model is fetched here and handed to ORT as bytes instead
+           * of letting ORT fetch it. That is the same single download either way, and
+           * it is what lets a task resolve its labels off the model. Set to `false` to
+           * keep the URL path untouched and leave {@link OrtSession.metadata} empty.
+           */
+          readonly readMetadata?: boolean;
       }
 
       /**
@@ -840,9 +994,57 @@ export declare interface LetterboxResult {
       export declare class ProviderNotAvailableError extends OrtVisionError {
       }
 
+      /**
+       * Read the metadata an exporter baked into a `.onnx` file.
+       *
+       * `onnxruntime-web` exposes input/output metadata but **not** the model's
+       * custom metadata map, which is where Ultralytics writes `names`, `task` and
+       * `imgsz`. The Python SDK gets it for free from
+       * `InferenceSession.get_modelmeta().custom_metadata_map`; in the browser the
+       * only way to the same information is to read it out of the file, so this
+       * module walks just enough of the ModelProto wire format to collect
+       * `metadata_props`.
+       *
+       * It never throws and never allocates unbounded: a truncated, hostile or
+       * simply unexpected file yields an empty map, and every caller treats that as
+       * "the model says nothing", falling back to what it was given.
+       */
+      /**
+       * Collect a model's custom metadata map straight out of its bytes.
+       *
+       * @param model The `.onnx` file contents.
+       * @returns Key/value metadata — `names`, `task`, `imgsz`, ... for an
+       *   Ultralytics export — or an empty object when the file carries none or
+       *   cannot be walked.
+       */
+      export declare function readModelMetadata(model: Uint8Array | ArrayBufferLike): Readonly<Record<string, string>>;
+
       /** Resize an image to `(targetWidth, targetHeight)` using high-quality canvas resampling. */
       export declare function resize(image: RGBImage, targetWidth: number, targetHeight: number): RGBImage;
 
+      /**
+       * Decide the input size a task will preprocess to.
+       *
+       * Precedence is graph → caller → fallback. The graph wins over an explicit
+       * `inputSize` because a static shape is not a preference, it is what ORT will
+       * accept: honoring the caller there would only turn a fixable mismatch into a
+       * failed run. A disagreement is a configuration bug in the caller, so it is
+       * reported through `console.warn` instead of being swallowed.
+       *
+       * @param options Graph shape, requested size and per-task fallback.
+       * @returns The `[width, height]` to preprocess to.
+       */
+      export declare function resolveInputSize(options: ResolveInputSizeOptions): readonly [number, number];
+
+      export declare interface ResolveInputSizeOptions {
+          /** Declared shape of the model's image input, from {@link declaredShapesFrom}. */
+          readonly graphShape?: DeclaredShape;
+          /** Size the caller asked for, if any. */
+          readonly requested?: readonly [number, number];
+          /** Size to use when neither the graph nor the caller pins one. */
+          readonly fallback: readonly [number, number];
+      }
+
       /**
        * Resolve a labels specification into an ordered array of class names.
        *
@@ -991,6 +1193,14 @@ export declare interface LetterboxResult {
            get labels(): readonly string[];
            /** Class id → class name dict (matches Ultralytics' `model.names`). */
            get names(): Readonly<Record<number, string>>;
+           /**
+            * The `[width, height]` this task preprocesses to.
+            *
+            * Resolved at creation time from the model's graph when it declares a static
+            * input, so reading it back tells you the resolution inference really runs at
+            * — not merely what was requested.
+            */
+           get inputSize(): readonly [number, number];
            /** Number of classes the model predicts. */
            get numClasses(): number;
            /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
@@ -1026,7 +1236,13 @@ export declare interface LetterboxResult {
            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]`. */
+           /**
+            * Model input `[width, height]` in pixels for letterboxing.
+            *
+            * Only used when the model's graph leaves its spatial axes dynamic: a graph
+            * that declares a static size always wins, since that is the only shape ONNX
+            * Runtime will accept. Defaults to `[640, 640]`.
+            */
            readonly inputSize?: readonly [number, number];
            /** Default minimum class score to keep a candidate. */
            readonly confThreshold?: number;
@@ -1054,6 +1270,16 @@ export declare interface LetterboxResult {
        /** Apply numerically-stable softmax to a 1-D vector of logits. */
        export declare function softmax(logits: Float32Array | readonly number[]): Float32Array;
 
+       /**
+        * Read the spatial input size out of a declared NCHW shape.
+        *
+        * @param shape The declared shape of the model's image input.
+        * @returns `[width, height]` in pixels, or `null` when the shape is not 4D or
+        *   leaves either spatial axis dynamic — in which case the model accepts more
+        *   than one resolution and there is nothing to correct.
+        */
+       export declare function spatialInputSize(shape: DeclaredShape): readonly [number, number] | null;
+
        /**
         * Per-stage timing for a single `predict()` call.
         *

package/dist/vision.js

@@ -4,18 +4,20 @@ import { BoundingBox as s, Mask as c, RGBImage as l } from "./vision/types.js";
 import { SpeedTimer as u } from "./vision/core/timing.js";
 import { Boxes as d, ClassificationResults as f, DetectionResults as p, Masks as m, Probs as h, SegmentationResults as g } from "./vision/results.js";
 import { COCO_CLASSES as _, resolveLabels as v } from "./vision/labels.js";
-import { DEFAULT_PROVIDERS as y, resolveProviders as b } from "./vision/core/providers.js";
-import { OrtSession as x } from "./vision/core/session.js";
-import { loadImage as S } from "./vision/io/image.js";
-import { fromCv2 as C, letterbox as w, normalize as T, resize as E, toCHW as D, toCv2 as O, toFloat32 as k, toFloat32Tensor as A, toTensor as j } from "./vision/preprocess/image.js";
-import { softmax as M, topK as N } from "./vision/postprocess/classification.js";
-import { batchedNms as P, decodeYolo as F, decodeYoloAnchors as I, decodeYoloV8 as L, decodeYoloV8Anchors as R, nms as z } from "./vision/postprocess/detection.js";
-import { decodeYoloSeg as B, decodeYoloV8Seg as V } from "./vision/postprocess/segmentation.js";
-import { VisionTask as H } from "./vision/tasks/base.js";
-import { Classifier as U } from "./vision/tasks/classifier.js";
-import { Detector as W } from "./vision/tasks/detector.js";
-import { Segmenter as G } from "./vision/tasks/segmenter.js";
-import { VERSION as K } from "./vision/index.js";
-import { LUMINANCE_SAMPLE_MAX_EDGE as q, LowLuminanceError as J, computeImageLuminance as Y, isLuminanceAcceptable as X } from "./vision/luminance.js";
-import { useLiveLuminance as Z } from "./vision/use-live-luminance.js";
-export { s as BoundingBox, d as Boxes, _ as COCO_CLASSES, f as ClassificationResults, U as Classifier, y as DEFAULT_PROVIDERS, p as DetectionResults, W as Detector, t as ImageLoadError, n as InferenceError, q as LUMINANCE_SAMPLE_MAX_EDGE, r as LabelMapError, J as LowLuminanceError, c as Mask, m as Masks, i as ModelLoadError, x as OrtSession, a as OrtVisionError, h as Probs, o as ProviderNotAvailableError, l as RGBImage, g as SegmentationResults, G as Segmenter, u as SpeedTimer, K as VERSION, H as VisionTask, P as batchedNms, Y as computeImageLuminance, F as decodeYolo, I as decodeYoloAnchors, B as decodeYoloSeg, L as decodeYoloV8, R as decodeYoloV8Anchors, V as decodeYoloV8Seg, C as fromCv2, X as isLuminanceAcceptable, w as letterbox, S as loadImage, z as nms, T as normalize, E as resize, v as resolveLabels, b as resolveProviders, M as softmax, D as toCHW, O as toCv2, k as toFloat32, A as toFloat32Tensor, j as toTensor, N as topK, e as useCameraStream, Z as useLiveLuminance };
+import { classificationNumClasses as y, declaredShapesFrom as b, detectionNumClasses as x, resolveInputSize as S, spatialInputSize as C } from "./vision/core/graph.js";
+import { modelNames as w, readModelMetadata as T } from "./vision/core/metadata.js";
+import { DEFAULT_PROVIDERS as E, resolveProviders as D } from "./vision/core/providers.js";
+import { OrtSession as O } from "./vision/core/session.js";
+import { loadImage as k } from "./vision/io/image.js";
+import { fromCv2 as A, letterbox as j, normalize as M, resize as N, toCHW as P, toCv2 as F, toFloat32 as I, toFloat32Tensor as L, toTensor as R } from "./vision/preprocess/image.js";
+import { softmax as z, topK as B } from "./vision/postprocess/classification.js";
+import { batchedNms as V, decodeYolo as H, decodeYoloAnchors as U, decodeYoloV8 as W, decodeYoloV8Anchors as G, nms as K } from "./vision/postprocess/detection.js";
+import { decodeYoloSeg as q, decodeYoloV8Seg as J } from "./vision/postprocess/segmentation.js";
+import { VisionTask as Y } from "./vision/tasks/base.js";
+import { Classifier as X } from "./vision/tasks/classifier.js";
+import { Detector as Z } from "./vision/tasks/detector.js";
+import { Segmenter as Q } from "./vision/tasks/segmenter.js";
+import { VERSION as $ } from "./vision/index.js";
+import { LUMINANCE_SAMPLE_MAX_EDGE as ee, LowLuminanceError as te, computeImageLuminance as ne, isLuminanceAcceptable as re } from "./vision/luminance.js";
+import { useLiveLuminance as ie } from "./vision/use-live-luminance.js";
+export { s as BoundingBox, d as Boxes, _ as COCO_CLASSES, f as ClassificationResults, X as Classifier, E as DEFAULT_PROVIDERS, p as DetectionResults, Z as Detector, t as ImageLoadError, n as InferenceError, ee as LUMINANCE_SAMPLE_MAX_EDGE, r as LabelMapError, te as LowLuminanceError, c as Mask, m as Masks, i as ModelLoadError, O as OrtSession, a as OrtVisionError, h as Probs, o as ProviderNotAvailableError, l as RGBImage, g as SegmentationResults, Q as Segmenter, u as SpeedTimer, $ as VERSION, Y as VisionTask, V as batchedNms, y as classificationNumClasses, ne as computeImageLuminance, b as declaredShapesFrom, H as decodeYolo, U as decodeYoloAnchors, q as decodeYoloSeg, W as decodeYoloV8, G as decodeYoloV8Anchors, J as decodeYoloV8Seg, x as detectionNumClasses, A as fromCv2, re as isLuminanceAcceptable, j as letterbox, k as loadImage, w as modelNames, K as nms, M as normalize, T as readModelMetadata, N as resize, S as resolveInputSize, v as resolveLabels, D as resolveProviders, z as softmax, C as spatialInputSize, P as toCHW, F as toCv2, I as toFloat32, L as toFloat32Tensor, R as toTensor, B as topK, e as useCameraStream, ie as useLiveLuminance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.36.0",
+  "version": "0.38.0",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",