examples/deepzoom: convert to sRGB via selectable "color modes"

bgilbert · bgilbert · commit 17e2b08c5ef9 · 2023-07-22T00:47:39.000-04:00
By default, use absolute colorimetric rendering intent, since that
preserves comparability between slides.  Allow configuring other rendering
intents, or embedding the slide's ICC profile in individual tiles so the
viewer can do its own color management, or ignoring the ICC profile (the
legacy behavior).

Embed our own ICC v2 sRGB profile instead of using the v4 one generated by
Pillow, for reproducibility and because Firefox apparently doesn't fully
support v4 profiles.

Signed-off-by: Benjamin Gilbert &lt;bgilbert@cs.cmu.edu&gt;
diff --git a/examples/deepzoom/deepzoom_multiserver.py b/examples/deepzoom/deepzoom_multiserver.py
@@ -3,7 +3,7 @@
 # deepzoom_multiserver - Example web application for viewing multiple slides
 #
 # Copyright (c) 2010-2015 Carnegie Mellon University
-# Copyright (c) 2021-2022 Benjamin Gilbert
+# Copyright (c) 2021-2023 Benjamin Gilbert
 #
 # This library is free software; you can redistribute it and/or modify it
 # under the terms of version 2.1 of the GNU Lesser General Public License
@@ -20,11 +20,14 @@
 #
 
 from argparse import ArgumentParser
+import base64
 from collections import OrderedDict
 from io import BytesIO
 import os
 from threading import Lock
+import zlib
 
+from PIL import ImageCms
 from flask import Flask, abort, make_response, render_template, url_for
 
 if os.name == 'nt':
@@ -40,6 +43,23 @@
 from openslide import OpenSlide, OpenSlideCache, OpenSlideError, OpenSlideVersionError
 from openslide.deepzoom import DeepZoomGenerator
 
+# Optimized sRGB v2 profile, CC0-1.0 license
+# https://github.com/saucecontrol/Compact-ICC-Profiles/blob/bdd84663/profiles/sRGB-v2-micro.icc
+# ImageCms.createProfile() generates a v4 profile and Firefox has problems
+# with those: https://littlecms.com/blog/2020/09/09/browser-check/
+SRGB_PROFILE_BYTES = zlib.decompress(
+    base64.b64decode(
+        'eNpjYGA8kZOcW8wkwMCQm1dSFOTupBARGaXA/oiBmUGEgZOBj0E2Mbm4wDfYLYQBCIoT'
+        'y4uTS4pyGFDAt2sMjCD6sm5GYl7K3IkMtg4NG2wdSnQa5y1V6mPADzhTUouTgfQHII5P'
+        'LigqYWBg5AGyecpLCkBsCSBbpAjoKCBbB8ROh7AdQOwkCDsErCYkyBnIzgCyE9KR2ElI'
+        'bKhdIMBaCvQsskNKUitKQLSzswEDKAwgop9DwH5jFDuJEMtfwMBg8YmBgbkfIZY0jYFh'
+        'eycDg8QthJgKUB1/KwPDtiPJpUVlUGu0gLiG4QfjHKZS5maWk2x+HEJcEjxJfF8Ez4t8'
+        'k8iS0VNwVlmjmaVXZ/zacrP9NbdwX7OQshjxFNmcttKwut4OnUlmc1Yv79l0e9/MU8ev'
+        'pz4p//jz/38AR4Nk5Q=='
+    )
+)
+SRGB_PROFILE = ImageCms.getOpenProfile(BytesIO(SRGB_PROFILE_BYTES))
+
 
 def create_app(config=None, config_file=None):
     # Create and configure app
@@ -53,6 +73,7 @@ def create_app(config=None, config_file=None):
         DEEPZOOM_OVERLAP=1,
         DEEPZOOM_LIMIT_BOUNDS=True,
         DEEPZOOM_TILE_QUALITY=75,
