WSIReader

tiatoolbox . wsicore . wsireader . WSIReader

class WSIReader(input_img, mpp=None, power=None)

Base whole slide image (WSI) reader class.

This class defines functions for reading pixel data and metadata from whole slide image (WSI) files.

input_img

Input path to WSI file.

Type

pathlib.Path

Parameters

• input_img (str or pathlib.Path or numpy.ndarray) – Input path to WSI.

• mpp (tuple or list or None, optional) – The MPP of the WSI. If not provided, the MPP is approximated from the objective power.

• power (float or None, optional) – The objective power of the WSI. If not provided, the power is approximated from the MPP.

Return type

None

Methods

convert_resolution_units	Converts resolution value between different units.
find_read_rect_params	Find optimal parameters for reading a rect at a given resolution.
open	Return an appropriate WSIReader object.
read_bounds	Read a region of the whole slide image within given bounds.
read_rect	Read a region of the whole slide image at a location and size.
read_region	Read a region of the whole slide image (OpenSlide format args).
save_tiles	Generate image tiles from whole slide images.
slide_dimensions	Return the size of WSI at requested resolution.
slide_thumbnail	Read the whole slide image thumbnail (1.25x by default).
tissue_mask	Create a tissue mask and wrap it in a VirtualWSIReader.

Attributes

info	WSI metadata property.

convert_resolution_units(input_res, input_unit, output_unit=None)

Converts resolution value between different units.

This function accepts a resolution and its units in the input and converts it to all other units (‘mpp’, ‘power’, ‘baseline’). To achieve resolution in ‘mpp’ and ‘power’ units in theoutput, WSI meta data should cotain mpp and objective_power information, respectively.

Parameters

• input_res (float) – the resolution which we want to convert to

• units. (the other) –

• input_unit (str) – the unit of the input resolution (input_res). Acceptable

• 'mpp' (input_units are) –

• 'power' –

• 'baseline' –

• 'level'. (and) –

• output_unit (str) – the desired unit to which we want to convert

• are (the input_res. Acceptable values for output_unit) – ‘mpp’,

• 'power' –

• provided (and 'baseline'. If output_unit is not) –

• of (all) –

• a (the conversions to all of the mentioned units will be returned in) –

• dictionary. –

Returns

either a float which is the converted input_res to the desired output_unit or a dictionary containing the converted input_res to all acceptable units (‘mpp’, ‘power’, ‘baseline’). If there is not enough meta data to calculate a unit (like mpp or power), they will be set to None in the dictionary.

Return type

output_res (float or dictionary)

find_read_rect_params(location, size, resolution, units, precision=3)

Find optimal parameters for reading a rect at a given resolution.

Reading the image at full baseline resolution and re-sampling to the desired resolution would require a large amount of memory and be very slow. This function checks the other resolutions stored in the WSI’s pyramid of resolutions to find the lowest resolution (smallest level) which is higher resolution (a larger level) than the requested output resolution.

In addition to finding this ‘optimal level’, the scale factor to apply after reading in order to obtain the desired resolution is found along with conversions of the location and size into level and baseline coordinates.

Parameters

• location (tuple(int)) – Location in terms of the baseline image (level 0) resolution.

• size (tuple(int)) – Desired output size in pixels (width, height) tuple.

• resolution (float) – Desired output resolution.

• units (str) – Units of scale, default = “level”. Supported units are: - microns per pixel (‘mpp’) - objective power (‘power’) - pyramid / resolution level (‘level’) - pixels per baseline pixel (“baseline”)

• precision (int, optional) – Decimal places to use when finding optimal scale. See find_optimal_level_and_downsample() for more.

Returns

Parameters for reading the requested region - int - Optimal read level - tuple - Read location in level coordinates

• int - X location

• int - Y location

• tuple - Region size in level coordinates

  • int - Width

  • int - Height

• tuple - Scaling to apply after level read to achieve desired output resolution.

  • float - X scale factor

  • float - Y scale factor

• tuple - Region size in baseline coordinates

  • int - Width

  • int - Height

Return type

tuple

property info: tiatoolbox.wsicore.wsimeta.WSIMeta

WSI metadata property.

This property is cached and only generated on the first call.

Returns

An object containing normalized slide metadata

Return type

WSIMeta

static open(input_img, mpp=None, power=None)

Return an appropriate WSIReader object.

Parameters

