{"record":{"id":"3e24b25f7da051cd","repo":"roboflow/supervision","slug":"unsupported-color-conversion-code-code","errorCode":null,"errorMessage":"Unsupported color conversion code: {code}","messagePattern":"Unsupported color conversion code: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/_cv2/_color.py","lineNumber":57,"sourceCode":"                values[..., 0] * 3735\n                + values[..., 1] * 19235\n                + values[..., 2] * 9798\n                + (1 << 14)\n            ) >> 15\n            return weighted.astype(np.uint8)\n        float_values = (\n            image[..., 0].astype(np.float64) * 0.114\n            + image[..., 1].astype(np.float64) * 0.587\n            + image[..., 2].astype(np.float64) * 0.299\n        )\n        return _cast_array_like_opencv(float_values, image.dtype)\n\n    if code == _COLOR_HSV2BGR:\n        if image.ndim != 3 or image.shape[2] != 3:\n            raise ValueError(\"HSV2BGR conversion requires a three-channel image\")\n        return _hsv_to_bgr(image)\n\n    raise ValueError(f\"Unsupported color conversion code: {code}\")\n\n\ndef _hsv_to_bgr(image: npt.NDArray[Any]) -> npt.NDArray[Any]:\n    \"\"\"Convert OpenCV's 8-bit HSV representation to BGR.\"\"\"\n    values = image.astype(np.float64)\n    hue = values[..., 0] / 30.0\n    saturation = values[..., 1] / 255.0\n    value = values[..., 2] / 255.0\n\n    chroma = value * saturation\n    sector_index = np.floor(hue).astype(np.int64) % 6\n    sector = hue - np.floor(hue)\n    x = chroma * (1 - np.abs(((sector_index + sector) % 2) - 1))\n    match = value - chroma\n    zeros = np.zeros_like(chroma)\n\n    red = np.choose(sector_index, (chroma, x, zeros, zeros, x, chroma))\n    green = np.choose(sector_index, (x, chroma, chroma, x, zeros, zeros))","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/_cv2/_color.py#L39-L75","documentation":"The fallback `cv2.cvtColor` at src/supervision/_cv2/_color.py:57 implements exactly the conversions supervision itself needs: BGR<->RGB, GRAY2BGR, BGR2GRAY, and HSV2BGR. Any other conversion code constant (e.g. COLOR_BGR2HSV, COLOR_BGR2Lab, COLOR_YUV2BGR) raises with the offending code in the message.","triggerScenarios":"Calling `cv2.cvtColor(img, cv2.COLOR_BGR2HSV)` or any unsupported code while opencv-python is absent and the NumPy fallback backend is active.","commonSituations":"Application code that assumes real cv2 is present using color spaces beyond the supported set (HSV conversion for classic segmentation, Lab for color distance) in slim Docker/serverless environments.","solutions":["Restrict conversions to the supported set (BGR2RGB/RGB2BGR, GRAY2BGR, BGR2GRAY, HSV2BGR)","Install `opencv-python` — the full conversion matrix comes back","Gate unsupported conversions behind a `BACKEND_NAME == 'opencv'` check and skip/ substitute features on the fallback"],"exampleFix":"// before\nhsv = cv2.cvtColor(frame, cv2.COLOR_BGR2HSV)\n\n// after (no cv2 available)\ngray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)  # supported by the fallback\n# or: pip install opencv-python to unlock COLOR_BGR2HSV","handlingStrategy":"fallback","validationCode":"from supervision._cv2 import BACKEND_NAME\n\nSUPPORTED_CODES = {\"COLOR_BGR2RGB\", \"COLOR_RGB2BGR\", \"COLOR_GRAY2BGR\", \"COLOR_BGR2GRAY\", \"COLOR_HSV2BGR\"}\n\ndef assert_conversion_supported(code_name: str) -> None:\n    \"\"\"Fail fast when a cvtColor code is unavailable on the fallback backend.\"\"\"\n    if BACKEND_NAME != \"opencv\" and code_name not in SUPPORTED_CODES:\n        raise ValueError(f\"cvtColor code {code_name} needs opencv-python installed\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin opencv-python as a real dependency if you use color spaces beyond BGR/RGB/GRAY/HSV2BGR","Check for the 'using its pure NumPy fallback backend' warning at startup in slim deployments"],"tags":["cv2-fallback","color-conversion","unsupported-operation"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}