{"record":{"id":"7b8a6feb0084d525","repo":"roboflow/supervision","slug":"blur-kernel-dimensions-must-be-positive","errorCode":null,"errorMessage":"Blur kernel dimensions must be positive","messagePattern":"Blur kernel dimensions must be positive","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/_cv2/_transform.py","lineNumber":18,"sourceCode":"\"\"\"Private transform and filter fallbacks.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Any\n\nimport numpy as np\nimport numpy.typing as npt\n\nfrom supervision._cv2._common import _cast_array_like_opencv\n\n\ndef _blur(\n    image: npt.NDArray[Any], ksize: tuple[int, int], border_type: int = 4\n) -> npt.NDArray[Any]:\n    \"\"\"Apply a box filter with OpenCV's default reflect-101 boundary behavior.\"\"\"\n    if min(ksize) <= 0:\n        raise ValueError(\"Blur kernel dimensions must be positive\")\n    if border_type != 4:\n        raise ValueError(\"Only OpenCV's default blur border is supported\")\n\n    from scipy import ndimage\n\n    size = (*ksize[::-1], 1) if image.ndim == 3 else ksize[::-1]\n    values = ndimage.uniform_filter(image.astype(np.float64), size=size, mode=\"mirror\")\n    return np.ascontiguousarray(_cast_array_like_opencv(values, image.dtype))\n","sourceCodeStart":1,"sourceCodeEnd":27,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/_cv2/_transform.py#L1-L27","documentation":"The fallback cv2.blur runs scipy.ndimage.uniform_filter, which requires positive kernel extents in both axes. A ksize containing 0 or a negative value would make the filter undefined, so it is rejected before the scipy call.","triggerScenarios":"cv2.blur(image, (0, 5)), negative kernel sizes, or ksize computed from a parameter that defaults to 0 when not configured.","commonSituations":"Config-driven blur strength where 0 means 'disabled' but the call is still made; odd/even kernel math producing 0 for tiny inputs; unvalidated user parameters.","solutions":["Skip the blur entirely when the configured strength is 0 instead of calling cv2.blur with a zero kernel.","Ensure ksize entries are >= 1; use max(1, k) if a computed size can round down to 0.","Validate kernel parameters at the API/config boundary."],"exampleFix":"# before\nblurred = cv2.blur(frame, (blur_ksize, blur_ksize))  # blur_ksize may be 0\n\n# after\nblurred = cv2.blur(frame, (blur_ksize, blur_ksize)) if blur_ksize > 0 else frame","handlingStrategy":"validation","validationCode":"if min(ksize) <= 0:\n    raise ValueError(f'blur kernel must be positive: {ksize}')\nblurred = cv2.blur(image, ksize)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Skip blur when configured strength is 0","Clamp computed kernel sizes with max(1, k)","Validate kernel parameters at the API boundary"],"tags":["opencv-fallback","blur","kernel-size","input-validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}