{"record":{"id":"530c3c8d49fa3375","repo":"roboflow/supervision","slug":"opacity-must-be-between-0-0-and-1-0","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/utils/image.py","lineNumber":568,"sourceCode":"        ValueError: If opacity is outside range [0.0, 1.0].\n\n    Examples:\n        ```pycon\n        >>> import numpy as np\n        >>> import supervision as sv\n        >>> image = np.zeros((100, 100, 3), dtype=np.uint8)\n        >>> tinted_image = sv.tint_image(\n        ...     image=image, color=sv.Color.ROBOFLOW, opacity=0.5\n        ... )\n        >>> tinted_image.shape\n        (100, 100, 3)\n\n        ```\n\n    ![tint-image](https://media.roboflow.com/supervision-docs/supervision-docs-tint-image-2.png){ align=center width=\"1000\" }\n    \"\"\"  # noqa E501 // docs\n    if not 0.0 <= opacity <= 1.0:\n        raise ValueError(\"opacity must be between 0.0 and 1.0\")\n\n    overlay = np.full_like(image, fill_value=color.as_bgr(), dtype=image.dtype)\n    cv2.addWeighted(\n        src1=overlay, alpha=opacity, src2=image, beta=1 - opacity, gamma=0, dst=image\n    )\n    return image\n\n\n@ensure_cv2_image_for_standalone_function\ndef grayscale_image(image: ImageType) -> ImageType:\n    \"\"\"\n    Convert image to 3-channel grayscale. Luminance channel is broadcast to\n    all three channels for compatibility with color-based drawing helpers.\n\n    Args:\n        image: The image to convert to\n            grayscale.\n","sourceCodeStart":550,"sourceCodeEnd":586,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/image.py#L550-L586","documentation":"Raised by `sv.tint_image` when `opacity` is outside [0.0, 1.0]. Opacity is used directly as the `alpha` weight in `cv2.addWeighted`, so out-of-range values are meaningless (and negative values would produce corrupt pixels). The inclusive bounds allow exactly 0 (no tint) and 1 (solid color).","triggerScenarios":"Passing `opacity=50` (percent instead of fraction); computing opacity from a ratio that exceeds 1 due to float accumulation; negated variable passing -0.3.","commonSituations":"Config files storing percentages 0-100; UI sliders reporting 0-100 ranges fed straight into the call; overlay loops that increment opacity past 1.0 for fade effects.","solutions":["Convert percentages: `opacity=pct / 100.0`.","Clamp computed values: `opacity = min(1.0, max(0.0, opacity))`.","For fade animations, wrap the loop variable: `opacity=i / n_steps` bounded to <= 1."],"exampleFix":"# before\ntinted = sv.tint_image(image=image, color=sv.Color.ROBOFLOW, opacity=50)\n# after\ntinted = sv.tint_image(image=image, color=sv.Color.ROBOFLOW, opacity=0.5)","handlingStrategy":"validation","validationCode":"assert 0.0 <= opacity <= 1.0, f'opacity out of range: {opacity}'\nopacity = min(1.0, max(0.0, opacity))","typeGuard":"def is_valid_opacity(x: Any) -> bool:\n    return isinstance(x, (int, float)) and 0.0 <= x <= 1.0","tryCatchPattern":null,"preventionTips":["Store opacity as a 0-1 float in configs, not a percent.","Clamp values coming from sliders or arithmetic.","Bound fade/animation loops so opacity never exceeds 1."],"tags":["image","opacity","validation","argument-error"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}