histolab

Histolab

概述

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

安装

uv pip install histolab

快速开始

从全切片图像中提取图块的基本工作流：

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)

核心功能

1. 切片管理

加载、检查和处理各种格式的全切片图像。

常见操作：

• 加载 WSI 文件（SVS、TIFF、NDPI 等）
• 访问切片元数据（尺寸、放大倍率、属性）
• 生成缩略图以供可视化
• 处理金字塔图像结构
• 提取特定坐标处的区域

关键类： Slide

参考： references/slide_management.md 包含以下内容的完整文档：

• 切片初始化与配置
• 内置示例数据集（前列腺、卵巢、乳腺、心脏、肾脏组织）
• 访问切片属性和元数据
• 缩略图生成与可视化
• 处理金字塔层级
• 多切片处理工作流

示例工作流：

from histolab.slide import Slide
from histolab.data import prostate_tissue

# Load sample data
prostate_svs, prostate_path = prostate_tissue()

# Initialize slide
slide = Slide(prostate_path, processed_path="output/")

# Inspect properties
print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
print(f"Magnification: {slide.properties.get('openslide.objective-power')}")

# Save thumbnail
slide.save_thumbnail()

2. 组织检测与掩膜

自动识别组织区域并过滤背景和伪影。

常见操作：

• 创建二值组织掩膜
• 检测最大的组织区域
• 排除背景和伪影
• 自定义组织分割
• 移除笔迹标注

关键类： TissueMask、BiggestTissueBoxMask、BinaryMask

参考： references/tissue_masks.md 包含以下内容的完整文档：

• TissueMask：使用自动化过滤器分割所有组织区域
• BiggestTissueBoxMask：返回最大组织区域的边界框（默认）
• BinaryMask：自定义掩膜实现的基类
• 使用 locate_mask() 可视化掩膜
• 创建自定义矩形掩膜和排除标注的掩膜
• 掩膜与图块提取的集成
• 最佳实践与故障排除

示例工作流：

from histolab.masks import TissueMask, BiggestTissueBoxMask

# Create tissue mask for all tissue regions
tissue_mask = TissueMask()

# Visualize mask on slide
slide.locate_mask(tissue_mask)

# Get mask array
mask_array = tissue_mask(slide)

# Use largest tissue region (default for most extractors)
biggest_mask = BiggestTissueBoxMask()

各类掩膜的适用场景：

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

3. 图块提取

使用不同策略从大型 WSI 中提取较小区域。

三种提取策略：

RandomTiler： 提取固定数量、位置随机的图块

• 最适合：采样多样区域、探索性分析、训练数据
• 关键参数：n_tiles、用于保证可复现性的 seed

GridTiler： 按网格模式系统地提取组织中的图块

• 最适合：完整覆盖、空间分析、重建
• 关键参数：用于滑动窗口的 pixel_overlap

ScoreTiler： 根据评分函数提取排名靠前的图块

• 最适合：提取信息量最大的区域、基于质量进行选择
• 关键参数：scorer（NucleiScorer、CellularityScorer、自定义）

常见参数：

• tile_size：图块尺寸（例如 (512, 512)）
• level：提取所用的金字塔层级（0 = 最高分辨率）
• check_tissue：按组织含量过滤图块
• tissue_percent：最低组织覆盖率（默认 80%）
• extraction_mask：定义提取区域的掩膜

参考： references/tile_extraction.md 包含以下内容的完整文档：

• 各种切块策略的详细说明
• 可用的评分器（NucleiScorer、CellularityScorer、自定义）
• 使用 locate_tiles() 预览图块
• 提取工作流与报告
• 高级模式（多层级、分层提取）
• 性能优化与故障排除

示例工作流：

from histolab.tiler import RandomTiler, GridTiler, ScoreTiler
from histolab.scorer import NucleiScorer

# Random sampling (fast, diverse)
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)
random_tiler.extract(slide)

# Grid coverage (comprehensive)
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=0,
    pixel_overlap=0,
    check_tissue=True
)
grid_tiler.extract(slide)

# Score-based selection (most informative)
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    scorer=NucleiScorer(),
    level=0
)
score_tiler.extract(slide, report_path="tiles_report.csv")

提取前务必先预览：

# Preview tile locations on thumbnail
tiler.locate_tiles(slide, n_tiles=20)

4. 筛选器与预处理

应用图像处理筛选器进行组织检测、质量控制和预处理。

