{"record":{"id":"31f88fcd06b0afd0","repo":"roboflow/supervision","slug":"box-coordinates-must-be-real-valued","errorCode":null,"errorMessage":"box coordinates must be real-valued","messagePattern":"box coordinates must be real-valued","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/utils/iou_and_nms.py","lineNumber":150,"sourceCode":"        ValueError: If `overlap_metric` is not IOU or IOS.\n\n    Examples:\n        ```pycon\n        >>> import supervision as sv\n        >>> box_true = [100, 100, 200, 200]\n        >>> box_detection = [150, 150, 250, 250]\n        >>> sv.box_iou(box_true, box_detection, overlap_metric=sv.OverlapMetric.IOU)\n        0.142857...\n        >>> sv.box_iou(box_true, box_detection, overlap_metric=sv.OverlapMetric.IOS)\n        0.25\n\n        ```\n    \"\"\"\n    overlap_metric = OverlapMetric.from_value(overlap_metric)\n    box_true_array = np.asarray(box_true)\n    box_detection_array = np.asarray(box_detection)\n    if np.iscomplexobj(box_true_array) or np.iscomplexobj(box_detection_array):\n        raise TypeError(\"box coordinates must be real-valued\")\n\n    x_min_true, y_min_true, x_max_true, y_max_true = box_true_array\n    x_min_det, y_min_det, x_max_det, y_max_det = box_detection_array\n\n    x_min_inter = max(x_min_true, x_min_det)\n    y_min_inter = max(y_min_true, y_min_det)\n    x_max_inter = min(x_max_true, x_max_det)\n    y_max_inter = min(y_max_true, y_max_det)\n\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(","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/utils/iou_and_nms.py#L132-L168","documentation":"Raised by sv.box_iou when either bounding box contains complex-valued coordinates (np.iscomplexobj true). IoU is defined over real geometry, so complex inputs indicate an upstream data error and are rejected explicitly instead of producing nonsense values or a subtle NumPy cast.","triggerScenarios":"sv.box_iou(box_true, box_detection) where either argument is a complex dtype array, e.g. boxes produced by an FFT-based pipeline, complex-valued model outputs, or accidental dtype propagation (np.zeros(4, dtype=complex) defaults).","commonSituations":"Signal-processing or frequency-domain preprocessing leaking complex dtype into downstream box code; loading boxes from a complex-typed tensor (torch.complex) without conversion; a bug that mixes complex intermediates into coordinate arrays.","solutions":["Take the real part before calling: boxes = np.real(np.asarray(boxes))","Fix the upstream step that produced complex coordinates if complex values are unexpected","If complex tensors come from PyTorch, convert with .real before turning into numpy"],"exampleFix":"# before\niou = sv.box_iou(np.array([0,0,10,10], dtype=complex), [5,5,15,15])\n# after\niou = sv.box_iou(np.real(np.array([0,0,10,10])), [5,5,15,15])","handlingStrategy":"type-guard","validationCode":"import numpy as np\n\ndef as_real_boxes(boxes):\n    arr = np.asarray(boxes)\n    if np.iscomplexobj(arr):\n        arr = np.real(arr)\n    return arr","typeGuard":"def is_real_valued_boxes(boxes) -> bool:\n    import numpy as np\n    return not np.iscomplexobj(np.asarray(boxes))","tryCatchPattern":null,"preventionTips":["Call np.real on arrays coming from FFT/frequency-domain code before geometry ops","Avoid dtype=complex defaults when allocating coordinate arrays","Add a dtype assertion (arr.dtype.kind == 'f' or 'i') in data-loading code"],"tags":["iou","numpy","dtype","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}