docling-project/docling · error · ValueError

expected coordinate origin to be {CoordOrigin.TOPLEFT.value}

Error message

expected coordinate origin to be {CoordOrigin.TOPLEFT.value}

What it means

Raised by tesseract_box_to_bounding_rectangle() in docling/utils/ocr_utils.py when an original_offset BoundingBox is supplied whose coord_origin is not CoordOrigin.TOPLEFT. The function offsets Tesseract rectangle coordinates by simply adding offset.l and offset.t, which is only mathematically correct for top-left origin coordinates, so any other origin is rejected to avoid silently producing wrong geometry.

Source

Thrown at docling/utils/ocr_utils.py:59

    im_size: Tuple[int, int],
) -> BoundingRectangle:
    # box is in the top, left, height, width format, top left coordinates
    rect = rotate_bounding_box(bbox, angle=orientation, im_size=im_size)
    rect = BoundingRectangle(
        r_x0=rect.r_x0 / scale,
        r_y0=rect.r_y0 / scale,
        r_x1=rect.r_x1 / scale,
        r_y1=rect.r_y1 / scale,
        r_x2=rect.r_x2 / scale,
        r_y2=rect.r_y2 / scale,
        r_x3=rect.r_x3 / scale,
        r_y3=rect.r_y3 / scale,
        coord_origin=CoordOrigin.TOPLEFT,
    )
    if original_offset is not None:
        if original_offset.coord_origin is not CoordOrigin.TOPLEFT:
            msg = f"expected coordinate origin to be {CoordOrigin.TOPLEFT.value}"
            raise ValueError(msg)
        if original_offset is not None:
            rect.r_x0 += original_offset.l
            rect.r_x1 += original_offset.l
            rect.r_x2 += original_offset.l
            rect.r_x3 += original_offset.l
            rect.r_y0 += original_offset.t
            rect.r_y1 += original_offset.t
            rect.r_y2 += original_offset.t
            rect.r_y3 += original_offset.t
    return rect

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Convert the offset box to a top-left origin before the call using the BoundingBox's own conversion API (to_top_left_origin() / from relative image height), then pass it as original_offset.
2. Construct the offset box explicitly with coord_origin=CoordOrigin.TOPLEFT at creation time.
3. Pass original_offset=None and apply the offset yourself after checking/normalizing the origin.

Example fix

# before
rect = tesseract_box_to_bounding_rectangle(
    bbox, original_offset=crop_box, scale=s, orientation=0, im_size=size
)  # ValueError if crop_box is BOTTOMLEFT

# after
if crop_box.coord_origin is not CoordOrigin.TOPLEFT:
    crop_box = crop_box.to_top_left_origin(page_height)
rect = tesseract_box_to_bounding_rectangle(
    bbox, original_offset=crop_box, scale=s, orientation=0, im_size=size
)

from docling.datamodel.base_models import CoordOrigin

if original_offset is not None and original_offset.coord_origin is not CoordOrigin.TOPLEFT:
    original_offset = original_offset.to_top_left_origin(image_height)
rect = tesseract_box_to_bounding_rectangle(bbox, original_offset=original_offset, scale=scale, orientation=orientation, im_size=im_size)

from docling.datamodel.base_models import BoundingBox, CoordOrigin

def is_top_left(box: BoundingBox) -> bool:
    return box.coord_origin is CoordOrigin.TOPLEFT

try:
    rect = tesseract_box_to_bounding_rectangle(...)
except ValueError as exc:
    raise ValueError(f"offset box origin invalid: {exc}") from exc  # surface with context

When it happens

Trigger: Calling tesseract_box_to_bounding_rectangle(bbox, original_offset=offset, ...) where offset.coord_origin is CoordOrigin.BOTTOMLEFT (or anything other than TOPLEFT). This typically happens when the crop/offset box was created by code that assumes a bottom-left coordinate system, such as PDF-native or matplotlib-style coordinates.

Common situations: Mixing BoundingBox instances from different pipelines: a PDF backend (bottom-left origin) feeding an OCR crop step that expects image coordinates; converting page crops produced by another library that defaults to bottom-left; recent refactors that changed the coord_origin field of offset boxes.

Related errors

• Cannot specify both ocr_preset and ocr_custom_config.
• Unsupported EasyOCR language code: {language}
• Invalid RapidOCR model spec {value!r}. Expected '<backend>:<
• Unknown RapidOCR backend {backend!r} in {value!r}. Supported
• Invalid RapidOCR model spec {value!r}: {err}

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/7cd0524848f830a7. Report an issue: GitHub.