tmapslide 0.2.0__py3-none-any.whl

tmapslide/__init__.py

@@ -0,0 +1,56 @@
+"""tmapslide — Pure Python TMAP whole-slide image reader.
+
+A minimal, cross-platform reader for UNIC TMAP whole-slide images
+with an OpenSlide-compatible API.
+
+Author: Yifan Feng <evanfeng97@gmail.com>
+License: MIT
+
+Drop-in usage:
+    import tmapslide
+    slide = tmapslide.OpenSlide("sample.TMAP")
+"""
+
+from ._exceptions import (
+    OpenSlideError,
+    OpenSlideUnsupportedFormatError,
+    TmapError,
+    TmapOpenError,
+    TmapUnsupportedFormatError,
+)
+from ._slide import OpenSlide, TmapSlide, open_slide
+
+__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__ = [
+    "OpenSlide",
+    "OpenSlideError",
+    "OpenSlideUnsupportedFormatError",
+    "TmapError",
+    "TmapOpenError",
+    "TmapUnsupportedFormatError",
+    "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",
+    "TmapSlide",
+    "open_slide",
+]

tmapslide/_cache.py

@@ -0,0 +1,37 @@
+"""LRU cache for decoded TMAP tiles."""
+
+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)

tmapslide/_exceptions.py

@@ -0,0 +1,19 @@
+"""tmapslide / OpenSlide-compatible exceptions."""
+
+
+class OpenSlideError(Exception):
+    """Base exception for OpenSlide errors."""
+
+    pass
+
+
+class OpenSlideUnsupportedFormatError(OpenSlideError):
+    """File format not supported or file is corrupted."""
+
+    pass
+
+
+# Backward/short aliases
+TmapError = OpenSlideError
+TmapUnsupportedFormatError = OpenSlideUnsupportedFormatError
+TmapOpenError = OpenSlideError

tmapslide/_slide.py

