{"record":{"id":"262735bd4e184a42","repo":"roboflow/supervision","slug":"unsupported-image-type-type-scene","errorCode":null,"errorMessage":"Unsupported image type: {type(scene)}","messagePattern":"Unsupported image type: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/conversion.py","lineNumber":41,"sourceCode":"\n    Assumes the annotators modify the scene in-place.\n\n    Raises:\n        TypeError: If `scene` is not a `numpy.ndarray` or `PIL.Image.Image`.\n    \"\"\"\n\n    @functools.wraps(annotate_func)\n    def wrapper(self: Any, scene: ImageType, *args: Any, **kwargs: Any) -> Any:\n        if isinstance(scene, np.ndarray):\n            return annotate_func(self, scene, *args, **kwargs)\n\n        if isinstance(scene, Image.Image):\n            scene_np = pillow_to_cv2(scene)\n            annotated_np = annotate_func(self, scene_np, *args, **kwargs)\n            scene.paste(cv2_to_pillow(annotated_np))\n            return scene\n\n        raise TypeError(f\"Unsupported image type: {type(scene)}\")\n\n    return cast(F, wrapper)\n\n\n@deprecated(  # type: ignore[untyped-decorator]\n    target=ensure_cv2_image_for_class_method,\n    deprecated_in=\"0.27.0\",\n    remove_in=\"0.31.0\",\n)\ndef ensure_cv2_image_for_annotation(\n    annotate_func: F,\n) -> F:\n    return cast(F, void(annotate_func))\n\n\ndef ensure_cv2_image_for_standalone_function(\n    image_processing_fun: F,\n) -> F:","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/conversion.py#L23-L59","documentation":"Raised by the ensure_cv2_image_for_class_method decorator's wrapper in supervision.utils.conversion when the `scene` argument passed to an annotator's annotate() method is neither a np.ndarray nor a PIL.Image.Image. The decorator transparently converts PIL scenes to BGR NumPy arrays, runs the annotator, and pastes the result back; any other type cannot be handled.","triggerScenarios":"Calling an annotator method like box_annotator.annotate(scene, detections) with scene as a torch.Tensor, a cv2.VideoCapture frame object, a file path string, a matplotlib figure, or None.","commonSituations":"Passing a PyTorch tensor straight from a model without calling .cpu().numpy(); passing an image path instead of a loaded array; passing a QImage or other GUI-framework image type; reusing old code where scene was previously accepted in another format.","solutions":["Convert tensors to NumPy: scene = tensor.cpu().numpy() before annotate().","If you have a path, load it first: scene = cv2.imread(path).","Convert other image objects to a PIL Image or np.ndarray (e.g. np.asarray(qimage)).","Check for None — a failed upstream load (cv2.imread returning None) flows into annotate()."],"exampleFix":"// before\nframe = model.predict_source(...)  # torch.Tensor\nannotated = annotator.annotate(frame, detections)  # TypeError\n\n// after\nframe = frame.cpu().numpy()\nannotated = annotator.annotate(frame, detections)","handlingStrategy":"type-guard","validationCode":"if not isinstance(scene, (np.ndarray, Image.Image)):\n    if hasattr(scene, 'cpu') and hasattr(scene, 'numpy'):\n        scene = scene.cpu().numpy()\n    else:\n        scene = np.asarray(scene)\nassert isinstance(scene, (np.ndarray, Image.Image))","typeGuard":"ImageType = Union[np.ndarray, Image.Image]\n\ndef is_annotatable(scene: object) -> TypeGuard[ImageType]:\n    return isinstance(scene, (np.ndarray, Image.Image))","tryCatchPattern":"try:\n    annotator.annotate(scene, detections)\nexcept TypeError as e:\n    if 'Unsupported image type' in str(e):\n        raise TypeError(f'Convert {type(scene)} to np.ndarray first') from e\n    raise","preventionTips":["Convert model tensors to NumPy at the pipeline boundary, once.","Load images with cv2.imread/PIL.open and check for None before annotating.","Type-annotate your own pipeline functions as np.ndarray so mypy catches bad flows."],"tags":["type-error","annotators","numpy","pillow"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}