mrxsslide 0.1.0__py3-none-any.whl

mrxsslide/__init__.py

@@ -0,0 +1,60 @@
+"""
+MRXSSlide — Pure Python MRXS (3DHISTECH MIRAX) whole-slide image reader.
+
+A minimal, cross-platform reader for MRXS whole-slide images
+with an OpenSlide-compatible API.
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+License: MIT
+
+Drop-in replacement usage:
+    import mrxsslide as openslide
+    slide = openslide.OpenSlide("sample.mrxs")
+"""
+
+from ._exceptions import (
+    MrxsError,
+    MrxsOpenError,
+    MrxsUnsupportedFormatError,
+    OpenSlideError,
+    OpenSlideUnsupportedFormatError,
+)
+from ._slide import MrxsSlide, OpenSlide, open_slide
+
+__version__ = "0.1.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",
+    # Aliases
+    "MrxsSlide",
+    "open_slide",
+    "MrxsError",
+    "MrxsUnsupportedFormatError",
+    "MrxsOpenError",
+]

mrxsslide/_cache.py

@@ -0,0 +1,40 @@
+"""LRU cache for decoded MRXS camera images.
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+"""
+
+from collections import OrderedDict
+from typing import Hashable, Optional
+
+from PIL import Image
+
+
+class _LRUCache:
+    """OrderedDict-backed LRU cache for decoded images (O(1) ops)."""
+
+    __slots__ = ("capacity", "_cache")
+
+    def __init__(self, capacity: int):
+        self.capacity = max(0, capacity)
+        self._cache: OrderedDict[Hashable, Image.Image] = OrderedDict()
+
+    def get(self, key: Hashable) -> 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: Hashable, 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)

mrxsslide/_codecs.py

@@ -0,0 +1,37 @@
+"""按 IMAGE_FORMAT 分发的图像解码器。
+
+JPEG/PNG/BMP24 走 Pillow；JPEG-XR 走 imagecodecs（可选依赖，experimental：
+当前无 JPEG-XR 样本验证，通道顺序等待真实数据确认）。
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+"""
+
+import io
+
+from PIL import Image
+
+from ._exceptions import OpenSlideUnsupportedFormatError
+
+_PILLOW_FORMATS = {"JPEG", "PNG", "BMP24"}
+_JXR_FORMATS = {"JPEGXR", "JXR", "JPEG-XR"}
+
+
+def decode_image(data: bytes, image_format: str) -> Image.Image:
+    """解码一帧图像数据，返回 RGB 模式的 PIL Image。"""
+    fmt = image_format.upper()
+    if fmt in _PILLOW_FORMATS:
+        img: Image.Image = Image.open(io.BytesIO(data))
+        img.load()
+        if img.mode != "RGB":
+            img = img.convert("RGB")
+        return img
+    if fmt in _JXR_FORMATS:
+        try:
+            import imagecodecs  # type: ignore[import-not-found]
+        except ImportError:
+            raise OpenSlideUnsupportedFormatError(
+                "JPEG-XR compressed slide requires imagecodecs: "
+                "pip install mrxsslide[jxr]"
+            ) from None
+        return Image.fromarray(imagecodecs.jxr_decode(data)).convert("RGB")
+    raise OpenSlideUnsupportedFormatError(f"Unrecognized image format: {image_format}")

mrxsslide/_exceptions.py

@@ -0,0 +1,22 @@
+"""MRXSSlide / 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
+MrxsError = OpenSlideError
+MrxsUnsupportedFormatError = OpenSlideUnsupportedFormatError
+MrxsOpenError = OpenSlideError