{"record":{"id":"b6de7e2b060a7b25","repo":"roboflow/supervision","slug":"rle-size-rle-h-rle-w-must-match-image-shape","errorCode":null,"errorMessage":"RLE size {(rle_h, rle_w)} must match image_shape {(img_h, img_w)}.","messagePattern":"RLE size (.+?) must match image_shape (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/compact_mask.py","lineNumber":824,"sourceCode":"        crop_shapes_list: list[tuple[int, int]] = []\n        offsets_list: list[tuple[int, int]] = []\n\n        for mask_idx, rle in enumerate(rles):\n            if not isinstance(rle, Mapping):\n                raise ValueError(\"Each RLE payload must be a mapping.\")\n            if \"size\" not in rle or \"counts\" not in rle:\n                raise ValueError(\"Each RLE payload must contain 'size' and 'counts'.\")\n\n            try:\n                # COCO standard: size=[height, width] (h,w order per pycocotools spec)\n                rle_h, rle_w = rle[\"size\"]\n                rle_h = int(rle_h)\n                rle_w = int(rle_w)\n            except (TypeError, ValueError) as exc:\n                raise ValueError(\"RLE size must be [height, width].\") from exc\n\n            if (rle_h, rle_w) != (img_h, img_w):\n                raise ValueError(\n                    f\"RLE size {(rle_h, rle_w)} must match image_shape \"\n                    f\"{(img_h, img_w)}.\"\n                )\n\n            counts = _coco_rle_counts_to_array(rle[\"counts\"])\n            if int(np.sum(counts, dtype=np.int64)) != img_h * img_w:\n                raise ValueError(\n                    \"The sum of COCO RLE counts must match the image area.\"\n                )\n\n            x1, y1, x2, y2 = xyxy_arr[mask_idx]\n            x1i, y1i, x2i, y2i = int(x1), int(y1), int(x2), int(y2)\n            x1c = max(0, min(x1i, img_w - 1))\n            y1c = max(0, min(y1i, img_h - 1))\n\n            if (\n                x2i < x1i\n                or y2i < y1i","sourceCodeStart":806,"sourceCodeEnd":842,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/compact_mask.py#L806-L842","documentation":"Raised by CompactMask.from_coco_rle when an RLE's 'size' [height, width] does not equal the image_shape passed to the method. from_coco_rle expects full-image RLEs (not crop RLEs): each mask is decoded at image resolution and then cropped via the paired xyxy, so a size mismatch means the RLE cannot describe this image.","triggerScenarios":"Calling from_coco_rle with image_shape=(720, 1280) but an RLE whose size is [360, 640] (downscaled annotation); passing crop-sized RLEs; (h, w) vs (w, h) order swap between size and image_shape.","commonSituations":"Dataset annotated at a different resolution than the images being loaded; pycocotools encode run on resized masks; width/height order confusion (COCO size is [h, w] per pycocotools).","solutions":["Match resolutions: either resize masks to the current image size before encoding, or pass image_shape equal to the annotation's size.","Double-check ordering — both 'size' and image_shape are (height, width).","If you only have crop RLEs, decode them yourself and use CompactMask.from_dense with the crop masks and their xyxy."],"exampleFix":"# before — masks encoded at half resolution\ncm = CompactMask.from_coco_rle(rles_half, xyxy, image_shape=(720, 1280))\n\n# after — resize masks to image size first, then encode\nmasks_full = [cv2.resize(m, (1280, 720), interpolation=cv2.INTER_NEAREST) for m in masks_half]\nrles = encode_all(masks_full)\ncm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(720, 1280))","handlingStrategy":"validation","validationCode":"for r in rles:\n    r_h, r_w = r[\"size\"]\n    assert (r_h, r_w) == tuple(image_shape), f\"RLE size {(r_h, r_w)} != image_shape {tuple(image_shape)}\"","typeGuard":null,"tryCatchPattern":"try:\n    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)\nexcept ValueError as e:\n    if \"must match image_shape\" in str(e):\n        shape = tuple(rles[0][\"size\"])  # adopt annotation resolution\n    else:\n        raise","preventionTips":["Encode masks at the exact resolution you will pass as image_shape.","Remember COCO size is [height, width] — same order as image_shape.","If you only have crop RLEs, decode them and use from_dense instead."],"tags":["coco","rle","compact-mask","resolution-mismatch","image-shape"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}