histo_kit.utils.patches

Functions

get_patch_grid(regions[, patch_size, overlap])

Generate a grid of patch coordinates for one or multiple bounding regions.

merge_patches(patches_folder, attention_scores)

Merge image patches into a full image and optionally overlay an attention heatmap.

patch_wsi(region, patch_size, save_folder, ...)

Divide a whole-slide image region into patches and save them.
histo_kit.utils.patches.get_patch_grid(regions, patch_size=256, overlap=0.7)[source]

Generate a grid of patch coordinates for one or multiple bounding regions. Patches are placed with a given overlap and returned as coordinate lists.

Parameters:

  • regions (list of tuple) – List of bounding boxes, where each bounding box is defined as (y_min, x_min, y_max, x_max) in pixel coordinates.

  • patch_size (int, optional) – Size (height and width) of the extracted patches (default is 256).

  • overlap (float, optional) – Fraction of overlap between adjacent patches, where 0.0 means no overlap and 1.0 means fully overlapping patches (default is 0.9).

Returns:

A dictionary containing lists of patch coordinates:

  • "x_start" : list of int, starting x-coordinates

  • "y_start" : list of int, starting y-coordinates

  • "x_end" : list of int, ending x-coordinates

  • "y_end" : list of int, ending y-coordinates

Return type:

dict of list

Notes

The function may return coordinates outside the image boundaries. It is the caller’s responsibility to handle cropping or padding.

Examples

>>> regions = [(100, 200, 500, 800)]
>>> coords = get_patch_grid(regions, patch_size=256, overlap=0.5)
histo_kit.utils.patches.merge_patches(patches_folder, attention_scores, scale_factor=1, alpha=0.2)[source]

Merge image patches into a full image and optionally overlay an attention heatmap.

This function reconstructs a full tissue image from extracted patches. If attention scores are provided, it generates a heatmap overlay showing the attention values and blends it with the tissue image.

Parameters:

  • patches_folder (str) – Path to the folder containing extracted image patches. Patch filenames should encode their coordinates, e.g., ‘patch_x_y.png’.

  • attention_scores (dict or None) – Dictionary mapping patch filenames to attention scores. If None, no heatmap is generated.

  • scale_factor (float, optional) – Scaling factor applied to the final overlay and attention map images. Default is 1 (no scaling).

  • alpha (float, optional) – Weight for blending the attention heatmap with the tissue image. The final image is overlay = (1-alpha) * tissue + alpha * heatmap. Lower alpha makes the tissue more visible. Default is 0.2.

Returns:

  • overlay (PIL.Image.Image) – Reconstructed tissue image with attention heatmap overlay, rescaled if scale_factor ≠ 1.

  • attention_map_rgb (PIL.Image.Image) – RGB image of the attention heatmap alone, rescaled if scale_factor ≠ 1.

  • attention_map (ndarray of shape (H, W)) – 2D NumPy array of per-pixel attention scores. When patches overlap, scores are averaged per pixel.

Notes

  • The function expects patches to have filenames encoding their top-left coordinates as *_x_y.*.

  • Overlapping patches are handled by averaging attention scores where they overlap.

  • Uses a colormap (config.heatmap_colors) to map attention values to RGB colors.

  • The final overlay uses OpenCV blending for alpha compositing.

  • Image resizing is done with nearest-neighbor interpolation.

Examples

>>> overlay, heatmap_rgb, attention_map = merge_patches("patches/", attention_scores, scale_factor=2, alpha=0.3)
>>> overlay.show()
>>> heatmap_rgb.show()
>>> print("Attention map shape:", attention_map.shape)
histo_kit.utils.patches.patch_wsi(region, patch_size, save_folder, bg_percent, overlap=0, extract_type='valid')[source]

Divide a whole-slide image region into patches and save them.

This function extracts square patches of a given size from an RGB image, optionally overlapping, and saves only those patches that meet a background pixel threshold. Background pixels are assumed to be white ([255, 255, 255]).

Parameters:

  • region (ndarray of shape (H, W, 3)) – RGB image region (masked or unmasked). White pixels are treated as background.

  • patch_size (int) – Size of the square patches to extract (in pixels).

  • save_folder (str) – Path to the folder where extracted patches will be saved. The folder is created if it does not exist.

  • bg_percent (float) – Maximum allowable fraction of background pixels per patch. Patches with more background than this are rejected. Range [0, 1].

  • overlap (float, optional) – Fraction of overlap between adjacent patches. Must be in [0, 1). Default is 0.

  • extract_type (str, optional) – If “valid”, only extract fully contained patches. Otherwise, this specifies a NumPy padding mode (e.g., “constant”, “reflect”, “symmetric”) for partially overlapping patches. Default is “valid”.

Returns:

  • num_correct (int) – Number of patches successfully extracted (below background threshold).

  • num_rejected (int) – Number of patches rejected due to excessive background pixels.

Notes

  • Patch filenames include the top-left coordinates in the format “patch_x_y.png”.

  • When extract_type is not “valid”, the image is padded as needed.

Examples

>>> num_correct, num_rejected = patch_wsi(region, patch_size=256, save_folder="patches", bg_percent=0.5, overlap=0.2)
>>> print(f"Saved {num_correct} patches, rejected {num_rejected} patches.")