coglite 0.1.0__py3-none-any.whl

coglite/__init__.py

@@ -0,0 +1,58 @@
+"""coglite: read Cloud-Optimized GeoTIFFs over HTTP(S) or from local files without GDAL.
+
+>>> import coglite
+>>> cog = coglite.open("https://example.com/data/cog.tif")   # doctest: +SKIP
+>>> cog.profile, cog.bounds, cog.crs_epsg                    # doctest: +SKIP
+>>> arr = cog.read(window=(0, 0, 512, 512), bands=[1, 2, 3])  # doctest: +SKIP
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .codecs import available_codecs
+from .cog import COG, Level, RasterResult, Window, open
+from .errors import (
+    CodecError,
+    COGLiteError,
+    CRSError,
+    RangeRequestError,
+    TIFFError,
+    UnsupportedError,
+)
+from .geo import Affine
+from .io import (
+    BytesReader,
+    CallableReader,
+    FileReader,
+    HTTPReader,
+    RangeReader,
+    ReaderStats,
+    register_scheme,
+)
+from .validate import ValidationReport
+
+__all__ = [
+    "__version__",
+    "open",
+    "COG",
+    "Window",
+    "Level",
+    "RasterResult",
+    "Affine",
+    "ValidationReport",
+    "RangeReader",
+    "HTTPReader",
+    "FileReader",
+    "BytesReader",
+    "CallableReader",
+    "ReaderStats",
+    "register_scheme",
+    "available_codecs",
+    "COGLiteError",
+    "TIFFError",
+    "UnsupportedError",
+    "CodecError",
+    "RangeRequestError",
+    "CRSError",
+]

coglite/cli.py

@@ -0,0 +1,152 @@
+"""Command line interface: ``coglite info | read | validate``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any, List, Optional, Sequence
+
+import numpy as np
+
+from . import __version__
+from .cog import COG, Window, open
+from .errors import COGLiteError
+from .png import write_png
+
+
+def _open(args: argparse.Namespace) -> COG:
+    headers = {}
+    for h in args.header or []:
+        if ":" not in h:
+            raise SystemExit(f"--header expects 'Name: value', got {h!r}")
+        k, v = h.split(":", 1)
+        headers[k.strip()] = v.strip()
+    return open(args.source, headers=headers or None, timeout=args.timeout)
+
+
+def _bands(text: Optional[str]) -> Optional[List[int]]:
+    if not text:
+        return None
+    return [int(b) for b in text.split(",") if b.strip()]
+
+
+def _json_default(o: Any) -> Any:
+    if isinstance(o, (np.integer,)):
+        return int(o)
+    if isinstance(o, (np.floating,)):
+        return float(o)
+    return str(o)
+
+
+def cmd_info(args: argparse.Namespace) -> int:
+    with _open(args) as cog:
+        info = cog.info()
+        if args.json:
+            print(json.dumps(info, indent=2, default=_json_default))
+            return 0
+        print(f"Source:      {info['source']}")
+        print(
+            f"Size:        {info['width']} x {info['height']} pixels, {info['count']} band(s), {info['dtype']}"
+        )
+        print(f"CRS:         EPSG:{info['crs_epsg']}" if info["crs_epsg"] else "CRS:         unknown")
+        print(f"Transform:   {info['transform']}")
+        print(f"Bounds:      {info['bounds']}")
+        nod = "nan" if info["nodata_is_nan"] else info["nodata"]
+        print(f"NoData:      {nod}")
+        print(
+            f"Layout:      {'tiled' if info['tiled'] else 'stripped'} {info['blockxsize']}x{info['blockysize']}, "
+            f"{info['compress']}, predictor {info['predictor']}, interleave {info['interleave']}"
+        )
+        print(f"Format:      {'BigTIFF' if info['bigtiff'] else 'TIFF'}, {info['byteorder']}-endian")
+        print(f"Overviews:   {', '.join(f'{w}x{h}' for w, h in info['overviews']) or 'none'}")
+        print(f"Mask:        {'internal' if info['has_mask'] else 'none'}")
+        if any(s != 1.0 for s in info["scales"]) or any(o != 0.0 for o in info["offsets"]):
+            print(f"Scale/offset: {info['scales']} / {info['offsets']}")
+        st = cog.reader.stats
+        print(f"I/O:         {st.requests} request(s), {st.bytes_fetched} bytes")
+    return 0
+
+
+def cmd_read(args: argparse.Namespace) -> int:
+    out = args.output
+    if not out.lower().endswith((".npy", ".png")):
+        raise SystemExit("--output must end with .npy or .png")
+    with _open(args) as cog:
+        bands = _bands(args.bands)
+        if args.bbox:
+            res = cog.read_bbox(args.bbox, crs=args.crs, max_size=args.max_size, bands=bands, masked=True)
+            data = res.data
+            msg = f"level {res.level}, window {tuple(res.window)}, transform {tuple(res.transform) if res.transform else None}"
+        else:
+            win = Window(*args.window) if args.window else None
+            data = cog.read(win, bands, args.overview, masked=True)
+            msg = f"window {tuple(win) if win else 'full'}, overview {args.overview}"
+        if out.lower().endswith(".npy"):
+            np.save(out, np.ma.getdata(data))
+        else:
+            write_png(out, data)
+        st = cog.reader.stats
+        print(
+            f"wrote {out}: shape {tuple(data.shape)} {data.dtype}; {msg}; "
+            f"{st.requests} request(s), {st.bytes_fetched} bytes"
+        )
+    return 0
+
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    with _open(args) as cog:
+        report = cog.validate()
+    if args.json:
+        print(json.dumps(report.to_dict(), indent=2, default=_json_default))
+    else:
+        print(report)
+    return 0 if report.is_valid else 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="coglite", description="Read Cloud-Optimized GeoTIFFs without GDAL.")
+    p.add_argument("--version", action="version", version=f"coglite {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    def common(sp: argparse.ArgumentParser) -> None:
+        sp.add_argument("source", help="local path or http(s):// URL")
+        sp.add_argument("--timeout", type=float, default=30.0, help="HTTP timeout in seconds")
+        sp.add_argument("--header", action="append", help="extra HTTP header 'Name: value' (repeatable)")
+
+    sp = sub.add_parser("info", help="print the profile of a COG")
+    common(sp)
+    sp.add_argument("--json", action="store_true", help="machine-readable output")
+    sp.set_defaults(func=cmd_info)
+
+    sp = sub.add_parser("read", help="read a bbox or window to .npy or .png")
+    common(sp)
+    g = sp.add_mutually_exclusive_group()
+    g.add_argument("--bbox", type=float, nargs=4, metavar=("LEFT", "BOTTOM", "RIGHT", "TOP"))
+    g.add_argument("--window", type=int, nargs=4, metavar=("COL", "ROW", "WIDTH", "HEIGHT"))
+    sp.add_argument("--crs", default=None, help="CRS of --bbox (default: raster CRS); EPSG:4326/3857 only")
+    sp.add_argument("--max-size", type=int, default=1024, help="longest output side for --bbox")
+    sp.add_argument("--overview", type=int, default=None, help="overview index for --window")
+    sp.add_argument("--bands", default=None, help="comma separated 1-based band list")
+    sp.add_argument("-o", "--output", required=True, help="output .npy or .png file")
+    sp.set_defaults(func=cmd_read)
+
+    sp = sub.add_parser("validate", help="check Cloud-Optimized GeoTIFF layout rules")
+    common(sp)
+    sp.add_argument("--json", action="store_true", help="machine-readable output")
+    sp.set_defaults(func=cmd_validate)
+    return p
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except (COGLiteError, OSError, ValueError, IndexError) as exc:
+        print(f"coglite: error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

coglite/codecs.py

@@ -0,0 +1,290 @@
+"""Decompression codecs and TIFF predictors.
+
+Built in (standard library + numpy only):
+
+* ``1``     no compression
+* ``5``     LZW (pure-Python decoder, TIFF "early change" variant)
+* ``8``     Deflate / zlib (also the obsolete code ``32946``)
+* ``32773`` PackBits
+* ``34925`` LZMA
+
+Optional, through the ``imagecodecs`` package (``pip install coglite[imagecodecs]``):
+
+* ``7``     JPEG
+* ``50000`` ZSTD (also served by the standard library on Python 3.14+)
+* ``50001`` WebP
+* ``34887`` LERC (optionally wrapped in Deflate or ZSTD)
+
+Predictors: ``1`` none, ``2`` horizontal differencing (integers) and ``3``
+floating-point (byte-shuffled differencing).
+"""
+
+from __future__ import annotations
+
+import zlib
+from typing import Any, Callable, Dict, Optional, Sequence, Union
+
+import numpy as np
+
+from .errors import CodecError, TIFFError
+
+__all__ = [
+    "COMPRESSION_NAMES",
+    "lzw_decode",
+    "packbits_decode",
+    "decompress",
+    "is_image_codec",
+    "undo_horizontal_predictor",
+    "undo_float_predictor",
+    "available_codecs",
+]
+
+COMPRESSION_NAMES: Dict[int, str] = {
+    1: "none",
+    5: "lzw",
+    6: "ojpeg",
+    7: "jpeg",
+    8: "deflate",
+    32946: "deflate",
+    32773: "packbits",
+    34887: "lerc",
+    34925: "lzma",
+    50000: "zstd",
+    50001: "webp",
+}
+
+#: Codecs that return an image array instead of a byte stream.
+_IMAGE_CODECS = {7, 50001, 34887}
+
+
+def is_image_codec(compression: int) -> bool:
+    """Return True if the codec decodes straight to pixels (predictors do not apply)."""
+    return compression in _IMAGE_CODECS
+
+
+def _imagecodecs() -> Any:
+    try:
+        import imagecodecs  # type: ignore[import-not-found,import-untyped,unused-ignore]
+    except ImportError:  # pragma: no cover - depends on the environment
+        return None
+    return imagecodecs
+
+
+def available_codecs() -> Dict[str, bool]:
+    """Report which compression schemes can be decoded in this environment."""
+    ic = _imagecodecs()
+    zstd_ok = _zstd_decoder() is not None
+    return {
+        "none": True,
+        "lzw": True,
+        "deflate": True,
+        "packbits": True,
+        "lzma": True,
+        "zstd": zstd_ok,
+        "jpeg": ic is not None,
+        "webp": ic is not None,
+        "lerc": ic is not None,
+    }
+
+
+# --------------------------------------------------------------------------- LZW
+
+
+def lzw_decode(data: bytes) -> bytes:
+    """Decode TIFF LZW data (MSB-first codes, 9-12 bits, early change).
+
+    Raises :class:`~coglite.errors.TIFFError` for corrupt streams and for the
+    obsolete pre-TIFF-6 LSB-first variant.
+    """
+    if len(data) >= 2 and data[0] == 0 and (data[1] & 0x01):
+        raise CodecError("old-style (LSB-first) LZW is not supported")
+    buf = bytes(data) + b"\x00\x00\x00"
+    nbits = len(data) * 8
+    out = bytearray()
+    table: list = [bytes((i,)) for i in range(256)]
+    table.append(b"")  # 256 clear
+    table.append(b"")  # 257 end of information
+    append = table.append
+    bitpos = 0
+    code_len = 9
+    mask = 0x1FF
+    prev: Optional[bytes] = None
+    while bitpos + code_len <= nbits:
+        p = bitpos >> 3
+        word = (buf[p] << 16) | (buf[p + 1] << 8) | buf[p + 2]
+        code = (word >> (24 - (bitpos & 7) - code_len)) & mask
+        bitpos += code_len
+        if code == 257:
+            break
+        if code == 256:
+            del table[258:]
+            code_len = 9
+            mask = 0x1FF
+            prev = None
+            continue
+        if prev is None:
+            if code > 255:
+                raise TIFFError("corrupt LZW stream: first code after clear is not a literal")
+            entry = table[code]
+            out += entry
+            prev = entry
+            continue
+        n = len(table)
+        if code < n:
+            entry = table[code]
+            append(prev + entry[:1])
+        elif code == n:
+            entry = prev + prev[:1]
+            append(entry)
+        else:
+            raise TIFFError(f"corrupt LZW stream: code {code} > table size {n}")
+        out += entry
+        prev = entry
+        if len(table) >= (1 << code_len) - 1 and code_len < 12:
+            code_len += 1
+            mask = (1 << code_len) - 1
+    return bytes(out)
+
+
+# ---------------------------------------------------------------------- PackBits
+
+
+def packbits_decode(data: bytes) -> bytes:
+    """Decode Apple PackBits run-length encoded data."""
+    out = bytearray()
+    i = 0
+    n = len(data)
+    while i < n:
+        h = data[i]
+        i += 1
+        if h < 128:
+            out += data[i : i + h + 1]
+            i += h + 1
+        elif h > 128:
+            if i < n:
+                out += bytes((data[i],)) * (257 - h)
+            i += 1
+        # h == 128 is a no-op
+    return bytes(out)
+
+
+# ---------------------------------------------------------------------- dispatch
+
+
+def _zstd_decoder() -> Optional[Callable[[bytes], bytes]]:
+    try:  # Python 3.14+
+        from compression import zstd
+    except ImportError:
+        pass
+    else:
+        decoder: Callable[[bytes], bytes] = zstd.decompress
+        return decoder
+    ic = _imagecodecs()
+    if ic is not None:
+        return ic.zstd_decode  # type: ignore[no-any-return,unused-ignore]
+    return None
+
+
+def _need_imagecodecs(name: str) -> Any:
+    ic = _imagecodecs()
+    if ic is None:
+        raise CodecError(
+            f"{name} compression needs the optional 'imagecodecs' package: pip install 'coglite[imagecodecs]'"
+        )
+    return ic
+
+
+def _jpeg_colorspaces(photometric: int, planar: int, extrasamples: Sequence[int]) -> tuple:
+    if photometric == 6:  # YCbCr stored, return RGB
+        return 3, 2
+    if photometric == 2 and planar == 1 and not extrasamples:
+        return 2, 2  # RGB stored as RGB, no conversion
+    return None, None
+
+
+def decompress(
+    compression: int,
+    data: bytes,
+    *,
+    jpeg_tables: Optional[bytes] = None,
+    photometric: int = 1,
+    planar: int = 1,
+    extrasamples: Sequence[int] = (),
+    lerc_parameters: Sequence[int] = (),
+) -> Union[bytes, np.ndarray]:
+    """Decompress one tile or strip.
+
+    Byte-stream codecs return ``bytes``; image codecs (JPEG, WebP, LERC)
+    return a numpy array.
+    """
+    if compression == 1:
+        return bytes(data)
+    if compression in (8, 32946):
+        try:
+            return zlib.decompress(data)
+        except zlib.error:
+            # Some writers emit truncated/raw streams; decompressobj is lenient.
+            try:
+                return zlib.decompressobj().decompress(data)
+            except zlib.error as exc:
+                raise TIFFError(f"corrupt Deflate data: {exc}") from exc
+    if compression == 5:
+        return lzw_decode(data)
+    if compression == 32773:
+        return packbits_decode(data)
+    if compression == 34925:
+        import lzma
+
+        return lzma.decompress(data)
+    if compression == 50000:
+        dec = _zstd_decoder()
+        if dec is None:
+            _need_imagecodecs("ZSTD")
+        assert dec is not None
+        return bytes(dec(data))
+    if compression == 7:
+        ic = _need_imagecodecs("JPEG")
+        cs, ocs = _jpeg_colorspaces(photometric, planar, extrasamples)
+        return np.asarray(ic.jpeg_decode(data, tables=jpeg_tables, colorspace=cs, outcolorspace=ocs))
+    if compression == 50001:
+        ic = _need_imagecodecs("WebP")
+        return np.asarray(ic.webp_decode(data))
+    if compression == 34887:
+        ic = _need_imagecodecs("LERC")
+        extra = lerc_parameters[1] if len(lerc_parameters) > 1 else 0
+        if extra == 1:
+            data = zlib.decompress(data)
+        elif extra == 2:
+            data = ic.zstd_decode(data)
+        return np.asarray(ic.lerc_decode(data))
+    name = COMPRESSION_NAMES.get(compression, "unknown")
+    raise CodecError(f"compression {compression} ({name}) is not supported")
+
+
+# -------------------------------------------------------------------- predictors
+
+
+def undo_horizontal_predictor(arr: np.ndarray) -> np.ndarray:
+    """Undo predictor 2 on an array shaped ``(rows, cols, samples)`` (native byte order)."""
+    if arr.dtype.kind == "f":
+        # libtiff differences the raw bit patterns as unsigned integers.
+        as_int = np.ascontiguousarray(arr).view(f"u{arr.dtype.itemsize}")
+        return np.cumsum(as_int, axis=1, dtype=as_int.dtype).view(arr.dtype)
+    return np.cumsum(arr, axis=1, dtype=arr.dtype)
+
+
+def undo_float_predictor(raw: bytes, rows: int, cols: int, samples: int, itemsize: int) -> np.ndarray:
+    """Undo predictor 3 and return float values shaped ``(rows, cols, samples)``.
+
+    The floating-point predictor first splits every row into byte planes (most
+    significant byte first) and then applies byte-wise horizontal differencing
+    with a stride of ``samples``; this function reverses both steps.
+    """
+    nbytes = rows * cols * samples * itemsize
+    buf = np.frombuffer(raw, dtype=np.uint8, count=nbytes)
+    b = buf.reshape(rows, cols * itemsize, samples)
+    b = np.cumsum(b, axis=1, dtype=np.uint8)
+    planes = b.reshape(rows, itemsize, cols * samples)
+    shuffled = np.ascontiguousarray(planes.transpose(0, 2, 1))
+    values = shuffled.view(f">f{itemsize}").reshape(rows, cols, samples)
+    return values.astype(values.dtype.newbyteorder("="))