openslide.deepzoom: Optionally render only the non-empty region

Author: bgilbert

examples/deepzoom/deepzoom_server.py

@@ -2,7 +2,7 @@
 #
 # deepzoom_server - Example web application for serving whole-slide images
 #
-# Copyright (c) 2010-2013 Carnegie Mellon University
+# Copyright (c) 2010-2014 Carnegie Mellon University
 #
 # 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
@@ -30,6 +30,7 @@
 DEEPZOOM_FORMAT = 'jpeg'
 DEEPZOOM_TILE_SIZE = 256
 DEEPZOOM_OVERLAP = 1
+DEEPZOOM_LIMIT_BOUNDS = True
 DEEPZOOM_TILE_QUALITY = 75
 SLIDE_NAME = 'slide'
 
@@ -46,6 +47,7 @@ def load_slide():
     config_map = {
         'DEEPZOOM_TILE_SIZE': 'tile_size',
         'DEEPZOOM_OVERLAP': 'overlap',
+        'DEEPZOOM_LIMIT_BOUNDS': 'limit_bounds',
     }
     opts = dict((v, app.config[k]) for k, v in config_map.items())
     slide = open_slide(slidefile)
@@ -109,6 +111,9 @@ def slugify(text):
 
 if __name__ == '__main__':
     parser = OptionParser(usage='Usage: %prog [options] [slide]')
+    parser.add_option('-B', '--ignore-bounds', dest='DEEPZOOM_LIMIT_BOUNDS',
+                default=True, action='store_false',
+                help='display entire scan area')
     parser.add_option('-c', '--config', metavar='FILE', dest='config',
                 help='config file')
     parser.add_option('-d', '--debug', dest='DEBUG', action='store_true',

examples/deepzoom/deepzoom_tile.py

@@ -2,7 +2,7 @@
 #
 # deepzoom_tile - Convert whole-slide images to Deep Zoom format
 #
-# Copyright (c) 2010-2013 Carnegie Mellon University
+# Copyright (c) 2010-2014 Carnegie Mellon University
 #
 # 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
@@ -37,13 +37,15 @@
 class TileWorker(Process):
     """A child process that generates and writes tiles."""
 
-    def __init__(self, queue, slidepath, tile_size, overlap, quality):
+    def __init__(self, queue, slidepath, tile_size, overlap, limit_bounds,
+                quality):
         Process.__init__(self, name='TileWorker')
         self.daemon = True
         self._queue = queue
         self._slidepath = slidepath
         self._tile_size = tile_size
         self._overlap = overlap
+        self._limit_bounds = limit_bounds
         self._quality = quality
         self._slide = None
 
@@ -69,7 +71,8 @@ def _get_dz(self, associated=None):
             image = ImageSlide(self._slide.associated_images[associated])
         else:
             image = self._slide
-        return DeepZoomGenerator(image, self._tile_size, self._overlap)
+        return DeepZoomGenerator(image, self._tile_size, self._overlap,
+                    limit_bounds=self._limit_bounds)
 
 
 class DeepZoomImageTiler(object):
@@ -124,7 +127,7 @@ class DeepZoomStaticTiler(object):
     """Handles generation of tiles and metadata for all images in a slide."""
 
     def __init__(self, slidepath, basename, format, tile_size, overlap,
-                quality, workers, with_viewer):
+                limit_bounds, quality, workers, with_viewer):
         if with_viewer:
             # Check extra dependency before doing a bunch of work
             import jinja2