• (str (input_img) – obj:WSIReader): Input to create a WSI object from. Supported types of input are: str and pathlib.Path which point to the location on the disk where image is stored, numpy.ndarray in which the input image in the form of numpy array (HxWxC) is stored, or :obj:WSIReader which is an already created tiatoolbox WSI handler. In the latter case, the function directly passes the input_imge to the output.

• pathlib.Path – obj:WSIReader): Input to create a WSI object from. Supported types of input are: str and pathlib.Path which point to the location on the disk where image is stored, numpy.ndarray in which the input image in the form of numpy array (HxWxC) is stored, or :obj:WSIReader which is an already created tiatoolbox WSI handler. In the latter case, the function directly passes the input_imge to the output.

• input_img (Union[str, pathlib.Path, numpy.ndarray]) –

• mpp (Optional[Tuple[numbers.Number, numbers.Number]]) –

• power (Optional[numbers.Number]) –

Return type

tiatoolbox.wsicore.wsireader.WSIReader

:param numpy.ndarray: obj:WSIReader):

Input to create a WSI object from. Supported types of input are: str and pathlib.Path which point to the location on the disk where image is stored, numpy.ndarray in which the input image in the form of numpy array (HxWxC) is stored, or :obj:WSIReader which is an already created tiatoolbox WSI handler. In the latter case, the function directly passes the input_imge to the output.

Parameters

• or – obj:WSIReader): Input to create a WSI object from. Supported types of input are: str and pathlib.Path which point to the location on the disk where image is stored, numpy.ndarray in which the input image in the form of numpy array (HxWxC) is stored, or :obj:WSIReader which is an already created tiatoolbox WSI handler. In the latter case, the function directly passes the input_imge to the output.

• mpp (tuple) – (x, y) tuple of the MPP in the units of the input image.

• power (float) – Objective power of the input image.

• input_img (Union[str, pathlib.Path, numpy.ndarray]) –

Returns

an object with base WSIReader as base class.

Return type

WSIReader

Examples

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> wsi = get_wsireader(input_img="./sample.svs")

read_bounds(bounds, resolution=0, units='level', interpolation='optimise', pad_mode='constant', pad_constant_values=0, coord_space='baseline', **kwargs)

Read a region of the whole slide image within given bounds.

Bounds are in terms of the baseline image (level 0 / maximum resolution).

Reads can be performed at different resolutions by supplying a pair of arguments for the resolution and the units of resolution. If meta data does not specify mpp or objective_power then baseline units should be selected with resolution 1.0

The output image size may be different to the width and height of the bounds as the resolution will affect this. To read a region with a fixed output image size see read_rect().

Parameters

• bounds (tuple(int)) – By default, this is a tuple of (start_x, start_y, end_x, end_y) i.e. (left, top, right, bottom) of the region in baseline reference frame. However, with coord_space=”resolution”, the bound is expected to be at the requested resolution system.

• resolution (int or float or tuple(float)) – resolution at which to read the image, default = 0. Either a single number or a sequence of two numbers for x and y are valid. This value is in terms of the corresponding units. For example: resolution=0.5 and units=”mpp” will read the slide at 0.5 microns per-pixel, and resolution=3, units=”level” will read at level at pyramid level / resolution layer 3.

• units (str) – the units of resolution, default = “level”. Supported units are: microns per pixel (mpp), objective power (power), pyramid / resolution level (level), pixels per baseline pixel (baseline).

• interpolation (str) – Method to use when resampling the output image. Possible values are “linear”, “cubic”, “lanczos”, “area”, and “optimse”. Defaults to ‘optimise’ which will use cubic interpolation for upscaling and area interpolation for downscaling to avoid moiré patterns.

• pad_mode (str) – Method to use when padding at the edges of the image. Defaults to ‘constant’. See numpy.pad() for available modes.

• coord_space (str) – default to “baseline”, this is a flag to indicate if the input bounds is in the baseline coordinate system (“baseline”) or is in the requested resolution system (“resolution”).

• **kwargs (dict) – Extra key-word arguments for reader specific parameters. Currently only used by VirtualWSIReader. See class docstrings for more information.

• pad_constant_values (Union[numbers.Number, Iterable[Tuple[numbers.Number, numbers.Number]]]) –

Returns

array of size MxNx3 M=end_h-start_h, N=end_w-start_w

Return type

numpy.ndarray

