docling-core 2.97.2__tar.gz → 2.98.0__tar.gz

{docling_core-2.97.2 → docling_core-2.98.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.97.2
+Version: 2.98.0
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>

{docling_core-2.97.2 → docling_core-2.98.0}/docling_core/transforms/serializer/markdown.py

@@ -37,8 +37,10 @@ from docling_core.transforms.serializer.common import (
 )
 from docling_core.types.doc import (
     BaseMeta,
+    CaptionPlacement,
     CodeItem,
     ContentLayer,
+    CoordOrigin,
     DescriptionAnnotation,
     DescriptionMetaField,
     DocItem,
@@ -65,6 +67,7 @@ from docling_core.types.doc import (
     PictureItem,
     PictureMoleculeData,
     PictureTabularChartData,
+    ProvenanceItem,
     RichTableCell,
     SectionHeaderItem,
     SummaryMetaField,
@@ -89,6 +92,61 @@ def _cell_content_has_table(item: NodeItem, doc: DoclingDocument) -> bool:
     return False
 
 
+def _captions_below_item(item: FloatingItem, doc: DoclingDocument) -> bool | None:
+    """Tell whether the item's captions sit below the item, judging by bbox centers.
+
+    Returns ``True`` if every caption is centered lower than the item on the page,
+    ``False`` if the item has captions located at or above it, and ``None`` if the
+    position cannot be determined (no captions, missing provenance, different pages
+    or unresolvable page height), in which case the caller keeps its default order.
+    """
+
+    def center_y(prov: ProvenanceItem) -> float | None:
+        bbox = prov.bbox
+        if bbox.coord_origin != CoordOrigin.TOPLEFT:
+            page = doc.pages.get(prov.page_no)
+            if page is None:
+                return None
+            bbox = bbox.to_top_left_origin(page_height=page.size.height)
+        return (bbox.t + bbox.b) / 2
+
+    if not item.prov or not item.captions:
+        return None
+    item_prov = item.prov[0]
+    item_y = center_y(item_prov)
+    if item_y is None:
+        return None
+
+    below: list[bool] = []
+    for cap_ref in item.captions:
+        cap = cap_ref.resolve(doc)
+        if not isinstance(cap, DocItem):
+            continue
+        cap_prov = next((p for p in cap.prov if p.page_no == item_prov.page_no), None)
+        if cap_prov is None or (cap_y := center_y(cap_prov)) is None:
+            return None
+        below.append(cap_y > item_y)
+    return all(below) if below else None
+
+
+def _caption_goes_after(
+    item: FloatingItem,
+    doc: DoclingDocument,
+    params: "MarkdownParams",
+    standard_after: bool,
+) -> bool:
+    """Decide whether the item's captions are serialized after the item.
+
+    ``standard_after`` is the item type's default order, used for ``STANDARD``
+    placement and whenever ``LAYOUT`` placement cannot determine the position.
+    """
+    if params.caption_placement == CaptionPlacement.LAYOUT:
+        below = _captions_below_item(item, doc)
+        if below is not None:
+            return below
+    return standard_after
+
+
 def _mark_subtree_visited(
     item: NodeItem,
     doc: DoclingDocument,
@@ -197,6 +255,15 @@ class MarkdownParams(CommonParams):
         default=True,
         description="Include the picture classification prediction (the image's predicted class).",
     )
+    caption_placement: CaptionPlacement = Field(
+        default=CaptionPlacement.STANDARD,
+        description=(
+            "Where captions go relative to their item. 'standard' keeps the per-type order "
+            "(before tables and pictures, after code and formulas); 'layout' places a caption "
+            "after its item if the caption's bbox center is lower on the page, else before, "
+            "falling back to 'standard' when positions are unavailable."
+        ),
+    )
 
 
 class MarkdownTextSerializer(BaseModel, BaseTextSerializer):
@@ -373,7 +440,10 @@ class MarkdownTextSerializer(BaseModel, BaseTextSerializer):
         if isinstance(item, FloatingItem):
             cap_res = doc_serializer.serialize_captions(item=item, **kwargs)
             if cap_res.text:
-                res_parts.append(cap_res)
+                if _caption_goes_after(item, doc, params, standard_after=True):
+                    res_parts.append(cap_res)
+                else:
+                    res_parts.insert(0, cap_res)
 
         text = (" " if is_inline_scope else "\n\n").join([r.text for r in res_parts])
         if processing_pending:
@@ -732,7 +802,8 @@ class MarkdownTableSerializer(BaseTableSerializer):
             item=item,
             **kwargs,
         )
-        if cap_res.text:
+        cap_after = _caption_goes_after(item, doc, params, standard_after=False)
+        if cap_res.text and not cap_after:
             res_parts.append(cap_res)
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
@@ -790,6 +861,9 @@ class MarkdownTableSerializer(BaseTableSerializer):
             if table_text:
                 res_parts.append(create_ser_result(text=table_text, span_source=item))
 
+        if cap_res.text and cap_after:
+            res_parts.append(cap_res)
+
         text_res = "\n\n".join([r.text for r in res_parts])
 
         return create_ser_result(text=text_res, span_source=res_parts)
@@ -828,7 +902,8 @@ class MarkdownPictureSerializer(BasePictureSerializer):
             item=item,
             **kwargs,
         )
-        if cap_res.text:
+        cap_after = _caption_goes_after(item, doc, params, standard_after=False)
+        if cap_res.text and not cap_after:
             res_parts.append(cap_res)
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
@@ -862,6 +937,10 @@ class MarkdownPictureSerializer(BasePictureSerializer):
                 md_table_content = temp_table.export_to_markdown(temp_doc)
                 if len(md_table_content) > 0:
                     res_parts.append(create_ser_result(text=md_table_content, span_source=item))
+
+        if cap_res.text and cap_after:
+            res_parts.append(cap_res)
+
         text_res = "\n\n".join([r.text for r in res_parts if r.text])
 
         return create_ser_result(text=text_res, span_source=res_parts)

{docling_core-2.97.2 → docling_core-2.98.0}/docling_core/types/doc/__init__.py

@@ -2,6 +2,7 @@
 
 from docling_core.types.doc.base import (
     BoundingBox,
+    CaptionPlacement,
     CoordOrigin,
     ImageRefMode,
     PydanticSerCtxKey,

{docling_core-2.97.2 → docling_core-2.98.0}/docling_core/types/doc/base.py

@@ -14,6 +14,13 @@ class ImageRefMode(str, Enum):
     REFERENCED = "referenced"  # reference the image via uri
 
 
+class CaptionPlacement(str, Enum):
+    """Placement of captions relative to the item they caption."""
+
+    STANDARD = "standard"  # per item type: before tables and pictures, after code and formulas
+    LAYOUT = "layout"  # by bbox: after the item if the caption is centered lower on the page, else before
+
+
 class CoordOrigin(str, Enum):
     """CoordOrigin."""
 

{docling_core-2.97.2 → docling_core-2.98.0}/docling_core/types/doc/document.py

@@ -52,6 +52,7 @@ from typing_extensions import Self, deprecated, override
 from docling_core.types.base import _JSON_POINTER_REGEX, VERSION_PATTERN, UniqueList
 from docling_core.types.doc import BoundingBox, Size
 from docling_core.types.doc.base import (
+    CaptionPlacement,
     CoordOrigin,
     ImageRefMode,
     PydanticSerCtxKey,
@@ -3722,6 +3723,7 @@ class DoclingDocument(BaseModel):
         mark_meta: bool = False,
         use_legacy_annotations: bool | None = None,  # deprecated
         include_picture_classification: bool = True,
+        caption_placement: CaptionPlacement = CaptionPlacement.STANDARD,
     ):
         """Save to markdown."""
         if isinstance(filename, str):
@@ -3755,6 +3757,7 @@ class DoclingDocument(BaseModel):
             use_legacy_annotations=use_legacy_annotations,
             mark_meta=mark_meta,
             include_picture_classification=include_picture_classification,
+            caption_placement=caption_placement,
         )
 
         filename.write_text(md_out, encoding="utf-8")
@@ -3788,6 +3791,7 @@ class DoclingDocument(BaseModel):
         blocked_meta_names: set[str] | None = None,
         mark_meta: bool = False,
         include_picture_classification: bool = True,
+        caption_placement: CaptionPlacement = CaptionPlacement.STANDARD,
     ) -> str:
         r"""Serialize to Markdown.
 
@@ -3863,6 +3867,12 @@ class DoclingDocument(BaseModel):
             classification prediction (the image's predicted class) in the export.
             (Default value = True).
         :type include_picture_classification: bool = True
+        :param caption_placement: Where captions go relative to their item: "standard" keeps
+            the per-type order (before tables and pictures, after code and formulas); "layout"
+            places a caption after its item if the caption's bbox center is lower on the page,
+            else before, falling back to "standard" when positions are unavailable.
+            (Default value = CaptionPlacement.STANDARD).
+        :type caption_placement: CaptionPlacement = CaptionPlacement.STANDARD
         """
         from docling_core.transforms.serializer.markdown import (
             MarkdownDocSerializer,
@@ -3915,6 +3925,7 @@ class DoclingDocument(BaseModel):
                 compact_tables=compact_tables,
                 traverse_pictures=traverse_pictures,
                 include_picture_classification=include_picture_classification,
+                caption_placement=caption_placement,
             ),
         )
         ser_res = serializer.serialize()

