tmapslide 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tmapslide
-Version: 0.2.1
+Version: 0.2.2
 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
@@ -31,11 +31,7 @@ Description-Content-Type: text/markdown
 
 <div align="center">
 
-<img src="docs/hero.jpg" alt="TmapSlide — UNIC TMAP whole-slide images in pure Python" width="800" style="max-width: 100%;">
-
-<br/>
-
-**TmapSlide**
+# TmapSlide
 
 **Pure Python reader for UNIC TMAP whole-slide images — no SDK, no native deps.**
 
@@ -54,9 +50,6 @@ Description-Content-Type: text/markdown
   <a href="LICENSE">
     <img src="https://img.shields.io/badge/license-MIT-06b6d4?style=for-the-badge&logo=openaccess&logoColor=white&labelColor=1a1a2e" alt="License">
   </a>
-  <a href="https://github.com/yifanfeng97/tmapslide/actions/workflows/test.yml">
-    <img src="https://img.shields.io/github/actions/yifanfeng97/tmapslide/test.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&labelColor=1a1a2e&label=tests" alt="Tests">
-  </a>
   <a href="https://github.com/yifanfeng97/tmapslide/stargazers">
     <img src="https://img.shields.io/github/stars/yifanfeng97/tmapslide?style=for-the-badge&logo=github&labelColor=1a1a2e&color=facc15" alt="GitHub Stars">
   </a>
