简介针对数字病理切片格式转换需求整理的实用工具包面向需要将 SVS 影像转为 TIF、以便在 ASAP 等软件中完成标注的病理影像工作者与工程人员。其解决的问题较明确江丰生物 KFB 文件在直接转换 TIF 时容易出现仅显示左上角局部的情况而该工具可用于 SVS 到 TIF 的转换为后续标注、归档和格式兼容处理提供更完整的 TIF 文件。压缩包约 21.58MB文件总数显示为 0文件类型明细暂未提供包内具体构成需以下载后的实际目录为准标签中的 TIFF 对应其处理与输出对象。已有 2780 人学习或下载说明此类病理切片格式转换需求具有较高关注度。对于受 KFB 转 TIF 不完整困扰、又必须使用 TIF 进行标注的用户这份工具包提供了针对性的替代方案可减少转换环节的反复试错并帮助建立更顺畅的 SVS 转 TIF 处理路径。1. SVS 转 TIFF 的真实门槛后缀救不了的四件事去年冬天排查一份切片归档事故现场很典型有人在看图软件里对.svs点了“另存为.tif”文件确实生成了双击也能打开但只剩一张模糊的缩略图原本 40 倍镜下的细胞核直径量出来比红细胞还大。问题不在软件在于 SVS 和 TIFF 之间从来不是后缀的关系。SVS 本身就是一个披着 TIFF 外壳的金字塔容器里面塞着 4 到 6 个分辨率层级、每层切成 240×240 的瓦片、瓦片用 JPEG 或 JPEG 2000 压缩外带 MPP每像素微米数、扫描仪型号、ICC 色彩描述和一张标签缩略图。所谓“完美实现 SVS 转 TIFF”实际要做的是把这套金字塔结构原样重建到目标 TIFF 里同时把压缩方式、物理分辨率和色彩空间这三件事对齐。这篇笔记写给两类人一类是手里攥着几十张切片要做批量归档的另一类是把切片喂给下游分析工具时发现读不进去、读进去尺寸又不对的。下面按“先看清结构、再动手转换、最后验收”的顺序走完。2. 拆开 SVS 看内部层级、瓦片与 MPP 藏在哪里动手之前必须先看清楚输入长什么样。很多人一上来就写转换循环跑到一半才发现源文件只有 3 层而目标工具要求 5 层或者分辨率标签压根没读到返工的时间比读文档多得多。2.1 先用 openslide 读出层级和物理分辨率openslide 是读全切片图像这件事上最稳的一把手它对 SVS 的解析不是“当成普通 TIFF 打开”而是识别 Aperio 的私有标签、还原出层级关系和 MPP。第一步不需要写任何转换逻辑只做一次体检import openslide # 打开源切片这一步只读文件头不加载像素 src openslide.OpenSlide(case_01.svs) print(层级数:, src.level_count) for i in range(src.level_count): w, h src.level_dimensions[i] ds src.level_downsamples[i] print(flevel {i}: {w} x {h}, downsample{ds:.4f}) # 关键元数据缺一个下游都可能出问题 props src.properties for key in ( openslide.vendor, openslide.mpp-x, openslide.mpp-y, openslide.objective-power, aperio.AppMag, tiff.Compression, ): print(key, , props.get(key)) # 标签图、宏观缩略图这些“附属图像”不占层级要单独取 for name, img in src.associated_images.items(): print(associated:, name, img.size, img.mode)这段代码干了三件事。level_dimensions给出每一层的宽高注意这里的宽高已经是该层自己的像素数不是 layer 0 的尺寸level_downsamples给出这一层相对于 layer 0 的降采样倍率它不一定是严格的 2 的幂Aperio 常见的是 1、4、16、32、64 这种非均匀序列后面写金字塔时如果强行按 2 的幂重建层级就会对不上。mpp-x和mpp-y是物理分辨率的来源单位是微米/像素一张 40 倍镜切片通常是 0.25 左右20 倍镜在 0.5 左右这个数值直接决定下游测量出来的尺寸对不对。我一般会把这段体检输出存成一份 JSON 一起归档理由是转换失败时能立刻判断是源文件本身缺标签还是转换脚本丢的。血泪经验是有些扫描仪导出的 SVS 里openslide.mpp-x是空的只有aperio.MPP有值代码里必须做兜底。mpp_x props.get(openslide.mpp-x) or props.get(aperio.MPP) if not mpp_x: raise RuntimeError(源文件缺少物理分辨率转换前必须先人工确认) mpp_x float(mpp_x) mpp_y float(props.get(openslide.mpp-y) or mpp_x)2.2 瓦片尺寸、压缩格式与边界块的真实长相SVS 的像素不是一条一条按行存的而是切成一格一格的瓦片Aperio 的习惯是 240×240其他厂商常见 256×256。这个数字很重要因为目标 TIFF 的瓦片尺寸如果和源不一致等于每一块都要重新拼装再切开速度会掉一个数量级而且边界块的处理稍有不慎就会出现黑边。查看压缩格式最直接的办法不是靠 openslide而是看一眼底层标签# 先确认文件确实是 TIFF 家族再看压缩方式和瓦片参数 tiffinfo case_01.svs | head -40输出里重点看Compression、Tile Width、Tile Length、Photometric Interpretation这几行。如果Compression显示JPEG说明像素是 YCbCr 编码后存进去的openslide 读出来会自动转成 RGB这一步转换本身就带来一次有损如果显示JPEG 2000解码会更慢某些老版本的依赖库甚至直接报错。边界块是另一个容易被忽略的点。一张 60000×45000 的切片按 240 切下来右边和下边那一圈瓦片是不满的SVS 里通常用填充色补齐。openslide 的read_region会帮你把越界部分处理成透明或白色但你自己用 tifffile 逐块写的时候如果没做裁剪写进去的就是垃圾数据下游拼接时会在切片边缘看到一条诡异的色带。# 手工取块时必须自己裁剪别指望库兜底 def read_tile(slide, level, x, y, size240): w, h slide.level_dimensions[level] size min(size, w - x, h - y) if size 0: return None region slide.read_region((x, y), level, (size, size)).convert(RGB) return region注意read_region的坐标永远是 layer 0 坐标系下的坐标哪怕你读的是第 3 层。这一点新手极容易踩写成该层坐标后取出来的图会是错位的。2.3 哪些标签必须跟着数据一起搬到 TIFF目标 TIFF 想要“能用”光有像素不够至少这几样必须搬过去标签来源缺失后果XResolution / YResolutionMPP 换算下游软件按 72 dpi 处理尺寸全错ResolutionUnit固定为厘米同上且不同软件解释不一致NewSubfileType每层区分看图软件只认第一层金字塔丢失ICC Profile源文件 ICC染色偏色定量分析不可比ImageDescription厂商信息部分工具拒绝加载其中分辨率换算是最容易错的一环。TIFF 的XResolution单位是“像素/分辨率单位”而ResolutionUnit通常设成厘米所以换算公式是# MPP 单位是微米/像素先转成像素/毫米再转成像素/厘米 pixels_per_cm_x 10000.0 / mpp_x pixels_per_cm_y 10000.0 / mpp_y print(fxres{pixels_per_cm_x:.2f}, yres{pixels_per_cm_y:.2f})0.25 微米/像素的切片算出来就是 40000 像素/厘米。这个数字写错一位下游测出来的细胞面积就能差出两个数量级。ICC 描述文件则是染色定量分析的底线HE 切片如果丢了色彩描述不同批次之间的颜色就没法直接比。3. 用 pyvips 做主干转换一条命令写出金字塔 TIFF结构摸清之后转换本身其实可以很短。我自己跑批量任务时默认走 pyvips原因是它在处理全切片这种体量时是流式的——按条带读、按瓦片写内存占用和图像尺寸基本无关。用 PIL 或者裸 numpy 做整层read_region一张 40 倍镜切片轻松吃掉 20 GB 内存机器直接原地去世。3.1 依赖怎么装为什么不用 ImageMagick环境准备只需要三样东西# 建议用 conda 或独立虚拟环境避免和系统里的 libtiff 打架 pip install pyvips openslide-python tifffile numpy # pyvips 依赖系统级 libvips装完必须验证一次 python -c import pyvips; print(pyvips.version(0), pyvips.version(1), pyvips.version(2))如果上面那行报Could not find module libvips说明只装了 Python 绑定没装底层库Linux 下补apt install libvips42 libvips-toolsmacOS 用brew install vipsWindows 需要把 libvips 的bin目录加进PATH。这一步卡住的人最多装完务必跑一遍版本号验证。为什么不用 ImageMagick 的convert一是它对金字塔结构的支持很弱转出来经常只剩一层二是它对 SVS 的解析依赖底层 libtiff遇到 JPEG 2000 压缩的瓦片直接失败三是它的内存策略对大图不友好我需要的是可控的流式处理不是“先试试看能不能跑完”。3.2 openslideload 到 tiffsave 的参数逐条过一遍核心就两行但每个参数都得知道在改什么import pyvips # 用 openslide 的加载器读而不是通用的 tiffload src pyvips.Image.openslideload( case_01.svs, level0, # 只取最高分辨率层金字塔由 tiffsave 重建 associatedrgb, # 只取主图不要附属的标签图 ) src.tiffsave( case_01.tif, tileTrue, # 必须开否则写成条带式下游读取极慢 tile_width240, # 尽量对齐源文件的瓦片尺寸 tile_height240, pyramidTrue, # 由 libvips 自动构建多分辨率层级 subifdTrue, # 层级写成 SubIFD而不是平铺成多页 compressionjpeg, # 见下一节的取舍 Q90, # JPEG 质量只在 jpeg 压缩下生效 bigtiffTrue, # 超过 4 GB 必须开否则写一半报错 propertiesTrue, # 把元数据写成 TIFF 标签 )先解释为什么要用openslideload而不是pyvips.Image.new_from_file。后者会走通用的 TIFF 加载器绝大多数 SVS 也能打开但遇到厂商私有标签或非常规压缩时会静默降级读出来的层数可能对不上。openslideload明确走 openslide 的解析路径行为可预期。pyramidTrue是关键。它的意思是“根据当前这张最高分辨率图按 2 的幂自动生成一组降采样层”。这里有个取舍如果源文件本身有 5 层且降采样倍率是 1、4、16、32、64而 pyvips 重建出来的是 1、2、4、8、16、32层级数就对不上了。多数下游工具不在乎这个差异它只要求“有一组能用的金字塔”但如果你的流程要求层级严格一致就得走第 4 章的 tifffile 手工路线。subifdTrue决定层级是写成 SubIFD 还是写成多页多帧。看图软件和 QuPath 这类工具认 SubIFDImageJ 的 Bio-Formats 两种都认但行为不同。默认选 SubIFD兼容面最广。bigtiffTrue不要省。一张 40 倍镜 HE 切片转成 JPEG 压缩后通常在 1 到 3 GB但染色深、组织满的片子轻松破 4 GB到那时候再改参数就得从头跑一遍。3.3 一个带日志与断点提示的生产脚本单张转换和研究性试跑是两回事。批量跑的时候我最怕的是跑到第 37 张报错然后不知道前面哪些成功了。下面这个脚本加了三样东西转换前后的文件大小对比、耗时统计、失败不中断import os import time import traceback import pyvips SRC_DIR ./svs DST_DIR ./tif os.makedirs(DST_DIR, exist_okTrue) for name in sorted(os.listdir(SRC_DIR)): if not name.lower().endswith(.svs): continue src_path os.path.join(SRC_DIR, name) dst_path os.path.join(DST_DIR, os.path.splitext(name)[0] .tif) if os.path.exists(dst_path): print(f[skip] {name} 已存在) continue t0 time.time() try: img pyvips.Image.openslideload(src_path, level0, associatedrgb) img.tiffsave( dst_path, tileTrue, tile_width240, tile_height240, pyramidTrue, subifdTrue, compressionjpeg, Q90, bigtiffTrue, propertiesTrue, ) src_mb os.path.getsize(src_path) / 1024 / 1024 dst_mb os.path.getsize(dst_path) / 1024 / 1024 print(f[ok] {name} {time.time()-t0:.1f}s f{src_mb:.0f}MB - {dst_mb:.0f}MB) except Exception: # 单张失败不阻断整批日志里留全栈方便回溯 print(f[fail] {name}) traceback.print_exc()这个脚本的逻辑有三个细节值得说。os.path.exists的跳过判断让脚本天然支持断点续跑中断之后重新执行只处理没转过的文件这在批量场景下省下的时间很可观。文件名用os.path.splitext而不是字符串替换避免文件名里本身带.svs字样时被误伤。traceback.print_exc()保留完整堆栈比只打印一句错误信息有用得多——很多失败其实是磁盘满了或者某一张的压缩格式特殊堆栈里一眼能看出来。转换耗时可以做个体感参考一张 2 GB 的 40 倍镜切片在 8 核机器上走 pyvips 大约 3 到 8 分钟瓶颈主要在 JPEG 重编码。如果只是换容器不想重编码理论上可以做到秒级但那需要直接搬运原始压缩流属于另一个层级的操作一般场景用不上。4. 用 tifffile 精细落盘瓦片、SubIFD 与分辨率标签怎么写pyvips 那条路快、稳、省内存但它把控制权交出去了层级怎么写、标签怎么放、压缩怎么选都由 libvips 决定。一旦下游工具对 TIFF 结构有硬性要求——比如必须带特定的ImageDescription、必须用 Deflate 而不是 JPEG、必须让层级降采样倍率和源文件完全一致——就得自己拿笔写。4.1 什么时候必须放弃 pyvips 换成 tifffile判断标准有三条命中任何一条我都会改用 tifffile第一目标工具明确拒绝 SubIFD。少数老版本的病理分析软件只认多页 TIFF把每一层当成一页来读这时候subifdFalse都救不了得手工控制NewSubfileType和页序。第二需要保留源文件的原始层级序列。tifffile 允许你按 openslide 报出来的level_dimensions一层一层写降采样倍率完全照抄源文件不做任何重建。第三需要在写的时候注入自定义标签或 OME-XML。tifffile 对extratags和 OME 元数据的控制粒度是 pyvips 给不了的。代价是内存。tifffile 的write()需要你手上有一整个 numpy 数组所以下面这段代码只适合单层尺寸可控的情况比如 layer 0 宽度在 2 万像素以内或者机器内存足够。大图请回到第 3 章。4.2 手工构造金字塔subifds 参数到底做了什么先看代码import numpy as np import openslide import tifffile SRC case_01.svs DST case_01_manual.tif slide openslide.OpenSlide(SRC) # 物理分辨率换算成 TIFF 的像素/厘米 mpp_x float(slide.properties.get(openslide.mpp-x) or slide.properties.get(aperio.MPP) or 0.25) mpp_y float(slide.properties.get(openslide.mpp-y) or mpp_x) xres 10000.0 / mpp_x yres 10000.0 / mpp_y level_count slide.level_count with tifffile.TiffWriter(DST, bigtiffTrue) as tw: for idx in range(level_count): w, h slide.level_dimensions[idx] # 整层读入内存这一步是大图的分水岭 region slide.read_region((0, 0), idx, (w, h)).convert(RGB) arr np.asarray(region) tw.write( arr, tile(240, 240), photometricrgb, compressiondeflate, # 无损体积比 jpeg 大一截 resolution(xres, yres), resolutionunitCENTIMETER, subfiletype0 if idx 0 else 1, # 只有第一层需要声明后续有几层 SubIFD subifds(level_count - 1) if idx 0 else None, metadataNone, ) print(done:, DST)关键在subifds这个参数。它在第一层的 IFD 里预留了“后面还有 N 个 SubIFD”的位置之后的每一次write()都会被塞进这些预留槽位而不是新开一个顶层 IFD。如果漏了这个参数写出来的就是 N 个互不相干的平铺页看图软件打开只看得到第一页金字塔等于没做。subfiletype也要配合着改。0 表示“这是主图”1 表示“这是降采样版本”。不设的话部分读取器会把每一层都当成独立的主图显示出来是一堆小图并排。resolution和resolutionunit是分辨率的落地点。单位必须是CENTIMETER数值就是前面算出来的10000 / mpp。这里如果写成INCH但数值还是按厘米算的下游读出来的尺寸会差 2.54 倍。compressiondeflate是有意选的。Deflate 走无损压缩转出来的像素和源文件解码后的结果完全一致方便后面做逐像素比对验收。代价是体积JPEG 压到 1.5 GB 的片子Deflate 通常要 8 到 15 GB。如果你的目的只是归档而不做定量分析把这一行换成compressionjpeg并加compressionargs{level: 90}更实际。4.3 分辨率标签与 ICC 的搬法上面代码已经带上了分辨率但 ICC 还没搬。ICC 描述文件在 openslide 里通常不在properties里而是作为附属数据存在。如果源文件有 ICC最省事的做法是转换前先把它单独导出来再在 tifffile 写入时通过extratags挂上去import tifffile from PIL import Image # 从源文件里把 ICC 描述文件抠出来 with Image.open(case_01.svs) as im: icc im.info.get(icc_profile) if icc: # 34675 是 TIFF 里 ICC Profile 的标准 tag 编号类型 UNDEFINED icc_tag (34675, 7, len(icc), icc, False) extra [icc_tag] else: extra []然后在tw.write()里加上extratagsextra。这段代码看起来绕但染色切片的颜色一致性就靠它。我见过太多“两张切片颜色不一样”的争论最后查出来是一张有 ICC 一张没有转换脚本把它当无关紧要的附属信息扔了。至于是不是要走 OME-TIFF看你下游生态。QuPath、Bio-Formats 系工具对 OME 支持很好能给每一层标注更明确的元数据但如果你只是要一个“能打开、尺寸对、能看到细节”的 TIFF普通 TIFF 加 SubIFD 就够了OME 带来的额外复杂度在这个场景下不划算。5. 转换避坑五个把活干废的具体现场转换脚本写完之后真正的麻烦才刚开始。下面五条都是我自己或者身边人实际遇到过的按出现频率排序。5.1 打开就废层级和分辨率的两个坑现象一转换成功但打开只看得到一张模糊的小图。原因金字塔层级没写进 SubIFD或者写了但没设NewSubfileType。看图软件默认读第一个 IFD读到的是最高分辨率层但如果层级被平铺成多页软件要么只显示第一页要么按页序把最小层当成主图。 解决用tiffinfo out.tif | grep -i subfiletype确认每层的类型标记如果是平铺结构回到第 4 章补上subifds和subfiletype参数重写。用 pyvips 的话检查subifdTrue有没有漏。现象二图像能正常显示但量出来的尺寸差了十倍以上。原因分辨率标签写错单位。常见的是把10000 / mpp像素/厘米直接写成1000 / mpp像素/毫米或者数值算对了但ResolutionUnit设成了INCH。 解决换算公式只有一条像素/厘米 10000 ÷ MPP单位固定填CENTIMETER。转换后用tiffinfo看一眼Resolution那行0.25 微米/像素的切片应该显示40000左右。低于一万或者高于十万基本可以确定写错了。5.2 跑完才发现不对体积、内存与色彩的三个坑现象三转完之后文件从 1.2 GB 涨到 14 GB磁盘直接告急。原因把 JPEG 压缩的瓦片解码成 RGB 之后用 LZW 或 Deflate 重新压。JPEG 对这种照片级纹理的压缩比是 15 到 25 倍LZW 只有 2 到 3 倍中间差了将近一个数量级。 解决如果下游能接受有损compressionjpeg配Q85到Q90肉眼几乎看不出差别体积能压回源文件的 1.5 倍以内。确实需要无损的改用compressionjpeg2000或者接受 Deflate 的体积代价别指望两全。现象四脚本跑到一半进程被系统杀掉日志里什么都没有。原因整层read_region把像素一次性拉进内存。一张 60000×45000 的 RGB 图是 8 GB 解码后数据加上中间副本和写入缓冲很容易触顶。OOM killer 不会给你留遗言。 解决换 pyvips 的流式路径第 3 章或者用 tifffile 配合磁盘上的 numpy memmap 做中转。判断标准很简单源切片 layer 0 的像素总数乘以 3 字节超过物理内存的一半就别硬来。现象五同一批切片转出来的 TIFF颜色偏得明显。原因ICC 描述文件没搬过去。SVS 里的 ICC 通常挂在主 IFD 的ImageDescription旁边或者作为独立 tag转换脚本只搬像素不搬它下游软件只好按 sRGB 解释染色深的切片会明显发暗发紫。 解决转换前先把 ICC 抠出来写入时通过extratags挂到 tag 34675。验证方法是转完之后用tiffinfo看有没有ICC Profile那一行或者直接用读取器把 ICC 读回来和源文件的字节做比对。6. 验收与进阶怎么证明转出来的 TIFF 没坏转换脚本跑通不代表转换正确。我吃过一次亏200 张切片批量转完抽查了三张都正常结果归档半年后有人反馈其中十几张打开是黑屏——原因是那几张源文件用的是 JPEG 2000 压缩pyvips 在某个版本下对边界块处理有问题转出来的边缘瓦片全填了零。从那以后我每次批量转换完都会强制走一遍验收。6.1 像素抽检MAE 为零才算无损最直接的办法是从源文件和目标文件里各抽若干块逐像素比对import random import numpy as np import openslide def patch(slide, level, x, y, size240): w, h slide.level_dimensions[level] x, y max(0, min(x, w - size)), max(0, min(y, h - size)) arr slide.read_region((x, y), level, (size, size)).convert(RGB) return np.asarray(arr, dtypenp.int16) src openslide.OpenSlide(case_01.svs) dst openslide.OpenSlide(case_01.tif) random.seed(42) errs [] for level in range(min(src.level_count, dst.level_count)): w, h src.level_dimensions[level] for _ in range(20): x, y random.randrange(w), random.randrange(h) a, b patch(src, level, x, y), patch(dst, level, x, y) errs.append(np.abs(a - b).mean()) print(f平均绝对误差: {sum(errs)/len(errs):.4f}) print(f最大单块误差: {max(errs):.4f})判定标准看压缩方式。无损压缩Deflate、LZW应该严格为 0出现非零说明像素真的变了JPEG 有损压缩在 Q90 时一般落在 1 到 3 之间超过 6 就要警惕——要么质量参数没生效要么层级对错了位置。level参数和x, y坐标的配对是这段代码的关键。read_region的坐标永远基于 layer 0但level决定读取哪一层的像素。如果源和目标层级数不同pyvips 重建金字塔时常见比对只能做到两边都有的层前面几层就够用了。6.2 回读分辨率与层级清单像素对了元数据还得再确认一遍。用 openslide 重新打开目标文件把关键属性打出来对照dst openslide.OpenSlide(case_01.tif) print(层级:, dst.level_dimensions) print(mpp-x:, dst.properties.get(openslide.mpp-x)) print(vendor:, dst.properties.get(openslide.vendor))能被 openslide 识别成通用瓦片 TIFF说明结构是干净的。如果mpp-x是None说明分辨率标签没写对——openslide 会尝试从XResolution换算换算不出来就是空的。这种情况回头检查第 4 章的resolution参数或者 pyvips 那条路的xres有没有带过去。vendor字段从原来的厂商名变成通用标识是正常的不用紧张那是 openslide 根据文件结构重新判断的结果不影响使用。做完这两步基本可以确认文件是健康的。如果下游还要接别的分析流程我会额外用目标工具本身打开一次因为“openslide 能读”和“目标软件能用”之间还隔着一层兼容性早点发现早点改。从那以后我每次转完切片都强制走一遍像素抽检加分辨率回读多花的两分钟远比事后翻账便宜。希望帮到你。本文还有配套的精品资源点击获取