kfbslide 0.2.0__py3-none-any.whl

kfbslide/__init__.py

@@ -0,0 +1,60 @@
+"""
+KFBSlide — Pure Python KFB whole-slide image reader.
+
+A minimal, cross-platform reader for KFB (KFBio) whole-slide images
+with an OpenSlide-compatible API.
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+License: MIT
+
+Drop-in replacement usage:
+    import kfbslide as openslide
+    slide = openslide.OpenSlide("sample.kfb")
+"""
+
+from ._slide import OpenSlide, KfbSlide, open_slide
+from ._exceptions import (
+    OpenSlideError,
+    OpenSlideUnsupportedFormatError,
+    KfbError,
+    KfbUnsupportedFormatError,
+    KfbOpenError,
+)
+
+__version__ = "0.2.0"
+
+# Standard OpenSlide property name constants
+PROPERTY_NAME_VENDOR = "openslide.vendor"
+PROPERTY_NAME_QUICKHASH1 = "openslide.quickhash-1"
+PROPERTY_NAME_BACKGROUND_COLOR = "openslide.background-color"
+PROPERTY_NAME_OBJECTIVE_POWER = "openslide.objective-power"
+PROPERTY_NAME_MPP_X = "openslide.mpp-x"
+PROPERTY_NAME_MPP_Y = "openslide.mpp-y"
+PROPERTY_NAME_BOUNDS_X = "openslide.bounds-x"
+PROPERTY_NAME_BOUNDS_Y = "openslide.bounds-y"
+PROPERTY_NAME_BOUNDS_WIDTH = "openslide.bounds-width"
+PROPERTY_NAME_BOUNDS_HEIGHT = "openslide.bounds-height"
+
+__all__ = [
+    # Primary OpenSlide API
+    "OpenSlide",
+    "OpenSlideError",
+    "OpenSlideUnsupportedFormatError",
+    # Property constants
+    "PROPERTY_NAME_VENDOR",
+    "PROPERTY_NAME_QUICKHASH1",
+    "PROPERTY_NAME_BACKGROUND_COLOR",
+    "PROPERTY_NAME_OBJECTIVE_POWER",
+    "PROPERTY_NAME_MPP_X",
+    "PROPERTY_NAME_MPP_Y",
+    "PROPERTY_NAME_BOUNDS_X",
+    "PROPERTY_NAME_BOUNDS_Y",
+    "PROPERTY_NAME_BOUNDS_WIDTH",
+    "PROPERTY_NAME_BOUNDS_HEIGHT",
+    # Backward compatibility
+    "KfbSlide",
+    "open_slide",
+    "KfbError",
+    "KfbUnsupportedFormatError",
+    "KfbOpenError",
+]

kfbslide/_cache.py

@@ -0,0 +1,40 @@
+"""LRU cache for decoded KFB tiles.
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+"""
+
+from collections import OrderedDict
+from typing import Optional
+
+from PIL import Image
+
+
+class _LRUCache:
+    """OrderedDict-backed LRU cache for decoded tiles (O(1) ops)."""
+
+    __slots__ = ("capacity", "_cache")
+
+    def __init__(self, capacity: int):
+        self.capacity = max(0, capacity)
+        self._cache: OrderedDict[int, Image.Image] = OrderedDict()
+
+    def get(self, key: int) -> Optional[Image.Image]:
+        if key not in self._cache:
+            return None
+        self._cache.move_to_end(key)
+        return self._cache[key]
+
+    def put(self, key: int, value: Image.Image) -> None:
+        if self.capacity <= 0:
+            return
+        if key in self._cache:
+            self._cache.move_to_end(key)
+        elif len(self._cache) >= self.capacity:
+            self._cache.popitem(last=False)
+        self._cache[key] = value
+
+    def clear(self) -> None:
+        self._cache.clear()
+
+    def __len__(self) -> int:
+        return len(self._cache)

kfbslide/_exceptions.py

@@ -0,0 +1,22 @@
+"""KFBSlide / OpenSlide-compatible exceptions.
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+"""
+
+
+class OpenSlideError(Exception):
+    """Base exception for OpenSlide errors."""
+
+    pass
+
+
+class OpenSlideUnsupportedFormatError(OpenSlideError):
+    """File format not supported or file is corrupted."""
+
+    pass
+
+
+# Backward compatibility aliases
+KfbError = OpenSlideError
+KfbUnsupportedFormatError = OpenSlideUnsupportedFormatError
+KfbOpenError = OpenSlideError

kfbslide/_kfbformat.py

