image profile icc profile convert compatiblity check

Author: 67372a

library/image_utils.py

@@ -28,6 +28,59 @@
     (0, ImageCms.Intent.RELATIVE_COLORIMETRIC),
 ]
 
+# Maps ICC colour-space signatures (bytes 16-19 of the ICC header) to
+# the PIL image modes that are *compatible* with that colour-space.
+# littlecms cannot build a transform when the image mode and the ICC
+# colour-space are fundamentally incompatible (e.g. greyscale pixel
+# data with an RGB profile).
+_CS_TO_MODES = {
+    "RGB ": ("RGB", "RGBA"),
+    "GRAY": ("L", "LA"),
+    "CMYK": ("CMYK",),
+}
+
+
+def _extract_icc_color_space(src_profile, icc_bytes: bytes | None = None) -> str:
+    """Return the ICC colour-space signature, or ``""`` if unknown.
+
+    Tries the ``ImageCms`` API first, then falls back to reading the
+    4-byte colour-space field directly from the raw ICC header (bytes
+    16-19 per ICC.1:2022 §7.2.6).
+    """
+    try:
+        cs = ImageCms.getColorSpace(src_profile)
+        if cs:
+            return cs.strip()
+    except Exception:
+        pass
+
+    # Fallback: raw ICC header from bytes or from profile object.
+    raw = icc_bytes
+    if raw is None and src_profile is not None:
+        try:
+            raw = src_profile.tobytes()
+        except Exception:
+            pass
+    if raw is not None and len(raw) >= 20:
+        try:
+            return raw[16:20].decode("ascii", errors="replace")
+        except Exception:
+            pass
+
+    return ""
+
+
+def _mode_matches_profile(im_mode: str, color_space: str) -> bool:
+    """Return ``True`` if *im_mode* is compatible with *color_space*.
+
+    If *color_space* is unrecognised the function returns ``True``
+    (benefit of the doubt — we'll let littlecms try).
+    """
+    expected = _CS_TO_MODES.get(color_space)
+    if expected is None:
+        return True  # unknown colour-space → don't block the attempt
+    return im_mode in expected
+
 
 def _log_profile_failure(im: Image.Image, src_profile=None) -> None:
     """Log diagnostic information about a failed ICC conversion.
@@ -45,7 +98,8 @@ def _log_profile_failure(im: Image.Image, src_profile=None) -> None:
 
     # --- ICC profile details (each call independent so one failure
     #     doesn't suppress the others) ---
-    profile_name = profile_class = color_space = "<unavailable>"
+    profile_name = profile_class = "<unavailable>"
+    color_space = ""
     icc_size = 0
     if src_profile is not None:
         try:
@@ -56,46 +110,23 @@ def _log_profile_failure(im: Image.Image, src_profile=None) -> None:
             profile_class = ImageCms.getProfileClass(src_profile).strip()
         except Exception:
             pass
-        try:
-            color_space = ImageCms.getColorSpace(src_profile).strip()
-        except Exception:
-            pass
         try:
             icc_size = len(src_profile.tobytes())
         except Exception:
             pass
 
-    # --- detect the likely cause ---
-    reason = ""
     icc_bytes = im.info.get("icc_profile")
+    color_space = _extract_icc_color_space(src_profile, icc_bytes) or "<unavailable>"
     if icc_bytes:
         icc_size = icc_size or len(icc_bytes)
 
-        # Fallback: if the ImageCms API didn't yield a colour-space,
-        # read it directly from the ICC header (bytes 16-19 are the
-        # colour-space signature in the ICC spec).
-        if color_space == "<unavailable>" and len(icc_bytes) >= 20:
-            try:
-                color_space = icc_bytes[16:20].decode("ascii", errors="replace")
-            except Exception:
-                pass
-
-        # Check for a common mismatch: e.g. greyscale/LA image carrying
-        # an RGB profile (or vice-versa).  littlecms cannot build a
-        # transform when the image mode and the ICC colour-space are
-        # fundamentally incompatible.
-        _CS_TO_MODES = {
-            "RGB ": ("RGB", "RGBA"),
-            "GRAY": ("L", "LA"),
-            "CMYK": ("CMYK",),
-        }
-        expected_modes = _CS_TO_MODES.get(color_space, ())
-        if color_space != "<unavailable>" and im.mode not in expected_modes:
-            reason = (
-                f" — likely cause: image mode={im.mode} does not match "
-                f"ICC profile colour-space={color_space!r}; "
-                f"littlecms cannot build a transform across these types"
-            )
+    reason = ""
+    if color_space != "<unavailable>" and not _mode_matches_profile(im.mode, color_space):
+        reason = (
+            f" — likely cause: image mode={im.mode} does not match "
+            f"ICC profile colour-space={color_space!r}; "
+            f"littlecms cannot build a transform across these types"
+        )
 
     logger.warning(
         "ICC-aware colour conversion failed for image mode=%s, size=%s, "
@@ -139,6 +170,10 @@ def to_srgb(im: Image.Image, assume: str = "sRGB") -> Image.Image:
       CMYK profile is present (or the *assume* fallback).  PIL's
       ``profileToProfile`` handles the CMYK → RGB channel reduction
       natively when ``outputMode="RGB"``.
+    * If the image mode and the embedded ICC profile colour-space are
+      incompatible (e.g. a greyscale image carrying an sRGB profile),
+      the ICC pipeline is skipped entirely and a plain
+      ``im.convert("RGB")`` is returned without logging a warning.
     * The function tries several (flags, rendering-intent) combinations
       before falling back, so that images carrying unusual ICC profiles
       (V4, wide-gamut, etc.) still get correct colour conversion when
@@ -150,16 +185,35 @@ def to_srgb(im: Image.Image, assume: str = "sRGB") -> Image.Image:
     if im.mode == "RGB" and not im.info.get("icc_profile"):
         return im
 
-    src = None  # ensure defined for the except clause
-    try:
-        # --- determine source profile ---
-        icc_bytes = im.info.get("icc_profile")
-        if icc_bytes:
+    icc_bytes = im.info.get("icc_profile")
+
+    # --- proactive mismatch check ---
+    # If the image carries an ICC profile whose colour-space is
+    # incompatible with the image mode (e.g. greyscale pixels + sRGB
+    # profile), littlecms will *never* be able to build a transform.
+    # Detect this and convert silently rather than trying all four
+    # fallback combos and emitting a noisy warning.
+    if icc_bytes:
+        try:
             src = ImageCms.ImageCmsProfile(io.BytesIO(icc_bytes))
-        else:
-            src = ImageCms.createProfile(assume)
+        except Exception:
+            # Profile bytes are corrupt — plain convert is the only option.
+            return im.convert("RGB")
+
+        cs = _extract_icc_color_space(src, icc_bytes)
+        if cs and not _mode_matches_profile(im.mode, cs):
+            logger.debug(
+                "Image mode=%s is incompatible with ICC colour-space=%r; "
+                "skipping ICC pipeline and converting directly to RGB",
+                im.mode,
+                cs,
+            )
+            return im.convert("RGB")
+    else:
+        src = ImageCms.createProfile(assume)
 
-        # --- convert via the ICC pipeline ---
+    # --- convert via the ICC pipeline ---
+    try:
         for flags, intent in _TRANSFORM_ATTEMPTS:
             try:
                 result = ImageCms.profileToProfile(

tests/test_image_utils.py

@@ -12,7 +12,13 @@
 # Allow running from repo root or tests/
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
 
-from library.image_utils import to_srgb, _TRANSFORM_ATTEMPTS, _log_profile_failure
+from library.image_utils import (
+    to_srgb,
+    _TRANSFORM_ATTEMPTS,
+    _log_profile_failure,
+    _extract_icc_color_space,
+    _mode_matches_profile,
+)
 
 
 # ---------------------------------------------------------------------------
@@ -365,5 +371,133 @@ def test_handles_broken_profile_gracefully(self, caplog):
         assert "falling back" in caplog.text
 
 
+class TestProactiveMismatch:
+    """Tests for the proactive mode/profile mismatch detection."""
+
+    def test_greyscale_with_srgb_profile_converts_silently(self, caplog):
+        """A greyscale image carrying an sRGB profile should convert
+        directly to RGB without emitting a WARNING — the mismatch is
+        known and expected."""
+        im = _make_solid("L", color=128)
+        im.info["icc_profile"] = _make_srgb_profile_bytes()
+
+        with caplog.at_level("DEBUG", logger="library.image_utils"):
+            result = to_srgb(im)
+
+        assert result.mode == "RGB"
+        assert result.size == im.size
+        # Should log at DEBUG, not WARNING.
+        assert "incompatible" in caplog.text.lower() or "skipping" in caplog.text.lower()
+        assert "WARNING" not in caplog.text
+
+    def test_greyscale_with_srgb_profile_uses_plain_convert(self):
+        """Fallback path should produce the same pixels as im.convert('RGB')."""
+        im = _make_solid("L", color=200)
+        im.info["icc_profile"] = _make_srgb_profile_bytes()
+
+        result = to_srgb(im)
+        expected = im.convert("RGB")
+        np.testing.assert_array_equal(np.array(result), np.array(expected))
+
+    def test_la_with_srgb_profile_converts_silently(self, caplog):
+        """LA (greyscale + alpha) with an sRGB profile should also be
+        detected as a mismatch and converted silently."""
+        im = _make_solid("LA", color=(128, 255))
+        im.info["icc_profile"] = _make_srgb_profile_bytes()
+
+        with caplog.at_level("DEBUG", logger="library.image_utils"):
+            result = to_srgb(im)
+
+        assert result.mode == "RGB"
+        assert "WARNING" not in caplog.text
+
+    def test_rgb_with_srgb_profile_still_uses_icc_pipeline(self):
+        """An RGB image with an sRGB profile should still go through the
+        ICC pipeline (sRGB→sRGB is identity, but the pipeline should run)."""
+        im = _make_solid("RGB", color=(128, 64, 32))
+        im.info["icc_profile"] = _make_srgb_profile_bytes()
+
+        with patch("library.image_utils.ImageCms.profileToProfile", wraps=ImageCms.profileToProfile) as mock_ptp:
+            result = to_srgb(im)
+
+        mock_ptp.assert_called_once()
+        assert result.mode == "RGB"
+
+    def test_corrupt_profile_bytes_converts_directly(self):
+        """Corrupt ICC bytes that cannot even be parsed should still
+        produce an RGB result via plain convert."""
+        im = _make_solid("L", color=100)
+        im.info["icc_profile"] = b"not-a-valid-icc-profile"
+
+        result = to_srgb(im)
+        assert result.mode == "RGB"
+        expected = im.convert("RGB")
+        np.testing.assert_array_equal(np.array(result), np.array(expected))
+
+    def test_no_warning_for_known_mismatch(self, caplog):
+        """The proactive detection should suppress the WARNING that would
+        otherwise be emitted by _log_profile_failure."""
+        im = _make_solid("L", color=128)
+        im.info["icc_profile"] = _make_srgb_profile_bytes()
+
+        with caplog.at_level("WARNING", logger="library.image_utils"):
+            to_srgb(im)
+
+        # No WARNING should appear at all.
+        assert caplog.text.count("WARNING") == 0
+
+
+class TestExtractIccColorSpace:
+    """Tests for the _extract_icc_color_space helper."""
+
+    def test_extracts_rgb_from_profile(self):
+        """An sRGB profile should yield colour-space 'RGB '."""
+        src = ImageCms.ImageCmsProfile(ImageCms.createProfile("sRGB"))
+        cs = _extract_icc_color_space(src)
+        assert "RGB" in cs
+
+    def test_extracts_from_raw_bytes_fallback(self):
+        """When the ImageCms API fails, should fall back to raw header."""
+        srgb_bytes = _make_srgb_profile_bytes()
+        # Pass a mock that makes getColorSpace fail
+        mock_profile = MagicMock()
+        cs = _extract_icc_color_space(mock_profile, srgb_bytes)
+        assert "RGB" in cs
+
+    def test_returns_empty_for_no_data(self):
+        """No profile and no bytes → empty string."""
+        cs = _extract_icc_color_space(MagicMock(), None)
+        assert cs == ""
+
+
+class TestModeMatchesProfile:
+    """Tests for the _mode_matches_profile helper."""
+
+    def test_rgb_matches_rgb_space(self):
+        assert _mode_matches_profile("RGB", "RGB ") is True
+
+    def test_rgba_matches_rgb_space(self):
+        assert _mode_matches_profile("RGBA", "RGB ") is True
+
+    def test_l_does_not_match_rgb_space(self):
+        assert _mode_matches_profile("L", "RGB ") is False
+
+    def test_la_does_not_match_rgb_space(self):
+        assert _mode_matches_profile("LA", "RGB ") is False
+
+    def test_l_matches_gray_space(self):
+        assert _mode_matches_profile("L", "GRAY") is True
+
+    def test_cmyk_matches_cmyk_space(self):
+        assert _mode_matches_profile("CMYK", "CMYK") is True
+
+    def test_unknown_space_returns_true(self):
+        """Unrecognised colour-space should not block the attempt."""
+        assert _mode_matches_profile("L", "XYZ ") is True
+
+    def test_rgb_does_not_match_gray_space(self):
+        assert _mode_matches_profile("RGB", "GRAY") is False
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])