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: