NonMaximumSuppressionOp

NonMaximumSuppressionOp applies CV-CUDA suppression to aligned detection boxes and confidence scores. It produces a mask indicating which original candidates a downstream stage should retain.

The mask preserves candidate indexing. A downstream stage gathers or draws entries with nonzero mask values; the operator does not return a compacted box list, sorted indices, or rendered detections.

Ports and data contract

Port	Memory	Queue	Trigger	Contract
`boxes`	CUDA device	1	`OnAligned`	S16 `[N,W,4]`; each candidate is (x,y,width,height).
`scores`	CUDA device	1	`OnAligned`	F32 `[N,W]`, with batch and candidate dimensions matching `boxes`.
`mask`	CUDA device, contiguous	N/A	Same activation	New U8 `[N,W]`; nonzero means retain the corresponding candidate. Metadata comes from `boxes`.

The two inputs must have matching capture times and use the same CUDA device. A partial pair does not produce a mask.

Input arguments

NonMaximumSuppressionOpParams defines:

Parameter	Default and Meaning
`max_boxes`	`1`; positive maximum W per batch item, recompile-required and required on complete load.
`max_batch_size`	`1`; N within 1–65,535, recompile-required and required on complete load.
`score_threshold`	`0.F`; inclusive minimum score, range [0,1]. CompileTime.
`iou_threshold`	`0.5F`; permitted overlap threshold, range (0,1]. CompileTime.

All values are frozen for the accepted plan; OperatorHandle::set_params() is not a live threshold change. The mask bound is max_boxes × max_batch_size bytes. Capacity validation also requires the corresponding tightly packed boxes to fit the signed 32-bit limit, so that product must not exceed floor(INT32_MAX/8); actual padded input spans are checked separately.

The operator exposes no class-label or top-k parameter. Convert a detector's outputs into the required candidate representation and grouping before this stage. Another framework's NMS interface may not apply.

Example

Include <holoscan/vision/non_maximum_suppression_op.hpp>. In composition with graph already declared:

auto nms = graph.op<holoscan::vision::NonMaximumSuppressionOp>("nms");
nms.set_params(holoscan::vision::NonMaximumSuppressionOpParams{
    .max_boxes = 3,
    .max_batch_size = 1U,
    .score_threshold = 0.5F,
    .iou_threshold = 0.5F,
});

Connect the producer's boxes and scores to the matching input ports and consume nms->mask. In the complete pipeline's first frame, the first two boxes are identical (0,0,10,10) with scores 0.9 and 0.8; the third is (20,20,5,5) with score 0.7. Its expected mask is [1,0,1]. The middle entry remains position one with a zero mask; it is not removed from the array.

That result illustrates this programmed input and threshold choice. Keep downstream interpretation tied to the original candidate indexing and check actual results when changing data or thresholds.

Build

Follow Build the SDK on AGX Orin for the SDK build and installation. Link the installed holoscan::vision target in the application.

Related examples and concepts

Examples

Vision Pipeline Example supplies a complete checked source, transformations and validating sinks.

Concepts

Dynamic Graph Behavior distinguishes authoring parameters from admitted runtime publication.
Building Graphs and Queue Policies explains buffering and pressure.
InferenceOp describes model outputs that may need an explicit candidate-format conversion.
RemapOp contrasts exact joins with bounded latest-map reuse.

Source You can find the source code at NonMaximumSuppressionOp.

Official documentation

NVIDIA Holoscan SDK User Guide provides the official operator and application reference.

❯