roboflow/supervision · error · ValueError

bottomLeftOrigin is not supported by the fallback

Error message

bottomLeftOrigin is not supported by the fallback

What it means

Thrown by the Pillow-based fallback for cv2.putText. OpenCV's putText has a bottomLeftOrigin flag that renders text with inverted image axes; the fallback does not emulate it, so it raises rather than silently drawing wrong output. No Supervision annotator uses this mode.

Source

Thrown at src/supervision/_cv2/_text.py:96

    img: _ImageArray,
    text: str,
    org: tuple[int, int],
    fontFace: int,
    fontScale: float,
    color: Any,
    thickness: int = 1,
    lineType: int = _LINE_8,
    bottomLeftOrigin: bool = False,
) -> _ImageArray:
    """Render text with a Pillow face, anchored at OpenCV's baseline origin.

    Thickness maps to a Pillow stroke width to emulate OpenCV's bolder strokes.
    ``bottomLeftOrigin`` (an inverted-axis mode no Supervision caller uses) is
    rejected rather than silently ignored.
    """
    del lineType
    if bottomLeftOrigin:
        raise ValueError("bottomLeftOrigin is not supported by the fallback")
    if not text:
        return img

    font = _load_font(fontFace, fontScale)
    stroke_width = _stroke_width(thickness)
    x, y = round(org[0]), round(org[1])
    left, top, right, bottom = font.getbbox(
        text, anchor="ls", stroke_width=stroke_width
    )
    width, height = right - left, bottom - top
    if width <= 0 or height <= 0:
        return img

    mask_image = Image.new("1", (width, height))
    ImageDraw.Draw(mask_image).text(
        (-left, -top),
        text,
        fill=1,

View on GitHub (pinned to 7f254d9784)

Solutions

1. Pass bottomLeftOrigin=False (the default) and pre-flip the image yourself if you need inverted-axis rendering.
2. Install opencv-python-headless if you genuinely need bottomLeftOrigin behavior.

Example fix

# before
cv2.putText(img, 'hi', org, fontFace, 1, color, 2, bottomLeftOrigin=True)

# after
img = cv2.flip(img, 0)
cv2.putText(img, 'hi', (org[0], img.shape[0] - org[1]), fontFace, 1, color, 2)

if bottom_left_origin:
    raise NotImplementedError('bottomLeftOrigin unsupported without opencv-python')
cv2.putText(img, text, org, fontFace, scale, color, thickness, bottomLeftOrigin=False)

When it happens

Trigger: Calling cv2.putText(..., bottomLeftOrigin=True) while running without opencv-python, through Supervision's Pillow text renderer.

Common situations: Porting legacy OpenCV demo code that used bottomLeftOrigin=True for flipped-coordinate rendering; almost never hit via Supervision's public annotators, only via direct cv2.putText calls in the fallback environment.

Related errors

• Only OpenCV's default blur border is supported
• `image` must be a numpy.ndarray or PIL.Image.Image. Received
• `image` must be a numpy.ndarray or PIL.Image.Image. Received
• Expected shape (H,W), (H,W,3), or (H,W,4), got {image.shape}
• Unsupported image type: {type(scene)}

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