# fiftyone.utils.iou Intersection over union (IoU) utilities. Copyright 2017-2026, Voxel51, Inc.
[voxel51.com](https://voxel51.com/)

**Functions:** | [`compute_ious`](#fiftyone.utils.iou.compute_ious)(preds, gts[, iscrowd, ...]) | Computes the pairwise IoUs between the predicted and ground truth objects. | |--------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`compute_segment_ious`](#fiftyone.utils.iou.compute_segment_ious)(preds, gts[, sparse]) | Computes the pairwise IoUs between the predicted and ground truth temporal detections. | | [`compute_max_ious`](#fiftyone.utils.iou.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`](#fiftyone.utils.iou.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`](#fiftyone.utils.iou.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, keypoint_sigmas=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 `_ when ``filled=False`. For keypoints, “IoUs” are computed via [object keypoint similarity](https://cocodataset.org/#keypoints-eval). You can pass `keypoint_sigmas` to customize the per-keypoint OKS falloff. * **Parameters:** * **preds** – a list of predicted [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection), [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) instances * **gts** – a list of ground truth [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection), [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#fiftyone.core.labels.Polyline), or [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#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`](fiftyone.core.labels.md#fiftyone.core.labels.Detection) instances * **use_boxes** (*False*) – whether to compute IoUs using the bounding boxes of the provided [`fiftyone.core.labels.Polyline`](fiftyone.core.labels.md#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 * **keypoint_sigmas** (*None*) – an optional list of per-keypoint OKS sigmas to use when comparing [`fiftyone.core.labels.Keypoint`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoint) instances * **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:** * **preds** – a list of predicted [`fiftyone.core.labels.TemporalDetection`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetection) instances * **gts** – a list of ground truth [`fiftyone.core.labels.TemporalDetection`](fiftyone.core.labels.md#fiftyone.core.labels.TemporalDetection) instances * **sparse** (*False*) – whether to return a sparse dict of non-zero IoUs rather than a full matrix * **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:** * **sample_collection** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) * **label_field** – a label field of type [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections), [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines), or [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) * **other_field** (*None*) – another label field of type [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections), [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines), or [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) * **iou_attr** ( *"max_iou"*) – the label attribute in which to store the max IoU * **id_attr** (*None*) – an optional attribute in which to store the label ID of the maximum overlapping label * **progress** (*None*) – whether to render a progress bar (True/False), use the default value `fiftyone.config.show_progress_bars` (None), or a progress callback function to invoke instead * **\*\*kwargs** – optional keyword arguments for [`compute_ious()`](#fiftyone.utils.iou.compute_ious) ### 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:** * **sample_collection** – a [`fiftyone.core.collections.SampleCollection`](fiftyone.core.collections.md#fiftyone.core.collections.SampleCollection) * **label_field** – a label field of type [`fiftyone.core.labels.Detections`](fiftyone.core.labels.md#fiftyone.core.labels.Detections), [`fiftyone.core.labels.Polylines`](fiftyone.core.labels.md#fiftyone.core.labels.Polylines), or [`fiftyone.core.labels.Keypoints`](fiftyone.core.labels.md#fiftyone.core.labels.Keypoints) * **iou_thresh** (*0.999*) – the IoU threshold to use to determine whether labels are duplicates * **method** ( *"simple"*) – the duplicate removal method to use. The supported values are `("simple", "greedy")` * **progress** (*None*) – whether to render a progress bar (True/False), use the default value `fiftyone.config.show_progress_bars` (None), or a progress callback function to invoke instead * **\*\*kwargs** – optional keyword arguments for [`compute_ious()`](#fiftyone.utils.iou.compute_ious) * **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:** * **gt** – a [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection) * **pred** – a [`fiftyone.core.labels.Detection`](fiftyone.core.labels.md#fiftyone.core.labels.Detection) * **gt_crowd** (*False*) – whether the ground truth object is a crowd * **Returns:** the IoU, in `[0, 1]`