Support Image Stamps

JorjMcKie · JorjMcKie · commit dd4f4f233fb2 · 2025-04-14T07:25:17.000-04:00
Add support for image stamp annotations.
Add support for recoloring pages.
diff --git a/docs/document.rst b/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
@@ -924,14 +935,14 @@ For details on **embedded files** refer to Appendix 3.
 
   .. method:: get_page_fonts(pno, full=False)
 
-    PDF only: Return a list of all fonts (directly or indirectly) referenced by the page.
+    PDF only: Return a list of all fonts (directly or indirectly) referenced by the page object definition.
 
     :arg int pno: page number, 0-based, `-∞ < pno < page_count`.
     :arg bool full: whether to also include the referencer's :data:`xref`. If *True*, the returned items are one entry longer. Use this option if you need to know, whether the page directly references the font. In this case the last entry is 0. If the font is referenced by an `/XObject` of the page, you will find its :data:`xref` here.
 
     :rtype: list
 
-    :returns: a list of fonts referenced by this page. Each entry looks like
+    :returns: a list of fonts referenced by the object definition of the page. Each entry looks like
 
     **(xref, ext, type, basefont, name, encoding, referencer)**,
 
@@ -959,7 +970,12 @@ For details on **embedded files** refer to Appendix 3.
 
     .. note::
         * This list has no duplicate entries: the combination of :data:`xref`, *name* and *referencer* is unique.
-        * In general, this is a superset of the fonts actually in use by this page. The PDF creator may e.g. have specified some global list, of which each page only makes partial use.
+        * In general, this is a true superset of the fonts actually in use by this page. The PDF creator may e.g. have specified some global list, of which each page make only partial use.
+        * Be aware that font names returned by some variants of :meth:`Page.get_text` (respectively :ref:`TextPage` methods) need not (exactly) equal the base font name shown here. Reasons for any differences include:
+
+           - This method always shows any subset prefixes (the pattern ``ABCDEF+``), whereas text extractions do not do this by default.
+           - Text extractions use the base library to access the font name, which has a length cap of 31 bytes and generally interrogates the font file binary to access the name. Method ``get_page_fonts()`` however looks at the PDF definition source.
+           - Text extractions work for all supported document types in exactly the same way -- not just for PDFs. Consequently they do not contain PDF-specifics.
 
   .. method:: get_page_text(pno, output="text", flags=3, textpage=None, sort=False)
 
