pyramids-eo 0.3.0__tar.gz → 0.5.0__tar.gz

{pyramids_eo-0.3.0/src/pyramids_eo.egg-info → pyramids_eo-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyramids-eo
-Version: 0.3.0
+Version: 0.5.0
 Summary: Remote-sensing / Earth-observation tier for the pyramids GIS stack
 Author-email: Mostafa Farrag <moah.farag@gmail.com>
 License: GNU General Public License v3
@@ -24,11 +24,11 @@ Classifier: Intended Audience :: Developers
 Requires-Python: <4,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pyramids-gis>=0.53.0
+Requires-Dist: pyramids-gis>=0.56.0
 Requires-Dist: numpy>=2.0.0
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: viz
-Requires-Dist: pyramids-gis[viz]>=0.53.0; extra == "viz"
+Requires-Dist: pyramids-gis[viz]>=0.56.0; extra == "viz"
 Dynamic: license-file
 
 # pyramids-eo

{pyramids_eo-0.3.0 → pyramids_eo-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyramids-eo"
-version = "0.3.0"
+version = "0.5.0"
 description = "Remote-sensing / Earth-observation tier for the pyramids GIS stack"
 readme = {file = "README.md", content-type = "text/markdown"}
 authors = [{ name = "Mostafa Farrag", email = "moah.farag@gmail.com" }]
@@ -25,13 +25,13 @@ classifiers = [
 requires-python = ">= 3.11, <4"
 
 dependencies = [
-    "pyramids-gis >=0.53.0",
+    "pyramids-gis >=0.56.0",
     "numpy >=2.0.0",
     "pyyaml >=6.0",
 ]
 
 [project.optional-dependencies]
-viz = ["pyramids-gis[viz]>=0.53.0"]
+viz = ["pyramids-gis[viz]>=0.56.0"]
 
 [dependency-groups]
 dev = [

{pyramids_eo-0.3.0 → pyramids_eo-0.5.0}/src/pyramids_eo/__init__.py

@@ -11,14 +11,35 @@ resample a swath — and how to reach signed EO cloud assets. It is scoped by
 
 from __future__ import annotations
 
+# isort: off
+# MUST be the first runtime import in the whole package. pyramids bundles GDAL
+# (osgeo) and activates it on import; nothing in pyramids-eo — nor any osgeo
+# import anywhere downstream — works until `import pyramids` has run. GDAL is
+# therefore NEVER a dependency of pyramids-eo; it arrives through pyramids. Do
+# not reorder this below any other import, and do not add gdal/osgeo to
+# pyproject.toml.
+import pyramids as _pyramids_bootstrap  # noqa: F401  (activates the bundled osgeo)
+
+# isort: on
+
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _get_version
 
 from pyramids_eo.earthengine import (
     EarthEngineCredentials,
+    ReadCost,
+    Window,
     collection_from_earthengine,
+    estimate_earthengine_cost,
     from_earthengine,
 )
+from pyramids_eo.sentinel import (
+    SclClass,
+    collection_from_sentinel2,
+    from_sentinel2,
+    open_product,
+    scl_mask,
+)
 
 try:
     __version__ = _get_version("pyramids-eo")
@@ -27,7 +48,15 @@ except PackageNotFoundError:  # pragma: no cover
 
 __all__ = [
     "EarthEngineCredentials",
+    "ReadCost",
+    "SclClass",
+    "Window",
     "__version__",
     "collection_from_earthengine",
+    "collection_from_sentinel2",
+    "estimate_earthengine_cost",
     "from_earthengine",
+    "from_sentinel2",
+    "open_product",
+    "scl_mask",
 ]

{pyramids_eo-0.3.0 → pyramids_eo-0.5.0}/src/pyramids_eo/composites/_common.py

@@ -53,3 +53,23 @@ def _wrap_like(out: np.ndarray, *candidates: Any) -> Any:
     return Dataset.create_from_array(
         out, geo=template.geotransform, epsg=template.epsg, no_data_value=np.nan
     )
+
+
+def _coverage(value: Any) -> np.ndarray:
+    """Per-pixel validity mask — `True` where every band of `value` is finite.
+
+    Coverage is derived from data validity (finite values), never from pixel
+    brightness, so a dark-but-valid pixel (e.g. night ocean) stays covered while
+    an off-disk / terminator pixel (NaN from calibration) is not.
+
+    Args:
+        value: An array-like or pyramids `Dataset`. A `(band, H, W)` image
+            reduces over its bands; an `(H, W)` image is taken as-is.
+
+    Returns:
+        A boolean `(H, W)` mask, `True` where the pixel is finite in all bands.
+    """
+    arr = _as_array(value)
+    if arr.ndim >= 3:
+        return np.all(np.isfinite(arr), axis=tuple(range(arr.ndim - 2)))
+    return np.isfinite(arr)

{pyramids_eo-0.3.0 → pyramids_eo-0.5.0}/src/pyramids_eo/composites/blend.py

@@ -13,7 +13,7 @@ from typing import Any
 
 import numpy as np
 
-from pyramids_eo.composites._common import _as_array, _wrap_like
+from pyramids_eo.composites._common import _as_array, _coverage, _wrap_like
 
 _MODES = ("day_night", "day_only", "night_only")
 
@@ -66,6 +66,7 @@ def day_night_blend(
     lim_low: float = 78.0,
     lim_high: float = 88.0,
     mode: str = "day_night",
+    keep_alpha: bool = False,
 ) -> Any:
     """Cross-fade a day and a night image by solar zenith angle.
 
@@ -84,11 +85,19 @@ def day_night_blend(
         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)`).
+        keep_alpha: When `True`, append a coverage / alpha band — `1.0` where the
+            contributing input(s) are finite, the geometry is defined, and the
+            blended pixel itself is finite; `0.0` otherwise (see
+            :func:`pyramids_eo.composites._common._coverage`). The band comes from
+            data validity, not brightness, so a dark-but-valid pixel stays covered
+            while a NaN-producing twilight pixel does not. Default `False` leaves
+            the output unchanged.
 
     Returns:
         The blended image. A pyramids `Dataset` (carrying `day`'s / `night`'s
         geotransform + CRS) when either input is a `Dataset`, otherwise an
-        ndarray.
+        ndarray. With `keep_alpha=True` the output carries one extra (alpha)
+        band.
 
     Raises:
         ValueError: When `mode` is unknown or `lim_low >= lim_high`.
@@ -104,15 +113,27 @@ def day_night_blend(
             >>> day_night_blend(day, night, sza).round(2).tolist()
             [[1.0, 0.5], [0.0, 0.0]]
 
+            ```
+        - `keep_alpha` appends a coverage band, giving a 4-band RGBA result:
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import day_night_blend
+            >>> day = np.ones((3, 1, 2))
+            >>> night = np.zeros((3, 1, 2))
+            >>> sza = np.array([[0.0, 0.0]])
+            >>> day_night_blend(day, night, sza, keep_alpha=True).shape
+            (4, 1, 2)
+
             ```
     """
     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)
+    weight2d = 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, ...]
+    weight = weight2d
+    if weight2d.ndim == 2 and day_arr.ndim == 3:
+        weight = weight2d[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,
@@ -131,4 +152,46 @@ def day_night_blend(
     # 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)
+
+    if keep_alpha:
+        out = _append_alpha(out, day, night, weight2d, mode)
+
     return _wrap_like(out, day, night)
+
+
+def _append_alpha(
+    out: np.ndarray, day: Any, night: Any, weight2d: np.ndarray, mode: str
+) -> np.ndarray:
+    """Append a coverage / alpha band to a blended image.
+
+    Coverage is the validity of the mode's contributing input(s) — `day` for
+    `"day_only"`, `night` for `"night_only"`, their union for `"day_night"` —
+    masked out where the SZA geometry (weight) is undefined.
+
+    Args:
+        out: The blended image, `(H, W)` or `(band, H, W)`.
+        day: The day input (array-like or `Dataset`).
+        night: The night input (array-like or `Dataset`).
+        weight2d: The 2-D day weight, used to mask undefined-geometry pixels.
+        mode: The blend mode driving which inputs contribute.
+
+    Returns:
+        `out` with one extra trailing (alpha) band: `1.0` covered, `0.0` not.
+    """
+    if mode == "day_only":
+        covered = _coverage(day)
+    elif mode == "night_only":
+        covered = _coverage(night)
+    else:
+        covered = _coverage(day) | _coverage(night)
+    # Intersect with the finite blended output so alpha is never 1 over a NaN
+    # pixel — in the twilight band both inputs contribute, so a single NaN input
+    # yields NaN RGB there even though the input-union coverage is 1.
+    covered = covered & ~np.isnan(np.asarray(weight2d, dtype=float)) & _coverage(out)
+    alpha = np.asarray(covered, dtype=float)
+
+    if out.ndim >= 3:
+        alpha = np.broadcast_to(alpha, out.shape[1:])
+        return np.concatenate([out, alpha[np.newaxis, ...]], axis=0)
+    alpha = np.broadcast_to(alpha, out.shape)
+    return np.stack([out, alpha], axis=0)

pyramids_eo-0.5.0/src/pyramids_eo/composites/true_color.py

@@ -0,0 +1,248 @@
+"""True-colour RGB from calibrated reflectance bands.
+
+SEVIRI carries no native green band, so for it `true_color` synthesises one from
+the red, blue, and near-IR ("veggie") reflectances using the CIMSS weighted
+recipe (`green_mode="synthetic"`, the default), then stacks red / green / blue
+into an RGB image.
+
+FCI FDHSI *does* carry a native green band (`vis_05`, ~0.51 um). For FCI, pass
+that band as `green=` and select `green_mode="native"` to use it directly, or
+`green_mode="ndvi_hybrid"` to blend it with the NIR by an NDVI fraction (more NIR
+over barren surfaces, less over vegetation) — the reference true-colour look.
+
+This is the **no-Rayleigh** variant (per the pyramids-eo compositing decision):
+by default it does the band combination only. Atmospheric / Rayleigh correction
+is intentionally out of scope of the base install to keep the dependency
+footprint small; the result is slightly flatter over ocean / haze than a
+Rayleigh-corrected image. A correction can be opted in per call via the
+`rayleigh=` callable, which is applied to each solar band before green synthesis.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+from pyramids_eo.composites._common import _as_array, _wrap_like
+
+#: Default CIMSS synthetic-green weights (red, near-IR/veggie, blue).
+_DEFAULT_GREEN_WEIGHTS = (0.45, 0.10, 0.45)
+
+#: Green-synthesis modes accepted by :func:`true_color`.
+_GREEN_MODES = ("synthetic", "native", "ndvi_hybrid")
+
+
+def _ndvi_hybrid_green(
+    green: np.ndarray,
+    red: np.ndarray,
+    nir: np.ndarray,
+    *,
+    strength: float = 3.0,
+    limits: tuple[float, float] = (0.15, 0.05),
+    ndvi_min: float = 0.0,
+    ndvi_max: float = 1.0,
+) -> np.ndarray:
+    """Blend a native green band with the NIR by a per-pixel NDVI fraction.
+
+    Computes `NDVI = (nir - red) / (nir + red)`, optionally sharpens it with a
+    non-linear `strength`, maps it linearly from `[ndvi_min, ndvi_max]` onto
+    `[limits[0], limits[1]]` to get a NIR fraction, then returns
+    `(1 - fraction) * green + fraction * nir`. With the default `limits`, barren
+    pixels (low NDVI) take more NIR (0.15) and vegetated pixels take less (0.05),
+    so the native green dominates (0.85-0.95).
+
+    Args:
+        green: The native green reflectance (e.g. FCI `vis_05`).
+        red: The red reflectance (NDVI red term).
+        nir: The near-IR reflectance (NDVI NIR term and blend source).
+        strength: Non-linear sharpening exponent applied to the NDVI; `1.0`
+            leaves it linear. Must be `> 0`.
+        limits: The `(low_ndvi, high_ndvi)` NIR fractions the NDVI is mapped onto.
+            Fractions outside `[0, 1]` extrapolate the green beyond `[green, nir]`.
+        ndvi_min: Lower NDVI clip / mapping bound.
+        ndvi_max: Upper NDVI clip / mapping bound.
+
+    Returns:
+        The blended green channel, same shape as the inputs.
+
+    Raises:
+        ValueError: When `strength <= 0` or `limits` is not a 2-tuple.
+    """
+    if strength <= 0:
+        raise ValueError(f"strength must be > 0, got {strength}")
+    if len(limits) != 2:
+        raise ValueError(f"limits must be a 2-tuple (low, high); got {limits!r}")
+    red = np.asarray(red, dtype=float)
+    nir = np.asarray(nir, dtype=float)
+    green = np.asarray(green, dtype=float)
+    denom = nir + red
+    ndvi = np.divide(nir - red, denom, out=np.zeros_like(denom), where=denom != 0)
+    ndvi = np.clip(np.nan_to_num(ndvi), ndvi_min, ndvi_max)
+    if not math.isclose(strength, 1.0):
+        powered = ndvi**strength
+        ndvi = powered / (powered + (1.0 - ndvi) ** strength)
+    span = ndvi_max - ndvi_min
+    fraction = (ndvi - ndvi_min) / span * (limits[1] - limits[0]) + limits[0]
+    return np.asarray((1.0 - fraction) * green + fraction * nir, dtype=float)
+
+
+def _build_green_channel(
+    green_mode: str,
+    r: np.ndarray,
+    b: np.ndarray,
+    n: np.ndarray,
+    g_native: np.ndarray | None,
+    green_weights: tuple[float, float, float],
+    ndvi_strength: float,
+    ndvi_limits: tuple[float, float],
+) -> np.ndarray:
+    """Build the green channel for the requested `green_mode`.
+
+    Args:
+        green_mode: `"synthetic"`, `"native"`, or `"ndvi_hybrid"`.
+        r: Red reflectance (already rayleigh-corrected if requested).
+        b: Blue reflectance.
+        n: Near-IR reflectance.
+        g_native: The native green band, or `None`.
+        green_weights: The `(red, nir, blue)` weights for the synthetic green.
+        ndvi_strength: NDVI sharpening for `"ndvi_hybrid"`.
+        ndvi_limits: The `(low, high)` NIR fractions for `"ndvi_hybrid"`.
+
+    Returns:
+        The green-channel array.
+
+    Raises:
+        ValueError: When `green_weights` is not a 3-tuple, or a native /
+            ndvi_hybrid mode is requested without a `green=` band.
+    """
+    if green_mode == "synthetic":
+        if len(green_weights) != 3:
+            raise ValueError(
+                f"green_weights must be a 3-tuple (red, nir, blue); got {green_weights!r}"
+            )
+        wr, wn, wb = green_weights
+        return wr * r + wn * n + wb * b
+    if g_native is None:
+        raise ValueError(f"green_mode={green_mode!r} requires a `green=` band")
+    if green_mode == "native":
+        return g_native
+    return _ndvi_hybrid_green(
+        g_native, r, n, strength=ndvi_strength, limits=ndvi_limits
+    )
+
+
+def true_color(
+    red: Any,
+    blue: Any,
+    nir: Any,
+    *,
+    green: Any = None,
+    green_mode: str = "synthetic",
+    green_weights: tuple[float, float, float] = _DEFAULT_GREEN_WEIGHTS,
+    ndvi_strength: float = 3.0,
+    ndvi_limits: tuple[float, float] = (0.15, 0.05),
+    rayleigh: Callable[[np.ndarray], Any] | None = None,
+    gamma: float | None = None,
+    clip: bool = False,
+) -> Any:
+    """Build a true-colour RGB from red, blue, and near-IR reflectances.
+
+    The green channel is built per `green_mode`:
+
+    * `"synthetic"` (default) — `green = wr*red + wn*nir + wb*blue` (the CIMSS
+      recipe), for sensors with no native green band (SEVIRI). Byte-identical to
+      the historical behaviour.
+    * `"native"` — use the `green=` band directly (FCI `vis_05`).
+    * `"ndvi_hybrid"` — blend the `green=` band with the NIR by an NDVI fraction
+      (see :func:`_ndvi_hybrid_green`).
+
+    When `rayleigh` is given it is applied to each solar band (red, blue, nir, and
+    a native `green`) before green synthesis; `None` (default) leaves the bands
+    untouched and adds no dependency.
+
+    Args:
+        red: Red-band reflectance — array-like or a pyramids `Dataset`.
+        blue: Blue-band reflectance, same grid as `red`.
+        nir: Near-IR ("veggie") reflectance — the synthetic-green source, the
+            NDVI NIR term, and the `ndvi_hybrid` blend source.
+        green: Native green reflectance (FCI `vis_05`). Required for
+            `green_mode` `"native"` / `"ndvi_hybrid"`, ignored for `"synthetic"`.
+        green_mode: How to build the green channel — `"synthetic"` (default),
+            `"native"`, or `"ndvi_hybrid"`.
+        green_weights: The `(red, nir, blue)` weights for the synthetic green
+            (default the CIMSS `(0.45, 0.10, 0.45)`).
+        ndvi_strength: Non-linear NDVI sharpening for `"ndvi_hybrid"` (default 3.0).
+        ndvi_limits: The `(low, high)` NIR fractions for `"ndvi_hybrid"`.
+        rayleigh: Optional callable applied to each solar band before green
+            synthesis (an atmospheric correction), or `None`.
+        gamma: Optional gamma to apply (`value ** (1 / gamma)`), or `None`.
+        clip: When `True`, clip the output to `[0, 1]`.
+
+    Returns:
+        The `(3, H, W)` RGB image. A pyramids `Dataset` (carrying an input
+        `Dataset`'s geotransform + CRS) when any input is a `Dataset`, otherwise
+        an ndarray.
+
+    Raises:
+        ValueError: When `green_mode` is unknown, a native/ndvi_hybrid mode is
+            requested without a `green=` band, or `green_weights` is not a
+            3-tuple.
+
+    Examples:
+        - Synthetic CIMSS green (SEVIRI-style) from red / blue / NIR reflectance:
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import true_color
+            >>> r, b, n = np.full((1, 1), 0.2), np.full((1, 1), 0.6), np.full((1, 1), 0.9)
+            >>> true_color(r, b, n)[1].round(3).tolist()
+            [[0.45]]
+
+            ```
+        - Use FCI's native green band directly (`green_mode="native"`):
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import true_color
+            >>> out = true_color(
+            ...     np.full((1, 1), 0.2),
+            ...     np.full((1, 1), 0.6),
+            ...     np.full((1, 1), 0.9),
+            ...     green=np.full((1, 1), 0.44),
+            ...     green_mode="native",
+            ... )
+            >>> out[1].tolist()
+            [[0.44]]
+
+            ```
+    """
+    if green_mode not in _GREEN_MODES:
+        raise ValueError(
+            f"green_mode must be one of {_GREEN_MODES}; got {green_mode!r}"
+        )
+
+    r = _as_array(red)
+    b = _as_array(blue)
+    n = _as_array(nir)
+    g_native = _as_array(green) if green is not None else None
+
+    if rayleigh is not None:
+        r = np.asarray(rayleigh(r), dtype=float)
+        b = np.asarray(rayleigh(b), dtype=float)
+        n = np.asarray(rayleigh(n), dtype=float)
+        if g_native is not None:
+            g_native = np.asarray(rayleigh(g_native), dtype=float)
+
+    green_ch = _build_green_channel(
+        green_mode, r, b, n, g_native, green_weights, ndvi_strength, ndvi_limits
+    )
+
+    rgb = np.stack([r, green_ch, b], axis=0)
+
+    if gamma is not None:
+        rgb = np.where(rgb > 0, rgb, 0.0) ** (1.0 / gamma)
+    if clip:
+        rgb = np.clip(rgb, 0.0, 1.0)
+
+    return _wrap_like(rgb, red, blue, nir, green)

{pyramids_eo-0.3.0 → pyramids_eo-0.5.0}/src/pyramids_eo/composites/true_color_night.py

@@ -23,7 +23,7 @@ from typing import Any
 
 import numpy as np
 
-from pyramids_eo.composites._common import _as_array, _wrap_like
+from pyramids_eo.composites._common import _as_array, _coverage, _wrap_like
 from pyramids_eo.composites.blend import day_night_blend
 from pyramids_eo.composites.overlay import alpha_overlay
 
@@ -63,6 +63,7 @@ def true_color_with_night_ir(
     *,
     lim_low: float = 78.0,
     lim_high: float = 88.0,
+    keep_alpha: bool = False,
 ) -> Any:
     """Compose the full `true_color_with_night_ir` day/night image.
 
@@ -78,10 +79,64 @@ def true_color_with_night_ir(
         sza: Per-pixel solar zenith angle in degrees, 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).
+        keep_alpha: When `True`, append a coverage / alpha band to the `(3, H, W)`
+            result, giving `(4, H, W)`. Coverage is derived from the two
+            *satellite-derived* inputs before the global background is merged in —
+            the `day` true-colour image (valid on the day side of the disk) and
+            the `night_ir_rgba` clouds (valid on the night side) — so it marks the
+            whole sensor disk, including dark-but-valid night pixels, and is `0`
+            off-disk. Where the band is `0` the RGB is set to a finite `0` so a
+            premultiplied composite stays NaN-free. Default `False` returns the
+            3-band image unchanged.
 
     Returns:
         The composed day/night image — a pyramids `Dataset` when the inputs carry
-        one, otherwise an ndarray.
+        one, otherwise an ndarray. `(4, H, W)` when `keep_alpha=True`, else
+        `(3, H, W)`.
+
+    Examples:
+        - Compose a day/night frame from the primitives:
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import night_ir, true_color_with_night_ir
+            >>> day = np.ones((3, 1, 2))
+            >>> clouds = night_ir(np.ones((1, 2)), np.ones((1, 2)), np.ones((1, 2)))
+            >>> bg = np.zeros((3, 1, 2))
+            >>> true_color_with_night_ir(day, clouds, bg, np.zeros((1, 2))).shape
+            (3, 1, 2)
+
+            ```
+        - Keep a coverage band for edge feathering (4-band RGBA):
+            ```python
+            >>> import numpy as np
+            >>> from pyramids_eo.composites import night_ir, true_color_with_night_ir
+            >>> day = np.ones((3, 1, 2))
+            >>> clouds = night_ir(np.ones((1, 2)), np.ones((1, 2)), np.ones((1, 2)))
+            >>> bg = np.zeros((3, 1, 2))
+            >>> out = true_color_with_night_ir(
+            ...     day, clouds, bg, np.zeros((1, 2)), keep_alpha=True
+            ... )
+            >>> out.shape
+            (4, 1, 2)
+
+            ```
     """
     night = alpha_overlay(night_ir_rgba, background)
-    return day_night_blend(day, night, sza, lim_low=lim_low, lim_high=lim_high)
+    blended = day_night_blend(day, night, sza, lim_low=lim_low, lim_high=lim_high)
+    if not keep_alpha:
+        return blended
+
+    # Coverage from the satellite-derived inputs *before* the global background
+    # is merged in: the day true-colour image covers the day side of the disk,
+    # the night-IR clouds (RGB, ignoring their own alpha) cover the night side.
+    # Their union is the sensor disk. Intersect it with the finite blended pixels
+    # so alpha is never 1 over a NaN, and zero the RGB wherever it is not finite
+    # so a downstream premultiplied (RGB * alpha) composite cannot leak NaN.
+    disk = _coverage(day) | _coverage(_as_array(night_ir_rgba)[:3])
+    blended_arr = _as_array(blended)
+    rgb = blended_arr if blended_arr.ndim >= 3 else blended_arr[np.newaxis, ...]
+    finite_rgb = _coverage(rgb)
+    coverage = disk & finite_rgb
+    rgb = np.where(finite_rgb[np.newaxis, ...], rgb, 0.0)
+    rgba = np.concatenate([rgb, coverage.astype(float)[np.newaxis, ...]], axis=0)
+    return _wrap_like(rgba, day, night_ir_rgba, background)

{pyramids_eo-0.3.0 → pyramids_eo-0.5.0}/src/pyramids_eo/earthengine/__init__.py

@@ -19,12 +19,18 @@ from __future__ import annotations
 
 from pyramids_eo.earthengine.credentials import EarthEngineCredentials
 from pyramids_eo.earthengine.reader import (
+    ReadCost,
+    Window,
     collection_from_earthengine,
+    estimate_earthengine_cost,
     from_earthengine,
 )
 
 __all__ = [
     "EarthEngineCredentials",
+    "ReadCost",
+    "Window",
     "collection_from_earthengine",
+    "estimate_earthengine_cost",
     "from_earthengine",
 ]