🔱 三叉戟

arXiv | 博客 | 引用 | 文档 | 许可证

Trident 是一个用于大规模全切片图像处理的工具包。 该项目由哈佛医学院和布莱根妇女医院的 Mahmood 实验室 开发。本研究得到了美国国立卫生研究院 NIGMS R35GM138216 的资助。

[!注意] 欢迎大家贡献！请报告任何问题。您也可以通过提交拉取请求来参与贡献。

核心功能：

• 组织分割：从背景中提取组织（H&E、IHC 等）。
• 补丁提取：提取任意大小和放大倍数的组织补丁。
• 补丁特征提取：从 20 多种基础模型中提取补丁嵌入，包括 UNI、Virchow、H-Optimus-0 等等……
• 切片特征提取：从 5 种以上的切片基础模型中提取切片嵌入，包括 Threads（即将推出！）、Titan 和 GigaPath。

更新：

• 07.25：支持 Feather 模型。
• 05.25：新增基于批次的 WSI 缓存功能，以便在有限的 SSD 空间上进行可扩展处理 + 嵌套式 WSI 搜索（--search_nested）。
• 04.25：原生支持 PIL.Image 和 CuCIM（使用 wsi = load_wsi(xxx.svs)）。无需互联网即可进行组织分割和补丁编码。
• 04.25：通过 --remove_artifacts 和 --remove_penmarks 从组织分割结果中去除伪影和笔迹。
• 02.25：新增从 czi、png 等格式到 tiff 的图像转换器。
• 02.25：支持 GrandQC（需要引用，非商业用途，原始仓库）的组织与背景分割。
• 02.25：支持 Madeleine、Hibou、Lunit、Kaiko 和 H-Optimus-1 模型。

[!注意] GrandQC 已根据 CC BY-NC-SA 4.0 许可证集成到 Trident 中。如果您使用 GrandQC，请引用其 原始论文。

🔨 1. 安装：

• 创建环境（Python 3.10 或 3.11）：conda create -n "trident" python=3.10，并激活它：conda activate trident。
• 克隆：git clone https://github.com/mahmoodlab/trident.git && cd trident。
• 本地安装：pip install -e .。
  • 这将安装共享的模型栈（transformers、timm、safetensors 等）。

可选安装配置：

• pip install -e ".[patch-encoders]" 用于 CONCH/MUSK/CTransPath 相关的附加功能。
• pip install -e ".[slide-encoders]" 用于 PRISM/GigaPath/Madeleine 相关的附加功能。
• pip install -e ".[omezarr]" 用于支持 OME Zarr WSI 阅读器。
• pip install -e ".[convert]" 用于切片转换相关的依赖项。
• pip install -e ".[full]" 安装所有可通过 pip 安装的可选依赖项。

在启动任务前运行检查：

• trident-doctor --profile base
• trident-doctor --profile patch-encoders --check-gated
• trident-doctor --profile slide-encoders
• trident-doctor --profile convert
• trident-doctor --profile full --check-gated

[!注意] 一些模型仍需手动设置（例如，在 trident/slide_encoder_models/local_ckpts.json 中指定本地 CHIEF 仓库路径），或需要 HuggingFace 的访问权限批准。

🔨 2. 运行 Trident：

CLI 选项（全部支持）：

• python run_batch_of_slides.py ...（现有命令）
• python run_single_slide.py ...（现有命令）
• trident batch ...、trident single ...、trident convert ... 和 trident doctor ...（封装 CLI）

已经熟悉 WSI 处理？ 可以从一个包含 WSI 的目录中执行分割、补丁提取和 UNI 特征提取：

python run_batch_of_slides.py --task all --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

等效的封装 CLI：

trident batch -- --task all --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

想谨慎一点吗？

运行以下命令对 单张 切片执行所有处理步骤：

python run_single_slide.py --slide_path ./wsis/xxxx.svs --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

等效的封装 CLI：

trident single -- --slide_path ./wsis/xxxx.svs --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

将图像/WSI 转换为金字塔 TIFF：

trident convert --input_dir ./wsis --mpp_csv ./wsis/to_process.csv --job_dir ./pyramidal_tiff --downscale_by 1 --num_workers 1

