histolab

Histolab

概述

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

安装

请先安装 OpenSlide 系统库（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

# 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)

核心功能

六个功能领域均附有完整代码示例，详见 references/core_capabilities.md：

1. 切片管理 — 打开切片、查看属性和层级、生成缩略图及缩放图像。
2. 组织检测与掩码 — 使用 TissueMask 和 BiggestTissueBoxMask，以及自定义掩码。
3. 图块提取 — 使用随机、网格和基于评分的切片器，并控制尺寸、层级和 组织占比。
4. 滤镜与预处理 — 使用图像和形态学滤镜，并将它们组合起来。
5. 染色归一化 — 根据目标图像进行 Reinhard 和 Macenko 归一化。
6. 可视化 — 定位切片上的图块，并检查掩码和提取结果。

五个端到端工作流详见 references/typical_workflows.md。各主题的详细说明见 references/slide_management.md、 references/tissue_masks.md、 references/tile_extraction.md、 references/filters_preprocessing.md 和 references/visualization.md。

最佳实践

切片加载与检查

1. 处理前务必检查切片属性
2. 使用 slide.thumbnail.save() 保存缩略图，以便快速目视检查
3. 检查金字塔层级和尺寸
4. 使用缩略图确认是否存在组织

组织检测

1. 提取前使用 locate_mask() 预览掩码
2. 多个组织区域使用 TissueMask，单个组织区域使用 BiggestTissueBoxMask
3. 根据特定染色方式（H&E 与 IHC）自定义滤镜
4. 使用自定义掩码处理记号笔标注
5. 在各种切片上测试掩码

图块提取

1. 提取前务必使用 locate_tiles() 预览
2. 选择合适的切片器：
   • RandomTiler：采样与探索
   • GridTiler：完整覆盖
   • ScoreTiler：基于质量进行筛选
3. 设置合适的 tissue_percent 阈值（通常为 70–90%）
4. 在 RandomTiler 中使用种子，以确保结果可复现
5. 根据分析所需的分辨率选择合适的金字塔层级
6. 处理大型数据集时启用日志记录

性能

1. 使用较低层级（1、2）提取图块，以加快处理速度
2. 在适用情况下，优先使用 BiggestTissueBoxMask 而非 TissueMask
3. 调整 tissue_percent，以减少无效图块尝试
4. 初步探索时限制 n_tiles
5. 对于不重叠的网格，使用 pixel_overlap=0

质量控制

1. 验证图块质量（检查模糊、伪影和焦点）
2. 查看 ScoreTiler 的评分分布
3. 检查评分最高和最低的图块
4. 监控组织覆盖率统计数据
5. 如有需要，根据其他质量指标筛选提取的图块

常见用例

训练深度学习模型

• 使用 RandomTiler 在多个切片上提取均衡的数据集
• 使用带有 NucleiScorer 的 ScoreTiler，聚焦于富含细胞的区域
• 以一致的分辨率提取（层级 0 或层级 1）
• 生成 CSV 报告，以跟踪图块元数据

全切片分析

• 使用 GridTiler 覆盖完整组织
• 在多个金字塔层级提取图像，以进行分层分析
• 使用网格位置保持空间关系
• 使用 pixel_overlap 进行滑动窗口处理

组织表征

• 使用 RandomTiler 对不同区域进行采样
• 使用掩膜量化组织覆盖率
• 使用 HED 分解提取染色特异性信息
• 比较不同切片上的组织模式

质量评估

• 使用 ScoreTiler 确定最佳聚焦区域
• 使用自定义掩膜和过滤器检测伪影
• 评估切片集的染色质量
• 标记有问题的切片，以便人工审核

数据集整理

• 使用 ScoreTiler 优先选择信息丰富的图块
• 按组织百分比筛选图块
• 生成包含图块分数和元数据的报告
• 创建涵盖不同切片和组织类型的分层数据集

故障排除

未提取到图块

• 降低 tissue_percent 阈值
• 确认切片包含组织（检查缩略图）
• 确保 extraction_mask 能覆盖组织区域
• 检查 tile_size 是否适合切片分辨率

背景图块过多

• 启用 check_tissue=True
• 提高 tissue_percent 阈值
• 使用合适的掩膜（TissueMask 或 BiggestTissueBoxMask）
• 自定义掩膜过滤器，以更好地检测组织

提取速度非常慢

