Rename "layer" to "level" to match OpenSlide terminology changes

Author: bgilbert

openslide/__init__.py

@@ -60,27 +60,27 @@ def close(self):
         raise NotImplementedError
 
     @property
-    def layer_count(self):
-        """The number of layers in the image."""
+    def level_count(self):
+        """The number of levels in the image."""
         raise NotImplementedError
 
     @property
-    def layer_dimensions(self):
-        """A list of (width, height) tuples, one for each layer of the image.
+    def level_dimensions(self):
+        """A list of (width, height) tuples, one for each level of the image.
 
-        layer_dimensions[n] contains the dimensions of layer n."""
+        level_dimensions[n] contains the dimensions of level n."""
         raise NotImplementedError
 
     @property
     def dimensions(self):
-        """A (width, height) tuple for layer 0 of the image."""
-        return self.layer_dimensions[0]
+        """A (width, height) tuple for level 0 of the image."""
+        return self.level_dimensions[0]
 
     @property
-    def layer_downsamples(self):
-        """A list of downsampling factors for each layer of the image.
+    def level_downsamples(self):
+        """A list of downsampling factors for each level of the image.
 
-        layer_downsample[n] contains the downsample factor of layer n."""
+        level_downsample[n] contains the downsample factor of level n."""
         raise NotImplementedError
 
     @property
@@ -97,16 +97,16 @@ def associated_images(self):
         This is a map: image name -> PIL.Image."""
         raise NotImplementedError
 
-    def get_best_layer_for_downsample(self, downsample):
-        """Return the best layer for displaying the given downsample."""
+    def get_best_level_for_downsample(self, downsample):
+        """Return the best level for displaying the given downsample."""
         raise NotImplementedError
 
-    def read_region(self, location, layer, size):
+    def read_region(self, location, level, size):
         """Return a PIL.Image containing the contents of the region.
 
-        location: (x, y) tuple giving the top left pixel in the layer 0
+        location: (x, y) tuple giving the top left pixel in the level 0
                   reference frame.
-        layer:    the layer number.
+        level:    the level number.
         size:     (width, height) tuple giving the region size."""
         raise NotImplementedError
 
@@ -116,8 +116,8 @@ def get_thumbnail(self, size):
         size:     the maximum size of the thumbnail."""
         downsample = max(*[dim / thumb for dim, thumb in
                 zip(self.dimensions, size)])
-        layer = self.get_best_layer_for_downsample(downsample)
-        tile = self.read_region((0, 0), layer, self.layer_dimensions[layer])
+        level = self.get_best_level_for_downsample(downsample)
+        tile = self.read_region((0, 0), level, self.level_dimensions[level])
         # Apply on solid background
         bg_color = '#' + self.properties.get(PROPERTY_NAME_BACKGROUND_COLOR,
                 'ffffff')
@@ -154,25 +154,25 @@ def close(self):
         lowlevel.close(self._osr)
 
     @property
-    def layer_count(self):
-        """The number of layers in the image."""
-        return lowlevel.get_layer_count(self._osr)
+    def level_count(self):
+        """The number of levels in the image."""
+        return lowlevel.get_level_count(self._osr)
 
     @property
-    def layer_dimensions(self):
-        """A list of (width, height) tuples, one for each layer of the image.
+    def level_dimensions(self):
+        """A list of (width, height) tuples, one for each level of the image.
 
-        layer_dimensions[n] contains the dimensions of layer n."""
-        return tuple(lowlevel.get_layer_dimensions(self._osr, i)
-                for i in range(self.layer_count))
+        level_dimensions[n] contains the dimensions of level n."""
+        return tuple(lowlevel.get_level_dimensions(self._osr, i)
+                for i in range(self.level_count))
 
     @property
-    def layer_downsamples(self):
-        """A list of downsampling factors for each layer of the image.
+    def level_downsamples(self):
+        """A list of downsampling factors for each level of the image.
 
-        layer_downsample[n] contains the downsample factor of layer n."""
-        return tuple(lowlevel.get_layer_downsample(self._osr, i)
-                for i in range(self.layer_count))
+        level_downsample[n] contains the downsample factor of level n."""
+        return tuple(lowlevel.get_level_downsample(self._osr, i)
+                for i in range(self.level_count))
 
     @property
     def properties(self):
@@ -191,22 +191,22 @@ def associated_images(self):
         are not premultiplied."""
         return _AssociatedImageMap(self._osr)
 
-    def get_best_layer_for_downsample(self, downsample):
-        """Return the best layer for displaying the given downsample."""
-        return lowlevel.get_best_layer_for_downsample(self._osr, downsample)
+    def get_best_level_for_downsample(self, downsample):
+        """Return the best level for displaying the given downsample."""
+        return lowlevel.get_best_level_for_downsample(self._osr, downsample)
 
-    def read_region(self, location, layer, size):
+    def read_region(self, location, level, size):
         """Return a PIL.Image containing the contents of the region.
 
