rumi-eo 0.8.3__tar.gz

rumi_eo-0.8.3/.gitignore

@@ -0,0 +1,73 @@
+# 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
+
+demo_shortcog.tif
+
+demo.tif

rumi_eo-0.8.3/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: rumi-eo
+Version: 0.8.3
+Summary: A GeoTIFF profile for AI training data.
+Project-URL: Homepage, https://github.com/asterisk-labs/rumi
+Project-URL: Repository, https://github.com/asterisk-labs/rumi
+Project-URL: Issues, https://github.com/asterisk-labs/rumi/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.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: certifi
+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.

rumi_eo-0.8.3/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.

rumi_eo-0.8.3/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) / "rumi" / "_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

rumi_eo-0.8.3/pyproject.toml

@@ -0,0 +1,91 @@
+[build-system]
+requires      = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+
+[project]
+name            = "rumi-eo"
+dynamic         = ["version"]
+description     = "A GeoTIFF profile for AI training data."
+readme          = "README.md"
+license         = { text = "MIT" }
+requires-python = ">=3.11"
+
+authors = [
+    { name = "Cesar Aybar",     email = "cesar@asterisk.coop" },
+]
+
+dependencies = [
+    "numpy>=1.24",
+    "cffi>=1.17",
+    "certifi",
+]
+
+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.11",
+    "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/rumi"
+Repository = "https://github.com/asterisk-labs/rumi"
+Issues     = "https://github.com/asterisk-labs/rumi/issues"
+
+
+[tool.hatch.version]
+path    = "../../VERSION"
+pattern = "(?P<version>\\S+)"
+
+[tool.hatch.build.targets.wheel]
+packages  = ["rumi"]
+artifacts = [
+    "rumi/_lib/*.so",
+    "rumi/_lib/*.so.*",
+    "rumi/_lib/*.dylib",
+    "rumi/_lib/*.dll",
+]
+
+[tool.hatch.build.targets.wheel.hooks.custom]
+path = "hatch_build.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "rumi/**",
+    "tests/**",
+    "hatch_build.py",
+    "README.md",
+]
+exclude = [
+    "rumi/_lib/*.so",
+    "rumi/_lib/*.so.*",
+    "rumi/_lib/*.dylib",
+    "rumi/_lib/*.dll",
+]
+
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts   = "-ra --strict-markers"
+
+[tool.ruff]
+line-length    = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "NPY"]

rumi_eo-0.8.3/rumi/__init__.py

@@ -0,0 +1,16 @@
+from importlib.metadata import version
+
+from ._ffi import lib
+from ._read import index_file, parse, read
+from ._spec import Spec
+from ._write import Layout, tile, write
+
+__version__ = version("rumi-eo")
+
+# The OpenZL frame format version.
+OPENZL_VERSION = lib.rumi_openzl_format_version()
+
+__all__ = [
+    "Layout", "OPENZL_VERSION", "Spec", "__version__",
+    "index_file", "parse", "read", "tile", "write",
+]

rumi_eo-0.8.3/rumi/_dtype.py

@@ -0,0 +1,38 @@
+import numpy as np
+
+# (sample_format, bits_per_sample) is the canonical sample encoding from the spec.
+_ENCODING: dict[type[np.generic], tuple[int, int]] = {
+    np.uint8:      (1, 8),
+    np.uint16:     (1, 16),
+    np.uint32:     (1, 32),
+    np.uint64:     (1, 64),
+    np.int8:       (2, 8),
+    np.int16:      (2, 16),
+    np.int32:      (2, 32),
+    np.int64:      (2, 64),
+    np.float16:    (3, 16),
+    np.float32:    (3, 32),
+    np.float64:    (3, 64),
+    np.complex64:  (6, 64),
+    np.complex128: (6, 128),
+}
+
+_DECODE: dict[tuple[int, int], type[np.generic]] = {
+    enc: dt for dt, enc in _ENCODING.items()
+}
+
+
+def sample_encoding(dtype) -> tuple[int, int]:
+    try:
+        return _ENCODING[np.dtype(dtype).type]
+    except KeyError:
+        raise ValueError(f"unsupported dtype {np.dtype(dtype)}") from None
+
+
+def np_dtype(sf: int, bps: int) -> type[np.generic]:
+    try:
+        return _DECODE[(sf, bps)]
+    except KeyError:
+        raise NotImplementedError(
+            f"no numpy dtype for (sample_format={sf}, bits_per_sample={bps})"
+        ) from None

rumi_eo-0.8.3/rumi/_ffi.py

@@ -0,0 +1,173 @@
+import ctypes.util
+import os
+from pathlib import Path
+
+from cffi import FFI
+
+_CDEF = """
+typedef enum {
+    RUMI_OK              = 0,
+    RUMI_ERR_INVALID     = 1,
+    RUMI_ERR_IO          = 2,
+    RUMI_ERR_PARSE       = 3,
+    RUMI_ERR_FORMAT      = 4,
+    RUMI_ERR_DECODE      = 5,
+    RUMI_ERR_OOM         = 6,
+    RUMI_ERR_UNSUPPORTED = 7,
+    RUMI_ERR_INTERNAL    = 99
+} rumi_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;
+    uint32_t tiles_across;
+    uint32_t tiles_down;
+    uint64_t base_tiles_offset;
+} rumi_header;
+
+typedef struct {
+    int64_t shape[4];
+    int     ndim;
+    int64_t sn;
+    int64_t sb;
+    int64_t sy;
+    int64_t sx;
+    int     native;
+} rumi_layout;
+
+typedef struct rumi_spec rumi_spec;
+
+int         rumi_api_version(void);
+const char* rumi_version_string(void);
+int         rumi_openzl_format_version(void);
+const char* rumi_last_error(void);
+void        rumi_clear_error(void);
+void        rumi_free(void* ptr);
+
+rumi_status
+rumi_index_file(const char* path, unsigned char** out_blob, size_t* out_size);
+
+rumi_status
+rumi_compile_layout(const char* pattern,
+                    int64_t n, int64_t b, int64_t y, int64_t x,
+                    rumi_layout* out);
+
+rumi_status
+rumi_spec_parse(const unsigned char* blob, size_t blob_size,
+                rumi_spec** out);
+
+void rumi_spec_destroy(rumi_spec* spec);
+
+rumi_status
+rumi_spec_header(const rumi_spec* spec, rumi_header* out);
+
+rumi_status
+rumi_read(const char* path, const rumi_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);
+
+rumi_status
+rumi_read_stack(const char* const* paths,
+                const rumi_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);
+
+rumi_status
+rumi_geokeys(const char* srs, int pixel_is_point,
+             unsigned char** out_dir,   size_t* out_dir_size,
+             unsigned char** out_dbl,   size_t* out_dbl_size,
+             unsigned char** out_ascii, size_t* out_ascii_size);
+"""
+
+
+ffi = FFI()
+ffi.cdef(_CDEF)
+
+_LIB_GLOBS = ("*.so", "*.so.*", "*.dylib", "*.dll")
+
+
+def _ensure_ca_bundle():
+    # Bundled libcurl/openssl come from conda and look for CA certs at a conda
+    # path absent off-conda (Colab, venvs), breaking HTTPS /vsicurl/ reads.
+    if any(os.environ.get(v) for v in (
+        "CURL_CA_BUNDLE", "GDAL_CURL_CA_BUNDLE", "SSL_CERT_FILE",
+        "GDAL_HTTP_UNSAFESSL",
+    )):
+        return
+
+    bundle = None
+    try:
+        import certifi
+        bundle = certifi.where()
+    except Exception:
+        for p in ("/etc/ssl/certs/ca-certificates.crt",
+                  "/etc/pki/tls/certs/ca-bundle.crt",
+                  "/etc/ssl/cert.pem"):
+            if os.path.exists(p):
+                bundle = p
+                break
+
+    if bundle and os.path.exists(bundle):
+        os.environ.setdefault("CURL_CA_BUNDLE", bundle)
+        os.environ.setdefault("GDAL_CURL_CA_BUNDLE", bundle)
+        os.environ.setdefault("SSL_CERT_FILE", bundle)
+
+
+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():
+    # RUMI_LIB beats everything :D, then the bundled wheel copy, then the OS path.
+    env_path = os.environ.get("RUMI_LIB")
+    candidate = env_path or _bundled_lib() or ctypes.util.find_library("rumi")
+    if candidate is None:
+        raise OSError(
+            "librumi not found. Install it or set RUMI_LIB to its path."
+        )
+    try:
+        return ffi.dlopen(candidate)
+    except OSError as exc:
+        raise OSError(
+            f"failed to load librumi from {candidate!r}: {exc}. "
+            "It links GDAL; put a compatible libgdal on the loader path."
+        ) from exc
+
+
+_ensure_ca_bundle()
+lib = _load_lib()
+
+
+_STATUS_TO_EXC = {
+    lib.RUMI_ERR_INVALID:     ValueError,
+    lib.RUMI_ERR_IO:          IOError,
+    lib.RUMI_ERR_PARSE:       ValueError,
+    lib.RUMI_ERR_FORMAT:      ValueError,
+    lib.RUMI_ERR_DECODE:      IOError,
+    lib.RUMI_ERR_OOM:         MemoryError,
+    lib.RUMI_ERR_UNSUPPORTED: NotImplementedError,
+    lib.RUMI_ERR_INTERNAL:    RuntimeError,
+}
+
+
+def _check(rc):
+    if rc == lib.RUMI_OK:
+        return
+    err = lib.rumi_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)

rumi_eo-0.8.3/rumi/_read.py

@@ -0,0 +1,159 @@
+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)
+
+
+# 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.rumi_index_file(_enc(path), blob_out, size_out))
+    try:
+        return bytes(ffi.buffer(blob_out[0], size_out[0]))
+    finally:
+        lib.rumi_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("rumi_layout*")
+    _check(lib.rumi_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.rumi_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("rumi_layout*")
+    _check(lib.rumi_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("rumi_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.rumi_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)

rumi_eo-0.8.3/rumi/_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="rumi 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"rumi{next(_counter)}"
+    return (f'<div class="rumi-repr" id="{uid}"><style>'
+            f'{_CSS.replace("#ID", f"#{uid}")}</style>{inner}</div>')
+
+
+def text(f):
+    if not f["ok"]:
+        return "<rumi.Spec (unreadable)>"
+    tw, tl = f["tile"]
+    return "\n".join([
+        f"<rumi.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">rumi.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">rumi.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>')

rumi_eo-0.8.3/rumi/_spec.py

@@ -0,0 +1,54 @@
+import numpy as np
+
+from . import _repr
+from ._dtype import np_dtype
+from ._ffi import _check, ffi, lib
+
+
+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("rumi_spec**")
+        _check(lib.rumi_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.rumi_spec_destroy)
+
+        header = ffi.new("rumi_header*")
+        _check(lib.rumi_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": "OpenZL",
+            }
+        except Exception:
+            return {"ok": False}
+
+    def __repr__(self) -> str:
+        return _repr.text(self._facts())
+
+    def _repr_html_(self) -> str:
+        return _repr.html_(self._facts())

rumi_eo-0.8.3/rumi/_write.py

@@ -0,0 +1,215 @@
+import struct
+from collections.abc import Iterable
+from dataclasses import dataclass
+
+import numpy as np
+
+from ._dtype import sample_encoding
+
+
+@dataclass(frozen=True)
+class Layout:
+    """Grid and dtype of a tiled image. The header blob minus the bits the
+    writer fills in, base_tiles_offset and the per-tile byte counts."""
+
+    image_width: int
+    image_length: int
+    tile_width: int
+    tile_length: int
+    samples_per_pixel: int
+    dtype: np.dtype
+
+    @property
+    def sample_format(self) -> int:
+        return sample_encoding(self.dtype)[0]
+
+    @property
+    def bits_per_sample(self) -> int:
+        return sample_encoding(self.dtype)[1]
+
+    @property
+    def tiles_across(self) -> int:
+        return -(-self.image_width // self.tile_width)
+
+    @property
+    def tiles_down(self) -> int:
+        return -(-self.image_length // self.tile_length)
+
+    @property
+    def n_tiles(self) -> int:
+        return self.tiles_across * self.tiles_down * self.samples_per_pixel
+
+
+def tile(arr: np.ndarray, tile: int = 512) -> tuple[np.ndarray, Layout]:
+    if arr.ndim != 3:
+        raise ValueError(f"expected (B, Y, X), got shape {arr.shape}")
+    if tile < 16 or tile % 16:
+        raise ValueError(f"tile must be a positive multiple of 16, got {tile}")
+    sample_encoding(arr.dtype)  # reject unsupported dtype early
+
+    B, Y, X = arr.shape
+    T = tile
+    across = -(-X // T)
+    down = -(-Y // T)
+
+    pad_y, pad_x = down * T - Y, across * T - X
+    if pad_y or pad_x:
+        arr = np.pad(arr, ((0, 0), (0, pad_y), (0, pad_x)))
+
+    # split Y into (down, T) and X into (across, T), then put samples innermost
+    g = arr.reshape(B, down, T, across, T).transpose(1, 3, 0, 2, 4)
+    chunks = g.reshape(down * across * B, T, T)
+
+    return chunks, Layout(X, Y, T, T, B, arr.dtype)
+
+
+# BigTIFF assembler. The layout is fixed so every offset is known before a byte
+# is written: header, then the single IFD and its out-of-line arrays, then the
+# tile payloads in tile order with nothing between them. Every entry carries its
+# packed payload, so the CRS tags that come from C embed verbatim.
+
+_LE = "<"
+_SHORT, _LONG, _LONG8, _DOUBLE, _ASCII = 3, 4, 16, 12, 2
+_TYPE_FMT = {_SHORT: "H", _LONG: "I", _LONG8: "Q", _DOUBLE: "d"}
+_TYPE_SIZE = {_SHORT: 2, _LONG: 4, _LONG8: 8, _DOUBLE: 8, _ASCII: 1}
+
+_COMPRESSION_OPENZL = 60000
+_PHOTOMETRIC_MINISBLACK = 1
+_PLANARCONFIG_SEPARATE = 2
+_PREDICTOR_NONE = 1
+
+_TILE_OFFSETS = 324
+
+
+def _pack(type_, values):
+    return struct.pack(_LE + _TYPE_FMT[type_] * len(values), *values)
+
+
+def _entry(tag, type_, values):
+    return (tag, type_, len(values), _pack(type_, values))
+
+
+def _crs_geokeys(crs, pixel_is_point):
+    from ._ffi import _check, ffi, lib
+
+    s = (f"EPSG:{crs}" if isinstance(crs, int) else str(crs)).encode("utf-8")
+    out = [(ffi.new("unsigned char**"), ffi.new("size_t*")) for _ in range(3)]
+    _check(lib.rumi_geokeys(
+        s, 1 if pixel_is_point else 0,
+        out[0][0], out[0][1], out[1][0], out[1][1], out[2][0], out[2][1]))
+    try:
+        return tuple(bytes(ffi.buffer(p[0], n[0])) if n[0] else b""
+                     for p, n in out)
+    finally:
+        for p, n in out:
+            if n[0]:
+                lib.rumi_free(p[0])
+
+
+def _geo_entries(transform, crs, pixel_is_point):
+    if transform is None and crs is None:
+        return []
+    if (transform is None) != (crs is None):
+        raise ValueError("transform and crs must be given together")
+
+    a, b, c, d, e, f = (float(v) for v in tuple(transform)[:6])
+    out = []
+    # north up, no rotation: pixel scale + tiepoint, exactly what GDAL emits.
+    if b == 0.0 and d == 0.0:
+        out.append(_entry(33550, _DOUBLE, [a, -e, 0.0]))
+        out.append(_entry(33922, _DOUBLE, [0.0, 0.0, 0.0, c, f, 0.0]))
+    else:
+        out.append(_entry(34264, _DOUBLE, [a, b, 0.0, c,
+                                           d, e, 0.0, f,
+                                           0.0, 0.0, 0.0, 0.0,
+                                           0.0, 0.0, 0.0, 1.0]))
+
+    dir_b, dbl_b, ascii_b = _crs_geokeys(crs, pixel_is_point)
+    out.append((34735, _SHORT, len(dir_b) // 2, dir_b))
+    if dbl_b:
+        out.append((34736, _DOUBLE, len(dbl_b) // 8, dbl_b))
+    if ascii_b:
+        out.append((34737, _ASCII, len(ascii_b), ascii_b))
+    return out
+
+
+def write(path, frames: Iterable[bytes], layout: Layout, *,
+          transform=None, crs=None, pixel_is_point=False) -> None:
+    frames = [memoryview(f) for f in frames]
+    if len(frames) != layout.n_tiles:
+        raise ValueError(f"expected {layout.n_tiles} frames, got {len(frames)}")
+    counts = [f.nbytes for f in frames]
+    if any(c == 0 for c in counts):
+        raise ValueError("empty tile payload, rumi forbids sparse tiles")
+
+    B = layout.samples_per_pixel
+    sf, bps = layout.sample_format, layout.bits_per_sample
+
+    # rumi lays the tile bytes out tile-interleaved (samples innermost).
+    tpp = layout.tiles_across * layout.tiles_down
+    pm_order = [pos * B + b for b in range(B) for pos in range(tpp)]
+    counts_pm = [counts[i] for i in pm_order]
+
+    # (tag, type, count, packed) in ascending tag order. TileOffsets packs once
+    # the data offset is known. Geo tags, if any, append above 339.
+    entries = [
+        _entry(256, _LONG,  [layout.image_width]),
+        _entry(257, _LONG,  [layout.image_length]),
+        _entry(258, _SHORT, [bps] * B),
+        _entry(259, _SHORT, [_COMPRESSION_OPENZL]),
+        _entry(262, _SHORT, [_PHOTOMETRIC_MINISBLACK]),
+        _entry(277, _SHORT, [B]),
+        _entry(284, _SHORT, [_PLANARCONFIG_SEPARATE]),
+        _entry(317, _SHORT, [_PREDICTOR_NONE]),
+        _entry(322, _SHORT, [layout.tile_width]),
+        _entry(323, _SHORT, [layout.tile_length]),
+        (_TILE_OFFSETS, _LONG8, len(frames), None),
+        _entry(325, _LONG,  counts_pm),
+        _entry(339, _SHORT, [sf] * B),
+    ]
+    entries += _geo_entries(transform, crs, pixel_is_point)
+
+    ifd_offset = 16
+    ifd_size = 8 + 20 * len(entries) + 8
+    cursor = ifd_offset + ifd_size
+
+    ext_offset = {}
+    for tag, type_, count, _ in entries:
+        size = _TYPE_SIZE[type_] * count
+        if size > 8:
+            ext_offset[tag] = cursor
+            cursor += size + (size & 1)
+    base_tiles_offset = cursor
+
+    off = base_tiles_offset
+    tile_offsets = []
+    for c in counts:
+        tile_offsets.append(off)
+        off += c
+    offsets_pm = [tile_offsets[i] for i in pm_order]
+
+    buf = bytearray()
+    buf += struct.pack(_LE + "HHHH", 0x4949, 43, 8, 0)
+    buf += struct.pack(_LE + "Q", ifd_offset)
+    buf += struct.pack(_LE + "Q", len(entries))
+
+    ext = bytearray()
+    for tag, type_, count, packed in entries:
+        if tag == _TILE_OFFSETS:
+            packed = _pack(_LONG8, offsets_pm)
+        buf += struct.pack(_LE + "HHQ", tag, type_, count)
+        if len(packed) <= 8:
+            buf += packed.ljust(8, b"\x00")
+        else:
+            buf += struct.pack(_LE + "Q", ext_offset[tag])
+            ext += packed
+            if len(packed) & 1:
+                ext += b"\x00"
+    buf += struct.pack(_LE + "Q", 0)  # one IFD, no next
+    buf += ext
+
+    assert len(buf) == base_tiles_offset
+    with open(path, "wb") as fh:
+        fh.write(buf)
+        for f in frames:
+            fh.write(f)