{"record":{"id":"5de62ba71f97806f","repo":"roboflow/supervision","slug":"sam-segmentations-must-all-be-dense-arrays-or-coco","errorCode":null,"errorMessage":"SAM segmentations must all be dense arrays or COCO RLE dictionaries.","messagePattern":"SAM segmentations must all be dense arrays or COCO RLE dictionaries\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/detection/core.py","lineNumber":848,"sourceCode":"\n        if all(isinstance(segmentation, np.ndarray) for segmentation in segmentations):\n            mask = np.stack(segmentations, axis=0)\n        elif all(isinstance(segmentation, dict) for segmentation in segmentations):\n            image_height, image_width = cast(\n                tuple[int, int], tuple(int(v) for v in first_segmentation[\"size\"])\n            )\n            mask = np.stack(\n                [\n                    rle_to_mask(\n                        segmentation[\"counts\"],\n                        (image_width, image_height),\n                    )\n                    for segmentation in segmentations\n                ],\n                axis=0,\n            )\n        else:\n            raise ValueError(\n                \"SAM segmentations must all be dense arrays or COCO RLE dictionaries.\"\n            )\n\n        xyxy = xywh_to_xyxy(xywh=xywh)\n        return cls(xyxy=xyxy, mask=mask)\n\n    @classmethod\n    def from_sam3(\n        cls, sam3_result: dict[str, Any] | Any, resolution_wh: tuple[int, int]\n    ) -> Detections:\n        \"\"\"\n        Creates a Detections instance from\n        [SAM 3](https://github.com/facebookresearch/sam3) inference result.\n        Supports both PVS and PCS SAM3 segmentation formats.\n\n        Args:\n            sam3_result: The output result from SAM 3 inference, either\n                Sam3PromptResult from inference package or dict containing","sourceCodeStart":830,"sourceCodeEnd":866,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/detection/core.py#L830-L866","documentation":"Detections.from_sam accepts SAM outputs whose 'segmentation' entries are either all dense boolean np.ndarrays (SamAutomaticMaskGenerator default) or all COCO RLE dicts (from mask generators configured with output_mode='coco_rle'). The np.stack/rle_to_mask logic cannot handle a mixed or foreign-typed list, so anything else raises this ValueError.","triggerScenarios":"Passing a sam_result list where some items have np.ndarray 'segmentation' and others have dict RLE 'segmentation'; segmentations stored as torch.Tensor, lists, pycocotools RLE objects, or any other type after serialization/conversion; concatenating outputs from two SAM runs with different output modes.","commonSituations":"Saving SAM results to JSON (arrays become nested lists, RLE dicts survive) then reloading and mixing with fresh results; converting masks to torch tensors for a GPU step then calling from_sam on the converted list; merging binary_mask and coco_rle outputs.","solutions":["Normalize every segmentation to dense np.ndarray (mask dtype bool/uint8) before calling from_sam: np.asarray(seg, dtype=bool) or decode RLE entries with supervision's rle_to_mask.","If using SamAutomaticMaskGenerator, set a single output_mode ('binary_mask' or 'coco_rle') and don't mix runs.","After JSON round-trips, convert nested lists back: [np.asarray(s, dtype=bool) for s in segmentations]."],"exampleFix":"# before\n# segs is a mix of np.ndarray and RLE dicts after merging two SAM runs\ndetections = sv.Detections.from_sam(sam_result)  # ValueError\n\n# after\nfor item in sam_result:\n    seg = item['segmentation']\n    if isinstance(seg, dict):\n        from supervision.detection.utils import rle_to_mask\n        h, w = seg['size']\n        item['segmentation'] = rle_to_mask(seg['counts'], (w, h))\ndetections = sv.Detections.from_sam(sam_result)","handlingStrategy":"type-guard","validationCode":"import numpy as np\n\ndef normalize_sam_result(sam_result: list[dict]) -> list[dict]:\n    for item in sam_result:\n        seg = item['segmentation']\n        if isinstance(seg, dict):\n            from supervision.detection.utils import rle_to_mask\n            h, w = seg['size']\n            item['segmentation'] = rle_to_mask(seg['counts'], (w, h))\n        elif not isinstance(seg, np.ndarray):\n            item['segmentation'] = np.asarray(seg, dtype=bool)\n    return sam_result\n\ndetections = sv.Detections.from_sam(normalize_sam_result(sam_result))","typeGuard":"def sam_result_uniform(sam_result: list) -> bool:\n    segs = [m['segmentation'] for m in sam_result]\n    types = {type(s) for s in segs}\n    return types <= {np.ndarray} or types <= {dict}","tryCatchPattern":"try:\n    detections = sv.Detections.from_sam(sam_result)\nexcept ValueError as e:\n    if 'dense arrays or COCO RLE' in str(e):\n        detections = sv.Detections.from_sam(normalize_sam_result(sam_result))\n    else:\n        raise","preventionTips":["Fix one SAM output_mode per pipeline","Convert nested lists back to np.ndarray after JSON round-trips","Never mix SAM runs with different serialization in one result list"],"tags":["sam","segmentation","rle","type","from-sam"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}