fix: sample contrast over text pixels

Author: sjquant

quickthumb/_diagnostic_rules.py

@@ -256,43 +256,68 @@ def _alpha_region(
         return mask.point(lambda value: 255 if value else 0)
 
 
-def average_visible_background(image: Image.Image, region: BBox) -> tuple[float, float, float]:
+def average_visible_background(
+    image: Image.Image, region: BBox, mask: Image.Image | None = None
+) -> tuple[float, float, float]:
     crop = image.crop((region.x, region.y, region.right, region.bottom))
-    mean_r, mean_g, mean_b, mean_a = ImageStat.Stat(crop).mean
+    mask_crop = (
+        None if mask is None else mask.crop((region.x, region.y, region.right, region.bottom))
+    )
+    mean_r, mean_g, mean_b, mean_a = ImageStat.Stat(crop, mask=mask_crop).mean
 
     # Transparent areas read as white, matching JPEG export and typical viewers.
     alpha = mean_a / 255
     return tuple(channel * alpha + 255 * (1 - alpha) for channel in (mean_r, mean_g, mean_b))
 
 
 def worst_tile_contrast(
-    image: Image.Image,
+    background_image: Image.Image,
+    foreground_image: Image.Image,
     region: BBox,
-    foregrounds: Iterable[tuple[float, float, float]],
     *,
     tile_size: int,
 ) -> TiledContrastMeasurement | None:
-    """Measure the lowest foreground/background contrast across tiled samples."""
-    tiles = list(_tiled_regions(region, tile_size))
-    if not tiles:
-        return None
+    """Measure the lowest text-pixel contrast across tiled samples."""
+    foreground_alpha = foreground_image.getchannel("A").point(lambda value: 255 if value else 0)
+    tile_count = _tile_count(region, tile_size)
 
     worst: TiledContrastMeasurement | None = None
-    for tile in tiles:
-        background = average_visible_background(image, tile)
-        for foreground in foregrounds:
-            contrast = contrast_ratio(foreground, background)
-            if worst is None or contrast < worst.contrast:
-                worst = TiledContrastMeasurement(
-                    contrast=contrast,
-                    foreground=foreground,
-                    background=background,
-                    tile=tile,
-                    tile_count=len(tiles),
-                )
+    for tile in _tiled_regions(region, tile_size):
+        alpha_tile = foreground_alpha.crop((tile.x, tile.y, tile.right, tile.bottom))
+        if alpha_tile.getbbox() is None:
+            continue
+
+        background = average_visible_background(background_image, tile, mask=foreground_alpha)
+        foreground = _average_visible_foreground(foreground_image, tile, foreground_alpha)
+        contrast = contrast_ratio(foreground, background)
+        if worst is None or contrast < worst.contrast:
+            worst = TiledContrastMeasurement(
+                contrast=contrast,
+                foreground=foreground,
+                background=background,
+                tile=tile,
+                tile_count=tile_count,
+            )
     return worst
 
 
+def _average_visible_foreground(
+    image: Image.Image, region: BBox, mask: Image.Image
+) -> tuple[float, float, float]:
+    crop = image.crop((region.x, region.y, region.right, region.bottom))
+    mask_crop = mask.crop((region.x, region.y, region.right, region.bottom))
+    mean_r, mean_g, mean_b, *_ = ImageStat.Stat(crop, mask=mask_crop).mean
+    return mean_r, mean_g, mean_b
+
+
+def _tile_count(region: BBox, tile_size: int) -> int:
+    if tile_size <= 0:
+        raise ValueError("tile_size must be positive")
+    cols = (region.width + tile_size - 1) // tile_size
+    rows = (region.height + tile_size - 1) // tile_size
+    return cols * rows
+
+
 def _tiled_regions(region: BBox, tile_size: int) -> Iterable[BBox]:
     if tile_size <= 0:
         raise ValueError("tile_size must be positive")

quickthumb/_diagnostics.py

@@ -3,12 +3,7 @@
 
 from PIL import Image
 
-from quickthumb._base import (
-    DEFAULT_TEXT_COLOR,
-    DEFAULT_TEXT_SIZE,
-    RenderContext,
-    parse_coordinate,
-)
+from quickthumb._base import DEFAULT_TEXT_SIZE, RenderContext, parse_coordinate
 from quickthumb._diagnostic_rules import (
     LayerAlphaCache,
     OverlapMeasurement,
@@ -419,34 +414,32 @@ def _first_word_wider_than(
     def _text_background_contrast(
         self, running: Image.Image, measured: LayerMeasurement
     ) -> TiledContrastMeasurement | None:
-        """Worst contrast ratio between the layer's text colors and the area below it."""
+        """Worst contrast ratio between the layer's visible text pixels and the area below."""
         layer = measured.effective_text_layer
         if layer is None:
             return None
 
-        if isinstance(layer.content, list):
-            text_colors = {
-                _rgb_tuple(self._text.resolve_color(part, layer)) for part in layer.content
-            }
-        elif layer.color:
-            text_colors = {_rgb_tuple(self._effects.parse_color(layer.color))}
-        else:
-            text_colors = {_rgb_tuple(DEFAULT_TEXT_COLOR)}
-
         box = measured.bbox
         if box is None:
             return None
         clamped = box.clamped_to(self._ctx.width, self._ctx.height)
         if clamped is None:
             return None
 
+        foreground = self._render_text_foreground(layer)
         return worst_tile_contrast(
             running,
+            foreground,
             clamped,
-            text_colors,
             tile_size=CONTRAST_TILE_SIZE,
         )
 
+    def _render_text_foreground(self, layer: TextLayer) -> Image.Image:
+        content = layer.content
+        if isinstance(content, list):
+            content = [part.model_copy(update={"effects": []}) for part in content]
+        foreground_layer = layer.model_copy(update={"content": content, "effects": []})
 
-def _rgb_tuple(color: tuple[int, ...]) -> tuple[float, float, float]:
-    return float(color[0]), float(color[1]), float(color[2])
+        foreground = Image.new("RGBA", (self._ctx.width, self._ctx.height), (0, 0, 0, 0))
+        self._text.render_text_layer(foreground, foreground_layer)
+        return foreground

tests/test_diagnostics.py

@@ -516,6 +516,63 @@ def paint_split_background(image: Image.Image) -> None:
         assert finding.measured["tile_bbox"]["x"] >= 116
         assert finding.measured["background_rgb"][0] > 240
 
+    def test_should_ignore_low_contrast_tiles_without_text_pixels(self):
+        """Whitespace inside the text bbox does not drive low-contrast findings"""
+        from quickthumb import Canvas
+
+        def paint_background_with_light_gap(image: Image.Image) -> None:
+            image.paste((0, 0, 0, 255), (0, 0, 300, 120))
+            image.paste((255, 255, 255, 255), (70, 0, 120, 120))
+
+        # given: white glyphs sit on black while only the empty space crosses white
+        canvas = (
+            Canvas(300, 120)
+            .custom(paint_background_with_light_gap)
+            .text("A          A", size=36, color="#FFFFFF", position=(20, 30))
+        )
+
+        # when / then
+        assert canvas.diagnose() == []
+
+    def test_should_not_warn_for_readable_rich_text_on_split_background(self):
+        """Rich text colors are compared only where each colored run renders"""
+        from quickthumb import Canvas
+
+        def paint_split_background(image: Image.Image) -> None:
+            image.paste((0, 0, 0, 255), (0, 0, 300, 120))
+            image.paste((255, 255, 255, 255), (70, 0, 300, 120))
+
+        # given: white rich text renders on black and black rich text renders on white
+        canvas = (
+            Canvas(300, 120)
+            .custom(paint_split_background)
+            .text(
+                [
+                    {"text": "L", "color": "#FFFFFF"},
+                    {"text": "          R", "color": "#000000"},
+                ],
+                size=36,
+                position=(20, 30),
+            )
+        )
+
+        # when / then
+        assert canvas.diagnose() == []
+
+    def test_should_use_default_text_color_for_worst_tile_contrast(self):
+        """Text without a color still uses the public default black foreground"""
+        from quickthumb import Canvas
+
+        # given: default black text over a black background
+        canvas = Canvas(200, 120).background(color="#000000").text("default", size=36)
+
+        # when
+        diagnostics = canvas.diagnose()
+
+        # then
+        assert [finding.code for finding in diagnostics] == ["low-contrast"]
+        assert diagnostics[0].measured["foreground_rgb"] == (0.0, 0.0, 0.0)
+
     @pytest.mark.parametrize(
         "background,color",
         [