roboflow/supervision · error · ValueError

`{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr

Error message

`{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr.shape}.

What it means

`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.

Source

Thrown at src/supervision/detection/utils/iou_and_nms.py:546

        >>> sv.oriented_box_iou_batch(a, b)  # doctest: +ELLIPSIS
        array([[0.333...]])

        ```
    """

    for name, arr in (("boxes_true", boxes_true), ("boxes_detection", boxes_detection)):
        if arr.ndim == 3 and arr.shape[1:] != (4, 2):
            raise ValueError(
                f"`{name}` has shape {arr.shape}; expected (N, 4, 2) "
                f"— each box must have exactly 4 corners with (x, y) coordinates."
            )
        elif arr.ndim == 2 and arr.shape[1] != 8:
            raise ValueError(
                f"`{name}` has shape {arr.shape}; expected (N, 8) for flat "
                f"YOLO format or (N, 4, 2) for corner format."
            )
        elif arr.ndim not in (2, 3):
            raise ValueError(
                f"`{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr.shape}."
            )

    if overlap_metric == OverlapMetric.IOU:
        normalize_by_union = True
    elif overlap_metric == OverlapMetric.IOS:
        normalize_by_union = False
    else:
        raise ValueError(
            f"overlap_metric {overlap_metric} is not supported, "
            "only 'IOU' and 'IOS' are supported"
        )

    # Capture identity before reshape: NMS / NMM pass the same array twice, so
    # the matrix is symmetric and we can compute only its upper triangle.
    is_self_comparison = boxes_true is boxes_detection
    boxes_true = cast(
        npt.NDArray[np.floating], boxes_true.reshape(-1, 4, 2).astype(np.float64)

View on GitHub (pinned to 7f254d9784)

Solutions

1. Wrap a single box: `np.array([box], dtype=float).reshape(1, 4, 2)`.
2. Flatten extra batch axes: `boxes.reshape(-1, 4, 2)`.
3. Ensure homogeneous lists so NumPy builds a proper 2/3-D array, not an object array.

Example fix

# before
iou = sv.oriented_box_iou_batch(box, box)  # box.shape == (4, 2)

# after
box = box.reshape(1, 4, 2)
iou = sv.oriented_box_iou_batch(box, box)

arr = np.asarray(arr, dtype=float)
assert arr.ndim in (2, 3), f'bad rank: {arr.shape}'
corners = arr.reshape(-1, 4, 2)

def has_obb_rank(arr) -> bool:
    return np.asarray(arr).ndim in (2, 3)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• `{name}` has shape {arr.shape}; expected (N, 4, 2) — each bo
• `{name}` has shape {arr.shape}; expected (N, 8) for flat YOL
• `{name}` has shape {arr.shape}; expected (N, 5) or (N, 6).
• box coordinates must be real-valued
• overlap_metric {overlap_metric} is not supported, only 'IOU'

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/f8888add9b2b7f56. Report an issue: GitHub.