Back to Details

digital-pathology

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Digital Pathology

数字病理

Overview

概述

This skill teaches the agent to generate correct, runnable code for whole-slide image (WSI) pipelines. It covers TIAToolbox CLI and Python API, the H-optimus-0 foundation model, the standard tissue→tiles→features→aggregate→predict pattern, the CAMELYON datasets, and SageMaker deployment patterns for regulated workloads.
Default to TIAToolbox primitives (
WSIReader
, 
PatchPredictor
, 
DeepFeatureExtractor
) rather than reimplementing slide I/O. Default to H-optimus-0 at 0.5 mpp / 224×224 unless the task specifies otherwise.
本 skill 指导 Agent 生成正确、可运行的全切片图像（WSI）流水线代码。内容涵盖 TIAToolbox CLI 和 Python API、H-optimus-0 基础模型、标准的“组织→图块→特征→聚合→预测”流程、CAMELYON 数据集，以及面向受监管工作负载的 SageMaker 部署模式。
默认使用 TIAToolbox 原语（
WSIReader
、
PatchPredictor
、
DeepFeatureExtractor
），而不是重新实现切片 I/O。除非任务另有说明，默认使用 H-optimus-0，分辨率为 0.5 mpp / 224×224。

Usage

用法

Invoke this skill when the user asks to:
  • Inspect, tile, or stain-normalize a WSI (SVS, NDPI, MRXS, pyramidal TIFF).
  • Extract features with a pathology foundation model.
  • Build a slide-level classifier on CAMELYON or similar cohorts.
  • Deploy a WSI model to AWS SageMaker.
Ask for clarification only if the resolution, model, or output artifact is ambiguous. Otherwise apply the defaults in the Resolution Rules section.
当用户要求执行以下操作时调用本 skill：
  • 检查、切片或对 WSI（SVS、NDPI、MRXS、金字塔 TIFF）进行染色标准化。
  • 使用病理基础模型提取特征。
  • 在 CAMELYON 或类似队列上构建切片级分类器。
  • 将 WSI 模型部署到 AWS SageMaker。
仅当分辨率、模型或输出产物不明确时才请求澄清。否则应用“分辨率规则”部分中的默认值。

Response Format

响应格式

  • Lead with the command or code the user needs — explain after
  • Structure as: confirm inputs → working code → key parameters explained → gotchas
  • One complete working example per task; do not show every alternative
  • Keep code comments minimal and functional (what, not why-it-exists)
  • Target: 50-100 lines of code with brief surrounding explanation
  • 先给出用户需要的命令或代码——之后再进行说明
  • 结构：确认输入 → 可运行代码 → 关键参数说明 → 注意事项
  • 每项任务提供一个完整可运行的示例；不要展示所有替代方案
  • 代码注释应精简且实用（说明做什么，而非解释其存在原因）
  • 目标：50–100 行代码，并附简短说明

Core Concepts

核心概念

  • Pyramidal WSI: multi-resolution image (levels). 
    baseline
    = level 0 (native, finest). Addressing uses 
    resolution
    + 
    units ∈ {mpp, power, level, baseline}
    .
  • mpp: microns per pixel. 
    0.5 mpp ≈ 20×
    , 
    0.25 mpp ≈ 40×
    . Downsample = 
    baseline_mpp / target_mpp
    .
  • Tissue mask: binary foreground mask computed at low resolution (e.g., Otsu at 1.25× or 4 mpp) to skip background tiles.
  • Patch / tile: fixed-size crop (e.g., 224×224) read at a target mpp, used as model input.
  • Foundation model embedding: per-tile feature vector from a pretrained ViT (H-optimus-0 → 1536-d).
  • Aggregation: slide-level prediction from tile features (ABMIL, CLAM, TransMIL, SlideGraph).
  • 金字塔 WSI：多分辨率图像（层级）。
    baseline
    = 0 级（原生、最精细）。寻址使用 
    resolution
    + 
    units ∈ {mpp, power, level, baseline}
    。
  • mpp：每像素微米数。
    0.5 mpp ≈ 20×
    ，
    0.25 mpp ≈ 40×
    。下采样系数 = 
    baseline_mpp / target_mpp
    。
  • 组织掩膜：在低分辨率下计算的二值前景掩膜（例如，在 1.25× 或 4 mpp 下使用 Otsu），用于跳过背景图块。
  • Patch / tile：固定大小的裁剪区域（例如 224×224），按目标 mpp 读取，用作模型输入。
  • 基础模型嵌入：预训练 ViT 为每个图块生成的特征向量（H-optimus-0 → 1536 维）。
  • 聚合：根据图块特征生成切片级预测（ABMIL、CLAM、TransMIL、SlideGraph）。

Quick Reference — Standard Pipeline

快速参考——标准流水线

Copy-adapt this end-to-end pattern for any WSI classification task:
python
import torch
from tiatoolbox.wsicore.wsireader import WSIReader
from tiatoolbox.models.architecture.vanilla import TimmBackbone
from tiatoolbox.models.engine.semantic_segmentor import IOSegmentorConfig
from tiatoolbox.models.engine.patch_predictor import IOPatchPredictorConfig
from tiatoolbox.models import DeepFeatureExtractor

SLIDE = "slide.svs"
OUT = "./out"
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
复制并调整以下端到端模式，用于任意 WSI 分类任务：
python
import torch
from tiatoolbox.wsicore.wsireader import WSIReader
from tiatoolbox.models.architecture.vanilla import TimmBackbone
from tiatoolbox.models.engine.semantic_segmentor import IOSegmentorConfig
from tiatoolbox.models.engine.patch_predictor import IOPatchPredictorConfig
from tiatoolbox.models import DeepFeatureExtractor

SLIDE = "slide.svs"
OUT = "./out"
DEVICE = "cuda" if torch.cuda.is_available() else "cpu"

1. Inspect

1. Inspect

reader = WSIReader.open(SLIDE) info = reader.info.as_dict() print(info["mpp"], info["level_dimensions"])
reader = WSIReader.open(SLIDE) info = reader.info.as_dict() print(info["mpp"], info["level_dimensions"])

2. Tissue mask (Otsu at low res — do NOT pass as external mask)

2. Tissue mask (Otsu at low res — do NOT pass as external mask)

mask_reader = reader.tissue_mask(method="otsu", resolution=4, units="mpp")
mask_reader = reader.tissue_mask(method="otsu", resolution=4, units="mpp")

3. Tile + extract H-optimus-0 features @ 0.5 mpp, 224x224

3. Tile + extract H-optimus-0 features @ 0.5 mpp, 224x224

ioconfig = IOPatchPredictorConfig( input_resolutions=[{"units": "mpp", "resolution": 0.5}], patch_input_shape=[224, 224], stride_shape=[224, 224], ) extractor = DeepFeatureExtractor( model=TimmBackbone("H-optimus-0", pretrained=True), batch_size=16, num_loader_workers=4, ) output = extractor.run( images=[SLIDE], masks=[mask_reader], patch_mode=False, ioconfig=ioconfig, save_dir=OUT, device=DEVICE, )
ioconfig = IOPatchPredictorConfig( input_resolutions=[{"units": "mpp", "resolution": 0.5}], patch_input_shape=[224, 224], stride_shape=[224, 224], ) extractor = DeepFeatureExtractor( model=TimmBackbone("H-optimus-0", pretrained=True), batch_size=16, num_loader_workers=4, ) output = extractor.run( images=[SLIDE], masks=[mask_reader], patch_mode=False, ioconfig=ioconfig, save_dir=OUT, device=DEVICE, )

output[0] -> (positions.npy, features.npy)

output[0] -> (positions.npy, features.npy)


Then aggregate (ABMIL / SlideGraph / mean-pool) on `features.npy` for a slide-level prediction.

随后在 `features.npy` 上执行聚合（ABMIL / SlideGraph / mean-pool），生成切片级预测。

TIAToolbox CLI

TIAToolbox CLI

All CLI commands accept 
--img-input
(file or dir), 
--output-path
, 
--resolution
, 
--units
, 
--batch-size
, 
--device cuda
.
bash
undefined
所有 CLI 命令都接受 
--img-input
（文件或目录）、
--output-path
、
--resolution
、
--units
、
--batch-size
、
--device cuda
。
bash
undefined

Slide metadata

Slide metadata

tiatoolbox slide-info --img-input slide.svs --mode show
tiatoolbox slide-info --img-input slide.svs --mode show

Tissue mask (binary PNG)

Tissue mask (binary PNG)

tiatoolbox tissue-mask --img-input slide.svs --output-path ./mask --method otsu
--resolution 1.25 --units power
tiatoolbox tissue-mask --img-input slide.svs --output-path ./mask --method otsu
--resolution 1.25 --units power

Tile classification with built-in ResNet18 on Kather100k

Tile classification with built-in ResNet18 on Kather100k

tiatoolbox patch-predictor --img-input slide.svs
--pretrained-model resnet18-kather100k
--output-path ./pred --batch-size 32 --device cuda
--resolution 0.5 --units mpp
tiatoolbox patch-predictor --img-input slide.svs
--pretrained-model resnet18-kather100k
--output-path ./pred --batch-size 32 --device cuda
--resolution 0.5 --units mpp

Stain normalization (Reinhard / Macenko / Vahadane)

Stain normalization (Reinhard / Macenko / Vahadane)

tiatoolbox stain-norm --img-input tiles/ --method reinhard --output-path ./norm

Use `--units baseline` when inputs are pre-extracted PNG tiles to avoid an "unknown scale" warning.
tiatoolbox stain-norm --img-input tiles/ --method reinhard --output-path ./norm

处理预先提取的 PNG 图块时，使用 `--units baseline`，以避免出现“unknown scale”警告。

TIAToolbox Python API

TIAToolbox Python API

WSIReader

WSIReader

python
from tiatoolbox.wsicore.wsireader import WSIReader

reader = WSIReader.open("slide.svs")
reader.info.as_dict()                              # mpp, levels, vendor
reader.slide_dimensions(resolution=0.5, units="mpp")

tile = reader.read_rect(
    location=(10000, 10000),    # baseline coords
    size=(224, 224),
    resolution=0.5, units="mpp",
)
region = reader.read_bounds(
    bounds=(0, 0, 4096, 4096),
    resolution=2.0, units="mpp",
)
mask = reader.tissue_mask(method="otsu", resolution=4, units="mpp")
python
from tiatoolbox.wsicore.wsireader import WSIReader

reader = WSIReader.open("slide.svs")
reader.info.as_dict()                              # mpp, levels, vendor
reader.slide_dimensions(resolution=0.5, units="mpp")

tile = reader.read_rect(
    location=(10000, 10000),    # baseline coords
    size=(224, 224),
    resolution=0.5, units="mpp",
)
region = reader.read_bounds(
    bounds=(0, 0, 4096, 4096),
    resolution=2.0, units="mpp",
)
mask = reader.tissue_mask(method="otsu", resolution=4, units="mpp")

PatchPredictor

PatchPredictor

python
from tiatoolbox.models import PatchPredictor
from tiatoolbox.models.engine.patch_predictor import IOPatchPredictorConfig

ioconfig = IOPatchPredictorConfig(
    input_resolutions=[{"units": "mpp", "resolution": 0.5}],
    patch_input_shape=[224, 224],
    stride_shape=[224, 224],
)
predictor = PatchPredictor(pretrained_model="resnet18-kather100k", batch_size=32)
out = predictor.run(
    images=["slide.svs"], masks=[mask],
    patch_mode=False, ioconfig=ioconfig,
    save_dir="./pred", device="cuda",
)
python
from tiatoolbox.models import PatchPredictor
from tiatoolbox.models.engine.patch_predictor import IOPatchPredictorConfig

ioconfig = IOPatchPredictorConfig(
    input_resolutions=[{"units": "mpp", "resolution": 0.5}],
    patch_input_shape=[224, 224],
    stride_shape=[224, 224],
)
predictor = PatchPredictor(pretrained_model="resnet18-kather100k", batch_size=32)
out = predictor.run(
    images=["slide.svs"], masks=[mask],
    patch_mode=False, ioconfig=ioconfig,
    save_dir="./pred", device="cuda",
)

DeepFeatureExtractor + TimmBackbone

DeepFeatureExtractor + TimmBackbone

python
from tiatoolbox.models import DeepFeatureExtractor
from tiatoolbox.models.architecture.vanilla import TimmBackbone

extractor = DeepFeatureExtractor(
    model=TimmBackbone("H-optimus-0", pretrained=True),
    batch_size=16, num_loader_workers=4,
)
python
from tiatoolbox.models import DeepFeatureExtractor
from tiatoolbox.models.architecture.vanilla import TimmBackbone

extractor = DeepFeatureExtractor(
    model=TimmBackbone("H-optimus-0", pretrained=True),
    batch_size=16, num_loader_workers=4,
)

SlideGraph construction

SlideGraph 构建

python
import numpy as np
from tiatoolbox.tools.graph import SlideGraphConstructor

positions = np.load("out/0.position.npy")   # (N, 4) x1,y1,x2,y2
features  = np.load("out/0.features.npy")   # (N, D)
graph = SlideGraphConstructor.build(
    positions=positions[:, :2], features=features,
)
python
import numpy as np
from tiatoolbox.tools.graph import SlideGraphConstructor

positions = np.load("out/0.position.npy")   # (N, 4) x1,y1,x2,y2
features  = np.load("out/0.features.npy")   # (N, D)
graph = SlideGraphConstructor.build(
    positions=positions[:, :2], features=features,
)

graph -> {"x": features, "edge_index": (2,E), "coords": (N,2)}

graph -> {"x": features, "edge_index": (2,E), "coords": (N,2)}

undefined
undefined

Stain normalization

染色标准化

python
from tiatoolbox.tools.stainnorm import get_normalizer

norm = get_normalizer("reinhard")   # or "macenko", "vahadane"
norm.fit(target_tile)               # RGB ndarray HxWx3
normed = norm.transform(source_tile)
python
from tiatoolbox.tools.stainnorm import get_normalizer

norm = get_normalizer("reinhard")   # or "macenko", "vahadane"
norm.fit(target_tile)               # RGB ndarray HxWx3
normed = norm.transform(source_tile)

H-optimus-0 Foundation Model

H-optimus-0 基础模型

1.1B-parameter ViT-G/14, input 224×224 RGB at 0.5 mpp, output 1536-d embedding. License is gated — accept terms on Hugging Face and run 
huggingface-cli login
.
1.1B 参数规模的 ViT-G/14，输入为 0.5 mpp 下的 224×224 RGB 图像，输出为 1536 维嵌入。许可证受门控控制——需在 Hugging Face 上接受条款并运行 
huggingface-cli login
。

Direct timm usage

直接使用 timm

python
import timm, torch
from torchvision import transforms

model = timm.create_model(
    "hf-hub:bioptimus/H-optimus-0",
    pretrained=True,
    init_values=1e-5,
    dynamic_img_size=False,
).eval().to("cuda")

preprocess = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize(
        mean=(0.707223, 0.578729, 0.703617),
        std=(0.211883, 0.230117, 0.177517),
    ),
])

with torch.inference_mode(), torch.autocast("cuda", dtype=torch.float16):
    feats = model(preprocess(tile).unsqueeze(0).to("cuda"))   # (1, 1536)
Use 
batch_size=16
on a 24 GB GPU with fp16 autocast. Prefer 
TimmBackbone("H-optimus-0", pretrained=True)
inside 
DeepFeatureExtractor
— TIAToolbox applies the correct preprocessing automatically.
python
import timm, torch
from torchvision import transforms

model = timm.create_model(
    "hf-hub:bioptimus/H-optimus-0",
    pretrained=True,
    init_values=1e-5,
    dynamic_img_size=False,
).eval().to("cuda")

preprocess = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize(
        mean=(0.707223, 0.578729, 0.703617),
        std=(0.211883, 0.230117, 0.177517),
    ),
])

