upload v1.19.3

Author: JorjMcKie

README.md

@@ -2,7 +2,7 @@
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: December 15, 2021
+Release date: December 12, 2021
 
 On **[PyPI](https://pypi.org/project/PyMuPDF)** since August 2016: [![Downloads](https://static.pepy.tech/personalized-badge/pymupdf?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/pymupdf)
 
@@ -60,11 +60,7 @@ Have a look at the basic [demos](https://github.com/pymupdf/PyMuPDF-Utilities/tr
 Documentation is written using Sphinx and is available in various formats from the following sources. It currently is a combination of reference guide and user manual. For a **quick start** look at the [tutorial](https://pymupdf.readthedocs.io/en/latest/tutorial.html) and the [recipes](https://pymupdf.readthedocs.io/en/latest/faq.html) chapters.
 
 * You can view it online at [Read the Docs](https://readthedocs.org/projects/pymupdf/). This site also provides download options for PDF.
-<<<<<<< Updated upstream
-* The search function on Read the Docs does not work for me currently. If you want a working searchable local version, please download a zipped HTML for [here](https://github.com/pymupdf/PyMuPDF-optional-material/tree/master/doc/pymupdf.zip).
-=======
 * The search function on Read the Docs does not work for me currently. If you want a working searchable local version, please download a zipped HTML from [here](https://github.com/pymupdf/PyMuPDF-optional-material/tree/master/doc/pymupdf.zip).
->>>>>>> Stashed changes
 * Find a Windows help file [here](https://github.com/pymupdf/PyMuPDF-optional-material/tree/master/doc/PyMuPDF.chm).
 
 The latest changelog can be viewed [here](https://pymupdf.readthedocs.io/en/latest/changes.html).
@@ -81,12 +77,12 @@ python -m pip install --upgrade pip
 python -m pip install --upgrade pymupdf
 ```
 
-There are **no mandatory** external dependencies. However, some **optional features** become available if additional packages are installed:
+There are **no mandatory** external dependencies. However, some **optional features** become available only if additional packages are installed:
 
 * [Pillow](https://pypi.org/project/Pillow/) for using pillow image output directly from PyMuPDF
-* [fontTools](https://pypi.org/project/fonttools/) for creating font subsets
-* [pymupdf-fonts](https://pypi.org/project/pymupdf-fonts/) contains some nice fonts for your text output
-* [Tesseract-OCR](https://github.com/tesseract-ocr/tesseract) for optical character recognition in images and document pages. Tesseract is separate software, not a Python package. To enable OCR functions in PyMuPDF, the system environment variable `"TESSDATA_PREFIX"` must be defined and contain the `tessdata` folder name of the Tesseract installation location
+* [fontTools](https://pypi.org/project/fonttools/) for creating font subsets.
+* [pymupdf-fonts](https://pypi.org/project/pymupdf-fonts/) contains some nice fonts for your text output.
+* [Tesseract-OCR](https://github.com/tesseract-ocr/tesseract) for optical character recognition in images and document pages. Tesseract is separate software, not a Python package. To enable OCR functions in PyMuPDF, the system environment variable `"TESSDATA_PREFIX"` must be defined and contain the `tessdata` folder name of the Tesseract installation location.
 
 
 Older wheels - also with support for older Python versions - can be found [here](https://github.com/pymupdf/PyMuPDF-Optional-Material/tree/master/wheels-upto-Py3.5>) and on PyPI.

changes.rst

@@ -8,13 +8,23 @@ Change Log
 This patch version implements minor improvements for :ref:`Pixmap` and also some important fixes.
 
 * **Fixed** `#1351 <https://github.com/pymupdf/PyMuPDF/discussions/1351>`_. Reverted code that introduced the memory growth in v1.18.15.
+
 * **Fixed** `#1417 <https://github.com/pymupdf/PyMuPDF/discussions/1417>`_. Developped circumvention for growth of open file handles using :meth:`Document.insert_pdf`.
+
 * **Fixed** `#1418 <https://github.com/pymupdf/PyMuPDF/discussions/1418>`_. Developped circumvention for memory growth using :meth:`Document.insert_pdf`.
+
 * **Fixed** `#1430 <https://github.com/pymupdf/PyMuPDF/discussions/1430>`_. Developped circumvention for mass pixmap generations of document pages.
+
 * **Fixed** `#1433 <https://github.com/pymupdf/PyMuPDF/discussions/1433>`_. Solves a bbox error for some Type 3 font in PyMuPDF text processing.
+
 * **Added** :meth:`Pixmap.color_topusage` to determine the share of the most frequently used color. Solves `#1397 <https://github.com/pymupdf/PyMuPDF/discussions/1397>`_.
+
 * **Added** :meth:`Pixmap.warp` which makes a new pixmap from a given arbitrary convex quad inside the pixmap.
+
+* **Added** :attr:`Annot.irt_xref` and :meth:`Annot.set_irt_xref` to inquire or set the `/IRT` ("In Responde To") property of an annotation. Implements `#1450 <https://github.com/pymupdf/PyMuPDF/discussions/1450>`_.
+
 * **Added** :meth:`Rect.torect` and :meth:`IRect.torect` which compute a matrix that transforms to a given other rectangle.
+
 * **Changed** :meth:`Pixmap.color_count` to also return the count of each color.
 * **Changed** :meth:`Page.get_texttrace` to also return correct span and character bboxes if ``span["dir"] != (1, 0)``.
 

docs/annot.rst

@@ -32,6 +32,7 @@ There is a parent-child relationship between an annotation and its page. If the
 :meth:`Annot.set_blendmode`        set annotation's blend mode
 :meth:`Annot.set_colors`           set annotation's colors
 :meth:`Annot.set_flags`            set annotation's flags field
+:meth:`Annot.set_irt_xref`         define the annotation to being "In Response To"
 :meth:`Annot.set_name`             set annotation's name field
 :meth:`Annot.set_oc`               set :data:`xref` to an :data:`OCG` / :data:`OCMD`
 :meth:`Annot.set_opacity`          change transparency
@@ -46,6 +47,7 @@ There is a parent-child relationship between an annotation and its page. If the
 :attr:`Annot.colors`               border / background and fill colors
 :attr:`Annot.flags`                annotation flags
 :attr:`Annot.has_popup`            whether annotation has a Popup
+:attr:`Annot.irt_xref`             annotation to which this one responds
 :attr:`Annot.info`                 various information
 :attr:`Annot.is_open`              whether annotation or its Popup is open
 :attr:`Annot.line_ends`            start / end appearance of line-type annotations
@@ -173,6 +175,17 @@ There is a parent-child relationship between an annotation and its page. If the
       :returns: zero or the xref of an OCG (or OCMD).
 
 
+   .. method:: set_irt_xref(xref)
+
+      * New in v1.19.3
+
+      Set annotation to be "In Response To" another one.
+
+      :arg int xref: The :data:`xref` of another annotation.
+
+         .. note:: Must refer to an existing annotation on this page. Setting this property requires no subsequent ``update()``.
+
+
    .. method:: set_open(value)
 
       *(New in v1.18.4)*
@@ -477,6 +490,12 @@ There is a parent-child relationship between an annotation and its page. If the
 
       :rtype: int
 
+   .. attribute:: irt_xref
+
+      The PDF :data:`xref` of an annotation to which this one responds. Return zero if this is no response annotation.
+
+      :rtype: int
+
    .. attribute:: popup_xref
 
       The PDF :data:`xref` of the associated Popup annotation. Zero if non-existent.

docs/changes.rst

@@ -8,13 +8,23 @@ Change Log
 This patch version implements minor improvements for :ref:`Pixmap` and also some important fixes.
 
 * **Fixed** `#1351 <https://github.com/pymupdf/PyMuPDF/discussions/1351>`_. Reverted code that introduced the memory growth in v1.18.15.
+
 * **Fixed** `#1417 <https://github.com/pymupdf/PyMuPDF/discussions/1417>`_. Developped circumvention for growth of open file handles using :meth:`Document.insert_pdf`.
+
 * **Fixed** `#1418 <https://github.com/pymupdf/PyMuPDF/discussions/1418>`_. Developped circumvention for memory growth using :meth:`Document.insert_pdf`.
+
 * **Fixed** `#1430 <https://github.com/pymupdf/PyMuPDF/discussions/1430>`_. Developped circumvention for mass pixmap generations of document pages.
+
 * **Fixed** `#1433 <https://github.com/pymupdf/PyMuPDF/discussions/1433>`_. Solves a bbox error for some Type 3 font in PyMuPDF text processing.
+
 * **Added** :meth:`Pixmap.color_topusage` to determine the share of the most frequently used color. Solves `#1397 <https://github.com/pymupdf/PyMuPDF/discussions/1397>`_.
+
 * **Added** :meth:`Pixmap.warp` which makes a new pixmap from a given arbitrary convex quad inside the pixmap.
+
+* **Added** :attr:`Annot.irt_xref` and :meth:`Annot.set_irt_xref` to inquire or set the `/IRT` ("In Responde To") property of an annotation. Implements `#1450 <https://github.com/pymupdf/PyMuPDF/discussions/1450>`_.
+
 * **Added** :meth:`Rect.torect` and :meth:`IRect.torect` which compute a matrix that transforms to a given other rectangle.
+
 * **Changed** :meth:`Pixmap.color_count` to also return the count of each color.
 * **Changed** :meth:`Page.get_texttrace` to also return correct span and character bboxes if ``span["dir"] != (1, 0)``.
 

docs/document.rst

@@ -1169,6 +1169,8 @@ For details on **embedded files** refer to Appendix 3.
 
     .. method:: insert_pdf(docsrc, from_page=-1, to_page=-1, start_at=-1, rotate=-1, links=True, annots=True, show_progress=0, final=1)
 
+      * Changed in v1.19.3 - as a fix to issue `#537 <https://github.com/pymupdf/PyMuPDF/issues/537>`_, form fields are always excluded.
+
       PDF only: Copy the page range **[from_page, to_page]** (including both) of PDF document *docsrc* into the current one. Inserts will start with page number *start_at*. Value -1 indicates default values. All pages thus copied will be rotated as specified. Links and annotations can be excluded in the target, see below. All page numbers are 0-based.
 
       :arg docsrc: An opened PDF *Document* which must not be the current document. However, it may refer to the same underlying file.
@@ -1183,7 +1185,7 @@ For details on **embedded files** refer to Appendix 3.
       :arg int rotate: All copied pages will be rotated by the provided value (degrees, integer multiple of 90).
 
       :arg bool links: Choose whether (internal and external) links should be included in the copy. Default is *True*. Internal links to outside the copied page range are **always excluded**.
-      :arg bool annots: *(new in version 1.16.1)* choose whether annotations should be included in the copy.
+      :arg bool annots: *(new in version 1.16.1)* choose whether annotations should be included in the copy. *(Fixed in v1.19.3)* Form fields can never be copied.
       :arg int show_progress: *(new in version 1.17.7)* specify an interval size greater zero to see progress messages on ``sys.stdout``. After each interval, a message like ``Inserted 30 of 47 pages.`` will be printed.
       :arg int final: *(new in v1.18.0)* controls whether the list of already copied objects should be **dropped** after this method, default *True*. Set it to 0 except for the last one of multiple insertions from the same source PDF. This saves target file size and speeds up execution considerably.
 

docs/irect.rst

@@ -14,7 +14,7 @@ IRect is a rectangular bounding box, very similar to :ref:`Rect`, except that al
 :meth:`IRect.intersect`        common part with another rectangle
 :meth:`IRect.intersects`       checks for non-empty intersection
 :meth:`IRect.morph`            transform with a point and a matrix
-:meth:`IRect.torect`           the matrix that converts to another rectangle
+:meth:`IRect.torect`           matrix that transforms to another rectangle
 :meth:`IRect.norm`             the Euclidean norm
 :meth:`IRect.normalize`        makes a rectangle finite
 :attr:`IRect.bottom_left`      bottom left point, synonym *bl*
@@ -89,11 +89,11 @@ IRect is a rectangular bounding box, very similar to :ref:`Rect`, except that al
 
       *(New in version 1.19.3)*
 
-      Compute the matrix which transform this rectangle to a given one. See same-naed method of :ref:`Rect`.
+      Compute the matrix which transforms this rectangle to a given one. See :meth:`Rect.torect`.
 
       :arg rect_like rect: the target rectangle. Must not be empty or infinite.
       :rtype: :ref:`Matrix`
-      :returns: a matrix ``mat`` such ``self * mat = rect``. Can for example be used to switch between page coordinates and corresponding positions of its pixmap.
+      :returns: a matrix ``mat`` such that ``self * mat = rect``. Can for example be used to transform between the page and the pixmap coordinates.
 
 
    .. method:: morph(fixpoint, matrix)

docs/rect.rst

@@ -57,7 +57,7 @@ The following remarks are also valid for :ref:`IRect` objects:
 :meth:`Rect.intersect`        common part with another rectangle
 :meth:`Rect.intersects`       checks for non-empty intersections
 :meth:`Rect.morph`            transform with a point and a matrix
-:meth:`Rect.torect`           the matrix that converts to another rectangle
+:meth:`Rect.torect`           the matrix that transforms to another rectangle
 :meth:`Rect.norm`             the Euclidean norm
 :meth:`Rect.normalize`        makes a rectangle valid
 :meth:`Rect.round`            create smallest :ref:`Irect` containing rectangle
@@ -183,26 +183,28 @@ The following remarks are also valid for :ref:`IRect` objects:
 
       *(New in version 1.19.3)*
 
-      Compute the matrix which transform this rectangle to a given one.
+      Compute the matrix which transforms this rectangle to a given one.
 
       :arg rect_like rect: the target rectangle. Must not be empty or infinite.
       :rtype: :ref:`Matrix`
-      :returns: a matrix ``mat`` such ``self * mat = rect``. Can for example be used to switch between page coordinates and corresponding positions of its pixmap.
+      :returns: a matrix ``mat`` such that ``self * mat = rect``. Can for example be used to transform between the page and the pixmap coordinates.
 
-         .. note:: Suppose you want to check whether any of the words "pixmap" is located in an area with the same color as the text (e.g. white on white). We can find out whether the text's area mostly consists of pixels of identical color:
+         .. note:: Suppose you want to check whether any of the words "pixmap" is invisible, because the text color equals the ambient color -- e.g. white on white. We make a pixmap and check the "color environment" of each word:
 
+            >>> # make a pixmap of the page
             >>> pix = page.get_pixmap(dpi=150)
+            >>> # make a matrix that transforms to pixmap coordinates
             >>> mat = page.rect.torect(pix.irect)
-            >>> # "mat" converts page coordinates to pixmap coordinates
+            >>> # search for text locations
             >>> rlist = page.search_for("pixmap")
-            >>> # then the following makes rectangles on the page's pixmap,
-            >>> # wich each encircle one "pixmap" occurrence:
+            >>> # check color environment of each occurrence
+            >>> # we will check for "almost unicolor"
             >>> for r in rlist:
                     if pix.color_topusage(clip=r * mat) > 0.95:
-                        print("Word 'pixmap' is invisible!")
+                        print("'pixmap' invisible here:", r)
             >>> 
 
-         Method :meth:`Pixmap.color_topusage` computes the percentage of pixels showing the same color.
+            Method :meth:`Pixmap.color_topusage` computes the percentage of pixels showing the same color.
 
 
    .. method:: morph(fixpoint, matrix)

docs/version.rst

@@ -1,6 +1,6 @@
 Covered Version
 --------------------
 
-This documentation covers PyMuPDF v1.19.2 features as of **2021-11-20 00:00:01**.
+This documentation covers PyMuPDF v1.19.3 features as of **2021-12-12 06:51:56**.
 
 .. note:: The major and minor versions of **PyMuPDF** and **MuPDF** will always be the same. Only the third qualifier (patch level) may deviate from that of MuPDF.

fitz/fitz.i

@@ -8370,6 +8370,48 @@ struct Annot
             return Py_BuildValue("i", pdf_to_num(gctx, annot_obj));
         }
 
+        //----------------------------------------------------------------
+        // annotation get IRT xref number
+        //----------------------------------------------------------------
+        PARENTCHECK(irt_xref, """annotation IRT xref""")
+        %pythoncode %{@property%}
+        PyObject *irt_xref()
+        {
+            pdf_annot *annot = (pdf_annot *) $self;
+            pdf_obj *annot_obj = pdf_annot_obj(gctx, annot);
+            pdf_obj *irt = pdf_dict_get(gctx, annot_obj, PDF_NAME(IRT));
+            if (!irt) return PyLong_FromLong(0);
+            return PyLong_FromLong((long) pdf_to_num(gctx, irt));
+        }
+
+        //----------------------------------------------------------------
+        // annotation set IRT xref number
+        //----------------------------------------------------------------
+        FITZEXCEPTION(set_irt_xref, !result)
+        PARENTCHECK(set_irt_xref, """Set annotation IRT xref""")
+        PyObject *set_irt_xref(int xref)
+        {
+            fz_try(gctx) {
+                pdf_annot *annot = (pdf_annot *) $self;
+                pdf_obj *annot_obj = pdf_annot_obj(gctx, annot);
+                pdf_page *page = pdf_annot_page(gctx, annot);
+                if (!INRANGE(xref, 1, pdf_xref_len(gctx, page->doc) - 1))
+                    THROWMSG(gctx, "bad xref");
+                pdf_obj *irt = pdf_new_indirect(gctx, page->doc, xref, 0);
+                pdf_obj *subt = pdf_dict_get(gctx, irt, PDF_NAME(Subtype));
+                int irt_subt = pdf_annot_type_from_string(gctx, pdf_to_name(gctx, subt));
+                if (irt_subt < 0) {
+                    pdf_drop_obj(gctx, irt);
+                    THROWMSG(gctx, "xref not an annot");
+                }
+                pdf_dict_put_drop(gctx, annot_obj, PDF_NAME(IRT), irt);
+            }
+            fz_catch(gctx) {
+                return NULL;
+            }
+            Py_RETURN_NONE;
+        }
+
         //----------------------------------------------------------------
         // annotation get AP/N Matrix
         //----------------------------------------------------------------