Histolab System

A scientific computing skill for digital pathology image processing using Histolab — the Python library for automated preprocessing of whole slide images (WSI), including tissue detection, tile extraction, stain normalization, and quality filtering for computational pathology workflows.

When to Use This Skill

Choose Histolab System when:

• Extracting tiles from whole slide images for deep learning
• Performing tissue detection and background removal on WSIs
• Applying stain normalization across multiple slides
• Building preprocessing pipelines for computational pathology

Consider alternatives when:

• You need interactive slide viewing (use QuPath or ASAP)
• You need cell segmentation (use StarDist or Cellpose)
• You need image annotation tools (use QuPath or Labelbox)
• You need general image processing (use scikit-image or OpenCV)

Quick Start

Copy
claude "Extract tissue tiles from a whole slide image for deep learning"

Copy
from histolab.slide import Slide
from histolab.tiler import GridTiler, RandomTiler
from histolab.masks import TissueMask

# Load whole slide image
slide = Slide("specimen.svs", processed_path="./output")

print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
print(f"Level dimensions: {slide.level_dimensions}")

# Generate thumbnail with tissue mask
thumbnail = slide.scaled_image(scale_factor=32)
tissue_mask = TissueMask()
mask = tissue_mask(slide)

# Extract tiles using grid tiling
tiler = GridTiler(
    tile_size=(256, 256),
    level=0,                    # Highest resolution
    check_tissue=True,          # Skip background tiles
    tissue_percent=80,          # Min 80% tissue content
    pixel_overlap=0,
    prefix="tile_"
)

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

Core Concepts

WSI Processing Pipeline

Step	Class	Purpose
Load	Slide	Open WSI file (SVS, TIFF, NDPI)
Mask	TissueMask	Detect tissue vs. background
Filter	FilterCompose	Quality control filters
Tile	GridTiler / RandomTiler	Extract image patches
Normalize	Stain normalization	Color standardization

Tiling Strategies

Copy
from histolab.tiler import GridTiler, RandomTiler, ScoreTiler

# Grid Tiling — systematic, complete coverage
grid_tiler = GridTiler(
    tile_size=(256, 256),
    level=0,
    check_tissue=True,
    tissue_percent=80
)

# Random Tiling — sample N random tissue tiles
random_tiler = RandomTiler(
    tile_size=(256, 256),
    n_tiles=100,
    level=0,
    check_tissue=True,
    tissue_percent=80
)

# Score Tiling — tiles ranked by tissue content
score_tiler = ScoreTiler(
    tile_size=(256, 256),
    n_tiles=50,
    level=0,
    scorer=tissue_scorer
)

Quality Filters

Copy
from histolab.filters.morphological_filters import (
    RemoveSmallObjects,
    BinaryDilation,
    BinaryFillHoles
)
from histolab.filters.image_filters import (
    GreenChannelFilter,
    OtsuThreshold,
    RgbToGrayscale
)

# Compose tissue detection pipeline
from histolab.masks import BiggestTissueBoxMask

# Use biggest tissue region
mask = BiggestTissueBoxMask()

# Custom filter pipeline for quality control
from histolab.filters.compositions import FilterCompose

quality_filter = FilterCompose(
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=5),
    BinaryFillHoles(),
    RemoveSmallObjects(min_size=500)
)

Configuration

Parameter	Description	Default
tile_size	Output tile dimensions (px)	(256, 256)
level	WSI pyramid level (0=highest res)	0
tissue_percent	Minimum tissue content threshold	80
pixel_overlap	Overlap between adjacent tiles	0
n_tiles	Number of tiles (random/score tiler)	100

Best Practices

1. Start with a low-resolution overview. Generate a thumbnail (slide.scaled_image(scale_factor=64)) to visualize the entire slide before tiling. This helps identify tissue regions, artifacts, and staining quality issues.

2. Set tissue_percent threshold appropriately. 80% works for most applications, but may reject informative tiles at tissue boundaries. For tumor margin analysis, lower to 50-60% to capture the tissue-stroma interface.

3. Use level 0 for diagnostic tasks, higher levels for screening. Level 0 (highest resolution, typically 0.25 µm/pixel) captures cellular detail needed for diagnosis. Level 1 or 2 (lower resolution) is sufficient for tissue-level pattern recognition and processes faster.

4. Normalize staining before model training. H&E staining varies between labs, scanners, and tissue preparations. Apply stain normalization (Macenko or Vahadane methods) to reduce batch effects in multi-site studies.

5. Store tile coordinates alongside images. Save each tile's position (x, y, level) in metadata. This enables reconstructing the spatial context of model predictions and creating attention heatmaps overlaid on the original slide.

Common Issues

Slide loading fails with format error. Histolab uses OpenSlide internally. Ensure OpenSlide is installed (apt-get install openslide-tools on Linux, brew install openslide on Mac). Check that the file format is supported (SVS, TIFF, NDPI, MRXS).

Tissue detection includes artifacts. Pen marks, air bubbles, and folded tissue are detected as tissue. Add morphological filters (remove small objects, fill holes) or train a custom tissue segmentation model for challenging slides.

Tile extraction is extremely slow. Level 0 tiles from a 100,000 × 100,000 pixel slide can generate tens of thousands of tiles. Use a higher pyramid level for initial experiments, or extract tiles lazily (coordinates first, images on demand) for large-scale processing.