histolab

用途

Histolab 是一个用于处理数字病理全切片图像（Whole Slide Image，WSI）的 Python 库。它面向病理图像分析场景，主要解决从千兆像素级切片中自动检测组织区域、提取信息量高的图块（tile），以及为深度学习流程准备数据集等问题。该库支持多种 WSI 格式，实现组织分割，并提供灵活的图块提取策略。

主要能力

Histolab 的能力可归纳为六个方面：

切片管理：打开切片、读取属性、处理金字塔层级、生成缩略图和缩放图像。
组织检测与掩膜：提供 TissueMask 和 BiggestTissueBoxMask，以及自定义掩膜。
图块提取：提供随机（RandomTiler）、网格（GridTiler）和基于评分（ScoreTiler）的提取器，支持尺寸、层级和组织占比控制。
过滤器与预处理：提供图像过滤器、形态学过滤器及其组合。
染色归一化：支持 Reinhard 和 Macenko 归一化，可针对目标图像进行。
可视化：在切片上定位图块，检查掩膜和提取结果。

安装方式

需先安装 OpenSlide 系统库，然后安装 histolab：

uv pip install histolab

如需通过 histolab.data 使用内置 TCGA 示例切片，还需安装 pooch：

uv pip install pooch

Histolab 0.7.0（最新稳定版）支持 Linux 和 macOS 上的 Python 3.8–3.11。截至 0.7.0，暂不支持 Windows。

使用方式

基本工作流示例：

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

# 加载切片
slide = Slide("slide.svs", processed_path="output/")

# 配置提取器
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42
)

# 预览图块位置
tiler.locate_tiles(slide, n_tiles=20)

# 提取图块
tiler.extract(slide)

适用场景

训练深度学习模型：使用 RandomTiler 跨多张切片提取均衡数据集；使用 ScoreTiler 配合 NucleiScorer 聚焦细胞丰富区域；在一致分辨率下提取；生成 CSV 报告以跟踪图块元数据。
全切片分析：使用 GridTiler 实现完整组织覆盖；在多个金字塔层级提取以进行分层分析；通过网格位置保持空间关系；使用 pixel_overlap 实现滑动窗口方法。
组织特征描述：使用 RandomTiler 采样多样区域；用掩膜量化组织覆盖；通过 HED 分解提取染色特定信息；比较不同切片的组织模式。
质量评估：使用 ScoreTiler 识别最佳聚焦区域；用自定义掩膜和过滤器检测伪影；评估切片集合的染色质量；标记问题切片以供人工复核。
数据集整理：使用 ScoreTiler 优先选择信息量大的图块；按组织百分比过滤图块；生成带图块评分和元数据的报告；跨切片和组织类型创建分层数据集。

限制

截至 0.7.0，不支持 Windows。
支持 Python 3.8–3.11，仅限 Linux 和 macOS。
使用前需先安装 OpenSlide 系统库。
内置 TCGA 示例切片需额外安装 pooch。
输出为面向合格专业人员的决策支持，不构成医疗建议，不得作为诊断或医嘱呈现。
版本相关细节可能已过时，应以所安装版本的官方文档为准。
涉及费用、共享 GPU 或云配额、个人或患者数据、不可撤销操作时，需先征得同意。

最佳实践（摘要）

处理前始终检查切片属性，保存缩略图以便快速视觉复核。
提取前用 locate_mask() 预览掩膜，用 locate_tiles() 预览图块位置。
根据需求选择提取器：RandomTiler 用于采样和探索，GridTiler 用于完整覆盖，ScoreTiler 用于质量驱动选择。
设置合适的 tissue_percent 阈值（通常 70–90%）。
在 RandomTiler 中使用种子以保证可复现性。
在合适的金字塔层级提取以匹配分析分辨率。
大数据集启用日志记录。

故障排查（摘要）

未提取到图块：降低 tissue_percent 阈值；确认切片含组织；确保提取掩膜覆盖组织区域；检查 tile_size 是否适合切片分辨率。
背景图块过多：启用 check_tissue=True；提高 tissue_percent 阈值；使用合适的掩膜；自定义掩膜过滤器以更好检测组织。
提取非常慢：在较低金字塔层级提取；减少 n_tiles；用 RandomTiler 替代 GridTiler；用 BiggestTissueBoxMask 替代 TissueMask。
图块有伪影：实现自定义注释排除掩膜；调整过滤器参数；提高小对象移除阈值；应用提取后质量过滤。
跨切片结果不一致：为 RandomTiler 使用相同种子；用 MacenkoStainNormalizer 或 ReinhardStainNormalizer 归一化染色；按染色质量调整 tissue_percent；实现切片特定的掩膜定制。

参考文档

该技能在 references/ 目录中包含详细参考文档：references/slide_management.md、references/tissue_masks.md、references/tile_extraction.md、references/filters_preprocessing.md、references/visualization.md。参考文件包含深入信息，以支持主技能文档中描述的工作流；可根据需要加载特定参考文件以获取详细实现指导、故障排查或高级功能。

代理操作流程

检查环境：确认数据访问权限、去标识化状态以及适用的法规或协议。
明确输入：从数据或用户处确认格式、标识符和参数。对任何会改变结果的取值，应询问而非猜测。
先运行小版本：先在去标识化样本或合成数据上运行。
使用上述说明和参考执行完整任务。
验证结果：对照临床指南和报告标准检查输出；由合格人员复核临床内容。
报告：说明运行了什么（版本、命令、参数）、检查了什么，以及仍不确定的内容。

完整性规则

绝不捏造结果、参数、标识符、引用或统计数据。若无法运行或验证，应明确说明。
输出为面向合格专业人员的决策支持，不是医疗建议；绝不将其呈现为诊断或医嘱。
此处的版本特定细节可能已过时：请对照所安装版本的官方文档进行确认。
在涉及费用、消耗共享 GPU 或云配额、接触个人或患者数据，或不可撤销的操作前，应先征得同意。

技能介绍

用途