{"record":{"id":"aa9308710c4b51d0","repo":"roboflow/supervision","slug":"opacity-must-be-between-0-0-and-1-0-aa9308","errorCode":null,"errorMessage":"Opacity must be between 0.0 and 1.0.","messagePattern":"Opacity must be between 0\\.0 and 1\\.0\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/draw/utils.py","lineNumber":452,"sourceCode":"    \"\"\"\n\n    # Validate and load image\n    if isinstance(image, str):\n        if not os.path.exists(image):\n            raise FileNotFoundError(f\"Image path ('{image}') does not exist.\")\n        loaded_image = cv2.imread(image, cv2.IMREAD_UNCHANGED)\n        if loaded_image is None:\n            raise OSError(f\"Could not decode image path ('{image}').\")\n        image_np = cast(npt.NDArray[np.uint8], loaded_image)\n    else:\n        image_np = image\n\n    if image_np.ndim != 3 or image_np.shape[2] not in (3, 4):\n        raise ValueError(\"Image must have 3 or 4 channels.\")\n\n    # Validate opacity\n    if not 0.0 <= opacity <= 1.0:\n        raise ValueError(\"Opacity must be between 0.0 and 1.0.\")\n\n    rect_x = int(rect.x)\n    rect_y = int(rect.y)\n    rect_width = int(rect.width)\n    rect_height = int(rect.height)\n    # Validate rectangle dimensions\n    if (\n        rect_x < 0\n        or rect_y < 0\n        or rect_x + rect_width > scene.shape[1]\n        or rect_y + rect_height > scene.shape[0]\n    ):\n        raise ValueError(\"Invalid rectangle dimensions.\")\n\n    # Resize and isolate alpha channel\n    image_np = cast(\n        npt.NDArray[np.uint8], cv2.resize(image_np, (rect_width, rect_height))\n    )","sourceCodeStart":434,"sourceCodeEnd":470,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/draw/utils.py#L434-L470","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Clamp before calling: opacity = min(max(opacity, 0.0), 1.0)","Convert percent to fraction: opacity = percent / 100.0","Bind UI sliders to the [0, 1] range so the value can never be invalid"],"exampleFix":"# before\nscene = draw_image(scene, logo, opacity=80, rect=rect)  # percent, not fraction\n\n# after\nscene = draw_image(scene, logo, opacity=0.8, rect=rect)","handlingStrategy":"validation","validationCode":"opacity = min(max(float(opacity), 0.0), 1.0)\nscene = draw_image(scene, image, opacity=opacity, rect=rect)","typeGuard":"def is_valid_opacity(value: object) -> bool:\n    \"\"\"True when value is a float in [0.0, 1.0].\"\"\"\n    return isinstance(value, (int, float)) and 0.0 <= value <= 1.0","tryCatchPattern":"try:\n    scene = draw_image(scene, image, opacity=opacity, rect=rect)\nexcept ValueError as e:\n    if 'Opacity' in str(e):\n        scene = draw_image(scene, image, opacity=min(max(opacity, 0.0), 1.0), rect=rect)\n    else:\n        raise","preventionTips":["Store opacity as a fraction, not a percent, throughout your config","Clamp UI slider outputs before passing to drawing APIs"],"tags":["drawing","opacity","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}