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。

🏗️ 架构

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