Slide¶

class slide.Slide(filename, annotation_filename=None, xml_style=None)[source]¶

An open WSI, with or without annotations.

Added functionality to OpenSlide WSI instances, optionally with annotations.

Parameters:	filename: str Path to slide file. Namesake argument to openslide.OpenSlide and AnnotatedOpenSlide. annotation_filename: str Path to XML annotation file. Namesake argument to AnnotatedOpenSlide. xml_style: str The computational histology challenge releasing the dataset. Namesake argument to AnnotatedOpenSlide.

Examples

>>> from wsipre import slide
>>> wsi = slide.Slide('tumor_001.tif', 'tumor_001.xml', 'asap')
>>> wsi.label_map
{'_0': 2, '_1': 2, '_2': 1}
>>> wsi.level_count
10
>>> len(wsi.polygons)
2

>>> thumbnail, mask, dwnspl_factor = wsi.get_thumbnail_with_annotation(
...     size=(3000, 3000), polygon_type='line', line_thickness=5)

>>> slide_region = wsi.read_region_with_annotation(
...     location=(65000, 110000), level=4, size=(1000, 1000))

Attributes:	tissue_mask: Numpy 2D array Tissue RoI `annotation`. tissue_label_map: dict {str: int} Correspondence between polygon region annotation labels and integer values used in numpy masks. downsampling_factor: float The scaling factor relative to level 0 dimensions. downsampled_slide: PIL image The scaled down slide generated when running the tissue detector.

Methods

`close`()	Close the OpenSlide object.
`detect_format`(filename)	Return a string describing the format vendor of the specified file.
`get_best_level_for_downsample`(downsample)	Return the best level for displaying the given downsample.
`get_thumbnail`(size)	Return a PIL.Image containing an RGB thumbnail of the image.
`get_thumbnail_with_annotation`(size[, …])	Convert annotated WSI to a scaled-down thumbnail.
`get_tissue_mask`([downsampling_factor, …])	Generate tissue region annotation.
`read_random_patch`(level, size, target_class, …)	Crop random patch from WSI.
`read_random_tissue_patch`(level, size[, …])	Crop random patch from detected tissue on WSI.
`read_region`(location, level, size)	Return a PIL.Image containing the contents of the region.
`read_region_with_annotation`(location, level, …)	Crop a smaller region from an annotated WSI.

associated_images¶

Images associated with this whole-slide image.

This is a map: image name -> PIL.Image.

Unlike in the C interface, the images accessible via this property are not premultiplied.

close()¶: Close the OpenSlide object.

classmethod detect_format(filename)¶

Return a string describing the format vendor of the specified file.

If the file format is not recognized, return None.

dimensions¶: A (width, height) tuple for level 0 of the image.

get_best_level_for_downsample(downsample)¶: Return the best level for displaying the given downsample.

get_thumbnail(size)¶

Return a PIL.Image containing an RGB thumbnail of the image.

size: the maximum size of the thumbnail.

get_thumbnail_with_annotation(size, polygon_type='area', line_thickness=None)[source]¶

Convert annotated WSI to a scaled-down thumbnail.

Parameters:	size: 2-tuple Maximum size of compressed image thumbnail as (width, height). polygon_type: str Type of polygon drawing: * ‘line’ * ‘area’ line_thickness: int Polygon edge line thickness. Required if `polygon_type` is `line`.
Returns:	Scaled down slide (as PIL RGBA image) and annotation mask (as numpy 2D array), plus the scaling factor.

get_tissue_mask(downsampling_factor=64, polygon_type='area', line_thickness=None)[source]¶

Generate tissue region annotation.

Make a binary mask annotating tissue regions of interest (RoI) on the WSI using an automatic threshold-based segmentation method inspired by the one used by Wang et al. [1]. Briefly, the method consists on the following steps, starting from a WSI:

Select downsampling level (typically a factor of 64)

Transfer from the RGB to the HSV color space

Determine optimal threshold value in the saturation channel using the Otsu algorithm [2]

Threshold image to generate a binary mask

Fill in small holes and remove small objects

[1]	Dayong Wang, Aditya Khosla, Rishab Gargeya, Humayun Irshad, Andrew H. Beck, “Deep Learning for Identifying Metastatic Breast Cancer”, arXiv:1606.05718.

[2]	Nobuyuki Otsu, “A Threshold Selection Method from Gray-level Histograms”, IEEE Trans Syst Man Cybern., 9(1):62–66, 1979.

Parameters:	downsampling_factor: int The desired factor to downsample the image by, since full WSIs will not fit in memory. The image’s closest level downsample is found and used. polygon_type: str Type of polygon drawing: * ‘line’ * ‘area’ line_thickness: int Polygon edge line thickness. Required if `polygon_type` is `line`.
Returns:	Binary mask as numpy 2D array, RGB slide image (in the used downsampling level, to allow visualization) and downsampling factor.

level_count¶: The number of levels in the image.

level_dimensions¶

A list of (width, height) tuples, one for each level of the image.

level_dimensions[n] contains the dimensions of level n.

level_downsamples¶

A list of downsampling factors for each level of the image.

level_downsample[n] contains the downsample factor of level n.

properties¶

Metadata about the image.

This is a map: property name -> property value.

read_random_patch(level, size, target_class, min_class_area_ratio, polygon_type='area', line_thickness=None)[source]¶

Crop random patch from WSI.

Select random location within target class according to provided annotation.

Parameters:

level: int: Slide level. Namesake argument to OpenSlide’s “read_region” function.
size: 2-tuple: Crop size (width, height). Namesake argument to OpenSlide’s “read_region” function.
target_class: int: The class annotation of the central pixel of the patch. function.
min_class_area_ratio: float [0, 1]: Minimum ratio of target class pixels to total pixels.
polygon_type: str: Type of polygon drawing: * ‘line’ * ‘area’
line_thickness: int: Polygon edge line thickness. Required if polygon_type is line.

Returns:

Image region or patch as PIL RGBA image plus annotation mask as 2D
Numpy array.

read_random_tissue_patch(level, size, avoid_labels=None)[source]¶

Crop random patch from detected tissue on WSI.

Parameters:	level: int Slide level. Namesake argument to OpenSlide’s “read_region” function. size: 2-tuple Crop size (width, height). Namesake argument to OpenSlide’s “read_region” function. avoid_labels: iterable Labels from provided annotation to avoid when targeting tissue. An annotation is must be available.
Returns:	Image region or patch as PIL RGBA image (plus annotation mask as 2D Numpy array if labels to avoid are provided).

read_region(location, level, size)¶

Return a PIL.Image containing the contents of the region.

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

level: the level number. size: (width, height) tuple giving the region size.

Unlike in the C interface, the image data returned by this function is not premultiplied.

read_region_with_annotation(location, level, size, polygon_type='area', line_thickness=None)[source]¶

Crop a smaller region from an annotated WSI.

Get a defined region from a WSI, together with its annotation mask.

Parameters:

location: 2-tuple: X and y coordinates of the top left pixel. Namesake argument to OpenSlide’s “read_region” function.
level: int: Slide level. Namesake argument to OpenSlide’s “read_region” function.
size: 2-tuple: Crop size (width, height). Namesake argument to OpenSlide’s “read_region” function.
polygon_type: str: Type of polygon drawing: * ‘line’ * ‘area’
line_thickness: int: Polygon edge line thickness. Required if ‘polygon_type’ is ‘line’.

Returns:

Image region (as PIL RGBA image) and the annotation mask (as numpy 2d
array).

wsipre 0.1.2 documentation

Slide¶

Previous topic