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
- 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