Why do the images extracted from the PDF differ from those displayed on the page?

This paper uses synthetic samples to demonstrate the processing method. The code has been verified using examples in an isolated environment; this does not guarantee effectiveness for all real files or products. Before processing important files, please retain the original copies and verify them against the boundaries and acceptance criteria specified in the text. Which problem does this paper address first Images with transparency may be stored separately as the main image and a soft mask. Below, we construct an RGBA PNG using Pillow, then insert it into an in-memory PDF to examine both the main image and the SMask. Extracting the bytes of the main image does not yield a complete transparent effect, nor does it reconstruct all visible instances on the page. self-contained synthetic example dependencies are listed in the import section. The code constructs inputs in memory; runtime logs are provided separately and do not constitute a guarantee for all real-world files. from io import BytesIO from PIL import Image import pymupdf im = Image.new("RGBA", (16, 16), (255, 0, 0, 128)) raw = BytesIO() im.save(raw, format="PNG") with pymupdf.open() as doc: page = doc.new_page(width=100, height=100) page.insert_image(pymupdf.Rect(10, 10, 70, 70), stream=raw.getvalue()) images = page.get_images(full=True) assert len(images) == 1 xref, smask = images[0][:2] assert xref > 0 and smask > 0 assert doc.extract_image(xref)["width"] == 16 assert doc.extract_image(smask)["image"] Why do the images extracted from the PDF differ from those displayed on the page? When extracting images from a PDF using a script, the most common source of confusion is that the extracted files are either completely black with bizarre dimensions, or they simply lack backgrounds or watermarks that were clearly present on the page. This is usually not due to incorrect code, but rather because you’re directly reading the raw image objects (XRef) inside the PDF while ignoring the compositing instructions in the page rendering pipeline. In the PDF specification, image storage and page presentation are two decoupled layers; the raw objects are often just one component of the final visual output. Understanding this distinction is essential for performing high-quality document parsing, OCR preprocessing, or content reorganization. The fundamental difference between the original object and the rendering pipeline The PDF file structure is like a resource repository, Document.extract_image(xref) These methods simply extract the parts from the repository unchanged. However, on the page, these parts undergo transformations via the CTM (Coordinate Transformation Matrix), are scaled, clipped by a Clip Path, blended within a Transparency Group, and overlaid with a Soft Mask. The most typical discrepancy arises from SMask (Soft Mask): many PNGs with transparency channels are internally split in PDFs into an RGB image stream and a separate Gray mask stream. If you extract only the main image while discarding the associated SMask object, what remains is a solid-color rectangle without transparency; originally transparent areas will appear either black or white. Furthermore, to reduce file size, the same high-resolution base image may be reused across multiple pages, but each page applies it through different /BBox and the matrix display only their local regions; direct extraction would yield the full large image, rather than the cropped fragment visible to the user. This “what you see is not what you get” phenomenon is an inherent characteristic of PDF as an exchange format, not a flaw in the parsing library. Synthetic Test Environment and Boundary Condition Handling To verify the extraction logic without relying on external files, we must construct a synthetic PDF containing an SMask. The following code uses PyMuPDF to create a test document in memory, which includes an image object with an independent soft mask. This simulates the real-world scenario where “an icon has a transparent background but is stored as a separate stream at the underlying level.” correctly outputs the expected : The program should be able to detect that the image is associated with an SMask and successfully extract the primary image data. PyMuPDF image extraction and mask association verification The following Python code is fully self-contained and requires no external input files. It synthesizes a PDF with an SMask in memory and then verifies whether the extraction logic can correctly identify the mask association. The code includes two key assertions: one validates the integrity of normally extracted data, and the other verifies accurate perception of the SMask’s association status. This code focuses on metadata-level integrity verification . In actual production, if smask_xref != 0 , you need to use libraries such as Pillow to convert doc.extract_image(smask_xref) The result is pasted onto the main image as the alpha channel. The two assertions respectively cover the two core contracts—“data is extractable” and “mask association is visible”—preventing false positives when dealing with empty documents or API changes. extraction result acceptance and manual review boundary automated extraction can never fully replace visual verification. The table below summarizes common anomaly manifestations and their corresponding mitigation strategies, helping to distinguish between engineering issues that can be resolved by code and those that must be assessed manually. Observation of the phenomenon possible causes automated decision-making Manual review trigger condition image is entirely black or entirely white SMask is extracted as an independent image; color space decoding failed checks the smask association; attempts to fall back to the color space remains unrecognizable even after fallback; this involves spot colors/device-specific colors Image orientation inverted/stretching CTM matrix contains negative scaling or non-uniform transformations reads matrix parameters for geometric correction After correction, the text/face is visibly distorted; complex vector clipping path Multiple small images are stitched together to form a single large image tiling encoding (Tiling Pattern) or striped storage is cropped or stitched according to the BBox coordinates, or The splicing gap is obvious; logically, it should be an independent semantic unit. extraction succeeded, but the page is not visible is hidden by the OCG (Optional Content Group); it lies outside the clipping region queries OCG status filtering; compares with CropBox layer logic is complex (e.g., nested OCMD); dynamic form fields extremely low resolution/blurred The original embedding is the low-resolution thumbnail. records DPI metadata and is labeled as low-quality Key figures/tables and text are illegible due to blurriness; the source file needs to be rescanned. Please note that the “code demonstration” only verifies the connectivity of API calls and data flows; it does not equate to meeting the “end-to-end performance” standard. When encountering OCG nested logic, custom shaders, or encrypted documents, the script’s output serves only as a reference, and actual rendering in a PDF reader must be used as the acceptance criterion. uses this checklist for document translation first ensures that the page order, source locations, and text integrity have been thoroughly checked, then submits the same de-identified sample to the translation process. After translation, it is still necessary to verify that the headings, body text, and figure captions correspond correctly; one should not rely solely on whether the text flows smoothly. OmniDoc (Product Entry) provides an entry point for translating multi-format documents, and the official website highlights its OCR, terminology database, and bilingual alignment features. For teams that wish to start processing directly from files, this is a path worth evaluating with real-world samples. Please use de-identified files that you are authorized to upload, and verify the results against the checklist provided in this document; we do not claim that OmniDoc utilizes the open-source libraries or internal algorithms referenced herein, nor do we substitute examples for product performance testing. Original manufacturer interface based on: PyMuPDF document 。 - 1 -