From 6bb5830120b5459611aeaf0caebe5e6bc5d9c5d3 Mon Sep 17 00:00:00 2001 From: Afloat Date: Sat, 21 Nov 2026 11:20:56 +0800 Subject: [PATCH] feat(office): optionally extract authored picture alternative text --- .../partition/test_office_picture_alt_text.py | 93 +++++++++++++++++++ unstructured/partition/docx.py | 30 +++++- unstructured/partition/pptx.py | 21 ++++- 3 files changed, 136 insertions(+), 8 deletions(-) create mode 100644 test_unstructured/partition/test_office_picture_alt_text.py diff --git a/test_unstructured/partition/test_office_picture_alt_text.py b/test_unstructured/partition/test_office_picture_alt_text.py new file mode 100644 index 0000000000..a238900acc --- /dev/null +++ b/test_unstructured/partition/test_office_picture_alt_text.py @@ -0,0 +1,93 @@ +import io + +import docx +import pptx +import pytest +from PIL import Image as PILImage +from pptx.util import Inches + +from unstructured.documents.elements import Image +from unstructured.partition.docx import DocxPartitionerOptions, partition_docx +from unstructured.partition.pptx import PptxPartitionerOptions, partition_pptx + + +def _document(kind, title, description): + image = io.BytesIO() + PILImage.new("RGB", (10, 10), "white").save(image, "PNG") + image.seek(0) + if kind == "docx": + document = docx.Document() + properties = document.add_picture(image)._inline.docPr + else: + document = pptx.Presentation() + slide = document.slides.add_slide(document.slide_layouts[6]) + picture = slide.shapes.add_picture(image, Inches(1), Inches(1)) + properties = picture._element.xpath("./p:nvPicPr/p:cNvPr")[0] + properties.set("title", title) + properties.set("descr", description) + file = io.BytesIO() + document.save(file) + return file + + +@pytest.mark.parametrize("kind", ["docx", "pptx"]) +@pytest.mark.parametrize( + ("title", "description", "expected"), + [ + ("", "Revenue increased by 20%.", "Revenue increased by 20%."), + ("Revenue chart", "", "Revenue chart"), + ("Revenue chart", "Revenue increased by 20%.", "Revenue chart\nRevenue increased by 20%."), + (" Same description ", "Same description", "Same description"), + ], +) +def test_authored_picture_alt_text_can_be_extracted_without_ocr(kind, title, description, expected): + file = _document(kind, title, description) + original = file.getvalue() + partition = partition_docx if kind == "docx" else partition_pptx + + elements = partition( + file=file, include_image_alt_text=True, starting_page_number=5, languages=["eng"] + ) + + assert len(elements) == 1 + assert isinstance(elements[0], Image) + assert elements[0].text == expected + assert elements[0].metadata.page_number == (5 if kind == "pptx" else None) + assert file.getvalue() == original + + +@pytest.mark.parametrize("kind", ["docx", "pptx"]) +def test_picture_without_authored_alt_text_does_not_emit_filename_as_content(kind): + partition = partition_docx if kind == "docx" else partition_pptx + + assert ( + partition(file=_document(kind, " ", "\n"), include_image_alt_text=True, languages=["eng"]) + == [] + ) + + +@pytest.mark.parametrize("kind", ["docx", "pptx"]) +def test_picture_alt_text_is_opt_in(kind): + partition = partition_docx if kind == "docx" else partition_pptx + + assert partition(file=_document(kind, "Chart", "Description"), languages=["eng"]) == [] + + +@pytest.mark.parametrize("kind", ["docx", "pptx"]) +def test_registered_picture_partitioner_keeps_control_without_duplicate_alt_text(kind, monkeypatch): + class CustomPicturePartitioner: + @classmethod + def iter_elements(cls, picture, opts): + yield Image("Custom result") + + options = DocxPartitionerOptions if kind == "docx" else PptxPartitionerOptions + partition = partition_docx if kind == "docx" else partition_pptx + monkeypatch.setattr(options, "_PicturePartitionerCls", CustomPicturePartitioner) + + elements = partition( + file=_document(kind, "Chart", "Description"), + include_image_alt_text=True, + languages=["eng"], + ) + + assert [element.text for element in elements] == ["Custom result"] diff --git a/unstructured/partition/docx.py b/unstructured/partition/docx.py index c55651824e..048a206470 100644 --- a/unstructured/partition/docx.py +++ b/unstructured/partition/docx.py @@ -159,6 +159,7 @@ def partition_docx( *, file: IO[bytes] | None = None, include_page_breaks: bool = True, + include_image_alt_text: bool = False, infer_table_structure: bool = True, starting_page_number: int = 1, strategy: str | None = None, @@ -175,6 +176,9 @@ def partition_docx( include_page_breaks When True, add a `PageBreak` element to the element-stream when a page-break is detected in the document. Note that not all DOCX files include page-break information. + include_image_alt_text + If True, the default picture partitioner emits authored image titles/descriptions as + Image elements without OCR. Registered picture partitioners keep control of their output. infer_table_structure If True, any Table elements that are extracted will also have a metadata field named "text_as_html" where the table's text content is rendered into an html string. @@ -194,6 +198,7 @@ def partition_docx( file=file, file_path=filename, include_page_breaks=include_page_breaks, + include_image_alt_text=include_image_alt_text, infer_table_structure=infer_table_structure, starting_page_number=starting_page_number, strategy=strategy, @@ -226,10 +231,12 @@ def __init__( infer_table_structure: bool, starting_page_number: int = 1, strategy: str | None = None, + include_image_alt_text: bool = False, ): self._file = file self._file_path = file_path self._include_page_breaks = include_page_breaks + self.include_image_alt_text = include_image_alt_text self._infer_table_structure = infer_table_structure self._strategy = strategy # -- options object maintains page-number state -- @@ -1640,10 +1647,25 @@ class _UnrenderableLabel(Exception): class _NullPicturePartitioner: - """Does not parse the provided paragraph for pictures and generates zero `Image` elements.""" + """Skip pictures by default, or emit their authored alt text when explicitly requested.""" @classmethod def iter_elements(cls, paragraph: Paragraph, opts: DocxPartitionerOptions) -> Iterator[Image]: - """No-op picture partitioner.""" - return - yield + """Generate alt-text Image elements without opening image data or performing OCR.""" + if not opts.include_image_alt_text: + return + for properties in paragraph._p.xpath( + ".//w:drawing/*[self::wp:inline or self::wp:anchor][.//pic:pic]/wp:docPr" + ): + parts = [properties.get(attr, "").strip() for attr in ("title", "descr")] + text = "\n".join(dict.fromkeys(part for part in parts if part)) + if text: + yield Image( + text, + detection_origin=DETECTION_ORIGIN, + metadata=ElementMetadata( + filename=opts.metadata_file_path, + last_modified=opts.last_modified, + page_number=opts.metadata_page_number, + ), + ) diff --git a/unstructured/partition/pptx.py b/unstructured/partition/pptx.py index cca1795f67..b468c9975f 100644 --- a/unstructured/partition/pptx.py +++ b/unstructured/partition/pptx.py @@ -28,6 +28,7 @@ Element, ElementMetadata, EmailAddress, + Image, ListItem, NarrativeText, PageBreak, @@ -133,6 +134,7 @@ def partition_pptx( *, file: IO[bytes] | None = None, include_page_breaks: bool = True, + include_image_alt_text: bool = False, include_slide_notes: bool | None = None, include_off_slide_shapes: bool = False, infer_table_structure: bool = True, @@ -150,6 +152,9 @@ def partition_pptx( A file-like object using "rb" mode --> open(filename, "rb"). include_page_breaks If True, includes a PageBreak element between slides + include_image_alt_text + If True, the default picture partitioner emits authored image titles/descriptions as + Image elements without OCR. Registered picture partitioners keep control of their output. include_slide_notes If True, includes the slide notes as element include_off_slide_shapes @@ -169,6 +174,7 @@ def partition_pptx( file=file, file_path=filename, include_page_breaks=include_page_breaks, + include_image_alt_text=include_image_alt_text, include_slide_notes=include_slide_notes, include_off_slide_shapes=include_off_slide_shapes, infer_table_structure=infer_table_structure, @@ -491,10 +497,12 @@ def __init__( infer_table_structure: bool, strategy: str, starting_page_number: int = 1, + include_image_alt_text: bool = False, ): self._file = file self._file_path = file_path self._include_page_breaks = include_page_breaks + self.include_image_alt_text = include_image_alt_text self._include_slide_notes = include_slide_notes self._include_off_slide_shapes = include_off_slide_shapes self._infer_table_structure = infer_table_structure @@ -645,10 +653,15 @@ def text_metadata(self, category_depth: int = 0) -> ElementMetadata: class _NullPicturePartitioner: - """Does not parse the provided Picture element and generates zero elements.""" + """Skip pictures by default, or emit their authored alt text when explicitly requested.""" @classmethod def iter_elements(cls, picture: Picture, opts: PptxPartitionerOptions) -> Iterator[Element]: - """No-op picture partitioner.""" - return - yield + """Generate an alt-text Image element without opening image data or performing OCR.""" + if not opts.include_image_alt_text: + return + for properties in picture._element.xpath("./p:nvPicPr/p:cNvPr"): + parts = [properties.get(attr, "").strip() for attr in ("title", "descr")] + text = "\n".join(dict.fromkeys(part for part in parts if part)) + if text: + yield Image(text, metadata=opts.text_metadata(), detection_origin=DETECTION_ORIGIN)