roboflow/supervision · error · ValueError

`{name}` has shape {arr.shape}; expected (N, 8) for flat YOL

Error message

`{name}` has shape {arr.shape}; expected (N, 8) for flat YOLO format or (N, 4, 2) for corner format.

What it means

`oriented_box_iou_batch` accepts 2-D input only in the flat YOLO-OBB format (N, 8) — eight numbers per box describing the 4 corners. This error fires when a 2-D array has any other column count (e.g. (N, 4) axis-aligned xyxy, (N, 5) xywha, (N, 6)). The function cannot guess which of the 8 corner coordinates are missing, so it rejects the layout.

Source

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

        ```pycon
        >>> import numpy as np
        >>> import supervision as sv
        >>> a = np.array([[[0, 0], [2, 0], [2, 2], [0, 2]]], dtype=np.float32)
        >>> b = np.array([[[1, 0], [3, 0], [3, 2], [1, 2]]], dtype=np.float32)
        >>> 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"
        )

View on GitHub (pinned to 7f254d9784)

Solutions

1. Convert (x, y, w, h, angle) to 8-float corners with `cv2.boxPoints(cv2.RotatedRect(...))` and stack into (N, 8) or (N, 4, 2).
2. For axis-aligned boxes use `box_iou_batch`, not `oriented_box_iou_batch`.
3. Double-check `arr.shape == (N, 8)` or `arr.shape == (N, 4, 2)` immediately before calling.

Example fix

# before
ious = sv.oriented_box_iou_batch(dets.xyxy, dets.xyxy)  # (N, 4) -> ValueError

# after
ious = sv.box_iou_batch(dets.xyxy, dets.xyxy)

arr = np.asarray(arr, dtype=float)
if arr.ndim == 2 and arr.shape[1] != 8:
    if arr.shape[1] == 4:
        raise TypeError('axis-aligned xyxy: use box_iou_batch instead')
    raise ValueError('need (N, 8) or (N, 4, 2)')

def is_obb_flat(arr) -> bool:
    return np.asarray(arr).ndim == 2 and np.asarray(arr).shape[1] == 8

When it happens

Trigger: Passing `detections.xyxy` (N, 4) directly; passing rotated boxes in (x, y, w, h, angle) format (N, 5); slicing an (N, 8) array down to fewer columns before the call.

Common situations: Mixing axis-aligned supervision workflows with oriented-box ones; converting from a model that uses cv2 RotatedRect (5 floats) and assuming supervision takes it verbatim.

Related errors

• `{name}` has shape {arr.shape}; expected (N, 4, 2) — each bo
• `{name}` must be 2-D (N, 8) or 3-D (N, 4, 2), got shape {arr
• `{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/2a49a7c6b1ddfe59. Report an issue: GitHub.