Add page recolor method

Author: JorjMcKie

docs/document.rst

@@ -923,14 +923,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)**,
 
@@ -958,7 +958,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)
 

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
@@ -1924,6 +1925,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 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.
+
+      The changes made are **permanent** and cannot be reverted.
+
    .. method:: remove_rotation()
 
       PDF only: Set page rotation to 0 while maintaining appearance and page content.

src/__init__.py

@@ -8694,6 +8694,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"""