roboflow/supervision · error · ValueError

EasyOCR results must contain four corner points per detectio

Error message

EasyOCR results must contain four corner points per detection.

What it means

from_easyocr builds an (N, 4, 2) array of four corner points from result[0] of each item. If the collected bbox array does not have exactly shape (N, 4, 2), the per-detection geometry is not a quad and the method raises this ValueError.

Source

Thrown at src/supervision/detection/core.py:2181

            reader = easyocr.Reader(['en'])
            results = reader.readtext("<SOURCE_IMAGE_PATH>")
            detections = sv.Detections.from_easyocr(results)
            detected_text = detections["class_name"]
            ```
        """
        if len(easyocr_results) == 0:
            return cls.empty()

        if isinstance(easyocr_results[0], str):
            raise ValueError(
                "EasyOCR results produced with detail=0 do not include bounding "
                "boxes. Call reader.readtext(..., detail=1) instead."
            )

        bbox = np.array([result[0] for result in easyocr_results], dtype=np.float32)
        if bbox.ndim != 3 or bbox.shape[1:] != (4, 2):
            raise ValueError(
                "EasyOCR results must contain four corner points per detection."
            )
        xyxy = np.hstack((np.min(bbox, axis=1), np.max(bbox, axis=1)))
        confidence = np.array(
            [
                result[2] if len(result) > 2 and result[2] else 0
                for result in easyocr_results
            ]
        )
        ocr_text = np.array([result[1] for result in easyocr_results])

        data: _DetectionDataType = {
            CLASS_NAME_DATA_FIELD: ocr_text,
            ORIENTED_BOX_COORDINATES: bbox,
        }
        return cls(
            xyxy=xyxy.astype(np.float32),
            confidence=confidence.astype(np.float32),

View on GitHub (pinned to 7f254d9784)

Solutions

  1. Pass EasyOCR's readtext(..., detail=1) output unmodified — it already yields 4-point quads.
  2. Pre-validate shape before the call: np.array([r[0] for r in results]) must have .shape[1:] == (4, 2).
  3. If you have xyxy boxes instead of quads, construct Detections directly (cls(xyxy=...)) rather than via from_easyocr.

Example fix

# before
results = [(det[:2], det[2], det[3]) for det in custom_dets]  # 2-point 'bbox'
detections = sv.Detections.from_easyocr(results)

# after
quads = [np.array([[x1,y1],[x2,y2],[x3,y3],[x4,y4]], dtype=np.float32) for x1,y1,x2,y2 in custom_xyxy]
results = [(q, 'text', 0.9) for q in quads]
detections = sv.Detections.from_easyocr(results)
Defensive patterns

Strategy: validation

Validate before calling

import numpy as np

def valid_easyocr_quads(results: list) -> bool:
    if not results:
        return True
    try:
        arr = np.array([r[0] for r in results], dtype=np.float32)
    except (ValueError, TypeError):
        return False
    return arr.ndim == 3 and arr.shape[1:] == (4, 2)

assert valid_easyocr_quads(results)
detections = sv.Detections.from_easyocr(results)

Type guard

def is_quad_format(result_item: tuple) -> bool:
    pts = result_item[0]
    return (
        isinstance(pts, (list, tuple)) and len(pts) == 4
        and all(len(p) == 2 for p in pts)
    )

Try / catch

try:
    detections = sv.Detections.from_easyocr(results)
except ValueError as e:
    if 'four corner points' in str(e):
        raise ValueError(f'malformed OCR geometry: {results[:2]!r}') from e
    raise

Prevention

When it happens

Trigger: Passing easyocr_results whose first elements are not exactly 4 (x, y) pairs each — e.g. hand-built tuples with 2 or 8 points, lists of pixel coordinates with wrong nesting, or results from readtext with batched/altered formats (some paragraph or modified decoders), producing ragged input that np.array flattens incorrectly.

Common situations: Reformatting EasyOCR output into custom shapes before calling from_easyocr; mixing results from different OCR engines or frames; passing rotated-box centers/sizes instead of corner quads; ragged lists that numpy turns into an object array with wrong ndim.

Related errors

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