KFBSlide

纯 Python 实现的 KFB（KFBio）数字病理切片读取库，提供与 OpenSlide 完全兼容的 API

English | 简体中文

✨ 特性 • 📦 安装 • 🚀 快速开始 • 📖 API • ⚡ 性能

✨ 特性

• 🐍 纯 Python 实现 — 零原生依赖，跨平台开箱即用
• 🔄 OpenSlide 兼容 API — 可直接替换 openslide-python，无需修改业务代码
• ⚡ 对比 OpenSlide 更快 — 典型场景下 KFB 读取速度优于 OpenSlide 读取 SVS（详见性能）
• 🔺 金字塔多层级读取 — 自动解析 KFB 内部 40× / 20× / 10× / 5× / 2.5× / 1.25× 层级
• 🖼️ 关联图像读取 — 支持 macro、label、thumbnail
• ⚡ Tile LRU 缓存 — 重复读取同区域加速 10~20 倍
• 📊 完整元数据支持 — MPP、扫描倍率、瓦片尺寸等

📦 安装

使用 uv（推荐）

uv pip install kfbslide

使用 pip

pip install kfbslide

仅依赖 Pillow，任何平台都能直接安装。

🚀 快速开始

作为 OpenSlide 的 drop-in 替代品

import kfbslide as openslide

slide = openslide.OpenSlide("path/to/sample.kfb")

print(f"层级数: {slide.level_count}")
print(f"Level 0 尺寸: {slide.dimensions}")
for i in range(slide.level_count):
    print(f"  Level {i}: {slide.level_dimensions[i]} "
          f"downsample={slide.level_downsamples[i]}")

# 读取区域（location 为 level 0 坐标，返回 RGBA）
img = slide.read_region((1000, 2000), 0, (256, 256))
img.save("region.png")

# 缩略图
thumb = slide.get_thumbnail((512, 512))
thumb.save("thumbnail.png")

# 关联图像
macro = slide.associated_images["macro"]
macro.save("macro.png")

# 属性读取
vendor = slide.properties[openslide.PROPERTY_NAME_VENDOR]
mpp_x = slide.properties[openslide.PROPERTY_NAME_MPP_X]

slide.close()

上下文管理器

with openslide.OpenSlide("sample.kfb") as slide:
    img = slide.read_region((0, 0), 0, (256, 256))
# 自动 close

📖 API 参考

OpenSlide(filename)

打开一个 KFB 文件。

类方法

属性

方法

属性常量

from kfbslide import (
    PROPERTY_NAME_VENDOR,           # "openslide.vendor"
    PROPERTY_NAME_MPP_X,            # "openslide.mpp-x"
    PROPERTY_NAME_MPP_Y,            # "openslide.mpp-y"
    PROPERTY_NAME_OBJECTIVE_POWER,  # "openslide.objective-power"
)

⚡ 性能

在 sample.kfb（85,678 × 44,995，78,724 tiles）上测试：

测试环境：Python 3.12，Pillow，SSD。

与 OpenSlide 对比

我们与 OpenSlide 读取 SVS 格式做了横向对比（测试脚本见 benchmarks/compare_kfb_svs.py）：

测试文件：KFB sample.kfb（85,678 × 44,995，40×），SVS sample.svs（42,009 × 22,721，40×）。
环境：Intel Xeon E5-2678 v3 / Python 3.12 / Pillow 12.2.0 / OpenSlide 1.4.6。
完整报告见 benchmarks/results/report.md。

🧵 线程安全与并发

自 0.3.4 起，一个 OpenSlide 实例可以被多个线程并发调用：

• 每个线程持有独立的文件句柄（threading.local），并发 read_region 不存在 seek/read 竞争；
• tile 缓存为按字节限容（默认 256 MiB/实例）且内部加锁，缓存 tile 为 RGBA（读路径免重复 alpha 转换）；
• 索引解析、JPEG 解码（Pillow）与文件 I/O 均会释放 GIL，多线程流水线在 I/O 密集场景（网络盘/慢速挂载）收益明显；纯 Python 胶水代码仍受 GIL 限制；
• fork 后子进程自动重开句柄，PyTorch DataLoader worker 场景继续可用。

# 共享单实例多线程：0.3.4 起安全，推荐用于区域批量扫描
slide = OpenSlide("slide.kfb")
regions = [((x, y), 0, (448, 448)) for y in range(0, 4096, 448) for x in range(0, 4096, 448)]
images = slide.read_regions(regions, max_workers=8)  # 库内线程池，按输入顺序返回
print(slide.cache_info())  # {'entries': 64, 'bytes': 16777216, 'max_bytes': 268435456}

内存估算：

• 共享单实例：所有线程共用一份缓存，峰值 ≈ max_bytes（默认 256 MiB）；
• 每线程独立实例：N 线程 ≈ N 份缓存，峰值 ≈ N × 256 MiB；
• 单 tile 缓存开销 ≈ tile_size² × 4 字节（RGBA；256px ≈ 256 KiB，512px ≈ 1 MiB）。

若需关闭多线程安全带来的句柄开销（几乎可忽略），或旧版本（<0.3.4）下并发，请使用"每线程独立实例"模式——8 线程 × 独立实例在 NVMe 上实测约 10× 吞吐。

🏗️ 架构

KFBSlide 完全基于纯 Python 实现，通过直接解析 KFB 二进制格式完成图像读取：

• 无需任何 C/C++ 扩展或系统动态库
• 不依赖 OpenSlide、libtiff、libjpeg 等外部库
• 单文件即可部署，适合服务器、容器、嵌入式等场景

📁 项目结构

kfbslide/
├── src/kfbslide/
│   ├── __init__.py          # 包入口，导出 OpenSlide API
│   ├── _slide.py            # OpenSlide 主类
│   ├── _kfbformat.py        # KFB 二进制格式解析
│   ├── _cache.py            # LRU tile 缓存
│   └── _exceptions.py       # OpenSlideError / 兼容异常
├── tests/                   # 测试（含 sample.kfb 软链）
├── examples/                # 示例脚本
├── docs/                    # 文档图片
├── README.md
├── LICENSE
└── pyproject.toml

⚠️ 已知限制

1. 只读：目前不支持写入 KFB 文件。
2. KFB v1.6：在版本 1.6 文件上验证过。其他版本可能需要适配。

📄 License

MIT

Copyright (c) 2026 Yifan Feng