keras-team/keras · error · ValueError

When using relative bounding box formats (e.g. `rel_yxyx`) t

Error message

When using relative bounding box formats (e.g. `rel_yxyx`) the `image_shape` argument must be provided.Received `image_shape`: {image_shape}

What it means

compute_iou supports relative bounding box formats (any format containing 'rel', e.g. 'rel_xyxy', 'rel_yxyx'), but relative coordinates must be converted to absolute pixels internally, which requires the image dimensions. If bounding_box_format contains 'rel' and image_shape is None, this ValueError is raised.

Source

Thrown at keras/src/layers/preprocessing/image_preprocessing/bounding_boxes/iou.py:121

    if boxes1_rank not in [2, 3]:
        raise ValueError(
            "compute_iou() expects boxes1 to be batched, or to be unbatched. "
            f"Received len(boxes1.shape)={boxes1_rank}, "
            f"len(boxes2.shape)={boxes2_rank}. Expected either "
            "len(boxes1.shape)=2 AND or len(boxes1.shape)=3."
        )
    if boxes2_rank not in [2, 3]:
        raise ValueError(
            "compute_iou() expects boxes2 to be batched, or to be unbatched. "
            f"Received len(boxes1.shape)={boxes1_rank}, "
            f"len(boxes2.shape)={boxes2_rank}. Expected either "
            "len(boxes2.shape)=2 AND or len(boxes2.shape)=3."
        )

    target_format = "yxyx"
    if "rel" in bounding_box_format and image_shape is None:
        raise ValueError(
            "When using relative bounding box formats (e.g. `rel_yxyx`) "
            "the `image_shape` argument must be provided."
            f"Received `image_shape`: {image_shape}"
        )

    if image_shape is None:
        height, width = None, None
    else:
        height, width, _ = image_shape

    boxes1 = converters.convert_format(
        boxes1,
        source=bounding_box_format,
        target=target_format,
        height=height,
        width=width,
    )

View on GitHub (pinned to 7a34a03db6)

Solutions

1. Pass image_shape, e.g. compute_iou(b1, b2, bounding_box_format="rel_xyxy", image_shape=(H, W)).
2. Or convert boxes to an absolute format ('xyxy') and drop the rel format string.

Example fix

# before
iou = compute_iou(b1, b2, bounding_box_format="rel_xyxy")
# after
iou = compute_iou(b1, b2, bounding_box_format="rel_xyxy", image_shape=(416, 416))

if "rel" in bounding_box_format:
    assert image_shape is not None, "image_shape required for relative formats"

When it happens

Trigger: compute_iou(boxes1, boxes2, bounding_box_format="rel_xyxy") with no image_shape argument, or with image_shape=None passed explicitly.

Common situations: Swapping a pipeline from absolute to normalized coordinates without threading the image size through; reusing an IoU call written for 'xyxy' after changing the format string.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• `height` and `width` must be set if `format='xyxy'`.
• compute_iou() expects boxes1 to be batched, or to be unbatch
• compute_iou() expects boxes2 to be batched, or to be unbatch
• `variance` must be length 4, got {variance}
• `encoding_format` should be one of 'center_xywh' or 'center_

AI-assisted analysis of keras-team/keras@7a34a03db6 (2026-08-25). Data as JSON: /api/errors/dbe82a09afdbe7df. Report an issue: GitHub.