+        DEEPZOOM_COLOR_MODE='absolute-colorimetric',
     )
     app.config.from_envvar('DEEPZOOM_MULTISERVER_SETTINGS', silent=True)
     if config_file is not None:
@@ -69,7 +90,10 @@ def create_app(config=None, config_file=None):
     }
     opts = {v: app.config[k] for k, v in config_map.items()}
     app.cache = _SlideCache(
-        app.config['SLIDE_CACHE_SIZE'], app.config['SLIDE_TILE_CACHE_MB'], opts
+        app.config['SLIDE_CACHE_SIZE'],
+        app.config['SLIDE_TILE_CACHE_MB'],
+        opts,
+        app.config['DEEPZOOM_COLOR_MODE'],
     )
 
     # Helper functions
@@ -123,8 +147,14 @@ def tile(path, level, col, row, format):
         except ValueError:
             # Invalid level or coordinates
             abort(404)
+        slide.transform(tile)
         buf = BytesIO()
-        tile.save(buf, format, quality=app.config['DEEPZOOM_TILE_QUALITY'])
+        tile.save(
+            buf,
+            format,
+            quality=app.config['DEEPZOOM_TILE_QUALITY'],
+            icc_profile=tile.info.get('icc_profile'),
+        )
         resp = make_response(buf.getvalue())
         resp.mimetype = 'image/%s' % format
         return resp
@@ -133,9 +163,10 @@ def tile(path, level, col, row, format):
 
 
 class _SlideCache:
-    def __init__(self, cache_size, tile_cache_mb, dz_opts):
+    def __init__(self, cache_size, tile_cache_mb, dz_opts, color_mode):
         self.cache_size = cache_size
         self.dz_opts = dz_opts
+        self.color_mode = color_mode
         self._lock = Lock()
         self._cache = OrderedDict()
         # Share a single tile cache among all slide handles, if supported
@@ -162,6 +193,7 @@ def get(self, path):
             slide.mpp = (float(mpp_x) + float(mpp_y)) / 2
         except (KeyError, ValueError):
             slide.mpp = 0
+        slide.transform = self._get_transform(osr)
 
         with self._lock:
             if path not in self._cache:
@@ -170,6 +202,44 @@ def get(self, path):
                 self._cache[path] = slide
         return slide
 
+    def _get_transform(self, image):
+        if image.color_profile is None:
+            return lambda img: None
+        mode = self.color_mode
+        if mode == 'ignore':
+            # drop ICC profile from tiles
+            return lambda img: img.info.pop('icc_profile')
+        elif mode == 'embed':
+            # embed ICC profile in tiles
+            return lambda img: None
+        elif mode == 'absolute-colorimetric':
+            intent = ImageCms.Intent.ABSOLUTE_COLORIMETRIC
+        elif mode == 'relative-colorimetric':
+            intent = ImageCms.Intent.RELATIVE_COLORIMETRIC
+        elif mode == 'perceptual':
+            intent = ImageCms.Intent.PERCEPTUAL
+        elif mode == 'saturation':
+            intent = ImageCms.Intent.SATURATION
+        else:
+            raise ValueError(f'Unknown color mode {mode}')
+        transform = ImageCms.buildTransform(
+            image.color_profile,
+            SRGB_PROFILE,
+            'RGB',
+            'RGB',
+            intent,
+            0,
+        )
+
+        def xfrm(img):
+            ImageCms.applyTransform(img, transform, True)
+            # Some browsers assume we intend the display's color space if we
+            # don't embed the profile.  Pillow's serialization is larger, so
+            # use ours.
+            img.info['icc_profile'] = SRGB_PROFILE_BYTES
+
+        return xfrm
+
 
 class _Directory:
     def __init__(self, basedir, relpath=''):
@@ -202,6 +272,24 @@ def __init__(self, relpath):
         action='store_false',
         help='display entire scan area',
     )