diff --git a/docs/page.rst b/docs/page.rst
@@ -106,6 +106,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.recolor`               PDF only: change the colorspace of objects
 :meth:`Page.remove_rotation`       PDF only: set page rotation to 0
 :meth:`Page.replace_image`         PDF only: replace an image
 :meth:`Page.search_for`            search for a string
@@ -543,23 +544,34 @@ In a nutshell, this is what you can do with PyMuPDF:
 
    .. method:: add_stamp_annot(rect, stamp=0)
 
-      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" annotation to e.g. indicate the document's intended use ("DRAFT", "CONFIDENTIAL", etc.). The parameter may be either an integer to select text from a predefined array of standard texts or an image.
 
       :arg rect_like rect: rectangle where to place the annotation.
+      :arg multiple stamp: The following options are available:
+      
+         * The id number (int) of the stamp text. For available stamps see :ref:`StampIcons`.
+   
+         * A string specifying an image file path.
 
-      :arg int stamp: id number of the stamp text. For available stamps see :ref:`StampIcons`.
+         * A ``bytes``, ``bytearray`` or ``io.BytesIO`` object for an image in memory.
 
-      .. note::
+         * A :ref:`Pixmap`.
+         
+      1. **Text-based stamps**
 
-         * 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.*
 
-      .. image:: images/img-stampannot.*
-         :scale: 80
+      2. **Image-based stamps**
 
+         * The image is scaled to fit into the rectangle `rect` such that the image's center and the center of `rect` coincide. The aspect ratio of the image is preserved, so the image may not fill the entire rectangle. However, at least one of the given rectangle's width or height are fully covered.
+         * The annotation can be modified via :meth:`Annot.set_opacity`. This method therefore is a way to display images transparently even if no alpha channel is present.
+         * Setting colors has no effect on image stamps.
+         * Rotating image-based stamps **is not supported**. Setting the rotation may lead to unexpected results.
+         
    .. method:: add_widget(widget)
 
       PDF only: Add a PDF Form field ("widget") to a page. This also **turns the PDF into a Form PDF**. Because of the large amount of different options available for widgets, we have developed a new class :ref:`Widget`, which contains the possible PDF field attributes. It must be used for both, form field creation and updates.
@@ -1935,6 +1947,14 @@ In a nutshell, this is what you can do with PyMuPDF:
 
       :arg int rotate: An integer specifying the required rotation in degrees. Must be an integer multiple of 90. Values will be converted to one of 0, 90, 180, 270.
 
+   .. method:: recolor(components=1)
+
+      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 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 grayscale. If a page is already grayscale, the method will not cause visible changes -- independent of the value of ``components``.
+
+      These changes are **permanent** and cannot be reverted.
+
    .. method:: remove_rotation()
 
       PDF only: Set page rotation to 0 while maintaining appearance and page content.
diff --git a/src/__init__.py b/src/__init__.py
@@ -5366,6 +5366,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.
 
@@ -7717,42 +7730,69 @@ def _add_square_or_circle(self, rect, annot_type):
         return Annot(annot)
 
     def _add_stamp_annot(self, rect, stamp=0):
+        rect = Rect(rect)
+        r = JM_rect_from_py(rect)
+        if mupdf.fz_is_infinite_rect(r) or mupdf.fz_is_empty_rect(r):
+            raise ValueError(MSG_BAD_RECT)
         page = self._pdf_page()
         stamp_id = [
-                PDF_NAME('Approved'),
-                PDF_NAME('AsIs'),
-                PDF_NAME('Confidential'),
-                PDF_NAME('Departmental'),
-                PDF_NAME('Experimental'),
-                PDF_NAME('Expired'),
-                PDF_NAME('Final'),
-                PDF_NAME('ForComment'),
-                PDF_NAME('ForPublicRelease'),
-                PDF_NAME('NotApproved'),
-                PDF_NAME('NotForPublicRelease'),
-                PDF_NAME('Sold'),
-                PDF_NAME('TopSecret'),
-                PDF_NAME('Draft'),
+                "Approved",
+                "AsIs",
+                "Confidential",
+                "Departmental",
+                "Experimental",
+                "Expired",
+                "Final",
+                "ForComment",
+                "ForPublicRelease",
+                "NotApproved",
+                "NotForPublicRelease",
+                "Sold",
+                "TopSecret",
+                "Draft",
                 ]
         n = len(stamp_id)
-        name = stamp_id[0]
-        r = JM_rect_from_py(rect)
-        if mupdf.fz_is_infinite_rect(r) or mupdf.fz_is_empty_rect(r):
-            raise ValueError( MSG_BAD_RECT)
-        if _INRANGE(stamp, 0, n-1):
+        buf = None
+        name = None
+        if stamp in range(n):
             name = stamp_id[stamp]
+        elif isinstance(stamp, Pixmap):
+            buf = stamp.tobytes()
+        elif isinstance(stamp, str):
+            buf = pathlib.Path(stamp).read_bytes()
+        elif isinstance(stamp, (bytes, bytearray)):
+            buf = stamp
+        elif isinstance(stamp, io.BytesIO):
+            buf = stamp.getvalue()
+        else:
+            name = stamp_id[0]
+
         annot = mupdf.pdf_create_annot(page, mupdf.PDF_ANNOT_STAMP)
-        mupdf.pdf_set_annot_rect(annot, r)
-        try:
-            n = PDF_NAME('Name')
-            mupdf.pdf_dict_put(mupdf.pdf_annot_obj(annot), PDF_NAME('Name'), name)
-        except Exception:
-            if g_exceptions_verbose:    exception_info()
-            raise
-        mupdf.pdf_set_annot_contents(
-                annot,
-                mupdf.pdf_dict_get_name(mupdf.pdf_annot_obj(annot), PDF_NAME('Name')),
-                )
+        if buf:  # image stamp
+            fzbuff = mupdf.fz_new_buffer_from_copied_data(buf)
+            img = mupdf.fz_new_image_from_buffer(fzbuff)
+
+            # compute image boundary box on page
+            w, h = img.w(), img.h()
+            scale = min(rect.width / w, rect.height / h)
+            width = w * scale  # bbox width
+            height = h * scale  # bbox height
+
+            # center of "rect"
+            center = (rect.tl + rect.br) / 2
+            x0 = center.x - width / 2
+            y0 = center.y - height / 2
+            x1 = x0 + width
+            y1 = y0 + height
+            r = mupdf.fz_make_rect(x0, y0, x1, y1)
+            mupdf.pdf_set_annot_rect(annot, r)
+            mupdf.pdf_set_annot_stamp_image(annot, img)
+            mupdf.pdf_dict_put(mupdf.pdf_annot_obj(annot), PDF_NAME("Name"), mupdf.pdf_new_name("ImageStamp"))
+            mupdf.pdf_set_annot_contents(annot, "Image Stamp")
+        else:  # text stamp
+            mupdf.pdf_set_annot_rect(annot, r)
+            mupdf.pdf_dict_put(mupdf.pdf_annot_obj(annot), PDF_NAME("Name"), PDF_NAME(name))
+            mupdf.pdf_set_annot_contents(annot, name)
         mupdf.pdf_update_annot(annot)
         JM_add_annot_id(annot, "A")
         return Annot(annot)
@@ -8510,7 +8550,7 @@ 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=0) -> Annot:
         """Add a ('rubber') 'Stamp' annotation."""
         old_rotation = annot_preprocess(self)
         try:
@@ -8601,6 +8641,19 @@ def annots(self, types=None):
             annot._yielded=True
             yield annot
 
+    def recolor(self, components=1):
+        """Convert colorspaces of objects on the page.
+        
+        Valid values are 1, 3 and 4.
+        """
+        if components not in (1, 3, 4):
+            raise ValueError("components must be one of 1, 3, 4")
+        pdfdoc = _as_pdf_document(self.parent)
+        ropt = mupdf.pdf_recolor_options()
+        ropt.num_comp = components
+        ropts = mupdf.PdfRecolorOptions(ropt)
+        mupdf.pdf_recolor_page(pdfdoc, self.number, ropts)
+
     @property
     def artbox(self):
         """The ArtBox"""
diff --git a/tests/test_annots.py b/tests/test_annots.py
@@ -144,15 +144,24 @@ def test_fileattachment():
 def test_stamp():
     doc = pymupdf.open()
     page = doc.new_page()
-    annot = page.add_stamp_annot(r, stamp=10)
+    annot = page.add_stamp_annot(r, stamp=0)
     assert annot.type == (13, "Stamp")
+    assert annot.info["content"] == "Approved"
     annot_id = annot.info["id"]
     annot_xref = annot.xref
     page.load_annot(annot_id)
     page.load_annot(annot_xref)
     page = doc.reload_page(page)
 
 
+def test_image_stamp():
+    doc = pymupdf.open()
+    page = doc.new_page()
+    filename = os.path.join(scriptdir, "resources", "nur-ruhig.jpg")
+    annot = page.add_stamp_annot(r, stamp=filename)
+    assert annot.info["content"] == "Image Stamp"
+
+
 def test_redact1():
     doc = pymupdf.open()
     page = doc.new_page()
