{"record":{"id":"838fa4d18301e761","repo":"roboflow/supervision","slug":"pixel-size-must-be-1-got-pixel-size","errorCode":null,"errorMessage":"pixel_size must be >= 1, got {pixel_size}.","messagePattern":"pixel_size must be >= 1, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/annotators/core.py","lineNumber":2462,"sourceCode":"        return scene\n\n\nclass PixelateAnnotator(BaseAnnotator):\n    \"\"\"\n    A class for pixelating regions in an image using provided detections.\n    \"\"\"\n\n    def __init__(self, pixel_size: int | None = None):\n        \"\"\"\n        Args:\n            pixel_size: The size of the pixelation. If not set, a dynamic size is\n                computed as one-half of the shorter bounding-box dimension. When set\n                and the detection area is smaller than `pixel_size`, the region is\n                filled with its average colour instead to avoid an OpenCV crash.\n                Must be >= 1 when provided.\n        \"\"\"\n        if pixel_size is not None and pixel_size < 1:\n            raise ValueError(f\"pixel_size must be >= 1, got {pixel_size}.\")\n        self.pixel_size: int | None = pixel_size\n\n    @ensure_cv2_image_for_class_method\n    def annotate(\n        self,\n        scene: ImageType,\n        detections: Detections,\n    ) -> ImageType:\n        \"\"\"\n        Annotates the given scene by pixelating regions based on the provided\n            detections.\n\n        Args:\n            scene: The image where pixelating will be applied.\n                `ImageType` is a flexible type, accepting either `numpy.ndarray`\n                or `PIL.Image.Image`.\n            detections: Object detections to annotate.\n","sourceCodeStart":2444,"sourceCodeEnd":2480,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/annotators/core.py#L2444-L2480","documentation":"Raised by `PixelateAnnotator.__init__` when an explicit `pixel_size` smaller than 1 is passed. The pixelation grid must have at least one cell per axis; smaller values are rejected up front because OpenCV resize cannot form a valid grid. When unset, the size is derived dynamically from each box.","triggerScenarios":"Calling `sv.PixelateAnnotator(pixel_size=0)` or a negative value; deriving pixel size from box dimensions or a config scale where rounding yields 0 (e.g. `int(box_w * 0.01)` on a 50px box); None is accepted (dynamic sizing), so only explicit bad values raise.","commonSituations":"Auto-computed pixel sizes on small or distant detections flooring to zero; config-driven privacy-blur strength of 0 intended as 'off' but interpreted as a literal size; parameter sweeps in tests hitting 0.","solutions":["Pass `pixel_size=None` for automatic per-box sizing.","Clamp derived values: `pixel_size=max(1, int(value))`.","If 0 is meant to disable pixelation, skip annotating that region entirely in your own code instead of passing 0."],"exampleFix":"# before\nannotator = sv.PixelateAnnotator(pixel_size=int(200 * 0.005))  # -> 1... for 100px -> 0\nannotator = sv.PixelateAnnotator(pixel_size=0)  # ValueError\n\n# after\nsize = max(1, int(smallest_side * 0.05))\nannotator = sv.PixelateAnnotator(pixel_size=size)","handlingStrategy":"validation","validationCode":"pixel_size = None if computed_size is None else max(1, int(computed_size))\nannotator = sv.PixelateAnnotator(pixel_size=pixel_size)","typeGuard":"def is_valid_pixel_size(v) -> bool:\n    return v is None or (isinstance(v, int) and v >= 1)","tryCatchPattern":null,"preventionTips":["Use pixel_size=None for dynamic sizing.","Never pass a literal 0 meaning 'disabled' — skip the annotator call instead."],"tags":["annotators","pixelate","validation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}