+    parser.add_argument(
+        '--color-mode',
+        dest='DEEPZOOM_COLOR_MODE',
+        choices=[
+            'absolute-colorimetric',
+            'perceptual',
+            'relative-colorimetric',
+            'saturation',
+            'embed',
+            'ignore',
+        ],
+        default='absolute-colorimetric',
+        help=(
+            'convert tiles to sRGB using specified rendering intent, or '
+            'embed original ICC profile, or ignore ICC profile (compat) '
+            '[absolute-colorimetric]'
+        ),
+    )
     parser.add_argument(
         '-c', '--config', metavar='FILE', dest='config', help='config file'
     )
diff --git a/examples/deepzoom/deepzoom_server.py b/examples/deepzoom/deepzoom_server.py
@@ -3,6 +3,7 @@
 # deepzoom_server - Example web application for serving whole-slide images
 #
 # Copyright (c) 2010-2015 Carnegie Mellon University
+# Copyright (c) 2023      Benjamin Gilbert
 #
 # This library is free software; you can redistribute it and/or modify it
 # under the terms of version 2.1 of the GNU Lesser General Public License
@@ -19,11 +20,14 @@
 #
 
 from argparse import ArgumentParser
+import base64
 from io import BytesIO
 import os
 import re
 from unicodedata import normalize
+import zlib
 
+from PIL import ImageCms
 from flask import Flask, abort, make_response, render_template, url_for
 
 if os.name == 'nt':
@@ -41,6 +45,23 @@
 
 SLIDE_NAME = 'slide'
 
+# Optimized sRGB v2 profile, CC0-1.0 license
+# https://github.com/saucecontrol/Compact-ICC-Profiles/blob/bdd84663/profiles/sRGB-v2-micro.icc
+# ImageCms.createProfile() generates a v4 profile and Firefox has problems
+# with those: https://littlecms.com/blog/2020/09/09/browser-check/
+SRGB_PROFILE_BYTES = zlib.decompress(
+    base64.b64decode(
+        'eNpjYGA8kZOcW8wkwMCQm1dSFOTupBARGaXA/oiBmUGEgZOBj0E2Mbm4wDfYLYQBCIoT'
+        'y4uTS4pyGFDAt2sMjCD6sm5GYl7K3IkMtg4NG2wdSnQa5y1V6mPADzhTUouTgfQHII5P'
+        'LigqYWBg5AGyecpLCkBsCSBbpAjoKCBbB8ROh7AdQOwkCDsErCYkyBnIzgCyE9KR2ElI'
+        'bKhdIMBaCvQsskNKUitKQLSzswEDKAwgop9DwH5jFDuJEMtfwMBg8YmBgbkfIZY0jYFh'
+        'eycDg8QthJgKUB1/KwPDtiPJpUVlUGu0gLiG4QfjHKZS5maWk2x+HEJcEjxJfF8Ez4t8'
+        'k8iS0VNwVlmjmaVXZ/zacrP9NbdwX7OQshjxFNmcttKwut4OnUlmc1Yv79l0e9/MU8ev'
+        'pz4p//jz/38AR4Nk5Q=='
+    )
+)
+SRGB_PROFILE = ImageCms.getOpenProfile(BytesIO(SRGB_PROFILE_BYTES))
+
 
 def create_app(config=None, config_file=None):
     # Create and configure app
@@ -52,6 +73,7 @@ def create_app(config=None, config_file=None):
         DEEPZOOM_OVERLAP=1,
         DEEPZOOM_LIMIT_BOUNDS=True,
         DEEPZOOM_TILE_QUALITY=75,
+        DEEPZOOM_COLOR_MODE='absolute-colorimetric',
     )
     app.config.from_envvar('DEEPZOOM_TILER_SETTINGS', silent=True)
     if config_file is not None:
@@ -71,12 +93,19 @@ def create_app(config=None, config_file=None):
     opts = {v: app.config[k] for k, v in config_map.items()}
     slide = open_slide(slidefile)
     app.slides = {SLIDE_NAME: DeepZoomGenerator(slide, **opts)}
