deepzoom: Change default tile size to 254 pixels

For best viewer performance, the total tile size including overlaps
should be a power of 2:

    https://github.com/jcupitt/libvips/pull/359#issuecomment-166433497
    https://github.com/jcupitt/libvips/pull/359#issuecomment-166440011
    https://github.com/jcupitt/libvips/pull/359#issuecomment-166686550

Author: bgilbert

doc/index.rst

@@ -253,14 +253,15 @@ Deep Zoom or a similar format.
 
 .. _`Deep Zoom`: http://msdn.microsoft.com/en-us/library/cc645050%28VS.95%29.aspx
 
-.. class:: DeepZoomGenerator(osr, tile_size=256, overlap=1, limit_bounds=False)
+.. class:: DeepZoomGenerator(osr, tile_size=254, overlap=1, limit_bounds=False)
 
    A Deep Zoom generator that wraps an
    :class:`OpenSlide <openslide.OpenSlide>` or
    :class:`ImageSlide <openslide.ImageSlide>` object.
 
    :param osr: the slide object
-   :param int tile_size: the width and height of a single tile
+   :param int tile_size: the width and height of a single tile.  For best
+      viewer performance, ``tile_size + 2 * overlap`` should be a power of two.
    :param int overlap: the number of extra pixels to add to each interior edge
       of a tile
    :param bool limit_bounds: ``True`` to render only the non-empty slide

examples/deepzoom/deepzoom_multiserver.py

@@ -31,7 +31,7 @@
 SLIDE_DIR = '.'
 SLIDE_CACHE_SIZE = 10
 DEEPZOOM_FORMAT = 'jpeg'
-DEEPZOOM_TILE_SIZE = 256
+DEEPZOOM_TILE_SIZE = 254
 DEEPZOOM_OVERLAP = 1
 DEEPZOOM_LIMIT_BOUNDS = True
 DEEPZOOM_TILE_QUALITY = 75
@@ -194,7 +194,7 @@ def tile(path, level, col, row, format):
                 help='JPEG compression quality [75]')
     parser.add_option('-s', '--size', metavar='PIXELS',
                 dest='DEEPZOOM_TILE_SIZE', type='int',
-                help='tile size [256]')
+                help='tile size [254]')
 
     (opts, args) = parser.parse_args()
     # Load config file if specified

examples/deepzoom/deepzoom_server.py

@@ -29,7 +29,7 @@
 
 DEEPZOOM_SLIDE = None
 DEEPZOOM_FORMAT = 'jpeg'
-DEEPZOOM_TILE_SIZE = 256
+DEEPZOOM_TILE_SIZE = 254
 DEEPZOOM_OVERLAP = 1
 DEEPZOOM_LIMIT_BOUNDS = True
 DEEPZOOM_TILE_QUALITY = 75
@@ -149,7 +149,7 @@ def slugify(text):
                 help='JPEG compression quality [75]')
     parser.add_option('-s', '--size', metavar='PIXELS',
                 dest='DEEPZOOM_TILE_SIZE', type='int',
-                help='tile size [256]')
+                help='tile size [254]')
 
     (opts, args) = parser.parse_args()
     # Load config file if specified

examples/deepzoom/deepzoom_tile.py

@@ -254,8 +254,8 @@ def _shutdown(self):
                 action='store_true',
                 help='generate directory tree with HTML viewer')
     parser.add_option('-s', '--size', metavar='PIXELS', dest='tile_size',
-                type='int', default=256,
-                help='tile size [256]')
+                type='int', default=254,
+                help='tile size [254]')
 
     (opts, args) = parser.parse_args()
     try:

openslide/deepzoom.py

@@ -38,11 +38,13 @@ class DeepZoomGenerator(object):
     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):
+    def __init__(self, osr, tile_size=254, overlap=1, limit_bounds=False):
         """Create a DeepZoomGenerator wrapping an OpenSlide object.
 
         osr:          a slide object.
-        tile_size:    the width and height of a single tile.
+        tile_size:    the width and height of a single tile.  For best viewer
+                      performance, tile_size + 2 * overlap should be a power
+                      of two.
         overlap:      the number of extra pixels to add to each interior edge
                       of a tile.
         limit_bounds: True to render only the non-empty slide region."""