{"record":{"id":"144287703a68337e","repo":"roboflow/supervision","slug":"max-axis-must-be-positive-when-provided","errorCode":null,"errorMessage":"max_axis must be positive when provided","messagePattern":"max_axis must be positive when provided","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/supervision/key_points/annotators.py","lineNumber":297,"sourceCode":"    \"\"\"\n\n    def __init__(\n        self,\n        sigma: float | Sequence[float] = (1.0, 2.0, 3.0),\n        color: Color | Sequence[Color] = (Color.GREEN, Color.YELLOW, Color.RED),\n        max_axis: float | None = None,\n    ) -> None:\n        sigma_seq: Sequence[float] = (\n            (sigma,) if isinstance(sigma, (int, float)) else sigma\n        )\n        color_seq: Sequence[Color] = (color,) if isinstance(color, Color) else color\n\n        if len(sigma_seq) == 0:\n            raise ValueError(\"sigma must contain at least one value\")\n        if any(s <= 0 for s in sigma_seq):\n            raise ValueError(\"All sigma values must be positive\")\n        if max_axis is not None and max_axis <= 0:\n            raise ValueError(\"max_axis must be positive when provided\")\n        if len(color_seq) != len(sigma_seq):\n            raise ValueError(\n                f\"color length ({len(color_seq)}) must match \"\n                f\"sigma length ({len(sigma_seq)})\"\n            )\n\n        sorted_indices = sorted(\n            range(len(sigma_seq)), key=lambda i: sigma_seq[i], reverse=True\n        )\n        self.sigma = [sigma_seq[i] for i in sorted_indices]\n        self.color = [color_seq[i] for i in sorted_indices]\n        self.max_axis = max_axis\n\n    def _get_covariances(self, key_points: KeyPoints) -> npt.NDArray[np.float32]:\n        covariances = key_points.data.get(\"covariance\")\n        if covariances is None:\n            raise ValueError(\n                \"key_points.data must contain 'covariance' with shape (N, K, 2, 2).\"","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/roboflow/supervision/blob/7f254d9784d4c37e0f03cd89ddee164c8db099c0/src/supervision/key_points/annotators.py#L279-L315","documentation":"Raised by sv.Color.from_rgba_tuple when any of the four (r, g, b, a) values is outside 0-255, including alpha. The method validates the full RGBA quartet before constructing the Color. Alpha here is a byte (0-255), not a 0-1 float, which is the most common source of confusion.","triggerScenarios":"sv.Color.from_rgba_tuple((255, 0, 0, 1.0)) with a CSS-style alpha float, sv.Color.from_rgba_tuple((255, 0, 0, 300)) from unclamped alpha math, or negative alpha values from blending calculations.","commonSituations":"Porting CSS rgba(255, 0, 0, 0.5) colors directly (CSS alpha is 0-1); UI frameworks or config files expressing opacity as percentages or floats; gradually varying transparency in overlays without clamping alpha per frame.","solutions":["Convert float/percentage alpha to a byte: alpha_byte = int(round(alpha_float * 255)) (e.g. 0.5 -> 128).","Clamp all four channels to 0-255 before the call.","If alpha semantics are unclear, prefer from_hex with the 8-digit #RRGGBBAA form which documents alpha as a byte.","Double-check you are not passing RGBA where the code expects BGRA."],"exampleFix":"# before\nsv.Color.from_rgba_tuple((255, 0, 0, 0.5))  # CSS-style float alpha\n\n# after\nsv.Color.from_rgba_tuple((255, 0, 0, int(round(0.5 * 255))))  # alpha = 128","handlingStrategy":"validation","validationCode":"def alpha_to_byte(a) -> int:\n    \"\"\"Accept 0-1 float or 0-255 int alpha; return a valid byte alpha.\"\"\"\n    a = a * 255 if isinstance(a, float) and a <= 1.0 else a\n    return max(0, min(255, int(round(a))))\n\n# before: sv.Color.from_rgba_tuple((255, 0, 0, css_alpha))\n# after:  sv.Color.from_rgba_tuple((255, 0, 0, alpha_to_byte(css_alpha)))","typeGuard":"def is_valid_rgba_tuple(t: tuple) -> bool:\n    \"\"\"True if t is four numbers (r, g, b, a) each within 0-255.\"\"\"\n    return len(t) == 4 and all(isinstance(v, (int, float)) and 0 <= v <= 255 for v in t)","tryCatchPattern":null,"preventionTips":["Never port CSS rgba(..., 0.5) alpha directly — supervision alpha is a 0-255 byte.","Keep alpha blending math clamped per frame; transparency animations commonly drift past 255 or below 0.","Prefer the 8-digit hex form (#RRGGBBAA) when alpha comes from string config, since the byte semantics are explicit."],"tags":["validation","color","rgba","alpha","range","valueerror"],"backgroundTag":null,"analyzedSha":"7f254d9784d4c37e0f03cd89ddee164c8db099c0","analyzedAt":"2026-08-15T05:13:01.950Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}