pyramids-eo 0.1.0__py3-none-any.whl

pyramids_eo/__init__.py

@@ -0,0 +1,33 @@
+"""pyramids-eo — the Earth-observation layer of the pyramids stack.
+
+``pyramids-eo`` is built on top of :mod:`pyramids` (``pyramids-gis``, the generic
+raster/vector engine) and adds the logic that is specific to
+**Earth-observation data**. Where pyramids knows how to *move rasters around*,
+pyramids-eo knows what a pixel *means* for a given instrument or provider: which
+subdataset is which channel, how to calibrate it, how to composite it, how to
+resample a swath — and how to reach signed EO cloud assets. It is scoped by
+*domain* (EO data), not by a restriction on what it may do.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _get_version
+
+from pyramids_eo.earthengine import (
+    EarthEngineCredentials,
+    collection_from_earthengine,
+    from_earthengine,
+)
+
+try:
+    __version__ = _get_version("pyramids-eo")
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+
+__all__ = [
+    "EarthEngineCredentials",
+    "__version__",
+    "collection_from_earthengine",
+    "from_earthengine",
+]

pyramids_eo/composites/__init__.py

@@ -0,0 +1,49 @@
+"""Day/night compositing for EO imagery.
+
+The pyramids-eo day/night composite chain (the `true_color_with_night_ir`
+look), implemented over NumPy + pyramids-gis with no third-party compositing
+dependency. So far:
+
+* `solar_zenith_angle` / `cos_solar_zenith_angle` — per-pixel solar zenith angle
+  (degrees) and its cosine (the `cos_sza` form the readers expect), the geometry
+  the day/night blend keys off.
+* `day_night_blend` / `day_weight` — the SZA-weighted cross-fade of a day and a
+  night image.
+* `alpha_overlay` — the "over" composite of an RGBA foreground on an RGB(A)
+  background.
+* `static_image` — load a georeferenced background image (e.g. Black Marble),
+  caching a remote URL and warping it to a target grid.
+* `true_color` — true-colour RGB from calibrated reflectance bands with a CIMSS
+  synthetic green (no Rayleigh).
+* `night_ir` / `true_color_with_night_ir` — assemble the full day/night image
+  (RGBA IR clouds over city lights, cross-faded against the day image by SZA).
+
+Together these compose the `true_color_with_night_ir` day/night look.
+"""
+
+from __future__ import annotations
+
+from pyramids_eo.composites.background import static_image
+from pyramids_eo.composites.blend import day_night_blend, day_weight
+from pyramids_eo.composites.geometry import (
+    cos_solar_zenith_angle,
+    solar_zenith_angle,
+)
+from pyramids_eo.composites.overlay import alpha_overlay
+from pyramids_eo.composites.true_color import true_color
+from pyramids_eo.composites.true_color_night import (
+    night_ir,
+    true_color_with_night_ir,
+)
+
+__all__ = [
+    "alpha_overlay",
+    "cos_solar_zenith_angle",
+    "day_night_blend",
+    "day_weight",
+    "night_ir",
+    "solar_zenith_angle",
+    "static_image",
+    "true_color",
+    "true_color_with_night_ir",
+]

pyramids_eo/composites/_common.py

@@ -0,0 +1,55 @@
+"""Shared helpers for the compositing primitives."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def _as_array(value: Any) -> np.ndarray:
+    """Return `value` as a float ndarray, reading a pyramids `Dataset` if given.
+
+    Args:
+        value: An ndarray-like, or a pyramids `Dataset` (read via `read_array`).
+
+    Returns:
+        A float ndarray.
+    """
+    if hasattr(value, "read_array"):
+        return np.asarray(value.read_array(), dtype=float)
+    return np.asarray(value, dtype=float)
+
+
+def _wrap_like(out: np.ndarray, *candidates: Any) -> Any:
+    """Wrap `out` in a pyramids `Dataset` cloned from the first Dataset candidate.
+
+    Args:
+        out: The result array to return.
+        *candidates: Inputs to search for a georeferenced template; the first one
+            exposing both `read_array` and `geotransform` supplies the
+            geotransform + CRS.
+
+    Returns:
+        A pyramids `Dataset` carrying the template's geotransform + CRS when a
+        candidate is a `Dataset`, otherwise `out` unchanged (an ndarray).
+    """
+    out = np.asarray(out, dtype=float)
+    template = next(
+        (
+            candidate
+            for candidate in candidates
+            if hasattr(candidate, "read_array") and hasattr(candidate, "geotransform")
+        ),
+        None,
+    )
+    if template is None:
+        return out
+
+    from pyramids.dataset import Dataset
+
+    # Composited data can legitimately hold NaN (masked terminator / gaps), so
+    # declare NaN as the nodata value rather than the default -9999 sentinel.
+    return Dataset.create_from_array(
+        out, geo=template.geotransform, epsg=template.epsg, no_data_value=np.nan
+    )

