upgrade to v1.16.17

Author: JorjMcKie

PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 1.1
 Name: PyMuPDF
-Version: 1.16.16
+Version: 1.16.17
 Author: Ruikai Liu
 Author-email: [email protected]
 Maintainer: Jorj X. McKie
@@ -9,7 +9,7 @@ Home-page: https://github.com/pymupdf/PyMuPDF
 Download-url: https://github.com/pymupdf/PyMuPDF
 Summary: PyMuPDF is a Python binding for the PDF rendering library MuPDF
 Description:
-        Release date: March 29, 2020
+        Release date: March 31, 2020
 
         Authors
         =======
@@ -20,7 +20,7 @@ Description:
         Introduction
         ============
 
-        This is **version 1.16.16 of PyMuPDF**, a Python binding for `MuPDF <http://mupdf.com/>`_ - "a lightweight PDF and XPS viewer".
+        This is **version 1.16.18 of PyMuPDF**, a Python binding for `MuPDF <http://mupdf.com/>`_ - "a lightweight PDF and XPS viewer".
 
         MuPDF can access files in PDF, XPS, OpenXPS, epub, comic and fiction book formats, and it is known for both, its top performance and high rendering quality.
 

README.md

@@ -1,8 +1,8 @@
-# PyMuPDF 1.16.16
+# PyMuPDF 1.16.17
 
 ![logo](https://github.com/pymupdf/PyMuPDF/blob/master/demo/pymupdf.jpg)
 
-Release date: March 29, 2020
+Release date: March 31, 2020
 
 **Travis-CI:** [![Build Status](https://travis-ci.org/JorjMcKie/py-mupdf.svg?branch=master)](https://travis-ci.org/JorjMcKie/py-mupdf)
 
@@ -14,7 +14,7 @@ On **[PyPI](https://pypi.org/project/PyMuPDF)** since August 2016: [![](https://
 
 # Introduction
 
-This is **version 1.16.16 of PyMuPDF (formerly python-fitz)**, a Python binding with support for [MuPDF 1.16.*](http://mupdf.com/) - "a lightweight PDF, XPS, and E-book viewer".
+This is **version 1.16.17 of PyMuPDF (formerly python-fitz)**, a Python binding with support for [MuPDF 1.16.*](http://mupdf.com/) - "a lightweight PDF, XPS, and E-book viewer".
 
 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.
 

docs/changes.rst

@@ -1,6 +1,12 @@
 Change Logs
 ===============
 
+Changes in Version 1.16.17
+---------------------------
+
+* **Fixed** issue `#479 <https://github.com/pymupdf/PyMuPDF/issues/479>`_. PyMuPDF should now more correctly report image resolutions. This applies to both, images (either from images files or extracted from PDF documents) and pixmaps created from images.
+* **Added** :meth:`Pixmap.setResolution` which sets the image resolution in x and y directions.
+
 Changes in Version 1.16.16
 ---------------------------
 

docs/conf.py

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

docs/document.rst

@@ -170,6 +170,8 @@ For addional details on **embedded files** refer to Appendix 3.
       :rtype: :ref:`Page`
 
       :returns: a new copy of the same page. All pending updates (e.g. to annotations or widgets) will be finalized and a fresh copy of the page will be loaded.
+        .. note:: In a typical use case, a page :ref:`Pixmap` should be taken after annotations / widgets have been added or changed. To force all those changes being reflected in the page structure, this method re-instates a fresh copy while keeping the object hierarchy "document -> page -> annotation(s)" intact.
+
 
     .. method:: pages(start=None, [stop=None, [step=None]])
 

docs/functions.rst

@@ -547,11 +547,11 @@ Yet others are handy, general-purpose utilities.
       :rtype: int
       :returns: :data:`xref` number of the **/Outlines** root object.
 
-   .. method:: Document.extractImage(xref=0)
+   .. method:: Document.extractImage(xref)
 
       PDF Only: Extract data and meta information of an image stored in the document. The output can directly be used to be stored as an image file, as input for PIL, :ref:`Pixmap` creation, etc. This method avoids using pixmaps wherever possible to present the image in its original format (e.g. as JPEG).
 
-      :arg int xref: :data:`xref` of an image object. Must be in *range(1, doc._getXrefLength())*, else an exception is raised. If the object is no image or other errors occur, an empty dictionary is returned and no exception occurs.
+      :arg int xref: :data:`xref` of an image object. If this is not in *range(1, doc.xrefLength())*, or the object is no image or other errors occur, *None* is returned and no exception is raised.
 
       :rtype: dict
       :returns: a dictionary with the following keys
@@ -560,15 +560,12 @@ Yet others are handy, general-purpose utilities.
         * *smask* (*int*) :data:`xref` number of a stencil (/SMask) image or zero
         * *width* (*int*) image width
         * *height* (*int*) image height
-        * *colorspace* (*int*) the image's *pixmap.n* number (indicative only: depends on whether internal pixmaps had to be used). Zero for JPX images.
+        * *colorspace* (*int*) the image's *colorspace.n* number.
         * *cs-name* (*str*) the image's *colorspace.name*.
-        * *xres* (*int*) resolution in x direction. Zero for JPX images.
-        * *yres* (*int*) resolution in y direction. Zero for JPX images.
+        * *xres* (*int*) resolution in x direction. Please also see :data:`resolution`.
+        * *yres* (*int*) resolution in y direction. Please also see :data:`resolution`.
         * *image* (*bytes*) image data, usable as image file content
 
-      >>> d = doc.extractImage(25)
-      >>> d
-      {}
       >>> d = doc.extractImage(1373)
       >>> d
       {'ext': 'png', 'smask': 2934, 'width': 5, 'height': 629, 'colorspace': 3, 'xres': 96,
@@ -579,7 +576,7 @@ Yet others are handy, general-purpose utilities.
       102
       >>> imgout.close()
 
-      .. note:: There is a functional overlap with *pix = fitz.Pixmap(doc, xref)*, followed by a *pix.getPNGData()*. Main differences are that extractImage **(1)** does not only deliver PNG image formats, **(2)** is **very** much faster with non-PNG images, **(3)** usually results in much less disk storage for extracted images, **(4)** generates an empty *dict* for non-image xrefs (generates no exception). Look at the following example images within the same PDF.
+      .. note:: There is a functional overlap with *pix = fitz.Pixmap(doc, xref)*, followed by a *pix.getPNGData()*. Main differences are that extractImage, **(1)** does not only deliver PNG image formats, **(2)** is **very** much faster with non-PNG images, **(3)** usually results in much less disk storage for extracted images, **(4)** returns *None* in error cases (generates no exception). Look at the following example images within the same PDF.
 
          * xref 1268 is a PNG -- Comparable execution time and identical output::
 
@@ -593,7 +590,7 @@ Yet others are handy, general-purpose utilities.
             In [26]: len(img["image"])
             Out[26]: 21462
 
-         * xref 1186 is a JPEG -- :meth:`Document.extractImage` is **thousands of times faster** and produces a **much smaller** output (2.48 MB vs. 0.35 MB)::
+         * xref 1186 is a JPEG -- :meth:`Document.extractImage` is **many times faster** and produces a **much smaller** output (2.48 MB vs. 0.35 MB)::
 
             In [27]: %timeit pix = fitz.Pixmap(doc, 1186);pix.getPNGData()
             341 ms ± 2.86 ms per loop (mean ± std. dev. of 7 runs, 1 loop each)

docs/glossary.rst

@@ -113,3 +113,6 @@ Glossary
 
         Abbreviation for cross-reference number: this is an integer unique identification for objects in a PDF. There exists a cross-reference table (which may physically consist of several separate segments) in each PDF, which stores the relative position of each object for quick lookup. The cross-reference table is one entry longer than the number of existing object: item zero is reserved and must not be used in any way. Many PyMuPDF classes have an *xref* attribute (which is zero for non-PDFs), and one can find out the total number of objects in a PDF via :meth:`Document.xrefLength` *- 1*.
 
+.. data:: resolution
+
+        Images and :ref:`Pixmap` objects may contain resolution information provided as "dots per inch", dpi, in each direction (horizontal and vertical). When MuPDF reads an image form a file or from a PDF object, it will parse this information and put it in :attr:`Pixmap.xres`, :attr:`Pixmap.yres`, respectively. When it finds not meaningful information in the input (like non-positive values or values exceeding 4800), it will use "sane" defaults instead. The usual default value is 96, but it may also be 72 in some cases (e.g. 72 for JPX images).

docs/pixmap.rst

@@ -32,6 +32,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
 :meth:`Pixmap.pixel`          return the value of a pixel
 :meth:`Pixmap.setPixel`       set the color of a pixel
 :meth:`Pixmap.setRect`        set the color of a rectangle
+:meth:`Pixmap.setResolution`  set the image resolution
 :meth:`Pixmap.setAlpha`       set alpha values
 :meth:`Pixmap.shrink`         reduce size keeping proportions
 :meth:`Pixmap.tintWith`       tint a pixmap with a color
@@ -224,6 +225,16 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
          1. This method is equivalent to :meth:`Pixmap.setPixel` executed for each pixel in the rectangle, but is obviously **very much faster** if many pixels are involved.
          2. This method can be used similar to :meth:`Pixmap.clearWith` to initialize a pixmap with a certain color like this: *pix.setRect(pix.irect, (255, 255, 0))* (RGB example, colors the complete pixmap with yellow).
 
+   .. method:: setResolution(xres, yres)
+
+      *(New in v1.16.17)* Set the resolution (dpi) in x and y direction.
+
+      :arg int xres: resolution in x direction.
+      :arg int yres: resolution in y direction.
+
+      .. note:: This is just documentary information. In MuPDF, this will not have other implications and will not be written to images created from the pixmap.
+
+
    .. method:: setAlpha([alphavalues])
 
       Change the alpha values. The pixmap must have an alpha channel.
@@ -362,13 +373,13 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work".
 
    .. attribute:: xres
 
-      Horizontal resolution in dpi (dots per inch).
+      Horizontal resolution in dpi (dots per inch). Please also see :data:`resolution`.
 
       :type: int
 
    .. attribute:: yres
 
-      Vertical resolution in dpi.
+      Vertical resolution in dpi. Please also see :data:`resolution`.
 
       :type: int
 

docs/tools.rst

@@ -9,6 +9,7 @@ This class is a collection of utility methods and attributes, mainly around memo
 **Method / Attribute**             **Description**
 ================================== =================================================
 :meth:`Tools.gen_id`               generate a unique identifyer
+:meth:`Tools.image_profile`        report basic image properties
 :meth:`Tools.store_shrink`         shrink the storables cache [#f1]_
 :meth:`Tools.mupdf_warnings`       return the accumulated MuPDF warnings
 :meth:`Tools.mupdf_display_errors` return the accumulated MuPDF warnings
@@ -36,6 +37,45 @@ This class is a collection of utility methods and attributes, mainly around memo
       :rtype: int
       :returns: a unique positive integer.
 
+   .. method:: image_profile(stream)
+
+      *(New in v1.16.17)* Show important properties of an image provided as a memory area. Its main purpose is to avoid using other Python packages just to determine basic properties.
+
+      :arg bytes,bytearray stream: the image data.
+      :rtype: dict
+      :returns: a dictionary with the keys "width", "height", "xres", "yres", "colorspace" (the *colorspace.n* value, number of colorants), "cs-name" (the *colorspace.name* value), "bpc", "ext" (image type as file extension). The values for these keys are the same as returned by :meth:`Document.extractImage`. Please also have a look at :data:`resolution`.
+      
+      .. note::
+
+        * For some "exotic" images (FAX encodings, RAW formats and the like), this method will not work and return *None*. You can however still work with such images in PyMuPDF, e.g. by using :meth:`Document.extractImage` or create pixmaps via ``Pixmap(doc, xref)``. These methods will automatically convert exotic images to the PNG format before returning results.
+
+        * Some examples::
+
+               In [1]: import fitz
+               In [2]: stream = open(<image.file>, "rb").read()
+               In [3]: fitz.TOOLS.image_profile(stream)
+               Out[3]:
+               {'width': 439,
+               'height': 501,
+               'xres': 96,
+               'yres': 96,
+               'colorspace': 3,
+               'bpc': 8,
+               'ext': 'jpeg',
+               'cs-name': 'DeviceRGB'}
+               In [4]: doc=fitz.open(<input.pdf>)
+               In [5]: stream = doc.xrefStreamRaw(5)  # no decompression!
+               In [6]: fitz.TOOLS.image_profile(stream)
+               Out[6]:
+               {'width': 816,
+               'height': 1056,
+               'xres': 96,
+               'yres': 96,
+               'colorspace': 1,
+               'bpc': 8,
+               'ext': 'jpeg',
+               'cs-name': 'DeviceGray'}
+
    .. method:: store_shrink(percent)
 
       Reduce the storables cache by a percentage of its current size.

docs/version.rst

@@ -1,6 +1,6 @@
 Covered Version
 --------------------
 
-This documentation covers PyMuPDF v1.16.16 features as of **2020-03-29 09:44:30**.
+This documentation covers PyMuPDF v1.16.17 features as of **2020-03-31 08:53:33**.
 
 .. note:: The major and minor versions of **PyMuPDF** and **MuPDF** will always be the same. Only the third qualifier (patch level) may be different from that of MuPDF.