shortcog 0.5.0__tar.gz

shortcog-0.5.0/.gitignore

@@ -0,0 +1,69 @@
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+.coverage
+coverage.xml
+htmlcov/
+.hypothesis/
+
+# c++ / cmake
+build/
+build-*/
+cmake-build-*/
+*.o
+*.obj
+*.so
+*.so.*
+*.dylib
+*.dll
+*.a
+*.lib
+*.pdb
+*.exp
+CMakeCache.txt
+CMakeFiles/
+CMakeUserPresets.json
+cmake_install.cmake
+*.ninja
+.ninja_deps
+.ninja_log
+compile_commands.json
+.cache/
+
+# virtualenvs
+.venv/
+venv/
+env/
+
+# distribution
+dist/
+wheelhouse/
+*.whl
+
+# editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# os
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# misc
+*.log
+
+
+# test data
+core/tests/fixtures/data/
+demo.py
+
+T30TYK_B04_shortcog.tif

shortcog-0.5.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: shortcog
+Version: 0.5.0
+Summary: A COG profile for AI training data.
+Project-URL: Homepage, https://github.com/asterisk-labs/shortcog
+Project-URL: Repository, https://github.com/asterisk-labs/shortcog
+Project-URL: Issues, https://github.com/asterisk-labs/shortcog/issues
+Author-email: Cesar Aybar <cesar@asterisk.coop>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cffi>=1.17
+Requires-Dist: numpy>=1.24
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# shortcog (python)
+
+Python bindings for the shortcog reader. See the top level `README.md` for the public API and usage examples.

shortcog-0.5.0/README.md

@@ -0,0 +1,3 @@
+# shortcog (python)
+
+Python bindings for the shortcog reader. See the top level `README.md` for the public API and usage examples.

shortcog-0.5.0/hatch_build.py

@@ -0,0 +1,20 @@
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+_LIB_GLOBS = ("*.so", "*.so.*", "*.dylib", "*.dll")
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        lib_dir = Path(self.root) / "shortcog" / "_lib"
+        found = [p for g in _LIB_GLOBS for p in lib_dir.glob(g)]
+        if not found:
+            raise RuntimeError(
+                f"no native library in {lib_dir}. Build it first: "
+                "`make lib` from the repo root."
+            )
+
+        # Binary inside, so tag the wheel for this platform, not py3-none-any.
+        build_data["pure_python"] = False
+        build_data["infer_tag"] = True

shortcog-0.5.0/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires      = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+
+[project]
+name            = "shortcog"
+dynamic         = ["version"]
+description     = "A COG profile for AI training data."
+readme          = "README.md"
+license         = { text = "MIT" }
+requires-python = ">=3.12"
+
+authors = [
+    { name = "Cesar Aybar",     email = "cesar@asterisk.coop" },
+]
+
+dependencies = [
+    "numpy>=1.24",
+    "cffi>=1.17",
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: C++",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: GIS",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7",
+]
+
+[project.urls]
+Homepage   = "https://github.com/asterisk-labs/shortcog"
+Repository = "https://github.com/asterisk-labs/shortcog"
+Issues     = "https://github.com/asterisk-labs/shortcog/issues"
+
+
+[tool.hatch.version]
+path    = "../../VERSION"
+pattern = "(?P<version>\\S+)"
+
+[tool.hatch.build.targets.wheel]
+packages  = ["shortcog"]
+artifacts = [
+    "shortcog/_lib/*.so",
+    "shortcog/_lib/*.so.*",
+    "shortcog/_lib/*.dylib",
+    "shortcog/_lib/*.dll",
+]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "shortcog/**",
+    "tests/**",
+    "hatch_build.py",
+    "README.md",
+]
+exclude = [
+    "shortcog/_lib/*.so",
+    "shortcog/_lib/*.so.*",
+    "shortcog/_lib/*.dylib",
+    "shortcog/_lib/*.dll",
+]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts   = "-ra --strict-markers"
+
+[tool.ruff]
+line-length    = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "NPY"]

shortcog-0.5.0/shortcog/__init__.py

@@ -0,0 +1,9 @@
+"""shortcog, a COG profile for AI training data."""
+
+from ._ffi import ffi, lib
+from ._read import index_file, parse, read
+from ._spec import Spec
+
+__all__ = ["Spec", "__version__", "index_file", "parse", "read"]
+
+__version__ = ffi.string(lib.shortcog_version_string()).decode("ascii")