pyramids_eo/composites/background.py

@@ -0,0 +1,173 @@
+"""Static georeferenced background images for compositing.
+
+`static_image` loads a georeferenced raster (e.g. the NASA **Black Marble** city
+lights that back the night-IR clouds), caching it locally when the source is a
+URL, and optionally warps/crops it to another dataset's grid via pyramids'
+`align`.
+
+It takes a plain local **or** remote path and caches a remote one. A live
+Black Marble mirror is
+`https://eoimages.gsfc.nasa.gov/images/imagerecords/144000/144898/BlackMarble_2016_3km_geo.tif`
+(the older `neo.gsfc.nasa.gov/archive/blackmarble/...` URLs are 404).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import urllib.request
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from pyramids_eo.errors import EOError
+
+#: Default cache directory for downloaded static images.
+_DEFAULT_CACHE = Path.home() / ".cache" / "pyramids-eo"
+#: Default cap on a single cached download (bytes) — guards against disk fill.
+_DEFAULT_MAX_BYTES = 1_000_000_000
+#: Read block size for streamed downloads.
+_BLOCK = 65536
+
+
+def _download(
+    url: str, target: Path, timeout: float, max_bytes: int = _DEFAULT_MAX_BYTES
+) -> None:
+    """Stream `url` to `target`, writing atomically via a `.part` temp file.
+
+    Streams in blocks with a running size cap and removes the `.part` file on any
+    failure, so a partial/oversized download never lingers in the cache.
+
+    Args:
+        url: The http/https source URL.
+        target: Destination path for the downloaded file.
+        timeout: Per-request timeout in seconds.
+        max_bytes: Maximum bytes to accept before aborting (default ~1 GB).
+
+    Raises:
+        EOError: When the download exceeds `max_bytes`.
+    """
+    request = urllib.request.Request(url)
+    part = target.with_name(target.name + ".part")
+    try:
+        total = 0
+        with (
+            urllib.request.urlopen(request, timeout=timeout) as response,  # nosec B310 - scheme restricted to http/https by _resolve_source
+            open(part, "wb") as handle,
+        ):
+            while block := response.read(_BLOCK):
+                total += len(block)
+                if total > max_bytes:
+                    raise EOError(
+                        f"static image exceeds the {max_bytes}-byte download cap: {url}"
+                    )
+                handle.write(block)
+        os.replace(part, target)
+    finally:
+        part.unlink(missing_ok=True)
+
+
+def _cache_path(cache: Path, url: str) -> Path:
+    """Return the cache filename for `url` — a full-URL hash plus its basename.
+
+    Hashing the whole URL avoids collisions between different URLs that share a
+    basename (e.g. `.../2016/BlackMarble.tif` vs `.../2020/BlackMarble.tif`) and
+    handles a URL with an empty path.
+
+    Args:
+        cache: The cache directory.
+        url: The source URL.
+
+    Returns:
+        The path the download is cached at.
+    """
+    basename = Path(urlparse(url).path).name or "download"
+    digest = hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
+    return cache / f"{digest}-{basename}"
+
+
+def _resolve_source(
+    source: Any,
+    cache_dir: Any,
+    timeout: float,
+    max_bytes: int = _DEFAULT_MAX_BYTES,
+    refresh: bool = False,
+) -> Path:
+    """Return a local path for `source`, downloading + caching a URL if needed.
+
+    Args:
+        source: A local filesystem path (relative or absolute) or an http/https
+            URL.
+        cache_dir: Directory to cache a downloaded URL (default `_DEFAULT_CACHE`).
+        timeout: Per-request timeout in seconds for a download.
+        max_bytes: Maximum bytes to accept for a download.
+        refresh: When `True`, re-download a URL even if a cached copy exists
+            (cache reuse is otherwise size-only, so a changed remote is not
+            picked up).
+
+    Returns:
+        The path to the local (possibly just-cached) file.
+
+    Raises:
+        FileNotFoundError: When a local `source` does not exist.
+    """
+    parsed = urlparse(str(source))
+    if parsed.scheme in ("http", "https"):
+        cache = Path(cache_dir) if cache_dir is not None else _DEFAULT_CACHE
+        cache.mkdir(parents=True, exist_ok=True)
+        target = _cache_path(cache, str(source))
+        if refresh or not (target.exists() and target.stat().st_size > 0):
+            _download(str(source), target, timeout, max_bytes)
+        return target
+    path = Path(source)
+    if not path.exists():
+        raise FileNotFoundError(f"static image not found: {path}")
+    return path
+
+
+def static_image(
+    source: Any,
+    *,
+    like: Any = None,
+    cache_dir: Any = None,
+    timeout: float = 60.0,
+    max_bytes: int = _DEFAULT_MAX_BYTES,
+    refresh: bool = False,
+) -> Any:
+    """Load a georeferenced image, caching a remote URL and warping to a grid.
+
+    Loads a georeferenced background image. `source` may be a local path
+    (relative or absolute) or an http/https URL; a URL is downloaded once and
+    cached under `cache_dir`. When `like` is given, the loaded image is warped
+    and cropped onto that dataset's grid (CRS + rows/columns + cell size) via
+    pyramids' `align`.
+
+    Args:
+        source: A local filesystem path or an http/https URL to a georeferenced
+            raster (e.g. the Black Marble GeoTIFF).
+        like: A pyramids `Dataset` whose grid the image is warped/cropped to. When
+            `None`, the image is returned at its native grid.
+        cache_dir: Directory used to cache a downloaded URL. Defaults to
+            `~/.cache/pyramids-eo`. Ignored for a local `source`.
+        timeout: Per-request download timeout in seconds (default 60).
+        max_bytes: Cap on a URL download in bytes (default ~1 GB) — guards against
+            an oversized/hostile URL filling the cache.
+        refresh: When `True`, re-download a URL even if it is already cached
+            (the cache is otherwise reused whenever the file is present).
+
+    Returns:
+        A pyramids `Dataset` — aligned to `like`'s grid when `like` is given,
+        otherwise the image at its native grid.
+
+    Raises:
+        FileNotFoundError: When a local `source` does not exist.
+        EOError: When a URL download exceeds `max_bytes`.
+    """
+    path = _resolve_source(source, cache_dir, timeout, max_bytes, refresh)
+
+    from pyramids.dataset import Dataset
+
+    dataset = Dataset.read_file(str(path))
+    if like is not None:
+        dataset = dataset.align(like)
+    return dataset

pyramids_eo/composites/blend.py

@@ -0,0 +1,134 @@
+"""Solar-zenith-angle day/night blending.
+
+`day_night_blend` cross-fades a *day* image and a *night* image by the
+per-pixel solar zenith angle (SZA), producing the smooth twilight transition of
+the `true_color_with_night_ir` look. The blend keys off the Sun's geometric
+position (from `solar_zenith_angle`), not on how dark a pixel looks — which is
+why an eclipse shadow is rendered as day, not night.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+from pyramids_eo.composites._common import _as_array, _wrap_like
+
+_MODES = ("day_night", "day_only", "night_only")
+
+
+def day_weight(sza: Any, lim_low: float = 78.0, lim_high: float = 88.0) -> np.ndarray:
+    """Per-pixel day weight in `[0, 1]` from the solar zenith angle.
+
+    The weight is 1 where the Sun is high (`sza <= lim_low`, full day), 0 where
+    it is low (`sza >= lim_high`, full night), and a smooth cos-space ramp
+    through the twilight band between them — the DayNightCompositor curve.
+
+    Args:
+        sza: Solar zenith angle in degrees (scalar or array), e.g. from
+            `solar_zenith_angle`.
+        lim_low: SZA (degrees) at/below which it is fully day. Default 78.
+        lim_high: SZA (degrees) at/above which it is fully night. Default 88.
+
+    Returns:
+        The day weight, same shape as `sza`, clipped to `[0, 1]`.
+
+    Raises:
+        ValueError: When `lim_low >= lim_high`.
+
+    Examples:
+        - Overhead Sun is full day, horizon is full night, midway is ~0.5:
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import day_weight
+            >>> day_weight(np.array([0.0, 83.0, 90.0])).round(2).tolist()
+            [1.0, 0.5, 0.0]
+
+            ```
+    """
+    if lim_low >= lim_high:
+        raise ValueError(
+            f"lim_low ({lim_low}) must be < lim_high ({lim_high}) in SZA degrees"
+        )
+    low = np.cos(np.deg2rad(lim_low))
+    high = np.cos(np.deg2rad(lim_high))
+    coszen = np.cos(np.deg2rad(np.asarray(sza, dtype=float)))
+    weight = (coszen - min(low, high)) / abs(low - high)
+    return np.asarray(np.clip(weight, 0.0, 1.0), dtype=float)
+
+
+def day_night_blend(
+    day: Any,
+    night: Any,
+    sza: Any,
+    *,
+    lim_low: float = 78.0,
+    lim_high: float = 88.0,
+    mode: str = "day_night",
+) -> Any:
+    """Cross-fade a day and a night image by solar zenith angle.
+
+    Computes a per-pixel day weight from `sza` (see `day_weight`) and mixes:
+    `day * weight + night * (1 - weight)`.
+    `day` / `night` may be `(H, W)` or `(band, H, W)` arrays, or pyramids
+    `Dataset` objects; the weight broadcasts across bands.
+
+    Args:
+        day: The day image — array-like or a pyramids `Dataset`.
+        night: The night image — same shape/type family as `day`. Ignored when
+            `mode="day_only"`.
+        sza: Per-pixel solar zenith angle in degrees (`(H, W)`), from
+            `solar_zenith_angle`.
+        lim_low: SZA at/below which it is fully day (default 78).
+        lim_high: SZA at/above which it is fully night (default 88).
+        mode: `"day_night"` (blend, default), `"day_only"` (`day * weight`), or
+            `"night_only"` (`night * (1 - weight)`).
+
+    Returns:
+        The blended image. A pyramids `Dataset` (carrying `day`'s / `night`'s
+        geotransform + CRS) when either input is a `Dataset`, otherwise an
+        ndarray.
+
+    Raises:
+        ValueError: When `mode` is unknown or `lim_low >= lim_high`.
+
+    Examples:
+        - A day (1s) / night (0s) pair collapses to the day weight per pixel:
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import day_night_blend
+            >>> day = np.ones((2, 2))
+            >>> night = np.zeros((2, 2))
+            >>> sza = np.array([[0.0, 83.0], [88.0, 180.0]])
+            >>> day_night_blend(day, night, sza).round(2).tolist()
+            [[1.0, 0.5], [0.0, 0.0]]
+
+            ```
+    """
+    if mode not in _MODES:
+        raise ValueError(f"mode must be one of {_MODES}; got {mode!r}")
+
+    weight = day_weight(_as_array(sza), lim_low=lim_low, lim_high=lim_high)
+    day_arr = _as_array(day)
+    if weight.ndim == 2 and day_arr.ndim == 3:
+        weight = weight[np.newaxis, ...]
+
+    # np.where zeros each image's contribution where its weight is 0, so a NaN
+    # in a fully-weighted-out region (e.g. sun-angle-normalised day reflectance,
+    # which is NaN across the night side) does not leak through NaN * 0 = NaN.
+    if mode == "day_only":
+        out = np.where(weight > 0, day_arr * weight, 0.0)
+    elif mode == "night_only":
+        night_arr = _as_array(night)
+        out = np.where(weight < 1, night_arr * (1.0 - weight), 0.0)
+    else:
+        night_arr = _as_array(night)
+        day_term = np.where(weight > 0, day_arr * weight, 0.0)
+        night_term = np.where(weight < 1, night_arr * (1.0 - weight), 0.0)
+        out = day_term + night_term
+    # A NaN weight means the SZA (day/night geometry) is undefined, so keep the
+    # pixel masked as NaN rather than collapsing it to 0 — matching day_weight's
+    # NaN propagation (the weight-zeroing above only handles image-side NaN).
+    out = np.where(np.isnan(weight), np.nan, out)
+    return _wrap_like(out, day, night)

