TilePyramidGenerator

class TilePyramidGenerator(wsi, tile_size=256, downsample=2, overlap=0)[source]

Generic tile pyramid generator with sensible defaults.

Parameters:

  • wsi (WSIReader) – The WSI reader object. Must implement tiatoolbox.wsicore.wsi_Reader.WSIReader.read_rect.

  • tile_size (int) – The size of tiles to generate. Default is 256. Note that the output tile size will be \(\text{tile size} + 2 \times\text{overlap}\).

  • downsample (int) – The downsample factor between levels. Default is 2.

  • overlap (int) – The number of extra pixel to add to each edge of the tile. Default is 0.

Initialize TilePyramidGenerator.

Methods

dump

Write all tiles to disk.

get_thumb_tile

Return a thumbnail which fits the whole slide in one tile.

get_tile

Get a tile at a given level and coordinate.

level_dimensions

The total pixel dimensions of the tile pyramid at a given level.

level_downsample

Find the downsample factor for a level.

tile_grid_size

Width and height of the minimal grid of tiles to cover the slide.

tile_path

Generate the path for a specified tile.

Attributes

level_count

Number of levels in the tile pyramid.

output_tile_size

The size of the tile which will be returned.

sub_tile_level_count

The number of sub-tile levels in the pyramid.
dump(path, container=None, compression=None)[source]

Write all tiles to disk.

Parameters:

  • path (str or Path) – The path to write the tiles to.

  • container (str) – Container to use. Defaults to None which saves to a directory. Possible values are “zip”, “tar”.

  • compression (str) – Compression method. Defaults to None. Possible values are None, “deflate”, “gzip”, “bz2”, “lzma”. Note that tar does not support deflate and zip does not support gzip.

  • self (TilePyramidGenerator)

Return type:

None

Examples

>>> from tiatoolbox.tools.pyramid import TilePyramidGenerator
>>> from tiatoolbox.wsicore.wsireader import WSIReader
>>> wsi = WSIReader.open("sample.svs")
>>> tile_generator = TilePyramidGenerator(
...   wsi=reader,
...   tile_size=256,
... )
>>> tile_generator.dump(
...    path="sample.gz.zip",
...    container="zip",
...    compression="gzip",
...  )
get_thumb_tile()[source]

Return a thumbnail which fits the whole slide in one tile.

The thumbnail output size has the longest edge equal to the tile size. The other edge preserves the original aspect ratio.

Parameters:

self (TilePyramidGenerator)

Return type:

Image

get_tile(level, x, y, res=1, pad_mode='constant', interpolation='optimise', transparent_value=None)[source]

Get a tile at a given level and coordinate.

Note that levels are in the reverse order of those in WSIReader. I.E. level 0 here corresponds to the lowest resolution whereas level 0 in WSIReader corresponds to the maximum resolution (baseline).

Parameters:

  • level (int) – The pyramid level of the tile starting from 0 (the whole slide in one tile, 0-0-0).

  • x (int) – The tile index in the x direction.

  • y (int) – The tile index in the y direction.

  • res (int) – The resolution of the tile. Defaults to 1, can be set to 2 for double resolution.

  • pad_mode (str) – Method for padding when reading areas outside the input image. Default is constant (0 padding). This is passed to read_func which defaults to safe_padded_read(). See safe_padded_read() for supported pad modes. Setting to “none” or None will result in no padding being applied.

  • interpolation (str) – Interpolation mode to use. Defaults to optimise. Possible values are: linear, cubic, lanczos, nearest, area, optimise. Linear most closely matches OpenSlide.

  • transparent_value (int) – If provided, pixels with this value across all channels will be made transparent. Defaults to None.

  • self (TilePyramidGenerator)

Returns:

Pillow image of the tile.

Return type:

PIL.Image

Example

>>> from tiatoolbox.tools.pyramid import TilePyramidGenerator
>>> from tiatoolbox.wsicore.wsireader import WSIReader
>>> wsi = WSIReader.open("sample.svs")
>>> tile_generator = TilePyramidGenerator(
...   wsi=wsi,
...   tile_size=256,
... )
>>> tile_0_0_0 = tile_generator.get_tile(level=0, x=0, y=0)
property level_count: int

Number of levels in the tile pyramid.

The number of levels is such that level_count - 1 is a 1:1 of the slide baseline resolution (level 0 of the WSI).

level_dimensions(level)[source]

The total pixel dimensions of the tile pyramid at a given level.

Parameters:
Return type:

tuple[int, int]

level_downsample(level)[source]

Find the downsample factor for a level.

Parameters:
Return type:

float

property output_tile_size: int

The size of the tile which will be returned.

This is equivalent to \(\text{tile size} + 2*\text{overlay}\).

property sub_tile_level_count: int

The number of sub-tile levels in the pyramid.

tile_grid_size(level)[source]

Width and height of the minimal grid of tiles to cover the slide.

Parameters:
Return type:

tuple[int, int]

tile_path(level, x, y)[source]

Generate the path for a specified tile.

Parameters:

  • level (int) – The pyramid level of the tile starting from 0 (the whole slide in one tile, 0-0-0).

  • x (int) – The tile index in the x direction.

  • y (int) – The tile index in the y direction.

  • self (TilePyramidGenerator)

Returns:

A pathlib path object with two parts.

Return type:

pathlib.Path