Examples

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> from matplotlib import pyplot as plt
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> # Read a region at level 0 (baseline / full resolution)
>>> bounds = [1000, 2000, 2000, 3000]
>>> img = wsi.read_bounds(bounds)
>>> plt.imshow(img)
>>> # This could also be written more verbosely as follows
>>> img = wsi.read_bounds(
...     bounds,
...     resolution=0,
...     units="level",
... )
>>> plt.imshow(img)

Note: The field of view remains the same as resolution is varied when using read_bounds().

This is because the bounds are in the baseline (level 0) reference frame. Therefore, varying the resolution does not change what is visible within the output image.

If the WSI does not have a resolution layer corresponding exactly to the requested resolution (shown above in white with a dashed outline), a larger resolution is downscaled to achieve the correct requested output resolution.

If the requested resolution is higher than the baseline (maximum resultion of the image), then bicubic interpolation is applied to the output image.

read_rect(location, size, resolution=0, units='level', interpolation='optimise', pad_mode='constant', pad_constant_values=0, coord_space='baseline', **kwargs)

Read a region of the whole slide image at a location and size.

Location is in terms of the baseline image (level 0 / maximum resolution), and size is the output image size.

Reads can be performed at different resolutions by supplying a pair of arguments for the resolution and the units of resolution. If meta data does not specify mpp or objective_power then baseline units should be selected with resolution 1.0

The field of view varies with resolution. For a fixed field of view see read_bounds().

Parameters

• location (tuple(int)) – (x, y) tuple giving the top left pixel in the baseline (level 0) reference frame.

• size (tuple(int)) – (width, height) tuple giving the desired output image size.

• resolution (int or float or tuple(float)) – resolution at which to read the image, default = 0. Either a single number or a sequence of two numbers for x and y are valid. This value is in terms of the corresponding units. For example: resolution=0.5 and units=”mpp” will read the slide at 0.5 microns per-pixel, and resolution=3, units=”level” will read at level at pyramid level / resolution layer 3.

• units (str) – the units of resolution, default = “level”. Supported units are: microns per pixel (mpp), objective power (power), pyramid / resolution level (level), pixels per baseline pixel (baseline).

• interpolation (str) – Method to use when resampling the output image. Possible values are “linear”, “cubic”, “lanczos”, “area”, and “optimse”. Defaults to ‘optimise’ which will use cubic interpolation for upscaling and area interpolation for downscaling to avoid moiré patterns.

• pad_mode (str) – Method to use when padding at the edges of the image. Defaults to ‘constant’. See numpy.pad() for available modes.

• coord_space (str) – default to “baseline”, this is a flag to indicate if the input bounds is in the baseline coordinate system (“baseline”) or is in the requested resolution system (“resolution”).

• **kwargs (dict) – Extra key-word arguments for reader specific parameters. Currently only used by VirtualWSIReader. See class docstrings for more information.

• pad_constant_values (Union[numbers.Number, Iterable[Tuple[numbers.Number, numbers.Number]]]) –

Returns

array of size MxNx3 M=size[0], N=size[1]

Return type

numpy.ndarray

Example

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> # Load a WSI image
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> location = (0, 0)
>>> size = (256, 256)
>>> # Read a region at level 0 (baseline / full resolution)
>>> img = wsi.read_rect(location, size)
>>> # Read a region at 0.5 microns per pixel (mpp)
>>> img = wsi.read_rect(location, size, 0.5, "mpp")
>>> # This could also be written more verbosely as follows
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=(0.5, 0.5),
...     units="mpp",
... )

Note: The field of view varies with resolution when using read_rect().

As the location is in the baseline reference frame but the size (width and height) is the output image size, the field of view therefore changes as resolution changes.

If the WSI does not have a resolution layer corresponding exactly to the requested resolution (shown above in white with a dashed outline), a larger resolution is downscaled to achieve the correct requested output resolution.

If the requested resolution is higher than the baseline (maximum resultion of the image), then bicubic interpolation is applied to the output image.

When reading between the levels stored in the WSI, the coordinates of the requested region are projected to the next highest resolution. This resolution is then decoded and downsampled to produced the desired output. This is a major source of variability in the time take to perform a read operation. Reads which require reading a large region before downsampling will be significantly slower than reading at a fixed level.