with torch.inference_mode(), torch.autocast("cuda", dtype=torch.float16):
    feats = model(preprocess(tile).unsqueeze(0).to("cuda"))   # (1, 1536)
在配备 24 GB GPU 的设备上使用 
batch_size=16
并启用 fp16 autocast。优先在 
DeepFeatureExtractor
中使用 
TimmBackbone("H-optimus-0", pretrained=True)
——TIAToolbox 会自动应用正确的预处理。

Resolution Rules

分辨率规则

ModelmppPatch size
H-optimus-0 / UNI / Prov-GigaPath0.5224×224
HoVer-Net (PanNuke)0.25256×256
SlideGraph CNN features0.25512×512
Tissue mask (Otsu)4 mpp or 1.25×—
Downsample factor = 
baseline_mpp / target_mpp
. For a 0.25-mpp slide targeting 0.5 mpp, downsample by 2.
模型mppPatch 大小
H-optimus-0 / UNI / Prov-GigaPath0.5224×224
HoVer-Net（PanNuke）0.25256×256
SlideGraph CNN 特征0.25512×512
组织掩膜（Otsu）4 mpp 或 1.25×—
下采样系数 = 
baseline_mpp / target_mpp
。对于原始分辨率为 0.25 mpp、目标分辨率为 0.5 mpp 的切片，按 2 倍下采样。

CAMELYON Datasets

CAMELYON 数据集

  • Format: pyramidal 
    .tif
    , OpenSlide-compatible, ~100 000 × 100 000 px at baseline.
  • Annotations: ASAP XML, polygon coordinates in baseline (level-0) pixels.
  • CAMELYON16: 270 training slides (
    normal/
    + 
    tumor/
    ) + 130 test slides, labels in 
    reference.csv
    . Task: slide-level tumor classification + tumor segmentation.
  • CAMELYON17: 1000 slides across 100 patients (5 slides each). Patient-level pN-stage in 
    stages.csv
    . Official 5-fold split is by patient — never split by slide.
python
import xml.etree.ElementTree as ET
tree = ET.parse("slide.xml")                 # ASAP format
for ann in tree.iter("Annotation"):
    pts = [(float(c.get("X")), float(c.get("Y")))
           for c in ann.iter("Coordinate")]   # baseline coords
  • 格式：金字塔 
    .tif
    ，兼容 OpenSlide，原始层级约为 100 000 × 100 000 像素。
  • 标注：ASAP XML，多边形坐标采用 baseline（level-0）像素。
  • CAMELYON16：270 张训练切片（
    normal/
    + 
    tumor/
    ）+ 130 张测试切片，标签位于 
    reference.csv
    。任务：切片级肿瘤分类 + 肿瘤分割。
  • CAMELYON17：来自 100 名患者的 1000 张切片（每名患者 5 张）。患者级 pN 分期位于 
    stages.csv
    。官方 5 折划分按患者进行——绝不按切片划分。
python
import xml.etree.ElementTree as ET
tree = ET.parse("slide.xml")                 # ASAP format
for ann in tree.iter("Annotation"):
    pts = [(float(c.get("X")), float(c.get("Y")))
           for c in ann.iter("Coordinate")]   # baseline coords

SageMaker Deployment

SageMaker 部署

WSIs are gigapixel — never send raw bytes through the invocation path. Pass an S3 URI in the request and let the container read via 
s3fs
/ 
boto3
.
  • Endpoint type: Async Inference (long-running, per-request) or Batch Transform (cohort scoring).
  • Base container: extend 
    763104351884.dkr.ecr.<region>.amazonaws.com/pytorch-inference:2.x-gpu-py310
    .
  • Apt packages: 
    openslide-tools libpixman-1-dev libvips
    .
  • Pip: 
    tiatoolbox timm huggingface_hub s3fs
    .
  • Instance: 
    ml.g5.2xlarge
    minimum for H-optimus-0 fp16 (24 GB A10G). Use 
    ml.g5.12xlarge
    for batches.
  • Async config: 
    invocations_timeout=3600
    , 
    max_concurrent_invocations_per_instance=2
    .
