{"record":{"id":"cc3b843532850f6d","repo":"roboflow/supervision","slug":"overlap-metric-overlap-metric-is-not-supported","errorCode":null,"errorMessage":"overlap_metric {overlap_metric} is not supported, only 'IOU' and 'IOS' are supported","messagePattern":"overlap_metric (.+?) is not supported, only 'IOU' and 'IOS' are supported","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/utils/iou_and_nms.py","lineNumber":177,"sourceCode":"\n    inter_w = max(0.0, _coordinate_difference(x_max_inter, x_min_inter))\n    inter_h = max(0.0, _coordinate_difference(y_max_inter, y_min_inter))\n\n    area_inter = inter_w * inter_h\n\n    area_true = _coordinate_difference(x_max_true, x_min_true) * _coordinate_difference(\n        y_max_true, y_min_true\n    )\n    area_det = _coordinate_difference(x_max_det, x_min_det) * _coordinate_difference(\n        y_max_det, y_min_det\n    )\n\n    if overlap_metric == OverlapMetric.IOU:\n        area_norm = area_true + area_det - area_inter\n    elif overlap_metric == OverlapMetric.IOS:\n        area_norm = min(area_true, area_det)\n    else:\n        raise ValueError(\n            f\"overlap_metric {overlap_metric} is not supported, \"\n            \"only 'IOU' and 'IOS' are supported\"\n        )\n\n    if area_norm <= 0.0:\n        return 0.0\n\n    return float(area_inter / area_norm)\n\n\ndef box_iou_batch(\n    boxes_true: npt.NDArray[np.number],\n    boxes_detection: npt.NDArray[np.number],\n    overlap_metric: OverlapMetric | str = OverlapMetric.IOU,\n) -> npt.NDArray[np.float32]:\n    \"\"\"\n    Compute pairwise overlap scores between batches of bounding boxes.\n","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/utils/iou_and_nms.py#L159-L195","documentation":"This ValueError is raised by the scalar (single-pair) box-overlap helper in supervision's IoU/NMS utilities when the `overlap_metric` argument is neither `OverlapMetric.IOU` nor `OverlapMetric.IOS`. The function computes intersection area and then picks a normalization denominator (union for IOU, smaller area for IOS); any other value has no defined normalization, so it fails fast instead of silently returning a wrong number. It is a guard against typos and against custom values injected by user code or stale versions.","triggerScenarios":"Calling the internal single-pair overlap function (e.g. via `box_iou_batch`-adjacent helpers or directly) with `overlap_metric` set to a string other than 'IOU'/'IOS' (e.g. 'GIoU', 'iou_' ), a misspelled enum like `OverlapMetric.IOUU`, or a raw value that bypassed `OverlapMetric.from_value` normalization.","commonSituations":"Copying a metric name from another library (torchvision `complete_box_iou`, Ultralytics) that supervision does not support; upgrading supervision after enum members were renamed and an old literal still lives in config; monkeypatching or wrapping internal helpers with a custom metric.","solutions":["Pass one of the two supported values: `sv.OverlapMetric.IOU` or `sv.OverlapMetric.IOS` (or the strings 'IOU' / 'IOS', which are normalized by `OverlapMetric.from_value`).","If you need a different overlap metric (GIoU, DIoU, etc.), compute it yourself from `box_iou_batch` outputs or use the underlying library directly — supervision does not support it.","Search your code/config for the exact metric string you passed and fix the typo (e.g. 'IOU ' with trailing space, 'iou' lowercase is fine only via from_value which upper-cases)."],"exampleFix":"// before\noverlap = sv.box_iou_batch(a, b, overlap_metric='GIoU')  # ValueError\n\n// after\noverlap = sv.box_iou_batch(a, b, overlap_metric=sv.OverlapMetric.IOU)","handlingStrategy":"validation","validationCode":"from supervision.detection.utils.iou_and_nms import OverlapMetric\nassert metric in (OverlapMetric.IOU, OverlapMetric.IOS)","typeGuard":"def is_valid_overlap_metric(v) -> bool:\n    return v in (OverlapMetric.IOU, OverlapMetric.IOS)","tryCatchPattern":null,"preventionTips":["Always pass enum members (sv.OverlapMetric.IOU) instead of string literals.","Normalize config strings once with sv.OverlapMetric.from_value at startup."],"tags":["argument-validation","enum","iou","detection"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}