Add new Page utility method

Add `Page.replace_image()`, `Page.delete_image()` to globally replace / delete an image given by its xref.

Author: JorjMcKie

docs/page.rst

@@ -62,6 +62,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 :meth:`Page.apply_redactions`      PDF olny: process the redactions of the page
 :meth:`Page.bound`                 rectangle of the page
 :meth:`Page.delete_annot`          PDF only: delete an annotation
+:meth:`Page.delete_image`          PDF only: delete an image
 :meth:`Page.delete_link`           PDF only: delete a link
 :meth:`Page.delete_widget`         PDF only: delete a widget / field
 :meth:`Page.draw_bezier`           PDF only: draw a cubic Bezier curve
@@ -100,6 +101,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 :meth:`Page.load_widget`           PDF only: load a specific field
 :meth:`Page.load_links`            return the first link on a page
 :meth:`Page.new_shape`             PDF only: create a new :ref:`Shape`
+:meth:`Page.replace_image`         PDF only: replace an image
 :meth:`Page.search_for`            search for a string
 :meth:`Page.set_artbox`            PDF only: modify ``/ArtBox``
 :meth:`Page.set_bleedbox`          PDF only: modify ``/BleedBox``
@@ -949,6 +951,45 @@ In a nutshell, this is what you can do with PyMuPDF:
 
          6. Another efficient way to display the same image on multiple pages is another method: :meth:`show_pdf_page`. Consult :meth:`Document.convert_to_pdf` for how to obtain intermediary PDFs usable for that method. Demo script `fitz-logo.py <https://github.com/pymupdf/PyMuPDF-Utilities/tree/master/demo/fitz-logo.py>`_ implements a fairly complete approach.
 
+   
+   .. index::
+      pair: filename; replace_image
+      pair: pixmap; replace_image
+      pair: stream; replace_image
+      pair: xref; replace_image
+
+   .. method:: replace_image(xref, filename=None, pixmap=None, stream=None)
+
+      * New in v1.21.0
+
+      Replace the image at xref with another one.
+
+      :arg int xref: the :data:`xref` of the image.
+      :arg filename: the filename of the new image.
+      :arg pixmap: the :ref:`Pixmap` of the new image.
+      :arg stream: the memory area containing the new image.
+
+      Arguments ``filename``, ``pixmap``, ``stream`` have the same meaning as in :meth:`Page.insert_image`, especially exactly one of these must be provided.
+
+      This is a **global replacement:** the new image will also be shown wherever the old one has been displayed throughout the file.
+
+      This method mainly exists for technical purposes. Typical uses include replacing large images by smaller versions, like a lower resolution, graylevel instead of colored, etc., or changing transparency.
+   
+   
+   .. index::
+      pair: xref; delete_image
+
+   .. method:: delete_image(xref)
+
+      * New in v1.21.0
+
+      Delete the image at xref. This is slightly misleading: actually the image is being replaced with a small transparent :ref:`Pixmap` using above :meth:`Page.replace_image`. The visible effect however is equivalent.
+
+      :arg int xref: the :data:`xref` of the image.
+
+      This is a **global replacement:** the image will disappear wherever the old one has been displayed throughout the file.
+   
+   
    .. index::
       pair: blocks; Page.get_text
       pair: dict; Page.get_text

fitz/__init__.py

@@ -7,6 +7,7 @@
 # maintained and developed by Artifex Software, Inc. https://artifex.com.
 # ------------------------------------------------------------------------
 import sys
+
 from fitz.fitz import *
 
 # define the supported colorspaces for convenience
@@ -31,12 +32,16 @@
 # This atexit handler runs, but doesn't cause ~Tools() to be run.
 #
 import atexit
-def cleanup_tools( TOOLS):
-    #print(f'cleanup_tools: TOOLS={TOOLS} id(TOOLS)={id(TOOLS)}')
-    #print(f'TOOLS.thisown={TOOLS.thisown}')
+
+
+def cleanup_tools(TOOLS):
+    # print(f'cleanup_tools: TOOLS={TOOLS} id(TOOLS)={id(TOOLS)}')
+    # print(f'TOOLS.thisown={TOOLS.thisown}')
     del TOOLS
     del fitz.TOOLS
-atexit.register( cleanup_tools, TOOLS)
+
+
+atexit.register(cleanup_tools, TOOLS)
 
 if fitz.VersionFitz != fitz.TOOLS.mupdf_version():
     v1 = fitz.VersionFitz.split(".")