shortcog-0.5.0/shortcog/_ffi.py

@@ -0,0 +1,141 @@
+import ctypes.util
+import os
+from pathlib import Path
+
+from cffi import FFI
+
+# The C definitions for the API.
+_CDEF = """
+typedef enum {
+    SHORTCOG_OK              = 0,
+    SHORTCOG_ERR_INVALID     = 1,
+    SHORTCOG_ERR_IO          = 2,
+    SHORTCOG_ERR_PARSE       = 3,
+    SHORTCOG_ERR_FORMAT      = 4,
+    SHORTCOG_ERR_DECODE      = 5,
+    SHORTCOG_ERR_OOM         = 6,
+    SHORTCOG_ERR_UNSUPPORTED = 7,
+    SHORTCOG_ERR_INTERNAL    = 99
+} shortcog_status;
+
+typedef struct {
+    uint32_t image_width;
+    uint32_t image_length;
+    uint16_t tile_width;
+    uint16_t tile_length;
+    uint16_t samples_per_pixel;
+    uint8_t  bits_per_sample;
+    uint8_t  sample_format;
+    uint8_t  predictor;
+    uint8_t  _reserved;
+    uint32_t tiles_across;
+    uint32_t tiles_down;
+    uint64_t base_tiles_offset;
+} shortcog_header;
+
+typedef struct {
+    int64_t shape[4];
+    int     ndim;
+    int64_t sn;
+    int64_t sb;
+    int64_t sy;
+    int64_t sx;
+    int     native;
+} shortcog_layout;
+
+typedef struct shortcog_spec shortcog_spec;
+
+int         shortcog_api_version(void);
+const char* shortcog_version_string(void);
+const char* shortcog_last_error(void);
+void        shortcog_clear_error(void);
+void        shortcog_free(void* ptr);
+
+shortcog_status
+shortcog_index_file(const char* path, unsigned char** out_blob, size_t* out_size);
+
+shortcog_status
+shortcog_compile_layout(const char* pattern,
+                        int64_t n, int64_t b, int64_t y, int64_t x,
+                        shortcog_layout* out);
+
+shortcog_status
+shortcog_spec_parse(const unsigned char* blob, size_t blob_size,
+                    shortcog_spec** out);
+
+void shortcog_spec_destroy(shortcog_spec* spec);
+
+shortcog_status
+shortcog_spec_header(const shortcog_spec* spec, shortcog_header* out);
+
+shortcog_status
+shortcog_read(const char* path, const shortcog_spec* spec,
+              const int* bands, size_t n_bands,
+              int y_off, int y_size, int x_off, int x_size,
+              const char* pattern, int num_threads,
+              void* dst, size_t dst_size);
+
+shortcog_status
+shortcog_read_stack(const char* const* paths,
+                    const shortcog_spec* const* specs, size_t n_images,
+                    const int* n_index, size_t n_n,
+                    const int* bands, size_t n_bands,
+                    int y_off, int y_size, int x_off, int x_size,
+                    const char* pattern, int num_threads,
+                    void* dst, size_t dst_size);
+"""
+
+
+ffi = FFI()
+ffi.cdef(_CDEF)
+
+_LIB_GLOBS = ("*.so", "*.so.*", "*.dylib", "*.dll")
+
+
+def _bundled_lib():
+    lib_dir = Path(__file__).parent / "_lib"
+    for pattern in _LIB_GLOBS:
+        for path in sorted(lib_dir.glob(pattern)):
+            return str(path)
+    return None
+
+
+def _load_lib():
+    # SHORTCOG_LIB beats everything, then the bundled wheel copy, then the OS path.
+    env_path = os.environ.get("SHORTCOG_LIB")
+    candidate = env_path or _bundled_lib() or ctypes.util.find_library("shortcog")
+    if candidate is None:
+        raise OSError(
+            "libshortcog not found. Install it or set SHORTCOG_LIB to its path."
+        )
+    try:
+        return ffi.dlopen(candidate)
+    except OSError as exc:
+        raise OSError(
+            f"failed to load libshortcog from {candidate!r}: {exc}. "
+            "It links GDAL; put a compatible libgdal on the loader path."
+        ) from exc
+
+
+lib = _load_lib()
+
+
+_STATUS_TO_EXC = {
+    lib.SHORTCOG_ERR_INVALID:     ValueError,
+    lib.SHORTCOG_ERR_IO:          IOError,
+    lib.SHORTCOG_ERR_PARSE:       ValueError,
+    lib.SHORTCOG_ERR_FORMAT:      ValueError,
+    lib.SHORTCOG_ERR_DECODE:      IOError,
+    lib.SHORTCOG_ERR_OOM:         MemoryError,
+    lib.SHORTCOG_ERR_UNSUPPORTED: NotImplementedError,
+    lib.SHORTCOG_ERR_INTERNAL:    RuntimeError,
+}
+
+
+def _check(rc):
+    if rc == lib.SHORTCOG_OK:
+        return
+    err = lib.shortcog_last_error()
+    msg = (ffi.string(err).decode("utf-8", errors="replace")
+           if err != ffi.NULL else "(no error message)")
+    raise _STATUS_TO_EXC.get(rc, RuntimeError)(msg)

