{"record":{"id":"a16209071aa2fde7","repo":"roboflow/supervision","slug":"scale-factor-must-be-positive","errorCode":null,"errorMessage":"Scale factor must be positive.","messagePattern":"Scale factor must be positive\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/image.py","lineNumber":271,"sourceCode":"        >>> scaled_image.shape\n        (540, 960, 3)\n\n        ```\n\n        ```pycon\n        >>> image = np.zeros((1920, 1080), dtype=np.uint8)\n        >>> image.shape\n        (1920, 1080)\n        >>> scaled_image = sv.scale_image(image=image, scale_factor=0.5)\n        >>> scaled_image.shape\n        (960, 540)\n\n        ```\n\n    ![scale-image](https://media.roboflow.com/supervision-docs/supervision-docs-scale-image-2.png){ align=center width=\"1000\" }\n    \"\"\"  # noqa E501 // docs\n    if scale_factor <= 0:\n        raise ValueError(\"Scale factor must be positive.\")\n\n    width_old, height_old = image.shape[1], image.shape[0]\n    width_new = int(width_old * scale_factor)\n    height_new = int(height_old * scale_factor)\n    return cast(\n        npt.NDArray[np.uint8],\n        cv2.resize(image, (width_new, height_new), interpolation=cv2.INTER_LINEAR),\n    )\n\n\n@ensure_cv2_image_for_standalone_function\ndef resize_image(\n    image: ImageType,\n    resolution_wh: tuple[int, int],\n    keep_aspect_ratio: bool = False,\n) -> ImageType:\n    \"\"\"\n    Resize image to specified resolution. Can optionally maintain aspect ratio.","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/image.py#L253-L289","documentation":"Raised by `sv.scale_image` when `scale_factor <= 0`. A non-positive factor would produce zero or negative dimensions, which `cv2.resize` cannot handle and would crash deeper with a less understandable error. The guard makes the contract explicit: any strictly positive factor (including values < 1.0 for zoom-out) is accepted.","triggerScenarios":"Calling `sv.scale_image(image=image, scale_factor=0)`; computing the factor as a ratio that divides by zero or by a wrong variable; a config/UI default of 0 reaching the call.","commonSituations":"Computing `scale = target / current` where `current` is 0 due to reading resolution before image load; sign errors or swapped numerator/denominator producing 0; percentage values (50) passed where a fraction (0.5) was expected and then multiplied somewhere to 0.","solutions":["Pass a positive factor: use 0.5 to halve, 2.0 to double.","If the factor is computed, guard the denominator and clamp: `factor = max(1e-6, target_w / src_w)`.","For percentages, convert first: `scale_factor=pct / 100.0`."],"exampleFix":"# before\nscaled = sv.scale_image(image=image, scale_factor=0)\n# after\nscaled = sv.scale_image(image=image, scale_factor=0.5)","handlingStrategy":"validation","validationCode":"assert scale_factor > 0, f'scale_factor must be > 0, got {scale_factor}'\n# if computed:\nscale_factor = max(scale_factor, 1e-6)","typeGuard":"def is_positive_scale(x: Any) -> bool:\n    return isinstance(x, (int, float)) and x > 0","tryCatchPattern":null,"preventionTips":["Convert percent configs to fractions before passing.","Guard denominators when computing scale as a ratio.","Validate UI/config inputs at load time."],"tags":["image","scale","validation","argument-error"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}