@mauriciobenjamin700/ort-vision-sdk-web 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,101 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-03
+
+### Added
+
+- **Tasks read their class names off the model, matching the Python SDK.**
+  `labels` is now optional on all three tasks: when omitted, the names the
+  exporter baked into the model are used (Ultralytics writes them as `names` in
+  the metadata map), and only a model carrying none falls back to the COCO
+  preset for detection/segmentation or generated `class_<id>` labels for
+  classification. Passing `labels` still wins, for a model whose names are
+  wrong or absent.
+
+  ```typescript
+  const det = await Detector.create("/models/detect.onnx");
+  console.log(det.labels); // ["ocular-mucosa"] — from the model, not a preset
+  ```
+
+  This also fixes a trap: a single-class detector used to **fail** without an
+  explicit `labels`, because the 80-name COCO default disagreed with its class
+  count.
+
+- **`numClasses` is inferred from the declared output shape.** A YOLO head
+  declares `(B, 4 + nc, N)` and a classifier `(B, nc)`, so the count no longer
+  has to be supplied. Passing it still validates the labels against the model.
+
+- **`OrtSession.metadata`** exposes the model's custom metadata map (`names`,
+  `task`, `imgsz`, ...). `onnxruntime-web` does not surface that map — unlike
+  Python's `custom_metadata_map` — so it is read from the model's own bytes at
+  load time by walking `metadata_props` in the ModelProto. A truncated or
+  unexpected file yields an empty map instead of an error, and every caller
+  falls back to what it was given.
+
+- **`OrtSession.outputShapes` / `.outputShape`**, the shapes the graph declares
+  for its outputs, with dynamic axes as `null` — the same treatment
+  `inputShapes` already got.
+
+- **`detectionNumClasses`, `classificationNumClasses`, `readModelMetadata`,
+  `modelNames`**: the pure helpers behind the above, exported for anyone
+  assembling their own pipeline.
+
+### Changed
+
+- **A URL model is fetched by the SDK instead of by ORT**, so its bytes are
+  available to read metadata from. It is the same single download, and
+  `readMetadata: false` on the session options restores the previous path (ORT
+  fetches the URL, `metadata` stays empty). A failed fetch falls back to handing
+  ORT the URL, so a model that ORT could load still loads.
+
+## [0.4.0] - 2026-08-03
+
+### Added
+
+- **Tasks read their input resolution off the model instead of trusting
+  configuration.** `Classifier`, `Detector` and `Segmenter` now ask the ONNX
+  graph what shape it declares and preprocess to that. The resolution a session
+  must be fed at is a property of the export — feeding a 640x640 tensor to a
+  graph exported at 224x224 makes ORT abort mid-run with:
+
+  ```text
+  Inference failed: failed to call OrtRun(). ERROR_CODE: 2, ERROR_MESSAGE: Got
+  invalid dimensions for input: images for the following indices index: 2
+  Got: 640 Expected: 224
+  ```
+
+  A caller had no way to see that coming: the number lives in the file. So it is
+  read from there now.
+
+  ```typescript
+  // An Ultralytics -cls export is 224; nothing to configure, nothing to get wrong
+  const clf = await Classifier.create("/models/classify.onnx", { labels: LABELS });
+  console.log(clf.inputSize); // [224, 224]
+  ```
+
+  `inputSize` is now a *fallback*, used only when the graph leaves its spatial
+  axes dynamic. Passing a size that contradicts a static graph logs a warning
+  and the graph wins — honoring the caller there would only turn a fixable
+  mismatch into a failed run.
+
+- **`inputSize` getter on every task**, so callers can read back the resolution
+  inference actually runs at rather than the one they asked for.
+
+- **`OrtSession.inputShapes` / `OrtSession.inputShape`** expose what the graph
+  declares, with dynamic axes as `null`. Empty when the runtime reports no
+  metadata (`onnxruntime-web` older than 1.21).
+
+- **`OrtSession.release()`** frees the native session. Needed whenever a session
+  is discarded while the page lives on — rebuilding a task at a different input
+  size, swapping in a newer model — which previously required reaching into
+  `session.raw`.
+
+- **`declaredShapesFrom`, `spatialInputSize`, `resolveInputSize`** (plus the
+  `DeclaredShape` / `DeclaredDim` types): the pure helpers behind the above,
+  exported so callers building their own pipeline can reuse the same precedence
+  rules without importing `onnxruntime-web` types themselves.
+
 ## [0.3.0] - 2026-08-02
 
 ### Added
