ai.onnx.NonMaxSuppression

ai.onnx · standard ONNX operator · ONNX opset ≥ 11

Description

Filters boxes whose intersection over union (IoU) with a higher-scoring selected box exceeds iou_threshold. Processing is independent per batch and class, and returns logical int64 [batch_index, class_index, box_index] triples with lossless uint32 WebGPU storage. The int64 selection limit uses a semantics-preserving saturating projection to uint32. Because the result length is data-dependent, its exact shape must be supplied. This package supports float32 boxes, scores, and thresholds.

See the ONNX NonMaxSuppression spec for the reference semantics.

Inputs

Outputs

Attributes

Default values (overridable per request):

Type constraints

Implementation variants

One implementation is selected per call from the device capabilities, the request shapes and the dtypes; these notes say what each one covers.

• bitmask_low_occupancy — For low (batch, class) group counts, a sorted-candidate pass and an all-pairs IoU bitmask pass expose pair-level parallelism; a mask-replay walk reproduces greedy suppression before compaction into selected_indices.
• groups_parallel — Workgroup-parallel greedy selection keeps sticky suppression flags in global scratch, followed by stable batch/class compaction.
• groups_private — Each invocation owns a bounded bitset for its strided candidates. Scores below the threshold are discarded once before greedy selection, avoiding their repeated IoU work and global suppression traffic.

Files

• metadata.json — kernel metadata (id, digests, per-variant templates, provenance)
• manifest.json — the op contract (source of truth)
• test.json — correctness cases
• bench.json — benchmark + tuning cases
• nms-bitmask.wgsl.jinja
• nms-groups-compact.wgsl.jinja
• nms-groups-select.wgsl.jinja
• non-max-suppression.wgsl.jinja

Use with @huggingface/kernels

npm install --save-exact @huggingface/kernels@0.0.1-preview.2

Outputs with inferable metadata are allocated automatically. Explicit outputs entries request optional results or provide metadata that cannot be inferred from the supplied inputs and attributes.

This example supplies explicit metadata for:

• selected_indices

The version: 1 option selects the published kernel contract; it is independent of any operator opset, contrib since_version, or model version. It follows the v1 branch as fixes land. To pin exact artifact bytes, pass a 40-character commit revision instead of version.

Replace each *Data placeholder with a typed array containing the corresponding input data.

import { getKernel } from "@huggingface/kernels";

const kernel = await getKernel("webgpu-kernels/ai.onnx.NonMaxSuppression", { version: 1 });
// Explicit destinations request optional results or supply metadata that cannot be inferred.
const { selected_indices } = await kernel({
  boxes: { data: boxesData, shape: [1, 1, 4] },
  scores: { data: scoresData, shape: [1, 1, 1] },
  max_output_boxes_per_class: { data: max_output_boxes_per_classData, shape: [] },
  iou_threshold: { data: iou_thresholdData, shape: [] },
  score_threshold: { data: score_thresholdData, shape: [] },
}, {
  outputs: { selected_indices: { shape: [1, 3], dtype: "int64" } },
});