feat(cvat): support rotated CVAT boxes via enclosing axis-aligned bbox

- Store CVAT rotation on elements (rotation_deg, bbox_unrotated)
- Compute enclosing bbox for rotated rectangles and apply during parsing
- Add tests for rotation math and parser integration

Signed-off-by: Christoph Auer <cau@zurich.ibm.com>

Author: cau-git

docling_eval/cvat_tools/geometry.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import math
 from typing import Iterable, Iterator, Optional, Protocol, Sequence, TypeVar
 
 from docling_core.types.doc.base import BoundingBox, CoordOrigin
@@ -87,3 +88,56 @@ def iter_unique_by_bbox(
         if all(bbox_iou(element.bbox, kept.bbox) < iou_threshold for kept in seen):
             seen.append(element)
             yield element
+
+
+def bbox_enclosing_rotated_rect(
+    unrotated_bbox: BoundingBox, *, rotation_deg: float
+) -> BoundingBox:
+    """Return the smallest axis-aligned BoundingBox enclosing a rotated rectangle.
+
+    CVAT represents rotated boxes as an unrotated rectangle (xtl/ytl/xbr/ybr) plus a
+    `rotation` attribute. The rotation is applied around the center of that rectangle.
+
+    This helper returns an axis-aligned BoundingBox that encloses the rotated rectangle.
+    It preserves the input bbox coord origin and requires TOPLEFT coordinates (CVAT).
+    """
+    if unrotated_bbox.coord_origin != CoordOrigin.TOPLEFT:
+        raise ValueError(
+            "bbox_enclosing_rotated_rect currently expects CoordOrigin.TOPLEFT"
+        )
+
+    normalized = rotation_deg % 360.0
+    if normalized == 0.0:
+        return unrotated_bbox
+
+    theta = math.radians(normalized)
+    cos_t = math.cos(theta)
+    sin_t = math.sin(theta)
+
+    cx = (unrotated_bbox.l + unrotated_bbox.r) / 2.0
+    cy = (unrotated_bbox.t + unrotated_bbox.b) / 2.0
+
+    corners = (
+        (unrotated_bbox.l, unrotated_bbox.t),
+        (unrotated_bbox.r, unrotated_bbox.t),
+        (unrotated_bbox.r, unrotated_bbox.b),
+        (unrotated_bbox.l, unrotated_bbox.b),
+    )
+
+    xs: list[float] = []
+    ys: list[float] = []
+    for x, y in corners:
+        dx = x - cx
+        dy = y - cy
+        rx = cx + (dx * cos_t) - (dy * sin_t)
+        ry = cy + (dx * sin_t) + (dy * cos_t)
+        xs.append(rx)
+        ys.append(ry)
+
+    return BoundingBox(
+        l=min(xs),
+        t=min(ys),
+        r=max(xs),
+        b=max(ys),
+        coord_origin=unrotated_bbox.coord_origin,
+    )

docling_eval/cvat_tools/models.py

@@ -32,6 +32,15 @@ class CVATElement(BaseModel):
     id: int
     label: Union[DocItemLabel, GraphCellLabel, TableStructLabel]
     bbox: BoundingBox
+    # CVAT supports rotated rectangles via the `rotation` attribute on <box>.
+    # In CVAT, xtl/ytl/xbr/ybr describe the unrotated rectangle and the rotation is applied
+    # around the box center. Docling's BoundingBox is axis-aligned only, so we store both:
+    # - bbox: the axis-aligned bbox used by our pipeline (potentially expanded to enclose rotation)
+    # - bbox_unrotated: the raw, unrotated CVAT bbox as authored in the XML (TOPLEFT origin)
+    # - rotation_deg: the rotation in degrees as provided by CVAT (clockwise/counterclockwise is
+    #   irrelevant for the enclosing axis-aligned bbox of a rectangle).
+    rotation_deg: float = 0.0
+    bbox_unrotated: Optional[BoundingBox] = None
     content_layer: ContentLayer
     type: Optional[str] = None
     level: Optional[int] = None

docling_eval/cvat_tools/parser.py

@@ -10,6 +10,7 @@
 from docling_core.types.doc.document import ContentLayer
 from docling_core.types.doc.labels import DocItemLabel, GraphCellLabel
 
+from docling_eval.cvat_tools.geometry import bbox_enclosing_rotated_rect
 from docling_eval.cvat_tools.models import (
     CVATAnnotationPath,
     CVATElement,
@@ -183,7 +184,11 @@ def _parse_image_element(
         ytl = float(box.attrib["ytl"])
         xbr = float(box.attrib["xbr"])
         ybr = float(box.attrib["ybr"])
-        bbox = cvat_box_to_bbox(xtl, ytl, xbr, ybr)  # -> BoundingBox(l,t,r,b) TOPLEFT
+        bbox_unrotated = cvat_box_to_bbox(
+            xtl, ytl, xbr, ybr
+        )  # -> BoundingBox(l,t,r,b) TOPLEFT
+        rotation_deg = float(box.attrib.get("rotation", "0.0"))
+        bbox = bbox_enclosing_rotated_rect(bbox_unrotated, rotation_deg=rotation_deg)
 
         # Parse child <attribute> tags; default content_layer to BODY
         attributes: dict[str, str | None] = {}
@@ -216,6 +221,8 @@ def _parse_image_element(
                 id=box_id,
                 label=label_obj,  # Union[DocItemLabel, GraphCellLabel, TableStructLabel]
                 bbox=bbox,
+                bbox_unrotated=bbox_unrotated,
+                rotation_deg=rotation_deg,
                 content_layer=content_layer,
                 type=type_,
                 level=level,