macrostrat.raster_index 0.1.0__tar.gz

macrostrat_raster_index-0.1.0/PKG-INFO

@@ -0,0 +1,102 @@
+Metadata-Version: 2.3
+Name: macrostrat.raster_index
+Version: 0.1.0
+Summary: An index of cloud-optimized raster datasets, for mosaicked tile serving
+Author: Daven Quinn
+Author-email: Daven Quinn <dev@davenquinn.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: macrostrat-database>=4.5,<5
+Requires-Dist: macrostrat-utils>=1.3.3,<2
+Requires-Dist: sqlalchemy>=2.0.18,<3
+Requires-Dist: rio-tiler>=8,<9
+Requires-Dist: rasterio>=1.4,<2
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.7,<3
+Requires-Dist: typer>=0.12,<0.27
+Requires-Dist: rich>=13,<16
+Requires-Dist: boto3>=1.28.50,<2 ; extra == 's3'
+Requires-Python: >=3.11, <4
+Project-URL: Repository, https://github.com/UW-Macrostrat/python-libraries
+Project-URL: Documentation, https://github.com/UW-Macrostrat/python-libraries/tree/main/raster-index#readme
+Provides-Extra: s3
+Description-Content-Type: text/markdown
+
+# `macrostrat.raster_index`
+
+An index of cloud-optimized rasters (COGs), grouped into named **layers** that a
+tile server can serve as single mosaics.
+
+Nothing here stores pixels. A row in `raster_layers.raster` is a reference to a
+COG in object storage plus the metadata needed to decide whether reading it is
+worthwhile for a given tile: its footprint, its native zoom range, and its data
+type. The schema name is `raster_layers` rather than `raster`/`rasters` to stay
+clear of PostGIS Raster's vocabulary.
+
+Serving these layers is [`macrostrat.raster_layers`](https://github.com/UW-Macrostrat/python-libraries/tree/main/raster-layers).
+
+## Usage
+
+```python
+from macrostrat.raster_index import RasterIndex, LayerDefinition
+
+index = RasterIndex("postgresql://localhost:5432/macrostrat")
+index.create_schema()  # or apply `schema_files()` through your own system
+
+index.register_layer(
+    LayerDefinition(slug="emit-minerals", name="EMIT mineral maps", maxzoom=14)
+)
+index.add_raster(
+    "https://storage.example.org/rasters/nevada.tif", layer="emit-minerals"
+)
+
+index.assets_for_tile(x=180, y=411, z=10, layers=["emit-minerals"])
+```
+
+## Schema
+
+`schema_files()` returns the SQL defining the schema, in application order, so a
+host application can fold it into its own schema management rather than calling
+`create_schema()`. Two tables and a few functions:
+
+- `raster_layers.layer` — a named mosaic, and the defaults its rasters inherit
+  (zoom range, rescale range, colormap).
+- `raster_layers.raster` — one COG: `href`, EPSG:4326 `footprint`, zoom range,
+  `dtype`/`nbands`/`nodata`, and the full reader metadata as `info`.
+- `raster_layers.get_rasters(x, y, z, layers[])` — asset selection, ordered by
+  layer priority then resolution. The core of the whole package.
+- `raster_layers.should_generate_tile(...)` — whether any asset actually resolves
+  at this zoom, for cache warmers and render short-circuits.
+- `raster_layers.layer_footprints(layers[])` — footprints as GeoJSON features.
+
+## CLI
+
+`raster-index` reads `RASTER_INDEX_DATABASE` (or `DATABASE_URL`):
+
+```sh
+raster-index define-layer emit-minerals --name "EMIT mineral maps"
+raster-index scan https://storage.example.org/remote-sensing-data/emit-mineral-maps/ \
+  --layer emit-minerals
+raster-index set-colormap emit-minerals --from https://storage.example.org/.../nevada.tif
+raster-index assets 10 180 411 --layer emit-minerals
+```
+
+The connection is a parameter of the app itself: `--database`, or those
+environment variables. A host application that already knows its own connection
+(Macrostrat mounts these as `macrostrat raster`) calls
+`set_default_connection(url_or_callable)` once, and its users never pass
+`--database` — though it still works, and still wins. Scanning object stores
+needs the `s3` extra (boto3), whichever URL form you use — an `https://` bucket
+URL is *rewritten* into an endpoint/bucket/prefix and listed through the same
+S3 API, rather than being a second code path.
+
+## Known limitations
+
+- Footprints are bounding boxes, so rasters crossing the antimeridian are
+  indexed incorrectly. The column is typed `geometry`, not `polygon`, so a
+  mask-derived footprint can replace them without a migration.
+- WebMercatorQuad only. Alternate tile grids (and non-Earth bodies, as in
+  [mars-tiler](https://github.com/davenquinn/mars-tiler)) would need a per-grid
+  bounds table.

macrostrat_raster_index-0.1.0/README.md

@@ -0,0 +1,76 @@
+# `macrostrat.raster_index`
+
+An index of cloud-optimized rasters (COGs), grouped into named **layers** that a
+tile server can serve as single mosaics.
+
+Nothing here stores pixels. A row in `raster_layers.raster` is a reference to a
+COG in object storage plus the metadata needed to decide whether reading it is
+worthwhile for a given tile: its footprint, its native zoom range, and its data
+type. The schema name is `raster_layers` rather than `raster`/`rasters` to stay
+clear of PostGIS Raster's vocabulary.
+
+Serving these layers is [`macrostrat.raster_layers`](https://github.com/UW-Macrostrat/python-libraries/tree/main/raster-layers).
+
+## Usage
+
+```python
+from macrostrat.raster_index import RasterIndex, LayerDefinition
+
+index = RasterIndex("postgresql://localhost:5432/macrostrat")
+index.create_schema()  # or apply `schema_files()` through your own system
+
+index.register_layer(
+    LayerDefinition(slug="emit-minerals", name="EMIT mineral maps", maxzoom=14)
+)
+index.add_raster(
+    "https://storage.example.org/rasters/nevada.tif", layer="emit-minerals"
+)
+
+index.assets_for_tile(x=180, y=411, z=10, layers=["emit-minerals"])
+```
+
+## Schema
+
+`schema_files()` returns the SQL defining the schema, in application order, so a
+host application can fold it into its own schema management rather than calling
+`create_schema()`. Two tables and a few functions:
+
+- `raster_layers.layer` — a named mosaic, and the defaults its rasters inherit
+  (zoom range, rescale range, colormap).
+- `raster_layers.raster` — one COG: `href`, EPSG:4326 `footprint`, zoom range,
+  `dtype`/`nbands`/`nodata`, and the full reader metadata as `info`.
+- `raster_layers.get_rasters(x, y, z, layers[])` — asset selection, ordered by
+  layer priority then resolution. The core of the whole package.
+- `raster_layers.should_generate_tile(...)` — whether any asset actually resolves
+  at this zoom, for cache warmers and render short-circuits.
+- `raster_layers.layer_footprints(layers[])` — footprints as GeoJSON features.
+
+## CLI
+
+`raster-index` reads `RASTER_INDEX_DATABASE` (or `DATABASE_URL`):
+
+```sh
+raster-index define-layer emit-minerals --name "EMIT mineral maps"
+raster-index scan https://storage.example.org/remote-sensing-data/emit-mineral-maps/ \
+  --layer emit-minerals
+raster-index set-colormap emit-minerals --from https://storage.example.org/.../nevada.tif
+raster-index assets 10 180 411 --layer emit-minerals
+```
+
+The connection is a parameter of the app itself: `--database`, or those
+environment variables. A host application that already knows its own connection
+(Macrostrat mounts these as `macrostrat raster`) calls
+`set_default_connection(url_or_callable)` once, and its users never pass
+`--database` — though it still works, and still wins. Scanning object stores
+needs the `s3` extra (boto3), whichever URL form you use — an `https://` bucket
+URL is *rewritten* into an endpoint/bucket/prefix and listed through the same
+S3 API, rather than being a second code path.
+
+## Known limitations
+
+- Footprints are bounding boxes, so rasters crossing the antimeridian are
+  indexed incorrectly. The column is typed `geometry`, not `polygon`, so a
+  mask-derived footprint can replace them without a migration.
+- WebMercatorQuad only. Alternate tile grids (and non-Earth bodies, as in
+  [mars-tiler](https://github.com/davenquinn/mars-tiler)) would need a per-grid
+  bounds table.

macrostrat_raster_index-0.1.0/macrostrat/raster_index/__init__.py

@@ -0,0 +1,26 @@
+"""An index of cloud-optimized rasters, for mosaicked tile serving.
+
+Rasters live in object storage; this package records *where* they are, *what*
+they cover, and *which named layer* they belong to, so a tile server can answer
+"which files do I read for this tile?" with a single spatial query.
+
+Serving is a separate concern, handled by `macrostrat.raster_layers`.
+"""
+
+from .defs import LayerDefinition, RasterAsset, RasterInfo
+from .footprints import get_raster_info
+from .index import RasterIndex, schema_files
+from .scan import BucketPrefix, RasterObject, parse_bucket_url, scan_prefix
+
+__all__ = [
+    "RasterIndex",
+    "schema_files",
+    "get_raster_info",
+    "scan_prefix",
+    "RasterObject",
+    "BucketPrefix",
+    "parse_bucket_url",
+    "RasterAsset",
+    "RasterInfo",
+    "LayerDefinition",
+]

macrostrat_raster_index-0.1.0/macrostrat/raster_index/cli.py

@@ -0,0 +1,326 @@
+"""Command-line surface for the raster index.
+
+A plain module-level Typer app. The database is a parameter of the app itself —
+`--database`, or the `RASTER_INDEX_DATABASE`/`DATABASE_URL` environment
+variables — resolved once in the callback and handed to commands through the
+Click context.
+
+A host application that already knows its own connection (Macrostrat mounts
+these commands as `macrostrat raster`) calls `set_default_connection()` to supply
+it, and its users never have to pass `--database`.
+"""
+
+from dataclasses import dataclass
+from typing import Callable, Optional, Union
+
+from rich import print
+from rich.table import Table
+from typer import Argument, BadParameter, Context, Exit, Option, Typer
+
+from .defs import LayerDefinition
+from .index import Connectable, RasterIndex
+from .scan import scan_prefix
+
+__all__ = ["cli", "set_default_connection", "index_for"]
+
+# A connection, or something that produces one when a command actually needs it.
+ConnectionSource = Union[Connectable, Callable[[], Connectable]]
+
+# Set by a host application to supply its own database. Lower priority than an
+# explicit `--database` so a user can always point the CLI somewhere else.
+_default_connection: Optional[ConnectionSource] = None
+
+
+def set_default_connection(source: Optional[ConnectionSource]) -> None:
+    """Supply the connection to use when `--database` isn't given.
+
+    Accepts a URL, an engine or `Database`, or a zero-argument callable
+    returning one — a callable defers reading the host's configuration until a
+    command actually runs.
+    """
+    global _default_connection
+    _default_connection = source
+
+
+@dataclass
+class RasterIndexContext:
+    """CLI state, attached to the Click context by the callback.
+
+    The index is built on first use rather than in the callback, so `--help` and
+    argument errors don't require a working database.
+    """
+
+    connection: Optional[ConnectionSource] = None
+    _index: Optional[RasterIndex] = None
+
+    @property
+    def index(self) -> RasterIndex:
+        if self._index is not None:
+            return self._index
+
+        source = self.connection
+        if callable(source) and not isinstance(source, str):
+            source = source()
+        if source is None:
+            raise BadParameter(
+                "No database configured. Pass --database, or set "
+                "RASTER_INDEX_DATABASE (or DATABASE_URL).",
+                param_hint="--database",
+            )
+
+        self._index = RasterIndex(source)
+        return self._index
+
+
+def index_for(ctx: Context, *, require_schema: bool = True) -> RasterIndex:
+    """The index for the running command.
+
+    The schema check turns the common first-run mistake — a database that's
+    never been provisioned — into a pointed message rather than an
+    `UndefinedTable` traceback from whichever query happened to run first.
+    """
+    index = ctx.find_object(RasterIndexContext).index
+    if require_schema and not index.schema_exists():
+        print(
+            "[yellow]No [bold]raster_layers[/bold] schema in this database.\n"
+            "[dim]Apply it through your schema-management system, or run "
+            "`create-schema` for a scratch database."
+        )
+        raise Exit(1)
+    return index
+
+
+cli = Typer(no_args_is_help=True, short_help="Manage indexed raster datasets")
+
+
+@cli.callback()
+def main(
+    ctx: Context,
+    database: Optional[str] = Option(
+        None,
+        "--database",
+        envvar=["RASTER_INDEX_DATABASE", "DATABASE_URL"],
+        help="PostgreSQL connection string for the raster index",
+        show_default=False,
+    ),
+):
+    """Manage indexed raster datasets."""
+    ctx.obj = RasterIndexContext(connection=database or _default_connection)
+
+
+@cli.command(name="create-schema")
+def create_schema(ctx: Context):
+    """Apply the `raster_layers` schema directly.
+
+    For scratch databases. Managed deployments should build the schema through
+    their own schema-management system.
+    """
+    index_for(ctx, require_schema=False).create_schema()
+    print("[green]Created [bold]raster_layers[/bold] schema")
+
+
+@cli.command(name="layers")
+def list_layers(ctx: Context):
+    """List indexed raster layers."""
+    index = index_for(ctx)
+
+    counts = {}
+    for raster in index.rasters():
+        counts[raster["layer"]] = counts.get(raster["layer"], 0) + 1
+
+    table = Table("Layer", "Name", "Rasters", "Zooms", box=None)
+    for layer in index.layers():
+        table.add_row(
+            layer.slug,
+            layer.name or "",
+            str(counts.get(layer.slug, 0)),
+            _zoom_range(layer.minzoom, layer.maxzoom),
+        )
+    print(table)
+
+
+@cli.command(name="rasters")
+def list_rasters(ctx: Context, layer: Optional[str] = Argument(None)):
+    """List indexed rasters, optionally within a single layer."""
+    table = Table("Layer", "Raster", "Zooms", "Type", "Href", box=None)
+    for raster in index_for(ctx).rasters(layer):
+        table.add_row(
+            raster["layer"],
+            raster["slug"],
+            _zoom_range(raster["minzoom"], raster["maxzoom"]),
+            f"{raster['dtype']}×{raster['nbands']}",
+            raster["href"],
+        )
+    print(table)
+
+
+@cli.command(name="define-layer")
+def define_layer(
+    ctx: Context,
+    slug: str,
+    name: Optional[str] = Option(None),
+    description: Optional[str] = Option(None),
+    minzoom: Optional[int] = Option(None),
+    maxzoom: Optional[int] = Option(None),
+):
+    """Create or update a layer definition."""
+    index_for(ctx).register_layer(
+        LayerDefinition(
+            slug=slug,
+            name=name,
+            description=description,
+            minzoom=minzoom,
+            maxzoom=maxzoom,
+        )
+    )
+    print(f"[green]Defined layer [bold]{slug}[/bold]")
+
+
+@cli.command(name="set-colormap")
+def set_colormap(
+    ctx: Context,
+    layer: str,
+    source: str = Option(
+        ...,
+        "--from",
+        help="Raster whose embedded palette should become the layer's colormap",
+    ),
+):
+    """Copy a raster's embedded color table onto its layer.
+
+    Categorical rasters (classification maps) carry their palette in the file.
+    Serving them means having that palette at render time, which is what the
+    layer's colormap is for.
+    """
+    from .footprints import get_raster_info
+
+    colormap = get_raster_info(source).colormap
+    if not colormap:
+        print(f"[yellow]{source} has no embedded color table")
+        raise Exit(1)
+
+    index = index_for(ctx)
+    existing = {l.slug: l for l in index.layers()}
+    if layer not in existing:
+        print(f"[yellow]Layer [bold]{layer}[/bold] is not defined")
+        raise Exit(1)
+
+    # Stored as JSON, so keys become strings and tuples become lists; the
+    # serving side normalizes them back.
+    index.register_layer(
+        existing[layer],
+        colormap={str(k): list(v) for k, v in colormap.items()},
+    )
+    print(f"[green]Set a {len(colormap)}-entry colormap on [bold]{layer}[/bold]")
+
+
+@cli.command(name="add")
+def add(
+    ctx: Context,
+    hrefs: list[str] = Argument(..., help="Raster URLs or paths"),
+    layer: str = Option(..., "--layer", "-l", help="Layer to add rasters to"),
+):
+    """Register rasters in a layer, reading footprints and zoom ranges."""
+    results = index_for(ctx).add_rasters(hrefs, layer)
+    print(f"[green]Registered {len(results)}/{len(hrefs)} rasters in {layer}")
+
+
+@cli.command(name="scan")
+def scan(
+    ctx: Context,
+    url: str = Argument(
+        ...,
+        help="Bucket prefix, e.g. https://storage.example.org/bucket/prefix/",
+    ),
+    layer: str = Option(..., "--layer", "-l", help="Layer to add rasters to"),
+    dry_run: bool = Option(False, help="Show what would be registered"),
+    credentials: bool = Option(False, help="Sign requests with AWS credentials"),
+    endpoint_url: Optional[str] = Option(
+        None, help="S3-compatible endpoint to list against (inferred from https URLs)"
+    ),
+    public_url: Optional[str] = Option(
+        None, help="Rewrite hrefs onto this origin (inferred from https URLs)"
+    ),
+):
+    """Register every raster under a bucket prefix.
+
+    An `https://` URL — the one you'd paste into a browser — needs nothing else:
+    its origin is the endpoint, its first path segment the bucket, and the
+    rasters are indexed at that same origin. Use `s3://` (with `--endpoint-url`)
+    for buckets whose location isn't implied by a public URL. Listing is
+    unsigned unless `--credentials` is given.
+    """
+    objects = list(
+        scan_prefix(
+            url,
+            endpoint_url=endpoint_url,
+            public_url=public_url,
+            credentials=credentials,
+        )
+    )
+    if not objects:
+        print(f"[yellow]No rasters found under {url}")
+        return
+
+    if dry_run:
+        for obj in objects:
+            print(f"{obj.href} [dim]({obj.size / 1e6:.1f} MB)")
+        print(f"[dim]{len(objects)} rasters (dry run — nothing registered)")
+        return
+
+    results = index_for(ctx).add_rasters([o.href for o in objects], layer)
+    print(f"[green]Registered {len(results)}/{len(objects)} rasters in {layer}")
+
+
+@cli.command(name="remove")
+def remove(ctx: Context, href: str):
+    """Remove a raster from the index."""
+    count = index_for(ctx).remove_raster(href)
+    if count:
+        print(f"[green]Removed {href}")
+    else:
+        print(f"[yellow]{href} is not in the index")
+
+
+@cli.command(name="info")
+def info(href: str):
+    """Show the metadata that would be indexed for a raster.
+
+    Reads the raster directly, so it needs no database.
+    """
+    from .footprints import get_raster_info
+
+    print(get_raster_info(href).model_dump(exclude={"metadata"}))
+
+
+@cli.command(name="assets")
+def assets(
+    ctx: Context,
+    z: int,
+    x: int,
+    y: int,
+    layers: list[str] = Option(..., "--layer", "-l"),
+):
+    """Show which rasters would be read for a tile."""
+    index = index_for(ctx)
+
+    table = Table("Layer", "Raster", "Zooms", "Overscaled", box=None)
+    for asset in index.assets_for_tile(x, y, z, layers):
+        table.add_row(
+            asset.layer,
+            asset.slug or "",
+            _zoom_range(asset.minzoom, asset.maxzoom),
+            "yes" if asset.overscaled else "",
+        )
+    print(table)
+
+    if not index.should_generate_tile(x, y, z, layers):
+        print("[yellow]No usable assets — this tile should not be generated")
+
+
+def _zoom_range(minzoom, maxzoom) -> str:
+    if minzoom is None and maxzoom is None:
+        return ""
+    low = minzoom if minzoom is not None else "?"
+    high = maxzoom if maxzoom is not None else "?"
+    return f"{low}–{high}"

macrostrat_raster_index-0.1.0/macrostrat/raster_index/defs.py

@@ -0,0 +1,60 @@
+"""Types shared between indexing and serving.
+
+These are the contract between `macrostrat.raster_index` and
+`macrostrat.raster_layers`: the serving side never touches the tables directly,
+it consumes `RasterAsset`s.
+"""
+
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field
+
+__all__ = ["RasterAsset", "RasterInfo", "LayerDefinition"]
+
+
+class RasterAsset(BaseModel):
+    """A raster selected for a specific tile.
+
+    Produced by `raster_layers.get_rasters`; consumed by the mosaic reader.
+    """
+
+    href: str
+    layer: str
+    slug: Optional[str] = None
+    minzoom: Optional[int] = None
+    maxzoom: Optional[int] = None
+    rescale_range: Optional[list[float]] = None
+    # True when the requested tile is zoomed in past what this raster resolves.
+    overscaled: bool = False
+
+
+class RasterInfo(BaseModel):
+    """Metadata derived by opening a raster, before it is written to the index."""
+
+    href: str
+    # Bounding box in EPSG:4326, as (west, south, east, north).
+    bounds: tuple[float, float, float, float]
+    # Footprint as a GeoJSON geometry dict, in EPSG:4326.
+    geometry: dict[str, Any]
+    minzoom: int
+    maxzoom: int
+    dtype: str
+    nbands: int
+    nodata: Optional[float] = None
+    crs: Optional[str] = None
+    # Colormap embedded in the raster itself (a GDAL color table), if any.
+    colormap: Optional[dict[int, tuple[int, int, int, int]]] = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class LayerDefinition(BaseModel):
+    """A named mosaic, and the defaults its rasters inherit."""
+
+    slug: str
+    name: Optional[str] = None
+    description: Optional[str] = None
+    minzoom: Optional[int] = None
+    maxzoom: Optional[int] = None
+    rescale_range: Optional[list[float]] = None
+    colormap: Optional[dict[str, Any]] = None
+    metadata: Optional[dict[str, Any]] = None

macrostrat_raster_index-0.1.0/macrostrat/raster_index/footprints.py

@@ -0,0 +1,94 @@
+"""Derive index metadata by opening a raster.
+
+This is the only place in the package that touches pixels (or, more precisely,
+headers): everything the index stores about a raster comes from here, so
+registering a raster and re-registering it later are guaranteed to agree.
+"""
+
+from typing import Any, Optional
+
+import rasterio
+from rio_tiler.constants import WGS84_CRS
+from rio_tiler.io import Reader
+
+from macrostrat.utils import get_logger
+
+from .defs import RasterInfo
+
+log = get_logger(__name__)
+
+__all__ = ["get_raster_info", "bounds_to_geometry"]
+
+
+def bounds_to_geometry(bounds: tuple[float, float, float, float]) -> dict[str, Any]:
+    """A GeoJSON polygon for a (west, south, east, north) bounding box."""
+    west, south, east, north = bounds
+    return {
+        "type": "Polygon",
+        "coordinates": [
+            [
+                [west, north],
+                [west, south],
+                [east, south],
+                [east, north],
+                [west, north],
+            ]
+        ],
+    }
+
+
+def get_raster_info(href: str, **reader_options) -> RasterInfo:
+    """Open a raster and collect everything the index needs to know about it.
+
+    The footprint is the geographic bounding box. That is enough for asset
+    selection — a false positive costs one wasted read, and rio-tiler masks the
+    result anyway — and it avoids paying for a mask read at registration time.
+    Rasters spanning the antimeridian are the known failure case: their
+    bounding box wraps the wrong way around the globe.
+    """
+    with Reader(href, **reader_options) as src:
+        bounds = tuple(src.get_geographic_bounds(WGS84_CRS))
+        info = src.info()
+        dataset = src.dataset
+
+        crs = _crs_string(src.crs)
+        # rio-tiler normalizes an absent color table to `{}`; keep it as None so
+        # "no colormap" and "empty colormap" don't have to be distinguished
+        # downstream.
+        colormap = src.colormap or None
+
+        return RasterInfo(
+            href=href,
+            bounds=bounds,
+            geometry=bounds_to_geometry(bounds),
+            minzoom=src.minzoom,
+            maxzoom=src.maxzoom,
+            dtype=dataset.meta["dtype"],
+            nbands=dataset.count,
+            nodata=_first_nodata(dataset),
+            crs=crs,
+            colormap=colormap,
+            metadata=info.model_dump(mode="json", exclude={"colormap"}),
+        )
+
+
+def _crs_string(crs: Optional[rasterio.crs.CRS]) -> Optional[str]:
+    if crs is None:
+        return None
+    # Prefer an authority code; fall back to WKT for CRSs PROJ can't name
+    # (planetary bodies, custom local grids).
+    try:
+        epsg = crs.to_epsg()
+    except Exception:  # pragma: no cover - PROJ can raise on exotic CRSs
+        epsg = None
+    if epsg is not None:
+        return f"EPSG:{epsg}"
+    return crs.to_string()
+
+
+def _first_nodata(dataset) -> Optional[float]:
+    """The dataset's nodata value, if all bands agree on one."""
+    values = {v for v in dataset.nodatavals if v is not None}
+    if len(values) != 1:
+        return None
+    return float(values.pop())