fix(docx): parse page headers and footers (#2599)

* fix(docx): parse page headers and footers

Signed-off-by: Cesar Berrospi Ramis <[email protected]>

* chore(docx): rename _add_header with _add_heading

To avoid confusion, rename _add_header function name with _add_heading
since the function is about adding section headings.

Signed-off-by: Cesar Berrospi Ramis <[email protected]>

* chore(docx): extend the page header and footer parsing to any content type

Signed-off-by: Cesar Berrospi Ramis <[email protected]>

* chore(docx): fix _add_header_footer function

Signed-off-by: Cesar Berrospi Ramis <[email protected]>

---------

Signed-off-by: Cesar Berrospi Ramis <[email protected]>

Author: ceberam

docling/backend/msword_backend.py

@@ -6,6 +6,7 @@
 from typing import Any, Callable, Final, Optional, Union
 
 from docling_core.types.doc import (
+    ContentLayer,
     DocItemLabel,
     DoclingDocument,
     DocumentOrigin,
@@ -95,6 +96,8 @@ def __init__(
         self.listIter = 0
         # Track list counters per numId and ilvl
         self.list_counters: dict[tuple[int, int], int] = {}
+        # Set starting content layer
+        self.content_layer = ContentLayer.BODY
 
         self.history: dict[str, Any] = {
             "names": [None],
@@ -148,6 +151,7 @@ def convert(self) -> DoclingDocument:
         if self.is_valid():
             assert self.docx_obj is not None
             doc, _ = self._walk_linear(self.docx_obj.element.body, doc)
+            self._add_header_footer(self.docx_obj, doc)
 
             return doc
         else:
@@ -258,12 +262,14 @@ def _walk_linear(
                                     label=GroupLabel.SECTION,
                                     parent=self.parents[level - 1],
                                     name="shape-text",
+                                    content_layer=self.content_layer,
                                 )
                                 added_elements.append(shape_group.get_ref())
                                 doc.add_text(
                                     label=DocItemLabel.TEXT,
                                     parent=shape_group,
                                     text=text_content,
+                                    content_layer=self.content_layer,
                                 )
 
                 if textbox_elements:
@@ -750,7 +756,10 @@ def _handle_textbox_content(
         level = self._get_level()
         # Create a textbox group to contain all text from the textbox
         textbox_group = doc.add_group(
-            label=GroupLabel.SECTION, parent=self.parents[level - 1], name="textbox"
+            label=GroupLabel.SECTION,
+            parent=self.parents[level - 1],
+            name="textbox",
+            content_layer=self.content_layer,
         )
         elem_ref.append(textbox_group.get_ref())
         # Set this as the current parent to ensure textbox content
@@ -864,7 +873,7 @@ def _create_or_reuse_parent(
         paragraph_elements: list,
     ) -> Optional[NodeItem]:
         return (
-            doc.add_inline_group(parent=prev_parent)
+            doc.add_inline_group(parent=prev_parent, content_layer=self.content_layer)
             if len(paragraph_elements) > 1
             else prev_parent
         )
@@ -932,7 +941,12 @@ def _handle_text_elements(
         if p_style_id in ["Title"]:
             for key in range(len(self.parents)):
                 self.parents[key] = None
-            te = doc.add_text(parent=None, label=DocItemLabel.TITLE, text=text)
+            te = doc.add_text(
+                parent=None,
+                label=DocItemLabel.TITLE,
+                text=text,
+                content_layer=self.content_layer,
+            )
             self.parents[0] = te
             elem_ref.append(te.get_ref())
         elif "Heading" in p_style_id:
@@ -943,7 +957,7 @@ def _handle_text_elements(
                 )
             else:
                 is_numbered_style = False
-            h1 = self._add_header(doc, p_level, text, is_numbered_style)
+            h1 = self._add_heading(doc, p_level, text, is_numbered_style)
             elem_ref.extend(h1)
 
         elif len(equations) > 0:
@@ -956,12 +970,15 @@ def _handle_text_elements(
                     label=DocItemLabel.FORMULA,
                     parent=self.parents[level - 1],
                     text=text.replace("<eq>", "").replace("</eq>", ""),
+                    content_layer=self.content_layer,
                 )
                 elem_ref.append(t1.get_ref())
             else:
                 # Inline equation
                 level = self._get_level()
-                inline_equation = doc.add_inline_group(parent=self.parents[level - 1])
+                inline_equation = doc.add_inline_group(
+                    parent=self.parents[level - 1], content_layer=self.content_layer
+                )
                 elem_ref.append(inline_equation.get_ref())
                 text_tmp = text
                 for eq in equations:
@@ -978,12 +995,14 @@ def _handle_text_elements(
                             label=DocItemLabel.TEXT,
                             parent=inline_equation,
                             text=pre_eq_text,
+                            content_layer=self.content_layer,
                         )
                         elem_ref.append(e1.get_ref())
                     e2 = doc.add_text(
                         label=DocItemLabel.FORMULA,
                         parent=inline_equation,
                         text=eq.replace("<eq>", "").replace("</eq>", ""),
+                        content_layer=self.content_layer,
                     )
                     elem_ref.append(e2.get_ref())
 
@@ -992,6 +1011,7 @@ def _handle_text_elements(
                         label=DocItemLabel.TEXT,
                         parent=inline_equation,
                         text=text_tmp.strip(),
+                        content_layer=self.content_layer,
                     )
                     elem_ref.append(e3.get_ref())
 
@@ -1018,6 +1038,7 @@ def _handle_text_elements(
                     text=text,
                     formatting=format,
                     hyperlink=hyperlink,
+                    content_layer=self.content_layer,
                 )
                 elem_ref.append(t2.get_ref())
 
@@ -1037,13 +1058,14 @@ def _handle_text_elements(
                     text=text,
                     formatting=format,
                     hyperlink=hyperlink,
+                    content_layer=self.content_layer,
                 )
                 elem_ref.append(t3.get_ref())
 
         self._update_history(p_style_id, p_level, numid, ilevel)
         return elem_ref
 
-    def _add_header(
+    def _add_heading(
         self,
         doc: DoclingDocument,
         curr_level: Optional[int],
@@ -1154,6 +1176,7 @@ def _add_formatted_list_item(
                         text=text,
                         formatting=format,
                         hyperlink=hyperlink,
+                        content_layer=self.content_layer,
                     )
         return elem_ref
 
@@ -1180,7 +1203,11 @@ def _add_list_item(
             # Reset counters for the new numbering sequence
             self._reset_list_counters_for_new_sequence(numid)
 
-            list_gr = doc.add_list_group(name="list", parent=self.parents[level - 1])
+            list_gr = doc.add_list_group(
+                name="list",
+                parent=self.parents[level - 1],
+                content_layer=self.content_layer,
+            )
             self.parents[level] = list_gr
             elem_ref.append(list_gr.get_ref())
 
@@ -1203,7 +1230,11 @@ def _add_list_item(
                 self.level_at_new_list + prev_indent + 1,
                 self.level_at_new_list + ilevel + 1,
             ):
-                list_gr1 = doc.add_list_group(name="list", parent=self.parents[i - 1])
+                list_gr1 = doc.add_list_group(
+                    name="list",
+                    parent=self.parents[i - 1],
+                    content_layer=self.content_layer,
+                )
                 self.parents[i] = list_gr1
                 elem_ref.append(list_gr1.get_ref())
 
@@ -1262,11 +1293,13 @@ def _group_cell_elements(
         doc: DoclingDocument,
         provs_in_cell: list[RefItem],
         docling_table: TableItem,
+        content_layer: ContentLayer = ContentLayer.BODY,
     ) -> RefItem:
         group_element = doc.add_group(
             label=GroupLabel.UNSPECIFIED,
             name=group_name,
             parent=docling_table,
+            content_layer=content_layer,
         )
         for prov in provs_in_cell:
             group_element.children.append(prov)
@@ -1298,7 +1331,9 @@ def _handle_tables(
 
         data = TableData(num_rows=num_rows, num_cols=num_cols)
         level = self._get_level()
-        docling_table = doc.add_table(data=data, parent=self.parents[level - 1])
+        docling_table = doc.add_table(
+            data=data, parent=self.parents[level - 1], content_layer=self.content_layer
+        )
         elem_ref.append(docling_table.get_ref())
 
         cell_set: set[CT_Tc] = set()
@@ -1349,7 +1384,11 @@ def _handle_tables(
                     rich_table_cell = True
                     group_name = f"rich_cell_group_{len(doc.tables)}_{col_idx}_{row.grid_cols_before + row_idx}"
                     ref_for_rich_cell = MsWordDocumentBackend._group_cell_elements(
-                        group_name, doc, provs_in_cell, docling_table
+                        group_name,
+                        doc,
+                        provs_in_cell,
+                        docling_table,
+                        content_layer=self.content_layer,
                     )
 
                 if rich_table_cell:
@@ -1383,6 +1422,26 @@ def _handle_tables(
                     col_idx += cell.grid_span
         return elem_ref
 
+    def _has_blip(self, element: BaseOxmlElement) -> bool:
+        """Check if a docx element holds any BLIP as a child.
+
+        Args:
+            element: a docx element
+
+        Returns:
+            Whether the element contains a BLIP as a direct child.
+        """
+
+        for item in element:
+            if self.blip_xpath_expr(item):
+                return True
+            if item.findall(
+                ".//w:drawing", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
+            ):
+                return True
+
+        return False
+
     def _is_rich_table_cell(self, cell: _Cell) -> bool:
         """Determine whether a docx cell should be parsed as a Docling RichTableCell.
 
@@ -1420,13 +1479,8 @@ def _is_rich_table_cell(self, cell: _Cell) -> bool:
             tag = child.tag.split("}")[-1]
             if tag not in allowed_tags:
                 return True
-        for elem in tc:
-            if self.blip_xpath_expr(elem):
-                return True
-            if elem.findall(
-                ".//w:drawing", namespaces=MsWordDocumentBackend._BLIP_NAMESPACES
-            ):
-                return True
+        if self._has_blip(tc):
+            return True
 
         # paragraph must contain runs with no run-properties
         for para in paragraphs:
@@ -1468,6 +1522,7 @@ def get_docx_image(drawing_blip: Any) -> Optional[bytes]:
             p1 = doc.add_picture(
                 parent=self.parents[level - 1],
                 caption=None,
+                content_layer=self.content_layer,
             )
             elem_ref.append(p1.get_ref())
         else:
@@ -1478,13 +1533,15 @@ def get_docx_image(drawing_blip: Any) -> Optional[bytes]:
                     parent=self.parents[level - 1],
                     image=ImageRef.from_pil(image=pil_image, dpi=72),
                     caption=None,
+                    content_layer=self.content_layer,
                 )
                 elem_ref.append(p2.get_ref())
             except (UnidentifiedImageError, OSError):
                 _log.warning("Warning: image cannot be loaded by Pillow")
                 p3 = doc.add_picture(
                     parent=self.parents[level - 1],
                     caption=None,
+                    content_layer=self.content_layer,
                 )
                 elem_ref.append(p3.get_ref())
         return elem_ref
@@ -1515,12 +1572,68 @@ def _handle_drawingml(self, doc: DoclingDocument, drawingml_els: Any):
                 parent=self.parents[level - 1],
                 image=ImageRef.from_pil(image=pil_image, dpi=72),
                 caption=None,
+                content_layer=self.content_layer,
             )
         except (UnidentifiedImageError, OSError):
             _log.warning("Warning: DrawingML image cannot be loaded by Pillow")
             doc.add_picture(
                 parent=self.parents[level - 1],
                 caption=None,
+                content_layer=self.content_layer,
             )
 
         return
+
+    def _add_header_footer(self, docx_obj: DocxDocument, doc: DoclingDocument) -> None:
+        """Add section headers and footers.
+
+        Headers and footers are added in the furniture content and only the text paragraphs
+        are parsed. The paragraphs are attached to a single group item for the header or the
+        footer. If the document has a section with new header and footer, they will be parsed
+        in new group items.
+
+        Args:
+            docx_obj: A docx Document object to be parsed.
+            doc: A DoclingDocument object to add the header and footer from docx_obj.
+        """
+        current_layer = self.content_layer
+        base_parent = self.parents[0]
+        self.content_layer = ContentLayer.FURNITURE
+        for sec_idx, section in enumerate(docx_obj.sections):
+            if sec_idx > 0 and not section.different_first_page_header_footer:
+                continue
+
+            hdr = (
+                section.first_page_header
+                if section.different_first_page_header_footer
+                else section.header
+            )
+            par = [txt for txt in (par.text.strip() for par in hdr.paragraphs) if txt]
+            tables = hdr.tables
+            has_blip = self._has_blip(hdr._element)
+            if par or tables or has_blip:
+                self.parents[0] = doc.add_group(
+                    label=GroupLabel.SECTION,
+                    name="page header",
+                    content_layer=self.content_layer,
+                )
+                self._walk_linear(hdr._element, doc)
+
+            ftr = (
+                section.first_page_footer
+                if section.different_first_page_header_footer
+                else section.footer
+            )
+            par = [txt for txt in (par.text.strip() for par in ftr.paragraphs) if txt]
+            tables = ftr.tables
+            has_blip = self._has_blip(ftr._element)
+            if par or tables or has_blip:
+                self.parents[0] = doc.add_group(
+                    label=GroupLabel.SECTION,
+                    name="page footer",
+                    content_layer=self.content_layer,
+                )
+                self._walk_linear(ftr._element, doc)
+
+        self.content_layer = current_layer
+        self.parents[0] = base_parent

tests/data/docx/unit_test_formatting.docx

@@ -29,4 +29,7 @@ item-0 at level 0: unspecified: group _root_
           item-28 at level 5: text: Nested
           item-29 at level 5: text: italic
           item-30 at level 5: text: bold
-  item-31 at level 1: text: 
+  item-31 at level 1: text: 
+  item-32 at level 1: text: The second page of the document with same header and footer
+  item-33 at level 1: text: 
+  item-34 at level 1: text: The third page of the document with different header and footer