@@ -50,7 +55,6 @@ def cleanup_tools( TOOLS):
 # copy functions in 'utils' to their respective fitz classes
 import fitz.utils
 
-
 # ------------------------------------------------------------------------------
 # General
 # ------------------------------------------------------------------------------
@@ -127,6 +131,8 @@ def cleanup_tools( TOOLS):
 fitz.Page.get_label = fitz.utils.get_label
 fitz.Page.get_image_rects = fitz.utils.get_image_rects
 fitz.Page.get_textpage_ocr = fitz.utils.get_textpage_ocr
+fitz.Page.delete_image = fitz.utils.delete_image
+fitz.Page.replace_image = fitz.utils.replace_image
 
 # ------------------------------------------------------------------------
 # Annot

fitz/utils.py

@@ -12,13 +12,12 @@
 import os
 import random
 import string
+import tempfile
 import typing
 import warnings
-import tempfile
 
 from fitz import *
 
-
 TESSDATA_PREFIX = os.environ.get("TESSDATA_PREFIX")
 point_like = "point_like"
 rect_like = "rect_like"
@@ -236,6 +235,51 @@ def calc_matrix(sr, tr, keep=True, rotate=0):
     return xref
 
 
+def replace_image(page: Page, xref: int, *, filename=None, pixmap=None, stream=None):
+    """Replace the image referred to by xref.
+
+    Replace the image by changing the object definition stored under xref. This
+    will leave the pages appearance instructions intact, so the new image is
+    being displayed with the same bbox, rotation etc.
+    By providing a small fully transparent image, an effect as if the image had
+    been deleted can be achieved.
+    A typical use may include replacing large images by a smaller version,
+    e.g. with a lower resolution or graylevel instead of colored.
+
+    Args:
+        xref: the xref of the image to replace.
+        filename, pixmap, stream: exactly one of these must be provided. The
+            meaning being the same as in Page.insert_image.
+    """
+    doc = page.parent  # the owning document
+    if not doc.is_image(xref):
+        raise ValueError("xref not an image")  # insert new image anywhere in page
+    if bool(filename) + bool(stream) + bool(pixmap) != 1:
+        raise ValueError("Exactly one of filename/stream/pixmap must be given")
+    new_xref = page.insert_image(
+        page.rect, filename=filename, stream=stream, pixmap=pixmap
+    )
+    doc.xref_copy(new_xref, xref)  # copy over new to old
+    last_contents_xref = page.get_contents()[-1]
+    # new image insertion has created a new /Contents source,
+    # which we will set to spaces now
+    doc.update_stream(last_contents_xref, b" ")
+
+
+def delete_image(page: Page, xref: int):
+    """Delete the image referred to by xef.
+
+    Actually replaces by a small transparent Pixmap using method Page.replace_image.
+
+    Args:
+        xref: xref of the image to delete.
+    """
+    # make a small 100% transparent pixmap (of just any dimension)
+    pix = fitz.Pixmap(fitz.csGRAY, (0, 0, 1, 1), 1)
+    pix.clear_with()  # clear all samples bytes to 0x00
+    page.replace_image(xref, pixmap=pix)
+
+
 def insert_image(page, rect, **kwargs):
     """Insert an image for display in a rectangle.
 
@@ -810,15 +854,15 @@ def get_page_text(
 
 
 def get_pixmap(
-        page: Page,
-        *,
-        matrix: matrix_like=Identity,
-        dpi=None,
-        colorspace: Colorspace=csRGB,
-        clip: rect_like=None,
-        alpha: bool=False,
-        annots: bool=True,
-        ) -> Pixmap:
+    page: Page,
+    *,
+    matrix: matrix_like = Identity,
+    dpi=None,
+    colorspace: Colorspace = csRGB,
+    clip: rect_like = None,
+    alpha: bool = False,
+    annots: bool = True,
+) -> Pixmap:
     """Create pixmap of page.
 
     Keyword args:
@@ -876,7 +920,12 @@ def get_page_pixmap(
         annots: (bool) also render annotations
     """
     return doc[pno].get_pixmap(
-        matrix=matrix, dpi=dpi, colorspace=colorspace, clip=clip, alpha=alpha, annots=annots
+        matrix=matrix,
+        dpi=dpi,
+        colorspace=colorspace,
+        clip=clip,
+        alpha=alpha,
+        annots=annots,
     )