{"id":51088453,"url":"https://github.com/yifanfeng97/kfbslide","last_synced_at":"2026-06-23T23:30:36.336Z","repository":{"id":364080386,"uuid":"1265900954","full_name":"yifanfeng97/kfbslide","owner":"yifanfeng97","description":"纯 Python KFB（KFBio）数字病理切片读取库，提供与 OpenSlide 完全兼容的 API","archived":false,"fork":false,"pushed_at":"2026-06-11T14:00:24.000Z","size":3699,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-11T16:04:01.257Z","etag":null,"topics":["digital-pathology","openslide","pathology","python","whole-slide-imaging","wsi"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/kfbslide","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yifanfeng97.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-11T07:04:36.000Z","updated_at":"2026-06-11T14:09:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yifanfeng97/kfbslide","commit_stats":null,"previous_names":["yifanfeng97/kfbslide"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/yifanfeng97/kfbslide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yifanfeng97%2Fkfbslide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yifanfeng97%2Fkfbslide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yifanfeng97%2Fkfbslide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yifanfeng97%2Fkfbslide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yifanfeng97","download_url":"https://codeload.github.com/yifanfeng97/kfbslide/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yifanfeng97%2Fkfbslide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34711176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["digital-pathology","openslide","pathology","python","whole-slide-imaging","wsi"],"created_at":"2026-06-23T23:30:34.713Z","updated_at":"2026-06-23T23:30:36.328Z","avatar_url":"https://github.com/yifanfeng97.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eKFBSlide\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003e纯 Python 实现的 KFB（KFBio）数字病理切片读取库，提供与 OpenSlide 完全兼容的 API\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README_EN.md\"\u003eEnglish\u003c/a\u003e |\n  \u003ca href=\"README.md\"\u003e简体中文\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/kfbslide\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/kfbslide?color=blue\" alt=\"PyPI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/kfbslide\"\u003e\u003cimg src=\"https://img.shields.io/pypi/pyversions/kfbslide\" alt=\"Python Versions\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yifanfeng97/kfbslide/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/kfbslide\"\u003e\u003cimg src=\"https://img.shields.io/pypi/dm/kfbslide?color=orange\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yifanfeng97/kfbslide\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/yifanfeng97/kfbslide?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#-特性\"\u003e✨ 特性\u003c/a\u003e •\n  \u003ca href=\"#-安装\"\u003e📦 安装\u003c/a\u003e •\n  \u003ca href=\"#-快速开始\"\u003e🚀 快速开始\u003c/a\u003e •\n  \u003ca href=\"#-api-参考\"\u003e📖 API\u003c/a\u003e •\n  \u003ca href=\"#-性能\"\u003e⚡ 性能\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/banner.png\" alt=\"KFBSlide Banner\" width=\"900\"\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ 特性\n\n- 🐍 **纯 Python 实现** — 零原生依赖，跨平台开箱即用\n- 🔄 **OpenSlide 兼容 API** — 可直接替换 `openslide-python`，无需修改业务代码\n- ⚡ **对比 OpenSlide 更快** — 典型场景下 KFB 读取速度优于 OpenSlide 读取 SVS（详见[性能](#-性能)）\n- 🔺 **金字塔多层级读取** — 自动解析 KFB 内部 40× / 20× / 10× / 5× / 2.5× / 1.25× 层级\n- 🖼️ **关联图像读取** — 支持 macro、label、thumbnail\n- ⚡ **Tile LRU 缓存** — 重复读取同区域加速 10~20 倍\n- 📊 **完整元数据支持** — MPP、扫描倍率、瓦片尺寸等\n\n---\n\n## 📦 安装\n\n### 使用 uv（推荐）\n\n```bash\nuv pip install kfbslide\n```\n\n### 使用 pip\n\n```bash\npip install kfbslide\n```\n\n仅依赖 Pillow，任何平台都能直接安装。\n\n---\n\n## 🚀 快速开始\n\n### 作为 OpenSlide 的 drop-in 替代品\n\n```python\nimport kfbslide as openslide\n\nslide = openslide.OpenSlide(\"path/to/sample.kfb\")\n\nprint(f\"层级数: {slide.level_count}\")\nprint(f\"Level 0 尺寸: {slide.dimensions}\")\nfor i in range(slide.level_count):\n    print(f\"  Level {i}: {slide.level_dimensions[i]} \"\n          f\"downsample={slide.level_downsamples[i]}\")\n\n# 读取区域（location 为 level 0 坐标，返回 RGBA）\nimg = slide.read_region((1000, 2000), 0, (256, 256))\nimg.save(\"region.png\")\n\n# 缩略图\nthumb = slide.get_thumbnail((512, 512))\nthumb.save(\"thumbnail.png\")\n\n# 关联图像\nmacro = slide.associated_images[\"macro\"]\nmacro.save(\"macro.png\")\n\n# 属性读取\nvendor = slide.properties[openslide.PROPERTY_NAME_VENDOR]\nmpp_x = slide.properties[openslide.PROPERTY_NAME_MPP_X]\n\nslide.close()\n```\n\n### 上下文管理器\n\n```python\nwith openslide.OpenSlide(\"sample.kfb\") as slide:\n    img = slide.read_region((0, 0), 0, (256, 256))\n# 自动 close\n```\n\n---\n\n## 📖 API 参考\n\n### `OpenSlide(filename)`\n\n打开一个 KFB 文件。\n\n### 类方法\n\n| 方法 | 说明 |\n|------|------|\n| `OpenSlide.detect_format(filename)` | 检测文件格式，返回 `\"kfbio\"` 或 `None` |\n\n### 属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `level_count` | `int` | 金字塔层级数 |\n| `dimensions` | `(int, int)` | Level 0 尺寸（最高分辨率） |\n| `level_dimensions` | `Tuple[(w, h), ...]` | 每层尺寸 |\n| `level_downsamples` | `Tuple[float, ...]` | 每层下采样倍数 |\n| `properties` | `Mapping[str, str]` | 元数据属性（只读映射） |\n| `associated_images` | `Mapping[str, PIL.Image]` | 关联图像：macro、label、thumbnail |\n| `color_profile` | `object \\| None` | ICC 颜色配置文件（当前返回 `None`） |\n\n### 方法\n\n| 方法 | 说明 |\n|------|------|\n| `read_region(location, level, size)` | 读取指定区域，返回 **RGBA** 图像 |\n| `get_best_level_for_downsample(downsample)` | 根据下采样倍数选择最佳层级 |\n| `get_thumbnail(size)` | 生成缩略图 |\n| `set_cache(cache)` | API 兼容方法（当前为 no-op） |\n| `close()` | 关闭并释放资源 |\n\n### 属性常量\n\n```python\nfrom kfbslide import (\n    PROPERTY_NAME_VENDOR,           # \"openslide.vendor\"\n    PROPERTY_NAME_MPP_X,            # \"openslide.mpp-x\"\n    PROPERTY_NAME_MPP_Y,            # \"openslide.mpp-y\"\n    PROPERTY_NAME_OBJECTIVE_POWER,  # \"openslide.objective-power\"\n)\n```\n\n---\n\n## ⚡ 性能\n\n在 `sample.kfb`（85,678 × 44,995，78,724 tiles）上测试：\n\n| 操作 | 时间 | 备注 |\n|------|------|------|\n| 首次读取 512×512 region | ~5.7 ms | Pillow 后端 |\n| 缓存命中读取 512×512 | **~0.9 ms** | 6× 加速 |\n| 扫描 20 个相邻 512×512 region（首次） | ~58 ms | 2.9 ms/region |\n| 扫描 20 个相邻 512×512 region（缓存后） | **~20 ms** | 1.0 ms/region，2.9× 加速 |\n\n\u003e 测试环境：Python 3.12，Pillow，SSD。\n\n### 与 OpenSlide 对比\n\n我们与 OpenSlide 读取 SVS 格式做了横向对比（测试脚本见 `benchmarks/compare_kfb_svs.py`）：\n\n| 操作 | KFBSlide (KFB) | OpenSlide (SVS) | 加速比 |\n|------|----------------|-----------------|--------|\n| 单区域 512×512 | 5.70 ms | 7.64 ms | **1.34×** |\n| 缓存命中 512×512 | 0.90 ms | 7.10 ms | **7.89×** |\n| 单区域 1024×1024 | 16.69 ms | 29.39 ms | **1.76×** |\n| 缓存命中 1024×1024 | 3.00 ms | 28.50 ms | **9.50×** |\n| 连续扫描 100 tiles | 302.41 ms | 840.74 ms | **2.78×** |\n| 随机访问 100 tiles | 587.49 ms | 1047.70 ms | **1.78×** |\n| Level 1 512×512 | 6.06 ms | 32.23 ms | **5.32×** |\n\n\u003e 测试文件：KFB `sample.kfb`（85,678 × 44,995，40×），SVS `sample.svs`（42,009 × 22,721，40×）。  \n\u003e 环境：Intel Xeon E5-2678 v3 / Python 3.12 / Pillow 12.2.0 / OpenSlide 1.4.6。  \n\u003e 完整报告见 `benchmarks/results/report.md`。\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/benchmark_region_zh.png\" alt=\"单区域读取与缓存命中\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/benchmark_scan_zh.png\" alt=\"瓦片扫描延迟\" width=\"900\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/benchmark_level_zh.png\" alt=\"金字塔层级读取延迟\" width=\"900\"\u003e\n\u003c/p\u003e\n\n---\n\n## 🏗️ 架构\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/fw_zh.png\" alt=\"KFBSlide Architecture\" width=\"800\"\u003e\n\u003c/p\u003e\n\nKFBSlide 完全基于纯 Python 实现，通过直接解析 KFB 二进制格式完成图像读取：\n\n- **无需任何 C/C++ 扩展或系统动态库**\n- **不依赖 OpenSlide、libtiff、libjpeg 等外部库**\n- **单文件即可部署，适合服务器、容器、嵌入式等场景**\n\n---\n\n## 📁 项目结构\n\n```\nkfbslide/\n├── src/kfbslide/\n│   ├── __init__.py          # 包入口，导出 OpenSlide API\n│   ├── _slide.py            # OpenSlide 主类\n│   ├── _kfbformat.py        # KFB 二进制格式解析\n│   ├── _cache.py            # LRU tile 缓存\n│   └── _exceptions.py       # OpenSlideError / 兼容异常\n├── tests/                   # 测试（含 sample.kfb 软链）\n├── examples/                # 示例脚本\n├── docs/                    # 文档图片\n├── README.md\n├── LICENSE\n└── pyproject.toml\n```\n\n---\n\n## ⚠️ 已知限制\n\n1. **只读**：目前不支持写入 KFB 文件。\n2. **KFB v1.6**：在版本 1.6 文件上验证过。其他版本可能需要适配。\n\n---\n\n## 📄 License\n\n[MIT](LICENSE)\n\nCopyright (c) 2026 Yifan Feng\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyifanfeng97%2Fkfbslide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyifanfeng97%2Fkfbslide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyifanfeng97%2Fkfbslide/lists"}