tmapslide 0.2.0__py3-none-any.whl

tmapslide/_tmapformat.py

@@ -0,0 +1,654 @@
+"""TMAP (UNIC whole-slide) file format parser — pure Python.
+
+Reverse-engineered from real scanner output (TMAP06 / TMAP07 variants).
+All multi-byte fields are little-endian.
+
+TMAP07 layout (fully mapped)
+-----------------------------
+- 0x000: magic "TMAP07\\0\\0"; 0x018: u32 level count; 0x01C: u32 tile count
+- associated image descriptors (32B each) in the header region:
+    (offset u64, size u64, width u32, height u32, bpp u32, id u32)
+  payloads live after the tile data near end-of-file; width/height may be
+  zero in the descriptor (real size taken from the JPEG).
+- level descriptor table (32B per level) right before the first record block:
+    (objective f32, width u32, height u32, cols u32, rows u32,
+     index_offset u32, cumulative_tiles u32, level_no u32)
+- per level a record block at index_offset + 24; 40B per tile:
+    (data_offset u64, data_size u64, level_no u32, f1 u32, f2 u32,
+     f3 u32, tile_w u32, tile_h u32)
+  blank (tissue-free) grid cells are stored as zero records; tiles form a
+  complete row-major grid, so coordinates derive from (i % cols, i // cols).
+- tile JPEG data follows the record blocks, in record order.
+
+TMAP06 layout
+-------------
+- 0x000: magic "TMAP06\\0\\0", 512-byte header
+  - 0x10/0x12: u16 scan area (micrometers, not pixels)
+  - 0x18: u16 objective power
+  - 0x40: u32 tail length; 0x44: u32 tail start
+- 0x0C8: fixed 308-byte slot array (exactly up to the first JPEG):
+  empty slots start with 0xFFFFFFFF; used slots are
+    [block_no u32][meta m1 u32][m2 u32 = y tile-row base][m3 u32][17 records]
+  record (12B) = (data_offset u32, data_size u32, x | y<<16 u32) where
+  x is a pixel column (256-px stride, tiles are 612 px wide) and y is a
+  tile row (512-px pitch, 4 rows per slot). Slots with m2/y-base n cover
+  global rows n..n+3. Records within a slot chain contiguously.
+- tile JPEG data (612x512) follows the slot array.
+- file tail: label then macro, each [descriptor (pad, w, h, stride, bpp)
+  + JPEG], sizes in header 0x88 / 0x8C.
+"""
+
+import io
+import struct
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Tuple
+
+from PIL import Image
+
+TMAP_MAGIC = b"TMAP"
+
+SLOT06_BASE = 0xC8
+SLOT06_STRIDE = 308
+SLOT06_RECORDS = 17
+REC06_SIZE = 12
+
+TMAP06_TILE_STRIDE_X = 256
+TMAP06_TILE_PITCH_Y = 512
+
+REC07_SIZE = 40
+REC07_HEADER_SKIP = 24
+
+
+@dataclass
+class TmapTile:
+    """One pyramid tile pointing at a JPEG blob in the file."""
+
+    level: int
+    offset: int
+    size: int
+    x: int
+    y: int
+    width: int
+    height: int
+
+
+@dataclass
+class TmapLevel:
+    """A pyramid level."""
+
+    index: int
+    downsample: float
+    width: int
+    height: int
+    tile_width: int
+    tile_height: int
+    tiles: List[TmapTile] = field(default_factory=list)
+
+
+@dataclass
+class TmapAssocImage:
+    name: str
+    offset: int
+    size: int
+    width: int
+    height: int
+    crop: Optional[Tuple[int, int, int, int]] = None
+
+
+@dataclass
+class TmapFileInfo:
+    path: str
+    magic: str
+    version: int
+    levels: List[TmapLevel]
+    assoc_images: List[TmapAssocImage]
+    tile_count: int
+    properties: Dict[str, str] = field(default_factory=dict)
+
+
+def _read_at(f, offset: int, size: int) -> bytes:
+    f.seek(offset)
+    return f.read(size)
+
+
+def _is_jpeg(data: bytes) -> bool:
+    return len(data) >= 3 and data[:3] == b"\xff\xd8\xff"
+
+
+def _jpeg_size(data: bytes) -> Optional[Tuple[int, int]]:
+    try:
+        with Image.open(io.BytesIO(data)) as img:
+            return img.size
+    except Exception:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# TMAP07
+# ---------------------------------------------------------------------------
+
+TMAP07_HEADER_SIZE = 304
+TMAP07_IMAGEINFO_SIZE = 32
+TMAP07_IMAGEINFO_COUNT = 8
+TMAP07_LAYERINFO_BASE = 560
+TMAP07_LAYERINFO_SIZE = 32
+TMAP07_LAYERINFO_COUNT = 16
+TMAP07_REC_SIZE = 40
+
+_ASSOC07_NAMES = {
+    0: "thumbnail",
+    1: "navigate",
+    2: "macro",
+    3: "label",
+    4: "preview",
+    5: "extern",
+}
+
+
+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.
+
+    ImageInfo table at offset 304, 8 entries of 32 B:
+        width u32, height u32, depth u32, image_type u32,
+        offset u64, length u32, pad u32
+    image_type: 0=thumbnail, 1=navigate, 2=macro, 3=label, 4=preview,
+    5=extern; type 6 (whole slide) stores no pixels. Assoc payloads live
+    after the tile data near end-of-file.
+    """
+    out: List[TmapAssocImage] = []
+    raw = _read_at(f, TMAP07_HEADER_SIZE, TMAP07_IMAGEINFO_SIZE * TMAP07_IMAGEINFO_COUNT)
+    for k in range(TMAP07_IMAGEINFO_COUNT):
+        base = k * TMAP07_IMAGEINFO_SIZE
+        w, h, _depth, img_type = struct.unpack_from("<IIII", raw, base)
+        offset, length = struct.unpack_from("<QI", raw, base + 16)
+        if length == 0 or offset == 0:
+            continue
+        if offset < tile_data_end or offset + length > file_size:
+            continue
+        if not _is_jpeg(_read_at(f, offset, 3)):
+            continue
+        if w == 0 or h == 0:
+            dims = _jpeg_size(_read_at(f, offset, min(length, 8192)))
+            if dims:
+                w, h = dims
+        name = _ASSOC07_NAMES.get(img_type, f"assoc{img_type}")
+        if any(img.name == name for img in out):
+            name = f"{name}_{k}"
+        out.append(
+            TmapAssocImage(name=name, offset=offset, size=length, width=w, height=h)
+        )
+    # Provide stable macro/label aliases expected by OpenSlide-style clients.
+    _ensure_alias(out, "macro", wide=True)
+    _ensure_alias(out, "label", wide=False)
+    return out
+
+
+def _ensure_alias(images: List[TmapAssocImage], name: str, wide: bool) -> None:
+    if any(img.name == name for img in images):
+        return
+    candidates = [i for i in images if i.width > 0 and i.height > 0]
+    if not candidates:
+        return
+    if wide:
+        best = max(candidates, key=lambda i: i.width / max(1, i.height))
+    else:
+        best = min(candidates, key=lambda i: i.width / max(1, i.height))
+    images.append(TmapAssocImage(name, best.offset, best.size, best.width, best.height))
+
+
+def _parse_layer_table07(f, base: int = TMAP07_LAYERINFO_BASE) -> List[dict]:
+    """Parse the 32 B LayerInfo table for TMAP07.
+
+    Entry: layer_id u32, scale f32, width u32, height u32,
+           tile_row u32, tile_col u32, offset u32, tile_start u32.
+    tile_row is the vertical tile count and tile_col the horizontal one.
+    """
+    raw = _read_at(f, base, TMAP07_LAYERINFO_COUNT * TMAP07_LAYERINFO_SIZE)
+    entries = []
+    for k in range(TMAP07_LAYERINFO_COUNT):
+        layer_id, scale_f, w, h, tile_row, tile_col, offset, tile_start = (
+            struct.unpack_from("<IfIIIIII", raw, k * TMAP07_LAYERINFO_SIZE)
+        )
+        if w == 0 or h == 0:
+            continue
+        entries.append(
+            dict(
+                order=k,
+                layer_id=layer_id,
+                scale=scale_f,
+                width=w,
+                height=h,
+                tile_row=tile_row,
+                tile_col=tile_col,
+                index_offset=offset,
+                tile_start=tile_start,
+            )
+        )
+    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
+
+
+def _parse_tmap07(path: str) -> TmapFileInfo:
+    with open(path, "rb") as f:
+        f.seek(0, 2)
+        file_size = f.tell()
+        head = _read_at(f, 0, TMAP07_HEADER_SIZE)
+        image_format, jpeg_quality = struct.unpack_from("<BB", head, 8)
+        focus_nums = struct.unpack_from("<B", head, 10)[0] or 1
+        scan_scale = struct.unpack_from("<B", head, 11)[0]
+        bkg_color = head[12]
+        pixel_size = struct.unpack_from("<f", head, 0x10)[0]
+        declared_image_num = struct.unpack_from("<I", head, 0x14)[0]
+        layer_num = struct.unpack_from("<I", head, 0x18)[0]
+        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:
+            raise ValueError("TMAP07: level descriptor table not found")
+
+        levels: List[TmapLevel] = []
+        prop_layer_info = []
+        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:
+                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,
+                    )
+                )
+            levels.append(lvl)
+            prop_layer_info.append(
+                f"{e['width']}x{e['height']}:{e['tile_col']}x{e['tile_row']}"
+            )
+
+        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(
+            path=path,
+            magic=magic,
+            version=7,
+            levels=levels,
+            assoc_images=assoc,
+            tile_count=sum(len(l.tiles) for l in levels),
+            properties={
+                "tmap.version": "07",
+                "tmap.image_format": str(image_format),
+                "tmap.jpeg_quality": str(jpeg_quality),
+                "tmap.focus_nums": str(focus_nums),
+                "tmap.scan_scale": str(scan_scale),
+                "tmap.bkg_color": str(bkg_color),
+                "tmap.pixel_size_mm": repr(pixel_size),
+                "tmap.declared_image_num": str(declared_image_num),
+                "tmap.layer_num": str(layer_num),
+                "tmap.declared_tiles": str(declared_tiles),
+                "tmap.layer_infos": ",".join(prop_layer_info),
+                "tmap.objective_power": str(scan_scale),
+            },
+        )
+
+
+
+# ---------------------------------------------------------------------------
+# TMAP06
+def _parse_tmap06(path: str) -> TmapFileInfo:
+    """Parse TMAP06.
+
+    File structure (little-endian):
+      0x000 magic "TMAP06"; 0x006 focus_nums u8; 0x007 image_format u8;
+      0x008 file_num u8; 0x009 layer_num u8; 0x00A img_color u8;
+      0x00B checksum u8; 0x00C ratio_step u8; 0x00D max_lay_num u8;
+      0x00E slide_type u8; 0x00F bkg_color u8; 0x010 pixel_size f32 (mm);
+      0x014 image_num u32 (= LayerInfo count); 0x018 scan_scale u16;
+      0x01A img_col u16; 0x01C img_row u16; 0x01E img_width u16;
+      0x020 img_height u16; 0x022 tile_width u16; 0x024 tile_height u16;
+      0x026 air_img_width u16; 0x028 air_img_height u16;
+      0x02A version_minor u8; 0x02B save_scale u8;
+      0x02C shrink_tile_num u32; 0x030 width u32; 0x034 height u32;
+      0x038 air_img_offset u32
+      0x03C ExtInfo: lMaxExtDataLen i32, lSumExtDataLen i32,
+            lTMAPDataEndPos i32, 8 x (ext_type i32, offset i32, length i32),
+            24 reserved  -> ends at 192
+      192 LayerInfo[image_num], 308 B each:
+            file_id u8, layer u8, pad u16, top_dx u8, top_dy u8,
+            left_dx u8, left_dy u8, n_img_col u16, n_img_row u16,
+            n_x i32, n_y i32, 24 x TileInfo
+            TileInfo = layer_no u8, col u8, row u8, pad u8,
+                       offset u32, length u32
+          empty blocks have n_img_col == n_img_row == -1
+      then ShrinkTileInfo[shrink_tile_num], 20 B each:
+            file_id u8, layer_no u8, pad u16, n_x i32, n_y i32,
+            offset u32, length u32
+      then tile JPEGs, packed.
+
+    A block (n_img_col, n_img_row) is drawn at (n_x, n_y) and spans
+    img_width x img_height pixels. Its layer-0 tiles form a 4x4 grid of
+    tile_width x tile_height JPEGs, edge to edge. Layer 1 holds one tile
+    covering the whole block (downsampled by ratio_step).
+    """
+    with open(path, "rb") as f:
+        f.seek(0, 2)
+        file_size = f.tell()
+        magic_raw = _read_at(f, 0, 0xC0)
+        (focus_nums, image_format, file_num, layer_num, _img_color,
+         _checksum, ratio_step, _max_lay_num, _slide_type,
+         bkg_color) = struct.unpack_from("<10B", magic_raw, 6)
+        pixel_size = struct.unpack_from("<f", magic_raw, 0x10)[0]
+        image_num, scan_scale, img_col, img_row, img_w, img_h, tile_w, tile_h = (
+            struct.unpack_from("<IHHHHHHH", magic_raw, 0x14)
+        )
+        shrink_tile_num, width, height = struct.unpack_from("<III", magic_raw, 0x2C)
+        if ratio_step < 2 or ratio_step > 4:
+            ratio_step = 2
+        if pixel_size < 1e-8:
+            pixel_size = 1e-4
+        if width <= 0 or height <= 0:
+            raise ValueError("TMAP06: invalid canvas dimensions")
+
+        # ExtInfo at 0x3C: assoc images as (type, offset, length) triplets.
+        # ext type 1 = combined macro+label image, 2 = thumbnail.
+        assoc: List[TmapAssocImage] = []
+        ext_base = 0x3C + 12
+        for i in range(8):
+            etype, eoff, elen = struct.unpack_from(
+                "<iii", _read_at(f, ext_base + i * 12, 12), 0
+            )
+            if etype not in (1, 2) or eoff <= 0 or elen <= 0 or eoff + elen > file_size:
+                continue
+            if not _is_jpeg(_read_at(f, eoff, 3)):
+                continue
+            blob = _read_at(f, eoff, min(elen, 65536))
+            dims = _jpeg_size(blob) or (0, 0)
+            if etype == 2:
+                assoc.append(
+                    TmapAssocImage("thumbnail", eoff, elen, dims[0], dims[1])
+                )
+                continue
+            # Type 1: combined image, label = left 1/3, macro = right 2/3.
+            w, h = dims
+            assoc.append(
+                TmapAssocImage("label", eoff, elen, max(1, w // 3), h)
+            )
+            assoc.append(
+                TmapAssocImage(
+                    "macro",
+                    eoff,
+                    elen,
+                    w - max(1, w // 3),
+                    h,
+                )
+            )
+
+        # Many TMAP06 files store assoc images in the file tail:
+        # block 1 = thumbnail (e.g. 256 x 228), block 2 = combined
+        # macro+label (label = left 1/3, macro = right 2/3), each as
+        # [24B descriptor (pad, w, h, stride, bpp, pad) + JPEG]; block sizes
+        # are in header 0x88 / 0x8C and the tail start in header 0x44
+        # (= lTMAPDataEndPos).
+        if not assoc:
+            tail_start = struct.unpack_from("<I", magic_raw, 0x44)[0]
+            tail_len = struct.unpack_from("<I", magic_raw, 0x40)[0]
+            s1 = struct.unpack_from("<I", magic_raw, 0x88)[0]
+            s2 = struct.unpack_from("<I", magic_raw, 0x8C)[0]
+            if (
+                0 < tail_start < file_size
+                and 0 < tail_len <= file_size - tail_start
+                and 24 < s1 < tail_len
+                and 24 < s2 <= tail_len - s1
+            ):
+                for name, desc_off, jpeg_len in (
+                    ("thumbnail", tail_start, s1 - 24),
+                    ("macro_label", tail_start + s1, s2 - 24),
+                ):
+                    desc = _read_at(f, desc_off, 24)
+                    _pad, w, h, _stride, _bpp, _extra = struct.unpack_from(
+                        "<IIIIII", desc, 0
+                    )
+                    jpeg_off = desc_off + 24
+                    if not (0 < jpeg_len <= file_size - jpeg_off):
+                        continue
+                    if not _is_jpeg(_read_at(f, jpeg_off, 3)):
+                        continue
+                    if w == 0 or h == 0:
+                        dims = _jpeg_size(
+                            _read_at(f, jpeg_off, min(jpeg_len, 8192))
+                        ) or (0, 0)
+                        w, h = dims
+                    if name == "macro_label" and w >= 3:
+                        third = w // 3
+                        assoc.append(
+                            TmapAssocImage(
+                                name="label",
+                                offset=jpeg_off,
+                                size=jpeg_len,
+                                width=third,
+                                height=h,
+                                crop=(0, 0, third, h),
+                            )
+                        )
+                        name = "macro"
+                        assoc.append(
+                            TmapAssocImage(
+                                name=name,
+                                offset=jpeg_off,
+                                size=jpeg_len,
+                                width=w - third,
+                                height=h,
+                                crop=(third, 0, w, h),
+                            )
+                        )
+                        continue
+                    assoc.append(
+                        TmapAssocImage(
+                            name=name, offset=jpeg_off, size=jpeg_len, width=w, height=h
+                        )
+                    )
+
+        # LayerInfo table at 192.
+        li_base = 192
+        li_raw = _read_at(f, li_base, min(image_num, 100000) * 308)
+        blocks = {}  # (n_img_col, n_img_row) -> layer info dict
+        for k in range(min(image_num, len(li_raw) // 308)):
+            base = k * 308
+            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)
+            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:
+                    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])
+
+        # ShrinkTileInfo right after the LayerInfo table.
+        st_base = li_base + image_num * 308
+        shrinks = []
+        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)
+            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))
+
+        # Pyramid levels: ratio_step division from the level-0 canvas.
+        levels_meta = []
+        w, h = width, height
+        scale = scan_scale
+        while scale >= 1 and w > 0 and h > 0:
+            levels_meta.append((w, h))
+            w = (w + ratio_step - 1) // ratio_step
+            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)
+            try:
+                return Image.open(io.BytesIO(data))
+            except Exception:
+                return None
+
+        # Determine layer-0 tile geometry from the first available tile.
+        tw = th = None
+        for info in blocks.values():
+            for layer_no, col, row, off, length in info["tiles"]:
+                if layer_no == 0:
+                    im = _tile_img(off, length)
+                    if im is not None:
+                        tw, th = im.size
+                        break
+            if tw:
+                break
+        if tw is None:
+            tw, th = tile_w, tile_h
+
+        # Build one TmapLevel per pyramid level. Level 0/1 tile lists are
+        # populated so iter_tiles()/caching can address individual tiles.
+        levels: List[TmapLevel] = []
+        for order, (lw, lh) in enumerate(levels_meta):
+            lvl = TmapLevel(
+                index=order,
+                downsample=float(ratio_step**order),
+                width=lw,
+                height=lh,
+                tile_width=tw * (ratio_step**order if order > 1 else 1),
+                tile_height=th * (ratio_step**order if order > 1 else 1),
+            )
+            levels.append(lvl)
+
+        for (n_col, n_row), blk in blocks.items():
+            n_x, n_y = blk["n_x"], blk["n_y"]
+            for layer_no, col, row, off, length in blk["tiles"]:
+                if layer_no == 0:
+                    levels[0].tiles.append(
+                        TmapTile(
+                            level=0,
+                            offset=off,
+                            size=length,
+                            x=n_x + col * tw,
+                            y=n_y + row * th,
+                            width=tw,
+                            height=th,
+                        )
+                    )
+                elif layer_no == 1 and len(levels) > 1:
+                    levels[1].tiles.append(
+                        TmapTile(
+                            level=1,
+                            offset=off,
+                            size=length,
+                            x=n_x // ratio_step,
+                            y=n_y // ratio_step,
+                            width=tw,
+                            height=th,
+                        )
+                    )
+
+        info = TmapFileInfo(
+            path=path,
+            magic=magic_raw[:6].decode("ascii", errors="replace"),
+            version=6,
+            levels=levels,
+            assoc_images=assoc,
+            tile_count=sum(len(v["tiles"]) for v in blocks.values()),
+            properties={
+                "tmap.version": "06",
+                "tmap.objective_power": str(scan_scale),
+                "tmap.pixel_size_mm": repr(pixel_size),
+                "tmap.img_col": str(img_col),
+                "tmap.img_row": str(img_row),
+                "tmap.img_width": str(img_w),
+                "tmap.img_height": str(img_h),
+                "tmap.tile_width": str(tile_w),
+                "tmap.tile_height": str(tile_h),
+                "tmap.blocks": str(len(blocks)),
+                "tmap.shrink_tiles": str(len(shrinks)),
+                "tmap.bkg_color": str(bkg_color),
+            },
+            # extra fields for read_region
+        )
+        info.__dict__["_blocks"] = blocks
+        info.__dict__["_shrinks"] = shrinks
+        info.__dict__["_ratio_step"] = ratio_step
+        info.__dict__["_tile_jpeg_size"] = (tw, th)
+        return info
+
+
+def parse_tmap_file(path: str) -> TmapFileInfo:
+    """Parse a TMAP file and return structured info."""
+    with open(path, "rb") as f:
+        magic = f.read(8)
+    if len(magic) < 6 or magic[:4] != TMAP_MAGIC:
+        raise ValueError(f"Not a TMAP file: magic={magic[:8]!r}")
+    if magic[:6] == b"TMAP06":
+        return _parse_tmap06(path)
+    if magic[:6] == b"TMAP07":
+        return _parse_tmap07(path)
+    raise ValueError(f"Unsupported TMAP version: {magic[:6]!r}")