Histolab

Histolab is a community skill for computational histopathology using the Histolab library, covering whole slide image processing, tissue detection, tile extraction, stain normalization, and preprocessing for digital pathology machine learning workflows.

What Is This?

Overview

Histolab provides patterns for processing whole slide images (WSIs) in computational pathology. It covers slide loading and metadata extraction from common WSI formats like SVS and NDPI, tissue region detection that distinguishes tissue from background in scanned slides, tile extraction that cuts slides into patches suitable for ML model input, stain normalization that standardizes color appearance across scanners and laboratories, and quality filtering that removes tiles with artifacts, blur, or insufficient tissue. The skill enables pathology researchers to build automated pipelines for preparing histology images for deep learning analysis.

Who Should Use This

This skill serves computational pathologists building image analysis pipelines for diagnostic research, ML engineers preparing training data from whole slide images, and digital pathology developers creating tools for tissue analysis. It is particularly relevant for teams working with hematoxylin and eosin stained slides or immunohistochemistry preparations.

Why Use It?

Problems It Solves

Whole slide images are gigapixel-scale and cannot be loaded into memory at full resolution. Extracting informative tissue regions requires detecting tissue boundaries and excluding background. Color variation between slides stained in different labs confounds ML model training. Ensuring tile quality by filtering artifacts and out-of-focus regions requires systematic quality checks. Without a structured approach, these steps are error-prone and difficult to reproduce across large cohorts.

Core Highlights

Slide class loads WSI files with multi-resolution pyramid access. Tissue detection identifies regions of interest using threshold and morphological operations. Tile extractor generates fixed-size patches from tissue regions with configurable overlap. Quality filters score tiles for tissue content, blur, and staining artifacts.

How to Use It?

Basic Usage

from histolab.slide import Slide
from histolab.tiler import GridTiler

slide = Slide(
    "path/to/slide.svs",
    processed_path="output/tiles")

print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
print(f"Name: {slide.name}")

tiler = GridTiler(
    tile_size=(256, 256),
    level=0,
    check_tissue=True,
    tissue_percent=80.0,
    pixel_overlap=0)

tiler.extract(slide)
print(f"Tiles saved to: {slide.processed_path}")

Real-World Examples

from histolab.slide import Slide
from histolab.tiler import GridTiler
import os

class SlideProcessor:
    def __init__(self, output_dir: str,
                 tile_size: int = 256,
                 tissue_thresh: float = 80.0):
        self.output_dir = output_dir
        self.tiler = GridTiler(
            tile_size=(tile_size, tile_size),
            level=0,
            check_tissue=True,
            tissue_percent=tissue_thresh)

    def process_slide(self, path: str) -> dict:
        name = os.path.splitext(
            os.path.basename(path))[0]
        slide_dir = os.path.join(
            self.output_dir, name)
        slide = Slide(path, slide_dir)
        self.tiler.extract(slide)
        tiles = [f for f in os.listdir(slide_dir)
                 if f.endswith(".png")]
        return {"slide": name,
                "dimensions": slide.dimensions,
                "tiles_extracted": len(tiles)}

    def batch_process(
            self, slide_dir: str) -> list[dict]:
        results = []
        for f in os.listdir(slide_dir):
            if f.endswith((".svs", ".ndpi", ".tiff")):
                path = os.path.join(slide_dir, f)
                result = self.process_slide(path)
                results.append(result)
        return results

proc = SlideProcessor("output/tiles")
results = proc.batch_process("slides/")
for r in results:
    print(f"{r['slide']}: {r['tiles_extracted']} tiles")

Advanced Tips

Use lower resolution levels for tissue detection and thumbnail generation to save memory. Apply stain normalization before tile extraction to reduce color variability across training data. Combine tissue percentage filtering with blur detection to maximize the quality of extracted tiles. When processing large cohorts, log per-slide tile counts to identify slides with unexpectedly low yields, which often indicates tissue detection parameter mismatches for a particular staining protocol.

When to Use It?

Use Cases

Build a slide preprocessing pipeline that extracts quality-filtered tiles for training a tumor classification model. Create a tissue detection tool that generates tissue masks and thumbnails for slide review. Implement a batch tiling system that processes cohorts of whole slide images for research datasets.

Related Topics

Digital pathology, whole slide image analysis, computational histopathology, medical image processing, and deep learning for pathology.

Important Notes

Requirements

Python with the histolab package installed. OpenSlide library for reading whole slide image formats. Sufficient disk space for extracted tiles from large slide collections, as a single high-magnification slide can produce thousands of image patches. Pillow library for image processing and tile output.

Usage Recommendations

Do: validate tissue detection results on sample slides before running batch extraction. Use appropriate magnification levels for the target analysis task. Filter tiles by tissue content percentage to exclude mostly-background patches.

Don't: extract tiles at maximum resolution without considering disk space and processing time requirements. Skip quality filtering steps that remove artifacts and improve downstream model performance. Assume default tissue detection parameters work for all staining protocols.

Limitations

Tissue detection accuracy depends on staining consistency and slide quality. Very large slide collections require significant disk space for extracted tiles. Some WSI formats may need additional codec libraries beyond the base OpenSlide installation. Tile extraction at high magnification produces very large output directories that require careful storage planning.