histo_kit.utils.wsi

Functions

get_regions_location(bg_mask)

Extract bounding boxes of connected tissue regions from a binary tissue mask.

load_wsi_mag(wsi, desired_mag[, ...])

Load and rescale a whole-slide image (WSI) to a desired magnification.

read_region(wsi, mask_file, region_idx, ...)

Read a masked region from a whole-slide image (WSI) and rescale it to a desired magnification.

slide_info(slide[, verbose])

Retrieve basic information about a whole-slide image (WSI).
histo_kit.utils.wsi.get_regions_location(bg_mask)[source]

Extract bounding boxes of connected tissue regions from a binary tissue mask.

This function identifies connected components in the input mask and returns their bounding box coordinates. Each bounding box is represented as: [y_min, x_min, y_max, x_max] in pixel coordinates.

Parameters:

bg_mask (ndarray of bool or int) – 2D binary mask where non-zero values indicate tissue (foreground) and zero indicates background.

Returns:

A list of bounding boxes, where each bounding box is represented as: [y_min, x_min, y_max, x_max]. If no tissue regions are found, an empty list is returned.

Return type:

list of list of int

Notes

  • The mask is expected to be 2D.

  • Bounding boxes are returned in the coordinate order used by skimage.measure.regionprops.

Examples

>>> mask = np.array([
...     [0, 1, 1, 0],
...     [0, 1, 1, 0],
...     [0, 0, 0, 0]
... ], dtype=bool)
>>> get_regions_location(mask)
[[0, 1, 2, 3]]
histo_kit.utils.wsi.load_wsi_mag(wsi, desired_mag, rescale_method=1, verbose=False, allow_upscaling=True)[source]

Load and rescale a whole-slide image (WSI) to a desired magnification.

This function reads the WSI at the closest available level to the desired magnification. If the exact magnification is unavailable, it rescales the image using the best level for downsample and the specified resampling method. When desired magnification is 5x and wsi has only magnifications 40x, 20x, 10x, 2.5x, the image will be rescaled from the magnification 10x to 5x. Optionally, upscaling is allowed when the desired magnification is higher than the highest WSI magnification.

Parameters:

  • wsi (OpenSlide object) – OpenSlide WSI object to load and rescale.

  • desired_mag (float) – Desired slide magnification (e.g., 10, 20, 40).

  • rescale_method (PIL.Image.Resampling or int, optional) – Resampling method used when resizing the image. Options include Image.BICUBIC, Image.BILINEAR, Image.BOX, Image.HAMMING, Image.LANCZOS, Image.NEAREST. Default is Image.LANCZOS.

  • verbose (bool, optional) – If True, prints information about the rescaling process. Default is False.

  • allow_upscaling (bool, optional) – If True, allows upscaling when the desired magnification is higher than the highest magnification available. Default is True.

Returns:

  • region (PIL.Image.Image) – Rescaled WSI region at the desired magnification (converted to RGB).

  • scale_val (float) – Scaling factor applied relative to the highest-resolution WSI level. For example, if the highest level is 40x and desired magnification is 10x, scale_val = 40/10 = 4.

  • info (str) – Information message describing whether the desired magnification was available or if rescaling/upscaling was applied.

  • mpp_slide (float) – Approximate microns-per-pixel (MPP) of the slide based on the highest magnification.

  • ratio (list of float) – List of downsample ratios for each WSI level.

Notes

  • If the desired magnification is available among the WSI levels, no rescaling is performed.

  • Rescaling is performed from the highest magnification level if the exact desired magnification is unavailable.

  • The function converts any RGBA images to RGB.

Examples

>>> region, scale_val, info, mpp_slide, ratio = load_wsi_mag(wsi, desired_mag=10)
>>> print(info)
>>> region.show()
histo_kit.utils.wsi.read_region(wsi, mask_file, region_idx, desired_mag, notation='python', allow_list=(1, 7), resampling_method=Resampling.LANCZOS)[source]

Read a masked region from a whole-slide image (WSI) and rescale it to a desired magnification.

This function extracts a specified region from a WSI using bounding box information stored in a mask file. It applies artifact filtering, rescales the region to the desired magnification, and converts background pixels to white.

Parameters:

  • wsi (OpenSlide object) – OpenSlide WSI object from which to read the region.

  • mask_file (dict-like) – Dictionary or NumPy file containing region bounding boxes, masks, and scaling information.

  • region_idx (int) – Index of the region to read from the mask file.

  • desired_mag (float) – Target magnification for the output region.

  • notation ({'python', 'matlab'}, optional) – Specifies whether bounding boxes use Python (0-based) or MATLAB (1-based) indexing. Default is “python”.

  • allow_list (tuple of int, optional) – Artifacts to allow in the mask. Only pixels labeled with these artifact types will be kept. Default is 1, 7.

  • resampling_method (PIL.Image.Resampling, optional) – Resampling method used when resizing regions (e.g., Image.Resampling.LANCZOS). Default is Image.Resampling.LANCZOS.

Returns:

region_masked – Masked and rescaled RGB region. Background pixels are set to white ([255, 255, 255]).

Return type:

ndarray of shape (H, W, 3)

Notes

  • Reads the WSI at the level closest to the desired magnification. If an exact level is not available, the region is rescaled using the specified resampling method.

  • Masks are resized to match the extracted region, and only allowed artifact regions are retained.

  • Pixels outside allowed regions are set to white for visualization.

Examples

>>> region = read_region(wsi, mask_file, region_idx=0, desired_mag=10)
>>> plt.imshow(region)
>>> plt.show()
histo_kit.utils.wsi.slide_info(slide, verbose=False)[source]

Retrieve basic information about a whole-slide image (WSI).

This function extracts metadata such as objective power, vendor, and width and height of the largest layer, and level downsamples.

Parameters:

  • slide (OpenSlide object) – Whole-slide image loaded via OpenSlide.

  • verbose (bool, default=False) – If True, prints slide information to the console.

Returns:

  • width_level_0 (int) – Width of the slide at the highest resolution (level 0).

  • height_level_0 (int) – Height of the slide at the highest resolution (level 0).

  • obj_power (float) – Objective magnification of the slide.

  • num_level (int) – Number of levels downsampled.

  • vendor (str) – Slide vendor.

  • down_levels (tuple of int) – Ratio of downsampled levels.

Examples

>>> patch_size,  obj_power = slide_info(slide, verbose=True)