GenericSlide

GenericSlide is a class providing abstraction for various WSI reading libraries, currently supporting the libraries openslide (default) and tiffslide. GenericSlide also supports treating flat image files as one level WSIs using the Pillow library.

GenericSlide class has been introduced to ensure that the package can maintain its full functionality in case a prominent WSI reading library was ever to lose its support or even disappear.

Note

Generally it is not required to be familiar with the GenericSlide class to successfully use dplabtools. Various classes and modules of dplabtools use GenericSlide internally and the integration details are transparent to the end user. GenericSlide can, however, be used independently as a standalone class in any Python context.

Other class features include:

  • Extracting patches based on WSI levels or arbitrary MPP (Microns Per Pixel) values.

  • Down-sampling and up-sampling of WSIs at any MPP value using two different modes.

  • Built-in checks for MPP values and location coordinates when reading WSI regions.

  • Built-in warnings for invalid coordinates, invalid MPP values or reading close to WSI borders.

  • Automated padding of extracted regions.

  • Enhanced ability to extract WSI MPP values encoded in non-standard ways.

  • Additional support for missing and invalid MPP values.

  • Reading WSI embedded properties.

Basic usage

from dplabtools.slides import GenericSlide

wsi_file = "/tmp/wsi1.svs"
slide = GenericSlide(wsi_file=wsi_file)

Changing WSI reading library

The current WSI reading library can be changed dynamically using package settings, which must be done before any other imports from dplabtools:

# change current slide library
import dplabtools.config
dplabtools.config.slide_library = "tiffslide"

# import any other class from the package
from dplabtools.slides import GenericSlide
# or
from dplabtools.slides.patches import WholeImageRandomPatches
# or
from dplabtools.slides.patches import DiskPatchExtractor

This change will affect all instances of GenericSlide created in the program code.

Automated resampling

GenericSlide can automatically down-sample/up-sample WSIs in one of the two modes: tile or wsi.

  1. tile mode - resampling individual regions on the fly:

  • GenericSlide should be initiated with the argument resampling_mode="tile".

  • Resampling procedure will be applied automatically when calling the built-in image region reading function get_region() based on the level_or_mpp value provided:

    from dplabtools.slides import GenericSlide

wsi_file = "/tmp/wsi1.svs"
slide = GenericSlide(wsi_file=wsi_file, resampling_mode="tile")
region = slide.get_region(location=(0, 0), level_or_mpp=0.333, size=(256, 256))

  1. wsi mode - resampling the whole WSI level upfront:

  • In this mode extra WSI levels will be created upfront and stored in memory. Resampling happens immediately upon creation of the object and may take significant amounts of resources.

  • GenericSlide should be initiated with the argument resampling_mode="wsi" and with the desired MPP levels included in the list parameter called extra_mpps:

    from dplabtools.slides import GenericSlide

wsi_file = "/tmp/wsi1.svs"
slide = GenericSlide(wsi_file=wsi_file, resampling_mode="wsi", extra_mpps=[0.55, 0.99])
# possibly lengthy resampling process will commence now...
# ...
region1 = slide.get_region(location=(0, 0), level_or_mpp=0.55, size=(256, 256))
region2 = slide.get_region(location=(0, 0), level_or_mpp=0.99, size=(256, 256))

  • GenericSlide built-in image region reading function get_region() can access all native WSI levels as well as the extra levels created for the custom MPP values.

Whether to use one mode or the other will depend largely on the number of patches extracted from a single WSI and on the resampling performance in that particular environment.

Note

By default the resampling process will use level zero in the WSI pyramid as the base, which will promote the highest quality of the produced image at the cost of slow performance. This behavior can be reversed by using set_level_zero_resampling().

Advanced features

GenericSlide provides a set of advanced features available as dedicated class methods:

Example: missing MPP data

In case of missing MPP data in a WSI file its value can be inputted using set_external_mpp():

from dplabtools.slides import GenericSlide
GenericSlide.set_external_mpp(0.5)

wsi_file = "/tmp/wsi1.svs"
slide = GenericSlide(wsi_file=wsi_file, resampling_mode="tile")
region = slide.get_region(location=(0, 0), level_or_mpp=0.25, size=(256, 256))

From now on every time a missing MPP value is encountered it will be automatically substituted with the value of 0.5. A confirmation message of this operation will be logged.

Class details

class dplabtools.slides.GenericSlide(...)

Create a GenericSlide object for reading WSIs.

Parameters:

  • wsi_file (str) – WSI file name or path.

  • resampling_mode (str, optional) – One of the two supported resampling methods: wsi or tile.

  • extra_mpps (list of float, optional) – List of MPP values for extra pyramid levels, required when using resampling mode="wsi".

get_property(name)

Return the embedded property value from a WSI.

Parameters:

name (str) – Property name.

get_region(location, level_or_mpp, size, skip_padding=False)

Return the specified WSI region as an RGB Pillow image.

Parameters:

  • location (tuple) – (x, y) pair of int values indicating the WSI region (top left corner).

  • level_or_mpp (int or float) – Value indicating the WSI level or the target MPP value for the region.

  • size (tuple) – (width, height) pair of int values indicating the WSI region size.

  • skip_padding (bool, default=False) – Whether to skip padding the region, if it partially exceeds the image area.