@@ -0,0 +1,244 @@
+"""
+KFB 文件格式解析器 —— 纯 Python 实现
+
+基于对 KFB 文件二进制结构的分析：
+- Section 0x01: 文件基本信息（版本、尺寸、瓦片数等）
+- Section 0x02: 关联图像（macro/label/thumbnail）信息
+- 关联图像数据: JPEG 格式，紧跟在 section 0x02 之后
+- 瓦片数据: JPEG 格式，通过瓦片索引表定位
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+"""
+
+import struct
+from dataclasses import dataclass
+from typing import List, Optional, Dict
+
+
+@dataclass
+class KfbSection:
+    """KFB Section: f? XX ee ee ... ff XX ee ee"""
+
+    sec_type: int
+    marker: int
+    offset: int  # 在文件中的绝对偏移
+    footer_pos: int  # footer 在文件中的绝对偏移
+    payload: bytes
+
+
+@dataclass
+class KfbHeader:
+    """KFB 文件头信息 (Section 0x01)"""
+
+    magic: str  # "KFB"
+    version: float  # 版本号 (如 1.6)
+    tile_count: int  # 瓦片总数
+    height: int  # 基础图像高度
+    width: int  # 基础图像宽度
+    scan_scale: int  # 扫描倍率 (如 40)
+    format: str  # 压缩格式 (如 "JPEG")
+    spend_time: int  # 扫描耗时
+    scan_time: int  # 扫描时间戳
+    tile_size: int  # 瓦片尺寸 (如 256)
+    # 以下为解析出的字段
+    section_0x02_offset: int  # section 0x02 (macro) 在文件中的偏移
+    section_0x03_offset: int  # section 0x03 (label) 在文件中的偏移
+    # 瓦片索引表范围
+    tile_index_start: int  # 索引表起始偏移
+    tile_index_end: int  # 索引表结束偏移
+    # 原始未知字段
+    _raw_field_0x3c: int
+    mpp: float  # microns per pixel
+
+
+@dataclass
+class KfbAssocImage:
+    """关联图像信息"""
+
+    name: str
+    width: int
+    height: int
+    data_length: int
+    data_offset: int  # 在文件中的绝对偏移
+
+
+@dataclass
+class KfbFileInfo:
+    """完整的 KFB 文件信息"""
+
+    header: KfbHeader
+    assoc_images: List[KfbAssocImage]
+    tile_index_offset: int
+    tile_data_offset: int
+
+
+def _read_section(data: bytes, offset: int) -> Optional[KfbSection]:
+    """读取一个 section: f? XX ee ee ... ff XX ee ee"""
+    if offset + 4 > len(data):
+        return None
+
+    header = data[offset : offset + 4]
+    if header[2:4] != b"\xee\xee":
+        return None
+
+    sec_type = header[1]
+    sec_marker = header[0]
+
+    # 寻找 footer: ff XX ee ee
+    footer_pos = offset + 4
+    max_search = min(offset + 100000, len(data) - 4)
+    while footer_pos < max_search:
+        if data[footer_pos : footer_pos + 4] == bytes([0xFF, sec_type, 0xEE, 0xEE]):
+            break
+        footer_pos += 1
+    else:
+        return None
+
+    payload = data[offset + 4 : footer_pos]
+    return KfbSection(
+        sec_type=sec_type,
+        marker=sec_marker,
+        offset=offset,
+        footer_pos=footer_pos,
+        payload=payload,
+    )
+
+
+def _parse_header(section: KfbSection) -> KfbHeader:
+    """解析 Section 0x01 (文件头)"""
+    p = section.payload
+    if len(p) < 88:
+        raise ValueError(f"Header section too small: {len(p)} bytes")
+
+    return KfbHeader(
+        magic=p[0:4].decode("ascii", errors="replace").rstrip("\x00"),
+        version=struct.unpack("<f", p[8:12])[0],
+        tile_count=struct.unpack("<I", p[12:16])[0],
+        height=struct.unpack("<I", p[16:20])[0],
+        width=struct.unpack("<I", p[20:24])[0],
+        scan_scale=struct.unpack("<I", p[24:28])[0],
+        format=p[28:32].decode("ascii", errors="replace").rstrip("\x00"),
+        spend_time=struct.unpack("<I", p[36:40])[0],
+        scan_time=struct.unpack("<q", p[40:48])[0],
+        tile_size=struct.unpack("<I", p[84:88])[0],
+        section_0x02_offset=struct.unpack("<I", p[48:52])[0],
+        section_0x03_offset=struct.unpack("<I", p[52:56])[0],
+        tile_index_end=struct.unpack("<I", p[56:60])[0],
+        _raw_field_0x3c=struct.unpack("<I", p[60:64])[0],
+        tile_index_start=struct.unpack("<I", p[64:68])[0],
+        mpp=struct.unpack("<f", p[72:76])[0],
+    )
+
+
+def _parse_image_section(data: bytes, section_offset: int, name: str) -> KfbAssocImage:
+    """解析一个图像描述 section (0x02 或 0x03)"""
+    p = data[section_offset + 4 : section_offset + 4 + 44]
+    height = struct.unpack("<I", p[4:8])[0]
+    width = struct.unpack("<I", p[8:12])[0]
+    data_length = struct.unpack("<I", p[16:20])[0]
+    rel_offset = struct.unpack("<I", p[20:24])[0]
+    data_offset = section_offset + rel_offset
+    return KfbAssocImage(
+        name=name,
+        width=width,
+        height=height,
+        data_length=data_length,
+        data_offset=data_offset,
+    )
+
+
+def _parse_assoc_images(sec2: KfbSection, header: KfbHeader, data: bytes) -> List[KfbAssocImage]:
+    """
+    解析所有关联图像信息。
+
+    文件结构:
+    - section 0x02: macro 图像信息
+    - section 0x03: label 图像信息
+    - thumbnail: 动态生成，不在文件中预存
+    """
+    images = []
+
+    # macro (section 0x02)
+    images.append(_parse_image_section(data, sec2.offset, "macro"))
+
+    # label (section 0x03)
+    label_sec_offset = header.section_0x03_offset
+    if label_sec_offset > 0 and data[label_sec_offset : label_sec_offset + 2] == b"\xf1\x03":
+        images.append(_parse_image_section(data, label_sec_offset, "label"))
+
+    return images
+
+
+def parse_kfb_file(path: str) -> KfbFileInfo:
+    """解析 KFB 文件，返回完整信息。
+
+    按需读取数据：先读 1MB，如果 section 0x02 或 JPEG 标记超出范围，
+    则动态扩展读取更多数据。
+    """
+    with open(path, "rb") as f:
+        # 先读取前 1MB（通常足够包含文件头）
+        data = bytearray(f.read(1024 * 1024))
+
+        # 读取 section 0x01
+        sec1 = _read_section(data, 0)
+        if not sec1 or sec1.sec_type != 0x01:
+            raise ValueError("Invalid KFB file: missing section 0x01")
+
+        header = _parse_header(sec1)
+
+        # 搜索 section 0x02 (它不一定紧跟在 section 0x01 之后)
+        sec2_pos = sec1.footer_pos + 4
+        needed = sec2_pos + 10000 + 4  # 搜索范围 + footer 安全区
+        while len(data) < needed:
+            chunk = f.read(1024 * 1024)
+            if not chunk:
+                break
+            data.extend(chunk)
+
+        sec2 = None
+        max_search = min(sec2_pos + 10000, len(data) - 4)
+        while sec2_pos < max_search:
+            sec2 = _read_section(data, sec2_pos)
+            if sec2 and sec2.sec_type == 0x02:
+                break
+            sec2_pos += 1
+        else:
+            raise ValueError("Invalid KFB file: missing section 0x02")
+
+        # 关联图像
+        assoc_images = _parse_assoc_images(sec2, header, data)
+
+        # 计算瓦片区域
+        last_assoc = assoc_images[-1]
+        tile_index_offset = last_assoc.data_offset + last_assoc.data_length
+
+        # 搜索第一个 JPEG 瓦片：确保数据足够覆盖搜索范围
+        needed_jpeg = tile_index_offset + 1024 * 1024  # 至少再读 1MB
+        while len(data) < needed_jpeg:
+            chunk = f.read(1024 * 1024)
+            if not chunk:
+                break
+            data.extend(chunk)
+
+        first_jpeg = data.find(b"\xff\xd8\xff", tile_index_offset)
+        if first_jpeg == -1:
+            # 继续读取更多数据直到文件末尾
+            while True:
+                chunk = f.read(1024 * 1024)
+                if not chunk:
+                    break
+                offset = len(data)
+                data.extend(chunk)
+                local_jpeg = chunk.find(b"\xff\xd8\xff")
+                if local_jpeg != -1:
+                    first_jpeg = offset + local_jpeg
+                    break
+
+    tile_data_offset = first_jpeg if first_jpeg != -1 else tile_index_offset
+
+    return KfbFileInfo(
+        header=header,
+        assoc_images=assoc_images,
+        tile_index_offset=tile_index_offset,
+        tile_data_offset=tile_data_offset,
+    )

