TmapSlide

Pure Python reader for UNIC TMAP whole-slide images — no SDK, no native deps.

以纯 Python 读取联影 TMAP 全切片图像，开箱即用

📖 English · 中文说明

⚡ Quick Start

1. Install:

pip install tmapslide

2. Read a slide:

import tmapslide

slide = tmapslide.OpenSlide("sample.TMAP")

print(slide.dimensions)          # (71424, 72704)
print(slide.level_count)         # 10
print(slide.level_downsamples)   # (1.0, 2.0, 4.0, ...)

region = slide.read_region((512, 512), 0, (1024, 1024))  # RGBA PIL image
thumb = slide.get_thumbnail((512, 512))
macro = slide.associated_images["macro"]

✨ Features

• Pure Python — no vendor SDK, no native dependencies; only Pillow
• OpenSlide-compatible API — drop-in for code written against openslide / kfbslide: read_region, get_thumbnail, dimensions, level_count, level_dimensions, level_downsamples, properties, 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

🏎️ Performance

Benchmark vs ASlide's pure-Python TMAP backend (median of 5 runs, same files, same machine):

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.OpenSlide(filename)

tmapslide.open_slide(filename)

Alias of OpenSlide(filename).

📦 Supported Formats

🧪 Testing

Tests run against real TMAP samples when the scce_external_center data directory (or TAPSLIDE_TEST_DATA) is present next to the repo; synthetic fixtures keep the core parser covered everywhere else.

pip install -e .[dev]
pytest

📄 Format Notes (reverse-engineered)

TMAP is an undocumented proprietary format. This reader is built from binary analysis of real scanner output, cross-validated against ASlide. Both variants store plain JPEG tiles with a small binary header and index tables; there is no encryption.

• TMAP06 stores 3 pyramid levels (40x / 10x / 2.5x); TMAP07 stores up to 10 levels (40x down to 0.078x, halving each level).
• TMAP06 level-2 previews come from pre-rendered ShrinkTile entries and 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

MIT

🙏 Acknowledgments

• kfbslide — the KFB reader this project is modelled after
• OpenSlide — the API this library mimics
• ASlide — its independent reverse-engineering of the TMAP06 layer/block structures (from decompiled vendor SDK) was used to cross-validate this implementation. tmapslide is an independent MIT-licensed implementation and ships no ASlide code