筛选器类别：

图像筛选器： 色彩空间转换、阈值处理、对比度增强

• RgbToGrayscale、RgbToHsv、RgbToHed
• OtsuThreshold、AdaptiveThreshold
• StretchContrast、HistogramEqualization

形态学筛选器： 对二值图像执行结构操作

• BinaryDilation、BinaryErosion
• BinaryOpening、BinaryClosing
• RemoveSmallObjects、RemoveSmallHoles

组合： 将多个筛选器串联起来

• Compose：创建筛选器流水线

参考： references/filters_preprocessing.md 中包含以下内容的全面文档：

• 各类筛选器的详细说明
• 筛选器的组合与串联
• 常见预处理流水线（组织检测、笔迹去除、细胞核增强）
• 对图块应用筛选器
• 自定义掩码筛选器
• 质量控制筛选器（模糊检测、组织覆盖率）
• 最佳实践与故障排除

工作流示例：

from histolab.filters.compositions import Compose
from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
from histolab.filters.morphological_filters import (
    BinaryDilation, RemoveSmallHoles, RemoveSmallObjects
)

# Standard tissue detection pipeline
tissue_detection = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=5),
    RemoveSmallHoles(area_threshold=1000),
    RemoveSmallObjects(area_threshold=500)
])

# Use with custom mask
from histolab.masks import TissueMask
custom_mask = TissueMask(filters=tissue_detection)

# Apply filters to tile
from histolab.tile import Tile
filtered_tile = tile.apply_filters(tissue_detection)

5. 可视化

可视化切片、掩码、图块位置和提取质量。

常见可视化任务：

• 显示切片缩略图
• 可视化组织掩码
• 预览图块位置
• 评估图块质量
• 创建报告和图表

参考： references/visualization.md 中包含以下内容的全面文档：

• 显示和保存切片缩略图
• 使用 locate_mask() 可视化掩码
• 使用 locate_tiles() 预览图块位置
• 显示提取的图块和拼接图
• 质量评估（分数分布、得分最高与最低的图块）
• 多切片可视化
• 筛选器效果可视化
• 导出高分辨率图表和 PDF 报告
• 在 Jupyter notebooks 中进行交互式可视化

工作流示例：

import matplotlib.pyplot as plt
from histolab.masks import TissueMask

# Display slide thumbnail
plt.figure(figsize=(10, 10))
plt.imshow(slide.thumbnail)
plt.title(f"Slide: {slide.name}")
plt.axis('off')
plt.show()

# Visualize tissue mask
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Preview tile locations
tiler = RandomTiler(tile_size=(512, 512), n_tiles=50)
tiler.locate_tiles(slide, n_tiles=20)

# Display extracted tiles in grid
from pathlib import Path
from PIL import Image

tile_paths = list(Path("output/tiles/").glob("*.png"))[:16]
fig, axes = plt.subplots(4, 4, figsize=(12, 12))
axes = axes.ravel()

for idx, tile_path in enumerate(tile_paths):
    tile_img = Image.open(tile_path)
    axes[idx].imshow(tile_img)
    axes[idx].set_title(tile_path.stem, fontsize=8)
    axes[idx].axis('off')

plt.tight_layout()
plt.show()

典型工作流

工作流 1：探索性图块提取

快速采样不同组织区域，用于初步分析。

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

# Enable logging for progress tracking
logging.basicConfig(level=logging.INFO)

# Load slide
slide = Slide("slide.svs", processed_path="output/random_tiles/")

# Inspect slide
print(f"Dimensions: {slide.dimensions}")
print(f"Levels: {slide.levels}")
slide.save_thumbnail()

# Configure random tiler
random_tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=100,
    level=0,
    seed=42,
    check_tissue=True,
    tissue_percent=80.0
)

# Preview locations
random_tiler.locate_tiles(slide, n_tiles=20)

# Extract tiles
random_tiler.extract(slide)

工作流 2：全面网格提取

完整覆盖组织区域，用于全切片分析。

from histolab.slide import Slide
from histolab.tiler import GridTiler
from histolab.masks import TissueMask

# Load slide
slide = Slide("slide.svs", processed_path="output/grid_tiles/")

# Use TissueMask for all tissue sections
tissue_mask = TissueMask()
slide.locate_mask(tissue_mask)