@@ -64,6 +57,10 @@ Description-Content-Type: text/markdown
 
 [📖 English](#-quick-start) · [中文说明](#-中文说明)
 
+<br/>
+
+<img src="docs/hero.jpg" alt="TmapSlide — UNIC TMAP whole-slide images in pure Python" width="800" style="max-width: 100%;">
+
 </div>
 
 ## ⚡ Quick Start
@@ -99,6 +96,14 @@ macro = slide.associated_images["macro"]
   `associated_images`
 - **Both known TMAP variants** — `TMAP06` (3-level pyramid) and
   `TMAP07` (up to 10 levels)
+- **Multi-file slides** — TMAP06 slides that spill tiles into `.DT1`
+  sidecar files are read transparently
+- **Trusted pixel size** — several TMAP06 *and* TMAP07 headers carry an
+  impossible `pixel_size` (e.g. 6.88e-05 mm at 40x, implying ~2 µm
+  nuclei); tmapslide cross-checks it against the objective power and
+  falls back to 10 µm / magnification, exposing the result via
+  `openslide.mpp-x` / `openslide.mpp-y` (the raw header value stays in
+  `tmap.pixel_size_mm`, the decision in `tmap.mpp_source`)
 - **Fork-safe file handles** — safe with PyTorch `DataLoader` workers
 - **LRU decoded-tile cache** — fast repeated reads
 - **Thread-safe reads** — concurrent `read_region` from worker threads
@@ -129,11 +134,12 @@ TMAP backend (median of 5 runs, same files, same machine):
 | `level_count` | number of pyramid levels |
 | `level_dimensions` | `(w, h)` per level |
 | `level_downsamples` | downsample factor per level |
-| `properties` | read-only metadata mapping (`openslide.vendor=unic`, `tmap.*`) |
+| `properties` | read-only metadata mapping (`openslide.vendor=unic`, `openslide.mpp-x/y`, `tmap.*`) |
 | `associated_images` | lazy mapping, typically `macro` / `label` / `thumbnail` |
 | `read_region(loc, level, size)` | `PIL.Image` (RGBA) of the region |
-| `get_thumbnail(size)` | thumbnail from the lowest resolution level |
+| `get_thumbnail(size)` | stored thumbnail when available, else lowest level |
 | `get_best_level_for_downsample(ds)` | best level for a downsample factor |
+| `iter_tiles(level=0)` | yields `(x, y, load)` per stored tile |
 | `close()` / context manager | release resources |
 
 ### `tmapslide.open_slide(filename)`
@@ -144,7 +150,7 @@ Alias of `OpenSlide(filename)`.
 
 | Format | Extension | Vendor | Backend |
 | --- | --- | --- | --- |
-| TMAP 06 | `.TMAP` | UNIC (United Imaging) | Pure Python |
+| TMAP 06 | `.TMAP` (+ optional `.DT1` sidecars) | UNIC (United Imaging) | Pure Python |
 | TMAP 07 | `.TMAP` | UNIC (United Imaging) | Pure Python |
 
 ## 🧪 Testing
@@ -172,6 +178,14 @@ encryption.
   are JPEG-compressed at that scale.
 - `iter_tiles()` exposes the stored tile grid directly — useful for
   tile-based ML pipelines.
+- **Metadata caveat**: the header `pixel_size` field cannot be trusted.
+  Measured on real slides (cell-nucleus diameters, canvas physical size,
+  cross-checked with ASlide), both the Henan TMAP06 batch (6.88e-05 mm)
+  and the Shanxi TMAP07 batch (1.01e-04 mm) carry corrupt values at 40x;
+  the true resolution is 0.25 µm/px. tmapslide keeps the raw value in
+  `tmap.pixel_size_mm`, exposes the corrected one via
+  `openslide.mpp-x/y`, and records the decision in `tmap.mpp_source`
+  (`header` / `derived`).
 
 ## 📄 License
 

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

@@ -1,10 +1,6 @@
 <div align="center">
 
-<img src="docs/hero.jpg" alt="TmapSlide — UNIC TMAP whole-slide images in pure Python" width="800" style="max-width: 100%;">
-
-<br/>
-
-**TmapSlide**
+# TmapSlide
 
 **Pure Python reader for UNIC TMAP whole-slide images — no SDK, no native deps.**
 
@@ -23,9 +19,6 @@
   <a href="LICENSE">
     <img src="https://img.shields.io/badge/license-MIT-06b6d4?style=for-the-badge&logo=openaccess&logoColor=white&labelColor=1a1a2e" alt="License">
   </a>
-  <a href="https://github.com/yifanfeng97/tmapslide/actions/workflows/test.yml">
-    <img src="https://img.shields.io/github/actions/yifanfeng97/tmapslide/test.yml?branch=main&style=for-the-badge&logo=githubactions&logoColor=white&labelColor=1a1a2e&label=tests" alt="Tests">
-  </a>
   <a href="https://github.com/yifanfeng97/tmapslide/stargazers">
     <img src="https://img.shields.io/github/stars/yifanfeng97/tmapslide?style=for-the-badge&logo=github&labelColor=1a1a2e&color=facc15" alt="GitHub Stars">
   </a>
@@ -33,6 +26,10 @@
 
 [📖 English](#-quick-start) · [中文说明](#-中文说明)
 
+<br/>
+
+<img src="docs/hero.jpg" alt="TmapSlide — UNIC TMAP whole-slide images in pure Python" width="800" style="max-width: 100%;">
+
 </div>
 
 ## ⚡ Quick Start
@@ -68,6 +65,14 @@ macro = slide.associated_images["macro"]
   `associated_images`
 - **Both known TMAP variants** — `TMAP06` (3-level pyramid) and
   `TMAP07` (up to 10 levels)
+- **Multi-file slides** — TMAP06 slides that spill tiles into `.DT1`
+  sidecar files are read transparently
+- **Trusted pixel size** — several TMAP06 *and* TMAP07 headers carry an
+  impossible `pixel_size` (e.g. 6.88e-05 mm at 40x, implying ~2 µm
+  nuclei); tmapslide cross-checks it against the objective power and
+  falls back to 10 µm / magnification, exposing the result via
+  `openslide.mpp-x` / `openslide.mpp-y` (the raw header value stays in
+  `tmap.pixel_size_mm`, the decision in `tmap.mpp_source`)
 - **Fork-safe file handles** — safe with PyTorch `DataLoader` workers
 - **LRU decoded-tile cache** — fast repeated reads
 - **Thread-safe reads** — concurrent `read_region` from worker threads
@@ -98,11 +103,12 @@ TMAP backend (median of 5 runs, same files, same machine):
 | `level_count` | number of pyramid levels |
 | `level_dimensions` | `(w, h)` per level |
 | `level_downsamples` | downsample factor per level |
-| `properties` | read-only metadata mapping (`openslide.vendor=unic`, `tmap.*`) |
+| `properties` | read-only metadata mapping (`openslide.vendor=unic`, `openslide.mpp-x/y`, `tmap.*`) |
 | `associated_images` | lazy mapping, typically `macro` / `label` / `thumbnail` |
 | `read_region(loc, level, size)` | `PIL.Image` (RGBA) of the region |
-| `get_thumbnail(size)` | thumbnail from the lowest resolution level |
+| `get_thumbnail(size)` | stored thumbnail when available, else lowest level |
 | `get_best_level_for_downsample(ds)` | best level for a downsample factor |
+| `iter_tiles(level=0)` | yields `(x, y, load)` per stored tile |
 | `close()` / context manager | release resources |
 
 ### `tmapslide.open_slide(filename)`
@@ -113,7 +119,7 @@ Alias of `OpenSlide(filename)`.
 
 | Format | Extension | Vendor | Backend |
 | --- | --- | --- | --- |
-| TMAP 06 | `.TMAP` | UNIC (United Imaging) | Pure Python |
+| TMAP 06 | `.TMAP` (+ optional `.DT1` sidecars) | UNIC (United Imaging) | Pure Python |
 | TMAP 07 | `.TMAP` | UNIC (United Imaging) | Pure Python |
 
 ## 🧪 Testing
@@ -141,6 +147,14 @@ encryption.
   are JPEG-compressed at that scale.
 - `iter_tiles()` exposes the stored tile grid directly — useful for
   tile-based ML pipelines.
+- **Metadata caveat**: the header `pixel_size` field cannot be trusted.
+  Measured on real slides (cell-nucleus diameters, canvas physical size,
+  cross-checked with ASlide), both the Henan TMAP06 batch (6.88e-05 mm)
+  and the Shanxi TMAP07 batch (1.01e-04 mm) carry corrupt values at 40x;
+  the true resolution is 0.25 µm/px. tmapslide keeps the raw value in
+  `tmap.pixel_size_mm`, exposes the corrected one via
+  `openslide.mpp-x/y`, and records the decision in `tmap.mpp_source`
+  (`header` / `derived`).
 
 ## 📄 License
 

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

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

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

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

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

@@ -117,6 +117,8 @@ class OpenSlide:
         "_tile_lookup",
         "_background_rgba",
         "_io_lock",
+        "_data_paths",
+        "_data_handles",
     )
 
     def __init__(self, filename: str):
@@ -127,6 +129,9 @@ class OpenSlide:
         self._pid = os.getpid()
         # Serialises seek+read on the shared file handle across threads.
         self._io_lock = threading.Lock()
+        # Auxiliary .DT1/.DT2 data files (TMAP06 multi-file slides).
+        self._data_paths: Dict[int, str] = {}
+        self._data_handles: Dict[int, io.BufferedReader] = {}
 
         try:
             self._info: TmapFileInfo = parse_tmap_file(filename)
@@ -151,6 +156,7 @@ class OpenSlide:
         }
         props.update(self._info.properties)
         self._properties = _PropertyMap(props)
