{"record":{"id":"fd4406a4461f2c0d","repo":"roboflow/supervision","slug":"numpy-image-must-have-at-least-2-dimensions-h-w","errorCode":null,"errorMessage":"NumPy image must have at least 2 dimensions (H, W, ...). Received shape: {image.shape}","messagePattern":"NumPy image must have at least 2 dimensions \\(H, W, \\.\\.\\.\\)\\. Received shape: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/utils/image.py","lineNumber":639,"sourceCode":"\n    Raises:\n        ValueError: If a `numpy.ndarray` image has fewer than 2 dimensions.\n        TypeError: If `image` is not a supported type (`numpy.ndarray` or\n            `PIL.Image.Image`).\n\n    Examples:\n        ```pycon\n        >>> import numpy as np\n        >>> import supervision as sv\n        >>> image = np.zeros((1080, 1920, 3), dtype=np.uint8)\n        >>> sv.get_image_resolution_wh(image)\n        (1920, 1080)\n\n        ```\n    \"\"\"\n    if isinstance(image, np.ndarray):\n        if image.ndim < 2:\n            raise ValueError(\n                \"NumPy image must have at least 2 dimensions (H, W, ...). \"\n                f\"Received shape: {image.shape}\"\n            )\n        height, width = image.shape[:2]\n        return int(width), int(height)\n\n    if isinstance(image, Image.Image):\n        width, height = image.size\n        return int(width), int(height)\n\n    raise TypeError(\n        \"`image` must be a numpy.ndarray or PIL.Image.Image. \"\n        f\"Received type: {type(image)}\"\n    )\n\n\nclass ImageSink:\n    \"\"\"","sourceCodeStart":621,"sourceCodeEnd":657,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/utils/image.py#L621-L657","documentation":"Raised by `sv.get_image_resolution_wh` when the input is an np.ndarray with fewer than 2 dimensions. Resolution is defined as `image.shape[:2]` (height, width), which is meaningless for a 0-D scalar or 1-D vector. The message includes the offending shape so the mismatch is obvious.","triggerScenarios":"Passing a 1-D flattened pixel array, a single-row slice `image[0]` (shape (W, 3) or (W,)), or a numpy scalar from aggregating an image (e.g. `image.mean()`).","commonSituations":"Accidentally indexing one channel/row instead of the frame; functions that call `.ravel()` for transport and forget to reshape; passing a grayscale profile vector where a 2-D image was expected.","solutions":["Pass the full 2-D frame: `image.shape` must be like (H, W) or (H, W, C).","If you hold flattened data with known geometry, reshape first: `flat.reshape(h, w, c)`.","Audit slicing: `image[0]` gives a row — use `image[0:1]` to keep 2-D."],"exampleFix":"# before\nres = sv.get_image_resolution_wh(frame[0])  # 1-D row\n# after\nres = sv.get_image_resolution_wh(frame)  # (H, W, 3)","handlingStrategy":"validation","validationCode":"if isinstance(image, np.ndarray):\n    assert image.ndim >= 2, f'need 2-D image, got shape {image.shape}'","typeGuard":"def is_2d_image(x: Any) -> bool:\n    return isinstance(x, np.ndarray) and x.ndim >= 2","tryCatchPattern":null,"preventionTips":["Use image[0:1] instead of image[0] to keep 2-D when slicing.","Reshape flattened buffers with known geometry before use.","Pass whole frames, not channels or rows."],"tags":["image","resolution","numpy","shape-mismatch"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}