Chore: Drop ImageMagik as a dependency (#14440)

* Mark the thumbnail constants Final

* Comment each pdftoppm option

* Feature/Chore: Replaces all usages of ImageMagik's convert binary with a simple Pillow based helper

This removes ImageMagik as a dependency entirly and all documentation is cleaned up from it.
We no longer need to install it, have a policy for it to allow PDFs and no longer shell
out to it either.

* Fix: Save WebP images losslessly when removing the alpha channel

Pillow's default WebP save is lossy, so a WebP with an alpha channel came
back from remove_alpha_channel with slightly shifted pixel values before
it reached OCR. Save WebP lossless; other formats are unchanged.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

src/documents/converters.py

@@ -1,12 +1,11 @@
 from pathlib import Path
 
 import img2pdf
-from django.conf import settings
 from PIL import Image
 
 from documents.utils import copy_basic_file_stats
 from documents.utils import maybe_override_pixel_limit
-from documents.utils import run_subprocess
+from documents.utils import remove_alpha_channel
 
 
 def convert_from_tiff_to_pdf(tiff_path: Path, target_directory: Path) -> Path:
@@ -27,15 +26,7 @@ def convert_from_tiff_to_pdf(tiff_path: Path, target_directory: Path) -> Path:
         # Note the save into the temp folder, so as not to trigger a new
         # consume
         scratch_image = target_directory / tiff_path.name
-        run_subprocess(
-            [
-                settings.CONVERT_BINARY,
-                "-alpha",
-                "off",
-                tiff_path,
-                scratch_image,
-            ],
-        )
+        remove_alpha_channel(tiff_path, scratch_image)
     else:
         # Not modifying the original, safe to use in place
         scratch_image = tiff_path

src/documents/tests/test_utils.py

@@ -1,6 +1,11 @@
+from pathlib import Path
+
+import pytest
 import pytest_mock
+from PIL import Image
 
 from documents.utils import QuerySetStream
+from documents.utils import remove_alpha_channel
 
 
 class TestQuerySetStream:
@@ -33,3 +38,99 @@ class TestQuerySetStream:
         # the thing being verified here.
         mock_queryset.count.assert_called_with()
         mock_queryset.iterator.assert_called_once_with(chunk_size=1000)
+
+
+class TestRemoveAlphaChannel:
+    @pytest.mark.parametrize(
+        ("image_format", "mode", "expected_mode", "color", "expected_pixel"),
+        [
+            pytest.param(
+                "PNG",
+                "RGBA",
+                "RGB",
+                (10, 20, 30, 0),
+                (10, 20, 30),
+                id="png-rgba",
+            ),
+            pytest.param(
+                "TIFF",
+                "RGBA",
+                "RGB",
+                (10, 20, 30, 128),
+                (10, 20, 30),
+                id="tiff-rgba",
+            ),
+            pytest.param("PNG", "LA", "L", (40, 0), 40, id="png-la"),
+        ],
+    )
+    def test_drops_alpha_and_keeps_format(
+        self,
+        tmp_path: Path,
+        image_format: str,
+        mode: str,
+        expected_mode: str,
+        color: tuple[int, ...],
+        expected_pixel: int | tuple[int, ...],
+    ) -> None:
+        """
+        GIVEN:
+            - An image with an alpha channel
+        WHEN:
+            - The alpha channel is removed to a destination without an extension
+        THEN:
+            - The destination has the matching opaque mode, the same size and
+              format, and the color values are kept rather than composited
+        """
+        source = tmp_path / "source"
+        Image.new(mode, (8, 6), color).save(source, format=image_format)
+        dest = tmp_path / "no-alpha"
+
+        result = remove_alpha_channel(source, dest)
+
+        assert result == dest
+        with Image.open(dest) as out:
+            assert out.mode == expected_mode
+            assert out.size == (8, 6)
+            assert out.format == image_format
+            assert out.getpixel((0, 0)) == expected_pixel
+
+    def test_keeps_every_frame_of_a_multi_page_tiff(self, tmp_path: Path) -> None:
+        """
+        GIVEN:
+            - A multi-page TIFF where every page has an alpha channel
+        WHEN:
+            - The alpha channel is removed
+        THEN:
+            - All pages are kept and none has an alpha channel
+        """
+        source = tmp_path / "multi.tiff"
+        first = Image.new("RGBA", (8, 6), (255, 0, 0, 50))
+        rest = [Image.new("RGBA", (8, 6), (0, 255, 0, 50)) for _ in range(2)]
+        first.save(source, save_all=True, append_images=rest)
+        dest = tmp_path / "multi-no-alpha.tiff"
+
+        remove_alpha_channel(source, dest)
+
+        with Image.open(dest) as out:
+            assert out.n_frames == 3
+            for index in range(out.n_frames):
+                out.seek(index)
+                assert out.mode == "RGB"
+
+    def test_keeps_dpi(self, tmp_path: Path) -> None:
+        """
+        GIVEN:
+            - An alpha image with a DPI set
+        WHEN:
+            - The alpha channel is removed
+        THEN:
+            - The DPI is unchanged, since OCR scaling depends on it
+        """
+        source = tmp_path / "source.png"
+        Image.new("RGBA", (8, 6)).save(source, dpi=(300, 300))
+        dest = tmp_path / "dest.png"
+
+        remove_alpha_channel(source, dest)
+
+        with Image.open(dest) as out:
+            assert round(out.info["dpi"][0]) == 300

src/documents/utils.py

@@ -9,11 +9,13 @@ from pathlib import Path
 from subprocess import CompletedProcess
 from subprocess import run
 from typing import TYPE_CHECKING
+from typing import Any
 from typing import Generic
 from typing import TypeVar
 
 from django.conf import settings
 from PIL import Image
+from PIL import ImageSequence
 
 if TYPE_CHECKING:
     from django.db.models import Model
@@ -128,6 +130,32 @@ def maybe_override_pixel_limit() -> None:
         Image.MAX_IMAGE_PIXELS = pixel_count
 
 
+def remove_alpha_channel(source: Path, dest: Path) -> Path:
+    """
+    Writes a copy of the image with its alpha channel dropped, keeping the
+    format, every frame, the DPI and any ICC profile.
+
+    The channel is dropped, not composited, so transparent pixels keep their
+    underlying color. Returns dest.
+    """
+    with Image.open(source) as im:
+        image_format = im.format
+        opaque_mode = "L" if im.mode == "LA" else "RGB"
+        frames = [frame.convert(opaque_mode) for frame in ImageSequence.Iterator(im)]
+        save_kwargs: dict[str, Any] = {}
+        if "dpi" in im.info:
+            save_kwargs["dpi"] = im.info["dpi"]
+        if "icc_profile" in im.info:
+            save_kwargs["icc_profile"] = im.info["icc_profile"]
+        if image_format == "WEBP":
+            save_kwargs["lossless"] = True
+        if len(frames) > 1:
+            save_kwargs["save_all"] = True
+            save_kwargs["append_images"] = frames[1:]
+    frames[0].save(dest, format=image_format, **save_kwargs)
+    return dest
+
+
 def run_subprocess(
     arguments: list[str],
     env: dict[str, str] | None = None,

src/paperless/checks.py

@@ -82,7 +82,7 @@ def binaries_check(app_configs: Any, **kwargs: Any) -> list[Error]:
     error = "Paperless can't find {}. Without it, consumption is impossible."
     hint = "Either it's not in your ${PATH} or it's not installed."
 
-    binaries = (settings.CONVERT_BINARY, "tesseract", "gs", "pdftoppm", "pdfinfo")
+    binaries = ("tesseract", "gs", "pdftoppm", "pdfinfo")
 
     check_messages = []
     for binary in binaries:

src/paperless/parsers/tesseract.py

@@ -19,7 +19,7 @@ from documents.parsers import ParseError
 from documents.parsers import make_thumbnail_from_pdf
 from documents.utils import copy_file_with_basic_stats
 from documents.utils import maybe_override_pixel_limit
-from documents.utils import run_subprocess
+from documents.utils import remove_alpha_channel
 from paperless.config import OcrConfig
 from paperless.models import CleanChoices
 from paperless.models import ModeChoices
@@ -197,18 +197,7 @@ class RasterisedDocumentParser:
             return im.mode in ("RGBA", "LA")
 
     def remove_alpha(self, image_path: Path) -> Path:
-        no_alpha_image = Path(self.tempdir) / "image-no-alpha"
-        run_subprocess(
-            [
-                settings.CONVERT_BINARY,
-                "-alpha",
-                "off",
-                str(image_path),
-                str(no_alpha_image),
-            ],
-            logger=self.log,
-        )
-        return no_alpha_image
+        return remove_alpha_channel(image_path, Path(self.tempdir) / "image-no-alpha")
 
     def get_dpi(self, image: Path) -> int | None:
         try:

src/paperless/settings/__init__.py

@@ -976,9 +976,6 @@ MAX_IMAGE_PIXELS: Final[int | None] = get_int_from_env(
 # GNUPG needs a home directory for some reason
 GNUPG_HOME = os.getenv("HOME", "/tmp")
 
-# Convert is part of the ImageMagick package
-CONVERT_BINARY = os.getenv("PAPERLESS_CONVERT_BINARY", "convert")
-
 # Fallback layout for .eml consumption
 EMAIL_PARSE_DEFAULT_LAYOUT = get_int_from_env(
     "PAPERLESS_EMAIL_PARSE_DEFAULT_LAYOUT",

src/paperless/tests/test_checks.py

@@ -26,9 +26,17 @@ class TestChecks:
     def test_binaries(self) -> None:
         assert binaries_check(None) == []
 
-    def test_binaries_fail(self, settings: Settings) -> None:
-        settings.CONVERT_BINARY = "uuuhh"
-        assert len(binaries_check(None)) == 1
+    def test_binaries_fail(self, mocker: MockerFixture) -> None:
+        """
+        GIVEN:
+            - None of tesseract, ghostscript, pdftoppm or pdfinfo can be found
+        WHEN:
+            - The binaries check runs
+        THEN:
+            - One warning is raised per missing binary
+        """
+        mocker.patch("paperless.checks.shutil.which", return_value=None)
+        assert len(binaries_check(None)) == 4
 
     @pytest.mark.parametrize("binary", ["pdftoppm", "pdfinfo"])
     def test_binaries_fail_poppler(self, mocker: MockerFixture, binary: str) -> None: