当前位置：首页 > news >正文

【WSI/QuPath实战】三步定制化导出病理切片：从脚本调参到批量处理

news 2026/6/17 12:09:48

1. 为什么需要定制化导出病理切片？

在病理AI研究领域，我们常常需要处理各种不同来源的WSI（全视野数字切片）数据。这些数据可能来自不同的扫描仪，采用不同的放大倍数（20x、40x等），包含不同类型的组织（如乳腺、肺、前列腺等）。更复杂的是，下游的AI模型对输入数据的要求也各不相同：有的分类模型需要10x的512×512图像，有的分割模型可能需要20x的1024×1024图像，并且要求有重叠区域。

我刚开始做病理AI研究时，最头疼的就是每次换一个数据集或者换一个模型，就得重新折腾一遍数据预处理。要么导出的图像尺寸不对，要么放大倍数不匹配，要么白白浪费存储空间导出了大量无用的空白区域。后来我发现，QuPath的Groovy脚本其实提供了非常灵活的导出参数配置，只需要掌握几个关键参数的调整方法，就能轻松应对各种导出需求。

2. 准备工作与环境配置

2.1 安装QuPath与创建项目

首先需要下载并安装QuPath，这个过程非常简单：

访问QuPath官网下载最新版本（目前稳定版是0.3.2）
根据操作系统选择对应的安装包（Windows/macOS/Linux都支持）
安装完成后启动QuPath，创建一个新项目

创建项目时有个小技巧：建议把项目文件夹放在SSD硬盘上，因为WSI文件通常都很大（可能达到几个GB），SSD能显著提升加载速度。我习惯的项目目录结构是这样的：

MyProject/ ├── slides/ # 存放原始WSI文件 ├── annotations/ # 存放标注文件 └── scripts/ # 存放Groovy脚本

2.2 理解WSI的多分辨率特性

在开始导出切片前，有必要理解WSI的多分辨率金字塔结构。简单来说，WSI在扫描时通常会保存多个放大倍数的图像数据。比如一张40x扫描的WSI，实际上包含了40x、20x、10x、5x等多个分辨率层级的数据。这种设计让我们可以快速浏览整张切片，同时在需要时又能查看高倍率的细节。

在QuPath中可以通过以下代码查看当前WSI的分辨率信息：

def server = getCurrentServer() println "像素大小(μm): " + server.getPixelCalibration().getAveragedPixelSizeMicrons() println "放大倍数: " + server.getMetadata().getMagnification()

3. 基础导出脚本解析

3.1 核心参数详解

让我们从一个基础导出脚本开始，逐步分析每个参数的作用：

extension = '.jpg' // 输出图像格式 def imageData = getCurrentImageData() def name = GeneralTools.getNameWithoutExtension(imageData.getServer().getMetadata().getName()) def pathOutput = buildFilePath(PROJECT_BASE_DIR, '../tiles-10x', name) mkdirs(pathOutput) double downsample = 4 // 下采样系数 int outputSize = 512 // 输出图像尺寸 int overLap = 0 // 重叠像素 new TileExporter(imageData) .downsample(downsample) .imageExtension(extension) .tileSize(outputSize) .overlap(overLap) .writeTiles(pathOutput)

关键参数说明：

downsample：这个参数决定了导出图像的放大倍数。计算方法是：导出倍数=原始倍数/downsample。例如原始是40x，downsample=4，则导出10x图像。
outputSize：每张patch的像素尺寸。512是常用值，但有些模型可能需要更大尺寸。
overLap：相邻patch之间的重叠像素数。设置重叠可以避免组织被切割，对分割任务特别重要。

3.2 输出格式选择

输出图像格式对后续处理影响很大，常见选择有：

JPG：有损压缩，文件小（约是PNG的1/5），适合分类任务
PNG：无损压缩，文件大，适合需要精确像素值的分割任务
TIFF：无损压缩，支持多通道，但文件非常大

我曾经做过一个对比测试：导出1000张512×512的patch：

JPG质量90%：总共约60MB
PNG：总共约300MB
TIFF：总共约800MB

除非特别需要，一般建议使用JPG格式，可以节省大量存储空间。

4. 高级导出技巧

4.1 仅导出标注区域

很多WSI包含大量空白区域，导出这些区域既浪费时间又浪费存储空间。QuPath提供了两种方式来只导出有组织的区域：

// 方式1：导出所有包含标注的patch .annotatedTilesOnly(true) // 方式2：只导出中心点位于标注内的patch .annotatedCentroidTilesOnly(true)

这两种方式的区别我用一个实际案例来说明：假设有一个大的肿瘤标注，方式1会导出所有与这个标注有交集的patch，方式2则只导出中心点落在标注内的patch。方式2导出的patch数量更少，但能确保每个patch都包含足够的组织区域。

4.2 多分辨率导出策略

有时候我们需要为同一个模型提供不同放大倍数的数据。比如可以先在低倍率下定位感兴趣区域，然后在高倍率下观察细节。这时可以这样设置：