python
from sagemaker.async_inference import AsyncInferenceConfig
async_config = AsyncInferenceConfig(
    output_path="s3://bucket/async-out/",
    max_concurrent_invocations_per_instance=2,
)
predictor = model.deploy(
    instance_type="ml.g5.2xlarge", initial_instance_count=1,
    async_inference_config=async_config,
)
predictor.predict_async(input_path="s3://bucket/slides/slide.svs")
Dockerfile sketch:
dockerfile
FROM 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-inference:2.3.0-gpu-py310
RUN apt-get update && apt-get install -y openslide-tools libpixman-1-dev libvips \
 && rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir tiatoolbox timm huggingface_hub s3fs
WSI 是十亿像素级图像——绝不通过调用路径发送原始字节。应在请求中传入 S3 URI，让容器通过 
s3fs
/ 
boto3
读取。
  • 端点类型：Async Inference（长时间运行、按请求执行）或 Batch Transform（队列评分）。
  • 基础容器：基于 
    763104351884.dkr.ecr.<region>.amazonaws.com/pytorch-inference:2.x-gpu-py310
    扩展。
  • Apt 包：
    openslide-tools libpixman-1-dev libvips
    。
  • Pip 包：
    tiatoolbox timm huggingface_hub s3fs
    。
  • 实例：H-optimus-0 fp16 的最低配置为 
    ml.g5.2xlarge
    （24 GB A10G）。批处理使用 
    ml.g5.12xlarge
    。
  • 异步配置：
    invocations_timeout=3600
    ，
    max_concurrent_invocations_per_instance=2
    。