pyramids_eo/composites/geometry.py

@@ -0,0 +1,175 @@
+"""Solar geometry for day/night compositing.
+
+`solar_zenith_angle` gives the per-pixel solar zenith angle (SZA) from a UTC
+time and a lon/lat grid, computed directly with the NOAA solar-position
+algorithm over NumPy. The SZA drives the day/night cross-fade
+(`day_night_blend`),
+which keys off the Sun's *geometric* position rather than how dark a pixel looks
+(the property that renders an eclipse shadow as day, not night).
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+from typing import Any
+
+import numpy as np
+
+
+def _to_utc(time: _dt.datetime) -> _dt.datetime:
+    """Return `time` as a timezone-aware UTC datetime.
+
+    A naive datetime is assumed to already be UTC; an aware one is converted.
+
+    Args:
+        time: The observation time.
+
+    Returns:
+        The same instant expressed in UTC.
+
+    Raises:
+        TypeError: When `time` is not a `datetime.datetime`.
+    """
+    if not isinstance(time, _dt.datetime):
+        raise TypeError("time must be a datetime.datetime")
+    if time.tzinfo is None:
+        return time.replace(tzinfo=_dt.UTC)
+    return time.astimezone(_dt.UTC)
+
+
+def solar_zenith_angle(
+    time: _dt.datetime,
+    *,
+    lat: Any = None,
+    lon: Any = None,
+    grid: Any = None,
+) -> np.ndarray:
+    """Per-pixel solar zenith angle (degrees) for a UTC time and a lon/lat grid.
+
+    Computed directly with the NOAA solar-position algorithm. Provide the
+    geographic coordinates either as `lat`
+    and `lon` arrays/scalars, or as a `grid` (a pyramids `Dataset` in EPSG:4326,
+    whose `lat` / `lon` cell-centre axes are meshed to 2-D).
+
+    The returned angle is the zenith angle in **degrees** (0 = Sun overhead,
+    90 = on the horizon / terminator, 180 = antisolar). `day_night_blend` takes
+    this and applies `cos(deg2rad(...))` internally.
+
+    Args:
+        time: Observation time. A naive datetime is treated as UTC; an aware one
+            is converted to UTC.
+        lat: Latitude(s) in degrees north — scalar or array. Mutually exclusive
+            with `grid`; must be paired with `lon`.
+        lon: Longitude(s) in degrees east — scalar or array, broadcast against
+            `lat`. Mutually exclusive with `grid`; must be paired with `lat`.
+        grid: A pyramids `Dataset` (EPSG:4326) supplying `lat` / `lon` cell-centre
+            axes. Mutually exclusive with `lat` / `lon`.
+
+    Returns:
+        The solar zenith angle in degrees. Shape follows the broadcast of `lat`
+        and `lon`, or `(grid.rows, grid.columns)` for a `grid`.
+
+    Raises:
+        ValueError: When neither `grid` nor both `lat` and `lon` are given, when
+            both are given, or when `grid` is not geographic (EPSG:4326).
+
+    Examples:
+        - The Sun is nearly overhead at (0degN, 0degE) at equinox noon:
+            ```python
+            >>> import datetime as dt
+            >>> from pyramids_eo.composites import solar_zenith_angle
+            >>> t = dt.datetime(2024, 3, 20, 12, 0, tzinfo=dt.timezone.utc)
+            >>> bool(solar_zenith_angle(t, lat=0.0, lon=0.0) < 5)
+            True
+
+            ```
+        - The antisolar point is in deep night (SZA near 180deg):
+            ```python
+            >>> bool(solar_zenith_angle(t, lat=0.0, lon=180.0) > 175)
+            True
+
+            ```
+    """
+    if grid is not None:
+        if lat is not None or lon is not None:
+            raise ValueError("pass either `grid` or (`lat`, `lon`), not both")
+        epsg = getattr(grid, "epsg", None)
+        if epsg is None or int(epsg) != 4326:
+            raise ValueError(
+                f"grid must be geographic (EPSG:4326); got EPSG:{epsg}. A grid "
+                "with no EPSG (e.g. geostationary) is not lon/lat — reproject it "
+                "with to_crs(4326) first."
+            )
+        lon2d, lat2d = np.meshgrid(
+            np.asarray(grid.lon, dtype=float), np.asarray(grid.lat, dtype=float)
+        )
+    else:
+        if lat is None or lon is None:
+            raise ValueError("provide `grid`, or both `lat` and `lon`")
+        lat2d, lon2d = np.broadcast_arrays(
+            np.asarray(lat, dtype=float), np.asarray(lon, dtype=float)
+        )
+
+    utc = _to_utc(time)
+    day_of_year = utc.timetuple().tm_yday
+    hour = utc.hour + utc.minute / 60 + utc.second / 3600 + utc.microsecond / 3.6e9
+
+    # NOAA fractional-year angle (radians) and its harmonics.
+    gamma = 2.0 * np.pi / 365.0 * (day_of_year - 1 + (hour - 12) / 24)
+    # Equation of time (minutes) and solar declination (radians).
+    eqtime = 229.18 * (
+        0.000075
+        + 0.001868 * np.cos(gamma)
+        - 0.032077 * np.sin(gamma)
+        - 0.014615 * np.cos(2 * gamma)
+        - 0.040849 * np.sin(2 * gamma)
+    )
+    decl = (
+        0.006918
+        - 0.399912 * np.cos(gamma)
+        + 0.070257 * np.sin(gamma)
+        - 0.006758 * np.cos(2 * gamma)
+        + 0.000907 * np.sin(2 * gamma)
+        - 0.002697 * np.cos(3 * gamma)
+        + 0.00148 * np.sin(3 * gamma)
+    )
+
+    # True solar time (minutes) per pixel: UTC clock time + equation of time +
+    # 4 min per degree of east longitude (timezone offset is 0 for UTC).
+    true_solar_time = hour * 60 + eqtime + 4.0 * lon2d
+    hour_angle = np.deg2rad(true_solar_time / 4.0 - 180.0)
+
+    lat_rad = np.deg2rad(lat2d)
+    cos_zenith = np.sin(lat_rad) * np.sin(decl) + np.cos(lat_rad) * np.cos(
+        decl
+    ) * np.cos(hour_angle)
+    return np.asarray(
+        np.rad2deg(np.arccos(np.clip(cos_zenith, -1.0, 1.0))), dtype=float
+    )
+
+
+def cos_solar_zenith_angle(
+    time: _dt.datetime,
+    *,
+    lat: Any = None,
+    lon: Any = None,
+    grid: Any = None,
+) -> np.ndarray:
+    """Per-pixel cosine of the solar zenith angle.
+
+    A thin wrapper over `solar_zenith_angle` returning `cos(SZA)` directly — the
+    form the readers' and `radiance_to_reflectance`'s `cos_sza` arguments expect
+    (note `solar_zenith_angle` itself returns the angle in *degrees*). Same
+    arguments as `solar_zenith_angle`.
+
+    Args:
+        time: Observation time (a naive datetime is treated as UTC).
+        lat: Latitude(s) in degrees north, paired with `lon`.
+        lon: Longitude(s) in degrees east, paired with `lat`.
+        grid: A pyramids `Dataset` grid (EPSG:4326), mutually exclusive with
+            `lat` / `lon`.
+
+    Returns:
+        The cosine of the solar zenith angle, same shape as the coordinates.
+    """
+    return np.cos(np.deg2rad(solar_zenith_angle(time, lat=lat, lon=lon, grid=grid)))