Merge pull request #209 from bgilbert/icc

Support ICC profiles

Author: bgilbert

MANIFEST.in

@@ -1,4 +1,4 @@
 include *.md pytest.ini
 recursive-include doc *.py *.rst
 recursive-include examples *.html *.js *.png *.py
-recursive-include tests *.png *.py *.svs *.tiff
+recursive-include tests *.dcm *.png *.py *.svs *.tiff

doc/conf.py

@@ -46,7 +46,7 @@
 
 # General information about the project.
 project = 'OpenSlide Python'
-copyright = '2010-2022 Carnegie Mellon University and others'
+copyright = '2010-2023 Carnegie Mellon University and others'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

doc/index.rst

@@ -148,6 +148,12 @@ OpenSlide objects
 
       Unlike in the C interface, these images are not premultiplied.
 
+   .. attribute:: color_profile
+
+      The embedded :ref:`color profile <color-management>` for this slide,
+      as a Pillow :class:`~PIL.ImageCms.ImageCmsProfile`, or :obj:`None` if
+      not available.
+
    .. method:: read_region(location, level, size)
 
       Return an RGBA :class:`Image <PIL.Image.Image>` containing the
@@ -188,6 +194,58 @@ OpenSlide objects
       Close the OpenSlide object.
 
 
+.. _color-management:
+
+Color management
+----------------
+
+Every slide region, associated image, thumbnail, and Deep Zoom tile produced
+by OpenSlide Python includes a reference to an ICC color profile whenever a
+profile is available for the underlying pixel data.  Profiles are stored as
+a :class:`bytes` object in
+:attr:`Image.info <PIL.Image.Image.info>`:attr:`['icc_profile']`.  If no
+profile is available, the :attr:`icc_profile` dictionary key is absent.
+
+To include the profile in an image file when saving the image to disk::
+
+    image.save(filename, icc_profile=image.info.get('icc_profile'))
+
+To perform color conversions using the profile, import it into
+:mod:`ImageCms <PIL.ImageCms>`.  For example, to convert an image in-place
+to a synthesized sRGB profile, using absolute colorimetric rendering::
+
+    from io import BytesIO
+    from PIL import ImageCms
+
+    fromProfile = ImageCms.getOpenProfile(BytesIO(image.info['icc_profile']))
+    toProfile = ImageCms.createProfile('sRGB')
+    ImageCms.profileToProfile(
+        image, fromProfile, toProfile,
+        ImageCms.Intent.ABSOLUTE_COLORIMETRIC, 'RGBA', True, 0
+    )
+
+Absolute colorimetric rendering `maximizes the comparability`_ of images
+produced by different scanners.  When converting Deep Zoom tiles, use
+``'RGB'`` instead of ``'RGBA'``.
+
+All pyramid regions in a slide have the same profile, but each associated
+image can have its own profile.  As a convenience, the former is also
+available as :attr:`OpenSlide.color_profile`, already parsed into an
+:class:`~PIL.ImageCms.ImageCmsProfile` object.  You can save processing time
+by building an :class:`~PIL.ImageCms.ImageCmsTransform` for the slide and
+reusing it for multiple slide regions::
+
+    toProfile = ImageCms.createProfile('sRGB')
+    transform = ImageCms.buildTransform(
+        slide.color_profile, toProfile, 'RGBA', 'RGBA',
+        ImageCms.Intent.ABSOLUTE_COLORIMETRIC, 0
+    )
+    # for each region image:
+    ImageCms.applyTransform(image, transform, True)
+
+.. _maximizes the comparability: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC4478790/
+
+
 Caching
 -------
 
@@ -286,8 +344,8 @@ Exceptions
    Subclass of :exc:`OpenSlideError`.
 
 
-Wrapping a PIL Image
-====================
+Wrapping a Pillow Image
+=======================
 
 .. class:: ImageSlide(file)
 

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'
     )