@@ -0,0 +1,553 @@
+"""TmapSlide — OpenSlide-compatible API for UNIC TMAP whole-slide images."""
+
+import io
+import os
+import threading
+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 ._tmapformat import TmapAssocImage, TmapFileInfo, TmapLevel, parse_tmap_file
+
+VENDOR = "unic"
+
+
+class _PropertyMap(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"_PropertyMap({self._data!r})"
+
+
+class _AssociatedImageMap(Mapping):
+    """Lazy read-only mapping for associated images."""
+
+    __slots__ = (
+        "_filename",
+        "_assoc_list",
+        "_names",
+        "_cache",
+        "_fh_getter",
+        "_io_lock_getter",
+    )
+
+    def __init__(
+        self,
+        filename: str,
+        assoc_images: List[TmapAssocImage],
+        file_handle_getter=None,
+        io_lock_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
+        self._io_lock_getter = io_lock_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:
+                fh = self._fh_getter() if self._fh_getter else None
+                if fh is not None:
+                    lock = self._io_lock_getter() if self._io_lock_getter else None
+                    if lock is not None:
+                        with lock:
+                            fh.seek(assoc.offset)
+                            data = fh.read(assoc.size)
+                    else:
+                        fh.seek(assoc.offset)
+                        data = fh.read(assoc.size)
+                else:
+                    with open(self._filename, "rb") as f:
+                        f.seek(assoc.offset)
+                        data = f.read(assoc.size)
+                img = Image.open(io.BytesIO(data)).convert("RGBA")
+                if assoc.crop:
+                    img = img.crop(assoc.crop)
+                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 OpenSlide:
+    """UNIC TMAP whole-slide image reader with an OpenSlide-compatible API.
+
+    Interface compatible with openslide-python, implemented in pure Python
+    with Pillow as the only dependency.
+    """
+
+    __slots__ = (
+        "_filename",
+        "_closed",
+        "_tile_cache",
+        "_file_handle",
+        "_pid",
+        "_info",
+        "_properties",
+        "_associated_images",
+        "_tile_lookup",
+        "_background_rgba",
+        "_io_lock",
+    )
+
+    def __init__(self, filename: str):
+        self._filename = filename
+        self._closed = False
+        self._tile_cache = _LRUCache(256)
+        self._file_handle: Optional[io.BufferedReader] = None
+        self._pid = os.getpid()
+        # Serialises seek+read on the shared file handle across threads.
+        self._io_lock = threading.Lock()
+
+        try:
+            self._info: TmapFileInfo = parse_tmap_file(filename)
+        except Exception as e:
+            raise OpenSlideUnsupportedFormatError(f"Cannot parse TMAP file: {e}")
+
+        # (level, x, y) -> tile index, for grid lookup in read_region.
+        self._tile_lookup: Dict[Tuple[int, int, int], int] = {}
+        for level in self._info.levels:
+            for idx, t in enumerate(level.tiles):
+                self._tile_lookup[(level.index, t.x, t.y)] = idx
+
+        try:
+            self._file_handle = open(filename, "rb")
+        except Exception as e:
+            raise OpenSlideError(f"Failed to open file handle: {e}")
+
+        props = {
+            "openslide.vendor": VENDOR,
+            "openslide.quickhash-1": "",
+            "tmap.version": self._info.magic,
+        }
+        props.update(self._info.properties)
+        self._properties = _PropertyMap(props)
+        if "tmap.objective_power" in self._info.properties:
+            self._properties._data["openslide.objective-power"] = self._info.properties[
+                "tmap.objective_power"
+            ]
+
+        bkg = int(self._info.properties.get("tmap.bkg_color", "244"))
+        bkg = max(0, min(255, bkg))
+        self._background_rgba = (bkg, bkg, bkg, 255)
+
+        self._associated_images = _AssociatedImageMap(
+            filename,
+            self._info.assoc_images,
+            file_handle_getter=lambda: self._ensure_open_handle()
+            if not self._closed
+            else None,
+            io_lock_getter=lambda: self._io_lock if not self._closed else None,
+        )
+
+    # ------------------------------------------------------------------
+    # Class methods
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def detect_format(cls, filename: str) -> Optional[str]:
+        """Return "unic" if the file is a recognized TMAP slide, else None."""
+        try:
+            with open(filename, "rb") as f:
+                magic = f.read(6)
+            if magic[:4] == b"TMAP" and magic[4:6].isdigit():
+                return VENDOR
+        except Exception:
+            pass
+        return None
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _check_open(self) -> None:
+        if self._closed:
+            raise OpenSlideError("Slide is closed")
+
+    def _ensure_open_handle(self) -> io.BufferedReader:
+        """Return a file handle valid in the current process (fork-safe)."""
+        if self._closed:
+            raise OpenSlideError("Slide is closed")
+        if self._file_handle is None or os.getpid() != self._pid:
+            if self._file_handle is not None:
+                try:
+                    self._file_handle.close()
+                except Exception:
+                    pass
+            try:
+                self._file_handle = open(self._filename, "rb")
+            except Exception as e:
+                raise OpenSlideError(f"Failed to reopen file handle: {e}")
+            self._pid = os.getpid()
+        return self._file_handle
+
+    def _read_decoded_tile(self, level: TmapLevel, idx: int) -> Image.Image:
+        # Key by (level index, tile index): tile idx values repeat across
+        # pyramid levels and must not share cache slots.
+        key = (level.index, idx)
+        tile = self._tile_cache.get(key)
+        if tile is not None:
+            return tile
+        fh = self._ensure_open_handle()
+        t = level.tiles[idx]
+        with self._io_lock:
+            fh.seek(t.offset)
+            jpeg = fh.read(t.size)
+        tile = Image.open(io.BytesIO(jpeg)).convert("RGB")
+        self._tile_cache.put(key, tile)
+        return tile
+
+    def _get_cached_tile(self, offset: int, length: int) -> Image.Image:
+        """Read + decode a raw tile by file range, with caching."""
+        key = ("raw", offset, length)
+        tile = self._tile_cache.get(key)
+        if tile is not None:
+            return tile
+        fh = self._ensure_open_handle()
+        with self._io_lock:
+            fh.seek(offset)
+            data = fh.read(length)
+        tile = Image.open(io.BytesIO(data)).convert("RGB")
+        self._tile_cache.put(key, tile)
+        return tile
+
+    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()
+        return len(self._info.levels)
+
+    @property
+    def dimensions(self) -> Tuple[int, int]:
+        """Dimensions of the slide at level 0 (highest resolution)."""
+        self._check_open()
+        return self._info.levels[0].width, self._info.levels[0].height
+
+    @property
+    def level_dimensions(self) -> Tuple[Tuple[int, int], ...]:
+        """Dimensions of each pyramid level."""
+        self._check_open()
+        return tuple((l.width, l.height) for l in self._info.levels)
+
+    @property
+    def level_downsamples(self) -> Tuple[float, ...]:
+        """Downsample factor for each level."""
+        self._check_open()
+        return tuple(l.downsample for l in self._info.levels)
+
+    @property
+    def properties(self) -> Mapping[str, str]:
+        """Metadata properties as a read-only mapping."""
+        self._check_open()
+        return self._properties
+
+    @property
+    def associated_images(self) -> Mapping[str, Image.Image]:
+        """Associated images (macro, label, ...) as a lazy mapping."""
+        self._check_open()
+        return self._associated_images
+
+    @property
+    def color_profile(self) -> Optional[object]:
+        """Embedded ICC color profile, or None if not available."""
+        self._check_open()
+        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()
+        best = 0
+        for i, ds in enumerate(l.downsample for l in self._info.levels):
+            if ds <= downsample:
+                best = i
+            else:
+                break
+        return best
+
+    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 in level pixels.
+
+        Returns:
+            PIL.Image.Image (RGBA).
+        """
+        self._check_open()
+        if level < 0 or level >= len(self._info.levels):
+            raise OpenSlideError(f"Invalid level {level}")
+        if self._info.version == 6:
+            region = self._read_region_v6(location, level, size)
+        else:
+            region = self._read_region_tmap07(location, level, size)
+        return region
+
+    def _read_region_tmap07(
+        self,
+        location: Tuple[int, int],
+        level: int,
+        size: Tuple[int, int],
+    ) -> Image.Image:
+        lvl = self._info.levels[level]
+        ds = lvl.downsample
+        x0 = int(location[0] / ds)
+        y0 = int(location[1] / ds)
+        w, h = int(size[0]), int(size[1])
+
+        out = Image.new("RGBA", (w, h), self._background_rgba)
+        if w <= 0 or h <= 0:
+            return out
+
+        tw, th = lvl.tile_width, lvl.tile_height
+        tx_start = x0 // tw
+        ty_start = y0 // th
+        tx_end = (x0 + w - 1) // tw + 1
+        ty_end = (y0 + h - 1) // th + 1
+
+        self._ensure_open_handle()
+
+        for ty in range(ty_start, ty_end):
+            for tx in range(tx_start, tx_end):
+                tile_x = tx * tw
+                tile_y = ty * th
+                idx = self._tile_lookup.get((level, tile_x, tile_y))
+                if idx is None:
+                    continue
+                tile = self._read_decoded_tile(lvl, idx)
+                crop_x0 = max(0, x0 - tile_x)
+                crop_y0 = max(0, y0 - tile_y)
+                crop_x1 = min(tile.width, x0 + w - tile_x)
+                crop_y1 = min(tile.height, 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))
+                    out.paste(cropped, (tile_x - x0 + crop_x0, tile_y - y0 + crop_y0))
+
+        return out
+
+    def _read_region_v6(
+        self,
+        location: Tuple[int, int],
+        level: int,
+        size: Tuple[int, int],
+    ) -> Image.Image:
+        """TMAP06: image blocks laid out on a (img_col x img_row) grid.
+
+        Level 0 renders the layer-0 4x4 tile grid of every overlapping
+        block; level 1 uses the layer-1 whole-block tile; deeper levels use
+        ShrinkTiles when available.
+        """
+        info = self._info
+        blocks = info.__dict__.get("_blocks") or {}
+        shrinks = info.__dict__.get("_shrinks") or []
+        ratio_step = info.__dict__.get("_ratio_step", 4)
+        props = info.properties
+        img_w = int(props.get("tmap.img_width", 2448))
+        img_h = int(props.get("tmap.img_height", 2048))
+        fh = self._ensure_open_handle()
+
+        # clamp level to what we can render
+        if shrinks:
+            max_renderable = 2
+        elif any(layer_no >= 1 for v in blocks.values() for layer_no, _, _, _, _ in v["tiles"]):
+            max_renderable = 1
+        else:
+            max_renderable = 0
+        level = min(level, max_renderable)
+        downsample = ratio_step**level
+        x0 = int(location[0] / downsample)
+        y0 = int(location[1] / downsample)
+        w, h = int(size[0]), int(size[1])
+        out = Image.new("RGBA", (w, h), self._background_rgba)
+        if w <= 0 or h <= 0:
+            return out
+
+        # level-0 footprint of the requested region
+        x0_l0 = int(location[0])
+        y0_l0 = int(location[1])
+        w0 = int(w * downsample)
+        h0 = int(h * downsample)
+        bkg = int(props.get("tmap.bkg_color", 244))
+        rgb = (bkg, bkg, bkg)
+
+        def paste_scaled(tile_img, tile_x0, tile_y0, cover_w, cover_h):
+            """Paste tile covering cover_w x cover_h at (tile_x0, tile_y0)
+            in level-0 coords into the output region."""
+            ov_x0 = max(x0_l0, tile_x0)
+            ov_y0 = max(y0_l0, tile_y0)
+            ov_x1 = min(x0_l0 + w0, tile_x0 + cover_w)
+            ov_y1 = min(y0_l0 + h0, tile_y0 + cover_h)
+            if ov_x1 <= ov_x0 or ov_y1 <= ov_y0:
+                return
+            sx = tile_img.width / cover_w
+            sy = tile_img.height / cover_h
+            src_x = int((ov_x0 - tile_x0) * sx)
+            src_y = int((ov_y0 - tile_y0) * sy)
+            src_w = max(1, int((ov_x1 - ov_x0) * sx))
+            src_h = max(1, int((ov_y1 - ov_y0) * sy))
+            cropped = tile_img.crop(
+                (src_x, src_y, src_x + src_w, src_y + src_h)
+            )
+            dst_x = int((ov_x0 - x0_l0) / downsample)
+            dst_y = int((ov_y0 - y0_l0) / downsample)
+            dst_w = max(1, int((ov_x1 - ov_x0) / downsample))
+            dst_h = max(1, int((ov_y1 - ov_y0) / downsample))
+            if cropped.size != (dst_w, dst_h):
+                cropped = cropped.resize((dst_w, dst_h), Image.BILINEAR)
+            out.paste(cropped, (dst_x, dst_y))
+
+        if level >= 2 and shrinks:
+            # ShrinkTiles: pre-rendered tiles for deep zoom-out levels.
+            for layer_no, n_x, n_y, off, length in shrinks:
+                if layer_no != level:
+                    continue
+                scale = ratio_step**layer_no
+                tile_img = self._get_cached_tile(off, length)
+                cover_w = info.__dict__["_tile_jpeg_size"][0] * scale
+                cover_h = info.__dict__["_tile_jpeg_size"][1] * scale
+                if (
+                    n_x + cover_w < x0_l0
+                    or n_x > x0_l0 + w0
+                    or n_y + cover_h < y0_l0
+                    or n_y > y0_l0 + h0
+                ):
+                    continue
+                paste_scaled(tile_img, n_x, n_y, cover_w, cover_h)
+            return out
+
+        # levels 0 and 1: walk blocks overlapping the region
+        has_layer1 = any(
+            layer_no == 1 for v in blocks.values() for layer_no, _, _, _, _ in v["tiles"]
+        )
+        for (n_col, n_row), blk in blocks.items():
+            n_x, n_y = blk["n_x"], blk["n_y"]
+            if n_x + img_w < x0_l0 or n_x > x0_l0 + w0 or n_y + img_h < y0_l0 or n_y > y0_l0 + h0:
+                continue
+            for layer_no, col, row, off, length in blk["tiles"]:
+                if layer_no != level:
+                    continue
+                tile_img = self._get_cached_tile(off, length)
+                if layer_no > 0:
+                    # one tile covers the whole block
+                    tile_x0, tile_y0 = n_x, n_y
+                    cover_w, cover_h = img_w, img_h
+                else:
+                    tile_x0 = n_x + col * tile_img.width
+                    tile_y0 = n_y + row * tile_img.height
+                    cover_w, cover_h = tile_img.width, tile_img.height
+                paste_scaled(tile_img, tile_x0, tile_y0, cover_w, cover_h)
+        return out
+
+    def get_thumbnail(self, size: Tuple[int, int]) -> Image.Image:
+        """Get a thumbnail image no larger than `size`."""
+        self._check_open()
+        # Prefer the lowest-resolution pyramid level.
+        level = self.level_count - 1
+        dims = self.level_dimensions[level]
+        region = self.read_region((0, 0), level, dims)
+        region.thumbnail(size, Image.LANCZOS)
+        return region
+
+    def iter_tiles(self, level: int = 0):
+        """Iterate over stored tiles at the given level.
+
+        Yields ``(x, y, load)`` where ``(x, y)`` is the tile's position in
+        level-0 pixel coordinates and ``load()`` returns the decoded
+        ``PIL.Image`` (RGB). Useful for tile-based pipelines when the global
+        canvas geometry is not needed.
+
+        Note: TMAP06 stores overlapping tiles (612 px wide tiles on a
+        256 px x-grid); ``x, y`` are the stored grid positions.
+        """
+        self._check_open()
+        if level < 0 or level >= len(self._info.levels):
+            raise OpenSlideError(f"Invalid level {level}")
+        lvl = self._info.levels[level]
+        for idx, t in enumerate(lvl.tiles):
+            def load(idx=idx, lvl=lvl):
+                return self._read_decoded_tile(lvl, idx).copy()
+            yield t.x, t.y, load
+
+    def set_cache(self, cache) -> None:
+        """Accepts a cache argument for API compatibility (no-op)."""
+        self._check_open()
+
+
+# Convenience alias matching the kfbslide naming style.
+TmapSlide = OpenSlide
+
+
+def open_slide(filename: str) -> OpenSlide:
+    """Open a TMAP whole-slide image."""
+    return OpenSlide(filename)
+
+
+__all__ = [
+    "OpenSlide",
+    "TmapSlide",
+    "open_slide",
+]