@@ -133,12 +136,14 @@ def __init__(self, slidepath, basename, format, tile_size, overlap,
         self._format = format
         self._tile_size = tile_size
         self._overlap = overlap
+        self._limit_bounds = limit_bounds
         self._queue = JoinableQueue(2 * workers)
         self._workers = workers
         self._with_viewer = with_viewer
         self._dzi_data = {}
         for _i in range(workers):
-            TileWorker(self._queue, slidepath, tile_size, overlap, quality).start()
+            TileWorker(self._queue, slidepath, tile_size, overlap,
+                        limit_bounds, quality).start()
 
     def run(self):
         self._run_image()
@@ -160,7 +165,8 @@ def _run_image(self, associated=None):
         else:
             image = ImageSlide(self._slide.associated_images[associated])
             basename = os.path.join(self._basename, self._slugify(associated))
-        dz = DeepZoomGenerator(image, self._tile_size, self._overlap)
+        dz = DeepZoomGenerator(image, self._tile_size, self._overlap,
+                    limit_bounds=self._limit_bounds)
         tiler = DeepZoomImageTiler(dz, basename, self._format, associated,
                     self._queue)
         tiler.run()
@@ -219,6 +225,9 @@ def _shutdown(self):
 
 if __name__ == '__main__':
     parser = OptionParser(usage='Usage: %prog [options] <slide>')
+    parser.add_option('-B', '--ignore-bounds', dest='limit_bounds',
+                default=True, action='store_false',
+                help='display entire scan area')
     parser.add_option('-e', '--overlap', metavar='PIXELS', dest='overlap',
                 type='int', default=1,
                 help='overlap of adjacent tiles [1]')
@@ -249,5 +258,5 @@ def _shutdown(self):
         opts.basename = os.path.splitext(os.path.basename(slidepath))[0]
 
     DeepZoomStaticTiler(slidepath, opts.basename, opts.format,
-                opts.tile_size, opts.overlap, opts.quality, opts.workers,
-                opts.with_viewer).run()
+                opts.tile_size, opts.overlap, opts.limit_bounds, opts.quality,
+                opts.workers, opts.with_viewer).run()

openslide/deepzoom.py

@@ -1,7 +1,7 @@
 #
 # openslide-python - Python bindings for the OpenSlide library
 #
-# Copyright (c) 2010-2012 Carnegie Mellon University
+# Copyright (c) 2010-2014 Carnegie Mellon University
 #
 # 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
@@ -33,7 +33,12 @@
 class DeepZoomGenerator(object):
     """Generates Deep Zoom tiles and metadata."""
 
-    def __init__(self, osr, tile_size=256, overlap=1):
+    BOUNDS_OFFSET_PROPS = (openslide.PROPERTY_NAME_BOUNDS_X,
+                openslide.PROPERTY_NAME_BOUNDS_Y)
+    BOUNDS_SIZE_PROPS = (openslide.PROPERTY_NAME_BOUNDS_WIDTH,
+                openslide.PROPERTY_NAME_BOUNDS_HEIGHT)
+
+    def __init__(self, osr, tile_size=256, overlap=1, limit_bounds=False):
         """Create a DeepZoomGenerator wrapping an OpenSlide object.
 
         osr:       a slide object.
@@ -52,8 +57,22 @@ def __init__(self, osr, tile_size=256, overlap=1):
         self._z_overlap = overlap
 
         # Precompute dimensions
-        # Slide level
-        self._l_dimensions = osr.level_dimensions
+        # Slide level and offset
+        if limit_bounds:
+            # Level 0 coordinate offset
+            self._l0_offset = tuple(int(osr.properties.get(prop, 0))
+                        for prop in self.BOUNDS_OFFSET_PROPS)
+            # Slide level dimensions scale factor in each axis
+            size_scale = tuple(int(osr.properties.get(prop, l0_lim)) / l0_lim
+                        for prop, l0_lim in zip(self.BOUNDS_SIZE_PROPS,
+                        osr.dimensions))
+            # Dimensions of active area
+            self._l_dimensions = tuple(tuple(int(math.ceil(l_lim * scale))
+                        for l_lim, scale in zip(l_size, size_scale))
+                        for l_size in osr.level_dimensions)
+        else:
+            self._l_dimensions = osr.level_dimensions
+            self._l0_offset = (0, 0)
         self._l0_dimensions = self._l_dimensions[0]
         # Deep Zoom level
         z_size = self._l0_dimensions
@@ -160,9 +179,9 @@ def _get_tile_info(self, dz_level, t_location):
         z_location = [self._z_from_t(t) for t in t_location]
         l_location = [self._l_from_z(dz_level, z - z_tl)
                     for z, z_tl in zip(z_location, z_overlap_tl)]
-        # Round location down and size up
-        l0_location = tuple(int(self._l0_from_l(slide_level, l))
-                    for l in l_location)
+        # Round location down and size up, and add offset of active area
+        l0_location = tuple(int(self._l0_from_l(slide_level, l) + l0_off)
+                    for l, l0_off in zip(l_location, self._l0_offset))
         l_size = tuple(int(min(math.ceil(self._l_from_z(dz_level, dz)),
                     l_lim - math.ceil(l)))
                     for l, dz, l_lim in