histo_kit.grand_qc.artifact_detection

Functions

detect_artifacts_slide(slide_file, ...[, ...])

Run optimized GrandQC inference on a whole-slide image (WSI), aggregate patch-wise predictions into full-resolution confidence maps, produce visualizations and save results to desired output folders.
histo_kit.grand_qc.artifact_detection.detect_artifacts_slide(slide_file, res_dict_path, batch_size, num_workers, device, model, paths_dict, vis_mag, overlap=0.7, mag_model=10, patch_size=512, mode='gaussian', classes=8, sigma=None, save_mag=2.5, save_confidence_maps=True)[source]

Run optimized GrandQC inference on a whole-slide image (WSI), aggregate patch-wise predictions into full-resolution confidence maps, produce visualizations and save results to desired output folders.

This function: - loads a WSI and a precomputed tissue/background detection map, - extracts patches from tissue bounding boxes using a sliding grid, - runs the provided model on batches of patches, - merges patch predictions into full-image class confidence maps using a weighting

(Gaussian or average) window,

  • normalizes the aggregated maps by the sum of weights,

  • produces a hard prediction mask and color visualizations,

  • optionally rescales results to a different magnification and saves both the hard masks and per-class confidence maps as MATLAB .mat files, and

  • saves an overlay visualization.

Parameters:

  • slide_file (str or pathlib.Path) – Path to the WSI file (e.g. .svs) to process.

  • res_dict_path (str or pathlib.Path) – Path to .mat file containing precomputed tissue/background detection and related metadata used to compute bounding boxes (expected keys used in code: "mask_bg", "ind_WSI", "ratio", "thr").

  • batch_size (int) – Batch size for the PyTorch DataLoader used during inference.

  • num_workers (int) – Number of worker processes for the DataLoader.

  • device (torch.device or str) – Device used for inference (e.g. "cuda" or cpu).

  • model (torch.nn.Module) – Pre-trained segmentation/classification model that accepts a batch of image tensors and returns per-pixel class confidence maps (shape (N, C, H, W)).

  • paths_dict (dict) – Dictionary with output directory paths. Expected keys (used in function): - "grandqc_overlay_vis" : directory to save overlay PNGs - "masks_grandqc" : directory to save .mat with hard masks - "masks_grandqc_confidence_maps" : directory to save per-class .mat

  • vis_mag (float) – Magnification used for creating visualization overlays (e.g. 2.5, 5, 10).

  • overlap (float, optional) – Fractional overlap between sliding patches (default 0.7).

  • mag_model (float or int, optional) – Working magnification at which the model expects inputs (default 10).

  • patch_size (int, optional) – Side length of extracted square patches in pixels (default 512).

  • mode ({'gaussian', 'average'}, optional) – Weighting mode used when aggregating overlapping patch predictions. If 'gaussian', a Gaussian window is applied; if 'average', equal weights are used (default "gaussian").

  • classes (int, optional) – Number of classes (including background) predicted by the network (default 8).

  • sigma (float or None, optional) – Standard deviation parameter for the Gaussian window (only relevant when mode=='gaussian'). If None, a reasonable default (from gaussian_window) is assumed by that helper (default None).

  • save_mag (float or int, optional) – Magnification at which final masks/confidence maps are saved (default 2.5).

  • save_confidence_maps (bool, optional) – If True, save per-class confidence maps as separate .mat files in the directory pointed by paths_dict["masks_grandqc_confidence_maps"] (default True).

Returns:

  • 'basename' : str, base filename of the processed WSI (without extension)

  • 'mask_art' : list or MATLAB cell (converted inside function) of hard masks for tissue regions

  • 'ind_WSI' : value loaded from res_dict_path (indexes for WSI layers)

  • 'ratio' : value loaded from res_dict_path (ratio per layer)

  • 'scale_val' : float, final scale factor applied to masks

  • 'thr' : thresholds loaded from res_dict_path for color channels

  • 'bbox' : bounding boxes used for patch extraction (possibly rescaled)

(The function also writes multiple .mat files and PNGs to disk as a side effect.)

Return type:

A dictionary summarizing saved results and metadata. Keys include

Notes

  • The function may produce coordinates outside original image bounds; these are handled by cropping and padding logic inside the dataset / merge loop.

  • The caller must ensure that paths_dict directories exist and are writable.

  • Large WSIs can consume substantial memory; the implementation aggregates patch predictions into full-resolution arrays sized (H, W, classes) — ensure sufficient RAM is available for the target magnification and image size.

Examples

>>> paths = {
...     "grandqc_overlay_vis": "/out/overlays",
...     "masks_grandqc": "/out/masks",
...     "masks_grandqc_confidence_maps": "/out/conf_maps"
... }
>>> save_info = detect_artifacts_slide(
...     "slide.svs",
...     "slide_res.mat",
...     batch_size=8,
...     num_workers=4,
...     device="cuda",
...     model=my_model,
...     paths_dict=paths,
...     vis_mag=2.5,
...     overlap=0.7,
...     mag_model=10,
...     patch_size=512
... )
>>> print(save_info["basename"])

References

This function is based on [1]