Image Tiling Utils

Minimalistic set of image reader agnostic tools to easily iterate over large images

Installation

Package installation with pip

pip install tiling

Package installation from sources

pip install git+https://github.com/vfdev-5/ImageTilingUtils.git

Examples

For more practical examples, see notebooks.

Quickstart

Constant stride tiles

Let’s iterate over a large image with overlapping tiles of the same size tiles in pixels. At boundaries we add “no-data” pixels.

Let’s assume the data access is provided with an example function

def read_data(x, y, width, height, out_width=None, out_height=None):
    out_width = width if out_width is None else out_width
    out_height = height if out_height is None else out_height
    img.read(x, y, width, height, out_width, out_height)

Thus, overlapping tiles can be extracted as

from tiling import ConstStrideTiles


tiles = ConstStrideTiles(image_size=(500, 500), tile_size=(256, 256), stride=(100, 100),
                         origin=(-100, -100),
                         scale=1.0,
                         include_nodata=True)

print("Number of tiles: %i" % len(tiles))
for extent, out_size in tiles:
    x, y, width, height = extent
    data = read_data(x, y, width, height,
                     out_width=out_size[0],
                     out_height=out_size[1])
    print("data.shape: {}".format(data.shape))

# Access a tile:
i = len(tiles) // 2
extent, out_size  = tiles[i]

There is also an option generate tiles without “nodata” but while keeping stride constant tile size is reduced at bottom and left boundaries.

Constant size tiles

Let’s iterate over a large image with overlapping tiles of the same size in pixels. In this case we prefer to not going outside the input image and fill tiles with nodata. In this situation, overlapping is not constant.

Let’s assume the data access is provided with an example function

def read_data(x, y, width, height, out_width=None, out_height=None):
    out_width = width if out_width is None else out_width
    out_height = height if out_height is None else out_height
    img.read(x, y, width, height, out_width, out_height)

Thus, overlapping tiles can be extracted as

from tiling import ConstSizeTiles

tiles = ConstSizeTiles(image_size=(500, 500), tile_size=(256, 256), min_overlapping=15, scale=1.0)

print("Number of tiles: %i" % len(tiles))
for extent, out_size in tiles:
    assert out_size[0] == tiles.tile_size[0]
    assert out_size[1] == tiles.tile_size[1]
    x, y, width, height = extent
    data = read_data(x, y, width, height,
                     out_width=out_size[0],
                     out_height=out_size[1])
    print("data.shape: {}".format(data.shape))

# Access a tile:
i = len(tiles) // 2
extent  = tiles[i]

tiling.const_stride

Class provides tile parameters (offset, extent) to extract data from image.

Generated tile extents starts from an origin, has constant stride and can optionally include nodata paddings. For example, tiling can look like this (origin is negative, include nodata)

   tile 0        tile 2      tile 4
   |<------->|   |<------>|  |<------>|     etc
             tile 1      tile 3      tile 5     tile n-1
   ^      |<------->|  |<------>|  |<------>| |<------>|
   |        |<------------------------------------>|
origin      |                IMAGE                 |
            |                                      |

Another example, tiling can look like this (origin is negative, no nodata, tile size is not constant at boundaries)

           tile 0    tile 2      tile 4
           |<->|   |<------>|  |<------>|     etc
             tile 1      tile 3      tile 5     tile n-1
   ^       |<------>|  |<------>|  |<------>| |<->|
   |       |<------------------------------------>|
origin     |                IMAGE                 |
           |                                      |

Another example, tiling can look like this (origin is postive, no nodata, tile size is not constant at boundaries)

      tile 0        tile 2
    |<------->|   |<------>|      etc
              tile 1      tile 3      tile n-1
    ^      |<------->|  |<------>|  |<-->|
|<-------------------------------------->|
|   |            IMAGE                   |
| origin                                 |

Basic usage:

from tiling import ConstStrideTiles

tiles = ConstStrideTiles(image_size=(500, 500), tile_size=(256, 256), stride=(100, 100))

print("Number of tiles: %i" % len(tiles))
for (x, y, width, height), (out_width, out_height) in tiles:
    data = read_data(x, y, width, height, out_width, out_height)
    print("data.shape: {}".format(data.shape))

# Get a tile params at linear index:
extent, out_size = tiles[len(tiles)//2]

class tiling.const_stride.ConstStrideTiles(image_size, tile_size, stride=(1, 1), scale=1.0, origin=(0, 0), include_nodata=True)

Class provides tile parameters (offset, extent) to extract data from image.

Examples

from tiling import ConstStrideTiles

tiles = ConstStrideTiles(image_size=(500, 500), tile_size=(256, 256), stride=(100, 100),
                         origin=(-100, -100),
                         scale=1.0,
                         include_nodata=True)

print("Number of tiles: %i" % len(tiles))
for extent, out_size in tiles:
    x, y, width, height = extent
    data = read_data(x, y, width, height,
                     out_width=out_size[0],
                     out_height=out_size[1])
    print("data.shape: {}".format(data.shape))

Parameters:

• image_size (list/tuple of int) – input image size in pixels (width, height)
• tile_size (int or list/tuple of int) – output tile size in pixels (width, height)
• stride (list/tuple of int) – horizontal and vertical strides in pixels. Values need to be positive larger than 1 pixel. Stride value is impacted with scale and corresponds to a sliding over scaled image.
• scale (float) – Scaling applied to the input image parameters before extracting tile’s extent
• origin (list or tuple of int) – point in pixels in the original image from where to start the tiling. Values can be positive or negative.
• include_nodata (bool) – Include or not nodata. If nodata is included then tile extents have all the same size, otherwise tiles at boundaries will be reduced

next()

Method to get next tile

Returns:tile data (ndarray), tile extent (list) in the original image, in pixels

tiling.const_size

Class provides constant size tile parameters (offset, extent) to extract data from image.

Generated tile extents can overlap, do not includes nodata paddings. For example, tiling can look like this:

  tile 0      tile 2      tile 4
|<------>|  |<------>|  |<------>|
        tile 1      tile 3      tile 5
      |<------>|  |<------>|  |<------>|
|<------------------------------------>|
|                IMAGE                 |
|                                      |

Basic usage:

from tiling import ConstSizeTiles

tiles = ConstSizeTiles(image_size=(500, 500), tile_size=(256, 256), min_overlapping=100)

print("Number of tiles: %i" % len(tiles))
for x, y, width, height in tiles:
    data = read_data(x, y, width, height, tiles.tile_size[0], tiles.tile_size[0])
    print("data.shape: {}".format(data.shape))

class tiling.const_size.ConstSizeTiles(image_size, tile_size, min_overlapping=0, scale=1.0)

Class provides constant size tile parameters (offset, extent) to extract data from image. Generated tile extents can overlap and do not includes nodata paddings.

Examples

from tiling import ConstSizeTiles

tiles = ConstSizeTiles(image_size=(500, 500), tile_size=(256, 256), min_overlapping=15, scale=1.0)

print("Number of tiles: %i" % len(tiles))
for extent, out_size in tiles:
    x, y, width, height = extent
    data = read_data(x, y, width, height,
                     out_width=out_size[0],
                     out_height=out_size[1])
    print("data.shape: {}".format(data.shape))

Parameters:

• image_size (list/tuple of int) – input image size in pixels (width, height)
• tile_size (int or list/tuple of int) – output tile size in pixels (width, height)
• min_overlapping (int) – minimal overlapping in pixels between tiles.
• scale (float) – Scaling applied to the input image parameters before extracting tile’s extent

next()

Method to get next tile

Returns:tile data (ndarray), tile extent (list) in the original image, in pixels