PathML 3.0.5 预处理实战指南Pipeline 执行模型、组织掩膜 QC 与 HE 染色归一化【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇指南以scientific-agent-skills仓库中 PathML 预处理参考文档 为骨架结合该 Skill 内置的plan_pipeline.py、image_qc.py等有界 CLI 工具与测试用例系统讲解 PathML 3.0.5 中预处理管线的正确写法。读完本文你将掌握Pipeline 与 Transform 的真实执行模型谁拥有执行权、apply()与run()的正确用法、组织检测/空白与伪影 QC/染色归一化等稳定 Transform 的完整参数语义、基于islice与plan_pipeline.py的有界试运行方法以及掩膜坐标、填充、重叠与数据泄漏的工程细节。版本基线与写作前提本文全部示例以PathML 3.0.5PyPI 稳定版为准。该 Skill 在 SKILL.md 中记录v3.0.5 于 2026-03-24 发布官方声明支持 Python 3.10–3.12GitHub 上存在 v3.0.6/v3.0.7 源码 tag但 PyPI 无对应 wheelReadTheDocs/latest自识别为 3.0.5。因此本文刻意纠正了三类常见过时示例调用不存在的Pipeline.run()、遗漏 mask/label 名称参数、传递不支持的 Transform 构造参数。PathML 属于研究用途的 beta 软件不是经认证的医疗设备或诊断系统输出不得用于临床诊断、分级、分期或治疗决策——这是使用本 Skill 的前提边界。Pipeline 执行模型谁拥有执行权PathML 的Pipeline是一个有序的Transform列表核心公开 API 只有两个Pipeline(transform_sequenceNone)构造管线Pipeline.apply(tile)就地修改一个Tile并返回它。Pipeline没有run()方法管线的执行权属于 slide 或 dataset 对象。标准写法如下from pathml.core import HESlide from pathml.preprocessing import BoxBlur, Pipeline, TissueDetectionHE slide HESlide(data/slide-001.svs, backendopenslide) pipeline Pipeline( [ BoxBlur(kernel_size5), TissueDetectionHE(mask_nametissue), ] ) slide.run( pipeline, distributedFalse, tile_size512, tile_stride512, level0, tile_padFalse, )关键稳定事实SlideData.run()与SlideDataset.run()负责应用管线而不是Pipeline自身distributedTrue是默认值可能按可用核心数创建本地 Dask 集群生产调试请先从distributedFalse开始把并发问题与算法问题隔离开已有 tile 默认受保护除非显式传入overwrite_existing_tilesTrue否则不会被覆盖传入write_dir时处理完成后会写出slide.name.h5path文件详见 数据管理参考Pipeline.save()输出的是picklepickle 加载即执行绝不要加载来自不可信来源的管线文件。SlideData.run()与generate_tiles()的参数名并不一致run()使用tile_size/tile_stride/tile_pad/level而generate_tiles()使用shape/stride/pad/level混用时容易踩坑详见 图像加载参考。稳定 Transform 导入清单PathML 3.0.5 的稳定导入如下本文后文会逐一展开语义from pathml.preprocessing import ( AdaptiveHistogramEqualization, BinaryThreshold, BoxBlur, CollapseRunsCODEX, CollapseRunsVectra, ForegroundDetection, GaussianBlur, HistogramEqualization, LabelArtifactTileHE, LabelWhiteSpaceHE, MedianBlur, MorphClose, MorphOpen, NucleusDetectionHE, Pipeline, QuantifyMIF, RescaleIntensity, SegmentMIF, SegmentMIFRemote, StainNormalizationHE, SuperpixelInterpolation, TissueDetectionHE, )不存在稳定的transform...字符串注册表也没有安全的理由从任意 Python 表达式构造 Transform。正确的做法是先解析一份严格的、可白名单校验的配置例如 JSON再显式实例化已知类。仓库内置的 plan_pipeline.py 正是这一思路的体现——它以白名单TRANSFORM_KINDS校验管线中每个 transform 名称未知名称直接报错# 来自 skills/pathml/scripts/plan_pipeline.py TRANSFORM_KINDS { AdaptiveHistogramEqualization: image, BinaryThreshold: mask, BoxBlur: image, ... LabelArtifactTileHE: label, LabelWhiteSpaceHE: label, TissueDetectionHE: mask, }测试 test_scripts.py 验证了这一点传入NotATransform时 CLI 以退出码 2 返回并提示unknown绝不会动态求值。这同时是该 Skill 的防御性设计所有 CLI 拒绝 URL、拒绝符号链接、无网络访问、--help不依赖 PathML 安装。TissueDetectionHE组织区域检测TissueDetectionHE期望输入HE 染色的uint8tile完整签名from pathml.preprocessing import TissueDetectionHE tissue TissueDetectionHE( mask_nametissue, use_saturationTrue, blur_ksize17, thresholdNone, # None 时使用 Otsu morph_n_iter3, morph_k_size7, min_region_size5000, max_hole_size1500, outer_contours_onlyFalse, )它的处理流水线是使用 HSV 饱和度通道use_saturationTrue或灰度通道中值模糊核大小blur_ksize应用 Otsu 阈值thresholdNone时或显式阈值执行形态学开运算与闭运算morph_k_size、morph_n_iter依据min_region_size与max_hole_size的面积/空洞策略保留前景区域写入tile.masks[tissue]。mask_name在实践中是必需的传None会在apply()执行时失败。min_region_size、max_hole_size与形态学核的度量单位都是所选处理层级下的像素——一旦改变金字塔层级level或 MPP必须重新调参。组织检测是tile 局部的相邻 tile 边缘可能产生不一致判定且 PathML 不会自动从管线中剔除背景 tile。因此掩膜生成之后应当自行计算并记录组织覆盖率coverage float((tile.masks[tissue] 0).mean()) keep coverage 0.50覆盖率规则要在训练数据上确定并保留被拒绝 tile 的计数——被丢弃的 tile 数量本身就是一条重要的 QC 记录。空白与伪影 QC写的是 tile 标签不是像素掩膜与组织检测不同下面两个 Transform 写入的是tile 标签tile.labels[...]而不是像素掩膜from pathml.preprocessing import LabelArtifactTileHE, LabelWhiteSpaceHE whitespace LabelWhiteSpaceHE( label_namemostly_white, greyscale_threshold230, proportion_threshold0.5, ) artifact LabelArtifactTileHE(label_nameartifact)LabelWhiteSpaceHE当灰度像素占比超过proportion_threshold时将该 tile 标记为大片空白LabelArtifactTileHE一套固定的基于规则的 HSI 启发式用于识别空白、暗区与类笔迹颜色。它只暴露label_name一个参数——旧示例中的pen_threshold、bubble_threshold在 3.0.5 中不存在。两者的定位都需要明确它们不是完整的整片质量系统。模糊、褶皱、气泡、笔迹、组织覆盖率、裁剪、颜色漂移、通道缺失、对焦问题应当由你的工作流单独追踪也不要将启发式 QC 标志转换成临床质量判定。仓库还附带了一个无依赖、无网络的本地辅助 CLI见 image_qc.py用于合成图片/本地图片的快速自检仅作 Pilot 用、不替代 PathMLpython skills/pathml/scripts/image_qc.py synthetic --width 256 --height 256 python skills/pathml/scripts/image_qc.py inspect --image 本地图片路径 --root .该 CLI 支持两个子命令子命令关键参数说明synthetic--width/--height默认 256、--tissue-fraction默认 0.5、--saturation-threshold默认 0.15、--brightness-threshold默认 0.95、--mask-output内存中生成白底居中粉色组织区的确定性合成图并计算 QCinspect--image、--max-pixels上限 16,000,000、--max-image-bytes上限 256 MiB、--saturation-threshold、--brightness-threshold、--mask-output检查本地有界光栅或 P5/P6 PNM 图实现细节值得注意PNM.ppm/.pgm输入直接用标准库解析无需任何第三方依赖PNG/JPEG/TIFF 输入才需要 Pillow且 Pillow 是在参数校验通过后才延迟导入from PIL import Image位于函数体内。QC 报告输出严格 JSON字段包括mean_rgb、tissue_like_fraction、white_like_fraction、dark_fraction、any_channel_clipped_high_fraction、mask_rule且始终带clinical_use: False与注释此粗略 RGB 启发式仅用于合成/Pilot QC不是诊断质量判定。可选--mask-output会以权限 0600 原子写出一张 8-bit 二进制 PGM 掩膜。测试用例 test_scripts.py 验证了合成图、PPM 解析与掩膜输出权限。HE 染色归一化与染色分离StainNormalizationHE是整张 WSI 实验中影响全局一致性的关键环节from pathml.preprocessing import StainNormalizationHE normalizer StainNormalizationHE( targetnormalize, # normalize | hematoxylin | eosin stain_estimation_methodmacenko, # macenko | vahadane optical_density_threshold0.15, regularizer0.1, angular_percentile0.01, background_intensity245, )稳定版 API 的边界要特别注意不接受tissue_mask_name、target_od、target_concentrations接受stain_matrix_target_od与max_c_target且这些参数有固定默认值。拟合参考reference与转换normalizer.fit_to_reference(training_reference_rgb) normalized_rgb normalizer.F(source_rgb)泄漏控制Leakage Controls染色归一化的参考选择与 OD 参数调整是数据泄漏的高发点必须严格约束只允许用training slides选择参考图与调优 OD 参数在进入验证/测试集之前冻结拟合好的染色矩阵与目标浓度禁止因为测试集效果更好而换参考图——这等于用测试集拟合记录参考图的来源 slide 假名、区域坐标、level、MPP、所用方法与全部拟合数组且不得包含直接标识符参考图应裁剪/过滤为组织丰富、无伪影的 RGB 区域——稳定 API 不直接消费组织掩膜因此必须在喂入前自行裁剪过滤。值得强调的是Macenko 与 Vahadane 都是基于模型的颜色标准化方法不保证生物学染色变得可比。应当始终保留原始输入并评估归一化是否移除了任务相关信号、是否放大了伪影。简单的 HE 细胞核掩膜from pathml.preprocessing import NucleusDetectionHE nuclei NucleusDetectionHE( mask_namenuclei, stain_estimation_methodvahadane, superpixel_region_size10, n_iter30, )这是一个简单的组合 Transform苏木精分离 → 超像素插值SuperpixelInterpolation→ Otsu 阈值最终写入二值 tile 掩膜。它不是 HoVer-Net不分配细胞核类别也不应被当作经过验证的细胞计数。使用后要人工检查粘连对象、碎片、坏死区域、染色失败与 tile 边界。二值与形态学构建块三个稳定的底层构建块from pathml.preprocessing import BinaryThreshold, MorphClose, MorphOpen threshold BinaryThreshold( mask_nameforeground, use_otsuTrue, threshold0, inverseFalse, ) opened MorphOpen(mask_nameforeground, kernel_size5, n_iterations1) closed MorphClose(mask_nameforeground, kernel_size5, n_iterations1)注意语义差异BinaryThreshold.apply()会创建一个命名掩膜MorphOpen/MorphClose会修改命名掩膜。组合使用时必须显式匹配 dtype、极性与维度。推荐的 Pilot 管线仓库文档给出了一条可直接复制的组合管线它把 QC 标签、模糊、组织检测与染色归一化串成有序阶段from pathml.preprocessing import ( BoxBlur, LabelArtifactTileHE, LabelWhiteSpaceHE, Pipeline, StainNormalizationHE, TissueDetectionHE, ) pipeline Pipeline( [ LabelWhiteSpaceHE( label_namemostly_white, greyscale_threshold230, proportion_threshold0.8, ), LabelArtifactTileHE(label_nameartifact), BoxBlur(kernel_size3), TissueDetectionHE( mask_nametissue, min_region_size5000, outer_contours_onlyFalse, ), StainNormalizationHE( targetnormalize, stain_estimation_methodmacenko, ), ] )重要限制QC 标签不会短路后续 Transform。LabelWhiteSpaceHE不会因为打了大片空白标签就让管线跳过染色归一化。如果昂贵阶段只应作用于被接受的 tile必须写一个显式的自定义 Transform或使用带文档化策略的有界手动循环——保持逻辑确定性并测试它。有界试运行PathML 没有max_tiles参数PathML 3.0.5 的SlideData.run()没有max_tiles参数本地 Pilot 的正确工具是itertools.islicefrom itertools import islice sampled [] for tile in islice( slide.generate_tiles(shape512, stride512, padFalse, level0), 16, ): pipeline.apply(tile) sampled.append( { coords_ij: tile.coords, shape: tuple(tile.image.shape), tissue_fraction: float((tile.masks[tissue] 0).mean()), mostly_white: bool(tile.labels[mostly_white]), artifact: bool(tile.labels[artifact]), } )generate_tiles()是惰性的因此islice只物化前 16 个 tile配合前文提到的先计划后运行策略非常安全。用 plan_pipeline.py 做离线规划大规模运行前用仓库内置规划器估算 tile 数量与输出体积它不打开切片、不导入 PathML、无网络python skills/pathml/scripts/plan_pipeline.py \ --width 100000 --height 80000 \ --tile-size 512 --stride 512 \ --pipeline TissueDetectionHE,LabelWhiteSpaceHE,StainNormalizationHE \ --max-tiles 1000000plan_pipeline.py 的完整参数表均带上下界校验参数默认校验范围作用--width/--height必填1 ~ 1,000,000,000level-0 宽高--level-downsample1.01.0 ~ 1,000,000.0所选金字塔层级的降采样倍数--tile-size/--stride256 / 2561 ~ 8192tile 尺寸与步长--pad关闭—边缘填充使用后端特定计数逻辑并零填充边缘--channels31 ~ 4096通道数--bytes-per-channel11 / 2 / 4 / 8每个通道的字节数--pipeline—白名单 transform 名逗号分隔的执行顺序--mpp-x/--mpp-y无(0, 1000]微米每像素用于换算物理 tile 尺寸--max-tiles1,000,0001 ~ 100,000,000tile 数上限超限报错--max-output-gib1024.0(0, 1,000,000]未压缩载荷估算上限--output/--root/--force—路径校验严格 JSON 输出规划器实现的 tile 计数算法与 PathML 3.0.5 后端一致padFalse时单维 tile 数为0当D T否则(D - T) // S 1padTrue且维度不能被步长整除时额外 1。输出 JSON 包含tiles_ij、tile_count、overlap_pixels_per_axis、gap_pixels_per_axis、expected_mask_outputs_per_tile、estimated_uncompressed_payload_gib、physical_tile_size_um_yx以及warnings例如填充警告、重叠复制警告、SegmentMIFRemote网络下载提示。测试 test_scripts.py 验证1024×1024 图、512 tile、512 stride 会得出tile_count 4、mask 输出 1、label 输出 1。输入宽高必须来自可信的技术元数据检查建议先用 slide_manifest.py 的inspect子命令完成白名单元数据检查规划器自身不打开切片。掩膜、标签、填充与重叠的工程约定tile 掩膜的前两个维度必须与 tile 图像匹配apply()后有断言式检查SKILL.md 的最小工作流中即用tile.masks[tissue].shape[:2] tile.image.shape[:2]验证使用语义化且互不冲突的掩膜名tissue、nuclei、cell_segmentation并记录每个掩膜是二值、语义还是实例标签实例掩膜约定背景为 0前景对象为正整数 IDtile_padTrue会引入零填充像素必须记录填充像素是否从 QC、染色拟合、损失计算与拼接中被忽略稳定版SlideData.generate_tiles()无法把整片级掩膜切到带填充的 tile 上详见 image_loading.md重叠 tile 会重复统计组织与细胞计数前需按 slide 坐标去重或采用显式的混合/裁剪策略掩膜必须与其坐标处于同一 level重采样实例掩膜必须用最近邻插值且重采样后要重新标注并做 QC。训练/验证/测试泄漏检查清单一切划分操作都必须在以下任何步骤之前完成选择染色参考估计 QC 或组织阈值拟合特征缩放器学习增强策略或颜色分布选择分割参数提取重叠 tile构建图校准模型阈值。来自同一患者的全部 tile、区域、连续切片与重复扫描必须全部划入同一个 split。若目标是站点/扫描仪泛化则应把整个站点或扫描仪保留为独立划分。所有排除项都要在看测试结果之前记录在案。仓库的 slide_manifest.pyvalidate子命令会自动检测同一 patient 出现在多个 split的泄漏——测试 test_scripts.py 正是用patient-1 的两张切片分别进入 train 与 test的样例验证了退出码 2 与multiple报错。可复现性记录每次运行必须保留以下清单这也是 SKILL.md 中报告 provenance 与局限步骤的要求PathML 及依赖锁文件版本源文件 SHA-256 与假名化 ID后端、level、downsample、MPP、tile 尺寸/步长/是否填充有序的 Transform 名称与全部构造参数值拟合的染色数组与仅限训练的参考来源QC/掩膜定义与每个 slide 的接受/拒绝总数Dask 配置、worker 数、CPU/GPU、失败/重试策略代码修订号、随机种子、split manifest 哈希与输出哈希。安全边界pickle、远程下载与网络披露预处理阶段同样受 SKILL.md 的安全边界约束值得在管线设计时一并考虑Pipeline.save()与EntityDataset涉及的.pt/pickle 对象加载即执行绝不打开不可信来源的管线文件与检查点SegmentMIFRemote在构造时会从 Hugging Face 下载 Mesmer ONNX 文件不依赖用户显式 opt-in 就不该实例化且稳定源码不会上传图像像素但请求仍会披露 IP 等网络元数据并生成temp.onnx无内置校验和与离线开关不要把本地文件命名为pathml.py、torch.py、onnx.py等与标准库/关键模块同名的文件防止遮蔽导入。仓库测试 test_scripts.py 会静态检查全部 CLI 脚本禁止importlib/requests/urllib/socket等导入、禁止eval/exec/compile/__import__调用、禁止上述遮蔽文件名。结语与延伸阅读本文覆盖了 PathML 3.0.5 预处理管线的完整技术栈执行模型SlideData.run()vsPipeline.apply()、稳定 Transform 白名单、组织检测与覆盖率策略、空白/伪影标签 QC、染色归一化的泄漏控制、二值与形态学构建块以及以isliceplan_pipeline.py为核心的先计划、后试跑、再全量工作流。将染色归一化、掩膜语义、填充/重叠与数据泄漏这几条红线牢记于心预处理流水线就能做到既可复现又可控。相邻主题图像加载与坐标约定、h5path 数据管理与 split、多参数影像CODEX/Vectra/MIF、空间图构建、推理与模型信任配套工具管线规划器、图像 QC 工具、共享 I/O 校验库、CLI 测试【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
PathML 3.0.5 预处理实战指南：Pipeline 执行模型、组织掩膜 QC 与 HE 染色归一化
PathML 3.0.5 预处理实战指南Pipeline 执行模型、组织掩膜 QC 与 HE 染色归一化【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇指南以scientific-agent-skills仓库中 PathML 预处理参考文档 为骨架结合该 Skill 内置的plan_pipeline.py、image_qc.py等有界 CLI 工具与测试用例系统讲解 PathML 3.0.5 中预处理管线的正确写法。读完本文你将掌握Pipeline 与 Transform 的真实执行模型谁拥有执行权、apply()与run()的正确用法、组织检测/空白与伪影 QC/染色归一化等稳定 Transform 的完整参数语义、基于islice与plan_pipeline.py的有界试运行方法以及掩膜坐标、填充、重叠与数据泄漏的工程细节。版本基线与写作前提本文全部示例以PathML 3.0.5PyPI 稳定版为准。该 Skill 在 SKILL.md 中记录v3.0.5 于 2026-03-24 发布官方声明支持 Python 3.10–3.12GitHub 上存在 v3.0.6/v3.0.7 源码 tag但 PyPI 无对应 wheelReadTheDocs/latest自识别为 3.0.5。因此本文刻意纠正了三类常见过时示例调用不存在的Pipeline.run()、遗漏 mask/label 名称参数、传递不支持的 Transform 构造参数。PathML 属于研究用途的 beta 软件不是经认证的医疗设备或诊断系统输出不得用于临床诊断、分级、分期或治疗决策——这是使用本 Skill 的前提边界。Pipeline 执行模型谁拥有执行权PathML 的Pipeline是一个有序的Transform列表核心公开 API 只有两个Pipeline(transform_sequenceNone)构造管线Pipeline.apply(tile)就地修改一个Tile并返回它。Pipeline没有run()方法管线的执行权属于 slide 或 dataset 对象。标准写法如下from pathml.core import HESlide from pathml.preprocessing import BoxBlur, Pipeline, TissueDetectionHE slide HESlide(data/slide-001.svs, backendopenslide) pipeline Pipeline( [ BoxBlur(kernel_size5), TissueDetectionHE(mask_nametissue), ] ) slide.run( pipeline, distributedFalse, tile_size512, tile_stride512, level0, tile_padFalse, )关键稳定事实SlideData.run()与SlideDataset.run()负责应用管线而不是Pipeline自身distributedTrue是默认值可能按可用核心数创建本地 Dask 集群生产调试请先从distributedFalse开始把并发问题与算法问题隔离开已有 tile 默认受保护除非显式传入overwrite_existing_tilesTrue否则不会被覆盖传入write_dir时处理完成后会写出slide.name.h5path文件详见 数据管理参考Pipeline.save()输出的是picklepickle 加载即执行绝不要加载来自不可信来源的管线文件。SlideData.run()与generate_tiles()的参数名并不一致run()使用tile_size/tile_stride/tile_pad/level而generate_tiles()使用shape/stride/pad/level混用时容易踩坑详见 图像加载参考。稳定 Transform 导入清单PathML 3.0.5 的稳定导入如下本文后文会逐一展开语义from pathml.preprocessing import ( AdaptiveHistogramEqualization, BinaryThreshold, BoxBlur, CollapseRunsCODEX, CollapseRunsVectra, ForegroundDetection, GaussianBlur, HistogramEqualization, LabelArtifactTileHE, LabelWhiteSpaceHE, MedianBlur, MorphClose, MorphOpen, NucleusDetectionHE, Pipeline, QuantifyMIF, RescaleIntensity, SegmentMIF, SegmentMIFRemote, StainNormalizationHE, SuperpixelInterpolation, TissueDetectionHE, )不存在稳定的transform...字符串注册表也没有安全的理由从任意 Python 表达式构造 Transform。正确的做法是先解析一份严格的、可白名单校验的配置例如 JSON再显式实例化已知类。仓库内置的 plan_pipeline.py 正是这一思路的体现——它以白名单TRANSFORM_KINDS校验管线中每个 transform 名称未知名称直接报错# 来自 skills/pathml/scripts/plan_pipeline.py TRANSFORM_KINDS { AdaptiveHistogramEqualization: image, BinaryThreshold: mask, BoxBlur: image, ... LabelArtifactTileHE: label, LabelWhiteSpaceHE: label, TissueDetectionHE: mask, }测试 test_scripts.py 验证了这一点传入NotATransform时 CLI 以退出码 2 返回并提示unknown绝不会动态求值。这同时是该 Skill 的防御性设计所有 CLI 拒绝 URL、拒绝符号链接、无网络访问、--help不依赖 PathML 安装。TissueDetectionHE组织区域检测TissueDetectionHE期望输入HE 染色的uint8tile完整签名from pathml.preprocessing import TissueDetectionHE tissue TissueDetectionHE( mask_nametissue, use_saturationTrue, blur_ksize17, thresholdNone, # None 时使用 Otsu morph_n_iter3, morph_k_size7, min_region_size5000, max_hole_size1500, outer_contours_onlyFalse, )它的处理流水线是使用 HSV 饱和度通道use_saturationTrue或灰度通道中值模糊核大小blur_ksize应用 Otsu 阈值thresholdNone时或显式阈值执行形态学开运算与闭运算morph_k_size、morph_n_iter依据min_region_size与max_hole_size的面积/空洞策略保留前景区域写入tile.masks[tissue]。mask_name在实践中是必需的传None会在apply()执行时失败。min_region_size、max_hole_size与形态学核的度量单位都是所选处理层级下的像素——一旦改变金字塔层级level或 MPP必须重新调参。组织检测是tile 局部的相邻 tile 边缘可能产生不一致判定且 PathML 不会自动从管线中剔除背景 tile。因此掩膜生成之后应当自行计算并记录组织覆盖率coverage float((tile.masks[tissue] 0).mean()) keep coverage 0.50覆盖率规则要在训练数据上确定并保留被拒绝 tile 的计数——被丢弃的 tile 数量本身就是一条重要的 QC 记录。空白与伪影 QC写的是 tile 标签不是像素掩膜与组织检测不同下面两个 Transform 写入的是tile 标签tile.labels[...]而不是像素掩膜from pathml.preprocessing import LabelArtifactTileHE, LabelWhiteSpaceHE whitespace LabelWhiteSpaceHE( label_namemostly_white, greyscale_threshold230, proportion_threshold0.5, ) artifact LabelArtifactTileHE(label_nameartifact)LabelWhiteSpaceHE当灰度像素占比超过proportion_threshold时将该 tile 标记为大片空白LabelArtifactTileHE一套固定的基于规则的 HSI 启发式用于识别空白、暗区与类笔迹颜色。它只暴露label_name一个参数——旧示例中的pen_threshold、bubble_threshold在 3.0.5 中不存在。两者的定位都需要明确它们不是完整的整片质量系统。模糊、褶皱、气泡、笔迹、组织覆盖率、裁剪、颜色漂移、通道缺失、对焦问题应当由你的工作流单独追踪也不要将启发式 QC 标志转换成临床质量判定。仓库还附带了一个无依赖、无网络的本地辅助 CLI见 image_qc.py用于合成图片/本地图片的快速自检仅作 Pilot 用、不替代 PathMLpython skills/pathml/scripts/image_qc.py synthetic --width 256 --height 256 python skills/pathml/scripts/image_qc.py inspect --image 本地图片路径 --root .该 CLI 支持两个子命令子命令关键参数说明synthetic--width/--height默认 256、--tissue-fraction默认 0.5、--saturation-threshold默认 0.15、--brightness-threshold默认 0.95、--mask-output内存中生成白底居中粉色组织区的确定性合成图并计算 QCinspect--image、--max-pixels上限 16,000,000、--max-image-bytes上限 256 MiB、--saturation-threshold、--brightness-threshold、--mask-output检查本地有界光栅或 P5/P6 PNM 图实现细节值得注意PNM.ppm/.pgm输入直接用标准库解析无需任何第三方依赖PNG/JPEG/TIFF 输入才需要 Pillow且 Pillow 是在参数校验通过后才延迟导入from PIL import Image位于函数体内。QC 报告输出严格 JSON字段包括mean_rgb、tissue_like_fraction、white_like_fraction、dark_fraction、any_channel_clipped_high_fraction、mask_rule且始终带clinical_use: False与注释此粗略 RGB 启发式仅用于合成/Pilot QC不是诊断质量判定。可选--mask-output会以权限 0600 原子写出一张 8-bit 二进制 PGM 掩膜。测试用例 test_scripts.py 验证了合成图、PPM 解析与掩膜输出权限。HE 染色归一化与染色分离StainNormalizationHE是整张 WSI 实验中影响全局一致性的关键环节from pathml.preprocessing import StainNormalizationHE normalizer StainNormalizationHE( targetnormalize, # normalize | hematoxylin | eosin stain_estimation_methodmacenko, # macenko | vahadane optical_density_threshold0.15, regularizer0.1, angular_percentile0.01, background_intensity245, )稳定版 API 的边界要特别注意不接受tissue_mask_name、target_od、target_concentrations接受stain_matrix_target_od与max_c_target且这些参数有固定默认值。拟合参考reference与转换normalizer.fit_to_reference(training_reference_rgb) normalized_rgb normalizer.F(source_rgb)泄漏控制Leakage Controls染色归一化的参考选择与 OD 参数调整是数据泄漏的高发点必须严格约束只允许用training slides选择参考图与调优 OD 参数在进入验证/测试集之前冻结拟合好的染色矩阵与目标浓度禁止因为测试集效果更好而换参考图——这等于用测试集拟合记录参考图的来源 slide 假名、区域坐标、level、MPP、所用方法与全部拟合数组且不得包含直接标识符参考图应裁剪/过滤为组织丰富、无伪影的 RGB 区域——稳定 API 不直接消费组织掩膜因此必须在喂入前自行裁剪过滤。值得强调的是Macenko 与 Vahadane 都是基于模型的颜色标准化方法不保证生物学染色变得可比。应当始终保留原始输入并评估归一化是否移除了任务相关信号、是否放大了伪影。简单的 HE 细胞核掩膜from pathml.preprocessing import NucleusDetectionHE nuclei NucleusDetectionHE( mask_namenuclei, stain_estimation_methodvahadane, superpixel_region_size10, n_iter30, )这是一个简单的组合 Transform苏木精分离 → 超像素插值SuperpixelInterpolation→ Otsu 阈值最终写入二值 tile 掩膜。它不是 HoVer-Net不分配细胞核类别也不应被当作经过验证的细胞计数。使用后要人工检查粘连对象、碎片、坏死区域、染色失败与 tile 边界。二值与形态学构建块三个稳定的底层构建块from pathml.preprocessing import BinaryThreshold, MorphClose, MorphOpen threshold BinaryThreshold( mask_nameforeground, use_otsuTrue, threshold0, inverseFalse, ) opened MorphOpen(mask_nameforeground, kernel_size5, n_iterations1) closed MorphClose(mask_nameforeground, kernel_size5, n_iterations1)注意语义差异BinaryThreshold.apply()会创建一个命名掩膜MorphOpen/MorphClose会修改命名掩膜。组合使用时必须显式匹配 dtype、极性与维度。推荐的 Pilot 管线仓库文档给出了一条可直接复制的组合管线它把 QC 标签、模糊、组织检测与染色归一化串成有序阶段from pathml.preprocessing import ( BoxBlur, LabelArtifactTileHE, LabelWhiteSpaceHE, Pipeline, StainNormalizationHE, TissueDetectionHE, ) pipeline Pipeline( [ LabelWhiteSpaceHE( label_namemostly_white, greyscale_threshold230, proportion_threshold0.8, ), LabelArtifactTileHE(label_nameartifact), BoxBlur(kernel_size3), TissueDetectionHE( mask_nametissue, min_region_size5000, outer_contours_onlyFalse, ), StainNormalizationHE( targetnormalize, stain_estimation_methodmacenko, ), ] )重要限制QC 标签不会短路后续 Transform。LabelWhiteSpaceHE不会因为打了大片空白标签就让管线跳过染色归一化。如果昂贵阶段只应作用于被接受的 tile必须写一个显式的自定义 Transform或使用带文档化策略的有界手动循环——保持逻辑确定性并测试它。有界试运行PathML 没有max_tiles参数PathML 3.0.5 的SlideData.run()没有max_tiles参数本地 Pilot 的正确工具是itertools.islicefrom itertools import islice sampled [] for tile in islice( slide.generate_tiles(shape512, stride512, padFalse, level0), 16, ): pipeline.apply(tile) sampled.append( { coords_ij: tile.coords, shape: tuple(tile.image.shape), tissue_fraction: float((tile.masks[tissue] 0).mean()), mostly_white: bool(tile.labels[mostly_white]), artifact: bool(tile.labels[artifact]), } )generate_tiles()是惰性的因此islice只物化前 16 个 tile配合前文提到的先计划后运行策略非常安全。用 plan_pipeline.py 做离线规划大规模运行前用仓库内置规划器估算 tile 数量与输出体积它不打开切片、不导入 PathML、无网络python skills/pathml/scripts/plan_pipeline.py \ --width 100000 --height 80000 \ --tile-size 512 --stride 512 \ --pipeline TissueDetectionHE,LabelWhiteSpaceHE,StainNormalizationHE \ --max-tiles 1000000plan_pipeline.py 的完整参数表均带上下界校验参数默认校验范围作用--width/--height必填1 ~ 1,000,000,000level-0 宽高--level-downsample1.01.0 ~ 1,000,000.0所选金字塔层级的降采样倍数--tile-size/--stride256 / 2561 ~ 8192tile 尺寸与步长--pad关闭—边缘填充使用后端特定计数逻辑并零填充边缘--channels31 ~ 4096通道数--bytes-per-channel11 / 2 / 4 / 8每个通道的字节数--pipeline—白名单 transform 名逗号分隔的执行顺序--mpp-x/--mpp-y无(0, 1000]微米每像素用于换算物理 tile 尺寸--max-tiles1,000,0001 ~ 100,000,000tile 数上限超限报错--max-output-gib1024.0(0, 1,000,000]未压缩载荷估算上限--output/--root/--force—路径校验严格 JSON 输出规划器实现的 tile 计数算法与 PathML 3.0.5 后端一致padFalse时单维 tile 数为0当D T否则(D - T) // S 1padTrue且维度不能被步长整除时额外 1。输出 JSON 包含tiles_ij、tile_count、overlap_pixels_per_axis、gap_pixels_per_axis、expected_mask_outputs_per_tile、estimated_uncompressed_payload_gib、physical_tile_size_um_yx以及warnings例如填充警告、重叠复制警告、SegmentMIFRemote网络下载提示。测试 test_scripts.py 验证1024×1024 图、512 tile、512 stride 会得出tile_count 4、mask 输出 1、label 输出 1。输入宽高必须来自可信的技术元数据检查建议先用 slide_manifest.py 的inspect子命令完成白名单元数据检查规划器自身不打开切片。掩膜、标签、填充与重叠的工程约定tile 掩膜的前两个维度必须与 tile 图像匹配apply()后有断言式检查SKILL.md 的最小工作流中即用tile.masks[tissue].shape[:2] tile.image.shape[:2]验证使用语义化且互不冲突的掩膜名tissue、nuclei、cell_segmentation并记录每个掩膜是二值、语义还是实例标签实例掩膜约定背景为 0前景对象为正整数 IDtile_padTrue会引入零填充像素必须记录填充像素是否从 QC、染色拟合、损失计算与拼接中被忽略稳定版SlideData.generate_tiles()无法把整片级掩膜切到带填充的 tile 上详见 image_loading.md重叠 tile 会重复统计组织与细胞计数前需按 slide 坐标去重或采用显式的混合/裁剪策略掩膜必须与其坐标处于同一 level重采样实例掩膜必须用最近邻插值且重采样后要重新标注并做 QC。训练/验证/测试泄漏检查清单一切划分操作都必须在以下任何步骤之前完成选择染色参考估计 QC 或组织阈值拟合特征缩放器学习增强策略或颜色分布选择分割参数提取重叠 tile构建图校准模型阈值。来自同一患者的全部 tile、区域、连续切片与重复扫描必须全部划入同一个 split。若目标是站点/扫描仪泛化则应把整个站点或扫描仪保留为独立划分。所有排除项都要在看测试结果之前记录在案。仓库的 slide_manifest.pyvalidate子命令会自动检测同一 patient 出现在多个 split的泄漏——测试 test_scripts.py 正是用patient-1 的两张切片分别进入 train 与 test的样例验证了退出码 2 与multiple报错。可复现性记录每次运行必须保留以下清单这也是 SKILL.md 中报告 provenance 与局限步骤的要求PathML 及依赖锁文件版本源文件 SHA-256 与假名化 ID后端、level、downsample、MPP、tile 尺寸/步长/是否填充有序的 Transform 名称与全部构造参数值拟合的染色数组与仅限训练的参考来源QC/掩膜定义与每个 slide 的接受/拒绝总数Dask 配置、worker 数、CPU/GPU、失败/重试策略代码修订号、随机种子、split manifest 哈希与输出哈希。安全边界pickle、远程下载与网络披露预处理阶段同样受 SKILL.md 的安全边界约束值得在管线设计时一并考虑Pipeline.save()与EntityDataset涉及的.pt/pickle 对象加载即执行绝不打开不可信来源的管线文件与检查点SegmentMIFRemote在构造时会从 Hugging Face 下载 Mesmer ONNX 文件不依赖用户显式 opt-in 就不该实例化且稳定源码不会上传图像像素但请求仍会披露 IP 等网络元数据并生成temp.onnx无内置校验和与离线开关不要把本地文件命名为pathml.py、torch.py、onnx.py等与标准库/关键模块同名的文件防止遮蔽导入。仓库测试 test_scripts.py 会静态检查全部 CLI 脚本禁止importlib/requests/urllib/socket等导入、禁止eval/exec/compile/__import__调用、禁止上述遮蔽文件名。结语与延伸阅读本文覆盖了 PathML 3.0.5 预处理管线的完整技术栈执行模型SlideData.run()vsPipeline.apply()、稳定 Transform 白名单、组织检测与覆盖率策略、空白/伪影标签 QC、染色归一化的泄漏控制、二值与形态学构建块以及以isliceplan_pipeline.py为核心的先计划、后试跑、再全量工作流。将染色归一化、掩膜语义、填充/重叠与数据泄漏这几条红线牢记于心预处理流水线就能做到既可复现又可控。相邻主题图像加载与坐标约定、h5path 数据管理与 split、多参数影像CODEX/Vectra/MIF、空间图构建、推理与模型信任配套工具管线规划器、图像 QC 工具、共享 I/O 校验库、CLI 测试【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
