TmapSlide

Pure Python reader for UNIC TMAP whole-slide images (WSI) with an OpenSlide-compatible API — the companion library to kfbslide (KFB format).

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 (single pixel level, 612x512 overlapping tiles) and TMAP07 (full pyramid, up to 10 levels, 256x256 tiles).
• Fork-safe file handles — safe to use from PyTorch DataLoader workers.
• LRU tile cache for fast repeated reads.

Installation

pip install tmapslide
# or from source
pip install git+https://github.com/yifanfeng97/tmapslide.git

Supported formats

API

tmapslide.OpenSlide(filename)

tmapslide.open_slide(filename)

Alias of OpenSlide(filename).

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. In short: 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 (slightly softer than downsampling level 0 yourself).
• iter_tiles() exposes the stored tile grid directly, useful for tile-based ML pipelines.

Testing

Tests run against real TMAP samples when the scce_external_center data directory (or TAPSLIDE_TEST_DATA) is present next to the repo, and are skipped otherwise.

pip install -e .[dev]
pytest

License

MIT — see LICENSE.

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.