+        self._data_paths = dict(self._info.data_files)
         if "tmap.objective_power" in self._info.properties:
             self._properties._data["openslide.objective-power"] = self._info.properties[
                 "tmap.objective_power"
@@ -217,8 +223,12 @@ class OpenSlide:
         tile = self._tile_cache.get(key)
         if tile is not None:
             return tile
-        fh = self._ensure_open_handle()
         t = level.tiles[idx]
+        fh = self._get_file_handle(t.file_id)
+        if fh is None:
+            raise OpenSlideError(
+                f"Data file for file_id {t.file_id} is missing"
+            )
         with self._io_lock:
             fh.seek(t.offset)
             jpeg = fh.read(t.size)
@@ -226,13 +236,42 @@ class OpenSlide:
         self._tile_cache.put(key, tile)
         return tile
 
-    def _get_cached_tile(self, offset: int, length: int) -> Image.Image:
+    def _get_file_handle(self, file_id: int):
+        """Return the handle for a data file: 0 = main TMAP, 1+ = .DT sidecars.
+
+        Sidecar handles open lazily and reopen when the PID changes (same
+        fork-safety rule as the main handle). Returns None if the sidecar
+        file is missing."""
+        self._check_open()
+        if file_id == 0:
+            return self._ensure_open_handle()
+        path = self._data_paths.get(file_id)
+        if path is None:
+            return None
+        handle = self._data_handles.get(file_id)
+        if handle is None or os.getpid() != getattr(handle, "_tmap_pid", -1):
+            try:
+                handle.close()
+            except Exception:
+                pass
+            try:
+                handle = open(path, "rb")
+            except OSError:
+                self._data_paths.pop(file_id, None)
+                return None
+            handle._tmap_pid = os.getpid()
+            self._data_handles[file_id] = handle
+        return handle
+
+    def _get_cached_tile(self, offset: int, length: int, file_id: int = 0) -> Image.Image:
         """Read + decode a raw tile by file range, with caching."""
-        key = ("raw", offset, length)
+        key = ("raw", file_id, offset, length)
         tile = self._tile_cache.get(key)
         if tile is not None:
             return tile
-        fh = self._ensure_open_handle()
+        fh = self._get_file_handle(file_id)
+        if fh is None:
+            raise OpenSlideError(f"Data file for file_id {file_id} is missing")
         with self._io_lock:
             fh.seek(offset)
             data = fh.read(length)
@@ -260,6 +299,12 @@ class OpenSlide:
             except Exception:
                 pass
             self._file_handle = None
+        for handle in self._data_handles.values():
+            try:
+                handle.close()
+            except Exception:
+                pass
+        self._data_handles.clear()
 
     # ------------------------------------------------------------------
     # Properties
@@ -409,7 +454,6 @@ class OpenSlide:
         img_w = int(props.get("tmap.img_width", 2448))
         img_h = int(props.get("tmap.img_height", 2048))
         tile_img_w, tile_img_h = info.__dict__.get("_tile_jpeg_size", (612, 512))
-        fh = self._ensure_open_handle()
 
         # clamp level to what we can render
         if shrinks:
@@ -463,11 +507,10 @@ class OpenSlide:
 
         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:
+            for layer_no, n_x, n_y, off, length, fid 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 (
@@ -477,6 +520,7 @@ class OpenSlide:
                     or n_y > y0_l0 + h0
                 ):
                     continue
+                tile_img = self._get_cached_tile(off, length, fid)
                 paste_scaled(tile_img, n_x, n_y, cover_w, cover_h)
             return out
 
@@ -489,6 +533,9 @@ class OpenSlide:
             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
             jw, jh = info.__dict__.get("_tile_jpeg_size", (tile_img_w, tile_img_h))
+            fid = blk.get("file_id", 0)
+            if self._get_file_handle(fid) is None:
+                continue  # sidecar file missing; degrade to background
             for layer_no, col, row, off, length in blk["tiles"]:
                 if layer_no != level:
                     continue
@@ -508,7 +555,7 @@ class OpenSlide:
                     or tile_y0 >= y0_l0 + h0
                 ):
                     continue
