{"record":{"id":"a53ca448693b2fb5","repo":"roboflow/supervision","slug":"the-sum-of-the-number-of-pixels-in-the-rle-must-be","errorCode":null,"errorMessage":"the sum of the number of pixels in the RLE must be the same as the number of pixels in the expected mask","messagePattern":"the sum of the number of pixels in the RLE must be the same as the number of pixels in the expected mask","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/utils/converters.py","lineNumber":717,"sourceCode":"               [False, False, False, False]])\n\n        ```\n    \"\"\"\n    if isinstance(rle, bytes):\n        rle = rle.decode(\"utf-8\")\n    if isinstance(rle, str):\n        counts: npt.NDArray[np.int32] = np.array(\n            _delta_decode(_base48_decode(rle)), dtype=np.int32\n        )\n    elif isinstance(rle, list):\n        counts = np.array(rle, dtype=np.int32)\n    else:\n        counts = np.asarray(rle, dtype=np.int32)\n\n    width, height = resolution_wh\n\n    if width * height != np.sum(counts):\n        raise ValueError(\n            \"the sum of the number of pixels in the RLE must be the same \"\n            \"as the number of pixels in the expected mask\"\n        )\n\n    return _rle_counts_to_mask(counts, height, width)\n\n\ndef mask_to_rle(\n    mask: npt.NDArray[np.bool_], compressed: bool = False\n) -> list[int] | str:\n    \"\"\"\n    Converts a binary mask into a COCO run-length encoding (RLE).\n\n    Produces RLE in the COCO format used by ``pycocotools``: pixels are counted\n    in **column-major (Fortran) order** — top-to-bottom within each column,\n    left-to-right across columns. The output is directly compatible with\n    ``pycocotools.mask.decode`` and COCO annotation JSON files.\n","sourceCodeStart":699,"sourceCodeEnd":735,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/utils/converters.py#L699-L735","documentation":"When decoding a COCO-style run-length encoding back into a mask, the sum of the RLE run counts must equal width*height of the supplied resolution — every pixel is accounted for by alternating runs. A mismatch means the RLE and resolution_wh disagree (wrong resolution, truncated counts, or an RLE produced under column-major vs row-major differences), so reconstruction would be ill-defined.","triggerScenarios":"Calling rle_to_mask(rle, resolution_wh) with a resolution different from the one used to encode (e.g. encoding at 640x480, decoding at 1920x1080); passing a compressed string decoded with the wrong scheme; hand-modified or truncated count lists.","commonSituations":"Resizing images after storing RLEs without updating resolution metadata; mixing COCO API RLEs (column-major) with supervision's encoder; storing resolution as (height, width) and swapping the tuple.","solutions":["Pass the exact resolution used at encode time — store it alongside the RLE.","Double-check tuple order: supervision expects resolution as (width, height).","If the RLE came from pycocotools, convert counts orientation before decoding with this API.","Sanity check: assert sum(counts) == w * h in your data loader before decoding."],"exampleFix":"# before\n mask = sv.rle_to_mask(rle=stored_rle, resolution_wh=(1920, 1080))  # encoded at 640x480\n\n# after\n mask = sv.rle_to_mask(rle=stored_rle, resolution_wh=stored_resolution_wh)","handlingStrategy":"validation","validationCode":"w, h = resolution_wh\nif int(np.sum(counts)) != w * h:\n    raise ValueError(f\"RLE sum {np.sum(counts)} != {w}x{h}={w * h}; wrong resolution?\")","typeGuard":null,"tryCatchPattern":"try:\n    mask = sv.rle_to_mask(rle=rle, resolution_wh=wh)\nexcept ValueError as e:\n    logger.error(\"RLE/resolution mismatch for record %s: %s\", record_id, e)\n    raise","preventionTips":["Store the encoding resolution next to every RLE at write time.","Remember resolution_wh is (width, height), not (height, width).","Validate the sum invariant in data loaders before decoding."],"tags":["rle","mask","resolution-mismatch","coco"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}