+    app.transforms = {
+        SLIDE_NAME: get_transform(slide, app.config['DEEPZOOM_COLOR_MODE'])
+    }
     app.associated_images = []
     app.slide_properties = slide.properties
     for name, image in slide.associated_images.items():
         app.associated_images.append(name)
         slug = slugify(name)
-        app.slides[slug] = DeepZoomGenerator(ImageSlide(image), **opts)
+        image_slide = ImageSlide(image)
+        app.slides[slug] = DeepZoomGenerator(image_slide, **opts)
+        app.transforms[slug] = get_transform(
+            image_slide, app.config['DEEPZOOM_COLOR_MODE']
+        )
     try:
         mpp_x = slide.properties[openslide.PROPERTY_NAME_MPP_X]
         mpp_y = slide.properties[openslide.PROPERTY_NAME_MPP_Y]
@@ -124,8 +153,14 @@ def tile(slug, level, col, row, format):
         except ValueError:
             # Invalid level or coordinates
             abort(404)
+        app.transforms[slug](tile)
         buf = BytesIO()
-        tile.save(buf, format, quality=app.config['DEEPZOOM_TILE_QUALITY'])
+        tile.save(
+            buf,
+            format,
+            quality=app.config['DEEPZOOM_TILE_QUALITY'],
+            icc_profile=tile.info.get('icc_profile'),
+        )
         resp = make_response(buf.getvalue())
         resp.mimetype = 'image/%s' % format
         return resp
@@ -138,6 +173,43 @@ def slugify(text):
     return re.sub('[^a-z0-9]+', '-', text)
 
 
+def get_transform(image, mode):
+    if image.color_profile is None:
+        return lambda img: None
+    if mode == 'ignore':
+        # drop ICC profile from tiles
+        return lambda img: img.info.pop('icc_profile')
+    elif mode == 'embed':
+        # embed ICC profile in tiles
+        return lambda img: None
+    elif mode == 'absolute-colorimetric':
+        intent = ImageCms.Intent.ABSOLUTE_COLORIMETRIC
+    elif mode == 'relative-colorimetric':
+        intent = ImageCms.Intent.RELATIVE_COLORIMETRIC
+    elif mode == 'perceptual':
+        intent = ImageCms.Intent.PERCEPTUAL
+    elif mode == 'saturation':
+        intent = ImageCms.Intent.SATURATION
+    else:
+        raise ValueError(f'Unknown color mode {mode}')
+    transform = ImageCms.buildTransform(
+        image.color_profile,
+        SRGB_PROFILE,
+        'RGB',
+        'RGB',
+        intent,
+        0,
+    )
+
+    def xfrm(img):
+        ImageCms.applyTransform(img, transform, True)
+        # Some browsers assume we intend the display's color space if we don't
+        # embed the profile.  Pillow's serialization is larger, so use ours.
+        img.info['icc_profile'] = SRGB_PROFILE_BYTES
+
+    return xfrm
+
+
 if __name__ == '__main__':
     parser = ArgumentParser(usage='%(prog)s [options] [SLIDE]')
     parser.add_argument(
@@ -148,6 +220,24 @@ def slugify(text):
         action='store_false',
         help='display entire scan area',
     )
+    parser.add_argument(
+        '--color-mode',
+        dest='DEEPZOOM_COLOR_MODE',
+        choices=[
+            'absolute-colorimetric',
+            'perceptual',
+            'relative-colorimetric',
+            'saturation',
+            'embed',
+            'ignore',
+        ],
+        default='absolute-colorimetric',
+        help=(
+            'convert tiles to sRGB using specified rendering intent, or '
+            'embed original ICC profile, or ignore ICC profile (compat) '
+            '[absolute-colorimetric]'
+        ),
+    )
     parser.add_argument(
         '-c', '--config', metavar='FILE', dest='config', help='config file'
     )
diff --git a/examples/deepzoom/deepzoom_tile.py b/examples/deepzoom/deepzoom_tile.py