# Configure grid tiler
grid_tiler = GridTiler(
    tile_size=(512, 512),
    level=1,  # Use level 1 for faster extraction
    pixel_overlap=0,
    check_tissue=True,
    tissue_percent=70.0
)

# Preview grid
grid_tiler.locate_tiles(slide)

# Extract all tiles
grid_tiler.extract(slide, extraction_mask=tissue_mask)

工作流 3：基于质量的图块筛选

根据细胞核密度提取信息量最高的图块。

from histolab.slide import Slide
from histolab.tiler import ScoreTiler
from histolab.scorer import NucleiScorer
import pandas as pd
import matplotlib.pyplot as plt

# Load slide
slide = Slide("slide.svs", processed_path="output/scored_tiles/")

# Configure score tiler
score_tiler = ScoreTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    scorer=NucleiScorer(),
    check_tissue=True
)

# Preview top tiles
score_tiler.locate_tiles(slide, n_tiles=15)

# Extract with report
score_tiler.extract(slide, report_path="tiles_report.csv")

# Analyze scores
report_df = pd.read_csv("tiles_report.csv")
plt.hist(report_df['score'], bins=20, edgecolor='black')
plt.xlabel('Tile Score')
plt.ylabel('Frequency')
plt.title('Distribution of Tile Scores')
plt.show()

工作流 4：多切片处理流水线

使用一致的参数处理整个切片集。

from pathlib import Path
from histolab.slide import Slide
from histolab.tiler import RandomTiler
import logging

logging.basicConfig(level=logging.INFO)

# Configure tiler once
tiler = RandomTiler(
    tile_size=(512, 512),
    n_tiles=50,
    level=0,
    seed=42,
    check_tissue=True
)

# Process all slides
slide_dir = Path("slides/")
output_base = Path("output/")

for slide_path in slide_dir.glob("*.svs"):
    print(f"\nProcessing: {slide_path.name}")

    # Create slide-specific output directory
    output_dir = output_base / slide_path.stem
    output_dir.mkdir(parents=True, exist_ok=True)

    # Load and process slide
    slide = Slide(slide_path, processed_path=output_dir)

    # Save thumbnail for review
    slide.save_thumbnail()

    # Extract tiles
    tiler.extract(slide)

    print(f"Completed: {slide_path.name}")

工作流 5：自定义组织检测与筛选

处理带有伪影、标注或染色异常的切片。

from histolab.slide import Slide
from histolab.masks import TissueMask
from histolab.tiler import RandomTiler
from histolab.filters.compositions import Compose
from histolab.filters.image_filters import RgbToGrayscale, OtsuThreshold
from histolab.filters.morphological_filters import (
    BinaryDilation, RemoveSmallObjects, RemoveSmallHoles
)

# Define custom filter pipeline for aggressive artifact removal
aggressive_filters = Compose([
    RgbToGrayscale(),
    OtsuThreshold(),
    BinaryDilation(disk_size=10),
    RemoveSmallHoles(area_threshold=5000),
    RemoveSmallObjects(area_threshold=3000)  # Remove larger artifacts
])

# Create custom mask
custom_mask = TissueMask(filters=aggressive_filters)

# Load slide and visualize mask
slide = Slide("slide.svs", processed_path="output/")
slide.locate_mask(custom_mask)

# Extract with custom mask
tiler = RandomTiler(tile_size=(512, 512), n_tiles=100)
tiler.extract(slide, extraction_mask=custom_mask)

最佳实践

切片加载与检查

1. 处理前始终检查切片属性
2. 保存缩略图以便快速目视检查
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，聚焦细胞丰富的区域
• 以一致的分辨率提取（level 0 或 level 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 使用相同的 seed
• 使用预处理过滤器对染色进行归一化
• 根据染色质量调整 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

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

• 图像过滤器（颜色转换、阈值处理、对比度）
• 形态学过滤器（膨胀、腐蚀、开运算、闭运算）
• 过滤器组合和串联
• 常见预处理流程
• 对切片块应用过滤器
• 自定义掩码过滤器
• 质量控制过滤器
• 最佳实践和故障排除

references/visualization.md

全面的可视化指南：

• 幻灯片缩略图显示与保存
• 掩码可视化技术
• 图块位置预览
• 显示提取的图块并创建拼图
• 质量评估可视化
• 多张幻灯片对比
• 筛选效果可视化
• 导出高分辨率图表和 PDF
• 在 Jupyter 笔记本中进行交互式可视化

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