diff --git a/docs/installation.rst b/docs/installation.rst index afdf774ee..888c414e3 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -138,7 +138,7 @@ Notes * There are no **mandatory** external dependencies. However, some optional feature are available only if additional components are installed: - * `Pillow `_ is required for :meth:`Pixmap.pil_save` and :meth:`Pixmap.pil_tobytes`. + * `Pillow `_ is required for :meth:`Pixmap.pil`, :meth:`Pixmap.pil_save` and :meth:`Pixmap.pil_tobytes`. * `fontTools `_ is required for :meth:`Document.subset_fonts`. * `pymupdf-fonts `_ is a collection of nice fonts to be used for text output methods. * `Tesseract-OCR `_ for optical character recognition in images and document pages. Tesseract is separate software, not a Python package. To enable OCR functions in PyMuPDF, the software must be installed and the system environment variable `"TESSDATA_PREFIX"` must be defined and contain the `tessdata` folder name of the Tesseract installation location. See below. diff --git a/docs/pixmap.rst b/docs/pixmap.rst index 75251aeec..609338c79 100644 --- a/docs/pixmap.rst +++ b/docs/pixmap.rst @@ -33,6 +33,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work". :meth:`Pixmap.invert_irect` invert the pixels of a given area :meth:`Pixmap.pdfocr_save` save the pixmap as an OCRed 1-page PDF :meth:`Pixmap.pdfocr_tobytes` save the pixmap as an OCRed 1-page PDF +:meth:`Pixmap.pil` get as pillow image :meth:`Pixmap.pil_save` save as image using pillow :meth:`Pixmap.pil_tobytes` write to `bytes` object using pillow :meth:`Pixmap.pixel` return the value of a pixel @@ -388,7 +389,15 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work". doc.save("ocr-images.pdf") - .. method:: pil_save(*args, unmultiply=False, **kwargs) + .. method:: pil() + + * New in v1.17.3 + + Get the pixmap as Pillow image object. The returned image has the same colorspace as the pixmap. + + :raises ImportError: if Pillow is not installed. + + .. method:: pil_save(*args, **kwargs) * New in v1.17.3 @@ -400,8 +409,6 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work". A simple example: `pix.pil_save("some.webp", optimize=True, dpi=(150, 150))`. - :arg bool unmultiply: If the pixmap's colorspace is RGB with transparency, the alpha values may or may not already be multiplied into the color components ref/green/blue (called "premultiplied"). To enforce undoing premultiplication, set this parameter to `True`. To learn about some background, e.g. look for "Premultiplied alpha" `here `_. - For details on other parameters see the Pillow documentation. @@ -409,7 +416,7 @@ Have a look at the :ref:`FAQ` section to see some pixmap usage "at work". :raises ImportError: if Pillow is not installed. - .. method:: pil_tobytes(*args, unmultiply=False, **kwargs) + .. method:: pil_tobytes(*args, **kwargs) * New in v1.17.3 diff --git a/src/__init__.py b/src/__init__.py index 39350d1c8..421b158f2 100644 --- a/src/__init__.py +++ b/src/__init__.py @@ -10168,12 +10168,8 @@ def pdfocr_tobytes(self, compress=True, language="eng", tessdata=None): self.pdfocr_save(bio, compress=compress, language=language, tessdata=tessdata) return bio.getvalue() - def pil_save(self, *args, **kwargs): - """Write to image file using Pillow. - - Args are passed to Pillow's Image.save method, see their documentation. - Use instead of save when other output formats are desired. - """ + def pil(self): + """Get pixmap as a Pillow image.""" try: from PIL import Image except ImportError: @@ -10190,7 +10186,15 @@ def pil_save(self, *args, **kwargs): else: mode = "CMYK" - img = Image.frombytes(mode, (self.width, self.height), self.samples) + return Image.frombytes(mode, (self.width, self.height), self.samples) + + def pil_save(self, *args, **kwargs): + """Write to image file using Pillow. + + Args are passed to Pillow's Image.save method, see their documentation. + Use instead of save when other output formats are desired. + """ + img = self.pil() if "dpi" not in kwargs.keys(): kwargs["dpi"] = (self.xres, self.yres) diff --git a/tests/test_pixmap.py b/tests/test_pixmap.py index c456f05fc..7062e0fa2 100644 --- a/tests/test_pixmap.py +++ b/tests/test_pixmap.py @@ -10,7 +10,6 @@ import os import platform import sys -import tempfile import pytest import textwrap @@ -57,7 +56,31 @@ def test_filepixmap(): assert pix1.digest == pix2.digest -def test_pilsave(): +def test_pil(tmpdir): + # pixmaps from file then get pillow image + # make pixmap from this and confirm equality + try: + pix1 = pymupdf.Pixmap(imgfile) + pix1.pil().save(tmpdir / "foo.png") + pix2 = pymupdf.Pixmap(str(tmpdir / "foo.png")) + assert repr(pix1) == repr(pix2) + except ModuleNotFoundError: + assert platform.system() == 'Windows' and sys.maxsize == 2**31 - 1 + + +def test_pil_save(tmpdir): + # pixmaps from file then save pillow image to temporary file + # make pixmap from this and confirm equality + try: + pix1 = pymupdf.Pixmap(imgfile) + pix1.pil_save(tmpdir / "foo.png") + pix2 = pymupdf.Pixmap(str(tmpdir / "foo.png")) + assert repr(pix1) == repr(pix2) + except ModuleNotFoundError: + assert platform.system() == 'Windows' and sys.maxsize == 2**31 - 1 + + +def test_pil_tobytes(): # pixmaps from file then save to pillow image # make pixmap from this and confirm equality try: