Image stamp annotation support

Author: JorjMcKie

docs/document.rst

@@ -96,6 +96,7 @@ For details on **embedded files** refer to Appendix 3.
 :meth:`Document.pdf_catalog`            PDF only: :data:`xref` of catalog (root)
 :meth:`Document.pdf_trailer`            PDF only: trailer source
 :meth:`Document.prev_location`          return (chapter, pno) of preceding page
+:meth:`Document.recolor`                PDF only: execute :meth:`Page.recolor` for all pages
 :meth:`Document.reload_page`            PDF only: provide a new copy of a page
 :meth:`Document.resolve_names`          PDF only: Convert destination names into a Python dict
 :meth:`Document.save`                   PDF only: save the document
@@ -594,6 +595,16 @@ For details on **embedded files** refer to Appendix 3.
 
      To maintain a consistent API, for document types not supporting a chapter structure (like PDFs), :attr:`Document.chapter_count` is 1, and pages can also be loaded via tuples *(0, pno)*. See this [#f3]_ footnote for comments on performance improvements.
 
+
+  .. method:: recolor(components=1)
+
+    PDF only: Change the color component counts for all object types text, image and vector graphics for all pages.
+
+    :arg int components: desired color space indicated by the number of color components: 1 = DeviceGRAY, 3 = DeviceRGB, 4 = DeviceCMYK.
+
+    The typical use case is 1 (DeviceGRAY) which converts the PDF to grayscale.
+
+
   .. method:: reload_page(page)
 
     * New in v1.16.10

docs/images/img-imagestamp.png

@@ -536,24 +536,33 @@ In a nutshell, this is what you can do with PyMuPDF:
          There is also the `pdf2docx extract tables method`_ which is capable of table extraction if you prefer.
 
 
-   .. method:: add_stamp_annot(rect, stamp=0)
+   .. method:: add_stamp_annot(rect, stamp=0, *, image=None)
 
-      PDF only: Add a "rubber stamp" like annotation to e.g. indicate the document's intended use ("DRAFT", "CONFIDENTIAL", etc.).
+      PDF only: Add a "rubber stamp"-like annotation to e.g. indicate the document's intended use ("DRAFT", "CONFIDENTIAL", etc.). Instead of text, an image may also be shown.
 
       :arg rect_like rect: rectangle where to place the annotation.
-
       :arg int stamp: id number of the stamp text. For available stamps see :ref:`StampIcons`.
+      :arg multiple image: if not ``None``, an image specification is assumed and the ``stamp`` parameter will be ignored. Valid argument types are
+      
+         * a string specifying an image file path,
+         * a ``bytes``, ``bytearray`` or ``io.BytesIO`` object for an image in memory, and
+         * a :ref:`Pixmap`.
+         
+      1. **Text-based stamps**
 
-      .. note::
-
-         * The stamp's text and its border line will automatically be sized and be put horizontally and vertically centered in the given rectangle. :attr:`Annot.rect` is automatically calculated to fit the given **width** and will usually be smaller than this parameter.
+         * :attr:`Annot.rect` is automatically calculated as the largest rectangle with an aspect ratio of ``width/height = 3.8`` that fits in the provided ``rect``. Its position is vertically and horizontally centered.
          * The font chosen is "Times Bold" and the text will be upper case.
-         * The appearance can be changed using :meth:`Annot.set_opacity` and by setting the "stroke" color (no "fill" color supported).
-         * This can be used to create watermark images: on a temporary PDF page create a stamp annotation with a low opacity value, make a pixmap from it with *alpha=True* (and potentially also rotate it), discard the temporary PDF page and use the pixmap with :meth:`insert_image` for your target PDF.
+         * The appearance can be modified using :meth:`Annot.set_opacity` and by setting the "stroke" color. By PDF specification, stamp annotations have no "fill" color.
+
+         .. image:: images/img-stampannot.*
 
+      2. **Image-based stamps**
 
-      .. image:: images/img-stampannot.*
-         :scale: 80
+         * At first, a rectangle is computed like for text stamps: vertically and horizontally centered, aspect ratio ``width/height = 3.8``.
+         * Into that rectangle, the image will be inserted aligned left and vertically centered. The resulting image boundary box becomes :attr:`Annot.rect`.
+         * The annotation can be modified via :meth:`Annot.set_opacity`. This is a way to display images without alpha channel with transparency. Setting colors has no effect on image stamps.
+         
+         .. image:: images/img-imagestamp.*
 
    .. method:: add_widget(widget)
 
@@ -1929,7 +1938,7 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       PDF only: Change the colorspace components of all objects on page.
 
-      :arg int components: The desired count of color components. Must be one of 1, 3 or 4, which results in color space DeviceGray, DeviceRGB and DeviceCMYK respectively. The method affects text, images and vector graphics. For instance, with the default value 1, a page will be converted to gray-scale.
+      :arg int components: The desired count of color components. Must be one of 1, 3 or 4, which results in color spaces DeviceGray, DeviceRGB or DeviceCMYK respectively. The method affects text, images and vector graphics. For instance, with the default value 1, a page will be converted to gray-scale.
 
       The changes made are **permanent** and cannot be reverted.
 

docs/page.rst

@@ -5444,6 +5444,19 @@ def resolve_link(self, uri=None, chapters=0):
         pno = mupdf.fz_page_number_from_location(self.this, loc)
         return pno, xp, yp
 
+    def recolor(self, components=1):
+        """Change the color component count on all pages.
+
+        Args:
+            components: (int) desired color component count, one of 1, 3, 4.
+
+        Invokes the same-named method for all pages.
+        """
+        if not self.is_pdf:
+            raise ValueError("is no PDF")
+        for i in range(self.page_count):
+            self.load_page(i).recolor(components)
+
     def resolve_names(self):
         """Convert the PDF's destination names into a Python dict.
 
@@ -8604,11 +8617,30 @@ def add_squiggly_annot(
             q = CheckMarkerArg(quads)
         return self._add_text_marker(q, mupdf.PDF_ANNOT_SQUIGGLY)
 
-    def add_stamp_annot(self, rect: rect_like, stamp: int =0) -> Annot:
+    def add_stamp_annot(self, rect: rect_like, stamp: int =0, *, image=None) -> Annot:
         """Add a ('rubber') 'Stamp' annotation."""
+        if isinstance(image, Pixmap):
+            buf = image.tobytes()
+        elif isinstance(image, str):
+            buf = pathlib.Path(image).read_bytes()
+        elif isinstance(image, (bytes, bytearray)):
+            buf = image
+        elif isinstance(image, io.BytesIO):
+            buf = image.getvalue()
+        else:
+            buf = None
         old_rotation = annot_preprocess(self)
         try:
             annot = self._add_stamp_annot(rect, stamp)
+            if buf:
+                fzbuff = mupdf.fz_new_buffer_from_copied_data(buf)
+                img = mupdf.fz_new_image_from_buffer(fzbuff)
+                mupdf.pdf_set_annot_stamp_image(annot, img)
+                self.parent.xref_set_key(annot.xref, "Name", "null")
+                self.parent.xref_set_key(
+                    annot.xref, "Contents", "(Image Stamp)")
+                buf = None
+                fzbuff = None
         finally:
             if old_rotation != 0:
                 self.set_rotation(old_rotation)