/histolab

name: histolab
description: Lightweight WSI tile extraction and preprocessing. Use for basic slide processing, tissue detection, tile extraction, and stain normalization for H&E images. Best for simple pipelines, dataset preparation, and quick tile-based analysis. For advanced spatial proteomics, multiplexed imaging, or deep learning pipelines use pathml.
license: Apache-2.0 license
compatibility: Requires Python 3.8–3.11 (histolab 0.7.0), OpenSlide system libraries, and Linux or macOS. Sample data via histolab.data requires pooch.
metadata:
  version: "1.3"
  skill-author: K-Dense Inc.

Histolab

Overview

Histolab is a Python library for processing whole slide images (WSI) in digital pathology. It automates tissue detection, extracts informative tiles from gigapixel images, and prepares datasets for deep learning pipelines. The library handles multiple WSI formats, implements sophisticated tissue segmentation, and provides flexible tile extraction strategies.

Installation

Install OpenSlide system libraries first ([OpenSlide download](https://openslide.org/download/)), then install histolab:

uv pip install histolab

For built-in TCGA sample slides via `histolab.data`, also install pooch:

uv pip install pooch

Histolab 0.7.0 (latest stable) supports Python 3.8–3.11 on Linux and macOS. Windows is not supported as of 0.7.0.

Quick Start

Basic workflow for extracting tiles from a whole slide image:

from histolab.slide import Slide
from histolab.tiler import RandomTiler

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

# Configure tiler
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42
)

# Preview tile locations
tiler.locate_tiles(slide, n_tiles=20)

# Extract tiles
tiler.extract(slide)

Core Capabilities

Six capability areas, each with worked code, are documented in [references/core_capabilities.md](references/core_capabilities.md):

1. **Slide management** — opening slides, properties, levels, thumbnails, and scaled images. 2. **Tissue detection and masks** — `TissueMask` and `BiggestTissueBoxMask`, and custom masks. 3. **Tile extraction** — random, grid, and score-based tilers with size, level, and tissue-fraction control. 4. **Filters and preprocessing** — image and morphological filters, and composing them. 5. **Stain normalization** — Reinhard and Macenko normalization against a target image. 6. **Visualization** — locating tiles on the slide and inspecting masks and extractions.

Five end-to-end workflows are in [references/typical_workflows.md](references/typical_workflows.md). Per-topic detail lives in [references/slide_management.md](references/slide_management.md), [references/tissue_masks.md](references/tissue_masks.md), [references/tile_extraction.md](references/tile_extraction.md), [references/filters_preprocessing.md](references/filters_preprocessing.md), and [references/visualization.md](references/visualization.md).

Best Practices

Slide Loading and Inspection

1. Always inspect slide properties before processing 2. Save thumbnails with `slide.thumbnail.save()` for quick visual review 3. Check pyramid levels and dimensions 4. Verify tissue is present using thumbnails

Tissue Detection

1. Preview masks with `locate_mask()` before extraction 2. Use `TissueMask` for multiple sections, `BiggestTissueBoxMask` for single sections 3. Customize filters for specific stains (H&E vs IHC) 4. Handle pen annotations with custom masks 5. Test masks on diverse slides

Tile Extraction

1. **Always preview with `locate_tiles()` before extracting** 2. Choose appropriate tiler:

• RandomTiler: Sampling and exploration
• GridTiler: Complete coverage
• ScoreTiler: Quality-driven selection

3. Set appropriate `tissue_percent` threshold (70-90% typical) 4. Use seeds for reproducibility in RandomTiler 5. Extract at appropriate pyramid level for analysis resolution 6. Enable logging for large datasets

Performance

1. Extract at lower levels (1, 2) for faster processing 2. Use `BiggestTissueBoxMask` over `TissueMask` when appropriate 3. Adjust `tissue_percent` to reduce invalid tile attempts 4. Limit `n_tiles` for initial exploration 5. Use `pixel_overlap=0` for non-overlapping grids

Quality Control

1. Validate tile quality (check for blur, artifacts, focus) 2. Review score distributions for ScoreTiler 3. Inspect top and bottom scoring tiles 4. Monitor tissue coverage statistics 5. Filter extracted tiles by additional quality metrics if needed

Common Use Cases

Training Deep Learning Models

• Extract balanced datasets using RandomTiler across multiple slides
• Use ScoreTiler with NucleiScorer to focus on cell-rich regions
• Extract at consistent resolution (level 0 or level 1)
• Generate CSV reports for tracking tile metadata

Whole Slide Analysis

• Use GridTiler for complete tissue coverage
• Extract at multiple pyramid levels for hierarchical analysis
• Maintain spatial relationships with grid positions
• Use `pixel_overlap` for sliding window approaches

Tissue Characterization

• Sample diverse regions with RandomTiler
• Quantify tissue coverage with masks
• Extract stain-specific information with HED decomposition
• Compare tissue patterns across slides

Quality Assessment

• Identify optimal focus regions with ScoreTiler
• Detect artifacts using custom masks and filters
• Assess staining quality across slide collection
• Flag problematic slides for manual review

Dataset Curation

• Use ScoreTiler to prioritize informative tiles
• Filter tiles by tissue percentage
• Generate reports with tile scores and metadata
• Create stratified datasets across slides and tissue types

Troubleshooting

No tiles extracted

• Lower `tissue_percent` threshold
• Verify slide contains tissue (check thumbnail)
• Ensure extraction_mask captures tissue regions
• Check tile_size is appropriate for slide resolution

Many background t