DOCX Image Extraction#

The DOCX image extraction logic lives in MsWordDocumentBackend (docling/backend/msword_backend.py). It handles three distinct image types — DrawingML blip pictures, VML legacy images, and blip-less DrawingML shapes (SmartArt, charts) — dispatched from the central _walk_linear() method.

Three Extraction Paths#

The dispatcher in _walk_linear classifies each XML element and routes it accordingly 1:

DrawingML blip pictures (_handle_pictures)#

For each a:blip element, the backend calls _get_image_from_relationship() using the r:embed relationship attribute to retrieve raw image bytes. It then attempts direct PIL loading via Image.open() and validates the image by round-tripping it to PNG 2. On UnidentifiedImageError or OSError (e.g., WMF/EMF formats PIL can't decode), it falls back to _convert_elements_via_docx().

VML images (_handle_vml_pictures)#

Mirrors the DrawingML path but uses r:id as the relationship attribute (not r:embed) and searches for parent object or pict tags during DOCX conversion fallback 3. VML is the legacy format for embedded Visio drawings and similar objects.

Blip-less DrawingML shapes (_handle_drawingml)#

Shapes and SmartArt have no embedded image to extract directly. These are always rendered via _convert_elements_via_docx(), which requires LibreOffice. If LibreOffice is unavailable, a one-time warning is logged and the element is added as a picture placeholder 4. Native charts (graphicFrame elements referencing word/charts/chartN.xml) are handled separately by _handle_chart() without LibreOffice 5.

Relationship Resolution#

_get_image_from_relationship() is the single function responsible for resolving a relationship ID to binary image data. It uses self.current_part (which may be overridden for headers/footers) to look up the relationship target, skips external references with a warning, and returns the blob bytes from image_part.blob 6.

DOCX→PDF→PNG Rendering Pipeline#

_convert_elements_via_docx() handles all cases where PIL cannot directly decode an image:

1. Loads a fresh copy of the source DOCX, strips its body, and inserts a deep-copy of the target element(s) into a new paragraph run.
2. Calls get_pil_from_dml_docx() (in docling/backend/docx/drawingml/utils.py), which converts the scratch DOCX to PDF via LibreOffice, renders page 0 at 2× scale using pypdfium2, then crops whitespace.
3. Returns a PIL Image or None on failure 7.

The LibreOffice converter is lazily initialized once per document via the docx_to_pdf_converter_init flag 8. See the LibreOffice Integration knowledge base article for discovery and availability details.

Text Preservation#

A critical invariant: text in the same paragraph as an image must not be lost. All three dispatch branches in _walk_linear check for w:t nodes after handling the image and call _handle_text_elements() if any exist 9. For the blip-less DrawingML branch, text is always processed with skip_empty_text=True to filter spurious empty runs 10.

This was hardened across three PRs:

• PR #3394 — added image + text extraction for textbox containers, preventing double-extraction via XPath ancestry checks.
• PR #3484 — fixed text loss when LibreOffice is absent and DrawingML conversion is skipped.
• PR #3490 — made text extraction unconditional (regardless of LibreOffice availability), introducing skip_empty_text=True to avoid spurious empty items.

Spacer Filtering#

After any image is decoded, _is_invisible_spacer() filters out layout artifacts using three heuristics: area ≤ 25 px², fully transparent RGBA/LA images, and pure-white RGB images. Spacers are added to the document under ContentLayer.INVISIBLE rather than being dropped 11, preserving document structure without polluting main content.

Key Source Files#