DOCX Embedded Image Handling#

MinerU extracts images embedded in DOCX files, serializes them to base64 data URIs, and passes them through the Office block pipeline — without applying any OCR to image content. The pipeline is entirely separate from the PDF/image pipeline and runs through three main stages: extraction, serialization, and storage.

Entry Point#

Processing begins in office_docx_analyze(), which calls convert_binary() to invoke the DocxConverter, then passes the resulting page-block lists to result_to_middle_json().

Stage 1: Image Detection and Extraction (DocxConverter)#

DocxConverter uses an XPath expression registered at init time to locate image references in the DOCX XML 1:

self.picture_xpath_expr = etree.XPath(
    ".//a:blip | .//v:imagedata", namespaces=...
)

This covers both modern DrawingML (a:blip) and legacy VML (v:imagedata) formats. During _walk_linear(), each top-level body element is checked for picture refs. When found, _handle_pictures() is called.

Inside _handle_pictures() 2:

1. Each picture ref's relationship ID (r:embed or r:id) is resolved against self.docx_obj.part.rels to get the image part.
2. Duplicate relationship IDs within the same element are skipped via a seen_rel_ids set.
3. The image part's raw bytes (.blob) are passed to serialize_office_image().
4. The resulting base64 string is stored as {"type": BlockType.IMAGE, "content": img_base64} and appended to self.cur_page 3.

For anchored (floating) images inside a paragraph, the text of that paragraph is processed first, then the image — preserving document order 4.

Images embedded in table cells are handled differently: mammoth pre-parses all top-level tables against the full DOCX package context, converting embedded images to inline data: URI <img src="..."> tags within the table HTML 5. Those <img> src attributes are preserved through the clean_table_html() step 6.

Stage 2: Serialization (serialize_office_image)#

serialize_office_image() in mineru/backend/utils/office_image.py handles the full serialization path:

• Vector images (WMF/EMF): Detected by part name extension or content-type 7. On non-Windows systems, these are replaced with a standard 320×180 gray placeholder reading "WMF/EMF placeholder / Use Windows to parse / the original image" 8. On Windows, Pillow attempts to render them as PNG 9.
• Raster images: Loaded via Pillow. If loading fails, None is returned and the block is skipped 10.
• Format normalization:
  • RGB images → JPEG 11
  • RGBA/LA images or palette images with transparency → PNG 12
  • All other modes → converted to RGB then JPEG 13

The output is a standard data URI string via image_to_b64str() (from mineru/utils/pdf_reader.py):

data:image/jpeg;base64,<base64-encoded bytes>

Stage 3: Block Restructuring and Storage#

In MagicModel, raw {"type": "image", "content": <base64>} blocks from the converter are restructured 14:

span = {
    "type": ContentType.IMAGE,
    "image_base64": block_content,
}

If an image_writer is provided to blocks_to_page_info(), each image span is written to persistent storage by save_span_image_if_needed() (from html_image_utils.py), which decodes the base64, writes the file, and replaces image_base64 with a local image_path. Without an image_writer, images remain as inline base64 data URIs in the output.

No OCR on Embedded Images#

There is no OCR step for images extracted from DOCX files. Unlike PDF images (which go through the ML model pipeline), DOCX images are passed through purely as pixel data — extracted, format-normalized, serialized to base64, and stored. Any text content within an embedded image is not extracted.

This is a known limitation. A related user report 15 shows that WMF images inside DOCX produce a warning Skipping WMF image part before Pillow load and result in placeholder output rather than any recognized content.

Key Files#