--mpp_csv 是必需的，必须包含 wsi,mpp 列。只有 CSV 中列出的文件会被转换。如果检测到切片中嵌入了 MPP 元数据，Trident 会将其与 CSV 中的值进行比较，并记录不匹配的情况。

或者按照逐步指南操作：

步骤 1：组织分割：从一组 WSI 中分割出组织与背景

• 命令：

  python run_batch_of_slides.py --task seg --wsi_dir ./wsis --job_dir ./trident_processed --gpu 0 --segmenter hest
  

  • --task seg：指定要进行组织分割。
  • --wsi_dir ./wsis：您的 WSI 所在目录的路径。
  • --job_dir ./trident_processed：处理结果的输出目录。
  • --gpu 0：使用索引为 0 的 GPU。
• --segmenter：分割模型。默认是 hest。可以使用 grandqc（需要引用，非商业用途，原始仓库）进行快速的 H&E 分割，或使用 otsu 作为经典的纯图像处理回退方案。添加选项 --remove_artifacts 可进一步清除伪影。
• 输出：
  • 在 ./trident_processed/thumbnails 中生成 WSI 缩略图。
  • 在 ./trident_processed/contours 中生成带有组织轮廓的 WSI 缩略图。
  • 在 ./trident_processed/contours_geojson 中生成包含组织轮廓的 GeoJSON 文件。如有必要，这些文件可以在 QuPath 中打开进行编辑或质量控制。

步骤 2：组织切片补丁提取：在特定放大倍数下，从分割后的组织区域中提取补丁。

• 命令：

  python run_batch_of_slides.py --task coords --wsi_dir ./wsis --job_dir ./trident_processed --mag 20 --patch_size 256 --overlap 0
  

  • --task coords：指定执行补丁提取操作。
  • --wsi_dir wsis：WSI 文件所在的目录路径。
  • --job_dir ./trident_processed：处理结果的输出目录。
  • --mag 20：以 20 倍放大倍数提取补丁。
  • --patch_size 256：每个补丁的尺寸为 256×256 像素。
  • --overlap 0：补丁之间无重叠（始终使用像素数表示，例如，对于 256×256 的补丁，若需 50% 重叠，则应设置为 --overlap 128）。
• 输出：
  • 补丁坐标以 h5 文件形式保存在 ./trident_processed/20x_256px/patches 目录中。
  • 带有补丁边界的 WSI 缩略图保存在 ./trident_processed/20x_256px/visualization 目录中。

步骤 3a：补丁特征提取：使用指定的编码器从组织补丁中提取特征。

• 命令：

  python run_batch_of_slides.py --task feat --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256 
  

  • --task feat：指定执行特征提取操作。
  • --wsi_dir wsis：WSI 文件所在的目录路径。
  • --job_dir ./trident_processed：处理结果的输出目录。
  • --patch_encoder uni_v1：使用 UNI 补丁编码器。支持的模型列表见下文。
  • --mag 20：在 20 倍放大倍数下从补丁中提取特征。
  • --patch_size 256：补丁尺寸为 256×256 像素。
• 输出：
  • 特征以 h5 文件形式保存在 ./trident_processed/20x_256px/features_uni_v1 目录中。（形状：(n_patches, feature_dim)）

Trident 支持 24 种补丁编码器，可通过补丁 encoder_factory 加载。需要特定安装的模型会返回包含额外说明的错误信息。HuggingFace 上的门控模型需要提交访问申请。

补丁编码器	嵌入维度	参数	链接
UNI	1024	--patch_encoder uni_v1 --patch_size 256 --mag 20	MahmoodLab/UNI
UNI2-h	1536	--patch_encoder uni_v2 --patch_size 256 --mag 20	MahmoodLab/UNI2-h
CONCH	512	--patch_encoder conch_v1 --patch_size 512 --mag 20	MahmoodLab/CONCH
CONCHv1.5	768	--patch_encoder conch_v15 --patch_size 512 --mag 20	MahmoodLab/conchv1_5
Virchow	2560	--patch_encoder virchow --patch_size 224 --mag 20	paige-ai/Virchow
Virchow2	2560	--patch_encoder virchow2 --patch_size 224 --mag 20	paige-ai/Virchow2
Phikon	768	--patch_encoder phikon --patch_size 224 --mag 20	owkin/phikon
Phikon-v2	1024	--patch_encoder phikon_v2 --patch_size 224 --mag 20	owkin/phikon-v2
Prov-Gigapath	1536	--patch_encoder gigapath --patch_size 256 --mag 20	prov-gigapath
H-Optimus-0	1536	--patch_encoder hoptimus0 --patch_size 224 --mag 20	bioptimus/H-optimus-0
H-Optimus-1	1536	--patch_encoder hoptimus1 --patch_size 224 --mag 20	bioptimus/H-optimus-1
H0-mini	768/1536	--patch_encoder h0-mini --patch_size 224 --mag 20	bioptimus/H0-mini
MUSK	1024	--patch_encoder musk --patch_size 384 --mag 20	xiangjx/musk
Midnight-12k	3072	--patch_encoder midnight12k --patch_size 224 --mag 20	kaiko-ai/midnight
OpenMidnight	1536	--patch_encoder openmidnight --patch_size 224 --mag 20	SophontAI/OpenMidnight
GPFM	1024	--patch_encoder gpfm --patch_size 224 --mag 20	majiabo/GPFM
GenBio-PathFM	4608	--patch_encoder genbio-pathfm --patch_size 224 --mag 20	genbio-ai/genbio-pathfm
Kaiko	384/768/1024	--patch_encoder {kaiko-vits8, kaiko-vits16, kaiko-vitb8, kaiko-vitb16, kaiko-vitl14} --patch_size 256 --mag 20	1aurent/kaikoai-models-66636c99d8e1e34bc6dcf795
Lunit	384	--patch_encoder lunit-vits8 --patch_size 224 --mag 20	1aurent/vit_small_patch8_224.lunit_dino
Hibou	1024	--patch_encoder hibou_l --patch_size 224 --mag 20	histai/hibou-L
CTransPath-CHIEF	768	--patch_encoder ctranspath --patch_size 256 --mag 10	—
ResNet50	1024	--patch_encoder resnet50 --patch_size 256 --mag 20	—

步骤 3b：幻灯片特征提取：使用幻灯片编码器提取幻灯片嵌入。同时也会自动提取正确的补丁嵌入。

• 命令：

  python run_batch_of_slides.py --task feat --wsi_dir ./wsis --job_dir ./trident_processed --slide_encoder titan --mag 20 --patch_size 512 
  

  • --task feat：指定要进行特征提取。
  • --wsi_dir wsis：包含WSI的目录路径。
  • --job_dir ./trident_processed：处理结果的输出目录。
  • --slide_encoder titan：使用Titan幻灯片编码器。支持的模型见下文。
  • --mag 20：在20倍放大倍率下从补丁中提取特征。
  • --patch_size 512：补丁大小为512×512像素。
• 输出：
  • 特征以h5文件格式保存在./trident_processed/20x_256px/slide_features_titan中。（形状：(feature_dim)）

Trident支持5种幻灯片编码器，通过幻灯片级别的encoder_factory加载。需要特定安装的模型会返回带有额外说明的错误信息。HuggingFace上的门控模型需要申请访问权限。

演示板编码器	补丁编码器	参数	链接
Threads	conch_v15	--slide_encoder threads --patch_size 512 --mag 20	(即将推出！)
Titan	conch_v15	--slide_encoder titan --patch_size 512 --mag 20	MahmoodLab/TITAN
PRISM	virchow	--slide_encoder prism --patch_size 224 --mag 20	paige-ai/Prism
CHIEF	ctranspath	--slide_encoder chief --patch_size 256 --mag 10	CHIEF
GigaPath	gigapath	--slide_encoder gigapath --patch_size 256 --mag 20	prov-gigapath
Madeleine	conch_v1	--slide_encoder madeleine --patch_size 256 --mag 10	MahmoodLab/madeleine
Feather	conch_v15	--slide_encoder feather --patch_size 512 --mag 20	MahmoodLab/FEATHER

[!注意] 如果您的任务涉及每位患者有多张幻灯片，您可以通过以下方式生成患者级别的嵌入：(1) 独立处理每张幻灯片并取其平均幻灯片嵌入（晚期融合），或 (2) 将所有补丁合并在一起，将其作为单个“伪幻灯片”进行处理（早期融合）。有关这两种融合策略的实现，请查看我们的姊妹仓库Patho-Bench。

请参阅我们的教程以获取更多支持，以及详细自述文件以了解其他功能。

🙋 常见问题解答

• 问：如何从使用CLAM提取的旧版补丁坐标中提取补丁嵌入？

  • 答：

    python run_batch_of_slides.py --task feat --wsi_dir ..wsis --job_dir legacy_dir --patch_encoder uni_v1 --mag 20 --patch_size 256 --coords_dir extracted_mag20x_patch256_fp/
    

• 问：如何保留对应于组织中孔洞的补丁？

  • 答：在run_batch_of_slides中，此行为是默认设置。将--remove_holes设置为排除位于孔洞上的补丁。

• 问：使用timm构建模型时，我看到一些奇怪的消息。这是怎么回事？

  • 答：请确保已安装timm==0.9.16。timm==1.X.X会导致大多数模型出现问题。

• 问：如何在其他仓库中以最少的工作量使用run_single_slide.py和run_batch_of_slides.py？

  • 答：确保已使用pip install -e .安装了trident。然后，这两个脚本将被公开，并可集成到任何Python代码中，例如：

import sys 
from run_single_slide import main

sys.argv = [
    "run_single_slide",
    '--slide_path', "output/wsis/394140.svs",
    "--job_dir", 'output/',
    "--mag", "20",
    "--patch_size", '256'
]

main()

• 问：我对组织与背景的分割效果不满意。该怎么办？

  • 答：Trident使用GeoJSON来存储和加载分割结果。这种格式由QuPath原生支持。您可以将Trident的分割结果导入QuPath，使用QuPath的标注工具进行修改，然后将更新后的分割结果保存回GeoJSON。
  • 答：您也可以尝试使用其他分割模型，通过指定--segmenter grandqc（需注明引用来源《自然通讯》，仅限非商业用途知识共享署名-非商业性-相同方式共享4.0国际许可协议，原始仓库地址为GitHub上的cpath-ukk/grandqc)或--segmenter otsu。

• 问：我想处理一个自定义的WSI列表。可以吗？另外，我的大部分WSI都没有存储每像素微米数（mpp）。我可以传递这个值吗？

  • 答：可以，使用--custom_list_of_wsis参数。提供一个包含WSI名称的CSV文件（带幻灯片扩展名，wsi）。可选地，提供mpp值（字段mpp）。

• 问：使用Trident是否需要安装任何额外的软件包？

  • 答：运行pip install -e .会安装核心依赖项。但某些可选组件仍需额外安装。请使用配置文件（.[patch-encoders]、.[slide-encoders]、.[convert]、.[omezarr]或.[full]）并运行trident-doctor进行飞行前检查。

许可证与使用条款

ⓒ Mahmood Lab。本仓库根据CC-BY-NC-ND 4.0许可证发布，仅可用于非商业性的学术研究目的，并需正确注明出处。任何商业用途、销售或其他盈利行为均被禁止，且须事先获得批准。下载任何预训练编码器即表示您同意遵守该模型各自的许可证。

致谢

该项目建立在许多优秀的开源项目之上，如Timm、HuggingFace以及社区的开源贡献。我们感谢各位作者和开发人员的贡献。

问题

• 推荐的沟通方式是通过GitHub问题。
• 如果GitHub问题不合适，请发送邮件至guillaume.jaume@unil.ch和andrewzh@mit.edu。
• 对于小问题，可能无法立即得到回复。

资助

本工作由美国国立卫生研究院NIGMS资助，项目编号为R35GM138216。

如何引用

如果您在研究中认为我们的工作有所帮助，或者使用了本代码的部分内容，请考虑引用我们的论文：

@article{zhang2025standardizing,
  title={加速病理学人工智能模型的数据处理与基准测试},
  author={Zhang, Andrew 和 Jaume, Guillaume 和 Vaidya, Anurag 和 Ding, Tong 和 Mahmood, Faisal},
  journal={arXiv 预印本 arXiv:2502.06750},
  year={2025}
}

@article{vaidya2025molecular,
  title={面向肿瘤病理学的分子驱动型基础模型},
  author={Vaidya, Anurag 和 Zhang, Andrew 和 Jaume, Guillaume 和 Song, Andrew H 和 Ding, Tong 和 Wagner, Sophia J 和 Lu, Ming Y 和 Doucet, Paul 和 Robertson, Harry 和 Almagro-Perez, Cristina 等},
  journal={arXiv 预印本 arXiv:2501.16652},
  year={2025}
}