shortcog-0.5.0/shortcog/_read.py

@@ -0,0 +1,161 @@
+import os
+from collections.abc import Sequence
+
+import numpy as np
+
+from ._ffi import _check, ffi, lib
+from ._spec import Spec
+
+# (start, stop) slice, explicit 0-based indices, or None for all.
+Axis = tuple[int, int] | list[int] | None
+PathLike = str | bytes | os.PathLike
+
+
+def _enc(path: PathLike) -> bytes:
+    return path.encode("utf-8") if isinstance(path, str) else os.fsencode(path)
+
+
+# Tuple selectors are Python slices (start, stop), 0-based. Lists are 0-based
+# explicit indices in the order requested. Both convert to 1-based for the C
+# API. None means all and gets passed through as NULL/0.
+def _resolve_axis(sel: Axis, name: str, total: int) -> list[int] | None:
+    if sel is None:
+        return None
+    if isinstance(sel, tuple):
+        if len(sel) != 2:
+            raise ValueError(f"{name}: tuple must be (start, stop)")
+        start, stop = sel
+        if not (0 <= start < stop <= total):
+            raise ValueError(f"{name}: slice ({start}, {stop}) out of [0, {total}]")
+        return list(range(start + 1, stop + 1))
+    if isinstance(sel, list):
+        out = [int(i) + 1 for i in sel]
+        for x in out:
+            if not (1 <= x <= total):
+                raise ValueError(f"{name}: index {x - 1} out of [0, {total})")
+        return out
+    raise TypeError(f"{name}: expected tuple or list, got {type(sel).__name__}")
+
+
+def _resolve_window(sel: tuple[int, int] | None, name: str,
+                    total: int) -> tuple[int, int]:
+    if sel is None:
+        return 0, total
+    if isinstance(sel, tuple) and len(sel) == 2:
+        start, stop = sel
+        if not (0 <= start < stop <= total):
+            raise ValueError(f"{name}: window ({start}, {stop}) out of [0, {total}]")
+        return start, stop - start
+    raise TypeError(f"{name}: expected (start, stop) tuple")
+
+
+def _to_c(lst: list[int] | None):
+    if lst is None:
+        return ffi.NULL, 0
+    return ffi.new("int[]", lst), len(lst)
+
+
+def index_file(path: PathLike) -> bytes:
+    blob_out = ffi.new("unsigned char**")
+    size_out = ffi.new("size_t*")
+    _check(lib.shortcog_index_file(_enc(path), blob_out, size_out))
+    try:
+        return bytes(ffi.buffer(blob_out[0], size_out[0]))
+    finally:
+        lib.shortcog_free(blob_out[0])
+
+
+def parse(blob: bytes | bytearray | memoryview) -> Spec:
+    return Spec(blob)
+
+
+def _read_one(path: PathLike, spec: Spec, pattern: str | None,
+              b: Axis, y: tuple[int, int] | None, x: tuple[int, int] | None,
+              num_threads: int) -> np.ndarray:
+    h = spec._header
+    bands = _resolve_axis(b, "b", h.samples_per_pixel)
+    y_off, y_size = _resolve_window(y, "y", h.image_length)
+    x_off, x_size = _resolve_window(x, "x", h.image_width)
+
+    n_bands = len(bands) if bands is not None else h.samples_per_pixel
+    if pattern is None:
+        pattern = "b y x"
+
+    layout = ffi.new("shortcog_layout*")
+    _check(lib.shortcog_compile_layout(
+        pattern.encode("ascii"), 1, n_bands, y_size, x_size, layout
+    ))
+    shape = tuple(layout.shape[i] for i in range(layout.ndim))
+    arr = np.empty(shape, dtype=spec._dtype)
+
+    bands_c, n_bands_c = _to_c(bands)
+    _check(lib.shortcog_read(
+        _enc(path), spec._handle, bands_c, n_bands_c,
+        y_off, y_size, x_off, x_size,
+        pattern.encode("ascii"), num_threads,
+        ffi.cast("void*", arr.ctypes.data), arr.nbytes,
+    ))
+    return arr
+
+
+def _read_stack(paths: Sequence[PathLike], specs: Sequence[Spec],
+                pattern: str | None, n: Axis, b: Axis,
+                y: tuple[int, int] | None, x: tuple[int, int] | None,
+                num_threads: int) -> np.ndarray:
+    paths = list(paths)
+    specs = list(specs)
+    if len(paths) != len(specs):
+        raise ValueError(
+            f"paths and specs length mismatch: {len(paths)} vs {len(specs)}"
+        )
+    if not paths:
+        raise ValueError("read requires at least one image")
+
+    h = specs[0]._header
+    n_sel = _resolve_axis(n, "n", len(specs))
+    bands = _resolve_axis(b, "b", h.samples_per_pixel)
+    y_off, y_size = _resolve_window(y, "y", h.image_length)
+    x_off, x_size = _resolve_window(x, "x", h.image_width)
+
+    n_count = len(n_sel) if n_sel is not None else len(specs)
+    n_bands = len(bands) if bands is not None else h.samples_per_pixel
+    if pattern is None:
+        pattern = "n b y x" if n_count > 1 else "b y x"
+
+    layout = ffi.new("shortcog_layout*")
+    _check(lib.shortcog_compile_layout(
+        pattern.encode("ascii"), n_count, n_bands, y_size, x_size, layout
+    ))
+    shape = tuple(layout.shape[i] for i in range(layout.ndim))
+    arr = np.empty(shape, dtype=specs[0]._dtype)
+
+    paths_c = [ffi.new("char[]", _enc(p)) for p in paths]
+    paths_arr = ffi.new("char*[]", paths_c)
+    specs_arr = ffi.new("shortcog_spec*[]", [s._handle for s in specs])
+
+    n_c, n_count_c = _to_c(n_sel)
+    bands_c, n_bands_c = _to_c(bands)
+    _check(lib.shortcog_read_stack(
+        paths_arr, specs_arr, len(specs),
+        n_c, n_count_c, bands_c, n_bands_c,
+        y_off, y_size, x_off, x_size,
+        pattern.encode("ascii"), num_threads,
+        ffi.cast("void*", arr.ctypes.data), arr.nbytes,
+    ))
+    return arr
+
+
+# Polymorphic and stateless. A single path/spec reads one image, lists read a
+# stack. Opens, reads, closes, with nothing kept alive between calls.
+def read(paths: PathLike | Sequence[PathLike],
+         specs: Spec | Sequence[Spec],
+         pattern: str | None = None, *,
+         n: Axis = None, b: Axis = None,
+         y: tuple[int, int] | None = None,
+         x: tuple[int, int] | None = None,
+         num_threads: int = 1) -> np.ndarray:
+    if isinstance(paths, (str, bytes, os.PathLike)):
+        if n is not None:
+            raise ValueError("n applies to a stack; pass lists of paths/specs")
+        return _read_one(paths, specs, pattern, b, y, x, num_threads)
+    return _read_stack(paths, specs, pattern, n, b, y, x, num_threads)

