TransformedWSIReader

tiatoolbox . wsicore . wsireader . TransformedWSIReader

class TransformedWSIReader(input_img, target_img, mpp=None, power=None, transform=None, fixed_info=None)

Resampling regions from a whole slide image.

This class is used to resample tiles/patches from a whole slide image using transformation.

Example

>>> from tiatoolbox.wsicore.wsireader import TransformedWSIReader
>>> transform_level0 = np.eye(3)
>>> transformed_wsi = TransformedWSIReader(
...     input_img=sample_ome_tiff, target_img=sample_ome_tiff,
...     transform=transform_level0
... )
>>> output = transformed_wsi.read_rect(
...     location,
...     size,
...     resolution,
...     units="level"
... )

Initialize TransformedWSIReader.

Parameters:

• input_img (str | Path | np.ndarray) – Path to the input image or the image array.

• target_img (str | Path | np.ndarray) – Path to the input target image or the image array.

• mpp (tuple(Number, Number)) – Microns per pixel in x and y directions.

• power (Number) – Objective power of the image.

• transform (str | Path | np.ndarray) –

  Transformation matrix or path to a transformation file (.npy or .mha).

  • .npy: A file format for storing numpy arrays.

  • .mha: MetaImage Header, a file format used for storing medical imaging

    data. It is part of the MetaIO library. For more information, visit: https://public.kitware.com/Wiki/ITK/MetaIO/Documentation

• fixed_info (WSIMeta) – Fixed metadata to use for the transformed image.

Methods

get_location_array	Transform an array of locations using the displacement field.
get_patch_dimensions	Compute patch size needed for transformation.
get_transformed_location	Get corresponding location on unregistered image and the required patch size.
get_transformed_location_df	Get corresponding location on unregistered image and the required patch size.
read_bounds	Read a transformed region of the transformed whole slide image within bounds.
read_rect	Read a transformed region of the transformed whole slide image.
sample_image_opencv	Samples image a at positions specified by b using OpenCV's remap function.
transform_patch	Apply transformation to the given patch.
transform_points	Transform points using the given transformation matrix.
transform_using_disp_array	Transform an array of locations using the displacement field.

Attributes

get_location_array(disp_array)

Transform an array of locations using the displacement field.

Gives an inverse showing, for a given pixel in a transformed image, where it would come from in the original image.

Parameters:

disp_array (np.ndarray) – A numpy array representing the displacement values.

Returns:

None

Return type:

None

get_patch_dimensions(size, transform)

Compute patch size needed for transformation.

Parameters:

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

• transform (numpy.ndarray) – Transformation matrix of shape (3, 3).

• self (TransformedWSIReader)

Returns:

tuple - Maximum size of the patch needed for transformation.

• int - Width

• int - Height

Return type:

tuple[int, int]

get_transformed_location(location, size, level)

Get corresponding location on unregistered image and the required patch size.

This function applies inverse transformation to the centre point of the region. The transformed centre point is used to obtain the transformed top left pixel of the region.

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.

• level (int) – Pyramid level/resolution layer.

• self (TransformedWSIReader)

Returns:

• tuple - Transformed location (top left pixel).

  • int - X coordinate

  • int - Y coordinate

• tuple - Maximum size suitable for transformation.

  • int - Width

  • int - Height

Return type:

tuple

get_transformed_location_df(location, size, level)

Get corresponding location on unregistered image and the required patch size.

This function applies inverse transformation to the points in the region, in the case of a displacement field transform. The transformed points are used to obtain the transformed bounding box of the region.

Parameters:

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

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

• level (int) – Pyramid level/resolution layer.

• self (TransformedWSIReader)

Returns:

• tuple - Transformed location (top left pixel).

  • int - X coordinate

  • int - Y coordinate

• tuple - Maximum size suitable for transformation.

  • int - Width

  • int - Height

Return type:

tuple

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

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

Bounds are 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 metadata 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 (IntBounds) – 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 (Resolution) – 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 (Units) – 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).

• coord_space (str) – Coordinate space of the bounds. By default, the bounds are in the baseline reference frame. If coord_space=”resolution” then the bounds are expected to be at the requested resolution system.

• interpolation (str) – Method to use when resampling the output image. Possible values are “linear”, “cubic”, “lanczos”, “area”, and “optimise”. 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.

• pad_constant_values (int | tuple(int)) – Constant values to use when padding with constant pad mode. Passed to the numpy.pad() constant_values argument. Default is 0.

• coord_space – Defaults 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 – Extra key-word arguments for reader specific parameters. Currently only used by VirtualWSIReader. See class docstrings for more information.

• self (TransformedWSIReader)

Returns:

A transformed region/patch.

Return type:

numpy.ndarray

Example

>>> from tiatoolbox.wsicore import TransformedWSIReader
>>> wsi = TransformedWSIReader(
...    input_img="cmu-1.ndpi", target_img="cmu-1.ndpi",
...    transform="transform.mha"
... )
>>> # read a region of size 1000x1000 at 1.25x scale
>>> # from (10000, 10000) at level 0
>>> img = wsi.read_bounds(25000,25000,27000,27000)

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

Read a transformed region of the transformed whole slide image.

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

Parameters:

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

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

• resolution (Resolution) – 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 (Units) – 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 “optimise”. 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.

• pad_constant_values (int, tuple(int)) – Constant values to use when padding with constant pad mode. Passed to the numpy.pad() constant_values argument. Default is 0.

• coord_space (str) – Defaults to “baseline”. This is a flag to indicate if the input location is in the baseline coordinate system (“baseline”) or is in the requested resolution system (“resolution”).

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

• self (TransformedWSIReader)

Returns:

A transformed region/patch.

Return type:

numpy.ndarray

Example

>>> from tiatoolbox.wsicore.wsireader import TransformedWSIReader
>>> transform_level0 = np.eye(3)
>>> tfm = TransformedWSIReader(
...     input_img=sample_ome_tiff, target_img=sample_ome_tiff,
...     transform=transform_level0
... )
>>> output = tfm.read_rect(
...     location, size, resolution=resolution, units="level"
... )

static sample_image_opencv(a, b)

Samples image a at positions specified by b using OpenCV’s remap function.

Parameters: - a: numpy array of shape (H, W, 3), the source image. - b: numpy array of shape (M, N, 2), the array of x, y positions.

Returns: - output: numpy array of shape (M, N, 3), the sampled image.

Parameters:

• a (ndarray)

• b (ndarray)

Return type:

ndarray

transform_patch(patch, size)

Apply transformation to the given patch.

This function applies the transformation matrix after removing the translation.

Parameters:

• patch (numpy.ndarray) – A region of whole slide image.

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

• self (TransformedWSIReader)

Returns:

A transformed region/patch.

Return type:

numpy.ndarray

static transform_points(points, transform)

Transform points using the given transformation matrix.

Parameters:

• points (numpy.ndarray) – A set of points of shape (N, 2).

• transform (numpy.ndarray) – Transformation matrix of shape (3, 3).

Returns:

Warped points of shape (N, 2).

Return type:

numpy.ndarray

static transform_using_disp_array(input_array, disp_array)

Transform an array of locations using the displacement field.

Parameters:

• input_array (np.ndarray) – A numpy array representing the input locations.

• disp_array (np.ndarray) – A numpy array representing the displacement field.

Returns:

The transformed array of locations.

Return type:

np.ndarray