python
from sagemaker.async_inference import AsyncInferenceConfig
async_config = AsyncInferenceConfig(
    output_path="s3://bucket/async-out/",
    max_concurrent_invocations_per_instance=2,
)
predictor = model.deploy(
    instance_type="ml.g5.2xlarge", initial_instance_count=1,
    async_inference_config=async_config,
)
predictor.predict_async(input_path="s3://bucket/slides/slide.svs")
Dockerfile 草图：
dockerfile
FROM 763104351884.dkr.ecr.us-east-1.amazonaws.com/pytorch-inference:2.3.0-gpu-py310
RUN apt-get update && apt-get install -y openslide-tools libpixman-1-dev libvips \
 && rm -rf /var/lib/apt/lists/*
RUN pip install --no-cache-dir tiatoolbox timm huggingface_hub s3fs

Common Mistakes

常见错误

  • Wrong: Using an old pixman library (<0.40) with OpenSlide Right: 
    apt-get install libpixman-1-dev
    and rebuild, or use libvips ≥ 8.12 Why: Causes all-black tiles from 
    read_rect
    due to a rendering bug
  • Wrong: Requesting a resolution finer than the slide's native mpp Right: Use a coarser 
    resolution
    , or check 
    reader.info.mpp
    first Why: Triggers 
    UserWarning: Scale > 1
    and produces upsampled (interpolated) data
  • Wrong: Attempting to load H-optimus-0 without accepting the gated model terms Right: Accept terms on the Hugging Face model page, then run 
    huggingface-cli login
    Why: Results in 
    OSError: 401
    authentication failure
  • Wrong: Using a batch size too large for GPU memory in DeepFeatureExtractor Right: Lower 
    batch_size
    (16→8→4) and ensure fp16 autocast is enabled Why: Causes CUDA out-of-memory errors
  • Wrong: Passing a non-pyramidal TIFF to OpenSlide Right: Convert first with 
    vips tiffsave in.tif out.tif --tile --pyramid --compression jpeg
    Why: Raises 
    OpenSlideUnsupportedFormatError
    because OpenSlide requires pyramidal format
  • Wrong: Passing a numpy array as an external mask with shape not aligned to the WSI pyramid Right: Use 
    reader.tissue_mask(...)
    directly and pass the returned reader object Why: Causes 
    DimensionMismatchError
    due to resolution/shape mismatch
  • Wrong: Processing PNG tiles without specifying resolution units Right: Pass 
    units="baseline"
    and explicit 
    resolution=1.0
    Why: Tiles lack mpp metadata, triggering an "unknown scale" warning
  • Wrong: Splitting CAMELYON17 data by slide rather than by patient Right: Split by 
    patient_id
    (5-fold) per the official protocol Why: Causes patient data leakage since each patient has 5 slides
  • Wrong: Skipping H-optimus-0 normalization (mean/std) when extracting features Right: Use 
    TimmBackbone
    (applies normalization automatically) or apply mean/std explicitly Why: Features look random and produce low AUC without proper input normalization
  • Wrong: Using annotation coordinates at the wrong pyramid level Right: ASAP XML coordinates are always at baseline level — scale them when reading at lower resolution Why: Coordinates will be off by 2× or 4× if the level mismatch is not accounted for
  • 错误： 使用过旧的 pixman 库（<0.40）与 OpenSlide 搭配 正确做法： 执行 
    apt-get install libpixman-1-dev
    后重新构建，或使用 libvips ≥ 8.12 原因： 由于渲染 bug，
    read_rect
    读取的所有图块都会变成全黑
  • 错误： 请求比切片原生 mpp 更精细的分辨率 正确做法： 使用更粗的 
    resolution
    ，或先检查 
    reader.info.mpp
    原因： 会触发 
    UserWarning: Scale > 1
    ，并生成上采样（插值）数据
  • 错误： 尝试加载 H-optimus-0，但未接受受门控的模型条款 正确做法： 在 Hugging Face 模型页面上接受条款，然后运行 
    huggingface-cli login
    原因： 导致 
    OSError: 401
    身份验证失败
  • 错误： 在 DeepFeatureExtractor 中使用的批大小过大，超出 GPU 显存容量 正确做法： 降低 
    batch_size
    （16→8→4），并确保启用 fp16 autocast 原因： 导致 CUDA 显存不足错误
  • 错误： 向 OpenSlide 传入非金字塔 TIFF 正确做法： 先使用 
    vips tiffsave in.tif out.tif --tile --pyramid --compression jpeg
    转换 原因： OpenSlide 要求金字塔格式，因此会抛出 
    OpenSlideUnsupportedFormatError
  • 错误： 传入与 WSI 金字塔形状未对齐的 numpy 数组作为外部掩膜 正确做法： 直接使用 
    reader.tissue_mask(...)
    ，并传入其返回的 reader 对象 原因： 由于分辨率/形状不匹配，导致 
    DimensionMismatchError
  • 错误： 处理 PNG 图块时未指定分辨率单位 正确做法： 传入 
    units="baseline"
    和明确的 
    resolution=1.0
    原因： 图块缺少 mpp 元数据，触发“unknown scale”警告
  • 错误： 按切片而非按患者划分 CAMELYON17 数据 正确做法： 按官方协议，根据 
    patient_id
    进行 5 折划分 原因： 每名患者有 5 张切片，按切片划分会造成患者数据泄漏
  • 错误： 提取特征时跳过 H-optimus-0 的归一化（mean/std） 正确做法： 使用 
    TimmBackbone
    （自动应用归一化），或显式应用 mean/std 原因： 特征看起来像随机值，未进行正确的输入归一化会导致 AUC 较低
  • 错误： 使用了错误金字塔层级上的标注坐标 正确做法： ASAP XML 坐标始终位于 baseline 层级——以较低分辨率读取时必须进行缩放 原因： 如果未考虑层级差异，坐标会偏移 2× 或 4×

Minimal Dependency Set

最小依赖集

tiatoolbox>=1.5
timm>=1.0
torch>=2.1
openslide-python
huggingface_hub
System: 
openslide-tools
, 
libpixman-1-dev
, 
libvips
(for non-pyramidal TIFF conversion).
tiatoolbox>=1.5
timm>=1.0
torch>=2.1
openslide-python
huggingface_hub
系统依赖：
openslide-tools
、
libpixman-1-dev
、
libvips
（用于转换非金字塔 TIFF）。

References

参考资料