// 定义多个下采样系数 def downsamples = [1, 4, 16] // 对应40x,10x,2.5x downsamples.each { ds -> def outputPath = buildFilePath(PROJECT_BASE_DIR, "../tiles-${ds}x", name) mkdirs(outputPath) new TileExporter(imageData) .downsample(ds) .tileSize(outputSize) .writeTiles(outputPath) }

4.3 批量处理整个项目

当需要处理大量WSI时，逐个运行脚本效率太低。QuPath提供了批量处理功能：

在Script Editor中点击右侧的"Run for project"按钮
选择要处理的图像（可以全选或部分选择）
脚本会自动在所有选中的图像上运行

我处理过包含200多张WSI的项目，使用批量处理功能加上多线程优化，整个导出过程可以在1小时内完成，而手动操作可能需要一整天。

5. 实战案例与性能优化

5.1 乳腺病理切片导出案例

假设我们有一批40x扫描的乳腺病理切片，需要为分类模型准备10x的512×512图像，并且只导出肿瘤区域。脚本可以这样配置：

extension = '.jpg' def imageData = getCurrentImageData() def name = GeneralTools.getNameWithoutExtension(imageData.getServer().getMetadata().getName()) def pathOutput = buildFilePath(PROJECT_BASE_DIR, '../breast-tumor-tiles', name) mkdirs(pathOutput) new TileExporter(imageData) .downsample(4) // 40x→10x .imageExtension(extension) .tileSize(512) .annotatedCentroidTilesOnly(true) // 只导出肿瘤中心区域 .overlap(64) // 设置重叠避免切割细胞 .writeTiles(pathOutput)

5.2 性能优化技巧

在处理大型WSI时，导出速度可能成为瓶颈。以下是我总结的几个优化技巧：

使用SSD存储：相比HDD，SSD可以提升2-3倍的导出速度
适当增加内存：在QuPath的启动配置中增加内存分配（编辑QuPath.cfg文件）
调整tile大小：较大的tile（如1024×1024）比较小的tile（如256×256）处理效率更高
关闭实时预览：在Edit→Preferences→Viewer中关闭"Show overview"和"Show locations"

在我的测试中，通过这些优化，一张典型的WSI（约80,000×60,000像素）的导出时间可以从原来的30秒缩短到10秒左右。

5.3 常见问题排查

问题1：导出的图像全是黑色的

原因：可能是图像通道问题，尝试添加.includeProbabilityMaps(false)

问题2：导出过程中内存不足

解决方法：增加QuPath内存分配，或者减小tile size

问题3：导出的图像放大倍数不对

检查点：确认原始WSI的扫描倍数和downsample参数的计算是否正确

问题4：批处理时部分图像失败

解决方法：先单独运行失败的图像，查看具体错误信息

6. 与其他工具的集成

6.1 与Python生态的衔接

虽然我们主要使用Groovy脚本进行导出，但后续的分析通常会在Python中进行。为了便于衔接，我通常会做以下处理：

在导出时规范命名：

// 在导出循环中添加前缀 def newName = "slide_${name}_x${x}_y${y}_ds${downsample}.jpg"

生成对应的CSV索引文件：

def csvFile = new File(pathOutput, "metadata.csv") csvFile.withWriter { writer -> writer.writeLine("filename,slide,x,y,downsample") // 在导出循环中记录每个patch的信息 writer.writeLine("${newName},${name},${x},${y},${downsample}") }

6.2 在深度学习框架中使用

导出的patch可以直接用于主流深度学习框架。以PyTorch为例，可以这样创建DataLoader：

from torch.utils.data import Dataset, DataLoader from PIL import Image import pandas as pd class WsiDataset(Dataset): def __init__(self, csv_file, transform=None): self.metadata = pd.read_csv(csv_file) self.transform = transform def __len__(self): return len(self.metadata) def __getitem__(self, idx): img_path = self.metadata.iloc[idx, 0] image = Image.open(img_path) if self.transform: image = self.transform(image) return image # 使用示例 dataset = WsiDataset('path/to/metadata.csv') dataloader = DataLoader(dataset, batch_size=32, shuffle=True)

7. 扩展应用与自定义开发

7.1 添加图像预处理

有时我们需要在导出时对图像进行预处理，比如颜色归一化或增强对比度。这可以通过在导出前添加处理步骤来实现：

import qupath.lib.images.servers.ImageServer import qupath.lib.images.servers.PixelCalibration // 自定义图像处理函数 def processImage(server, region) { def img = server.readRegion(region) // 在这里添加处理代码，例如： // 1. 颜色去卷积 // 2. 对比度拉伸 // 3. 颜色归一化 return img } // 修改TileExporter使用处理后的图像 new TileExporter(imageData) .downsample(downsample) .imageExtension(extension) .tileSize(outputSize) .imageRegion { region -> processImage(imageData.getServer(), region) } .writeTiles(pathOutput)

7.2 导出多通道图像

对于特殊染色或荧光图像，我们可能需要导出多通道数据。这时可以使用OME-TIFF格式：

extension = '.ome.tif' new TileExporter(imageData) .downsample(downsample) .imageExtension(extension) .tileSize(outputSize) .omeXmlOptions { options -> options.compression = ome.units.UNITS.MICROMETER options.pixelType = ome.xml.model.PixelType.UINT16 } .writeTiles(pathOutput)