roboflow/supervision · error · ValueError

`{name}` has shape {arr.shape}; expected (N, 4, 2) — each bo

Error message

`{name}` has shape {arr.shape}; expected (N, 4, 2) — each box must have exactly 4 corners with (x, y) coordinates.

What it means

`oriented_box_iou_batch` accepts oriented (rotated) boxes only as 3-D arrays of shape (N, 4, 2) — one box per row, exactly 4 corners, each an (x, y) pair — or as flat 2-D (N, 8). This error fires when the input is 3-D but the trailing dimensions are not (4, 2), e.g. (N, 2, 4), (N, 8, 1), or (N, 4, 3). The shape check exists because the algorithm reshapes to (-1, 4, 2) and treats each row as a quadrilateral; a wrong layout would silently produce garbage IoU values.

Source

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

        ValueError: If ``overlap_metric`` is not
            :attr:`~supervision.config.OverlapMetric.IOU` or
            :attr:`~supervision.config.OverlapMetric.IOS`.

    Examples:
        ```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:

View on GitHub (pinned to 7f254d9784)

Solutions

1. Reshape flat (N, 8) input to corners: `boxes.reshape(-1, 4, 2)`.
2. If your array is (N, 2, 4), transpose the last two axes: `arr.transpose(0, 2, 1)`.
3. If your polygons come from contours, first reduce each to exactly 4 vertices (e.g. `cv2.approxPolyDP` or `sv.approximate_polygon` with a 4-point target) before calling this function.

Example fix

# before
ious = sv.oriented_box_iou_batch(corners.transpose(0, 2, 1), b)  # shape (N, 2, 4)

# after
ious = sv.oriented_box_iou_batch(corners.transpose(0, 2, 1).reshape(-1, 4, 2), b)

def to_corner_format(arr):
    arr = np.asarray(arr, dtype=float)
    assert arr.ndim == 2 and arr.shape[1] == 8 or (arr.ndim == 3 and arr.shape[1:] == (4, 2))
    return arr.reshape(-1, 4, 2)

a = to_corner_format(a)

def is_valid_obb_array(arr) -> bool:
    arr = np.asarray(arr)
    return (arr.ndim == 3 and arr.shape[1:] == (4, 2)) or (arr.ndim == 2 and arr.shape[1] == 8)

When it happens

Trigger: Passing corners in (x, y, w, h, angle) order rolled into an array, transposing corner/coordinate axes (shape (N, 2, 4)), stacking polygons with more than 4 points from `cv2.findContours`, or reshaping an (N, 8) flat array incorrectly to (N, 8, 1).

Common situations: Converting from OpenCV rotated-rect or contour outputs (contours can have many points and must be approximated to 4); consuming OBB output from models (YOLO-OBB gives 8 floats per box) and reshaping with the wrong axis order; test fixtures hand-built with wrong axis order.

Related errors

• `{name}` has shape {arr.shape}; expected (N, 8) for flat YOL
• `{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/313bff601da05663. Report an issue: GitHub.