roboflow/supervision · error · ValueError

sigma must contain at least one value

Error message

sigma must contain at least one value

What it means

Raised by sv.Color.from_rgb_tuple when any element of the (r, g, b) tuple falls outside 0-255. The method validates before delegating to the Color constructor, giving an RGB-specific message with the offending values. This guards the common path where annotators receive colors from external sources as tuples.

Source

Thrown at src/supervision/key_points/annotators.py:293

    """Private base for ellipse-based keypoint annotators.

    Handles sigma/color validation, sorting, covariance extraction and
    eigendecomposition shared by all VertexEllipse* variants.
    """

    def __init__(
        self,
        sigma: float | Sequence[float] = (1.0, 2.0, 3.0),
        color: Color | Sequence[Color] = (Color.GREEN, Color.YELLOW, Color.RED),
        max_axis: float | None = None,
    ) -> None:
        sigma_seq: Sequence[float] = (
            (sigma,) if isinstance(sigma, (int, float)) else sigma
        )
        color_seq: Sequence[Color] = (color,) if isinstance(color, Color) else color

        if len(sigma_seq) == 0:
            raise ValueError("sigma must contain at least one value")
        if any(s <= 0 for s in sigma_seq):
            raise ValueError("All sigma values must be positive")
        if max_axis is not None and max_axis <= 0:
            raise ValueError("max_axis must be positive when provided")
        if len(color_seq) != len(sigma_seq):
            raise ValueError(
                f"color length ({len(color_seq)}) must match "
                f"sigma length ({len(sigma_seq)})"
            )

        sorted_indices = sorted(
            range(len(sigma_seq)), key=lambda i: sigma_seq[i], reverse=True
        )
        self.sigma = [sigma_seq[i] for i in sorted_indices]
        self.color = [color_seq[i] for i in sorted_indices]
        self.max_axis = max_axis

    def _get_covariances(self, key_points: KeyPoints) -> npt.NDArray[np.float32]:

View on GitHub (pinned to 7f254d9784)

Solutions

1. If values are normalized 0-1 floats, convert first: tuple(int(round(v * 255)) for v in rgb).
2. Clamp integer inputs to 0-255 before calling from_rgb_tuple.
3. Check for negative values coming from arithmetic (subtraction, alpha blending) in your color pipeline.
4. Add unit-test or runtime assertions on color tuples ingested from external data sources.

Example fix

# before
color = sv.Color.from_rgb_tuple((1.0, 0.4, 0.0))  # 0-1 floats -> passes range but wrong; 256.0 would raise

# after
rgb_255 = tuple(int(round(v * 255)) for v in (1.0, 0.4, 0.0))
color = sv.Color.from_rgb_tuple(rgb_255)

def to_rgb255(rgb: tuple[float, float, float]) -> tuple[int, int, int]:
    """Convert 0-1 float or 0-255 numeric RGB to a valid from_rgb_tuple input."""
    vals = [int(round(v * 255)) if isinstance(v, float) and v <= 1.0 else int(round(v)) for v in rgb]
    return tuple(max(0, min(255, v)) for v in vals)  # type: ignore[return-value]

def is_valid_rgb_tuple(t: tuple) -> bool:
    """True if t is three numbers each within 0-255."""
    return len(t) == 3 and all(isinstance(v, (int, float)) and 0 <= v <= 255 for v in t)

When it happens

Trigger: sv.Color.from_rgb_tuple((300, 0, 0)), sv.Color.from_rgb_tuple((-10, 128, 128)), or passing float tuples like (1.0, 0.5, 0.0) from a library using normalized colors (values equal to 1.0 pass the range check but are floats and semantically wrong).

Common situations: Interfacing with matplotlib, seaborn, or plotly which express colors as 0-1 floats; reading RGB values from JSON/YAML configs without validation; math on channel values that overflows; mixing up 0-255 and 0-1 conventions in a multi-library pipeline.

Related errors

• Edge indices must use the 1-based convention and be within t
• All sigma values must be positive
• max_axis must be positive when provided
• color length ({len(color_seq)}) must match sigma length ({le
• module {__name__} has no attribute {name}

AI-assisted analysis of roboflow/supervision@7f254d9784 (2026-08-15). Data as JSON: /api/errors/65250ad58eda8cb0. Report an issue: GitHub.