Histolab

When to use

Use Histolab to inspect WSI metadata, identify tissue, extract image tiles, and standardize H&E staining. Its masks and scores are image-processing heuristics; they do not diagnose cancer, count individual cells, or establish image quality.

Installation

Histolab 0.7.0 remains the latest published release as of the review date. Its release constraints require Python <3.12, NumPy <=1.24.4, scikit-image <0.19.4, SciPy <1.10.1, Pillow <11, and openslide-python 1.3.1. Keep this stack isolated from modern scientific environments. Windows is not supported by this Histolab release.

Install native OpenSlide for your system, then create a dedicated environment (Python 3.10 was tested):

uv venv --python 3.10 .venv-histolab
uv pip install --python .venv-histolab/bin/python 'histolab==0.7.0' pooch matplotlib
.venv-histolab/bin/python -c 'import openslide; print(openslide.__library_version__)'

On macOS with Homebrew, brew install openslide installs the native library. If the older Python binding cannot find it, launch Python with the library path set immediately before Python starts:

env DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix openslide)/lib" .venv-histolab/bin/python -c 'import openslide; print(openslide.__library_version__)'

pooch is optional for remote examples. Start with a local slide or the tiny bundled cmu_small_region sample; other sample functions may download hundreds of megabytes. Exact mpp extraction also needs large-image and a matching source plugin; see slide management.

Workflow

1. Inspect slide.dimensions, slide.levels (a list), and slide.level_dimensions(level) (a method). Check both MPP axes in metadata.
2. Select physical field of view and pixel resolution; level numbers are not interchangeable across scanners. Preserve level-0 coordinate bounds.
3. Choose TissueMask for all tissue sections or BiggestTissueBoxMask for the largest section's bounding box. Inspect the mask at its actual resolution.
4. Configure a tiler and preview with the same mask passed to extraction. Preview methods return a Pillow image; save or display that return value.
5. Extract into a distinct per-slide/per-strategy directory. Count saved files, inspect representative tiles, and retain parameters, source IDs and QC flags.
6. Split datasets by patient before training/validation/test tile assignment. Fit stain normalization targets on training data only and validate on held-out scanners. A seed reproduces sampling; it does not prevent patient leakage.

Quick start

Illustrative for a user-provided slide; the same API path is tested with small local fixtures. n_tiles is an upper bound, not a promise of 100 valid tiles.

from pathlib import Path
from histolab.slide import Slide
from histolab.masks import TissueMask
from histolab.tiler import RandomTiler

output = Path("output/random_tiles")
output.mkdir(parents=True, exist_ok=True)
slide = Slide("slide.svs", processed_path=output)
mask = TissueMask()
slide.locate_mask(mask).save(output / "mask_preview.png")

tiler = RandomTiler(
    tile_size=(512, 512), n_tiles=100, level=0, seed=42,
    check_tissue=True, tissue_percent=80.0, prefix="random_",
)
tiler.locate_tiles(slide, extraction_mask=mask).save(output / "tile_preview.png")
tiler.extract(slide, extraction_mask=mask)
print("[OK] Saved tiles:", len(list(output.glob("random_tile_*.png"))))

extraction_mask belongs to extract() and locate_tiles(), not to the tiler constructor. locate_tiles() has no n_tiles argument. Previewing runs tile selection again, so it may be expensive; use a separate small tiler for initial exploration, then preview the final configuration before committing a large run.

Choose a strategy

For grids, stride in each axis is tile size minus pixel_overlap; positive

…