ENH: Check whether image is displayed on a given page

pypdf/_page.py

@@ -414,6 +414,87 @@ def __str__(self) -> str:
     def __repr__(self) -> str:
         return self.__str__()[:-1] + f", hash: {hash(self.data)})"
 
+    def is_displayed_on_page(self, page: "PageObject") -> bool:
+        """
+        Check if this image is displayed on the specified page.
+
+        This method determines whether an image is actually rendered on a page
+        (not just referenced in resources). It checks the page's content stream
+        for image operators.
+
+        Args:
+            page: The page object to check.
+
+        Returns:
+            True if the image is displayed on the page, False otherwise.
+        """
+        # Check if this is an inline image or XObject image
+        # Inline images have names starting with "~"
+        if self.name.startswith("~"):
+            result = self._check_inline_image_displayed(page)
+        else:
+            result = self._check_xobject_image_displayed(page)
+
+        return result
+
+    def _check_inline_image_displayed(self, page: "PageObject") -> bool:
+        """
+        Check if an inline image is displayed on a page.
+
+        Inline images appear in the content stream as "INLINE IMAGE" operators.
+        The image name starts with "~" and is the first operand of the operator.
+
+        Args:
+            page: The page to check.
+
+        Returns:
+            True if the inline image is displayed on the page.
+        """
+        image_name = self.name.split(".")[0]
+
+        if page.inline_images:
+            return len(list(filter(lambda i: i == image_name, page.inline_images.keys()))) > 0
+        return False
+
+    def _check_xobject_image_displayed(self, page: "PageObject") -> bool:
+        """
+        Check if an XObject image is displayed on a page.
+
+        XObject images appear in the content stream as "Do" operators.
+        The image name is the first operand of the Do operator.
+        The name may have a leading "/" that needs to be stripped.
+
+        Args:
+            page: The page to check.
+
+        Returns:
+            True if the XObject image is displayed on the page.
+        """
+        from .generic._data_structures import ContentStream  # noqa: PLC0415
+
+        try:
+            if not self.indirect_reference:
+                return False
+
+            raw_contents = page.get(NameObject("/Contents"), None)
+
+            stream = ContentStream(raw_contents, self.indirect_reference.pdf)
+
+            for operands, operator in stream.operations:
+                # First operand is the XObject name (may have leading /)
+                if operator == b"Do" and operands:
+                    xobj_name = str(operands[0])
+                    # Compare base names (without extension like .jp2)
+                    img_base = self.name.split(".")[0].lstrip("/")
+                    xobj_base = xobj_name.lstrip("/")
+
+                    if img_base == xobj_base:
+                        return True
+        except (KeyError, IndexError, AttributeError):
+            pass
+
+        return False
+
 
 class VirtualListImages(Sequence[ImageFile]):
     """

tests/test_images.py

@@ -658,3 +658,52 @@ def test_get_ids_image__resources_is_none():
     reader = PdfReader(BytesIO(get_data_from_url(url, name=name)))
     page = reader.pages[2]
     assert list(page.images.items()) == []
+
+
+@pytest.mark.samples
+def test_is_xobject_image_displayed():
+    """
+    This test ensures that only actually displayed referenced images
+    are detected by `ImageFile.is_displayed_on_page`
+    """
+    path = SAMPLE_ROOT / "027-image-references-deduplication/wrong-references.pdf"
+    reader = PdfReader(path)
+    pages = reader.pages
+    page_1, page_2, page_3 = pages
+
+    # Page 1: Im8.jp2 displayed, Im20.jp2 not displayed
+    # Page 2: Neither displayed
+    # Page 3: Im20.jp2 displayed, Im8.jp2 not displayed
+    expected_results = [
+        (page_1, 0, "/Im20", False),
+        (page_1, 0, "/Im8", True),
+        (page_2, 1, "/Im20", False),
+        (page_2, 1, "/Im8", False),
+        (page_3, 2, "/Im20", True),
+        (page_3, 2, "/Im8", False),
+    ]
+
+    for page, page_num, image_id, expected in expected_results:
+        img = page.images[image_id]
+        is_used = img.is_displayed_on_page(page)
+        assert isinstance(is_used, bool), f"is_displayed_on_page() must return bool for {image_id}"
+        assert is_used == expected, f"Page {page_num}: {image_id} expected {expected}, got {is_used}"
+
+@pytest.mark.samples
+def test_is_inline_image_displayed():
+    """This test ensures that displayed inline images are detected by `ImageFile.is_displayed_on_page`"""
+    path = SAMPLE_ROOT / "008-reportlab-inline-image/inline-image.pdf"
+    reader = PdfReader(path)
+    pages = reader.pages
+    page_1 = pages[0]
+
+    # Page 1:
+    expected_results = [
+        (page_1, 0, "~0~", True),
+    ]
+
+    for page, page_num, image_id, expected in expected_results:
+        img = page.images[image_id]
+        is_used = img.is_displayed_on_page(page)
+        assert isinstance(is_used, bool), f"is_displayed_on_page() must return bool for {image_id}"
+        assert is_used == expected, f"Page {page_num}: {image_id} expected {expected}, got {is_used}"