tmapslide 0.2.2__tar.gz → 0.2.3__tar.gz

{tmapslide-0.2.2 → tmapslide-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tmapslide
-Version: 0.2.2
+Version: 0.2.3
 Summary: Pure Python UNIC TMAP whole-slide image reader with OpenSlide-compatible API
 Project-URL: Homepage, https://github.com/yifanfeng97/tmapslide
 Project-URL: Documentation, https://github.com/yifanfeng97/tmapslide#readme
@@ -115,14 +115,17 @@ TMAP backend (median of 5 runs, same files, same machine):
 
 | Scenario | TMAP07 | TMAP06 |
 |---|---|---|
-| Open slide | **281 ms** vs 43 ms ⚠️ | **101 ms** vs 224 ms (2.2×) |
-| Cold 1024² region @L0 | **4.1 ms** vs 15.7 ms (3.8×) | **2.6 ms** vs 14.8 ms (5.6×) |
-| Random 512² region @L0 | **1.1 ms** vs 5.7 ms (5.3×) | **0.9 ms** vs 6.3 ms (6.7×) |
-| Warm 512² region ×50 | **42 ms** vs 217 ms (5.1×) | **54 ms** vs 408 ms (7.6×) |
-
-> ASlide's TMAP backend re-decodes every tile on every call; tmapslide adds
-> an LRU decoded-tile cache and per-tile culling, so warm reads and random
-> access are several times faster.
+| Open slide | 68 ms vs 46 ms | **80 ms vs 220 ms (2.8×)** |
+| Cold 1024² region @L0 | **3.6 ms vs 15.7 ms (4.4×)** | **2.8 ms vs 12.3 ms (4.4×)** |
+| Random 512² region @L0 | **1.0 ms vs 5.2 ms (5.0×)** | **1.0 ms vs 5.6 ms (5.6×)** |
+| Warm 512² region ×50 | **45 ms vs 242 ms (5.4×)** | **55 ms vs 373 ms (6.8×)** |
+
+> The two libraries pay for indexing in opposite places. tmapslide builds a
+> validated tile index (grid + lazy tile tables) once at open; ASlide defers
+> that work into every read, re-decoding tiles per call. That is why TMAP07
+> open runs ~20 ms slower while every read is 4–7× faster — for any workload
+> that reads more than a handful of regions, tmapslide comes out far ahead.
+> Slide open is a once-per-process cost.
 
 ## 📖 API
 

{tmapslide-0.2.2 → tmapslide-0.2.3}/README.md

@@ -84,14 +84,17 @@ TMAP backend (median of 5 runs, same files, same machine):
 
 | Scenario | TMAP07 | TMAP06 |
 |---|---|---|
-| Open slide | **281 ms** vs 43 ms ⚠️ | **101 ms** vs 224 ms (2.2×) |
-| Cold 1024² region @L0 | **4.1 ms** vs 15.7 ms (3.8×) | **2.6 ms** vs 14.8 ms (5.6×) |
-| Random 512² region @L0 | **1.1 ms** vs 5.7 ms (5.3×) | **0.9 ms** vs 6.3 ms (6.7×) |
-| Warm 512² region ×50 | **42 ms** vs 217 ms (5.1×) | **54 ms** vs 408 ms (7.6×) |
-
-> ASlide's TMAP backend re-decodes every tile on every call; tmapslide adds
-> an LRU decoded-tile cache and per-tile culling, so warm reads and random
-> access are several times faster.
+| Open slide | 68 ms vs 46 ms | **80 ms vs 220 ms (2.8×)** |
+| Cold 1024² region @L0 | **3.6 ms vs 15.7 ms (4.4×)** | **2.8 ms vs 12.3 ms (4.4×)** |
+| Random 512² region @L0 | **1.0 ms vs 5.2 ms (5.0×)** | **1.0 ms vs 5.6 ms (5.6×)** |
+| Warm 512² region ×50 | **45 ms vs 242 ms (5.4×)** | **55 ms vs 373 ms (6.8×)** |
+
+> The two libraries pay for indexing in opposite places. tmapslide builds a
+> validated tile index (grid + lazy tile tables) once at open; ASlide defers
+> that work into every read, re-decoding tiles per call. That is why TMAP07
+> open runs ~20 ms slower while every read is 4–7× faster — for any workload
+> that reads more than a handful of regions, tmapslide comes out far ahead.
+> Slide open is a once-per-process cost.
 
 ## 📖 API
 

{tmapslide-0.2.2 → tmapslide-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "tmapslide"
-version = "0.2.2"
+version = "0.2.3"
 description = "Pure Python UNIC TMAP whole-slide image reader with OpenSlide-compatible API"
 readme = "README.md"
 license = "MIT"

{tmapslide-0.2.2 → tmapslide-0.2.3}/src/tmapslide/__init__.py

@@ -20,7 +20,7 @@ from ._exceptions import (
 )
 from ._slide import OpenSlide, TmapSlide, open_slide
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 
 # Standard OpenSlide property name constants
 PROPERTY_NAME_VENDOR = "openslide.vendor"

{tmapslide-0.2.2 → tmapslide-0.2.3}/src/tmapslide/_slide.py

@@ -114,7 +114,6 @@ class OpenSlide:
         "_info",
         "_properties",
         "_associated_images",
-        "_tile_lookup",
         "_background_rgba",
         "_io_lock",
         "_data_paths",
@@ -138,12 +137,6 @@ class OpenSlide:
         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:
@@ -416,13 +409,22 @@ class OpenSlide:
 
         self._ensure_open_handle()
 
+        grid = lvl.grid
+        gcols = lvl.grid_cols
+        glen = len(grid) if grid is not None else 0
+
         for ty in range(ty_start, ty_end):
+            tile_y = ty * th
             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:
+                if grid is None or tx < 0:
                     continue
+                cell = ty * gcols + tx
+                if cell >= glen:
+                    continue
+                idx = grid[cell]
+                if idx < 0:
+                    continue
+                tile_x = tx * tw
                 tile = self._read_decoded_tile(lvl, idx)
                 crop_x0 = max(0, x0 - tile_x)
                 crop_y0 = max(0, y0 - tile_y)

{tmapslide-0.2.2 → tmapslide-0.2.3}/src/tmapslide/_tmapformat.py

@@ -41,6 +41,7 @@ TMAP06 layout
 import io
 import os
 import struct
+from collections.abc import Sequence
 from dataclasses import dataclass, field
 from typing import Dict, List, Optional, Tuple
 
@@ -60,12 +61,13 @@ REC07_SIZE = 40
 REC07_HEADER_SKIP = 24
 
 
-@dataclass
+@dataclass(slots=True)
 class TmapTile:
     """One pyramid tile pointing at a JPEG blob in a data file.
 
     ``file_id`` selects the file: 0 is the main TMAP, 1+ are .DT sidecar
-    files (TMAP06 multi-file slides).
+    files (TMAP06 multi-file slides). Slotted for fast bulk construction:
+    TMAP07 slides materialize 100k+ tiles at open time.
     """
 
     level: int
@@ -78,6 +80,46 @@ class TmapTile:
     file_id: int = 0
 
 
+class _TileList(Sequence):
+    """Lazily materializes TmapTile objects from a level's raw record table.
+
+    A TMAP07 level-0 table holds 100k+ records; constructing every tile
+    up front dominated slide-open time. The record table is kept as raw
+    bytes and a tile is unpacked on first access. Public behavior is
+    identical to a list of TmapTile.
+    """
+
+    __slots__ = ("_level", "_raw", "_rec_idx", "_tw", "_th")
+
+    def __init__(self, level: int, raw: bytes, rec_idx: List[int], tw: int, th: int):
+        self._level = level
+        self._raw = raw
+        self._rec_idx = rec_idx
+        self._tw = tw
+        self._th = th
+
+    def __len__(self) -> int:
+        return len(self._rec_idx)
+
+    def __getitem__(self, i):
+        if isinstance(i, slice):
+            return [self[j] for j in range(*i.indices(len(self)))]
+        base = self._rec_idx[i] * TMAP07_REC_SIZE
+        _layer, _focus, x, y, _w, _h, off, size = _REC07.unpack_from(self._raw, base)
+        return TmapTile(self._level, off, size, x, y, self._tw, self._th)
+
+    def __iter__(self):
+        unpack = _REC07.unpack_from
+        raw = self._raw
+        level, tw, th = self._level, self._tw, self._th
+        for i in self._rec_idx:
+            _layer, _focus, x, y, _w, _h, off, size = unpack(raw, i * TMAP07_REC_SIZE)
+            yield TmapTile(level, off, size, x, y, tw, th)
+
+    def __repr__(self) -> str:
+        return f"_TileList(len={len(self._rec_idx)})"
+
+
 @dataclass
 class TmapLevel:
     """A pyramid level."""
@@ -88,7 +130,12 @@ class TmapLevel:
     height: int
     tile_width: int
     tile_height: int
-    tiles: List[TmapTile] = field(default_factory=list)
+    tiles: Sequence[TmapTile] = field(default_factory=list)
+    # TMAP07: map from grid cell (row * grid_cols + col) to the index of
+    # that tile in `tiles`, or -1 for blank cells. Replaces a hash lookup
+    # at read time; None for TMAP06 levels (block-based geometry).
+    grid: Optional[List[int]] = None
+    grid_cols: int = 0
 
 
 @dataclass
@@ -189,19 +236,6 @@ _ASSOC07_NAMES = {
 }
 
 
-def _find_tile_data_start07(f, file_size: int) -> int:
-    """First JPEG SOI at/after the record region -> start of tile data."""
-    pos = 0
-    step = 1024 * 1024
-    while pos < file_size:
-        chunk = _read_at(f, pos, min(step, file_size - pos))
-        p = chunk.find(b"\xff\xd8\xff")
-        if p != -1:
-            return pos + p
-        pos += len(chunk)
-    raise ValueError("TMAP07: no tile data found")
-
-
 def _parse_assoc07(f, file_size: int, tile_data_end: int) -> List[TmapAssocImage]:
     """Collect TMAP07 associated images.
 
@@ -284,32 +318,7 @@ def _parse_layer_table07(f, base: int = TMAP07_LAYERINFO_BASE) -> List[dict]:
     return entries
 
 
-def _parse_records07(f, entry: dict, file_size: int) -> List[Optional[tuple]]:
-    """Read one level's tile table.
-
-    Record (40 B), indexed by (row * tile_col + col):
-        layer_no u32, focus_no u32, x u32, y u32, w u32, h u32,
-        data_offset u64, data_length u32, pad u32
-    Blank cells store offset == 0.
-    """
-    cols, rows = entry["tile_col"], entry["tile_row"]
-    total = cols * rows
-    raw = _read_at(f, entry["index_offset"], total * TMAP07_REC_SIZE + 64)
-    recs: List[Optional[tuple]] = []
-    for i in range(total):
-        base = i * TMAP07_REC_SIZE
-        if base + TMAP07_REC_SIZE > len(raw):
-            break
-        layer_no, focus_no, x, y, w, h, off, size = struct.unpack_from(
-            "<IIIIIIQI", raw, base
-        )
-        if off == 0 and size == 0:
-            recs.append(None)
-            continue
-        if size == 0 or off + size > file_size:
-            break
-        recs.append((off, size, layer_no, focus_no, x, y, w, h))
-    return recs
+_REC07 = struct.Struct("<IIIIIIQI")  # layer_no, focus_no, x, y, w, h, off u64, size
 
 
 def _parse_tmap07(path: str) -> TmapFileInfo:
@@ -327,8 +336,6 @@ def _parse_tmap07(path: str) -> TmapFileInfo:
         declared_tiles = struct.unpack_from("<I", head, 0x1C)[0]
         magic = head[:6].decode("ascii", errors="replace")
 
-        data_start = _find_tile_data_start07(f, file_size)
-
         # TMAP07 LayerInfo table at 560.
         entries = _parse_layer_table07(f)
         if not entries:
@@ -336,32 +343,55 @@ def _parse_tmap07(path: str) -> TmapFileInfo:
 
         levels: List[TmapLevel] = []
         prop_layer_info = []
+        tile_data_end = 0
         for order, e in enumerate(entries):
-            real = _parse_records07(f, e, file_size)
-            real = [r for r in real if r is not None]
-            if not real:
+            # Single pass over the record table: validate records, fix the
+            # level tile size from the first stored record, build the
+            # grid-position index, and keep the table as raw bytes — tile
+            # objects are materialized lazily by _TileList (100k+ tiles on
+            # level 0 would otherwise dominate slide-open time).
+            cols = e["tile_col"]
+            total = cols * e["tile_row"]
+            raw = _read_at(f, e["index_offset"], total * TMAP07_REC_SIZE + 64)
+            n = min(total, len(raw) // TMAP07_REC_SIZE)
+            unpack = _REC07.unpack_from
+            grid = [-1] * total
+            rec_idx: List[int] = []
+            ri_append = rec_idx.append
+            tw = th = None
+            level_end = 0
+            pos = 0
+            for i in range(n):
+                _layer, _focus, x, y, w, h, off, size = unpack(raw, i * TMAP07_REC_SIZE)
+                if off == 0 and size == 0:
+                    continue
+                if size == 0 or off + size > file_size:
+                    break
+                if tw is None:
+                    tw = w if 16 <= w <= 4096 else 256
+                    th = h if 16 <= h <= 4096 else 256
+                grid[i] = pos
+                pos += 1
+                ri_append(i)
+                if off + size > level_end:
+                    level_end = off + size
+            if not rec_idx:
                 continue
-            sample = real[0]
-            tw = sample[6] if 16 <= sample[6] <= 4096 else 256
-            th = sample[7] if 16 <= sample[7] <= 4096 else 256
-            lvl = TmapLevel(
-                index=order,
-                downsample=float(2**order),
-                width=e["width"],
-                height=e["height"],
-                tile_width=tw,
-                tile_height=th,
-            )
-            for r in real:
-                off, size = r[0], r[1]
-                x, y = r[4], r[5]
-                lvl.tiles.append(
-                    TmapTile(
-                        level=order, offset=off, size=size, x=x, y=y,
-                        width=tw, height=th,
-                    )
+            if level_end > tile_data_end:
+                tile_data_end = level_end
+            levels.append(
+                TmapLevel(
+                    index=order,
+                    downsample=float(2**order),
+                    width=e["width"],
+                    height=e["height"],
+                    tile_width=tw,
+                    tile_height=th,
+                    tiles=_TileList(order, raw, rec_idx, tw, th),
+                    grid=grid,
+                    grid_cols=cols,
                 )
-            levels.append(lvl)
+            )
             prop_layer_info.append(
                 f"{e['width']}x{e['height']}:{e['tile_col']}x{e['tile_row']}"
             )
@@ -369,7 +399,6 @@ def _parse_tmap07(path: str) -> TmapFileInfo:
         if not levels:
             raise ValueError("TMAP07: no tile records parsed")
 
-        tile_data_end = max(t.offset + t.size for l in levels for t in l.tiles)
         assoc = _parse_assoc07(f, file_size, tile_data_end)
 
         return TmapFileInfo(