TRIDENT 快速上手指南

TRIDENT 是由哈佛医学院 Mahmood 实验室开发的大规模全切片图像（WSI）处理工具包，支持组织分割、图块提取及基于多种基础模型的特征提取。

1. 环境准备

• 操作系统：Linux 推荐（Windows/macOS 需额外配置依赖）
• Python 版本：3.10 或 3.11
• 硬件要求：
  • 建议配备 NVIDIA GPU（用于加速分割和特征提取）
  • 充足的磁盘空间用于存储 WSI 文件及处理结果
• 前置依赖：
  • Conda（推荐用于环境管理）
  • Git

💡 国内加速建议：建议使用清华或中科大镜像源加速 Conda 和 Pip 包的下载。

• Conda 配置：conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
• Pip 配置：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装步骤

2.1 创建并激活虚拟环境

conda create -n "trident" python=3.10
conda activate trident

2.2 克隆代码仓库

git clone https://github.com/mahmoodlab/trident.git && cd trident

2.3 安装核心依赖

安装基础版本（包含共享模型栈）：

pip install -e .

如需使用特定功能，可选择以下可选安装配置：

• 图块编码器（如 CONCH, MUSK, CTransPath）：

  pip install -e ".[patch-encoders]"
  

• 切片编码器（如 PRISM, GigaPath, Madeleine）：

  pip install -e ".[slide-encoders]"
  

• OME Zarr 格式支持：

  pip install -e ".[omezarr]"
  

• 图像格式转换支持：

  pip install -e ".[convert]"
  

• 安装所有可选依赖：

  pip install -e ".[full]"
  

2.4 运行环境检查

在开始任务前，建议运行诊断命令确保环境配置正确：

trident-doctor --profile base
# 若安装了额外组件，可分别检查
trident-doctor --profile patch-encoders --check-gated
trident-doctor --profile slide-encoders

⚠️ 注意：部分模型（如 HuggingFace 上的受限模型）需要手动申请访问权限或在本地配置路径。

3. 基本使用

TRIDENT 提供命令行接口（CLI），支持单张幻灯片处理或批量处理。

3.1 一键全流程处理（推荐）

对目录下的所有 WSI 执行组织分割、图块提取及 UNI 模型特征提取：

python run_batch_of_slides.py --task all --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

或使用封装后的 CLI 命令：

trident batch -- --task all --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

参数说明：

• --wsi_dir: 输入 WSI 文件目录
• --job_dir: 输出结果目录
• --patch_encoder: 使用的预训练模型（如 uni_v1）
• --mag: 提取倍率（如 20x）
• --patch_size: 图块尺寸（像素）

3.2 单张幻灯片测试

初次使用建议先对单张幻灯片进行测试：

python run_single_slide.py --slide_path ./wsis/xxxx.svs --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256

3.3 分步执行（高级用法）

若需单独控制流程，可按以下步骤操作：

步骤 1：组织分割

python run_batch_of_slides.py --task seg --wsi_dir ./wsis --job_dir ./trident_processed --gpu 0 --segmenter hest

输出：缩略图、组织轮廓 GeoJSON 文件（可用 QuPath 查看）。

步骤 2：图块坐标提取

python run_batch_of_slides.py --task coords --wsi_dir ./wsis --job_dir ./trident_processed --mag 20 --patch_size 256 --overlap 0

输出：包含图块坐标的 h5 文件及可视化结果。

步骤 3：特征提取

python run_batch_of_slides.py --task feat --wsi_dir ./wsis --job_dir ./trident_processed --patch_encoder uni_v1 --mag 20 --patch_size 256 

输出：特征向量 h5 文件，形状为 (n_patches, feature_dim)。

3.4 图像格式转换

将 CZI、PNG 等格式转换为金字塔 TIFF：

trident convert --input_dir ./wsis --mpp_csv ./wsis/to_process.csv --job_dir ./pyramidal_tiff --downscale_by 1 --num_workers 1

注意：--mpp_csv 文件必须包含 wsi,mpp 两列。