tmapslide 0.2.0__tar.gz

tmapslide-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+# throwaway spike probes
+probe_tmap*.py
+diag*.py
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# large sample renders (analysis artifacts)
+cache/
+
+# local sample-data symlink
+scce_external_center

tmapslide-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yifan Feng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tmapslide-0.2.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.5
+Name: tmapslide
+Version: 0.2.0
+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
+Project-URL: Repository, https://github.com/yifanfeng97/tmapslide
+Project-URL: Issues, https://github.com/yifanfeng97/tmapslide/issues
+Author-email: Yifan Feng <evanfeng97@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: digital-pathology,openslide,pathology,tmap,tmapslide,unic,whole-slide-image,wsi
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.10
+Requires-Dist: pillow>=9.0.0
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# TmapSlide
+
+![tmapslide — TMAP whole-slide images in pure Python](docs/hero.jpg)
+
+Pure Python reader for **UNIC TMAP** whole-slide images (WSI) with an
+[OpenSlide](https://openslide.org/)-compatible API — the companion library to
+[kfbslide](https://github.com/yifanfeng97/kfbslide) (KFB format).
+
+```python
+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
+
+```bash
+pip install tmapslide
+# or from source
+pip install git+https://github.com/yifanfeng97/tmapslide.git
+```
+
+## Supported formats
+
+| Format  | Extension | Vendor             | Backend     |
+| ------- | --------- | ------------------ | ----------- |
+| TMAP 06 | `.TMAP`   | UNIC (United Imaging) | Pure Python |
+| TMAP 07 | `.TMAP`   | UNIC (United Imaging) | Pure Python |
+
+## API
+
+### `tmapslide.OpenSlide(filename)`
+
+| Member                | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `dimensions`          | `(width, height)` at level 0                       |
+| `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.*`) |
+| `associated_images`   | lazy mapping, typically `macro` / `label`          |
+| `read_region(loc, level, size)` | `PIL.Image` (RGBA) of the region         |
+| `get_thumbnail(size)`  | thumbnail from the lowest resolution level        |
+| `get_best_level_for_downsample(ds)` | best level for a downsample factor   |
+| `close()` / context manager | release resources                            |
+
+### `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](https://github.com/MrPeterJin/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.
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Acknowledgments
+
+- [kfbslide](https://github.com/yifanfeng97/kfbslide) — the KFB reader this
+  project is modelled after.
+- [OpenSlide](https://openslide.org/) — the API this library mimics.
+- [ASlide](https://github.com/MrPeterJin/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.

tmapslide-0.2.0/README.md

@@ -0,0 +1,111 @@
+# TmapSlide
+
+![tmapslide — TMAP whole-slide images in pure Python](docs/hero.jpg)
+
+Pure Python reader for **UNIC TMAP** whole-slide images (WSI) with an
+[OpenSlide](https://openslide.org/)-compatible API — the companion library to
+[kfbslide](https://github.com/yifanfeng97/kfbslide) (KFB format).
+
+```python
+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
+
+```bash
+pip install tmapslide
+# or from source
+pip install git+https://github.com/yifanfeng97/tmapslide.git
+```
+
+## Supported formats
+
+| Format  | Extension | Vendor             | Backend     |
+| ------- | --------- | ------------------ | ----------- |
+| TMAP 06 | `.TMAP`   | UNIC (United Imaging) | Pure Python |
+| TMAP 07 | `.TMAP`   | UNIC (United Imaging) | Pure Python |
+
+## API
+
+### `tmapslide.OpenSlide(filename)`
+
+| Member                | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| `dimensions`          | `(width, height)` at level 0                       |
+| `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.*`) |
+| `associated_images`   | lazy mapping, typically `macro` / `label`          |
+| `read_region(loc, level, size)` | `PIL.Image` (RGBA) of the region         |
+| `get_thumbnail(size)`  | thumbnail from the lowest resolution level        |
+| `get_best_level_for_downsample(ds)` | best level for a downsample factor   |
+| `close()` / context manager | release resources                            |
+
+### `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](https://github.com/MrPeterJin/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.
+
+```bash
+pip install -e .[dev]
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Acknowledgments
+
+- [kfbslide](https://github.com/yifanfeng97/kfbslide) — the KFB reader this
+  project is modelled after.
+- [OpenSlide](https://openslide.org/) — the API this library mimics.
+- [ASlide](https://github.com/MrPeterJin/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.

tmapslide-0.2.0/examples/read_region.py

@@ -0,0 +1,30 @@
+"""Read regions and metadata from a TMAP whole-slide image."""
+
+import tmapslide
+
+slide = tmapslide.OpenSlide("sample.TMAP")
+
+print("dimensions:      ", slide.dimensions)
+print("level count:     ", slide.level_count)
+print("level dimensions:", slide.level_dimensions)
+print("level downsamples:", slide.level_downsamples)
+print("vendor:          ", slide.properties["openslide.vendor"])
+print("associated images:", list(slide.associated_images))
+
+# Read a 1024x1024 region at the highest resolution.
+region = slide.read_region((1000, 1000), 0, (1024, 1024))
+region.save("region.png")
+
+# Read from a lower pyramid level (4x downsampled).
+region_l2 = slide.read_region((0, 0), 2, (1024, 1024))
+region_l2.save("region_l2.png")
+
+# Whole-slide thumbnail.
+thumb = slide.get_thumbnail((512, 512))
+thumb.save("thumbnail.png")
+
+# Associated images (macro photo, label).
+for name in slide.associated_images:
+    slide.associated_images[name].save(f"assoc_{name}.png")
+
+slide.close()

tmapslide-0.2.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tmapslide"
+version = "0.2.0"
+description = "Pure Python UNIC TMAP whole-slide image reader with OpenSlide-compatible API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Yifan Feng", email = "evanfeng97@gmail.com" },
+]
+keywords = [
+    "tmap",
+    "tmapslide",
+    "unic",
+    "whole-slide-image",
+    "openslide",
+    "pathology",
+    "wsi",
+    "digital-pathology",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Image Processing",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+    "Pillow>=9.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "ruff",
+    "mypy",
+]
+
+[project.urls]
+Homepage = "https://github.com/yifanfeng97/tmapslide"
+Documentation = "https://github.com/yifanfeng97/tmapslide#readme"
+Repository = "https://github.com/yifanfeng97/tmapslide"
+Issues = "https://github.com/yifanfeng97/tmapslide/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tmapslide"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/tests",
+    "/examples",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]

tmapslide-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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