Add AbstractSlide.color_profile property

For any given slide, every image returned by read_region() will have the
same color profile.  It's important that we attach it to every region to
document the correct color space, but applications that want to do color
conversion may find it more efficient to build a transform once, up front.
Add a property to help them do this.

Signed-off-by: Benjamin Gilbert <bgilbert@cs.cmu.edu>

Author: bgilbert

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,8 @@ OpenSlide objects
       Close the OpenSlide object.
 
 
+.. _color-management:
+
 Color management
 ----------------
 

openslide/__init__.py

@@ -24,8 +24,9 @@
 """
 
 from collections.abc import Mapping
+from io import BytesIO
 
-from PIL import Image
+from PIL import Image, ImageCms
 
 from openslide import lowlevel
 
@@ -114,6 +115,13 @@ def associated_images(self):
         This is a map: image name -> PIL.Image."""
         raise NotImplementedError
 
+    @property
+    def color_profile(self):
+        """Color profile for the whole-slide image, or None if unavailable."""
+        if self._profile is None:
+            return None
+        return ImageCms.getOpenProfile(BytesIO(self._profile))
+
     def get_best_level_for_downsample(self, downsample):
         """Return the best level for displaying the given downsample."""
         raise NotImplementedError

tests/test_imageslide.py

@@ -89,6 +89,7 @@ def test_metadata(self):
         self.assertEqual(self.osr.associated_images, {})
 
     def test_color_profile(self):
+        self.assertEqual(self.osr.color_profile.profile.device_class, 'mntr')
         self.assertEqual(
             len(self.osr.read_region((0, 0), 0, (100, 100)).info['icc_profile']), 588
         )
@@ -127,6 +128,7 @@ class TestNoIccImage(_SlideTest, unittest.TestCase):
     FILENAME = 'boxes-no-icc.png'
 
     def test_color_profile(self):
+        self.assertIsNone(self.osr.color_profile)
         self.assertNotIn(
             'icc_profile', self.osr.read_region((0, 0), 0, (100, 100)).info
         )

tests/test_openslide.py

@@ -127,6 +127,7 @@ def test_properties(self):
         lowlevel.read_icc_profile.available, "requires OpenSlide 4.0.0"
     )
     def test_color_profile(self):
+        self.assertEqual(self.osr.color_profile.profile.device_class, 'mntr')
         self.assertEqual(
             len(self.osr.read_region((0, 0), 0, (100, 100)).info['icc_profile']), 588
         )
@@ -196,6 +197,7 @@ def mangle_repr(o):
         )
 
     def test_color_profile(self):
+        self.assertIsNone(self.osr.color_profile)
         self.assertNotIn(
             'icc_profile', self.osr.read_region((0, 0), 0, (100, 100)).info
         )
@@ -212,6 +214,7 @@ class TestDicomSlide(_SlideTest, unittest.TestCase):
     FILENAME = 'boxes_0.dcm'
 
     def test_color_profile(self):
+        self.assertEqual(self.osr.color_profile.profile.device_class, 'mntr')
         main_profile = self.osr.read_region((0, 0), 0, (100, 100)).info['icc_profile']
         associated_profile = self.osr.associated_images['thumbnail'].info['icc_profile']
         self.assertEqual(len(main_profile), 456)