• 在较低的金字塔层级提取（level=1 或 2）
• 减少 RandomTiler/ScoreTiler 的 n_tiles
• 采样时使用 RandomTiler，而非 GridTiler
• 使用 BiggestTissueBoxMask，而非 TissueMask

图块中存在伪影

• 实现自定义标注排除掩膜
• 调整过滤器参数以去除伪影
• 提高小目标去除阈值
• 提取后进行质量筛选

不同切片的结果不一致

• 为 RandomTiler 使用相同的种子
• 使用 MacenkoStainNormalizer 或 ReinhardStainNormalizer 进行染色归一化
• 根据染色质量调整 tissue_percent
• 实现针对特定切片的掩膜定制

资源

此技能在 references/ 目录中包含详细的参考文档：

references/slide_management.md

加载、检查和处理全切片图像的综合指南：

• 切片初始化和配置
• 内置示例数据集
• 切片属性和元数据
• 缩略图生成和可视化
• 使用金字塔层级
• 多切片处理工作流
• 最佳实践和常见模式

references/tissue_masks.md

组织检测和掩膜的完整文档：

• TissueMask、BiggestTissueBoxMask、BinaryMask 类
• 组织检测过滤器的工作原理
• 使用过滤器链自定义掩膜
• 掩膜可视化
• 创建自定义矩形掩膜和标注排除掩膜
• 与图块提取集成
• 最佳实践和故障排除

references/tile_extraction.md

图块提取策略的详细说明：

• RandomTiler、GridTiler、ScoreTiler 对比
• 可用的评分器（NucleiScorer、CellularityScorer、自定义评分器）
• 通用参数和特定策略参数
• 使用 locate_tiles() 预览图块
• 提取工作流和 CSV 报告
• 高级模式（多层级、分层）
• 性能优化
• 常见问题的故障排除

references/filters_preprocessing.md

完整的过滤器参考和预处理指南：

• 图像过滤器（颜色转换、阈值处理、对比度）
• 形态学过滤器（膨胀、腐蚀、开运算、闭运算）
• 过滤器组合和串联
• 内置染色归一化（Macenko、Reinhard）和基于过滤器的替代方案
• 常见预处理流程
• 对图块应用过滤器
• 自定义掩膜过滤器
• 质量控制过滤器
• 最佳实践和故障排除

references/visualization.md

全面的可视化指南：

• 显示和保存幻灯片缩略图
• 掩膜可视化技术
• 瓦片位置预览
• 显示提取的瓦片并创建马赛克
• 质量评估可视化
• 多张幻灯片对比
• 滤镜效果可视化
• 导出高分辨率图像和 PDF
• 在 Jupyter 笔记本中进行交互式可视化

使用模式： 参考文件包含深入信息，可支持本文档主技能中介绍的工作流。根据需要加载特定参考文件，以获取详细的实现指南、故障排除信息或高级功能。

Agent 操作流程

1. 检查环境。 确认数据访问权限、去标识化状态以及适用的法规或协议。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会改变结果的值都应询问，不要猜测。
3. 先运行小规模版本。 先使用去标识化样本或合成数据。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 根据临床指南和报告标准检查输出；临床内容须由具备资质的人员审核。
6. 报告。 说明运行的内容（版本、命令、参数）、检查的内容以及仍不确定的事项。

如果发生以下情况	请执行以下操作
数据似乎包含可识别患者身份的信息	停止操作，并在继续处理前询问用户。
这些说明中的函数、标志或端点在已安装版本中不存在	查阅已安装版本自带的文档（help()、--help、官方文档），进行调整并告知用户。切勿编造 API。
必需的输入、标识符或参数含糊不清	询问用户，或在运行前明确说明所作的假设。

诚信规则

• 切勿捏造结果、参数、标识符、引用或统计数据。如果无法运行或验证某项内容，请如实说明。
• 输出仅供具备资质的专业人员辅助决策，不构成医疗建议；切勿将其作为诊断或医嘱呈现。
• 此处与版本相关的细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得同意。

相关技能

• pathml：介绍使用 PathML 3.0.5 进行本地、仅限研究用途的计算病理分析：加载和切分全切片图像（OpenSlide、Bio-Formats）、预处理…
• scientific-slides：为研究演讲制作幻灯片和演示文稿。
• segment-anything-model：采用零样本迁移进行图像分割的基础模型。