Fix #3515 by preserving images quality by default

Author: Lucas-C

Makefile

@@ -26,4 +26,4 @@ mypy:
 	mypy pypdf --ignore-missing-imports --check-untyped --strict
 
 ruff:
-	ruff check pypdf tests make_release.py
+	ruff check --fix pypdf tests make_release.py

pypdf/_page.py

@@ -389,16 +389,18 @@ def replace(self, new_image: Image, **kwargs: Any) -> None:
         b = BytesIO()
         new_image.save(b, "PDF", **kwargs)
         reader = PdfReader(b)
-        assert reader.pages[0].images[0].indirect_reference is not None
+        page_image = reader.pages[0].images[0]
+        assert page_image.indirect_reference is not None
         self.indirect_reference.pdf._objects[self.indirect_reference.idnum - 1] = (
-            reader.pages[0].images[0].indirect_reference.get_object()
+            page_image.indirect_reference.get_object()
         )
         cast(
             PdfObject, self.indirect_reference.get_object()
         ).indirect_reference = self.indirect_reference
         # change the object attributes
         extension, byte_stream, img = _xobj_to_image(
-            cast(DictionaryObject, self.indirect_reference.get_object())
+            cast(DictionaryObject, self.indirect_reference.get_object()),
+            pillow_parameters=kwargs,
         )
         assert extension is not None
         self.name = self.name[: self.name.rfind(".")] + extension

pypdf/filters.py

@@ -791,15 +791,20 @@ def decode_stream_data(stream: Any) -> bytes:
     return data
 
 
-def _xobj_to_image(x_object: dict[str, Any]) -> tuple[Optional[str], bytes, Any]:
+def _xobj_to_image(
+        x_object: dict[str, Any],
+        pillow_parameters: Union[dict[str, Any], None] = None
+    ) -> tuple[Optional[str], bytes, Any]:
     """
     Users need to have the pillow package installed.
 
     It's unclear if pypdf will keep this function here, hence it's private.
     It might get removed at any point.
 
     Args:
-      x_object:
+        x_object:
+        pillow_parameters: parameters provided to Pillow Image.save() method,
+            cf. <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save>
 
     Returns:
         Tuple[file extension, bytes, PIL.Image.Image]
@@ -846,6 +851,9 @@ def _apply_alpha(
                 extension = ".png"
         return img, extension, image_format
 
+    if pillow_parameters is None:
+        pillow_parameters = {}
+
     # For error reporting
     obj_as_text = (
         x_object.indirect_reference.__repr__()
@@ -947,10 +955,14 @@ def _apply_alpha(
         img, x_object, obj_as_text, image_format, extension
     )
 
+    # Preserver JPEG image quality - cf. https://github.com/py-pdf/pypdf/issues/3515
+    if image_format == "JPEG" and "quality" not in pillow_parameters:
+        pillow_parameters["quality"] = "keep"
+
     # Save image to bytes
     img_byte_arr = BytesIO()
     try:
-        img.save(img_byte_arr, format=image_format)
+        img.save(img_byte_arr, format=image_format, **pillow_parameters)
     except OSError:  # pragma: no cover  # covered with pillow 10.3
         # in case of we convert to RGBA and then to PNG
         img1 = img.convert("RGBA")

pypdf/generic/_data_structures.py

@@ -1046,10 +1046,14 @@ def flate_encode(self, level: int = -1) -> "EncodedStreamObject":
         retval._data = FlateDecode.encode(self._data, level)
         return retval
 
-    def decode_as_image(self) -> Any:
+    def decode_as_image(self, pillow_parameters: Union[dict[str, Any], None] = None) -> Any:
         """
         Try to decode the stream object as an image
 
+        Args:
+            pillow_parameters: parameters provided to Pillow Image.save() method,
+                cf. <https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save>
+
         Returns:
             a PIL image if proper decoding has been found
         Raises:
@@ -1066,7 +1070,7 @@ def decode_as_image(self) -> Any:
             except AttributeError:
                 msg = f"{self.__repr__()} object does not seem to be an Image"  # pragma: no cover
             logger_warning(msg, __name__)
-        extension, _, img = _xobj_to_image(self)
+        extension, _, img = _xobj_to_image(self, pillow_parameters)
         if extension is None:
             return None  # pragma: no cover
         return img

tests/test_images.py

@@ -474,6 +474,17 @@ def test_extract_image_from_object(caplog):
     assert "does not seem to be an Image" in caplog.text
 
 
+def test_extract_image_with_explicit_quality():
+    url = "https://github.com/py-pdf/pypdf/files/15176076/B2.pdf"
+    name = "iss2613.pdf"
+    reader = PdfReader(BytesIO(get_data_from_url(url, name=name)))
+    image = reader.pages[0]["/Resources"]["/Pattern"]["/P1"]["/Resources"]["/XObject"][
+        "/X1"
+    ].decode_as_image({"quality": 25})
+    assert isinstance(image, Image.Image)
+    # Work-in-progress...
+
+
 @pytest.mark.enable_socket
 def test_4bits_images(caplog):
     url = "https://github.com/user-attachments/files/16624406/tt.pdf"