roboflow/supervision · error · ValueError

Invalid rectangle dimensions.

Error message

Invalid rectangle dimensions.

What it means

Raised by draw_image when the target rectangle does not fit inside the scene: negative x/y, or width/height extending past the scene's right/bottom edges (checked against scene.shape[1] and scene.shape[0]). The function blends pixels within the rect, so out-of-bounds placement would index outside the frame. Coordinates are truncated to int before the check.

Source

Thrown at src/supervision/draw/utils.py:465

    if image_np.ndim != 3 or image_np.shape[2] not in (3, 4):
        raise ValueError("Image must have 3 or 4 channels.")

    # Validate opacity
    if not 0.0 <= opacity <= 1.0:
        raise ValueError("Opacity must be between 0.0 and 1.0.")

    rect_x = int(rect.x)
    rect_y = int(rect.y)
    rect_width = int(rect.width)
    rect_height = int(rect.height)
    # Validate rectangle dimensions
    if (
        rect_x < 0
        or rect_y < 0
        or rect_x + rect_width > scene.shape[1]
        or rect_y + rect_height > scene.shape[0]
    ):
        raise ValueError("Invalid rectangle dimensions.")

    # Resize and isolate alpha channel
    image_np = cast(
        npt.NDArray[np.uint8], cv2.resize(image_np, (rect_width, rect_height))
    )
    alpha_channel = (
        image_np[:, :, 3]
        if image_np.shape[2] == 4
        else np.ones((rect_height, rect_width), dtype=image_np.dtype) * 255
    )
    alpha_scaled = cv2.convertScaleAbs(alpha_channel * opacity)

    # Perform blending
    scene_roi = scene[rect_y : rect_y + rect_height, rect_x : rect_x + rect_width]
    alpha_float = alpha_scaled.astype(np.float32) / 255.0
    blended_roi = cv2.convertScaleAbs(
        (1 - alpha_float[..., np.newaxis]) * scene_roi
        + alpha_float[..., np.newaxis] * image_np[:, :, :3]

View on GitHub (pinned to 7f254d9784)

Solutions

1. Clamp the rect to the scene: rect.width = min(rect.width, scene.shape[1] - rect.x); rect.height = min(rect.height, scene.shape[0] - rect.y) with x,y clamped to >= 0
2. Recompute rect from current scene dimensions each frame instead of caching
3. For corner placement use explicit anchors: Rect(x=W - w - margin, y=margin, width=w, height=h)

Example fix

# before
rect = Rect(x=scene.shape[1] - 50, y=10, width=60, height=60)  # overflows by 10
scene = draw_image(scene, logo, opacity=0.8, rect=rect)

# after
rect = Rect(x=scene.shape[1] - 60, y=10, width=60, height=60)  # fits
scene = draw_image(scene, logo, opacity=0.8, rect=rect)

def clamp_rect(rect, scene):
    h, w = scene.shape[:2]
    x = max(0, min(int(rect.x), w - 1))
    y = max(0, min(int(rect.y), h - 1))
    return Rect(
        x=x,
        y=y,
        width=min(int(rect.width), w - x),
        height=min(int(rect.height), h - y),
    )

scene = draw_image(scene, image, opacity=0.8, rect=clamp_rect(rect, scene))

def rect_fits(rect: Rect, scene) -> bool:
    """True when rect lies fully inside the scene with positive size."""
    h, w = scene.shape[:2]
    return (
        rect.x >= 0 and rect.y >= 0 and rect.width > 0 and rect.height > 0
        and rect.x + rect.width <= w and rect.y + rect.height <= h
    )

try:
    scene = draw_image(scene, image, opacity=0.8, rect=rect)
except ValueError as e:
    if 'rectangle dimensions' in str(e):
        scene = draw_image(scene, image, opacity=0.8, rect=clamp_rect(rect, scene))
    else:
        raise

When it happens

Trigger: Calling draw_image with Rect(x=-5, ...), or Rect(x=scene_width - 10, width=40) that overflows the right edge; also height/width large enough that x+width > scene.shape[1].

Common situations: Placing logos/badges at computed positions (e.g. top-right corner: x = W - logo_w with an off-by-one or already-scaled logo size); scenes resized after the rect was computed; scaled coordinates from a different resolution.

Related errors

• The magnitude of the vector cannot be zero.
• Polygon must have at least one vertex.
• Opacity must be between 0.0 and 1.0.
• Invalid characters in color hash
• module {__name__} has no attribute {name}

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