alterlab-histolab

Histolab

概述

Histolab 是一个用于数字病理全视野图像（WSI）处理的 Python 库。它能够自动检测组织、从千兆像素图像中提取有信息量的图块，并为深度学习工作流准备数据集。该库支持多种 WSI 格式，实现了复杂的组织分割，并提供灵活的图块提取策略。

何时使用此技能

在构建轻量级 WSI 图块工作流时使用 histolab：组织检测、创建用于 ML 训练的图块数据集、处理 H&E 染色，以及对组织病理切片进行快速的基于图块的分析。对于高级空间蛋白质组学、多重成像或完整的深度学习病理学工作流，请改用 alterlab-pathml。

不适用的场景

场景	改用
端到端计算病理学、细胞核分割、多重成像（CODEX/Vectra）	alterlab-pathml
使用提取的图块训练下游分类器	alterlab-pytorch-lightning
DICOM 全视野图像或放射影像，而非 SVS/NDPI	alterlab-pydicom、alterlab-imaging-data-commons
组织切片上的空间转录组学	alterlab-squidpy-spatial
管理/版本化切片集合本身	alterlab-omero、alterlab-lamindb

安装

# histolab 0.7.0 needs Python >= 3.8, < 3.12 and numpy 1.x — give it its own env
uv venv --python 3.11 .venv-histolab
uv pip install --python .venv-histolab "histolab==0.7.0" openslide-bin

在 2026 年的工具链中，有两个需要注意的限制：

1. 固定的科学计算依赖栈。 0.7.0（2024 年 2 月发布，仍是最新版本）要求 numpy <= 1.24.4、scipy < 1.10.1、scikit-image < 0.19.4 和 openslide-python 1.3.1。它无法与使用 numpy 2.x / Python 3.12+ 的项目共用环境——请使用单独的 venv 解决，而不要放宽版本固定要求。
2. OpenSlide 是 C 库，并未随 wheel 一同打包。最简单的解决办法是使用 openslide-bin wheel（预编译二进制文件）；否则，可在 macOS 上运行 brew install openslide，或在 Debian/Ubuntu 上运行 apt install libopenslide0。缺少该库时， import histolab.slide 会因 Couldn't locate OpenSlide dylib 而失败。

以下示例适用于 histolab 0.7.0；旧版本的 API 有所不同。

核心工作流

1. 使用 Slide(path, processed_path=...) 加载切片，并检查尺寸/层级。
2. 使用遮罩（TissueMask 或 BiggestTissueBoxMask）检测组织。
3. 在确认提取前，使用 tiler.locate_tiles(slide) 预览图块位置。
4. 使用三种图块器之一（Random/Grid/Score）提取图块。

最简示例：

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 注意事项（histolab 0.7.0）： locate_tiles() 和 extract() 只接受 slide、可选的 extraction_mask，以及日志/样式相关的 kwargs——它们 不接受 n_tiles。请在图块器构造函数中设置 n_tiles（以及 seed、level、tile_size、 check_tissue、tissue_percent）。extraction_mask 应传给 extract()/locate_tiles()，而不是构造函数。

可直接复制粘贴的完整工作流（快速入门、5 个端到端工作流，以及按功能分类的示例）位于 references/workflows.md。

核心功能

1. 切片管理

加载、检查和处理 WSI 文件（SVS、TIFF、NDPI 等）：访问元数据 （尺寸、放大倍数、属性），生成缩略图，并处理金字塔/多层结构。主要类：Slide。

有关切片初始化、内置示例数据集（prostate_tissue、ovarian_tissue、breast_tissue、heart_tissue、 aorta_tissue，以及带笔迹标记和 IHC 的示例）、金字塔层级和 多切片处理，请参阅 references/slide_management.md。

2. 组织检测与掩膜

自动识别组织区域并过滤背景和伪影。关键类：TissueMask（所有组织区域）、BiggestTissueBoxMask（最大区域的边界框——默认选项）和 BinaryMask（自定义掩膜的基类）。

选择掩膜：

• TissueMask：多个组织切片，全面分析
• BiggestTissueBoxMask：单个主要切片，排除伪影（默认选项）
• 自定义 BinaryMask：特定 ROI、排除标注、自定义分割

参见 references/tissue_masks.md，了解检测过滤器的工作原理、如何使用 locate_mask() 可视化掩膜，以及自定义矩形掩膜和排除标注的掩膜。

3. 图块提取

使用以下三种策略之一，从大型 WSI 中提取较小区域：

• RandomTiler — 提取固定数量、随机定位的图块。适合采样多样化区域、探索和训练数据。关键参数：n_tiles、seed。
• GridTiler — 在组织上按网格系统提取。适合完整覆盖、空间分析和重建。关键参数：pixel_overlap。
• ScoreTiler — 根据评分函数提取排名靠前的图块。适合筛选信息丰富的区域，以及基于质量进行选择。关键参数：scorer（NucleiScorer、CellularityScorer、自定义评分器）。

通用参数：tile_size、level（0 = 最高分辨率）、check_tissue、tissue_percent（默认 80%）、extraction_mask。提取前务必使用 locate_tiles() 预览。

参见 references/tile_extraction.md，了解评分器、报告和高级（多层级、分层）提取模式。

4. 过滤器与预处理

应用图像处理过滤器，用于组织检测、QC 和预处理：

• 图像过滤器 — RgbToGrayscale、RgbToHsv、RgbToHed、OtsuThreshold、Invert、StretchContrast、HistogramEqualization、Lambda。
• 形态学过滤器 — BinaryDilation、BinaryErosion、BinaryOpening、BinaryClosing、RemoveSmallObjects、RemoveSmallHoles。
• 组合 — Compose（位于 histolab.filters.image_filters 中）将多个过滤器串联为管道。将自定义过滤器作为位置可变参数传递给掩膜：TissueMask(RgbToGrayscale(), OtsuThreshold(), ...)。

参见 references/filters_preprocessing.md，了解过滤器串联、常用管道（组织检测、去除笔迹、细胞核增强）和 QC 过滤器。

5. 可视化

显示切片、掩膜、图块位置和提取质量：缩略图、通过 locate_mask() 查看掩膜叠加、通过 locate_tiles() 预览图块位置、图块拼接图和评分分布。

参见 references/visualization.md，了解拼接图、质量评估图、多切片对比，以及高分辨率图像和 PDF 报告的导出。

参考索引

• references/workflows.md — 快速入门、各项功能示例，以及 5 个端到端的完整工作流（探索、网格、评分驱动、多切片、自定义组织检测）。
• references/slide_management.md — 加载和检查切片、示例数据集、金字塔层级、多切片处理。
• references/tissue_masks.md — TissueMask/BiggestTissueBoxMask/BinaryMask、自定义掩膜、掩膜可视化与集成。
• references/tile_extraction.md — Random/Grid/Score tiler 对比、评分器、CSV 报告、高级提取模式。
• references/filters_preprocessing.md — 图像与形态学过滤器、过滤器组合、预处理管道、QC 过滤器。
• references/visualization.md — 缩略图、掩膜/图块预览、拼接图、质量图、图像导出。
• references/best_practices.md — 最佳实践、常见用例和故障排查（未提取到图块、背景图块、提取缓慢、伪影）。

加载所需的特定参考文件，获取详细的实现指导、故障排查方法或高级功能说明。

属于 AlterLab Academic Skills 套件。