@@ -46,6 +141,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   would break `tempest-react-sdk`, which re-exports all three from its vendored
   copy. The warning now points at `0.4.0`.
 
+## [0.2.2] - 2026-05-31
+
+### Changed
+
+- README now links to the bilingual (PT-BR + EN-US) documentation site on
+  GitHub Pages (<https://mauriciobenjamin700.github.io/ort-vision-sdk/>) so the
+  npm package page points readers to the full guide and API reference.
+  Documentation-only release; no public API changes.
+
 ## [0.2.1] - 2026-05-03
 
 First **published** release on npm. The previous `0.2.0` tag never produced a

package/README.md

@@ -37,8 +37,17 @@ const result = await clf.predict("/images/dog.jpg", { topK: 5 });
 console.log(result.className, result.confidence);
 console.log(result.probabilities);
 // result.image is an RGBImage (HWC RGB Uint8Array) — the original input.
+console.log(clf.inputSize);
+// [224, 224] — read from the .onnx graph, not configured.
 ```
 
+> **The model decides its input size.** `inputSize` is optional: the resolution
+> the graph declares always wins, because it is the only shape ONNX Runtime will
+> accept. An Ultralytics `-cls` export is 224x224 while a detector is 640x640 —
+> get it wrong and ORT aborts with `Got invalid dimensions for input: images`.
+> Read it back with `task.inputSize`, or inspect `session.inputShape`. See
+> [O modelo manda / The model decides](https://mauriciobenjamin700.github.io/ort-vision-sdk/en/guia/modelo/).
+
 ### Object detection
 
 ```typescript

package/dist/core/graph.d.ts

@@ -0,0 +1,81 @@
+/**
+ * What the ONNX graph itself says about its inputs.
+ *
+ * The resolution a session must be fed at is a property of the exported model,
+ * not of the configuration around it. Feeding a 640x640 tensor to a graph
+ * exported at 224x224 makes ORT abort the run with
+ * `Got invalid dimensions for input: images ... Got: 640 Expected: 224`, and the
+ * caller has no way to see that coming from the outside — the number lives in
+ * the file. So the SDK reads it from the graph and treats any configured size as
+ * a fallback for when the graph leaves it open.
+ */
+import type * as ort from "onnxruntime-web";
+/**
+ * One declared dimension: a number when the graph pins it, `null` when the
+ * dimension is symbolic (dynamic).
+ */
+export type DeclaredDim = number | null;
+/** A declared input/output shape, dynamic axes appearing as `null`. */
+export 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[];
+/**
+ * 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;
+/**
+ * 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;
+/**
+ * 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;
+export 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];
+}
+/**
+ * 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];
+//# sourceMappingURL=graph.d.ts.map

package/dist/core/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/core/graph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,CAAC;AAExC,uEAAuE;AACvE,MAAM,MAAM,aAAa,GAAG,SAAS,WAAW,EAAE,CAAC;AAEnD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,SAAS,GAAG,CAAC,gBAAgB,CAAC,aAAa,EAAE,GAAG,SAAS,GAClE,SAAS,aAAa,EAAE,CAO1B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAMvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAMvE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAI5E;AAED,MAAM,WAAW,uBAAuB;IACtC,kFAAkF;IAClF,QAAQ,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/C,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAW5F"}

package/dist/core/graph.js

@@ -0,0 +1,102 @@
+/**
+ * What the ONNX graph itself says about its inputs.
+ *
+ * The resolution a session must be fed at is a property of the exported model,
+ * not of the configuration around it. Feeding a 640x640 tensor to a graph
+ * exported at 224x224 makes ORT abort the run with
+ * `Got invalid dimensions for input: images ... Got: 640 Expected: 224`, and the
+ * caller has no way to see that coming from the outside — the number lives in
+ * the file. So the SDK reads it from the graph and treats any configured size as
+ * a fallback for when the graph leaves it open.
+ */
+/**
+ * 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 function declaredShapesFrom(metadata) {
+    if (metadata === undefined)
+        return [];
+    return metadata.map((value) => value.isTensor
+        ? value.shape.map((dim) => (typeof dim === "number" && Number.isInteger(dim) && dim > 0 ? dim : null))
+        : []);
+}
+/**
+ * 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 function spatialInputSize(shape) {
+    if (shape.length !== 4)
+        return null;
+    const height = shape[2];
+    const width = shape[3];
+    if (height === null || height === undefined || width === null || width === undefined)
+        return null;
+    return [width, height];
+}
+/**
+ * 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 function detectionNumClasses(shape) {
+    const staticDims = shape.filter((dim) => dim !== null && dim > 1);
+    if (staticDims.length === 0)
+        return null;
+    const channels = Math.min(...staticDims);
+    if (channels < 5)
+        return null;
+    return channels - 4;
+}
+/**
+ * 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 function classificationNumClasses(shape) {
+    const last = shape[shape.length - 1];
+    if (last === null || last === undefined || last < 1)
+        return null;
+    return last;
+}
+/**
+ * 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 function resolveInputSize(options) {
+    const graph = options.graphShape === undefined ? null : spatialInputSize(options.graphShape);
+    const requested = options.requested;
+    if (graph === null)
+        return requested ?? options.fallback;
+    if (requested !== undefined && (requested[0] !== graph[0] || requested[1] !== graph[1])) {
+        console.warn(`[ort-vision-sdk] The model declares a ${graph[0]}x${graph[1]} input; ` +
+            `ignoring the requested ${requested[0]}x${requested[1]}, which ONNX Runtime would reject.`);
+    }
+    return graph;
+}
+//# sourceMappingURL=graph.js.map

package/dist/core/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/core/graph.ts"],"names":[],"mappings":"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"}

package/dist/core/metadata.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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>>;
+/**
+ * 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;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/core/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAyIH;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,UAAU,GAAG,eAAe,GAClC,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAqBlC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CACxB,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GACrD,SAAS,MAAM,EAAE,GAAG,IAAI,CA6B1B"}

package/dist/core/metadata.js

@@ -0,0 +1,233 @@
+/**
+ * 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.
+ */
+/** Field number of `metadata_props` in `ModelProto` (repeated StringStringEntryProto). */
+const MODEL_METADATA_PROPS_FIELD = 14;
+/** Field numbers of `key` and `value` in `StringStringEntryProto`. */
+const ENTRY_KEY_FIELD = 1;
+const ENTRY_VALUE_FIELD = 2;
+/** Protobuf wire types this reader understands. */
+const WIRE_VARINT = 0;
+const WIRE_FIXED64 = 1;
+const WIRE_LENGTH_DELIMITED = 2;
+const WIRE_FIXED32 = 5;
+/**
+ * Hard ceiling on a single length-delimited field, as a guard against a corrupt
+ * length turning into a huge slice. Model metadata values are strings — a class
+ * name map for thousands of classes still fits well inside this.
+ */
+const MAX_FIELD_BYTES = 1 << 20;
+/**
+ * Read a base-128 varint.
+ *
+ * @param cursor Cursor to advance.
+ * @returns The value, or `null` when the varint is truncated or overlong
+ *   (beyond the 64-bit range protobuf allows).
+ */
+function readVarint(cursor) {
+    let result = 0;
+    let shift = 0;
+    while (cursor.pos < cursor.end) {
+        const byte = cursor.bytes[cursor.pos];
+        cursor.pos += 1;
+        result += (byte & 0x7f) * 2 ** shift;
+        if ((byte & 0x80) === 0)
+            return result;
+        shift += 7;
+        if (shift > 63)
+            return null;
+    }
+    return null;
+}
+/**
+ * Skip a field whose contents are not needed.
+ *
+ * @param cursor Cursor to advance past the field's payload.
+ * @param wireType Wire type read from the field's tag.
+ * @returns `true` when the field was skipped, `false` when the stream is
+ *   unreadable from here (unknown wire type or truncated payload).
+ */
+function skipField(cursor, wireType) {
+    switch (wireType) {
+        case WIRE_VARINT:
+            return readVarint(cursor) !== null;
+        case WIRE_FIXED64:
+            cursor.pos += 8;
+            return cursor.pos <= cursor.end;
+        case WIRE_LENGTH_DELIMITED: {
+            const length = readVarint(cursor);
+            if (length === null)
+                return false;
+            cursor.pos += length;
+            return cursor.pos <= cursor.end;
+        }
+        case WIRE_FIXED32:
+            cursor.pos += 4;
+            return cursor.pos <= cursor.end;
+        default:
+            return false;
+    }
+}
+/**
+ * Read a length-delimited payload as a byte range.
+ *
+ * @param cursor Cursor to advance past the payload.
+ * @returns Start and end offsets of the payload, or `null` when the length is
+ *   truncated, overruns the buffer, or exceeds {@link MAX_FIELD_BYTES}.
+ */
+function readLengthDelimited(cursor) {
+    const length = readVarint(cursor);
+    if (length === null || length > MAX_FIELD_BYTES)
+        return null;
+    const start = cursor.pos;
+    const end = start + length;
+    if (end > cursor.end)
+        return null;
+    cursor.pos = end;
+    return { start, end };
+}
+/**
+ * Decode one `StringStringEntryProto` into a key/value pair.
+ *
+ * @param bytes The model buffer.
+ * @param start Offset the entry's payload starts at.
+ * @param end Offset the entry's payload ends at.
+ * @returns The pair, or `null` when either half is missing or undecodable.
+ */
+function readEntry(bytes, start, end) {
+    const cursor = { bytes, end, pos: start };
+    const decoder = new TextDecoder("utf-8", { fatal: false });
+    let key = null;
+    let value = null;
+    while (cursor.pos < end) {
+        const tag = readVarint(cursor);
+        if (tag === null)
+            return null;
+        const field = tag >>> 3;
+        const wireType = tag & 0x07;
+        if (wireType === WIRE_LENGTH_DELIMITED &&
+            (field === ENTRY_KEY_FIELD || field === ENTRY_VALUE_FIELD)) {
+            const range = readLengthDelimited(cursor);
+            if (range === null)
+                return null;
+            const text = decoder.decode(bytes.subarray(range.start, range.end));
+            if (field === ENTRY_KEY_FIELD)
+                key = text;
+            else
+                value = text;
+            continue;
+        }
+        if (!skipField(cursor, wireType))
+            return null;
+    }
+    if (key === null || value === null)
+        return null;
+    return [key, value];
+}
+/**
+ * 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 function readModelMetadata(model) {
+    const bytes = model instanceof Uint8Array ? model : new Uint8Array(model);
+    const cursor = { bytes, end: bytes.length, pos: 0 };
+    const metadata = {};
+    while (cursor.pos < cursor.end) {
+        const tag = readVarint(cursor);
+        if (tag === null)
+            break;
+        const field = tag >>> 3;
+        const wireType = tag & 0x07;
+        if (field === MODEL_METADATA_PROPS_FIELD && wireType === WIRE_LENGTH_DELIMITED) {
+            const range = readLengthDelimited(cursor);
+            if (range === null)
+                break;
+            const entry = readEntry(bytes, range.start, range.end);
+            if (entry)
+                metadata[entry[0]] = entry[1];
+            continue;
+        }
+        if (!skipField(cursor, wireType))
+            break;
+    }
+    return metadata;
+}
+/**
+ * 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 function modelNames(metadata) {
+    const raw = metadata?.names?.trim();
+    if (!raw || !raw.startsWith("{") || !raw.endsWith("}"))
+        return null;
+    const body = raw.slice(1, -1).trim();
+    if (!body)
+        return null;
+    const names = new Map();
+    const entryPattern = /(-?\d+)\s*:\s*(?:'((?:[^'\\]|\\.)*)'|"((?:[^"\\]|\\.)*)")/g;
+    let consumed = 0;
+    for (const match of body.matchAll(entryPattern)) {
+        const id = Number(match[1]);
+        const text = match[2] ?? match[3];
+        if (!Number.isInteger(id) || text === undefined)
+            return null;
+        names.set(id, unescapeQuoted(text));
+        consumed += match[0].length;
+    }
+    if (names.size === 0)
+        return null;
+    const separators = body.length - consumed;
+    if (separators > names.size * 3)
+        return null;
+    const ordered = [];
+    for (let id = 0; id < names.size; id += 1) {
+        const name = names.get(id);
+        if (name === undefined)
+            return null;
+        ordered.push(name);
+    }
+    return ordered;
+}
+/**
+ * Resolve the backslash escapes Python's `repr` emits inside a quoted string.
+ *
+ * @param text The quoted string's contents, escapes intact.
+ * @returns The same text with `\\`, `\'`, `\"`, `\n`, `\r` and `\t` resolved.
+ */
+function unescapeQuoted(text) {
+    return text.replace(/\\(.)/g, (_, char) => {
+        if (char === "n")
+            return "\n";
+        if (char === "r")
+            return "\r";
+        if (char === "t")
+            return "\t";
+        return char;
+    });
+}
+//# sourceMappingURL=metadata.js.map

package/dist/core/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/core/metadata.ts"],"names":[],"mappings":"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"}