{"record":{"id":"31a2381c022a60da","repo":"roboflow/supervision","slug":"image-shape-img-h-img-w-exceeds-the-maximum-a","errorCode":null,"errorMessage":"image_shape {(img_h, img_w)} exceeds the maximum allowed dimension of {_MAX_IMAGE_DIMENSION} pixels per side.","messagePattern":"image_shape (.+?) exceeds the maximum allowed dimension of (.+?) pixels per side\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/compact_mask.py","lineNumber":786,"sourceCode":"            >>> from supervision.detection.compact_mask import CompactMask\n            >>> # 4x4 image with a 2x2 True block at the top-left corner.\n            >>> # Uncompressed F-order COCO counts: F=0, T=2, F=2, T=2, F=10\n            >>> # (column-major: col0=[T,T,F,F], col1=[T,T,F,F], cols2-3 all F).\n            >>> rles = [{\"size\": [4, 4], \"counts\": [0, 2, 2, 2, 10]}]\n            >>> xyxy = np.array([[0, 0, 3, 3]], dtype=np.float32)\n            >>> cm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(4, 4))\n            >>> cm.shape\n            (1, 4, 4)\n            >>> cm.area.tolist()\n            [4]\n\n            ```\n        \"\"\"\n        img_h, img_w = (int(image_shape[0]), int(image_shape[1]))\n        if img_h <= 0 or img_w <= 0:\n            raise ValueError(\"image_shape must contain positive height and width.\")\n        if img_h > _MAX_IMAGE_DIMENSION or img_w > _MAX_IMAGE_DIMENSION:\n            raise ValueError(\n                f\"image_shape {(img_h, img_w)} exceeds the maximum allowed dimension \"\n                f\"of {_MAX_IMAGE_DIMENSION} pixels per side.\"\n            )\n\n        xyxy_arr = np.asarray(xyxy)\n        if xyxy_arr.shape != (len(rles), 4):\n            raise ValueError(\n                \"xyxy must have shape (N, 4), where N matches the number of RLEs.\"\n            )\n\n        if len(rles) == 0:\n            return cls(\n                [],\n                np.empty((0, 2), dtype=np.int32),\n                np.empty((0, 2), dtype=np.int32),\n                (img_h, img_w),\n            )\n","sourceCodeStart":768,"sourceCodeEnd":804,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/compact_mask.py#L768-L804","documentation":"Raised by CompactMask.from_coco_rle when either image dimension exceeds the module-level constant _MAX_IMAGE_DIMENSION. The cap bounds memory/CPU cost of decoding and storing per-mask RLE crops, so absurdly large shapes (typically from corrupt metadata) are rejected early with the allowed maximum stated in the message.","triggerScenarios":"Passing image_shape=(100000, 100000) or similar oversized dims; unit confusion such as passing bytes-per-row instead of pixels; shapes sourced from a malformed image header or a typo with extra zeros.","commonSituations":"Corrupt image metadata (EXIF/header) reporting huge dimensions; passing shape multiplied twice; loading a huge tiled scan/WSI image without slicing first.","solutions":["Print the actual image_shape you pass and compare against the real image dimensions from cv2.imread(...).shape.","If you genuinely have a very large image, slice/tile it (e.g. InferenceSlicer) and build CompactMask per tile with tile-sized image_shape.","Fix the metadata source if headers are corrupt."],"exampleFix":"# before\ncm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(h * 1000, w * 1000))\n\n# after\ncm = CompactMask.from_coco_rle(rles, xyxy, image_shape=(h, w))","handlingStrategy":"validation","validationCode":"MAX_DIM = 65535  # keep in sync with installed supervision's _MAX_IMAGE_DIMENSION\nh, w = image_shape\nassert 0 < h <= MAX_DIM and 0 < w <= MAX_DIM, f\"image too large: {(h, w)}\"","typeGuard":null,"tryCatchPattern":"try:\n    cm = sv.CompactMask.from_coco_rle(rles, xyxy, image_shape=shape)\nexcept ValueError as e:\n    if \"maximum allowed dimension\" in str(e):\n        raise ValueError(\"tile the image before building CompactMask\") from e\n    raise","preventionTips":["Tile very large images (InferenceSlicer) and construct CompactMask per tile.","Validate dimensions coming from untrusted image headers before use.","Watch for unit mistakes (bytes vs pixels) when computing shape."],"tags":["compact-mask","coco","rle","limits","image-shape"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}