feat(preprod): Add image comparison library with odiff batch support (#109381)

## Summary
- Add `compare_images` and `compare_images_batch` functions using
dual-threshold detection (base + color-sensitive)
- Produces base64-encoded diff mask PNGs with pixel-level change data
- Unit tests covering identical, different, different-size, threshold
sensitivity, bytes input, and batch modes

**Stack**: 2/3 — depends on #109380, next: Celery task

---------

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

Author: NicoHinderling

.github/workflows/backend.yml

@@ -269,6 +269,13 @@ jobs:
         with:
           mode: backend-ci
 
+      - name: Download odiff binary
+        run: |
+          curl -sL https://registry.npmjs.org/odiff-bin/-/odiff-bin-4.3.2.tgz \
+            | tar -xz --strip-components=2 package/raw_binaries/odiff-linux-x64
+          sudo install -m 755 odiff-linux-x64 /usr/local/bin/odiff
+          rm odiff-linux-x64
+
       - name: Download selected tests artifact
         if: needs.prepare-selective-tests.outputs.has-selected-tests == 'true'
         uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0

src/sentry/preprod/snapshots/image_diff/compare.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import base64
+import io
+import logging
+import tempfile
+from collections.abc import Sequence
+from pathlib import Path
+
+from PIL import Image
+
+from .odiff import OdiffServer
+from .types import DiffResult
+
+logger = logging.getLogger(__name__)
+
+DIFF_THRESHOLD = 0
+
+
+def _as_image(source: bytes | Image.Image) -> Image.Image:
+    if isinstance(source, bytes):
+        img = Image.open(io.BytesIO(source))
+        try:
+            img.load()
+        except Exception:
+            img.close()
+            raise
+        return img
+    return source
+
+
+def _mask_from_diff_output(output_path: Path) -> Image.Image:
+    with Image.open(output_path) as img:
+        rgba = img.convert("RGBA")
+    bands: tuple[Image.Image, ...] = ()
+    try:
+        bands = rgba.split()
+        alpha = bands[3]
+        mask = alpha.point(lambda px: 255 if px > 0 else 0)
+        return mask
+    finally:
+        for band in bands:
+            band.close()
+        rgba.close()
+
+
+def _encode_mask_png_base64(mask: Image.Image) -> str:
+    buf = io.BytesIO()
+    mask.save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode("ascii")
+
+
+def compare_images(
+    before: bytes | Image.Image,
+    after: bytes | Image.Image,
+) -> DiffResult | None:
+    return compare_images_batch([(before, after)])[0]
+
+
+def compare_images_batch(
+    pairs: Sequence[tuple[bytes | Image.Image, bytes | Image.Image]],
+    server: OdiffServer | None = None,
+) -> list[DiffResult | None]:
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir_path = Path(tmpdir)
+        if server is not None:
+            return _compare_pairs(pairs, server, tmpdir_path)
+        with OdiffServer() as new_server:
+            return _compare_pairs(pairs, new_server, tmpdir_path)
+
+
+def _compare_pairs(
+    pairs: Sequence[tuple[bytes | Image.Image, bytes | Image.Image]],
+    server: OdiffServer,
+    tmpdir_path: Path,
+) -> list[DiffResult | None]:
+    return [
+        _compare_single_pair(idx, before, after, server, tmpdir_path)
+        for idx, (before, after) in enumerate(pairs)
+    ]
+
+
+def _compare_single_pair(
+    idx: int,
+    before: bytes | Image.Image,
+    after: bytes | Image.Image,
+    server: OdiffServer,
+    tmpdir_path: Path,
+) -> DiffResult | None:
+    before_img: Image.Image | None = None
+    after_img: Image.Image | None = None
+    diff_mask: Image.Image | None = None
+    try:
+        before_img = _as_image(before)
+        after_img = _as_image(after)
+        bw, bh = before_img.size
+        aw, ah = after_img.size
+        max_w = max(bw, aw)
+        max_h = max(bh, ah)
+
+        before_path = tmpdir_path / f"before_{idx}.png"
+        after_path = tmpdir_path / f"after_{idx}.png"
+        before_img.save(before_path, "PNG")
+        after_img.save(after_path, "PNG")
+
+        output_path = tmpdir_path / f"diff_{idx}.png"
+        resp = server.compare(
+            before_path,
+            after_path,
+            output_path,
+            threshold=DIFF_THRESHOLD,
+            antialiasing=True,
+            outputDiffMask=True,
+            failOnLayoutDiff=False,
+        )
+        changed_pixels = resp.diffCount or 0
+        diff_pct = resp.diffPercentage or 0.0
+
+        total_pixels = max_w * max_h
+        diff_score = diff_pct / 100.0
+
+        if changed_pixels == 0:
+            diff_mask = Image.new("L", (max_w, max_h), 0)
+        elif not output_path.exists():
+            raise RuntimeError(f"odiff did not produce output file: {output_path}")
+        else:
+            diff_mask = _mask_from_diff_output(output_path)
+            if diff_mask.size != (max_w, max_h):
+                old_mask = diff_mask
+                diff_mask = diff_mask.resize((max_w, max_h), Image.NEAREST)
+                old_mask.close()
+
+        diff_mask_png = _encode_mask_png_base64(diff_mask)
+
+        return DiffResult(
+            diff_mask_png=diff_mask_png,
+            diff_score=diff_score,
+            changed_pixels=changed_pixels,
+            total_pixels=total_pixels,
+            aligned_height=max_h,
+            width=max_w,
+            before_width=bw,
+            before_height=bh,
+            after_width=aw,
+            after_height=ah,
+        )
+    except Exception:
+        logger.exception("Failed to compare image pair %d", idx)
+        return None
+    finally:
+        if before_img is not None and isinstance(before, bytes):
+            before_img.close()
+        if after_img is not None and isinstance(after, bytes):
+            after_img.close()
+        if diff_mask is not None:
+            diff_mask.close()

src/sentry/preprod/snapshots/image_diff/odiff.py

@@ -154,6 +154,11 @@ def close(self) -> None:
                 proc.stdin.close()
             except OSError:
                 pass
+        if proc.stdout:
+            try:
+                proc.stdout.close()
+            except OSError:
+                pass
         try:
             proc.wait(timeout=3)
             return

src/sentry/preprod/snapshots/image_diff/types.py

@@ -22,8 +22,8 @@ class OdiffResponse(BaseModel):
     model_config = ConfigDict(frozen=True)
 
     requestId: int
-    exitCode: int
-    result: str
+    match: bool = False
+    reason: str | None = None
     diffCount: int | None = None
     diffPercentage: float | None = None
     error: str | None = None

tests/sentry/preprod/snapshots/image_diff/test_image_diff.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import io
+
+from PIL import Image, ImageDraw
+
+from sentry.preprod.snapshots.image_diff.compare import compare_images, compare_images_batch
+
+
+def _make_solid_image(width: int, height: int, color: tuple[int, int, int, int]) -> Image.Image:
+    return Image.new("RGBA", (width, height), color)
+
+
+class TestCompareImages:
+    def test_identical_images(self):
+        img = _make_solid_image(100, 100, (128, 128, 128, 255))
+        result = compare_images(img, img.copy())
+        assert result is not None
+        assert result.diff_score == 0.0
+        assert result.changed_pixels == 0
+        assert result.total_pixels == 100 * 100
+
+    def test_different_sizes(self):
+        small = _make_solid_image(30, 30, (100, 100, 100, 255))
+        large = _make_solid_image(50, 50, (100, 100, 100, 255))
+        result = compare_images(small, large)
+        assert result is not None
+        assert result.width == 50
+        assert result.aligned_height == 50
+        assert result.before_width == 30
+        assert result.before_height == 30
+        assert result.after_width == 50
+        assert result.after_height == 50
+
+    def test_modified_block(self):
+        before = _make_solid_image(100, 100, (100, 100, 100, 255))
+        after = _make_solid_image(100, 100, (100, 100, 100, 255))
+        draw = ImageDraw.Draw(after)
+        draw.rectangle((10, 10, 29, 29), fill=(255, 0, 0, 255))
+        result = compare_images(before, after)
+        assert result is not None
+        assert result.changed_pixels > 0
+
+    def test_bytes_input(self):
+        img = _make_solid_image(30, 30, (128, 128, 128, 255))
+        buf = io.BytesIO()
+        img.save(buf, format="PNG")
+        img_bytes = buf.getvalue()
+
+        result = compare_images(img_bytes, img_bytes)
+        assert result is not None
+        assert result.diff_score == 0.0
+
+
+class TestCompareImagesBatch:
+    def test_batch_returns_correct_count(self):
+        img1 = _make_solid_image(50, 50, (100, 100, 100, 255))
+        img2 = _make_solid_image(50, 50, (200, 200, 200, 255))
+
+        results = compare_images_batch(
+            [
+                (img1, img1.copy()),
+                (img1, img2),
+            ]
+        )
+
+        assert len(results) == 2
+        assert results[0] is not None
+        assert results[1] is not None
+        assert results[0].diff_score == 0.0
+        assert results[1].diff_score > 0.0
+
+    def test_batch_single_pair_matches_single(self):
+        before = _make_solid_image(50, 50, (100, 100, 100, 255))
+        after = _make_solid_image(50, 50, (200, 200, 200, 255))
+
+        single = compare_images(before, after)
+        batch = compare_images_batch([(before, after)])[0]
+
+        assert single is not None
+        assert batch is not None
+        assert single.diff_score == batch.diff_score
+        assert single.changed_pixels == batch.changed_pixels