alterlab-histolab

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.

When to Use This Skill

Use histolab for lightweight WSI tile pipelines: tissue detection, building tile datasets for ML training, H&E stain handling, and quick tile-based analysis of histopathology slides. For advanced spatial proteomics, multiplexed imaging, or full deep-learning pathology pipelines, use pathml instead.

Installation

uv pip install "histolab==0.7.0"

histolab wraps the OpenSlide C library, which is not bundled with the pip package. On macOS install it with brew install openslide; without it, any import histolab.slide fails with Couldn't locate OpenSlide dylib. The examples below are pinned to histolab 0.7.0; the API differs in older releases.

Core Workflow

1. Load the slide with Slide(path, processed_path=...) and inspect dimensions/levels.
2. Detect tissue with a mask (TissueMask or BiggestTissueBoxMask).
3. Preview tile locations with tiler.locate_tiles(slide) before committing.
4. Extract tiles with one of three tilers (Random/Grid/Score).

Minimal example:

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

slide = Slide("slide.svs", processed_path="output/")
# n_tiles, level, seed are CONSTRUCTOR args — not args to locate_tiles/extract.
tiler = RandomTiler(tile_size=(512, 512), n_tiles=100, level=0, seed=42)
tiler.locate_tiles(slide)   # preview locations on the thumbnail first
tiler.extract(slide)        # writes PNGs into processed_path

API gotcha (histolab 0.7.0): locate_tiles() and extract() take only slide, an optional extraction_mask, and logging/styling kwargs — they do not accept n_tiles. Set n_tiles (and seed, level, tile_size, check_tissue, tissue_percent) on the tiler constructor. The extraction_mask is passed to extract()/locate_tiles(), never to the constructor.