kfbslide/_slide.py

@@ -0,0 +1,525 @@
+"""
+KFBSlide — OpenSlide-compatible API for KFB files.
+
+Architecture:
+- File header parsing: Pure Python (cross-platform)
+- Associated images: Pure Python (read JPEG directly from file)
+- Tile reading: Pure Python via tile index table
+- Tile cache: LRU decoded-tile cache for repeated reads
+- JPEG decoding: Pillow (pure Python, no extra dependencies)
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+"""
+
+import io
+import struct
+from collections.abc import Mapping
+from typing import Dict, List, Optional, Tuple
+
+from PIL import Image
+
+from ._cache import _LRUCache
+from ._exceptions import OpenSlideError, OpenSlideUnsupportedFormatError
+from ._kfbformat import KfbAssocImage, KfbFileInfo, parse_kfb_file
+
+
+class _KfbPropertyMap(Mapping):
+    """Read-only mapping compatible with OpenSlide's property map."""
+
+    __slots__ = ("_data",)
+
+    def __init__(self, items: Dict[str, str]):
+        self._data = dict(items)
+
+    def __getitem__(self, key: str) -> str:
+        return self._data[key]
+
+    def __iter__(self):
+        return iter(self._data)
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    def __repr__(self) -> str:
+        return f"_KfbPropertyMap({self._data!r})"
+
+
+class _AssociatedImageMap(Mapping):
+    """Lazy read-only mapping for associated images.
+
+    When a file_handle_getter is provided and returns a valid handle,
+    it reuses that handle to avoid reopening the file on every access.
+    If the handle is unavailable (e.g. slide closed), falls back to
+    opening the file independently.
+    """
+
+    __slots__ = ("_filename", "_assoc_list", "_names", "_cache", "_fh_getter")
+
+    def __init__(
+        self,
+        filename: str,
+        assoc_images: List[KfbAssocImage],
+        file_handle_getter=None,
+    ):
+        self._filename = filename
+        self._assoc_list = assoc_images
+        self._names = [a.name for a in assoc_images]
+        self._cache: Dict[str, Image.Image] = {}
+        self._fh_getter = file_handle_getter
+
+    def __getitem__(self, key: str) -> Image.Image:
+        if key in self._cache:
+            return self._cache[key]
+        for assoc in self._assoc_list:
+            if assoc.name == key:
+                # Try to reuse the slide's file handle first.
+                fh = self._fh_getter() if self._fh_getter else None
+                if fh is not None:
+                    fh.seek(assoc.data_offset)
+                    jpeg_data = fh.read(assoc.data_length)
+                else:
+                    with open(self._filename, "rb") as f:
+                        f.seek(assoc.data_offset)
+                        jpeg_data = f.read(assoc.data_length)
+                img = Image.open(io.BytesIO(jpeg_data)).convert("RGBA")
+                self._cache[key] = img
+                return img
+        raise KeyError(key)
+
+    def __iter__(self):
+        return iter(self._names)
+
+    def __len__(self) -> int:
+        return len(self._names)
+
+    def __repr__(self) -> str:
+        return f"_AssociatedImageMap({self._names!r})"
+
+
+class _TileIndex:
+    """Parsed KFB tile index table."""
+
+    __slots__ = (
+        "filename",
+        "tile_size",
+        "entries",
+        "lookup",
+        "offsets",
+        "level_scales",
+        "scale_to_level",
+        "level_count",
+        "_level_dimensions",
+        "_level_downsamples",
+    )
+
+    def __init__(self, filename: str, info: KfbFileInfo):
+        self.filename = filename
+        self.tile_size = info.header.tile_size
+
+        tile_count = info.header.tile_count
+        idx_start = info.header.tile_index_start
+
+        with open(filename, "rb") as f:
+            f.seek(idx_start)
+            data = f.read(tile_count * 64)
+
+        self.entries: List[Dict] = []
+        self.lookup: Dict[Tuple[float, int, int], int] = {}
+        scales = set()
+
+        for i in range(tile_count):
+            off = i * 64
+            e = data[off : off + 64]
+            entry = {
+                "scale": struct.unpack("<f", e[20:24])[0],
+                "x": struct.unpack("<I", e[4:8])[0],
+                "y": struct.unpack("<I", e[8:12])[0],
+                "width": struct.unpack("<I", e[12:16])[0],
+                "height": struct.unpack("<I", e[16:20])[0],
+                "size": struct.unpack("<I", e[32:36])[0],
+            }
+            self.entries.append(entry)
+            self.lookup[(entry["scale"], entry["x"], entry["y"])] = i
+            scales.add(entry["scale"])
+
+        # Compute file offset for each tile.
+        cumulative = info.tile_data_offset
+        self.offsets: List[int] = []
+        for entry in self.entries:
+            self.offsets.append(cumulative)
+            cumulative += entry["size"]
+
+        # Build level info from scales (descending: 40.0, 20.0, ...).
+        sorted_scales = sorted([s for s in scales if s >= 1.0], reverse=True)
+        self.level_scales = {i: s for i, s in enumerate(sorted_scales)}
+        self.scale_to_level = {s: i for i, s in self.level_scales.items()}
+        self.level_count = len(sorted_scales)
+
+        # Level dimensions derived from base resolution.
+        base_w, base_h = info.header.width, info.header.height
+        self._level_dimensions: List[Tuple[int, int]] = []
+        self._level_downsamples: List[float] = []
+        for i in range(self.level_count):
+            scale = self.level_scales[i]
+            ds = info.header.scan_scale / scale
+            self._level_downsamples.append(ds)
+            self._level_dimensions.append((int(base_w / ds), int(base_h / ds)))
+
+    def level_dimensions(self) -> Tuple[Tuple[int, int], ...]:
+        return tuple(self._level_dimensions)
+
+    def level_downsamples(self) -> Tuple[float, ...]:
+        return tuple(self._level_downsamples)
+
+    def get_best_level_for_downsample(self, downsample: float) -> int:
+        """Choose the level with downsample closest to but not greater than target."""
+        best = 0
+        for i in range(self.level_count):
+            if self._level_downsamples[i] <= downsample:
+                best = i
+            else:
+                break
+        return best
+
+
+class OpenSlide:
+    """
+    KFB whole-slide image reader with OpenSlide-compatible API.
+
+    Interface compatible with openslide-python, but completely independent
+    and implemented in pure Python with no native library dependencies.
+    """
+
+    __slots__ = (
+        "_filename",
+        "_closed",
+        "_error",
+        "_tile_cache",
+        "_file_handle",
+        "_info",
+        "_index",
+        "_properties",
+        "_associated_images",
+    )
+
+    def __init__(self, filename: str):
+        self._filename = filename
+        self._closed = False
+        self._error = False
+        self._tile_cache = _LRUCache(256)
+        self._file_handle: Optional[io.BufferedReader] = None
+
+        try:
+            self._info = parse_kfb_file(filename)
+        except Exception as e:
+            raise OpenSlideUnsupportedFormatError(f"Cannot parse KFB file: {e}")
+
+        try:
+            self._index = _TileIndex(filename, self._info)
+        except Exception as e:
+            raise OpenSlideError(f"Failed to build tile index: {e}")
+
+        try:
+            self._file_handle = open(filename, "rb")
+        except Exception as e:
+            raise OpenSlideError(f"Failed to open file handle: {e}")
+
+        # Pre-build property map.
+        header = self._info.header
+        props = {
+            "openslide.vendor": "kfbio",
+            "openslide.quickhash-1": "",
+            "openslide.mpp-x": str(header.mpp),
+            "openslide.mpp-y": str(header.mpp),
+            "openslide.objective-power": str(header.scan_scale),
+            "kfbio.vendor": "Kfbio",
+            "kfbio.version": str(header.version),
+            "kfbio.scan_scale": str(header.scan_scale),
+            "kfbio.tile_size": str(header.tile_size),
+            "kfbio.tile_count": str(header.tile_count),
+            "kfbio.width": str(header.width),
+            "kfbio.height": str(header.height),
+            "kfbio.spend_time": str(header.spend_time),
+            "kfbio.scan_time": str(header.scan_time),
+            "kfbio.mpp": str(header.mpp),
+        }
+        self._properties = _KfbPropertyMap(props)
+
+        # Lazy associated images map (reuses file handle when possible).
+        self._associated_images = _AssociatedImageMap(
+            filename,
+            self._info.assoc_images,
+            file_handle_getter=lambda: self._file_handle
+            if not self._closed
+            else None,
+        )
+
+    # ------------------------------------------------------------------
+    # Class methods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def detect_format(cls, filename: str) -> Optional[str]:
+        """Detect whether a file is a KFB format slide.
+
+        Returns:
+            "kfbio" if the file is recognized, None otherwise.
+        """
+        try:
+            info = parse_kfb_file(filename)
+            if info.header.magic == "KFB":
+                return "kfbio"
+        except Exception:
+            pass
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _check_open(self) -> None:
+        """Raise if the slide is closed."""
+        if self._closed:
+            raise OpenSlideError("Slide is closed")
+
+    def _check_error(self) -> None:
+        """Raise if an error has occurred (latching semantics)."""
+        if self._error:
+            raise OpenSlideError("OpenSlide error has occurred")
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}({self._filename!r})"
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
+    def close(self) -> None:
+        """Close the slide and release resources."""
+        self._closed = True
+        self._tile_cache.clear()
+        if self._file_handle is not None:
+            try:
+                self._file_handle.close()
+            except Exception:
+                pass
+            self._file_handle = None
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def level_count(self) -> int:
+        """Number of pyramid levels."""
+        self._check_open()
+        self._check_error()
+        return self._index.level_count
+
+    @property
+    def dimensions(self) -> Tuple[int, int]:
+        """Dimensions of the slide at level 0 (highest resolution)."""
+        self._check_open()
+        self._check_error()
+        return self._index.level_dimensions()[0]
+
+    @property
+    def level_dimensions(self) -> Tuple[Tuple[int, int], ...]:
+        """Dimensions of each pyramid level."""
+        self._check_open()
+        self._check_error()
+        return self._index.level_dimensions()
+
+    @property
+    def level_downsamples(self) -> Tuple[float, ...]:
+        """Downsample factor for each level."""
+        self._check_open()
+        self._check_error()
+        return self._index.level_downsamples()
+
+    @property
+    def properties(self) -> Mapping[str, str]:
+        """Metadata properties as a read-only mapping."""
+        self._check_open()
+        self._check_error()
+        return self._properties
+
+    @property
+    def associated_images(self) -> Mapping[str, Image.Image]:
+        """Associated images (macro, label, thumbnail) as a lazy mapping."""
+        self._check_open()
+        self._check_error()
+        return self._associated_images
+
+    @property
+    def color_profile(self) -> Optional[object]:
+        """Embedded ICC color profile, or None if not available."""
+        self._check_open()
+        self._check_error()
+        return None
+
+    # ------------------------------------------------------------------
+    # Reading operations
+    # ------------------------------------------------------------------
+
+    def get_best_level_for_downsample(self, downsample: float) -> int:
+        """Get the best pyramid level for a given downsample factor."""
+        self._check_open()
+        self._check_error()
+        return self._index.get_best_level_for_downsample(downsample)
+
+    def read_region(
+        self,
+        location: Tuple[int, int],
+        level: int,
+        size: Tuple[int, int],
+    ) -> Image.Image:
+        """
+        Read a region from the slide.
+
+        Args:
+            location: (x, y) top-left coordinates in level 0.
+            level: Pyramid level.
+            size: (width, height) output size.
+
+        Returns:
+            PIL.Image.Image (RGBA).
+        """
+        self._check_open()
+        self._check_error()
+
+        try:
+            if level < 0 or level >= self._index.level_count:
+                raise OpenSlideError(f"Invalid level {level}")
+
+            scale = self._index.level_scales[level]
+            ds = self._info.header.scan_scale / scale
+
+            x0, y0 = int(location[0] / ds), int(location[1] / ds)
+            w, h = int(size[0]), int(size[1])
+
+            out = Image.new("RGBA", (w, h), (0, 0, 0, 0))
+            tile_size = self._index.tile_size
+
+            tx_start = x0 // tile_size
+            ty_start = y0 // tile_size
+            tx_end = (x0 + w - 1) // tile_size + 1
+            ty_end = (y0 + h - 1) // tile_size + 1
+
+            if self._file_handle is None:
+                raise OpenSlideError("Slide is closed")
+            f = self._file_handle
+
+            for ty in range(ty_start, ty_end):
+                for tx in range(tx_start, tx_end):
+                    tile_x = tx * tile_size
+                    tile_y = ty * tile_size
+                    key = (scale, tile_x, tile_y)
+                    idx = self._index.lookup.get(key)
+                    if idx is None:
+                        continue
+
+                    entry = self._index.entries[idx]
+                    tw, th = entry["width"], entry["height"]
+
+                    # Try cached decoded tile first.
+                    tile = self._tile_cache.get(idx)
+                    if tile is None:
+                        offset = self._index.offsets[idx]
+                        f.seek(offset)
+                        jpeg = f.read(entry["size"])
+                        tile = Image.open(io.BytesIO(jpeg)).convert("RGB")
+
+                        # Tile may be smaller than tile_size at image edges.
+                        if tile.size != (tw, th):
+                            tile = tile.resize((tw, th))
+
+                        self._tile_cache.put(idx, tile)
+
+                    paste_x = tile_x - x0
+                    paste_y = tile_y - y0
+                    crop_x0 = max(0, x0 - tile_x)
+                    crop_y0 = max(0, y0 - tile_y)
+                    crop_x1 = min(tw, x0 + w - tile_x)
+                    crop_y1 = min(th, y0 + h - tile_y)
+
+                    if crop_x1 > crop_x0 and crop_y1 > crop_y0:
+                        cropped = tile.crop((crop_x0, crop_y0, crop_x1, crop_y1))
+                        cropped_rgba = cropped.convert("RGBA")
+                        out.paste(
+                            cropped_rgba,
+                            (paste_x + crop_x0, paste_y + crop_y0),
+                        )
+
+            return out
+        except Exception:
+            self._error = True
+            raise
+
+    def get_thumbnail(self, size: Tuple[int, int]) -> Image.Image:
+        """Get a thumbnail image."""
+        self._check_open()
+        self._check_error()
+
+        thumb = None
+        try:
+            thumb = self._associated_images.get("thumbnail")
+        except KeyError:
+            pass
+
+        if thumb is not None:
+            thumb_copy = thumb.copy()
+            thumb_copy.thumbnail(size, Image.LANCZOS)
+            return thumb_copy
+
+        # Fallback: read from lowest resolution level.
+        level = self.level_count - 1
+        dims = self.level_dimensions[level]
+        return self.read_region((0, 0), level, dims)
+
+    def set_cache(self, cache) -> None:
+        """
+        Attach a shared cache to the slide.
+
+        For kfbslide, this is currently a no-op since we use a private
+        per-slide LRU cache. Accepts the cache argument for API compatibility.
+        """
+        self._check_open()
+        self._check_error()
+        # No-op for now. Could be extended to use a shared cache.
+        pass
+
+
+# Backward compatibility alias
+KfbSlide = OpenSlide
+
+
+def open_slide(filename: str, **kwargs) -> OpenSlide:
+    """
+    Open a KFB file.
+
+    Args:
+        filename: Path to the KFB file.
+
+    Returns:
+        OpenSlide instance.
+    """
+    if kwargs.pop("tile_cache_size", None) is not None:
+        import warnings
+
+        warnings.warn(
+            "tile_cache_size is deprecated and ignored",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    return OpenSlide(filename)
+
+
+__all__ = [
+    "OpenSlide",
+    "KfbSlide",
+    "open_slide",
+]

kfbslide-0.2.0.dist-info/METADATA

@@ -0,0 +1,246 @@
+Metadata-Version: 2.4
+Name: kfbslide
+Version: 0.2.0
+Summary: Pure Python KFB whole-slide image reader with OpenSlide-compatible API
+Project-URL: Homepage, https://github.com/yifanfeng97/kfbslide
+Project-URL: Documentation, https://github.com/yifanfeng97/kfbslide#readme
+Project-URL: Repository, https://github.com/yifanfeng97/kfbslide
+Project-URL: Issues, https://github.com/yifanfeng97/kfbslide/issues
+Author-email: Yifan Feng <evanfeng97@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: digital-pathology,kfb,kfbio,openslide,pathology,whole-slide-image,wsi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: pillow>=9.0.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<h1 align="center">KFBSlide</h1>
+
+<p align="center">
+  <strong>A pure-Python KFB (KFBio) whole-slide image reader with an OpenSlide-compatible API</strong>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> |
+  <a href="README_zh.md">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/kfbslide"><img src="https://img.shields.io/pypi/v/kfbslide?color=blue" alt="PyPI"></a>
+  <a href="https://pypi.org/project/kfbslide"><img src="https://img.shields.io/pypi/pyversions/kfbslide" alt="Python Versions"></a>
+  <a href="https://github.com/yifanfeng97/kfbslide/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
+  <a href="https://pypi.org/project/kfbslide"><img src="https://img.shields.io/pypi/dm/kfbslide?color=orange" alt="Downloads"></a>
+  <a href="https://github.com/yifanfeng97/kfbslide"><img src="https://img.shields.io/github/stars/yifanfeng97/kfbslide?style=social" alt="Stars"></a>
+</p>
+
+<p align="center">
+  <a href="#-features">✨ Features</a> •
+  <a href="#-installation">📦 Installation</a> •
+  <a href="#-quick-start">🚀 Quick Start</a> •
+  <a href="#-api-reference">📖 API</a> •
+  <a href="#-performance">⚡ Performance</a>
+</p>
+
+<p align="center">
+  <img src="docs/banner.png" alt="KFBSlide Banner" width="900">
+</p>
+
+---
+
+## ✨ Features
+
+- 🐍 **Pure Python** — Zero native dependencies, works out of the box on Windows / macOS / Linux
+- 🔄 **OpenSlide-Compatible API** — Drop-in replacement for `openslide-python`, no code changes needed
+- 🔺 **Multi-Level Pyramids** — Automatically parses 40× / 20× / 10× / 5× / 2.5× / 1.25× levels inside KFB
+- 🖼️ **Associated Images** — Supports macro, label, and thumbnail
+- ⚡ **Tile LRU Cache** — 10~20× speedup for repeated reads of the same region
+- 📊 **Full Metadata** — MPP, objective power, tile size, and more
+
+---
+
+## 📦 Installation
+
+### Using uv (recommended)
+
+```bash
+uv pip install kfbslide
+```
+
+### Using pip
+
+```bash
+pip install kfbslide
+```
+
+Only depends on Pillow — installs directly on any platform.
+
+---
+
+## 🚀 Quick Start
+
+### Drop-in replacement for OpenSlide
+
+```python
+import kfbslide as openslide
+
+slide = openslide.OpenSlide("path/to/sample.kfb")
+
+print(f"Levels: {slide.level_count}")
+print(f"Level 0 dimensions: {slide.dimensions}")
+for i in range(slide.level_count):
+    print(f"  Level {i}: {slide.level_dimensions[i]} "
+          f"downsample={slide.level_downsamples[i]}")
+
+# Read a region (location in level-0 coordinates, returns RGBA)
+img = slide.read_region((1000, 2000), 0, (256, 256))
+img.save("region.png")
+
+# Thumbnail
+thumb = slide.get_thumbnail((512, 512))
+thumb.save("thumbnail.png")
+
+# Associated images
+macro = slide.associated_images["macro"]
+macro.save("macro.png")
+
+# Property access
+vendor = slide.properties[openslide.PROPERTY_NAME_VENDOR]
+mpp_x = slide.properties[openslide.PROPERTY_NAME_MPP_X]
+
+slide.close()
+```
+
+### Context manager
+
+```python
+with openslide.OpenSlide("sample.kfb") as slide:
+    img = slide.read_region((0, 0), 0, (256, 256))
+# Automatically closed
+```
+
+---
+
+## 📖 API Reference
+
+### `OpenSlide(filename)`
+
+Open a KFB file.
+
+### Class methods
+
+| Method | Description |
+|--------|-------------|
+| `OpenSlide.detect_format(filename)` | Detect file format, returns `"kfbio"` or `None` |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `level_count` | `int` | Number of pyramid levels |
+| `dimensions` | `(int, int)` | Level 0 dimensions (highest resolution) |
+| `level_dimensions` | `Tuple[(w, h), ...]` | Dimensions of each level |
+| `level_downsamples` | `Tuple[float, ...]` | Downsample factor for each level |
+| `properties` | `Mapping[str, str]` | Metadata properties (read-only mapping) |
+| `associated_images` | `Mapping[str, PIL.Image]` | Associated images: macro, label, thumbnail |
+| `color_profile` | `object \| None` | ICC color profile (currently returns `None`) |
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `read_region(location, level, size)` | Read a region, returns **RGBA** image |
+| `get_best_level_for_downsample(downsample)` | Pick the best pyramid level for a given downsample factor |
+| `get_thumbnail(size)` | Generate a thumbnail |
+| `set_cache(cache)` | API-compatible no-op |
+| `close()` | Close and release resources |
+
+### Property constants
+
+```python
+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"
+)
+```
+
+---
+
+## ⚡ Performance
+
+Benchmarked on `sample.kfb` (71,748 × 56,282, 82,595 tiles):
+
+| Operation | Time | Note |
+|-----------|------|------|
+| First read of 256×256 region | ~2.1 ms | Pillow backend |
+| Cache-hit read | **~0.10 ms** | 22× faster |
+| Scan 20 adjacent regions (first time) | ~33 ms | 1.6 ms/region |
+| Scan 20 adjacent regions (cached) | **~2.2 ms** | 0.11 ms/region, 15× faster |
+
+> Test environment: Python 3.12, Pillow, SSD.
+
+---
+
+## 🏗️ Architecture
+
+<p align="center">
+  <img src="docs/fw_en.png" alt="KFBSlide Architecture" width="800">
+</p>
+
+KFBSlide is implemented entirely in pure Python, reading images by directly parsing the KFB binary format:
+
+- **No C/C++ extensions or system dynamic libraries required**
+- **No dependency on OpenSlide, libtiff, libjpeg, or other external libraries**
+- **Single-file deployable, suitable for servers, containers, and embedded environments**
+
+---
+
+## 📁 Project Structure
+
+```
+kfbslide/
+├── src/kfbslide/
+│   ├── __init__.py          # Package entry point, exports OpenSlide API
+│   ├── _slide.py            # OpenSlide main class
+│   ├── _kfbformat.py        # KFB binary format parser
+│   ├── _cache.py            # LRU tile cache
+│   └── _exceptions.py       # OpenSlideError / compatibility exceptions
+├── tests/                   # Tests (includes sample.kfb symlink)
+├── examples/                # Example scripts
+├── docs/                    # Documentation images
+├── README.md
+├── LICENSE
+└── pyproject.toml
+```
+
+---
+
+## ⚠️ Known Limitations
+
+1. **Read-only**: Writing to KFB files is not currently supported.
+2. **KFB v1.6**: Verified on version 1.6 files. Other versions may require adaptation.
+3. **JPEG decoding**: Uses Pillow for JPEG decoding, consistent across all platforms.
+
+---
+
+## 📄 License
+
+[MIT](LICENSE)
+
+Copyright (c) 2026 Yifan Feng

kfbslide-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+kfbslide/__init__.py,sha256=lt47AacnbK5auoCCG72pb6Lmd4F-CGvxhLTTC0ozwX4,1693
+kfbslide/_cache.py,sha256=x_ejyQ-GsLwL9C3zX3Fxxezuyhy-tDtTCECfUFapLEw,1056
+kfbslide/_exceptions.py,sha256=JQ6ip_9l8UqIpbRB6AxF_oyosWFJnDHv6vMMrD284vQ,462
+kfbslide/_kfbformat.py,sha256=xgvNV_pssxsijX9kHpwaZCmNYiDQGZCRgGAXeCyr0tI,7834
+kfbslide/_slide.py,sha256=2NUvMkF8aVuELtAAOA4clreXnNF47EAMqmaB2IXFFxE,16998
+kfbslide-0.2.0.dist-info/METADATA,sha256=teFhSVvUmD388DR9WdPlTwOtslWb9dG7cKF1x3q47Lk,7965
+kfbslide-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+kfbslide-0.2.0.dist-info/licenses/LICENSE,sha256=giFRf5C_bgy4wEImlaDjXCYbghg5UFRkchQey2z_l_U,1067
+kfbslide-0.2.0.dist-info/RECORD,,

kfbslide-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

kfbslide-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yifan Feng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.