tempest-react-sdk 0.36.0 → 0.37.0

package/dist/vision.d.ts

@@ -196,6 +196,14 @@ export declare class Classifier 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 can predict. */
     get numClasses(): number;
     /** Alias for {@link predict} (parity with PyTorch `nn.Module.__call__`). */
@@ -214,7 +222,13 @@ export declare interface ClassifierOptions extends OrtSessionOptions {
      * 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]`. */
+    /**
+     * 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 +291,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;
@@ -504,6 +538,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 +590,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;
@@ -763,8 +811,9 @@ 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;
@@ -784,6 +833,29 @@ 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;
+      /**
+       * 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;
       /**
@@ -843,6 +915,29 @@ export declare interface LetterboxResult {
       /** 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 +1086,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 +1129,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 +1163,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,19 @@ 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 { declaredShapesFrom as y, resolveInputSize as b, spatialInputSize as x } from "./vision/core/graph.js";
+import { DEFAULT_PROVIDERS as S, resolveProviders as C } from "./vision/core/providers.js";
+import { OrtSession as w } from "./vision/core/session.js";
+import { loadImage as T } from "./vision/io/image.js";
+import { fromCv2 as E, letterbox as D, normalize as O, resize as k, toCHW as A, toCv2 as j, toFloat32 as M, toFloat32Tensor as N, toTensor as P } from "./vision/preprocess/image.js";
+import { softmax as F, topK as I } from "./vision/postprocess/classification.js";
+import { batchedNms as L, decodeYolo as R, decodeYoloAnchors as z, decodeYoloV8 as B, decodeYoloV8Anchors as V, nms as H } from "./vision/postprocess/detection.js";
+import { decodeYoloSeg as U, decodeYoloV8Seg as W } from "./vision/postprocess/segmentation.js";
+import { VisionTask as G } from "./vision/tasks/base.js";
+import { Classifier as K } from "./vision/tasks/classifier.js";
+import { Detector as q } from "./vision/tasks/detector.js";
+import { Segmenter as J } from "./vision/tasks/segmenter.js";
+import { VERSION as Y } from "./vision/index.js";
+import { LUMINANCE_SAMPLE_MAX_EDGE as X, LowLuminanceError as Z, computeImageLuminance as Q, isLuminanceAcceptable as $ } from "./vision/luminance.js";
+import { useLiveLuminance as ee } from "./vision/use-live-luminance.js";
+export { s as BoundingBox, d as Boxes, _ as COCO_CLASSES, f as ClassificationResults, K as Classifier, S as DEFAULT_PROVIDERS, p as DetectionResults, q as Detector, t as ImageLoadError, n as InferenceError, X as LUMINANCE_SAMPLE_MAX_EDGE, r as LabelMapError, Z as LowLuminanceError, c as Mask, m as Masks, i as ModelLoadError, w as OrtSession, a as OrtVisionError, h as Probs, o as ProviderNotAvailableError, l as RGBImage, g as SegmentationResults, J as Segmenter, u as SpeedTimer, Y as VERSION, G as VisionTask, L as batchedNms, Q as computeImageLuminance, y as declaredShapesFrom, R as decodeYolo, z as decodeYoloAnchors, U as decodeYoloSeg, B as decodeYoloV8, V as decodeYoloV8Anchors, W as decodeYoloV8Seg, E as fromCv2, $ as isLuminanceAcceptable, D as letterbox, T as loadImage, H as nms, O as normalize, k as resize, b as resolveInputSize, v as resolveLabels, C as resolveProviders, F as softmax, x as spatialInputSize, A as toCHW, j as toCv2, M as toFloat32, N as toFloat32Tensor, P as toTensor, I as topK, e as useCameraStream, ee as useLiveLuminance };

package/package.json

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