Improve the performance of PIL.pixelmatch (#181)

* Improve the performance of `PIL.pixelmatch`

This adds a PIL-specific fast path that detects identical images, then renders
the grayscale output with pure-PIL operations. This is most of the performance
gain.

This also slightly improves performance in the general case by:
* using a zeroed `bytearray`, instead of a transformed `output` (since the
initial value of `output` shouldn't actually matter)
* avoiding a call to `to_PIL_from_raw_data` (and associated pure-Python
loops), by using `Image.frombytes`

Benchmarks on 360x360 test images, with `output` requested:
- Identical images, `diff_mask=False`:
  33ms to 0.36ms (~90x faster)
- Identical images, `diff_mask=True`:
  33ms to 0.21ms (~150x faster, since no rendering occurs)
- Different images:
  170ms to 165ms

* Remove `PIL.from_PIL_to_raw_data`, `PIL.to_PIL_from_raw_data`

These functions are no longer needed internally (more
efficient bytes-based PIL operations are now used) and provide no
external value.

* tests: split PIL fixtures from core for identical-image cases

---------

Co-authored-by: Wu Haotian <whtsky@gmail.com>

Author: brianhelba

fixtures/1a_identical_alpha01.png

@@ -1,11 +1,12 @@
 """Functions to facilitate direct comparison of PIL.Image instances"""
 
-from typing import List, Optional, Tuple
+from typing import Optional
 
+import PIL.Image
 from PIL.Image import Image
 
 from pixelmatch import core
-from pixelmatch.types import ImageSequence, MutableImageSequence, RGBTuple
+from pixelmatch.types import RGBTuple
 
 
 def pixelmatch(
@@ -26,9 +27,9 @@ def pixelmatch(
     of raw image data.
 
     :param img1: PIL.Image data to compare with img2. Must be the same size as img2
-    :param img2: PIL.Image data to compare with img2. Must be the same size as img1
-    :param output: Image data to write the diff to. Should be the same size as
-    :param threshold: matching threshold (0 to 1); smaller is more sensitive, defaults to 1
+    :param img2: PIL.Image data to compare with img1. Must be the same size as img1
+    :param output: RGBA Image to write the diff to. Must be the same size as img1
+    :param threshold: matching threshold (0 to 1); smaller is more sensitive, defaults to 0.1
     :param includeAA: whether or not to skip anti-aliasing detection, ie if includeAA is True,
         detecting and ignoring anti-aliased pixels is disabled. Defaults to False
     :param alpha: opacity of original image in diff output, defaults to 0.1
@@ -42,20 +43,29 @@ def pixelmatch(
     :return: number of pixels that are different or 1 if fail_fast == true
     """
     width, height = img1.size
-    raw_img1 = from_PIL_to_raw_data(img1)
-    raw_img2 = from_PIL_to_raw_data(img2)
+    img1_rgba = img1.convert("RGBA")
+    img2_rgba = img2.convert("RGBA")
+    img1_bytes = img1_rgba.tobytes()
+    img2_bytes = img2_rgba.tobytes()
 
-    if output is not None:
-        raw_output: Optional[MutableImageSequence] = from_PIL_to_raw_data(output)
-    else:
-        raw_output = None
+    # Fast path: byte-identical images have no diff
+    if img1_bytes == img2_bytes:
+        if output is not None and not diff_mask:
+            _draw_grayscale(img1_rgba, alpha, output)
+        return 0
+
+    # core.pixelmatch doesn't read output_data, so initialize with zeros;
+    # img1 should be the same size as output (and will error in .frombytes otherwise)
+    output_data = bytearray(len(img1_bytes)) if output is not None else None
 
     diff_pixels = core.pixelmatch(
-        raw_img1,
-        raw_img2,
+        list(img1_bytes),
+        list(img2_bytes),
         width,
         height,
-        raw_output,
+        # bytearray is MutableSequence[int], not MutableSequence[int | float];
+        # safe because draw_pixel() only ever writes int values
+        output_data,  # type: ignore[arg-type]
         threshold=threshold,
         includeAA=includeAA,
         alpha=alpha,
@@ -65,29 +75,18 @@ def pixelmatch(
         fail_fast=fail_fast,
     )
 
-    if raw_output is not None and output is not None:
-        output.putdata(to_PIL_from_raw_data(raw_output))
+    if output_data is not None and output is not None:
+        output.frombytes(bytes(output_data), "raw", "RGBA")
 
     return diff_pixels
 
 
-def from_PIL_to_raw_data(pil_img: Image) -> MutableImageSequence:
-    """
-    Converts a PIL.Image object from [(R1, B1, A1, A1), (R2, ...), ...] to our raw data format
-    [R1, G1, B1, A1, R2, ...].
-
-    :param pil_img:
-    :return:
-    """
-    return list(pil_img.convert("RGBA").tobytes())
-
-
-def to_PIL_from_raw_data(
-    raw_data: ImageSequence,
-) -> List[Tuple[float, float, float, float]]:
-    """
-    Converts from the internal raw data format of [R1, G1, B1, A1, R2, ...] to PIL's raw data format, ie
-    [(R1, B1, A1, A1), (R2, ...), ...]
-    :return: raw image data in a PIL appropriate format
-    """
-    return [*zip(raw_data[::4], raw_data[1::4], raw_data[2::4], raw_data[3::4])]
+def _draw_grayscale(img_rgba: Image, alpha: float, output: Image) -> None:
+    """Draw a grayscale version of img_rgba blended with white into output."""
+    luminance = img_rgba.convert("L")
+    # Opaque pixels get weight `alpha`, transparent pixels get 0.
+    blend_weight = img_rgba.getchannel("A").point(lambda x: int(x * alpha))
+    white = PIL.Image.new("L", img_rgba.size, 255)
+    # Where mask is high, show luminance; where low, show white.
+    blended = PIL.Image.composite(image1=luminance, image2=white, mask=blend_weight)
+    output.paste(PIL.Image.merge("RGBA", (blended, blended, blended, white)))

fixtures/1a_identical_alpha05.png

@@ -51,6 +51,8 @@ def pil_to_flatten_data(img):
     ["6a", "6a", "6empty", {"threshold": 0}, 0],
     ["7a", "7b", "7diff", OPTIONS, 9856],
 ]
+pil_testdata = list(testdata)
+pil_testdata[8] = ["6a", "6a", "6empty_pil", {"threshold": 0}, 0]
 
 
 @pytest.mark.parametrize(
@@ -115,7 +117,7 @@ def test_pixelmatch_failfast(
 
 
 @pytest.mark.parametrize(
-    "img_path_1,img_path_2,diff_path,options,expected_mismatch", testdata
+    "img_path_1,img_path_2,diff_path,options,expected_mismatch", pil_testdata
 )
 def test_PIL_pixelmatch(
     img_path_1: str,
@@ -156,10 +158,10 @@ def test_PIL_pixelmatch_identical_images_diff_mask_output_stays_blank(benchmark)
 @pytest.mark.parametrize(
     "alpha,fixture",
     [
-        (0.0, "1a_identical_alpha00"),
-        (0.1, "1a_identical_alpha01"),
-        (0.5, "1a_identical_alpha05"),
-        (1.0, "1a_identical_alpha10"),
+        (0.0, "1a_identical_pil_alpha00"),
+        (0.1, "1a_identical_pil_alpha01"),
+        (0.5, "1a_identical_pil_alpha05"),
+        (1.0, "1a_identical_pil_alpha10"),
     ],
 )
 def test_PIL_pixelmatch_identical_images_output_matches_core(alpha, fixture, benchmark):