nms

paddle.vision.ops. nms ( boxes: Tensor, iou_threshold: float = 0.3, scores: Tensor | None = None, category_idxs: Tensor | None = None, categories: Sequence[int] | None = None, top_k: int | None = None ) → Tensor [source]

This operator implements non-maximum suppression. Non-maximum suppression (NMS) is used to select one bounding box out of many overlapping bounding boxes in object detection. Boxes with IoU > iou_threshold will be considered as overlapping boxes, just one with highest score can be kept. Here IoU is Intersection Over Union, which can be computed by:

\[ \begin{align}\begin{aligned}IoU = \frac{intersection\_area(box1, box2)}{union\_area(box1, box2)}\\If scores are provided, input boxes will be sorted by their scores firstly.\end{aligned}\end{align} \]

If category_idxs and categories are provided, NMS will be performed with a batched style, which means NMS will be applied to each category respectively and results of each category will be concatenated and sorted by scores.

If K is provided, only the first k elements will be returned. Otherwise, all box indices sorted by scores will be returned.

Parameters

  • boxes (Tensor) – The input boxes data to be computed, it’s a 2D-Tensor with the shape of [num_boxes, 4]. The data type is float32 or float64. Given as [[x1, y1, x2, y2], …], (x1, y1) is the top left coordinates, and (x2, y2) is the bottom right coordinates. Their relation should be 0 <= x1 < x2 && 0 <= y1 < y2.

  • iou_threshold (float, optional) – IoU threshold for determine overlapping boxes. Default value: 0.3.

  • scores (Tensor|None, optional) – Scores corresponding to boxes, it’s a 1D-Tensor with shape of [num_boxes]. The data type is float32 or float64. Default: None.

  • category_idxs (Tensor|None, optional) – Category indices corresponding to boxes. it’s a 1D-Tensor with shape of [num_boxes]. The data type is int64. Default: None.

  • categories (list|tuple|None, optional) – A list of unique id of all categories. The data type is int64. Default: None.

  • top_k (int|None, optional) – The top K boxes who has higher score and kept by NMS preds to consider. top_k should be smaller equal than num_boxes. Default: None.

Returns

1D-Tensor with the shape of [num_boxes]. Indices of boxes kept by NMS.

Return type

Tensor

Examples

>>> import paddle
>>> paddle.seed(2023)

>>> boxes = paddle.rand([4, 4]).astype('float32')
>>> boxes[:, 2] = boxes[:, 0] + boxes[:, 2]
>>> boxes[:, 3] = boxes[:, 1] + boxes[:, 3]
>>> print(boxes)
Tensor(shape=[4, 4], dtype=float32, place=Place(cpu), stop_gradient=True,
[[0.86583614, 0.52014720, 1.12544549, 1.42540050],
 [0.42400089, 0.40641287, 1.39420986, 1.15078652],
 [0.51785129, 0.73292869, 1.49571705, 0.77608776],
 [0.42639419, 0.71958369, 0.63450879, 0.91689879]])

>>> out = paddle.vision.ops.nms(boxes, 0.1)
>>> print(out)
Tensor(shape=[3], dtype=int64, place=Place(cpu), stop_gradient=True,
[0, 2, 3])

>>> scores = paddle.to_tensor([0.6, 0.7, 0.4, 0.233])
>>> categories = [0, 1, 2, 3]
>>> category_idxs = paddle.to_tensor([2, 0, 0, 3], dtype="int64")
>>> out = paddle.vision.ops.nms(boxes,
...                             0.1,
...                             paddle.to_tensor(scores),
...                             paddle.to_tensor(category_idxs),
...                             categories,
...                             4)
>>> print(out)
Tensor(shape=[4], dtype=int64, place=Place(cpu), stop_gradient=True,
[1, 0, 2, 3])