Non-maximum suppression (NMS) selects a subset of an object detector’s candidate boxes: it keeps a high-scoring box and removes lower-scoring boxes that overlap it beyond a chosen threshold. It does not normally improve or average box coordinates. The right result depends on the score ranking, IoU threshold, class policy, confidence cutoff, and output limit—not on one universal IoU setting.
Why object detectors produce duplicate boxes
A detector can predict several boxes for one object because multiple anchors or feature-map locations cover it, different feature-pyramid levels contribute candidates, or regression produces slightly different boxes. Test-time augmentation and tiled-image inference can add further candidates. NMS is usually applied after boxes are decoded and scored, before results are displayed or passed to a tracker.
A detection commonly contains coordinates, a score, and a class label. The score ranks candidates; depending on the model, it may be objectness, class confidence, a product of scores, or another value. It is not necessarily a calibrated probability. If ranking scores are poor, NMS can keep the wrong candidate even when its geometry looks plausible.
Understand IoU before tuning NMS
Intersection over Union (IoU) measures the overlap of two boxes as the area of their intersection divided by the area of their union:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
IoU(A, B) = area(A ∩ B) / area(A ∪ B)
- IoU 0 means the boxes do not overlap.
- IoU 1 means they are identical.
- Values between 0 and 1 indicate partial overlap.
For axis-aligned boxes represented as (x1, y1, x2, y2), intersection width and height are the positive portions of min(x2) − max(x1) and min(y2) − max(y1). Compute each box area using its width times height, then divide the intersection area by the union. A common implementation uses no +1 in width or height; that convention must match the framework and annotation pipeline.
How greedy hard NMS works
- Discard candidates below the confidence threshold.
- Sort the remaining candidates by descending score.
- Keep the highest-scoring candidate.
- Compare it with each remaining candidate and remove boxes whose IoU is above the NMS threshold.
- Repeat until no candidates remain or the output limit is reached.
The comparison boundary matters: Torchvision documents suppression when IoU is greater than the threshold. Do not assume every library handles an exact equality boundary identically; check the chosen API. Torchvision NMS documentation also specifies that kept indices are returned in decreasing score order.
For example, if two predictions cover nearly the same object and have scores 0.95 and 0.82, hard NMS keeps the 0.95 candidate if their IoU exceeds the configured threshold. A separate, non-overlapping box with score 0.88 remains. This selects an existing prediction; it does not average the first pair’s coordinates.
Use the coordinate format expected by the API
Coordinate ordering mistakes can make valid detections look like an NMS failure. Torchvision expects (x1, y1, x2, y2); TensorFlow’s NMS uses [y1, x1, y2, x2]. TensorFlow accepts absolute or normalized coordinates when their ordering is correct. Convert center-width-height outputs to corners before calling an API that expects corners, and make sure boxes are in the intended image coordinate space after resizing, letterboxing, or tiling. See the Torchvision API and TensorFlow API.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
Framework examples
PyTorch and Torchvision
import torch
from torchvision.ops import nms
# xyxy: [x1, y1, x2, y2]
boxes = torch.tensor([
[10, 10, 100, 100],
[15, 15, 98, 98],
[200, 200, 260, 260],
], dtype=torch.float32)
scores = torch.tensor([0.95, 0.82, 0.88])
keep = nms(boxes, scores, iou_threshold=0.5)
final_boxes = boxes[keep]
final_scores = scores[keep]nms returns indices into the input. Torchvision warns that tied scores can lead CPU and GPU implementations to select different boxes when those boxes meet the suppression condition. Test both backends if deterministic selection matters. Torchvision’s NMS reference documents the behavior.
TensorFlow
import tensorflow as tf
# yxyx: [y1, x1, y2, x2]
boxes = tf.constant([
[10, 10, 100, 100],
[15, 15, 98, 98],
[200, 200, 260, 260],
], dtype=tf.float32)
scores = tf.constant([0.95, 0.82, 0.88], dtype=tf.float32)
keep = tf.image.non_max_suppression(
boxes=boxes,
scores=scores,
max_output_size=100,
iou_threshold=0.5,
score_threshold=0.0,
)
final_boxes = tf.gather(boxes, keep)
final_scores = tf.gather(scores, keep)TensorFlow returns indices into the original collection, so gather the boxes and scores if you need the selected records. Its operation greedily selects boxes in descending score order and exposes both an IoU threshold and score threshold. TensorFlow’s API reference describes its inputs and outputs.
OpenCV
import cv2
indices = cv2.dnn.NMSBoxes(
bboxes=boxes,
scores=scores,
score_threshold=0.25,
nms_threshold=0.45,
top_k=100,
)OpenCV’s DNN API also documents adaptive-threshold and top-k parameters, as well as rotated-box NMS. Its argument names and box conventions should be checked against the API version in use. OpenCV NMSBoxes documentation.
Choose an IoU threshold with validation data
A lower threshold suppresses boxes more aggressively: it can reduce duplicates, but can also remove legitimate nearby objects. A higher threshold permits more overlap, which may preserve crowded instances while allowing more duplicates. The threshold is not a measure of how accurate an individual box is; it sets the overlap tolerated between candidates before suppression.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsRank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Ultralytics documents 0.7 as a configuration default in its general configuration reference. That is a library default, not evidence that 0.7 is best for another model, dataset, or product. Ultralytics configuration reference.
- Freeze model weights and preprocessing so the comparison isolates post-processing.
- Run the same representative validation set across a sweep, for example 0.30 to 0.80 in 0.05 increments.
- Measure precision, recall, F1, mAP at the evaluation IoU criteria, duplicates per image, missed objects in crowded scenes, and per-class results.
- Inspect difficult subsets separately: small objects, partial occlusion, dense scenes, similar classes, and images with no target objects.
- Choose based on the application’s error costs, then repeat validation when the model, image size, confidence cutoff, class list, or inference backend changes.
A counting system, search index, visual overlay, and security application can reasonably make different trade-offs. Do not tune from a handful of attractive examples alone.
Keep confidence, IoU, and output limits distinct
| Setting | What it filters or controls | Typical effect |
|---|---|---|
| Confidence threshold | Low-scoring candidate boxes | Changes candidate volume and the balance of false positives against missed detections. |
| IoU threshold | Overlapping lower-scoring boxes during NMS | Controls duplicate suppression versus retention of overlapping instances. |
| Maximum detections | The number of outputs retained | Caps final output and downstream cost; a low cap can discard valid objects. |
If background false positives are the problem, lowering the IoU threshold is usually aimed at the wrong stage; review confidence filtering and score calibration. If duplicate boxes are the problem, investigate NMS. TensorFlow exposes score and IoU thresholds, OpenCV exposes score and NMS thresholds, and Ultralytics has separate confidence, IoU, and detection-limit controls. TensorFlow, OpenCV, and Ultralytics configuration.
Choose class-aware or class-agnostic suppression
Class-aware NMS
Class-aware NMS runs independently per class, so an overlapping person box does not suppress a bicycle box. It is a sensible starting point when distinct categories can legitimately overlap, including nested objects such as a face inside a person box or a logo on a product. Torchvision’s batched_nms accepts category indices and does not suppress across different categories. Torchvision operators.
Recommended Free Tools
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Class-agnostic NMS
Class-agnostic NMS compares boxes regardless of their labels. It can remove competing class predictions for one physical object, but may discard valid overlapping objects from different classes. Ultralytics exposes an agnostic_nms option for this behavior. Ultralytics configuration reference.
Use class-agnostic behavior only when error analysis shows cross-class duplicates are more harmful than losing legitimate overlaps. For class-aware processing, either call NMS once per class or use a batched operation with labels. A single global call to ordinary NMS is not class-aware.
Hard NMS, Soft-NMS, and other options
| Method | What it does | When to evaluate it |
|---|---|---|
| Hard NMS | Removes lower-scoring boxes above the overlap threshold. | Use as a straightforward baseline when one surviving candidate per object is suitable. |
| Soft-NMS | Reduces scores of overlapping boxes rather than immediately deleting them. | Test for crowded scenes or when hard suppression appears to lose real instances; ensure downstream logic can handle adjusted scores. |
| DIoU-NMS | Uses center-distance information in addition to overlap in the proposed criterion. | Evaluate for particular crowded or elongated-object failures; it is not an automatic improvement. |
| Weighted box fusion | Merges predictions using a separate coordinate-fusion approach rather than selecting one box. | Consider when combining multiple model predictions and coordinate averaging is appropriate. |
| Matrix NMS or learned NMS | Alternative suppression or ranking approaches, including methods developed for particular tasks. | Consider when the task and implementation specifically support them, such as instance segmentation for Matrix NMS. |
| NMS-free detector | An end-to-end detector is designed to produce outputs without this post-processing heuristic. | Consider when selecting or redesigning a detector, not as a drop-in setting for a model whose pipeline expects NMS. |
TensorFlow’s tf.image.non_max_suppression_with_scores supports Soft-NMS: a positive soft_nms_sigma enables Gaussian score decay; with sigma zero, it falls back to standard NMS, and TensorFlow says the IoU threshold is ignored in Soft-NMS mode. TensorFlow Soft-NMS API. OpenCV documents softNMSBoxes in its DNN documentation. OpenCV DNN documentation.
The original Soft-NMS paper reported improvements on the evaluated detection systems, not a universal gain across models and datasets. Soft-NMS paper. DIoU methods incorporate center distance into geometric criteria. Distance-IoU Loss paper. Research has also proposed NMS-free detection, while a WACV 2024 paper examines confidence estimates and whether NMS remains useful. These are design alternatives, not proof that conventional NMS is obsolete in every deployment. NMS-free object detection; WACV 2024 NMS analysis.
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Handle crowded scenes, small objects, and nested boxes
- Crowds and stacked objects: People, cars, birds, products, cells, and other close instances can have substantial overlap. Consider raising the threshold, class-aware processing, or Soft-NMS, then measure recall by crowd density. Better localization, instance segmentation, or task-specific grouping may address a root cause more effectively.
- Small objects: The same pixel shift can change IoU much more for a small box than for a large one. Consider size-aware or per-class policies only if validation shows a real improvement; complexity alone is not a reason to add separate thresholds.
- Nested objects: A small box inside a larger one may be a separate valid detection. Class-aware NMS tends to preserve different labels; class-agnostic NMS can suppress one if overlap is high.
- Tiled inference: Per-tile NMS does not necessarily merge duplicates from neighboring tiles. If duplicate boxes cross tile boundaries, post-process candidates together after transforming them into the same image coordinates.
Debug common NMS failures
Duplicate boxes remain
- Check whether the IoU threshold is too high or whether same-object predictions have different labels and are preserved by class-aware NMS.
- Review confidence filtering and calculate IoU for the suspected duplicates.
- Check tile boundaries, image scaling, and whether all boxes were transformed back to the original image coordinates.
- Confirm the nearby boxes are actually duplicates rather than distinct objects.
Nearby objects disappear
- Check for an overly low IoU threshold, class-agnostic suppression, oversized predicted boxes, or an output limit that is too small.
- Try class-aware NMS or Soft-NMS and assess recall on crowded subsets.
- Review localization quality or consider a task-specific model if boxes cannot separate the instances.
No boxes are returned
- Inspect whether confidence filtering removes every candidate and whether scores use the expected scale.
- Check box validity, tensor shape, class and batch indexing, and whether the output cap is zero.
- Verify candidates were not all filtered earlier or suppressed by the configured policy.
Results differ between deployments
- Compare coordinate order, precision, pre-NMS filters, maximum-output behavior, and whether both paths use hard NMS.
- Check equal-score tie behavior and CPU/GPU implementation differences; Torchvision specifically documents possible different selections for tied scores.
- Compare actual kept boxes and indices, not only detection counts or score summaries.
Validate inputs and make post-processing reproducible
Before NMS, reject or handle boxes with x2 <= x1 or y2 <= y1, NaN or infinite values, unexpected image bounds, or coordinates left in a resized or tiled space. NMS cannot repair invalid boxes. Also check whether the model API already returns post-NMS results; applying a second NMS pass can remove valid detections.
Test zero boxes, zero scores, all candidates below confidence, and a case where all candidates are suppressed. Confirm that the empty result has the expected shape, dtype, and device. For ties, define a deterministic secondary ordering if the application permits it, and test the exact backend rather than relying on undocumented input order. A low max_output_size, OpenCV top_k, or model-specific cap can discard valid detections even when the overlap threshold is sound. TensorFlow requires max_output_size; Ultralytics documents limits including max_det and max_nms. TensorFlow NMS, OpenCV NMSBoxes, and Ultralytics NMS reference.
For a class-aware implementation in Torchvision, use batched_nms with class indices, or run NMS separately for each class and combine the kept indices in score order. Avoid accidentally applying one class-agnostic call when categories should be independent. Torchvision batched NMS operators.
Unit tests worth keeping in the pipeline
- Overlapping duplicates: Two high-IoU boxes with different scores should leave the higher-scoring candidate under hard NMS.
- Non-overlapping boxes: Candidates below the overlap threshold should both remain.
- Different classes: Verify that class-aware processing retains overlapping distinct labels and that class-agnostic processing follows the intended policy.
- Threshold boundary: Test IoU exactly at and near the cutoff for the backend in use.
- Equal scores: Compare CPU and GPU selection where applicable.
- Empty and invalid input: Verify output compatibility and that invalid coordinates are rejected or filtered.
Log candidate counts before and after confidence filtering, score range, confidence and IoU thresholds, class policy, output cap, and the number kept. Store the complete post-processing configuration with the model version so a deployment can be reproduced.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
