Slide

The slide module provides a simple high-level interface to handle a WSI; it contains the Slide class, which wraps functions, methods and properties of a virtual slide in a single object. The Slide class encapsulates OpenSlide, and relies on the openslide-python library for the low-level operations on digital slides. A WSI is usually stored in pyramidal format, where each level corresponds to a specific magnification factor. Therefore, two relevant properties of a WSI are: (i) its dimensions at native magnification; (ii) the number of levels and the dimensions at a specified level.

Note

OpenSlide identifies each magnification level of the WSI with a positive integer number, starting from 0.

A Slide is initialized by providing the path where the WSI is stored and the path where processed images (such as the WSI thumbnail or the extracted tiles) will be saved. Further, the slide module implements the SlideSet class, which handles a collection of Slide objects stored in the same directory, possibly filtered by the valid_extensions parameter.

The slides_stats property of a SlideSet computes statistics for the WSI collection, namely the number of available slides; the slide with the maximum/minimum width; the slide with the maximum/minimum height; the slide with the maximum/minimum size; the average width/height/size of the slides.

class Slide(path, processed_path, use_largeimage=False)[source]

Provide Slide objects and expose property and methods.

Parameters
  • path (Union[str, pathlib.Path]) – Path where the WSI is saved.

  • processed_path (Union[str, pathlib.Path]) – Path where the tiles will be saved to.

  • use_largeimage (bool, optional) – Whether or not to use the large_image package for accessing the slide and extracting or calculating various metadata. If this is False, openslide is used. If it is True, large_image will try from the various installed tile sources. For example, if you installed it using large_image[all], it will try openslide first, then PIL, and so on, depending on the slide format and metadata. large_image also handles internal logic to enable fetching exact micron-per-pixel resolution tiles by interpolating between the internal levels of the slide. If you don’t mind installing an extra dependency, we recommend setting this to True and fetching Tiles at exact resolutions as opposed to levels. Different scanners have different specifications, and the same level may not always encode the same magnification in different scanners and slide formats.

Raises
  • TypeError – If the processed path is not specified.

  • ModuleNotFoundError – when use_largeimage is set to True and large_image module is not installed.

Return type

None

property base_mpp: float

Get microns-per-pixel resolution at scan magnification.

Returns

Microns-per-pixel resolution at scan (base) magnification.

Return type

float

Raises
  • ValueError – If large_image cannot detemine the slide magnification.

  • MayNeedLargeImageError – If use_largeimage was set to False when slide was initialized, and we cannot determine the magnification otherwise.

property dimensions: Tuple[int, int]

Slide dimensions (w,h) at level 0.

Returns

dimensions – Slide dimensions (width, height)

Return type

Tuple[int, int]

extract_tile(coords, tile_size, level=None, mpp=None)[source]

Extract a tile of the image at the selected level.

Parameters
  • coords (CoordinatePair) – Coordinates at level 0 from which to extract the tile.

  • tile_size (Tuple[int, int]) – Final size of the extracted tile (x,y). If you choose to specify the mpp argument, you may elect to set this as None to return the tile as-is from large_image without any resizing. This is not recommended, as tile size may be off by a couple of pixels when coordinates are mapped to the exact mpp you request.

  • level (int) – Level from which to extract the tile. If you specify this, and mpp is None, openslide will be used to fetch tiles from this level from the slide. openslide is used for fetching tiles by level, regardless of self.use_largeimage.

  • mpp (float) – Micron per pixel resolution. Takes precedence over level. If this is not None, large_image will be used to fetch tiles at the exact microns-per-pixel resolution requested.

Returns

tile – Image containing the selected tile.

Return type

Tile

level_dimensions(level=0)[source]

Return the slide dimensions (w,h) at the specified level

Parameters

level (int) – The level which dimensions are requested, default is 0.

Returns

dimensions – Slide dimensions at the specified level (width, height)

Return type

Tuple[int, int]

Raises

LevelError – If the specified level is not available

level_magnification_factor(level=0)[source]

Return the magnification factor at the specified level.

Notice that the conversion level-magnification can be computed only if the native magnification is available in the slide metadata.

Parameters

level (int) – The level which magnification factor is requested, default is 0.

Returns

magnification factor – Magnification factor at speficied level

Return type

str

Raises
  • LevelError – If the specified level is not available.

  • SlidePropertyError – If the slide’s native magnification or the downsample factor for the specified level are not available in the file’s metadata.

property levels: List[int]

Slide’s available levels

Returns

The levels available

Return type

List[int]

locate_mask(binary_mask, scale_factor=32, tissue_mask=False, alpha=128, outline='red')[source]

Draw binary mask contours on a rescaled version of the slide

Parameters
  • binary_mask (BinaryMask) – Binary Mask object

  • scale_factor (int) – Scaling factor for the returned image. Default is 32.

  • tissue_mask (bool, optional) – Whether to draw the contours on the binary tissue mask instead of the rescaled version of the slide. Default is False.

  • alpha (int) – The alpha level to be applied to the rescaled slide, default to 128.

  • outline (str) – The outline color for the annotation, default to ‘red’.

Returns

PIL Image of the rescaled slide with the binary mask contours outlined.

Return type

PIL.Image.Image

property name: str

Slide name without extension.

Returns

name

Return type

str

property processed_path: str

Path to store the tiles generated from the slide.

Returns

Path to store the tiles generated from the slide

Return type

str

property properties: dict

Whole Slide Image properties.

Returns

WSI complete properties.

Return type

dict

resampled_array(scale_factor=32)[source]

Return the resampled array from the original slide

Parameters

scale_factor (int, optional) – Image scaling factor. Default is 32.

Returns

resampled_array – Resampled array

Return type

np.ndarray

scaled_image(scale_factor=32)[source]

Return a scaled image of the slide.

Parameters

scale_factor (int, optional) – Image scaling factor. Default is 32.

Returns

A scaled image of the slide.

Return type

PIL.Image.Image

show()[source]

Display the slide thumbnail.

NOTE: A new window of your OS image viewer will be opened.

Return type

None

property thumbnail: PIL.Image.Image

Slide thumbnail.

Returns

The slide thumbnail.

Return type

PIL.Image.Image

class SlideSet(slides_path, processed_path, valid_extensions, keep_slides=None, slide_kwargs=None)[source]

Slideset object. It is considered a collection of Slides.

Parameters
  • slides_path (str) –

  • processed_path (str) –

  • valid_extensions (List[str]) –

  • keep_slides (List[str]) –

  • slide_kwargs (dict) –

Return type

None

scaled_images(scale_factor=32, n=0)[source]

Return rescaled images of the slides.

Parameters
  • scale_factor (int, optional) – Image scaling factor. Default is 32.

  • n (int, optional) – First n slides in dataset folder to rescale. Default is 0, meaning that all the slides will be returned.

Returns

List of rescaled images of the slides.

Return type

List[PIL.Image.Image]

property slides_stats: dict

Statistics for the WSI collection, namely the number of available slides; the slide with the maximum/minimum width; the slide with the maximum/minimum height; the slide with the maximum/minimum size; the average width/height/size of the slides.

Returns

basic_stats

Return type

dict of slides stats e.g. min_size, avg_size, etc…

thumbnails(n=0)[source]

Return slides thumbnails

Parameters

n (int, optional) – First n slides in dataset folder. Default is 0, meaning that the thumbnails of all the slides will be returned.

Returns

List of slides thumbnails

Return type

List[PIL.Image.Image]

property total_slides: int

Number of slides within the slideset.

Returns

n – Number of slides.

Return type

int