Table of Contents
Contents

fiftyone.utils.iou¶

Intersection over union (IoU) utilities.

Copyright 2017-2025, Voxel51, Inc.
voxel51.com

Functions:

compute_ious(preds, gts[, iscrowd, …])

Computes the pairwise IoUs between the predicted and ground truth objects.

compute_segment_ious(preds, gts[, sparse])

Computes the pairwise IoUs between the predicted and ground truth temporal detections.

compute_max_ious(sample_collection, label_field)

Populates an attribute on each label in the given spatial field(s) that records the max IoU between the object and another object in the same sample/frame.

find_duplicates(sample_collection, label_field)

Returns IDs of duplicate labels in the given field of the collection, as defined as labels with an IoU greater than a chosen threshold with another label in the field.

compute_bbox_iou(gt, pred[, gt_crowd])

Computes the IoU between the given ground truth and predicted detections.
fiftyone.utils.iou.compute_ious(preds, gts, iscrowd=None, classwise=False, use_masks=False, use_boxes=False, tolerance=None, sparse=False, error_level=1)¶

Computes the pairwise IoUs between the predicted and ground truth objects.

For polylines, IoUs are computed as solid shapes when filled=True` and "IoUs" are computed using `object keypoint similarity <https://cocodataset.org/#keypoints-eval>`_ when ``filled=False.

For keypoints, “IoUs” are computed via object keypoint similarity.

Parameters

  • preds – a list of predicted fiftyone.core.labels.Detection, fiftyone.core.labels.Polyline, or fiftyone.core.labels.Keypoints instances

  • gts – a list of ground truth fiftyone.core.labels.Detection, fiftyone.core.labels.Polyline, or fiftyone.core.labels.Keypoints instances

  • iscrowd (None) – an optional name of a boolean attribute or boolean function to apply to each label that determines whether a ground truth object is a crowd. If provided, the area of the predicted object is used as the “union” area for IoU calculations involving crowd objects

  • classwise (False) – whether to consider objects with different label values as always non-overlapping (True) or to compute IoUs for all objects regardless of label (False)

  • use_masks (False) – whether to compute IoUs using the instances masks in the mask attribute of the provided objects, which must be fiftyone.core.labels.Detection instances

  • use_boxes (False) – whether to compute IoUs using the bounding boxes of the provided fiftyone.core.labels.Polyline instances rather than using their actual geometries

  • tolerance (None) – a tolerance, in pixels, when generating approximate polylines for instance masks. Typical values are 1-3 pixels. By default, IoUs are computed directly on the dense pixel masks

  • sparse (False) – whether to return a sparse dict of non-zero IoUs rather than a full matrix

  • error_level (1) –

    the error level to use when manipulating instance masks or polylines. Valid values are:

    • 0: raise geometric errors that are encountered

    • 1: log warnings if geometric errors are encountered

    • 2: ignore geometric errors

    If error_level > 0, any calculation that raises a geometric error will default to an IoU of 0

Returns

a num_preds x num_gts array of IoUs when sparse=False, or a dict of the form d[pred.id] = [(gt.id, iou), ...] when sparse=True

fiftyone.utils.iou.compute_segment_ious(preds, gts, sparse=False)¶

Computes the pairwise IoUs between the predicted and ground truth temporal detections.

Parameters
Returns

a num_preds x num_gts array of segment IoUs when sparse=False, or a dict of the form d[pred.id] = [(gt.id, iou), ...] when sparse=True

fiftyone.utils.iou.compute_max_ious(sample_collection, label_field, other_field=None, iou_attr='max_iou', id_attr=None, progress=None, **kwargs)¶

Populates an attribute on each label in the given spatial field(s) that records the max IoU between the object and another object in the same sample/frame.

If other_field is provided, IoUs are computed between objects in label_field and other_field.

If no other_field is provided, IoUs are computed between objects in label_field alone, excluding the object itself.

Parameters
fiftyone.utils.iou.find_duplicates(sample_collection, label_field, iou_thresh=0.999, method='simple', progress=None, **kwargs)¶

Returns IDs of duplicate labels in the given field of the collection, as defined as labels with an IoU greater than a chosen threshold with another label in the field.

The following duplicate removal methods are supported:

  • method="simple": mark the latter label in every pair of labels whose IoU exceeds the threshold. This may remove more labels than the greedy method

  • method="greedy": apply a greedy method to mark the fewest number of labels as duplicate such that no non-duplicate labels have IoU greater than the specified threshold. This method is more computationally expensive than the simple method

Parameters
Returns

a list of IDs of duplicate labels

fiftyone.utils.iou.compute_bbox_iou(gt, pred, gt_crowd=False)¶

Computes the IoU between the given ground truth and predicted detections.

Parameters
Returns

the IoU, in [0, 1]