{"record":{"id":"f8888add9b2b7f56","repo":"roboflow/supervision","slug":"name-must-be-2-d-n-8-or-3-d-n-4-2-got","errorCode":null,"errorMessage":"`{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr.shape}.","messagePattern":"`(.+?)` must be 2-D \\(N, 8\\) or 3-D \\(N, 4, 2\\), got shape (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/utils/iou_and_nms.py","lineNumber":546,"sourceCode":"        >>> sv.oriented_box_iou_batch(a, b)  # doctest: +ELLIPSIS\n        array([[0.333...]])\n\n        ```\n    \"\"\"\n\n    for name, arr in ((\"boxes_true\", boxes_true), (\"boxes_detection\", boxes_detection)):\n        if arr.ndim == 3 and arr.shape[1:] != (4, 2):\n            raise ValueError(\n                f\"`{name}` has shape {arr.shape}; expected (N, 4, 2) \"\n                f\"— each box must have exactly 4 corners with (x, y) coordinates.\"\n            )\n        elif arr.ndim == 2 and arr.shape[1] != 8:\n            raise ValueError(\n                f\"`{name}` has shape {arr.shape}; expected (N, 8) for flat \"\n                f\"YOLO format or (N, 4, 2) for corner format.\"\n            )\n        elif arr.ndim not in (2, 3):\n            raise ValueError(\n                f\"`{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr.shape}.\"\n            )\n\n    if overlap_metric == OverlapMetric.IOU:\n        normalize_by_union = True\n    elif overlap_metric == OverlapMetric.IOS:\n        normalize_by_union = False\n    else:\n        raise ValueError(\n            f\"overlap_metric {overlap_metric} is not supported, \"\n            \"only 'IOU' and 'IOS' are supported\"\n        )\n\n    # Capture identity before reshape: NMS / NMM pass the same array twice, so\n    # the matrix is symmetric and we can compute only its upper triangle.\n    is_self_comparison = boxes_true is boxes_detection\n    boxes_true = cast(\n        npt.NDArray[np.floating], boxes_true.reshape(-1, 4, 2).astype(np.float64)","sourceCodeStart":528,"sourceCodeEnd":564,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/utils/iou_and_nms.py#L528-L564","documentation":"`oriented_box_iou_batch` only accepts 2-D (N, 8) or 3-D (N, 4, 2) box arrays. This branch fires for any other dimensionality — a single box passed as (4, 2) without the leading N axis, a 1-D vector of 8 floats, a 4-D batch from a multi-frame tensor, or a Python list that NumPy coerces to an unexpected rank. The reshape to (-1, 4, 2) downstream requires a known 2/3-D layout.","triggerScenarios":"Passing one box as `np.array([[0,0],[2,0],[2,2],[0,2]])` (shape (4, 2)) instead of `[box]` (shape (1, 4, 2)); forwarding a (B, N, 4, 2) batch tensor from a video model without flattening the batch axis.","commonSituations":"Single-box edge cases in loops; batching video frames where an extra leading dimension survives; lists of variable-length polygons that ragged-stack to 1-D object arrays.","solutions":["Wrap a single box: `np.array([box], dtype=float).reshape(1, 4, 2)`.","Flatten extra batch axes: `boxes.reshape(-1, 4, 2)`.","Ensure homogeneous lists so NumPy builds a proper 2/3-D array, not an object array."],"exampleFix":"# before\niou = sv.oriented_box_iou_batch(box, box)  # box.shape == (4, 2)\n\n# after\nbox = box.reshape(1, 4, 2)\niou = sv.oriented_box_iou_batch(box, box)","handlingStrategy":"validation","validationCode":"arr = np.asarray(arr, dtype=float)\nassert arr.ndim in (2, 3), f'bad rank: {arr.shape}'\ncorners = arr.reshape(-1, 4, 2)","typeGuard":"def has_obb_rank(arr) -> bool:\n    return np.asarray(arr).ndim in (2, 3)","tryCatchPattern":null,"preventionTips":["Wrap single boxes in a list before array creation.","Flatten batch axes with reshape(-1, 4, 2) in video pipelines."],"tags":["shape-validation","oriented-boxes","iou","numpy","detection"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}