shortcog-0.5.0/shortcog/_repr.py

@@ -0,0 +1,114 @@
+import html
+import itertools
+
+_FACE = "#FAEEDA"
+_TOP = "#FAC775"
+_SIDE = "#EF9F27"
+_LINE = "#854F0B"
+_EDGE = "#633806"
+
+_counter = itertools.count()
+
+
+# At depth t the band slice is front-top-left -> front-top-right ->
+# front-bottom-right, each shifted by t*(33, -33).
+def _sheet(t):
+    dx, dy = 33 * t, -33 * t
+    return (f'<polyline points="{55+dx},{72+dy} {145+dx},{72+dy} {145+dx},{185+dy}" '
+            f'fill="none" stroke="{_EDGE}" stroke-width="1" opacity=".78"/>')
+
+
+def _bands(b):
+    if b <= 1:
+        return ""
+    if b < 10:
+        return "".join(_sheet(k / b) for k in range(1, b))
+    fronts = [0.06, 0.12, 0.18, 0.24] if b <= 50 else \
+             [0.04, 0.07, 0.10, 0.13, 0.16, 0.19]
+    sheets = "".join(_sheet(t) for t in fronts) + _sheet(0.88)
+    dots = "".join(f'<circle cx="{105+i*8}" cy="50" r="2.1" fill="{_EDGE}"/>'
+                   for i in range(3))
+    return sheets + dots
+
+
+def _cube(b, x, y):
+    return (
+        '<svg width="100%" viewBox="0 0 215 205" '
+        f'role="img" aria-label="shortcog image cube, {b} bands">'
+        f'<polygon points="55,72 88,39 178,39 145,72" fill="{_TOP}" '
+        f'stroke="{_LINE}" stroke-width="1.3"/>'
+        f'<polygon points="145,72 178,39 178,152 145,185" fill="{_SIDE}" '
+        f'stroke="{_LINE}" stroke-width="1.3"/>'
+        f'{_bands(b)}'
+        f'<rect x="55" y="72" width="90" height="113" fill="{_FACE}" '
+        f'stroke="{_EDGE}" stroke-width="1.5"/>'
+        f'<g stroke="{_LINE}" stroke-width="0.5" opacity=".35">'
+        '<line x1="85" y1="72" x2="85" y2="185"/>'
+        '<line x1="115" y1="72" x2="115" y2="185"/>'
+        '<line x1="55" y1="110" x2="145" y2="110"/>'
+        '<line x1="55" y1="147" x2="145" y2="147"/></g>'
+        f'<text x="100" y="199" text-anchor="middle" font-size="10.5" '
+        f'font-family="monospace" fill="currentColor" opacity=".7">X: {x}</text>'
+        f'<text x="44" y="128" text-anchor="middle" font-size="10.5" '
+        f'font-family="monospace" fill="currentColor" opacity=".7" '
+        f'transform="rotate(-90,44,128)">Y: {y}</text>'
+        f'<text x="182" y="37" font-size="10.5" font-family="monospace" '
+        f'fill="currentColor" opacity=".7">B: {b}</text>'
+        '</svg>'
+    )
+
+
+_CSS = """
+#ID{font-family:ui-monospace,Menlo,monospace;font-size:13px;color:inherit;
+ display:inline-block;line-height:1.5}
+#ID .box{display:flex;gap:6px;align-items:center;
+ background:rgba(128,128,128,.06);border:1px solid rgba(128,128,128,.25);
+ border-radius:8px;padding:12px 16px}
+#ID .hdr{margin-bottom:9px}
+#ID .cls{opacity:.6}
+#ID .dim{font-weight:600}
+#ID table{border-collapse:collapse;font-size:12.5px}
+#ID td.k{opacity:.6;padding:2px 16px 2px 0}
+#ID td.sub{opacity:.45;padding-left:10px}
+#ID .g{flex:0 0 auto;width:170px}
+"""
+
+
+def _wrap(inner):
+    uid = f"scog{next(_counter)}"
+    return (f'<div class="shortcog-repr" id="{uid}"><style>'
+            f'{_CSS.replace("#ID", f"#{uid}")}</style>{inner}</div>')
+
+
+def text(f):
+    if not f["ok"]:
+        return "<shortcog.Spec (unreadable)>"
+    tw, tl = f["tile"]
+    return "\n".join([
+        f"<shortcog.Spec ({f['b']}, {f['y']}, {f['x']})>",
+        f"  dtype      : {f['dtype']}",
+        f"  tile       : {tw} x {tl}",
+        f"  tiles      : {f['tiles']}",
+        f"  tiles/band : {f['across'] * f['down']}",
+        f"  codec      : {f['codec']}",
+    ])
+
+
+def html_(f):
+    if not f["ok"]:
+        return _wrap('<div class="hdr"><span class="cls">shortcog.Spec</span> '
+                     '<span class="dim">(unreadable)</span></div>')
+    tw, tl = f["tile"]
+    e = html.escape
+    rows = (
+        f'<tr><td class="k">dtype</td><td>{e(f["dtype"])}</td></tr>'
+        f'<tr><td class="k">tile</td><td>{tw} \u00d7 {tl}</td></tr>'
+        f'<tr><td class="k">tiles</td><td><b>{f["tiles"]:,}</b></td></tr>'
+        f'<tr><td class="k">tiles/band</td><td>{f["across"] * f["down"]:,}</td></tr>'
+        f'<tr><td class="k">codec</td><td>{e(f["codec"])}</td></tr>'
+    )
+    meta = (f'<div><div class="hdr"><span class="cls">shortcog.Spec</span> '
+            f'<span class="dim">({f["b"]}, {f["y"]}, {f["x"]})</span></div>'
+            f'<table>{rows}</table></div>')
+    return _wrap(f'<div class="box">{meta}'
+                 f'<div class="g">{_cube(f["b"], f["x"], f["y"])}</div></div>')