Examples

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> # Load a WSI image
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> location = (0, 0)
>>> size = (256, 256)
>>> # The resolution can be different in x and y, e.g.
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=(0.5, 0.75),
...     units="mpp",
... )
>>> # Several units can be used including: objective power,
>>> # microns per pixel, pyramid/resolution level, and
>>> # fraction of baseline.
>>> # E.g. Read a region at an objective power of 10x
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=10,
...     units="power",
... )
>>> # Read a region at pyramid / resolution level 1
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=1,
...     units="level",
... )
>>> # Read at a fractional level, this will linearly
>>> # interpolate the downsampling factor between levels.
>>> # E.g. if levels 0 and 1 have a downsampling of 1x and
>>> # 2x of baseline, then level 0.5 will correspond to a
>>> # downsampling factor 1.5x of baseline.
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=0.5,
...     units="level",
... )
>>> # Read a region at half of the full / baseline
>>> # resolution.
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=0.5,
...     units="baseline",
... )
>>> # Read at a higher resolution than the baseline
>>> # (interpolation applied to output)
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=1.25,
...     units="baseline",
... )
>>> # Assuming the image has a native mpp of 0.5,
>>> # interpolation will be applied here.
>>> img = wsi.read_rect(
...     location,
...     size,
...     resolution=0.25,
...     units="mpp",
... )

read_region(location, level, size)

Read a region of the whole slide image (OpenSlide format args).

This function is to help with writing code which is backwards compatible with OpenSlide. As such, it has the same arguments.

This internally calls read_rect() which should be implemented by any WSIReader subclass. Therefore, some WSI formats which are not supported by OpenSlide, such as Omnyx JP2 files, may also be readable with the same syntax.

Parameters

• location (tuple(int)) – (x, y) tuple giving the top left pixel in the level 0 reference frame.

• level (int) – the level number.

• size (tuple(int)) – (width, height) tuple giving the region size.

Returns

array of size MxNx3.

Return type

numpy.ndarray

save_tiles(output_dir, tile_objective_value, tile_read_size, tile_format='.jpg', verbose=True)

Generate image tiles from whole slide images.

Parameters

• output_dir (str or pathlib.Path) – Output directory to save the tiles.

• tile_objective_value (int) – Objective value at which tile is generated.

• tile_read_size (tuple(int)) – Tile (width, height).

• tile_format (str) – File format to save image tiles, defaults to “.jpg”.

• verbose (bool) – Print output, default to True.

Return type

None

Examples

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> wsi.save_tiles(output_dir='./dev_test',
...     tile_objective_value=10,
...     tile_read_size=(2000, 2000))

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> slide_param = wsi.info

slide_dimensions(resolution, units, precisions=3)

Return the size of WSI at requested resolution.

Parameters

• resolution (int or float or tuple(float)) – resolution to read thumbnail at, default = 1.25 (objective power)

• units (str) – resolution units, default = “power”

• precisions (int) –

Returns

shape of WSI in (width, height).

Return type

tuple

Examples

>>> from tiatoolbox.wsicore import wsireader
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> slide_shape = wsi.slide_dimensions(0.55, 'mpp')

slide_thumbnail(resolution=1.25, units='power')

Read the whole slide image thumbnail (1.25x by default).

For more information on resolution and units see read_rect()

Parameters

• resolution (int or float or tuple(float)) – resolution to read thumbnail at, default = 1.25 (objective power)

• units (str) – resolution units, default = “power”

Returns

thumbnail image

Return type

numpy.ndarray

Examples

>>> from tiatoolbox.wsicore.wsireader import get_wsireader
>>> wsi = get_wsireader(input_img="./CMU-1.ndpi")
>>> slide_thumbnail = wsi.slide_thumbnail()

tissue_mask(method='otsu', resolution=1.25, units='power', **masker_kwargs)

Create a tissue mask and wrap it in a VirtualWSIReader.

For the morphological method, mpp is used for calculating the scale of the morphological operations. If no mpp is available, objective power is used instead to estimate a good scale. This can be overridden with a custom size, via passing a kernel_size key-word argument in masker_kwargs, see tissuemask.MorphologicalMasker for more.

Parameters

• method (str) – Method to use for creating the mask. Defaults to ‘otsu’. Methods are: otsu, morphological.

• resolution (float) – Resolution to produce the mask at. Defaults to 1.25.

• units (str) – Units of resolution. Defaults to ‘power’.

• **masker_kwargs – Extra kwargs passed to the masker class.

Return type

tiatoolbox.wsicore.wsireader.VirtualWSIReader