{docling_core-2.97.2 → docling_core-2.98.0}/docling_core.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.97.2
+Version: 2.98.0
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>

{docling_core-2.97.2 → docling_core-2.98.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docling-core"
-version = "2.97.2"  # DO NOT EDIT, updated automatically
+version = "2.98.0"  # DO NOT EDIT, updated automatically
 description = "A python library to define and validate data types in Docling."
 license = "MIT"
 license-files = ["LICENSE"]

{docling_core-2.97.2 → docling_core-2.98.0}/tests/test_serialization.py

@@ -18,6 +18,7 @@ from docling_core.transforms.serializer.html import (
     HTMLTableSerializer,
 )
 from docling_core.transforms.serializer.markdown import (
+    CaptionPlacement,
     MarkdownDocSerializer,
     MarkdownParams,
     MarkdownPictureSerializer,
@@ -1747,3 +1748,125 @@ def test_export_to_html_image_dir_without_referenced_raises(sample_doc, tmp_path
     """Passing image_dir without REFERENCED mode raises ValueError."""
     with pytest.raises(ValueError, match=r"ImageRefMode\.REFERENCED"):
         sample_doc.export_to_html(image_dir=tmp_path / "images")
+
+
+def _make_captioned_doc(
+    *,
+    kind: str,
+    cap_bbox: BoundingBox | None,
+    obj_bbox: BoundingBox | None,
+    page_no: int = 1,
+) -> DoclingDocument:
+    doc = DoclingDocument(name="cap_order")
+    doc.add_page(page_no=1, size=Size(width=100, height=200))
+
+    def prov(bbox: BoundingBox | None) -> ProvenanceItem | None:
+        if bbox is None:
+            return None
+        return ProvenanceItem(page_no=page_no, bbox=bbox, charspan=(0, 0))
+
+    caption = doc.add_text(label=DocItemLabel.CAPTION, text="THE CAPTION", prov=prov(cap_bbox))
+    if kind == "table":
+        table_data = TableData(num_rows=1, num_cols=1)
+        table_data.add_row(["cell"])
+        table_data.num_rows = 1
+        doc.add_table(data=table_data, caption=caption, prov=prov(obj_bbox))
+    else:
+        doc.add_picture(caption=caption, prov=prov(obj_bbox))
+    return doc
+
+
+def _tl(t: float, b: float) -> BoundingBox:
+    return BoundingBox(l=0, r=10, t=t, b=b, coord_origin=CoordOrigin.TOPLEFT)
+
+
+def _bl(t: float, b: float) -> BoundingBox:
+    return BoundingBox(l=0, r=10, t=t, b=b, coord_origin=CoordOrigin.BOTTOMLEFT)
+
+
+def _serialize_md(doc: DoclingDocument, placement: CaptionPlacement) -> str:
+    return MarkdownDocSerializer(doc=doc, params=MarkdownParams(caption_placement=placement)).serialize().text
+
+
+@pytest.mark.parametrize("kind, marker", [("table", "cell"), ("picture", "<!-- image -->")])
+@pytest.mark.parametrize(
+    "cap_bbox, obj_bbox, layout_caption_first",
+    [
+        (None, None, True),  # no bboxes: falls back to standard order (caption first)
+        (_tl(150, 170), None, True),  # object without bbox: falls back to standard order
+        (_tl(10, 30), _tl(50, 100), True),  # caption above
+        (_tl(150, 170), _tl(50, 100), False),  # caption below
+        (_bl(190, 170), _bl(150, 100), True),  # caption above, BOTTOMLEFT origin
+        (_bl(50, 30), _bl(150, 100), False),  # caption below, BOTTOMLEFT origin
+        (_tl(150, 170), _bl(150, 100), False),  # mixed origins: caption (y=160) below object (y=75)
+        (_tl(10, 30), _bl(150, 100), True),  # mixed origins: caption (y=20) above object (y=75)
+    ],
+)
+def test_markdown_caption_placement(kind, marker, cap_bbox, obj_bbox, layout_caption_first):
+    doc = _make_captioned_doc(kind=kind, cap_bbox=cap_bbox, obj_bbox=obj_bbox)
+
+    # standard ignores bboxes: tables and pictures always have the caption first
+    md = _serialize_md(doc, CaptionPlacement.STANDARD)
+    assert md.index("THE CAPTION") < md.index(marker)
+    assert md == doc.export_to_markdown()
+
+    md = _serialize_md(doc, CaptionPlacement.LAYOUT)
+    if layout_caption_first:
+        assert md.index("THE CAPTION") < md.index(marker)
+    else:
+        assert md.index("THE CAPTION") > md.index(marker)
+
+
+def test_markdown_caption_placement_layout_other_page_falls_back_to_standard():
+    doc = DoclingDocument(name="cap_pages")
+    doc.add_page(page_no=1, size=Size(width=100, height=200))
+    doc.add_page(page_no=2, size=Size(width=100, height=200))
+    caption = doc.add_text(
+        label=DocItemLabel.CAPTION,
+        text="THE CAPTION",
+        prov=ProvenanceItem(page_no=2, bbox=_tl(150, 170), charspan=(0, 0)),
+    )
+    doc.add_picture(caption=caption, prov=ProvenanceItem(page_no=1, bbox=_tl(50, 100), charspan=(0, 0)))
+    md = _serialize_md(doc, CaptionPlacement.LAYOUT)
+    assert md.index("THE CAPTION") < md.index("<!-- image -->")
+
+
+@pytest.mark.parametrize(
+    "cap_bbox, placement, caption_first",
+    [
+        (None, CaptionPlacement.STANDARD, False),  # standard: code captions come after
+        (_tl(10, 30), CaptionPlacement.STANDARD, False),  # standard ignores bboxes
+        (None, CaptionPlacement.LAYOUT, False),  # no bboxes: falls back to standard
+        (_tl(10, 30), CaptionPlacement.LAYOUT, True),  # caption above the code
+        (_tl(150, 170), CaptionPlacement.LAYOUT, False),  # caption below the code
+    ],
+)
+def test_markdown_caption_placement_code(cap_bbox, placement, caption_first):
+    doc = DoclingDocument(name="cap_code")
+    doc.add_page(page_no=1, size=Size(width=100, height=200))
+
+    def prov(bbox):
+        return None if bbox is None else ProvenanceItem(page_no=1, bbox=bbox, charspan=(0, 0))
+
+    caption = doc.add_text(label=DocItemLabel.CAPTION, text="THE CAPTION", prov=prov(cap_bbox))
+    code = doc.add_code(text="print(1)", prov=prov(_tl(50, 100) if cap_bbox else None))
+    code.captions.append(caption.get_ref())
+
+    md = _serialize_md(doc, placement)
+    assert (md.index("THE CAPTION") < md.index("print(1)")) == caption_first
+
+
+@pytest.mark.parametrize("placement", [CaptionPlacement.LAYOUT, "layout"])
+def test_export_and_save_markdown_caption_placement(tmp_path, placement):
+    doc = _make_captioned_doc(kind="picture", cap_bbox=_tl(150, 170), obj_bbox=_tl(50, 100))
+
+    md = doc.export_to_markdown(caption_placement=placement)
+    assert md.index("THE CAPTION") > md.index("<!-- image -->")
+
+    out = tmp_path / "out.md"
+    doc.save_as_markdown(out, caption_placement=placement)
+    assert out.read_text(encoding="utf-8") == md
+
+    # default is unchanged
+    assert doc.export_to_markdown().index("THE CAPTION") < doc.export_to_markdown().index("<!-- image -->")
+    assert doc.export_to_markdown() == doc.export_to_markdown(caption_placement="standard")