roboflow/supervision · error · ValueError

Opacity must be between 0.0 and 1.0.

Error message

Opacity must be between 0.0 and 1.0.

What it means

Raised by draw_image when the opacity argument is outside [0.0, 1.0]. Opacity scales the image's alpha channel during blending, so values below 0 or above 1 are meaningless and would produce undefined compositing. The check runs after image loading and before the rectangle is validated.

Source

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

    """

    # Validate and load image
    if isinstance(image, str):
        if not os.path.exists(image):
            raise FileNotFoundError(f"Image path ('{image}') does not exist.")
        loaded_image = cv2.imread(image, cv2.IMREAD_UNCHANGED)
        if loaded_image is None:
            raise OSError(f"Could not decode image path ('{image}').")
        image_np = cast(npt.NDArray[np.uint8], loaded_image)
    else:
        image_np = image

    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))
    )

View on GitHub (pinned to 7f254d9784)

Solutions

1. Clamp before calling: opacity = min(max(opacity, 0.0), 1.0)
2. Convert percent to fraction: opacity = percent / 100.0
3. Bind UI sliders to the [0, 1] range so the value can never be invalid

Example fix

# before
scene = draw_image(scene, logo, opacity=80, rect=rect)  # percent, not fraction

# after
scene = draw_image(scene, logo, opacity=0.8, rect=rect)

opacity = min(max(float(opacity), 0.0), 1.0)
scene = draw_image(scene, image, opacity=opacity, rect=rect)

def is_valid_opacity(value: object) -> bool:
    """True when value is a float in [0.0, 1.0]."""
    return isinstance(value, (int, float)) and 0.0 <= value <= 1.0

try:
    scene = draw_image(scene, image, opacity=opacity, rect=rect)
except ValueError as e:
    if 'Opacity' in str(e):
        scene = draw_image(scene, image, opacity=min(max(opacity, 0.0), 1.0), rect=rect)
    else:
        raise

When it happens

Trigger: Calling draw_image(scene, image, opacity=1.5, rect=...) or opacity=-0.1; passing a percentage (e.g. 80 meaning 80%) instead of a fraction.

Common situations: UI configs that express opacity in percent (0-100) fed directly to the API; slider widgets with ranges not clamped to [0,1]; computed opacity values (e.g. 1 + fade_factor) that overshoot.

Related errors

• opacity must be between 0.0 and 1.0
• Invalid rectangle dimensions.
• Invalid characters in color hash
• module {__name__} has no attribute {name}
• Edge indices must use the 1-based convention and be within t

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