updates 0 for v1.19.3

Author: JorjMcKie

README.md

@@ -1,16 +1,17 @@
-# PyMuPDF 1.19.2
+# PyMuPDF 1.19.3
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: November 20, 2021
+Release date: December 15, 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)
 
-On **[PyPI](https://pypi.org/project/PyMuPDF)** since August 2016: [![](https://pepy.tech/badge/pymupdf)](https://pepy.tech/project/pymupdf)
 # Author
 [Jorj X. McKie](mailto:[email protected]), based on original code by [Ruikai Liu](mailto:[email protected]).
 
 # Introduction
 
-PyMuPDF (current version 1.19.2) is a Python binding with support for [MuPDF](https://mupdf.com/) (current version 1.19.*), a lightweight PDF, XPS, and E-book viewer, renderer, and toolkit, which is maintained and developed by Artifex Software, Inc.
+PyMuPDF (current version 1.19.3) is a Python binding with support for [MuPDF](https://mupdf.com/) (current version 1.19.*), a lightweight PDF, XPS, and E-book viewer, renderer, and toolkit, which is maintained and developed by Artifex Software, Inc.
 
 MuPDF can access files in PDF, XPS, OpenXPS, CBZ, EPUB and FB2 (e-books) formats, and it is known for its top performance and high rendering quality.
 
@@ -59,7 +60,11 @@ 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).
@@ -76,7 +81,7 @@ python -m pip install --upgrade pip
 python -m pip install --upgrade pymupdf
 ```
 
-There are **no mandatory** external dependencies. However, some **optional features** become available only if additional packages are installed:
+There are **no mandatory** external dependencies. However, some **optional features** become available 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

changes.rst

@@ -3,6 +3,23 @@ Change Log
 
 ------
 
+**Changes in Version 1.19.3**
+
+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** :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)``.
+
+------
+
 **Changes in Version 1.19.2**
 
 This patch version implements minor improvements for :meth:`Page.get_drawings` and also some important fixes.

docs/changes.rst

@@ -3,6 +3,23 @@ Change Log
 
 ------
 
+**Changes in Version 1.19.3**
+
+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** :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)``.
+
+------
+
 **Changes in Version 1.19.2**
 
 This patch version implements minor improvements for :meth:`Page.get_drawings` and also some important fixes.

docs/conf.py

@@ -43,7 +43,7 @@
 # built documents.
 #
 # The full version, including alpha/beta/rc tags.
-release = "1.19.2"
+release = "1.19.3"
 
 # The short X.Y version
 version = release

docs/document.rst

@@ -49,6 +49,7 @@ For details on **embedded files** refer to Appendix 3.
 :meth:`Document.find_bookmark`          retrieve page location after layouting document
 :meth:`Document.fullcopy_page`          PDF only: duplicate a page
 :meth:`Document.get_layer`              PDF only: lists of OCGs in ON, OFF, RBGroups
+:meth:`Document.get_layers`             PDF only: list of optional content configurations
 :meth:`Document.get_oc`                 PDF only: get OCG /OCMD xref of image / form xobject
 :meth:`Document.get_ocgs`               PDF only: info on all optional content groups
 :meth:`Document.get_ocmd`               PDF only: retrieve definition of an :data:`OCMD`
@@ -76,7 +77,6 @@ For details on **embedded files** refer to Appendix 3.
 :meth:`Document.journal_redo`           PDF only: redo current operation
 :meth:`Document.journal_save`           PDF only: save joural to a file
 :meth:`Document.journal_load`           PDF only: load joural from a file
-:meth:`Document.layer_configs`          PDF only: list of optional content configurations
 :meth:`Document.layer_ui_configs`       PDF only: list of optional content intents
 :meth:`Document.layout`                 re-paginate the document (if supported)
 :meth:`Document.load_page`              read a page
@@ -226,13 +226,13 @@ For details on **embedded files** refer to Appendix 3.
       :arg int ocxref: the :data:`xref` number of an :data:`OCG` / :data:`OCMD`. If not zero, an invalid reference raises an exception. If zero, any OC reference is removed.
 
 
-    .. method:: layer_configs()
+    .. method:: get_layers()
 
       *(New in v1.18.3)*
 
       Show optional layer configurations. There always is a standard one, which is not included in the response.
 
-        >>> for item in doc.layer_configs: print(item)
+        >>> for item in doc.get_layers(): print(item)
         {'number': 0, 'name': 'my-config', 'creator': ''}
         >>> # use 'number' as config identifyer in add_ocg
 

docs/faq.rst

@@ -706,97 +706,12 @@ The text sequence extracted from a page modified in this way will look like this
 2. header line
 3. footer line
 
-PyMuPDF has several means to re-establish some reading sequence or even to re-generate a layout close to the original.
+PyMuPDF has several means to re-establish some reading sequence or even to re-generate a layout close to the original:
 
-As a starting point take the above mentioned `script <https://github.com/pymupdf/PyMuPDF/wiki/How-to-extract-text-from-a-rectangle>`_ and then use the full page rectangle.
-
-On rare occasions, when the PDF creator has been "over-creative", extracted text does not even keep the correct reading sequence of **single letters**: instead of the two words "DELUXE PROPERTY" you might sometimes get an anagram, consisting of 8 words like "DEL", "XE" , "P", "OP", "RTY", "U", "R" and "E".
-
-Such a PDF is also not searchable by all PDF viewers, but it is displayed correctly and looks harmless.
-
-In those cases, the following function will help composing the original words of the page. The resulting list is also searchable and can be used to deliver rectangles for the found text locations::
-
-    from operator import itemgetter
-    from itertools import groupby
-    import fitz
-
-    def recover(words, rect):
-        """ Word recovery.
-
-        Notes:
-            Method 'get_textWords()' does not try to recover words, if their single
-            letters do not appear in correct lexical order. This function steps in
-            here and creates a new list of recovered words.
-        Args:
-            words: list of words as created by 'get_textWords()'
-            rect: rectangle to consider (usually the full page)
-        Returns:
-            List of recovered words. Same format as 'get_text_words', but left out
-            block, line and word number - a list of items of the following format:
-            [x0, y0, x1, y1, "word"]
-        """
-        # build my sublist of words contained in given rectangle
-        mywords = [w for w in words if fitz.Rect(w[:4]) in rect]
-
-        # sort the words by lower line, then by word start coordinate
-        mywords.sort(key=itemgetter(3, 0))  # sort by y1, x0 of word rectangle
-
-        # build word groups on same line
-        grouped_lines = groupby(mywords, key=itemgetter(3))
-
-        words_out = []  # we will return this
-
-        # iterate through the grouped lines
-        # for each line coordinate ("_"), the list of words is given
-        for _, words_in_line in grouped_lines:
-            for i, w in enumerate(words_in_line):
-                if i == 0:  # store first word
-                    x0, y0, x1, y1, word = w[:5]
-                    continue
-
-                r = fitz.Rect(w[:4])  # word rect
-
-                # Compute word distance threshold as 20% of width of 1 letter.
-                # So we should be safe joining text pieces into one word if they
-                # have a distance shorter than that.
-                threshold = r.width / len(w[4]) / 5
-                if r.x0 <= x1 + threshold:  # join with previous word
-                    word += w[4]  # add string
-                    x1 = r.x1  # new end-of-word coordinate
-                    y0 = max(y0, r.y0)  # extend word rect upper bound
-                    continue
-
-                # now have a new word, output previous one
-                words_out.append([x0, y0, x1, y1, word])
-
-                # store the new word
-                x0, y0, x1, y1, word = w[:5]
-
-            # output word waiting for completion
-            words_out.append([x0, y0, x1, y1, word])
-
-        return words_out
-
-    def search_for(text, words):
-        """ Search for text in items of list of words
-
-        Notes:
-            Can be adjusted / extended in obvious ways, e.g. using regular
-            expressions, or being case insensitive, or only looking for complete
-            words, etc.
-        Args:
-            text: string to be searched for
-            words: list of items in format delivered by 'get_text_words()'.
-        Returns:
-            List of rectangles, one for each found locations.
-        """
-        rect_list = []
-        for w in words:
-            if text in w[4]:
-                rect_list.append(fitz.Rect(w[:4]))
-
-        return rect_list
+1. Use ``sort`` parameter of :meth:`Page.get_text`. It will sort the output from top-left to bottom-right (ignored for XHTML, HTML and XML output).
+2. Use the ``fitz`` module in CLI: ``python -m fitz gettext ...``, which produces a text file where text has been re-arranged in layout-preserving mode. Many options are available to control the output.
 
+You can also use the above mentioned `script <https://github.com/pymupdf/PyMuPDF/wiki/How-to-extract-text-from-a-rectangle>`_ with your modifications.
 
 ----------