get_region_array(location, level, size)

Return the specified WSI region as a NumPy array.

Parameters:

  • location (tuple) – (x, y) pair of int values indicating the WSI region (top left corner).

  • level (int) – Value indicating the WSI level.

  • size (tuple) – (width, height) pair of int values indicating the WSI region size.

Notes

  • only native WSI level values are supported here, no MPPs (float numbers)

  • region padding is not supported

  • additional checks (e.g. location) are also not supported

  • the purpose of this function is to retrieve LARGE regions as NumPy arrays, not small patches

  • the alpha channel is removed to match get_region output format

classmethod set_external_mpp(external_mpp)

Set the externally provided MPP value.

This value will be used only if MPP data is not embedded in a WSI or cannot be retrieved using any other implemented methods. When MPP data is available natively, any value set using this method will be ignored.

Parameters:

external_mpp (float) – MPP value to be used.

classmethod set_level_zero_resampling(level_zero_resampling)

Set the base WSI level for image resampling.

If True (default), then the WSI level zero will be used for resampling, otherwise the optimal level will be found. Level zero will provide the best data quality, but at the same time the poorest performance.

Parameters:

level_zero_resampling (bool, default=True) – Use level zero or other level for WSI resampling.

classmethod set_mpp_level_margin(mpp_level_margin)

Set the accuracy margin value when converting MPP values to WSI levels.

The provided MPP value will be considered an equivalent of the WSI level, if their computed difference is less than mpp_level_margin.

Parameters:

mpp_level_margin (float, default=0.003) – Margin value to be used.

classmethod set_mpp_round_decimal_places(mpp_round_decimal_places)

Set the number of decimal places used in MPP value rounding.

Some scanners may report slightly different values for X and Y axes, in such cases rounding is necessary. No rounding will take place if MPP values for X and Y axes match.

Parameters:

mpp_round_decimal_places (int, default=5) – Number of decimal places value to be used.

classmethod set_padding_margin_pixels(padding_margin_pixels)

Set the number of pixels as proximity to image borders to trigger the potential image background padding process.

Parameters:

padding_margin_pixels (int, default=10) – Number of pixels value to be used.

classmethod set_range_max_magnification(range_max_magnification)

Set the maximum magnification value for MPP range checking.

This value will be used only if the embedded magnification information is not available.

Parameters:

range_max_magnification (int, default=40) – Maximum magnification value to be used.

classmethod set_range_min_mpp(range_min_mpp)

Set the minimum MPP value used in MPP range checking during region reading or image upsampling.

Parameters:

range_min_mpp (float, default=0.001) – Minimum MPP value to be used.

classmethod set_resampling_filter(resampling_filter)

Set the resampling filter value for image downsampling and upsampling.

Available filter values: https://pillow.readthedocs.io/en/stable/handbook/concepts.html#concept-filters

Parameters:

resampling_filter (str, default="LANCZOS") – Resampling filter value to be used.

property all_properties

Return all embedded properties from the WSI.

property external_mpp

Return the external MPP value set by set_external_mpp.

property label_image

Return the embedded WSI label image.

property level_count

Return the number of native levels in the WSI.

property level_count_extra

Return the number of additional WSI levels created during resampling.

property level_dimensions

Return the dimension values for all native levels in the WSI.

property level_dimensions_extra

Return the MPP-indexed dimension values for additional WSI levels created during resampling.

property level_downsamples

Return the downsample factor values for all native levels in the WSI.

property level_images_extra

Return MPP-indexed images of additional WSI levels created during resampling.

property level_mpp_values

Return the MPP values for all native levels in the WSI.

property level_mpp_values_extra

Return the MPP values for additional WSI levels created during resampling.

property level_resamples_extra

Return the MPP-indexed downsample/upsample factor values for additional WSI levels created during resampling.

property level_zero_resampling

Return the level_zero_resampling value set by set_level_zero_resampling (default=True).

property lib_name

Return the current WSI reading library name.

property magnification

Return the WSI magnification value.

property mpp_data

Return the MPP data embedded in the WSI.

property mpp_level_margin

Return the mpp_level_margin value set by set_mpp_level_margin (default=0.003).

property mpp_round_decimal_places

Return the mpp_round_decimal_places value set by set_mpp_round_decimal_places (default=5).

property padding_margin_pixels

Return the padding_margin_pixels value set by set_padding_margin_pixels (default=10).

property range_max_magnification

Return the range_max_magnification value set by set_range_max_magnification (default=40).

property range_min_mpp

Return the range_min_mpp value set by set_range_min_mpp (default=0.001).

property resampling_filter

Return the resampling_filter value set by set_resampling_filter (default=”LANCZOS”).

property slide_file

Return the WSI file name or path.

property slide_id

Return the WSI file id (file name without extension).

property slide_name

Return the WSI file name.

property slide_object

Return the object representing the WSI reading library.

property thumbnail_image

Return the embedded WSI thumbnail image.

See also

level_or_mpp