-                tile_img = self._get_cached_tile(off, length)
+                tile_img = self._get_cached_tile(off, length, fid)
                 paste_scaled(tile_img, tile_x0, tile_y0, cover_w, cover_h)
         return out
 

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

@@ -39,6 +39,7 @@ TMAP06 layout
 """
 
 import io
+import os
 import struct
 from dataclasses import dataclass, field
 from typing import Dict, List, Optional, Tuple
@@ -61,7 +62,11 @@ REC07_HEADER_SKIP = 24
 
 @dataclass
 class TmapTile:
-    """One pyramid tile pointing at a JPEG blob in the file."""
+    """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).
+    """
 
     level: int
     offset: int
@@ -70,6 +75,7 @@ class TmapTile:
     y: int
     width: int
     height: int
+    file_id: int = 0
 
 
 @dataclass
@@ -104,6 +110,44 @@ class TmapFileInfo:
     assoc_images: List[TmapAssocImage]
     tile_count: int
     properties: Dict[str, str] = field(default_factory=dict)
+    # file_id -> path of auxiliary data files (0 is the main TMAP itself).
+    data_files: Dict[int, str] = field(default_factory=dict)
+
+
+# Header pixel_size fields are unreliable in the wild (TMAP06 slides ship
+# with values like 6.88e-05 mm at 40x, implying biologically impossible
+# ~2 µm nuclei), so derived values are used whenever the header value is
+# outside the plausible mpp range for whole-slide imaging. 0.1 µm/px is
+# the practical floor (100x); no light-microscopy WSI scanner goes finer.
+MPP_MIN, MPP_MAX = 0.1, 5.0
+
+
+def _mpp_properties(pixel_size_mm: float, scan_scale: float) -> Dict[str, str]:
+    """openslide.mpp-x/y with plausibility checks and a documented fallback.
+
+    Two known-corrupt cases in real files: (1) TMAP06 headers carrying
+    6.88e-05 mm at 40x (biologically impossible ~2 µm nuclei), and
+    (2) TMAP07 headers carrying 1.01e-04 mm at 40x (implies a ~99x
+    objective that no WSI scanner has, and canvas physical sizes of 6-9 mm
+    instead of the standard 21-24 mm). A header value is trusted only if it
+    is inside the plausible mpp range AND within 25% of the 10 µm /
+    objective-power physics; otherwise 10 µm / objective is used. The raw
+    header value is always preserved in ``tmap.pixel_size_mm`` and
+    ``tmap.mpp_source`` records which value won.
+    """
+    mpp = pixel_size_mm * 1000.0
+    source = "header"
+    expected = 10.0 / scan_scale if scan_scale >= 4 else 0.0
+    plausible = MPP_MIN <= mpp <= MPP_MAX
+    consistent = expected <= 0 or abs(mpp - expected) / expected <= 0.25
+    if not (plausible and consistent):
+        mpp = expected if MPP_MIN <= expected <= MPP_MAX else 0.25
+        source = "derived"
+    return {
+        "openslide.mpp-x": f"{mpp:g}",
+        "openslide.mpp-y": f"{mpp:g}",
+        "tmap.mpp_source": source,
+    }
 
 
 def _read_at(f, offset: int, size: int) -> bytes:
@@ -348,6 +392,7 @@ def _parse_tmap07(path: str) -> TmapFileInfo:
                 "tmap.declared_tiles": str(declared_tiles),
                 "tmap.layer_infos": ",".join(prop_layer_info),
                 "tmap.objective_power": str(scan_scale),
+                **_mpp_properties(pixel_size, scan_scale),
             },
         )
 
@@ -409,6 +454,18 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
         if width <= 0 or height <= 0:
             raise ValueError("TMAP06: invalid canvas dimensions")
 
+        # Multi-file slides: file_num counts the main TMAP plus .DT
+        # sidecars; tiles with file_id k live in <stem>.DTk.
+        data_files: Dict[int, str] = {0: path}
+        data_sizes: Dict[int, int] = {0: file_size}
+        stem = os.path.splitext(path)[0]
+        for fid in range(1, max(1, file_num)):
+            for cand in (f"{stem}.DT{fid}", f"{stem}.dt{fid}"):
+                if os.path.exists(cand):
+                    data_files[fid] = cand
+                    data_sizes[fid] = os.path.getsize(cand)
+                    break
+
         # ExtInfo at 0x3C: assoc images as (type, offset, length) triplets.
         # ext type 1 = combined macro+label image, 2 = thumbnail.
         assoc: List[TmapAssocImage] = []
@@ -514,18 +571,20 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
         blocks = {}  # (n_img_col, n_img_row) -> layer info dict
         for k in range(min(image_num, len(li_raw) // 308)):
             base = k * 308
+            fid = li_raw[base]
             n_col, n_row = struct.unpack_from("<HH", li_raw, base + 8)
             if n_col == 0xFFFF and n_row == 0xFFFF:
                 continue
             n_x, n_y = struct.unpack_from("<ii", li_raw, base + 12)
+            limit = data_sizes.get(fid, 0)
             tiles = []
             for t in range(24):
                 tb = base + 20 + t * 12
                 layer_no, col, row = struct.unpack_from("<BBB", li_raw, tb)
                 off, length = struct.unpack_from("<II", li_raw, tb + 4)
-                if off > 0 and length > 0 and off + length <= file_size:
+                if off > 0 and length > 0 and off + length <= limit:
                     tiles.append((layer_no, col, row, off, length))
-            blocks[(n_col, n_row)] = dict(n_x=n_x, n_y=n_y, tiles=tiles, file_id=li_raw[base])
+            blocks[(n_col, n_row)] = dict(n_x=n_x, n_y=n_y, tiles=tiles, file_id=fid)
 
         # ShrinkTileInfo right after the LayerInfo table.
         st_base = li_base + image_num * 308
@@ -533,10 +592,10 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
         st_raw = _read_at(f, st_base, min(shrink_tile_num, 100000) * 20)
         for k in range(min(shrink_tile_num, len(st_raw) // 20)):
             base = k * 20
-            _file_id, layer_no = struct.unpack_from("<BB", st_raw, base)
+            fid, layer_no = struct.unpack_from("<BB", st_raw, base)
             n_x, n_y, off, length = struct.unpack_from("<iiII", st_raw, base + 4)
-            if off > 0 and length > 0 and off + length <= file_size:
-                shrinks.append((layer_no, n_x, n_y, off, length))
+            if off > 0 and length > 0 and off + length <= data_sizes.get(fid, 0):
+                shrinks.append((layer_no, n_x, n_y, off, length, fid))
 
         # Pyramid levels: ratio_step division from the level-0 canvas.
         levels_meta = []
@@ -548,9 +607,14 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
             h = (h + ratio_step - 1) // ratio_step
             scale = scale // ratio_step
 
-        def _tile_img(off: int, length: int) -> Optional[Image.Image]:
-            data = _read_at(f, off, length)
+        def _tile_img(fid: int, off: int, length: int) -> Optional[Image.Image]:
+            p = data_files.get(fid)
+            if p is None:
+                return None
             try:
+                with open(p, "rb") as df:
+                    df.seek(off)
+                    data = df.read(length)
                 return Image.open(io.BytesIO(data))
             except Exception:
                 return None
@@ -560,7 +624,7 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
         for info in blocks.values():
             for layer_no, col, row, off, length in info["tiles"]:
                 if layer_no == 0:
-                    im = _tile_img(off, length)
+                    im = _tile_img(info["file_id"], off, length)
                     if im is not None:
                         tw, th = im.size
                         break
@@ -585,6 +649,7 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
 
         for (n_col, n_row), blk in blocks.items():
             n_x, n_y = blk["n_x"], blk["n_y"]
+            fid = blk["file_id"]
             for layer_no, col, row, off, length in blk["tiles"]:
                 if layer_no == 0:
                     levels[0].tiles.append(
@@ -596,6 +661,7 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
                             y=n_y + row * th,
                             width=tw,
                             height=th,
+                            file_id=fid,
                         )
                     )
                 elif layer_no == 1 and len(levels) > 1:
@@ -608,6 +674,7 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
                             y=n_y // ratio_step,
                             width=tw,
                             height=th,
+                            file_id=fid,
                         )
                     )
 
@@ -631,7 +698,9 @@ def _parse_tmap06(path: str) -> TmapFileInfo:
                 "tmap.blocks": str(len(blocks)),
                 "tmap.shrink_tiles": str(len(shrinks)),
                 "tmap.bkg_color": str(bkg_color),
+                **_mpp_properties(pixel_size, scan_scale),
             },
+            data_files=data_files,
             # extra fields for read_region
         )
         info.__dict__["_blocks"] = blocks

{tmapslide-0.2.1 → tmapslide-0.2.2}/tests/test_synthetic.py

@@ -122,3 +122,83 @@ def test_synthetic_matches_reference_reading(tmp_path):
     s = OpenSlide(str(p))
     assert s.level_count == 2
     s.close()
+
+
+def test_synthetic_tmap06_multifile(tmp_path):
+    """TMAP06 file_num=2: block 1's tiles live in a .DT1 sidecar file and
+    must be routed to it for every read path (region, iter_tiles)."""
+    main = tmp_path / "s.TMAP"
+    side = tmp_path / "s.DT1"
+    meta = make_tmap06(str(main), sidecar_path=str(side))
+    assert side.exists()
+    assert sum(1 for t in meta["tiles"] if t["file_id"] == 1) == 9
+    s = OpenSlide(str(main))
+
+    # layer-0 sidecar tile colour through read_region
+    want = (
+        (120 + 1 * 20 + 2 * 25) % 256,
+        (60 + 1 * 30 + 0 * 45) % 256,
+        (150 + 2 * 8) % 256,
+    )
+    assert close(center(s.read_region((2 * 612 + 10, 1024 + 10), 0, (300, 200))), want)
+
+    # layer-1 whole-block sidecar tile renders at 1/4 scale
+    assert close(center(s.read_region((624, 1036), 1, (300, 250))), (37, 200, 90))
+
+    # iter_tiles load() must decode all 16 layer-0 tiles (8 of them sidecar)
+    loads = [load for _, _, load in s.iter_tiles()]
+    assert all(load().size == (612, 512) for load in loads)
+
+    # level-1 iter_tiles too (one whole-block tile per block)
+    for _, _, load in s.iter_tiles(level=1):
+        assert load().size == (612, 512)
+
+    # missing sidecar file degrades to background instead of crashing
+    s.close()
+    side.unlink()
+    s2 = OpenSlide(str(main))
+    edge = s2.read_region((2 * 612 + 10, 1024 + 10), 0, (8, 8)).getpixel((4, 4))
+    assert edge[3] == 255  # opaque background colour, not an exception
+    s2.close()
+
+
+def test_tmap06_mpp_fallback(tmp_path):
+    """Corrupt vendor pixel_size (real TMAP06 bug: 6.88e-05 mm at 40x, which
+    implies impossible 2 µm nuclei) must not leak into openslide.mpp-x/y —
+    fall back to 10 µm / objective power; the raw value stays in
+    tmap.pixel_size_mm."""
+    make_tmap06(str(tmp_path / "s.TMAP"), pixel_size_mm=6.88e-05)
+    s = OpenSlide(str(tmp_path / "s.TMAP"))
+    assert float(s.properties["tmap.pixel_size_mm"]) == pytest.approx(6.88e-05)
+    assert float(s.properties["openslide.mpp-x"]) == pytest.approx(0.25)
+    assert float(s.properties["openslide.mpp-y"]) == pytest.approx(0.25)
+    assert s.properties["tmap.mpp_source"] == "derived"
+    s.close()
+
+
+def test_tmap07_mpp_inconsistent_header(tmp_path):
+    """Real Shanxi TMAP07 headers carry 1.01e-04 mm at 40x — biologically
+    impossible (~99x objective, 6-9 mm canvas). The header value must lose
+    to the 10 µm / 40x = 0.25 physics even though it sits inside the
+    absolute plausibility range."""
+    make_tmap07(str(tmp_path / "a.TMAP"), pixel_size_mm=1.0117647e-4)
+    s = OpenSlide(str(tmp_path / "a.TMAP"))
+    assert float(s.properties["tmap.pixel_size_mm"]) == pytest.approx(1.0117647e-4)
+    assert float(s.properties["openslide.mpp-x"]) == pytest.approx(0.25)
+    assert s.properties["tmap.mpp_source"] == "derived"
+    s.close()
+
+
+def test_mpp_from_header(tmp_path):
+    """A plausible header pixel size is used as-is."""
+    make_tmap07(str(tmp_path / "a.TMAP"))
+    s = OpenSlide(str(tmp_path / "a.TMAP"))
+    assert float(s.properties["openslide.mpp-x"]) == pytest.approx(0.25)
+    assert s.properties["tmap.mpp_source"] == "header"
+    s.close()
+
+    make_tmap06(str(tmp_path / "b.TMAP"), pixel_size_mm=2.5e-4)
+    s = OpenSlide(str(tmp_path / "b.TMAP"))
+    assert float(s.properties["openslide.mpp-x"]) == pytest.approx(0.25)
+    assert s.properties["tmap.mpp_source"] == "header"
+    s.close()

{tmapslide-0.2.1 → tmapslide-0.2.2}/tests/tmap_fixtures.py

@@ -19,7 +19,7 @@ def _jpeg(color, size):
     return buf.getvalue()
 
 
-def make_tmap07(path, background=250):
+def make_tmap07(path, background=250, pixel_size_mm=2.5e-4):
     """Tiny TMAP07: level 0 = 2x2 grid of 256 px tiles, level 1 = one tile."""
     W = H = 512
     cols = rows = 2
@@ -53,7 +53,7 @@ def make_tmap07(path, background=250):
     struct.pack_into("<BBB", head, 8, 0, 80, 1)  # fmt, quality, focus
     head[11] = 40  # scan scale
     head[12] = background
-    struct.pack_into("<f", head, 0x10, 2.5e-4)  # pixel size (mm)
+    struct.pack_into("<f", head, 0x10, pixel_size_mm)  # pixel size (mm)
     struct.pack_into("<I", head, 0x14, 2)  # image num
     struct.pack_into("<I", head, 0x18, 2)  # layer num
     struct.pack_into("<I", head, 0x1C, 5)  # tile num
@@ -83,14 +83,20 @@ def make_tmap07(path, background=250):
     return dict(dims=(W, H), background=background)
 
 
-def make_tmap06(path, background=250):
+def make_tmap06(path, background=250, pixel_size_mm=2.5e-4, sidecar_path=None):
     """Tiny TMAP06: a 1x2 grid of blocks (each 2448x1024 = 4x2 tiles of
     612x512), one layer-1 whole-block tile per block, 3 pyramid levels
