PathML 是一个面向本地计算病理学研究的 Python 工具包，当前稳定版本为 3.0.5（PyPI 发布于 2026-03-24）。它属于 beta 研究软件，不是经过验证的医疗器械、诊断系统、临床决策支持工具，也不能替代病理学家。其输出不得用于诊断、分级、分期或治疗患者。
用途与范围 PathML 用于本地计算病理学研究，涵盖全切片图像（WSI）的加载与切分、预处理与质控、多参数/多重成像数据处理、空间图构建以及机器学习推理。病理文件可能包含人脸、标签、编号、患者标识符、DICOM 标签或关联临床数据，因此处理前必须确认授权、知情同意/豁免、数据使用条款与机构政策，并对像素和元数据去标识化，使用假名化的 patient_id、slide_id 和 specimen_id，且不得在文件名、日志、.h5path 标签、模型卡或报告中放入直接标识符。输入、中间产物和输出应保存在经批准的本地加密存储上，并在切分或拟合任何预处理步骤前按患者（再按切片）划分数据集。
版本与安装 可安装的稳定版本为 PyPI 上的 pathml==3.0.5。v3.0.5 发布说明声明支持 Python 3.10-3.12，并停止支持 3.9；PyPI 未声明 Requires-Python 且仍保留过时的 3.8 分类器，因此应以发布说明为准并测试具体环境。GitHub 上存在 v3.0.6（2026-04-14）和 v3.0.7（2026-07-09）发布，但截至审查时 PyPI 尚无对应构件；v3.0.7 更新了 Torch/TorchVision/torch-geometric 与 ONNX 导出代码，不要将这些源码依赖与 3.0.5 wheel 混用。
推荐使用 Python 3.11 安装：
uv venv --python 3.11 source .venv/bin/activate uv pip install "pathml==3.0.5" python -c "import importlib.metadata as m; print(m.version('pathml'))"
PathML 3.0.5 未声明任何 extras，不要使用 pathml[all]。其基础发行版固定了庞大的科学/机器学习依赖栈，包括 Torch 2.8.0、ONNX 1.17.0、ONNX Runtime 1.17.x、OpenSlide Python 1.3.1、python-bioformats 4.1.0 和 python-javabridge 4.0.4。安装前需先装原生依赖：Debian/Ubuntu 使用 apt-get 安装 openslide-tools、gcc、g++、libblas-dev、liblapack-dev、openjdk-17-jdk；macOS 使用 brew 安装 openslide、openjdk@17；Windows 上游文档给出 vcpkg install openslide。Java/Bio-Formats 用于广泛的多维格式后端，OpenSlide 处理常见明场 WSI 格式更高效。CUDA 为可选，且必须匹配固定的 PyTorch 构建。
主要能力与使用方式 PathML 3.0.5 使用切片便捷类和 SlideData.run()，不提供 SlideData.from_slide()，Pipeline 也没有 run()。典型最小工作流：
from pathml.core import HESlide from pathml.preprocessing import BoxBlur, Pipeline, TissueDetectionHE
slide = HESlide("data/pseudonymous_slide.svs", backend="openslide") pipeline = Pipeline([ BoxBlur(kernel_size=5), TissueDetectionHE(mask_name="tissue", min_region_size=5000), ]) slide.run(pipeline, distributed=False, tile_size=512, tile_stride=512, level=0, tile_pad=False) slide.write("derived/pseudonymous_slide.h5path")
正式运行前建议先用有界样本验证：
from itertools import islice for tile in islice(slide.generate_tiles(shape=512, stride=512, level=0), 8): pipeline.apply(tile) assert tile.masks["tissue"].shape[:2] == tile.image.shape[:2]
切片使用所选金字塔层级的 (i, j) = (行, 列) 坐标；对 OpenSlide，PathML 内部将其映射到 0 级坐标。需记录层级与降采样，并在下游显式转换为 (x, y) 或微米。
研究流程建议：本地清点并校验清单，拒绝 URL/符号链接，仅检查允许的技术元数据并移除标识符；在生成重叠切片、图、归一化参考或特征前冻结划分；估算切片数量、内存、输出大小与流水线阶段；在代表性训练切片上试点预处理并检查组织掩码、空白/伪影标签、染色行为、边缘填充与空掩码情况，不得用测试切片调参；运行并保留坐标、层级、(i, j)、降采样、MPP、掩码名称、质控决策与失败/跳过切片；谨慎构建空间数据并验证通道顺序、物理单位、实例标签、节点特征对齐、图边与细胞到组织分配；在有界批次中推理，验证模型来源与校验和，不加载未知 pickle 检查点，保持预测与切片/切片坐标关联并按文档化规则拼接重叠；报告来源与局限，包括包锁、源哈希、扫描仪、染色、参数、随机种子、划分清单、模型卡、排除项与质控。
网络与安全 默认不联网。除非用户在获知端点和披露信息后明确同意，否则不要实例化可下载类或设置 download=True。SegmentMIFRemote 在构造时会从 Hugging Face 下载 ONNX 文件并在本地推理，稳定源码不会上传图像像素，但请求仍会披露 IP 地址和请求头等网络元数据并创建 temp.onnx，且没有内置校验和或离线标志。RemoteTestHoverNet 会从 Hugging Face 下载模型。PanNukeDataModule(download=True) 联系 Warwick，DeepFocusDataModule 联系 Zenodo，两者默认 download=False。任何未来的托管预测调用前，需说明确切目的地、像素通道/区域、元数据、标识符、保留策略、法律依据与保障措施，获得明确同意，且默认绝不发送 PHI。
模型代码安全方面：PyTorch 的 model.eval() 是评估模式，不是 Python 危险的内置求值器；绝不使用 Python 动态求值或执行。不要将本地文件命名为 pathml.py、torch.py、onnx.py 或标准库名称，以免遮蔽模块。PathML 的 EntityDataset 以 weights_only=False 加载 .pt 对象，绝不打开不可信的图/检查点，将基于 pickle 的流水线和 .pt 文件视为可执行代码。ONNX 比 pickle 安全但并非天然可信，需验证来源、SHA-256、预期输入/输出模式、文件大小与运行时限制，对第三方模型使用隔离。
内置本地 CLI 所有辅助脚本拒绝 URL 和符号链接，限制输入/工作量，使用严格 JSON，避免网络访问，且 --help 无需导入 PathML：
python scripts/slide_manifest.py validate --manifest manifest.csv --root . python scripts/slide_manifest.py inspect --slide data/example.svs --root . python scripts/plan_pipeline.py --width 100000 --height 80000 --tile-size 512 --stride 512 python scripts/image_qc.py synthetic --width 256 --height 256 python scripts/validate_spatial_schema.py graph --input graph.json --root . python scripts/validate_spatial_schema.py multiplex --input cells.csv --root . python scripts/plan_inference.py --tile-count 4000 --batch-size 16 --height 256 --width 256
推理规划器只读取数字或有界 JSON 模型卡，绝不导入模型框架或打开检查点。
详细参考文档包括：image_loading.md（切片类、后端、格式、层级、坐标、技术元数据与隐私）、preprocessing.md（稳定变换、掩码/质控、染色处理、流水线执行与防泄漏）、data_management.md（.h5path、清单、数据集、来源、划分与安全下载）、multiparametric.md（多维布局、CODEX/Vectra、定量、AnnData、DeepCell/Mesmer 与网络披露）、graphs.md（实例图、特征对齐、KNN/RAG/HACT 图、空间单位、模式与验证）、machine_learning.md（HoVer-Net/HACTNet、本地 ONNX 推理、批处理、检查点信任、评估与模型来源）。
适用场景与限制 适用于本地、去标识化的计算病理学研究，如 WSI 切分与质控、组织检测、多重成像数据管理、空间图构建与本地模型推理。限制包括：属于 beta 研究软件，不得用于临床诊断或治疗决策；版本细节可能过时，需以已安装版本的官方文档为准；涉及费用、共享 GPU/云配额、个人或患者数据或不可撤销操作前需先询问；不得编造结果、参数、标识符、引用或统计。相关技能包括 histolab、clinical-decision-support 和 ray-data。