shortcog-0.5.0/shortcog/_spec.py

@@ -0,0 +1,85 @@
+import numpy as np
+
+from . import _repr
+from ._ffi import _check, ffi, lib
+
+# Spec dtype encoding (sample_format, bits_per_sample) -> numpy dtype.
+# Complex int and 16-bit complex float have no numpy equivalent and raise.
+_DTYPE: dict[tuple[int, int], type[np.generic]] = {
+    (1, 8):   np.uint8,
+    (1, 16):  np.uint16,
+    (1, 32):  np.uint32,
+    (1, 64):  np.uint64,
+    (2, 8):   np.int8,
+    (2, 16):  np.int16,
+    (2, 32):  np.int32,
+    (2, 64):  np.int64,
+    (3, 16):  np.float16,
+    (3, 32):  np.float32,
+    (3, 64):  np.float64,
+    (6, 64):  np.complex64,
+    (6, 128): np.complex128,
+}
+
+
+# predictor doubles as codec selector. 1/2 are ZSTD (TIFF predictor none/
+# horizontal); reserved high values pick a codec that needs no predictor.
+_CODEC = {1: "ZSTD", 2: "ZSTD + horizontal", 42: "OpenZL"}
+
+
+def _np_dtype(sf: int, bps: int) -> type[np.generic]:
+    try:
+        return _DTYPE[(sf, bps)]
+    except KeyError:
+        raise NotImplementedError(
+            f"no numpy dtype for (sample_format={sf}, bits_per_sample={bps})"
+        ) from None
+
+
+class Spec:
+    """Parsed header blob. Pure memory, no file handle, reusable across reads."""
+
+    def __init__(self, blob: bytes | bytearray | memoryview) -> None:
+        if not isinstance(blob, (bytes, bytearray, memoryview)):
+            raise TypeError(f"blob must be bytes-like, got {type(blob).__name__}")
+
+        blob_buf = ffi.from_buffer("unsigned char[]", blob)
+        handle_out = ffi.new("shortcog_spec**")
+        _check(lib.shortcog_spec_parse(blob_buf, len(blob), handle_out))
+        # ffi.gc frees the handle whenever it goes away, even mid-__init__.
+        self._handle = ffi.gc(handle_out[0], lib.shortcog_spec_destroy)
+
+        header = ffi.new("shortcog_header*")
+        _check(lib.shortcog_spec_header(self._handle, header))
+        self._header = header
+        self._dtype = _np_dtype(header.sample_format, header.bits_per_sample)
+
+    @property
+    def shape(self) -> tuple[int, int, int]:
+        h = self._header
+        return (h.samples_per_pixel, h.image_length, h.image_width)
+
+    @property
+    def dtype(self) -> type[np.generic]:
+        return self._dtype
+
+    def _facts(self) -> dict:
+        try:
+            h = self._header
+            return {
+                "ok": True,
+                "b": h.samples_per_pixel, "y": h.image_length, "x": h.image_width,
+                "dtype": self._dtype.__name__,
+                "tile": (h.tile_width, h.tile_length),
+                "across": h.tiles_across, "down": h.tiles_down,
+                "tiles": h.tiles_across * h.tiles_down * h.samples_per_pixel,
+                "codec": _CODEC.get(h.predictor, "ZSTD"),
+            }
+        except Exception:
+            return {"ok": False}
+
+    def __repr__(self) -> str:
+        return _repr.text(self._facts())
+
+    def _repr_html_(self) -> str:
+        return _repr.html_(self._facts())