-    (ratio step 4)."""
+    (ratio step 4).
+
+    With ``sidecar_path`` set, the header declares file_num=2 and block 1's
+    JPEG blobs are written to a separate .DT1-style file (512-byte header
+    then packed tiles); its LayerInfo offsets address that sidecar.
+    """
     TW, TH = 612, 512
     IMG_W, IMG_H = 4 * TW, 2 * TH  # 2448 x 1024 per block
     N_BLOCKS = 2
     CANVAS_W, CANVAS_H = IMG_W, N_BLOCKS * IMG_H  # 2448 x 2048
+    use_sidecar = sidecar_path is not None
 
     li_base = 192
     li_size = 308
@@ -98,8 +104,8 @@ def make_tmap06(path, background=250):
 
     out = bytearray(60)
     out[0:6] = b"TMAP06"
-    out[6:16] = bytes([1, 0, 0, 3, 24, 0, 4, 10, 0, background])
-    struct.pack_into("<f", out, 0x10, 2.5e-4)  # pixel size (mm)
+    out[6:16] = bytes([1, 0, 2 if use_sidecar else 0, 3, 24, 0, 4, 10, 0, background])
+    struct.pack_into("<f", out, 0x10, pixel_size_mm)  # pixel size (mm)
     struct.pack_into("<I", out, 0x14, N_BLOCKS)  # image num (LayerInfo count)
     struct.pack_into(
         "<HHHHHHHH", out, 0x18,
@@ -116,10 +122,14 @@ def make_tmap06(path, background=250):
 
     layerinfos = bytearray()
     tiles_blob = bytearray()
+    side_blob = bytearray()
     tile_colors = []
     for b in range(N_BLOCKS):
+        fid = 1 if (use_sidecar and b == 1) else 0
+        target = side_blob if fid else tiles_blob
+        base_off = 512 if fid else data_off  # sidecar tiles follow a 512 B header
         li = bytearray(li_size)
-        li[0] = 0  # file id
+        li[0] = fid  # file id
         li[1] = 0  # layer
         struct.pack_into("<HH", li, 8, 0, b)  # n_img_col, n_img_row
         n_x, n_y = 0, b * IMG_H
@@ -136,11 +146,11 @@ def make_tmap06(path, background=250):
         l1_color = (b * 37 % 256, 200, 90)
         entries.append((1, 0, 0, _jpeg(l1_color, (TW, TH)), l1_color))
         for t, (layer, col, row, j, color) in enumerate(entries[:24]):
-            off = data_off + len(tiles_blob)
+            off = base_off + len(target)
             li[20 + t * 12 : 20 + t * 12 + 12] = struct.pack(
                 "<BBBB II", layer, col, row, 0, off, len(j)
             )
-            tiles_blob += j
+            target += j
             tile_colors.append(
                 dict(
                     layer=layer,
@@ -149,6 +159,7 @@ def make_tmap06(path, background=250):
                     w=TW,
                     h=TH,
                     color=color,
+                    file_id=fid,
                 )
             )
         layerinfos += li
@@ -159,6 +170,12 @@ def make_tmap06(path, background=250):
 
     with open(path, "wb") as f:
         f.write(bytes(out))
+    if use_sidecar:
+        side = bytearray(512)
+        side[0:4] = b"DT01"
+        side += side_blob
+        with open(sidecar_path, "wb") as f:
+            f.write(bytes(side))
     return dict(
         dims=(CANVAS_W, CANVAS_H),
         background=background,