roboflow/supervision · error · ValueError

roundness attribute must be float between (0, 1.0]

Error message

roundness attribute must be float between (0, 1.0]

What it means

Raised by `RoundBoxAnnotator.__init__` when the `roundness` parameter is not in the exclusive-inclusive interval (0, 1.0]. Roundness is the fraction of the smaller box side used for the rounded-corner radius; 0 would give no rounding (use plain BoxAnnotator instead) and values above 1 produce overlapping/invalid arcs.

Source

Thrown at src/supervision/annotators/core.py:2693

        roundness: float = 0.6,
    ):
        """
        Args:
            color: The color or color palette to use for
                annotating detections.
            thickness: Thickness of the bounding box lines.
            color_lookup: Strategy for mapping colors to annotations.
                Options are `INDEX`, `CLASS`, `TRACK`.
            roundness: Percent of roundness for edges of bounding box.
                Value must be float 0 < roundness <= 1.0
                By default roundness percent is calculated based on smaller side
                length (width or height).
        """
        self.color: Color | ColorPalette = _normalize_color_input(color)
        self.thickness: int = thickness
        self.color_lookup: ColorLookup = color_lookup
        if not 0 < roundness <= 1.0:
            raise ValueError("roundness attribute must be float between (0, 1.0]")
        self.roundness: float = roundness

    @ensure_cv2_image_for_class_method
    def annotate(
        self,
        scene: ImageType,
        detections: Detections,
        custom_color_lookup: npt.NDArray[np.int_] | None = None,
    ) -> ImageType:
        """
        Annotates the given scene with bounding boxes with rounded edges
        based on the provided detections.

        Args:
            scene: The image where rounded bounding boxes will be drawn.
                `ImageType` is a flexible type, accepting either `numpy.ndarray`
                or `PIL.Image.Image`.
            detections: Object detections to annotate.

View on GitHub (pinned to 7f254d9784)

Solutions

1. Use a fraction in (0, 1.0], e.g. `roundness=0.5` for half-round corners or `1.0` for fully rounded.
2. Divide percentage values by 100 before passing: `roundness=pct / 100`.
3. If you truly want square corners, use `sv.BoxAnnotator` instead of RoundBoxAnnotator with roundness 0.

Example fix

# before
annotator = sv.RoundBoxAnnotator(roundness=0)     # ValueError
annotator = sv.RoundBoxAnnotator(roundness=30)    # meant 30% -> ValueError

# after
annotator = sv.RoundBoxAnnotator(roundness=0.3)   # 30% rounding

roundness = min(1.0, max(roundness / 100 if roundness > 1 else roundness, 1e-6))
annotator = sv.RoundBoxAnnotator(roundness=roundness)

def is_valid_roundness(v) -> bool:
    return isinstance(v, (int, float)) and 0 < v <= 1.0

When it happens

Trigger: Calling `sv.RoundBoxAnnotator(roundness=0)`, `roundness=0.0`, `roundness=1.5`, or a negative value; deriving roundness from a percentage without dividing by 100 (e.g. passing 50 for 50%); float configs parsed as 0 due to an empty field.

Common situations: Treating roundness as a 0-100 percentage instead of a 0-1 fraction; defaults copied from snippets that used 0 meaning 'square corners'; JSON config with a typo producing 0.0.

Related errors

• Unsupported color lookup strategy: {color_lookup}
• max_line_length must be a positive integer
• `slice_wh` must be an int or a tuple of two positive integer
• `overlap_wh` must be an int or a tuple of two non negative i
• `thread_workers` must be a positive integer. Received: {thre

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