-        location: (x, y) tuple giving the top left pixel in the layer 0
+        location: (x, y) tuple giving the top left pixel in the level 0
                   reference frame.
-        layer:    the layer number.
+        level:    the level number.
         size:     (width, height) tuple giving the region size.
 
         Unlike in the C interface, the image data returned by this
         function is not premultiplied."""
         return lowlevel.read_region(self._osr, location[0], location[1],
-                layer, size[0], size[1])
+                level, size[0], size[1])
 
 
 class _OpenSlideMap(Mapping):
@@ -274,22 +274,22 @@ def close(self):
         self._image = None
 
     @property
-    def layer_count(self):
-        """The number of layers in the image."""
+    def level_count(self):
+        """The number of levels in the image."""
         return 1
 
     @property
-    def layer_dimensions(self):
-        """A list of (width, height) tuples, one for each layer of the image.
+    def level_dimensions(self):
+        """A list of (width, height) tuples, one for each level of the image.
 
-        layer_dimensions[n] contains the dimensions of layer n."""
+        level_dimensions[n] contains the dimensions of level n."""
         return (self._image.size,)
 
     @property
-    def layer_downsamples(self):
-        """A list of downsampling factors for each layer of the image.
+    def level_downsamples(self):
+        """A list of downsampling factors for each level of the image.
 
-        layer_downsample[n] contains the downsample factor of layer n."""
+        level_downsample[n] contains the downsample factor of level n."""
         return (1.0,)
 
     @property
@@ -306,19 +306,19 @@ def associated_images(self):
         This is a map: image name -> PIL.Image."""
         return {}
 
-    def get_best_layer_for_downsample(self, _downsample):
-        """Return the best layer for displaying the given downsample."""
+    def get_best_level_for_downsample(self, _downsample):
+        """Return the best level for displaying the given downsample."""
         return 0
 
-    def read_region(self, location, layer, size):
+    def read_region(self, location, level, size):
         """Return a PIL.Image containing the contents of the region.
 
-        location: (x, y) tuple giving the top left pixel in the layer 0
+        location: (x, y) tuple giving the top left pixel in the level 0
                   reference frame.
-        layer:    the layer number.
+        level:    the level number.
         size:     (width, height) tuple giving the region size."""
-        if layer != 0:
-            raise OpenSlideError("Invalid layer")
+        if level != 0:
+            raise OpenSlideError("Invalid level")
         if ['fail' for s in size if s < 0]:
             raise OpenSlideError("Size %s must be non-negative" % (size,))
         # Any corner of the requested region may be outside the bounds of
@@ -358,8 +358,8 @@ def open_slide(filename):
     print "PIL can open:", ImageSlide.can_open(sys.argv[1])
     with open_slide(sys.argv[1]) as _slide:
         print "Dimensions:", _slide.dimensions
-        print "Layers:", _slide.layer_count
-        print "Layer dimensions:", _slide.layer_dimensions
-        print "Layer downsamples:", _slide.layer_downsamples
+        print "Levels:", _slide.level_count
+        print "Level dimensions:", _slide.level_dimensions
+        print "Level downsamples:", _slide.level_downsamples
         print "Properties:", _slide.properties
         print "Associated images:", _slide.associated_images

openslide/deepzoom.py

@@ -1,7 +1,7 @@
 #
 # openslide-python - Python bindings for the OpenSlide library
 #
-# Copyright (c) 2010-2011 Carnegie Mellon University
+# Copyright (c) 2010-2012 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
@@ -44,18 +44,18 @@ def __init__(self, osr, tile_size=256, overlap=1):
         # We have four coordinate planes:
         # - Row and column of the tile within the Deep Zoom level (t_)
         # - Pixel coordinates within the Deep Zoom level (z_)
-        # - Pixel coordinates within the slide layer (l_)
-        # - Pixel coordinates within slide layer 0 (l0_)
+        # - Pixel coordinates within the slide level (l_)
+        # - Pixel coordinates within slide level 0 (l0_)
 
         self._osr = osr
         self._z_t_downsample = tile_size
         self._z_overlap = overlap
 
         # Precompute dimensions
-        # Layer
-        self._l_dimensions = osr.layer_dimensions
+        # Slide level
+        self._l_dimensions = osr.level_dimensions
         self._l0_dimensions = self._l_dimensions[0]
-        # Level
+        # Deep Zoom level
         z_size = self._l0_dimensions
         z_dimensions = [z_size]
         while z_size[0] > 1 or z_size[1] > 1:
@@ -67,24 +67,24 @@ def __init__(self, osr, tile_size=256, overlap=1):
         self._t_dimensions = tuple((tiles(z_w), tiles(z_h))
                     for z_w, z_h in self._z_dimensions)
 
-        # Level count
-        self._levels = len(self._z_dimensions)
+        # Deep Zoom level count
+        self._dz_levels = len(self._z_dimensions)
 
-        # Total downsamples for each level
-        l0_z_downsamples = tuple(2 ** (self._levels - level - 1)
-                    for level in xrange(self._levels))
+        # Total downsamples for each Deep Zoom level
+        l0_z_downsamples = tuple(2 ** (self._dz_levels - dz_level - 1)
+                    for dz_level in xrange(self._dz_levels))
 
-        # Preferred layers for each level
-        self._layer_from_level = tuple(
-                    self._osr.get_best_layer_for_downsample(d)
+        # Preferred slide levels for each Deep Zoom level
+        self._slide_from_dz_level = tuple(
+                    self._osr.get_best_level_for_downsample(d)
                     for d in l0_z_downsamples)
 
         # Piecewise downsamples
-        self._l0_l_downsamples = self._osr.layer_downsamples
+        self._l0_l_downsamples = self._osr.level_downsamples
         self._l_z_downsamples = tuple(
-                    l0_z_downsamples[level] /
-                    self._l0_l_downsamples[self._layer_from_level[level]]
-                    for level in range(self._levels))
+                    l0_z_downsamples[dz_level] /
+                    self._l0_l_downsamples[self._slide_from_dz_level[dz_level]]
+                    for dz_level in range(self._dz_levels))
 
         # Slide background color
         self._bg_color = '#' + self._osr.properties.get(
@@ -93,7 +93,7 @@ def __init__(self, osr, tile_size=256, overlap=1):
     @property
     def level_count(self):
         """The number of Deep Zoom levels in the image."""
-        return self._levels
+        return self._dz_levels
 
     @property
     def level_tiles(self):
@@ -131,50 +131,51 @@ def get_tile(self, level, address):
 
         return tile
 
-    def _get_tile_info(self, level, t_location):
+    def _get_tile_info(self, dz_level, t_location):
         # Check parameters
-        if level < 0 or level >= self._levels:
+        if dz_level < 0 or dz_level >= self._dz_levels:
             raise ValueError("Invalid level")
-        for t, t_lim in zip(t_location, self._t_dimensions[level]):
+        for t, t_lim in zip(t_location, self._t_dimensions[dz_level]):
             if t < 0 or t >= t_lim:
                 raise ValueError("Invalid address")
 
-        # Get preferred layer
-        layer = self._layer_from_level[level]
+        # Get preferred slide level
+        slide_level = self._slide_from_dz_level[dz_level]
 
         # Calculate top/left and bottom/right overlap
         z_overlap_tl = tuple(self._z_overlap * int(t != 0)
                     for t in t_location)
         z_overlap_br = tuple(self._z_overlap * int(t != t_lim - 1)
-                    for t, t_lim in zip(t_location, self.level_tiles[level]))
+                    for t, t_lim in
+                    zip(t_location, self.level_tiles[dz_level]))
 
         # Get final size of the tile
         z_size = tuple(min(self._z_t_downsample,
                     z_lim - self._z_t_downsample * t) + z_tl + z_br
                     for t, z_lim, z_tl, z_br in
-                    zip(t_location, self._z_dimensions[level], z_overlap_tl,
-                    z_overlap_br))
+                    zip(t_location, self._z_dimensions[dz_level],
+                    z_overlap_tl, z_overlap_br))
 
         # Obtain the region coordinates
         z_location = [self._z_from_t(t) for t in t_location]
-        l_location = [self._l_from_z(level, z) - z_tl
+        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(layer, l))
+        l0_location = tuple(int(self._l0_from_l(slide_level, l))
                     for l in l_location)
-        l_size = tuple(int(min(math.ceil(self._l_from_z(level, dz)),
+        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
-                    zip(l_location, z_size, self._l_dimensions[layer]))
+                    zip(l_location, z_size, self._l_dimensions[slide_level]))
 
         # Return read_region() parameters plus tile size for final scaling
-        return ((l0_location, layer, l_size), z_size)
+        return ((l0_location, slide_level, l_size), z_size)
 
-    def _l0_from_l(self, layer, l):
-        return self._l0_l_downsamples[layer] * l
+    def _l0_from_l(self, slide_level, l):
+        return self._l0_l_downsamples[slide_level] * l
 
-    def _l_from_z(self, level, z):
-        return self._l_z_downsamples[level] * z
+    def _l_from_z(self, dz_level, z):
+        return self._l_z_downsamples[dz_level] * z
 
     def _z_from_t(self, t):
         return self._z_t_downsample * t